Event handling and callbacks

The big news in Listing 5-3, shown in the preceding section, is the handling of the user's button click. Anything the user does (such as pressing a key, touching the screen, or whatever) is an event. The code that responds to the user’s press or touch is the event-handling code.

Some things that the user doesn't do are also events. For example, when you turn on a device's GPS sensor and the sensor gets its first fix, Android calls the onGpsStatusChanged event handler.

Listing 5-3 deals with the click event with three parts of its code:

• The MyListener class declaration says that this class implements OnClickListener.
• The activity's onCreate() method sets the button's click handler to a new MyListener object.
• The code for the MyListener class has an onClick() method.

Taken together, all three of these tricks make the MyListener class handle button clicks. Figure 5-2 illustrates the process. (The details are for Java, but the Kotlin details are similar.)

When the user clicks the button, Android says, “Okay, the button was clicked. So, what should I do about that?” And the answer is, “Call an onClick() method.” It's as if Android has code that looks like this:

OnClickListener object1;
if (buttonJustGotClicked()) {
object1.onClick(infoAboutTheClick);
}

Of course, behind every answer is yet another question. In this situation, the follow-up question is, “Where does Android find onClick() methods to call?” And there’s another question: “What if you don’t want Android to call certain onClick() methods that are lurking in your code?”

Well, that's why you call the setOnClickListener() method. In Listing 5-3, the call

button.setOnClickListener(new MyListener(this));

or (for Kotlin)

button.setOnClickListener(MyListener())

creates a new MyListener object. You tell Android, “Put the new object's onClick method on your list of methods to be called. Call this object’s onClick() method whenever the button is clicked.”

And in response to this request, Android asks, “Oh, yeah? How do I know that your MyListener object has an onClick() method that I can call?” And before you can answer the question, Android notices that your MyListener class implements the OnClickListener interface. So (because of the code in Listing 5-2), your MyListener object has an onClick() method.

Of course, Android doesn't really ask, “How do I know that your MyListener object has an onClick() method?” For one thing, Android doesn't say anything because Android doesn't have a mouth. And for another thing, Android's code to call onClick() declares the object containing the onClick() method to be of type OnClickListener(). So, if your MyListener method doesn't implement OnClickListener, the compiler notices a type inconsistency (and the compiler complains vigorously).

So here's the sequence of events (follow along in Figure 5-2): Your app registers a listener with Android. Then your app goes about its business. When a relevant event takes place (such as the clicking of a button), Android calls back to your app's code. Android calls the onClick() method inside whatever object you registered.

Android calls back to your app's code, so the term callback describes the mechanism that Android uses to handle events.

Starting with version 1.6 (also known as Donut or API Level 4), Android provides a way to respond to button clicks, keystrokes, and other things without all the complicated code in this chapter's listings. That is, you can handle certain events without implementing the OnClickListener interface. Even so, you can't write Kotlin or Java code without understanding events and callbacks. At many points in your Android development life, you have to write the kind of code that you find in this chapter.

For more information on handling events without implementing OnClickListener, see Book 1, Chapter 5.

An object remembers who created it

This section is Java-specific. If you're not interested in how Java works because you don’t plan to go into the library code, you can skip it. Kotlin still does the things that this section discusses, but it does them in the background (hence the shortness of the Kotlin version of the example code found in Listing 5-3).

When you’re working with Java code, the preceding section raises several questions about the interaction between your app and Android's callback. But that section misses one of the questions, which is, “In the onClick() method of Listing 5-3, how does the code know what button means?” Listing 5-3 contains two classes — MyActivity and MyListener. Without jumping through some hoops, one class doesn't know anything about another class's fields.

In Listing 5-3, the keyword this sits inside the code that defines the MyActivity class:

button.setOnClickListener(new MyListener(this));

In Java, this refers to “the object that contains the current line of code.” So, in Listing 5-3, the word this refers to an instance of MyActivity — the activity that's being displayed on the device's screen. The current MyActivity instance has a button. So far, so good.

Later in Listing 5-3, the MyListener constructor tucks a reference to the current activity into one of its fields. (See Figure 5-3.)

Looking again at Figure 5-3, MyListener refers to an activity, and that activity contains a button. When Android calls the onClick() method, the method executes an instruction that's very much like this one:

activity.button.setBackgroundColor(android.graphics.Color.GRAY);

The instruction takes the referenced activity's button and sets the button's background color to gray. To make things work properly, you have to do some casting in the onClick() method of Listing 5-3. For example, when you see the statement:

button = ((Button) findViewById(R.id.button1));

what you're telling the compiler is that the output of findViewById() needs to be turned into a Button object, so that it matches the type of button. Otherwise, the assignment could result in an error.

A less wordy way to implement an interface

If you read the preceding section and then you read this section, you'll probably want to send us a nasty email message. The preceding section describes an admittedly convoluted way to make a listener remember which activity's button to tweak. You need to know how Listing 5-3 works, but if you modify Listing 5-3 so that the activity is its own listener, things become much simpler. Listing 5-4 shows you how to do it.

LISTING 5-4: An Activity Eats Its Own Dog Food

package com.allmycode.samples;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;

public class MyActivity extends Activity
implements OnClickListener {

Button button;

@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);

button = ((Button) findViewById(R.id.button1));

button.setOnClickListener(this);
}

@Override
public void onClick(View arg0) {
button.setBackgroundColor
(android.graphics.Color.GRAY);
}
}

The combination of automation in Android Studio and the concise nature of Kotlin make things even easier. Here is the Kotlin version of the same upgrade:

package com.example.myfirstapp

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.view.View
import kotlinx.android.synthetic.main.activity_main.*

class MainActivity : AppCompatActivity() {

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

fun onClick(v: View) {
button.setBackgroundColor(android.graphics.Color.GRAY)
}
}

The earlier section starts with a question: “In the onClick() method, how does the code know what button means?” In this section, that question goes away just as your lap goes away when you stand up.

In Listing 5-4, both the button and the onClick() method are members inside the activity. So the onClick() method has free-and-easy access to the button. You don't need an Activity field as in Listing 5-3, and you don't need any fancy casting from Activity to MyActivity.

When working with Java, you have to remind Android that MyActivity contains an onClick() method, and you do that by adding implements OnClickListener to the declaration of MyActivity. You must also remind Android to notify the current MyActivity object whenever the button gets clicked. You do this reminding by writing

button.setOnClickListener(this);

which, roughly speaking, translates to “Hey, Android! When someone clicks the button, call the onClick() method that's inside the this object (a MyActivity object, which fortunately implements OnClickListener).” All this connectivity takes place in the background when working with Kotlin, but it still takes place.

The pattern in Listing 5-4 (having an Activity implement whatever interface it requires) is a very common application-programming idiom.

The need to override

Suppose you want to add functionality to an existing Java class. You like Android's Activity class, but the pre-declared Activity class displays nothing on the screen. Do you rewrite Android's Activity class? No.

Instead of rewriting an existing class, you extend the class. Even in a do-nothing Android “Hello” application, you write

public class MyActivity extends Activity

Then, in the MyActivity class's declaration, you write

@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
}

Your MyActivity class creates new functionality by extending most of Android's Activity functionality while overriding the Activity class's brain-dead onCreate() method.

When working with a Java class in Kotlin, you can override the functions just as if you were programming in Java. This is the reason that the Kotlin version of the code can also override the onCreate() method.

Java's final classes

In object-oriented programming, extending a class is the noblest thing you can do.

But some classes aren't meant to be extended. Take, for example, Java's String class. A String is a String is a String. You don't want somebody's MyString.length method to return the length of time it takes to scramble a string's characters. To prevent someone from doing something unexpected, unconventional, or unusual with a string's methods, the creators of Java made the String class final:

public final class String

Some of Android's pre-declared classes are also final, including the Telephony and MediaStore classes.

Kotlin's open classes

As previously mentioned, all classes in Kotlin are final by default. To create a class that you can override, you must declare the class as being open. In addition, you must declare all functions, fields, and other elements that you want to override as being open. Here is an example of the Kotlin open classes:

fun main(args: Array<String>) {
val primary: MySaying = MySaying()
val secondary: YourSaying = YourSaying()

primary.printSaying()
secondary.printSaying()
}

open class MySaying {
open fun printSaying() {
println("This is my saying.")
}
}

class YourSaying: MySaying() {
override fun printSaying() {
println("This is your saying.")
}
}

You still have to initialize MySaying when extending YourSaying, which is why it appears as MySaying(). To override printSaying(), you must also include the override keyword.

Kotlin extensions

Unlike with Java, you can extend classes in Kotlin by using a special kind of function, the extension function. An extension function adds something new to a class without changing anything about the existing class. For example, you might want a new way to work with a List that Kotlin doesn't currently provide. Instead of creating an entirely new List class, you simply add the required functionality. Here’s an example of working with an extension in Kotlin:

fun main(args: Array<String>) {
val doSaying: MySaying = MySaying()

doSaying.printSaying()
doSaying.printSaying("My custom saying.")
}

class MySaying {
fun printSaying() {
println("This is my saying.")
}
}

fun MySaying.printSaying(saying: String){
println(saying)
}

The extension function uses the form class_name.function_name. This extension adds a version of printSaying() to the original class that accepts a String argument. This extension method works with final classes (the default), so you can make a kind of modification to Kotlin final classes without having to write everything from scratch.

As long as the function declaration is different, you can add just about anything you want. However, you can't override existing functionality by declaring a new function with the same signature (the same name and parameter list) as an existing function. The two functions must be different.

Abstract classes

Both Kotlin and Java provide abstract classes, and they work just about the same for both languages. Although a final class hates to be extended, an abstract class insists on being extended. Android's ViewGroup is an example of an abstract class. (See Listing 5-5.)

LISTING 5-5: A Small Part of Android's ViewGroup Class

public abstract class ViewGroup {

public void bringChildToFront(View child) {
int index = indexOfChild(child);
if (index >= 0) {
removeFromArray(index);
addInArray(child, mChildrenCount);
child.mParent = this;
}
}

protected abstract void onLayout(boolean changed,
int l, int t, int r, int b);
}

Android's ViewGroup.java file is more than 3,700 lines long. So Listing 5-5 has only a tiny fraction of the file's code. But you can see from Listing 5-5 how a class becomes abstract. To no one's surprise, the word abstract precedes the word class. But the word abstract also starts the declaration of some methods belonging to the class. (Kotlin abstract classes and functions also begin with the word abstract.)

The founders of Android decided that the idea of a ViewGroup is useful. They were correct because your favorite Android layouts (LinearLayout, RelativeLayout, and so on) are subclasses of ViewGroup. They also understood that from one kind of ViewGroup to another, some functionality doesn't change. For example, Listing 5-5 defines a bringChildToFront() method, and subclasses of ViewGroup inherit this method.

But the founders also realized that some aspects of a ViewGroup make no sense unless you work with a particular kind of group. For example, a LinearLayout positions things one after another, and a RelativeLayout positions things above, below, and to the side of one another. So Listing 5-5 doesn't have a full-blown onLayout() method. The onLayout() declaration in Listing 5-5 has no method body. But Android requires each subclass of the ViewGroup class to declare its own onLayout() method. Both Kotlin and Java enforce this requirement when (as in Listing 5-5) you declare method onLayout() to be abstract.

As a developer, you can't create an object from an abstract class. If you write

ViewGroup group = new ViewGroup();

or (for Kotlin)

val group: ViewGroup = ViewGroup()

the compiler tells you that you're behaving badly. To do something useful with the ViewGroup class, you need a subclass of the ViewGroup class. The subclass has a concrete version of each abstract method in the ViewGroup class:

package com.allmycode.samples;

import android.content.Context;
import android.view.ViewGroup;

public class MyLayout extends ViewGroup {

public MyLayout(Context context) {
super(context);
}

@Override
protected void onLayout(boolean changed,
int l, int t, int r, int b);
}
}

Here's the Kotlin version of this code:

class MyLayout: ViewGroup(context) {
override fun onLayout(changed: Boolean, l: Int,
t: Int, r: Int, b: Int) {

}
}

Named inner classes

For the user, Listing 5-6 behaves the same way as Listings 5-3 and 5-4. But in Listing 5-6, the MyActivity class contains its own MyListener class.

LISTING 5-6: A Class within a Class

package com.allmycode.samples;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;

public class MyActivity extends Activity {

Button button;

@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);

button = ((Button) findViewById(R.id.button1));

button.setOnClickListener(new MyListener());
}

class MyListener implements OnClickListener {

@Override
public void onClick(View arg0) {
button.setBackgroundColor
(android.graphics.Color.GRAY);
}
}
}

Here is the Kotlin version:

package com.example.myfirstapp

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.view.View
import kotlinx.android.synthetic.main.activity_main.*

class MainActivity : AppCompatActivity() {

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

button.setOnClickListener(MyListener())
}

class MyListener : View.OnClickListener {
override fun onClick(v: View?) {
v!!.setBackgroundColor(android.graphics.Color.GRAY)
}
}
}

The MyListener class in Listing 5-6 is an inner class. An inner class is a lot like any other class. But within an inner class's code, you can refer to the enclosing class's fields. For example, the onClick() method inside MyListener uses the name button, and button is defined in the enclosing MyActivity class.

Listings 5-4 and 5-6 are very similar. In both listings, you circumvent the complexities described in the section “An object remembers who created it,” earlier in this chapter. For this chapter's example, the choice of Listing 5-4 or Listing 5-6 is largely a matter of taste.

Anonymous inner classes

Notice that the code in Listing 5-6 uses the MyListener class only once. (The only use is in a call to button.setOnClickListener.) So, do you really need a name for something that's used only once? No, you don't. You can substitute the entire definition of the inner class inside the call to button.setOnClickListener. When you do this, you have an anonymous inner class. Listing 5-7 shows you how it works.

LISTING 5-7: A Class with No Name (Inside a Class with a Name)

package com.allmycode.samples;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;

public class MyActivity extends Activity {

Button button;

@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);

button = ((Button) findViewById(R.id.button1));

button.setOnClickListener(new OnClickListener() {

@Override
public void onClick(View arg0) {
button.setBackgroundColor
(android.graphics.Color.GRAY);
}
});
}

}

Here's the Kotlin version of the same code:

package com.example.myfirstapp

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.view.View
import kotlinx.android.synthetic.main.activity_main.*

class MainActivity : AppCompatActivity() {

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

button.setOnClickListener(object: View.OnClickListener {
override fun onClick(v: View?) {
v!!.setBackgroundColor(android.graphics.Color.GRAY)
}
})
}
}

Inner classes are good for things like event handlers, such as the onClick() method in this chapter's examples. The most difficult thing about an anonymous inner class is keeping track of the parentheses, the curly braces, and the indentation. So our humble advice is to start by writing code without any inner classes, such as the code in Listing 5-3 or Listing 5-4. Later, when you become bored with ordinary classes, experiment by changing some of your ordinary classes into inner classes.