Events

When you want something to happen as a response to a user doing something on your app, you simply need to write program logic when some events are raised, for example, click of a button, letters being typed on a text field, the device being tilted either to the left or to the right and many more possible events.

If you've used another IDE before like Visual Studio, it may have frustrated you a bit when you tried to double click on a button object in design view because, nothing happened. It did not take you to the main editor and automagically created a subroutine or method where you could just start writing the program logic. AS3 doesn't have that capability (yet). But you'll never know what the future holds, so it's okay to keep hoping. Event programming requires writing a little bit of boiler plate code, but the steps can essentially summarized into the following:

1. Choose a view object you want to use
2. A view object can detect a range of events e.g. click, long click, touch, key press etc., so you need to choose which event(s) you want to respond to
3. Create a method where you will put all the statements that you want to execute when the event happens
4. Create an association between the method (no. 3) and the view object (no. 1). This association can be done either in the XML layout (declaratively) or in the MainActivity program file (programmatically). Whichever approach you choose will be a matter of preference

The following list summarizes the steps to handle events declaratively for a Button view

1. Define the view object e.g. a Button view. this can be done either in design or text mode. Listing CH-1 shows the XML definition for this view
2. A button can respond to the click event, so we will choose that for now. We can associate the button's click event to a method (that we will create later) using the onClick attribute. We can do the association in text mode, which means directly editing the XML file of the layout or by typing the name of the function in attributes inspector (in design mode). See Fig 5-1. If you choose to edit the XML file directly, add the onClick attribute to the Button element — onClick="sayHello"
3. Create the sayHello method in the main program file (MainActivity.java) as shown in Listing 5-2

Fig 5-1 a portion of the attributes inspector showing the onClick attribute

Listing CH-1 Button view definition in activity_main.xml

<Button
  android:id="@+id/button"
  android:layout_width="wrap_content"
  android:layout_height="wrap_content"
  android:layout_marginStart="27dp"
  android:layout_marginTop="141dp"
  android:onClick="sayHello" 
  android:tag="mybutton"
  android:text="Button"
  app:layout_constraintStart_toStartOf="parent"
  app:layout_constraintTop_toTopOf="parent"
  tools:layout_editor_absoluteX="27dp"
  tools:layout_editor_absoluteY="141dp"/>

Listing 5-2 sayHello method in MainActivity.java

void sayHello(View v) {
  System.out.println("Hello");
}

The following list summarizes the programmatic steps for handling the same Button view

1. Define the view object e.g. a Button view
2. Inside the main program, declare a variable to hold a Button view object Button objButton;
3. Get a programmatic reference to the Button view object defined in the layout file objButton = (Button) findViewById(R.layout.button)
4. Decide which event you want to respond to and specify the listener object for it e.g. Click objButton.setOnClickListener(new View.OnClickListener(){ });
5. Override the onClick function. You can now implement the program logic here. Do whatever you want to do in response to the user action. void onClick(View v) { // do something in here }

Declarative Event Handling

Let's work on a project so we can deep dive into the specifics of event handling. Open the Hello project from the previous chapters, or you can just create another project, that should be fine as well. Whichever you choose, open the layout file (activity_main) from the project tool window and go to design mode.

1. select the button
2. while it's selected, go to the Attributes inspector and find the onClick attribute
3. Type the name of the method (which we will create later) on the attribute field, as shown in Fig 5-2

Any changes on the attribute of the button that was done on the inspector is automatically reflected on the XML layout file.

Listing CH-2 app/src/main/res/layout/activity_main.xml

<Button
  android:id="@+id/button"
  android:layout_width="wrap_content"
  android:layout_height="wrap_content"
  android:layout_marginStart="27dp"
  android:layout_marginTop="141dp"
  android:onClick="sayHello"  (1)
  android:tag="mybutton"
  android:text="Button"
  app:layout_constraintStart_toStartOf="parent"
  app:layout_constraintTop_toTopOf="parent"
  tools:layout_editor_absoluteX="27dp"
  tools:layout_editor_absoluteY="141dp"/>

1. This was added automatically by AS3 when you wrote sayHello on the onClick attribute. The update works both ways, you could have edited this XML directly and the update would have been reflected in the attribute inspector. When you run this app, the Android Runtime will look for the function sayHello in MainActivity.java, at the moment, we don't have it yet, so we have to implement that

Filling up the entry of the onClick attribute means you want something to happen when the Button view is clicked, the attribute entry becomes the name of a method which the Android Runtime will look for when a click event happens on the Button. The implementation of this method goes in the main program file (MainActivity.java).

To implement the sayHello method, let's open the MainActivity.java in the main editor and write our function. Here's the code snippet for the sayHello method again, as shown in Listing 5-2.

void sayHello(View v) {
  System.out.println("Hello");
}

NOTE

When a method is intended to be invoked by an event, it needs to accept a View object as parameter. In our example, when the button is clicked, the Android Runtime invokes the sayHello method and it passes the object reference of whatever view was clicked — this might seem unimportant, even superfluous right now, because we only have one Button object. If we had more, then it will make more sense why accepting a View object is useful

We're ready to test the application. Launch an appropriate AVD so we can see if the application is behaving as intended. Once the AVD is up and running, run the application. You can do from the main menu bar Run → Run app or just click the Run button from the toolbar. Open the Logcat tool window so we can look at the events being logged by Android

Fig 5-3 Logcat Window

To launch the Logcat tool window, click the "Logcat" launcher, it is located somewhere in the bottom left of the AS3 application window, as shown in Fig 5-3. Go to the emulator and click the Button on our app, while you are doing that, try to watch the Logcat window.

Fig 5-4 System.out on Logcat

The output of System.out will not be on the activity, instead, it is redirected to console Logcat window.