teaching machines

SENG 440: Lecture 3 – Activities and Layouts

February 25, 2019 by . Filed under lectures, semester1-2019, seng440.

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:

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:

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:

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:

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:
🤸‍♀️