teaching machines

SENG 440: Lecture 3 – Activities and Layouts

Dear students,

Now that we’ve examined Kotlin as a standalone language, it’s time to write our first Android apps. We will write a few today: one to emit Morse code’s dots and dashes and one to show the time in two different timezones.

Before we forget, here’s your TODO list for next time:

  • Work through the Build Your First App tutorial. Run the example on a real device if you have one, but the emulator is fine too.
  • We won’t be going into exhaustive detail on ConstraintLayout during lecture. In the near future—but at your convenience—watch some tutorials on ConstraintLayout, starting with Build a Responsive UI with ConstraintLayout.
  • Read the project 1 specification. Marks on this project are based on achievements rather than as a percentage of some ideal performance. One possible achievement is to share a post on Slack describing a plan for your app, with hand-drawn or wireframe mockups of your screens. If you want to claim this achievement, the post must appear on Slack before Saturday.
  • On a quarter sheet of paper to be turned in at the beginning of the next class, write down 3-4 questions, concerns, or observations you encountered during your reading, watching, and project planning.

Let’s get started by introducing two key actors in every Android app: the Activity class and layout resources.

Activity

We define each screenful of user interaction in our app as a subclass of Android’s Activity class. A messaging app, for example, will probably have an Activity that lists each contact that we have texted. When we click on a contact’s name, we load a new Activity that shows a history of our conversation with the contact.

Since Activity represents an interactive screen, it must gracefully handle a variety of events that affect the screen. When the device rotates, the screen must be redrawn. When a different Activity takes over the screen, the displaced one may need to stop whatever it was doing—like playing a video—or save its current state. When the user taps somewhere, the Activity must figure out which widget was tapped and trigger any associated action.

Each Activity follows a lifecycle of creation, foregroundedness, backgroundedness, and destruction. As it passes through the stages of this lifecycle, particular methods in our Activity are called. We will learn about the complete lifecycle in due time, but today we will focus on just one these methods: onCreate, which is called when an app first starts.

In onCreate, we tend to do two things:

  1. Lay out the widgets of the user interface
  2. Register callbacks that respond to interactions with the widgets

The first of these is made much easier by Android’s layout resources. The second is made much easier with lambdas.

Layout

Imperative languages like Kotlin and Java and C++ are clumsy tools for specifying user interfaces, which tend to be hierarchical and decorated with attributes. Instead, we often use a declarative language like XML or HTML. Android uses XML. The root of a layout resource file tends to be a layout manager which is responsible for position its child widgets according to some scheme. For example, this LinearLayout creates a vertical stack of two buttons:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  xmlns:tools="http://schemas.android.com/tools"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:orientation="vertical"
  tools:context=".MainActivity">

  <Button
    android:id="@+id/dot"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_weight="1"
    android:text="Dot" />

  <Button
    android:id="@+id/dash"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_weight="1"
    android:text="Dash" />
</LinearLayout>

Now let’s see Activity and layout resources in the context of actual apps.

Moarse

Let’s create an app to generate dot and dash tones to send Morse code messages. We’ll call it Moarse. When you create a new project in Android Studio, you will encounter several prompts, some of which merit discussion:

  • For the preconfigured Activity to create, choose Add No Activity. I personally prefer not automatically create a new activity from the new project wizard. I want to know what’s going on in my app.
  • For the package name, use something unique first to you and then to your app. If you have a domain on the web, use it. The convention is to invert the fields so they sort better. My domain is twodee.org, so I would use org.twodee.moarse. You could also use your email address: nz.ac.uclive.userid.moarse. Until you are publishing, this is not terribly important.
  • For the development language of your app, choose Kotlin—for this course at least.
  • For minimum API level, do not feel compelled to target an older version. Supporting old versions is a pain, and we will not discuss it in this course. (That doesn’t mean it isn’t important. But creating apps must happen before we concern ourselves with maintaining them.) Instead, if you an Android device, target the version that you have installed.

Once Android Studio finishes building, we create our first Activity with File / New / Activity / Empty Activity. The conventional name for the starting Activity is MainActivity. I disable the options for backward compatibility and generation of a layout file. We end up with a short class that looks like this:

package org.twodee.moarse

import android.app.Activity
import android.os.Bundle

class MainActivity : Activity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
  }
}

There’s our onCreate method. If we run this, we get an error telling us the app has no default Activity. We are missing some information from our app’s manifest, which holds metadata about our app. Inside our the element for our Activity, we must add these child elements:

<activity android:name=".MainActivity">
  <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
  </intent-filter>
</activity>

The action specifies that this Activity acts as a starting point within our app, and the category specifies that the app should get an entry in the application launcher. For our app to be runnable, we must have both of these.

Our app now runs, but it’s blank. Let’s add a layout with File / New / XML / Layout XML File. It’s a good idea to name the layout according to the activity name, so let’s use main. For the root tag, we’ll use LinearLayout to create a vertical stack of buttons.

To populate our layout with two button, we do the following in either the design view or text view:

  • Set the orientation to vertical.
  • Add two buttons as children of the LinearLayout.
  • Set the button labels to Dot and Dash.
  • Set the button IDs to dotButton and dashButton.
  • Set the buttons’ width. We have a few options: we can specify a fixed value in display pixel (dp) units, tightly pack the button around the label with wrap_content, or expand to fill the parent with match_parent. Let’s go with match_parent.
  • Set the buttons’ height. How do you suppose we get them to fill the vertical space of the screen? If we use match_parent, they will both maximize independently and overlap. LinearLayout is in charge of the vertical arrangement of the widgets. To get it to distribute its leftover space between its children, we use layout_weight attribute. These weights are unitless. If the top button has weight 2 and the bottom has weight 1, the weights total to 3. The top button gets 2/3 of the space, and the bottom gets 1/3. To split them evenly, we give them the same weight.

That takes care of defining the layout. To associate it with the Activity we add this line to onCreate:

setContentView(R.layout.main)

The R class is a structure generated by the Android tooling that contains identifiers that bridge between our imperative code and our resources.

When we run our code, we see buttons. But they don’t do anything. Let’s register some callbacks. If you’ve worked in Javascript before, you’ve probably done something like this before:

let dotButton = document.getElementBy('dotButton');
dotButton.addEventListener('click', function(e) {
  ...
});

We do something similar in Android:

val dashButton: Button = findViewById(R.id.dashButton)
val dotButton: Button = findViewById(R.id.dotButton)

This code must go after setContentView. Otherwise the widgets won’t be found in the view hierarchy. Once we have a reference to a widget, we register a callback in this way:

dashButton.setOnClickListener {
  Toast.makeText(this, "DASH!", Toast.LENGTH_LONG).show()
}

Toasts are the println of Android development.

For this app, we want to generate some sounds. Android provides a ToneGenerator class that can produce various telephonic sounds. Let’s have it generate a supervisory dial tone, whatever that means:

val toner = ToneGenerator(AudioManager.STREAM_ALARM, ToneGenerator.MAX_VOLUME)
toner.startTone(ToneGenerator.TONE_SUP_DIAL, durationInMillis)

The Morse standard states that dashes should be three times the length of dots, so let’s flesh out our callbacks in this way:

val toner = ToneGenerator(AudioManager.STREAM_ALARM, ToneGenerator.MAX_VOLUME)

val dotTime = 200
val dashTime = 3 * dotTime

dashButton.setOnClickListener {
  toner.startTone(ToneGenerator.TONE_SUP_DIAL, dotTime)
}

dotButton.setOnClickListener {
  toner.startTone(ToneGenerator.TONE_SUP_DIAL, dashTime)
}

That should work pretty well. The user can tap out messages. It feels good to save lives with computer science.

TwoTimer

Now let’s create an app named TwoTimer for showing the time in two different timezones. We’ll follow the same project setup that we did earlier. However, let’s go with a ConstraintLayout this time. This layout is the current darling of the various layout managers. Widgets can be anchored to their parent or one another through various mathematical constraints. It supercedes several older layout managers, like RelativeLayout. Because it lives in the Android Support Library and not in Android proper, the new layout wizard won’t properly qualify the root tag name, but we can set it manually to android.support.constraint.ConstraintLayout.

Let’s communicate with the user via four TextViews. Two will show the current time, and two will show the time zone. We’ll take these steps to specify the layout:

  • Add four TextViews. Name them time1, zone1, time2, and zone2.
  • Increase the font size for the times by setting textSize to 36sp.
  • Increase the font size for the zones by setting textSize to 24sp.
  • Constrain each text view to the left and right margins of the parent.
  • Constrain the top of time1 to the parent’s top.
  • Constrain the top of zone1 to the bottom of time1.
  • Constrain the top of time2 to the bottom of zone1.
  • Constrain the top of zone2 to the bottom of time2.
  • Push the second pair of labels down a bit by adding a bias of 64 on the time2zone1 constraint.

We’re going to do things a little differently for our Activity this time. To set the content of the TextViews, we’ll write this helper method:

private fun syncTimes() {
  val formatter = SimpleDateFormat("d MMMM HH:mm")
  val today = Calendar.getInstance()

  var timeZone = TimeZone.getDefault()
  formatter.timeZone = timeZone
  zone1.text = timeZone.displayName
  time1.text = formatter.format(today.time)

  timeZone = TimeZone.getTimeZone("America/Chicago")
  formatter.timeZone = timeZone
  zone2.text = timeZone.displayName
  time2.text = formatter.format(today.time)
}

For this code to work, we need our TextViews to be instance variables. Let’s try declaring them and initializing them in onCreate:

private var time1: TextView
private var time2: TextView
private var zone1: TextView
private var zone2: TextView

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  setContentView(R.layout.activity_main)

  time1 = findViewById(R.id.time1)
  zone1 = findViewById(R.id.zone1)
  time2 = findViewById(R.id.time2)
  zone2 = findViewById(R.id.zone2)
}

This code does not compile. In Kotlin, our variables cannot be declared without also being initialized at either the declaration site or in the constructor. We don’t know how to initialize them until after setContentView, and we don’t really have a constructor.

Maybe we should just set them to null? That’s a very Java-ish idea, but Kotlin discourages the use of null. We’d have to use the nullable type TextView? instead of TextView, and we’d have to use various null-safe operators everytime we invoked anything on our TextViews. A better solution is to use Kotlin’s special lateinit modifier:

private lateinit var time1: TextView
private lateinit var time2: TextView
private lateinit var zone1: TextView
private lateinit var zone2: TextView

As the name implies, we can now initialize these variables later. If we try to read from them before initialization has happened, we get an exception.

Now we just throw in a syncTimes call at the end of onCreate:

override fun onCreate(savedInstanceState: Bundle?) {
  ...
  syncTimes()
}

This works okay. But the times only get set once, when the app first runs. It should probably get updated more frequently. We could ask the user to force-quit the app and open it again, but we’ll certainly get some bad reviews. Instead, let’s schedule some updates on the event loop that drives our app.

Internally, each app is a sandboxed in a separate Linux process, and each process has a special thread for handling events. This is called the main thread or the UI thread—because many events are driven by the user interface. Internally, this thread follows this sort of event loop:

queue = []
forever
  task = q.dequeue 
  dispatch task

This algorithm is provided by the Looper class, but this is all managed behind the scenes. To get tasks into the queue, we use the Handler class, which talks to Looper for us. We can feed it Runnables to execute immediately or at some future time. Let’s add a Handler and a Runnable that syncs the times and schedules itself to run again:

private lateinit var handler: Handler
private lateinit var updateTask: Runnable

override fun onCreate(savedInstanceState: Bundle?) {
  ...

  handler = Handler()

  updateTask = Runnable {
    syncTimes()
    handler.postDelayed(updateTask, 1000 * 10)
  }

  handler.post(updateTask)
}

The clock will now update every 10 seconds. It’d be smarter to delay our updates by however many seconds are left in the minute, but I don’t really want to get caught up in such details during our lecture examples.

That’s enough for today. See you next time!

Sincerely,

P.S. It’s time for a haiku!

We have come so far
From bits to text to graphics
:woman-cartwheeling:
🤸‍♀️

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *