The AndroidBasicsStarter Activity

The Android API provides us with a special class called ListActivity, which derives from the Activity class that we used in the Hello World project. The ListActivity class is a special type of activity whose single purpose is to display a list of things (for example, strings). We use it to display the names of our test activities. When we touch one of the list items, we’ll start the corresponding activity programmatically. Listing 4-1 shows the code for our AndroidBasicsStarter main activity.

Listing 4-1.  AndroidBasicsStarter.java, Our Main Activity Responsible for Listing and Starting All Our Tests

package com.badlogic.androidgames;

import android.app.ListActivity;
import android.content.Intent;
import android.os.Bundle;
import android.view.View;
import android.widget.ArrayAdapter;
import android.widget.ListView;

public class AndroidBasicsStarter extends ListActivity {
    String tests[] = { "LifeCycleTest", "SingleTouchTest", "MultiTouchTest",
            "KeyTest", "AccelerometerTest", "AssetsTest",
            "ExternalStorageTest", "SoundPoolTest", "MediaPlayerTest",
            "FullScreenTest", "RenderViewTest", "ShapeTest", "BitmapTest",
            "FontTest", "SurfaceViewTest" };

    public void onCreate(Bundle savedInstanceState) {
        super .onCreate(savedInstanceState);
        setListAdapter(new ArrayAdapter<String>(this ,
                android.R.layout.simple_list_item_1, tests));
    }

    @Override
    protected void onListItemClick(ListView list, View view, int position,
            long id) {
        super .onListItemClick(list, view, position, id);
        String testName = tests[position];
        try {
            Class clazz = Class
                    .forName("com.badlogic.androidgames." + testName);
            Intent intent = new Intent(this , clazz);
            startActivity(intent);
        }catch (ClassNotFoundException e) {
            e.printStackTrace();
        }
    }
}

The package name we chose is com.badlogic.androidgames. The imports should also be pretty self-explanatory; these are simply all the classes we are going to use in our code. Our AndroidBasicsStarter class derives from the ListActivity class—still nothing special. The field tests is a string array that holds the names of all of the test activities that our starter application should display. Note that the names in that array are the exact Java class names of the activity classes we are going to implement later on.

The next piece of code should be familiar; it’s the onCreate() method that we have to implement for each of our activities, and that will be called when the activity is created. Remember that we must call the onCreate() method of the base class of our activity. It’s the first thing we must do in the onCreate() method of our own Activity implementation. If we don’t, an exception will be thrown and the activity will not be displayed.

With that out of the way, the next thing we do is call a method called setListAdapter(). This method is provided to us by the ListActivity class we derived it from. It lets us specify the list items we want the ListActivity class to display for us. These need to be passed to the method in the form of a class instance that implements the ListAdapter interface. We use the convenient ArrayAdapter class to do this. The constructor of this class takes three arguments: the first is our activity, the second we’ll explain in the next paragraph, and the third is the array of items that the ListActivity should display. We happily specify the tests array we defined earlier for the third argument, and that’s all we need to do.

So what’s this second argument to the ArrayAdapter constructor? To explain this, we’d have to go through all the Android UI API stuff, which we are not going to use in this book. So, instead of wasting pages on something we are not going to need, we’ll give you the quick-and-dirty explanation: each item in the list is displayed via a View. The argument defines the layout of each View, along with the type of each View. The value android.R.layout.simple_list_item_1 is a predefined constant provided by the UI API for getting up and running quickly. It stands for a standard list item View that will display text. Just as a quick refresher, a View is a UI widget on Android, such as a button, a text field, or a slider. We introduced views in form of a Button instance while dissecting the HelloWorldActivity in Chapter 2.

If we start our activity with just this onCreate() method, we’ll see something that looks like the screen shown in Figure 4-2.

Now let’s make something happen when a list item is touched. We want to start the respective activity that is represented by the list item we touched.

Starting Activities Programmatically

The ListActivity class has a protected method called onListItemClick() that will be called when an item is tapped. All we need to do is override that method in our AndroidBasicsStarter class. And that’s exactly what we did in Listing 4-1.

The arguments to this method are the ListView that the ListActivity uses to display the items, the View that got touched and that’s contained in that ListView, the position of the touched item in the list, and an ID, which doesn’t interest us all that much. All we really care about is the position argument.

The onListItemClicked() method starts off by being a good citizen and calls the base class method first. This is always a good thing to do if we override methods of an activity. Next, we fetch the class name from the tests array, based on the position argument. That’s the first piece of the puzzle.

Earlier, we discussed that we can start activities that we defined in the manifest file programmatically via an intent. The Intent class has a nice and simple constructor to do this, which takes two arguments: a Context instance and a Class instance. The latter represents the Java class of the activity we want to start.

Context is an interface that provides us with global information about our application. It is implemented by the Activity class, so we simply pass this reference to the Intent constructor.

To get the Class instance representing the activity we want to start, we use a little reflection, which will probably be familiar to you if you’ve worked with Java. Reflection allows us to programmatically inspect, instantiate, and call classes at runtime. The static method Class.forName() takes a string containing the fully qualified name of a class for which we want to create a Class instance. All of the test activities we’ll implement later will be contained in the com.badlogic.androidgames package. Concatenating the package name with the class name we fetched from the tests array will give us the fully qualified name of the activity class we want to start. We pass that name to Class.forName() and get a nice Class instance that we can pass to the Intent constructor.

Once the Intent instance is constructed, we can start it with a call to the startActivity() method. This method is also defined in the Context interface. Because our activity implements that interface, we just call its implementation of that method. And that’s it!

So how will our application behave? First, the starter activity will be displayed. Each time we touch an item on the list, the corresponding activity will be started. The starter activity will be paused and will go into the background. The new activity will be created by the intent we send out and will replace the starter activity on the screen. When we press the back button on the Android device, the activity is destroyed and the starter activity is resumed, taking back the screen.

Creating the Test Activities

When we create a new test activity, we have to perform the following steps:

1. Create the corresponding Java class in the com.badlogic.androidgames package and implement its logic.
2. Add an entry for the activity in the manifest file, using whatever attributes it needs (that is, android:configChanges or android:screenOrientation). Note that we won’t specify an <intent-filter> element, as we’ll start the activity programmatically.
3. Add the activity’s class name to the tests array of the AndroidBasicsStarter class.

As long as we stick to this procedure, everything else will be taken care of by the logic we implemented in the AndroidBasicsStarter class. The new activity will automatically show up in the list, and it can be started by a simple touch.

One thing you might wonder is whether the test activity that gets started on a touch is running in its own process and VM. It is not. An application composed of activities has something called an activity stack. Every time we start a new activity, it gets pushed onto that stack. When we close the new activity, the last activity that got pushed onto the stack will get popped and resumed, becoming the new active activity on the screen.

This also has some other implications. First, all of the activities of the application (those on the stack that are paused and the one that is active) share the same VM. They also share the same memory heap. That can be a blessing and a curse. If you have static fields in your activities, they will get memory on the heap as soon as they are started. Being static fields, they will survive the destruction of the activity and the subsequent garbage collection of the activity instance. This can lead to some bad memory leaks if you carelessly use static fields. Think twice before using a static field.

As stated a couple of times already, we’ll only ever have a single activity in our actual games. The preceding activity starter is an exception to this rule to make our lives a little easier. But don’t worry; we’ll have plenty of opportunities to get into trouble even with a single activity.

In Theory

An activity can be in one of three states:

• Running: In this state, it is the top-level activity that takes up the screen and directly interacts with the user.
• Paused: This happens when the activity is still visible on the screen but partially obscured by either a transparent activity or a dialog, or if the device screen is locked. A paused activity can be killed by the Android system at any point in time (for example, due to low memory). Note that the activity instance itself is still alive and kicking in the VM heap and waiting to be brought back to a running state.
• Stopped: This happens when the activity is completely obscured by another activity and thus is no longer visible on the screen. Our AndroidBasicsStarter activity will be in this state if we start one of the test activities, for example. It also happens when a user presses the home button to go to the home screen temporarily. The system can again decide to kill the activity completely and remove it from memory if memory gets low.

In both the paused and stopped states, the Android system can decide to kill the activity at any point in time. It can do so either politely, by first informing the activity by calling its finished() method, or impolitely, by silently killing the activity’s process.

The activity can be brought back to a running state from a paused or stopped state. Note again that when an activity is resumed from a paused or stopped state, it is still the same Java instance in memory, so all the state and member variables are the same as before the activity was paused or stopped.

An activity has some protected methods that we can override to get information about state changes:

• Activity.onCreate(): This is called when our activity is started up for the first time. Here, we set up all the UI components and hook into the input system. This method will get called only once in the life cycle of our activity.
• Activity.onRestart(): This is called when the activity is resumed from a stopped state. It is preceded by a call to onStop().
• Activity.onStart(): This is called after onCreate() or when the activity is resumed from a stopped state. In the latter case, it is preceded by a call to onRestart().
• Activity.onResume(): This is called after onStart() or when the activity is resumed from a paused state (for example, when the screen is unlocked).
• Activity.onPause(): This is called when the activity enters the paused state. It might be the last notification we receive, as the Android system might decide to kill our application silently. We should save all states we want to persist in this method!
• Activity.onStop(): This is called when the activity enters the stopped state. It is preceded by a call to onPause(). This means that an activity is stopped before it is paused. As with onPause(), it might be the last notification we get before the Android system silently kills the activity. We could also save persistent state here. However, the system might decide not to call this method and just kill the activity. As onPause() will always be called before onStop() and before the activity is silently killed, we’d rather save all our stuff in the onPause() method.
• Activity.onDestroy(): This is called at the end of the activity life cycle when the activity is irrevocably destroyed. It’s the last time we can persist any information we’d like to recover the next time our activity is created anew. Note that this method actually might never be called if the activity was destroyed silently after a call to onPause() or onStop() by the system.

Figure 4-3 illustrates the activity life cycle and the method call order.

Here are the three big lessons we should take away from this:

1. Before our activity enters the running state, the onResume() method is always called, whether or not we resume from a stopped state or from a paused state. We can thus safely ignore the onRestart() and onStart() methods. We don’t care whether we resumed from a stopped state or a paused state. For our games, we only need to know that we are now actually running, and the onResume() method signals that to us.
2. The activity can be destroyed silently after onPause(). We should never assume that either onStop() or onDestroy() gets called. We also know that onPause() will always be called before onStop(). We can therefore safely ignore the onStop() and onDestroy() methods and just override onPause(). In this method, we have to make sure that all the states we want to persist, like high scores and level progress, get written to external storage, such as an SD card. After onPause(), all bets are off, and we won’t know whether our activity will ever get the chance to run again.
3. We know that onDestroy() might never be called if the system decides to kill the activity after onPause() or onStop(). However, sometimes we’d like to know whether the activity is actually going to be killed. So how do we do that if onDestroy() is not going to get called? The Activity class has a method called Activity.isFinishing() that we can call at any time to check whether our activity is going to get killed. We are at least guaranteed that the onPause() method is called before the activity is killed. All we need to do is call this isFinishing() method inside the onPause() method to decide whether the activity is going to die after the onPause() call.

This makes life a lot easier. We only override the onCreate(), onResume(), and onPause() methods.

• In onCreate(), we set up our window and UI component to which we render and from which we receive input.
• In onResume(), we (re)start our main loop thread (discussed in Chapter 3).
• In onPause(), we simply pause our main loop thread, and if Activity.isFinishing() returns true, we also save to disk any state we want to persist.

Many people struggle with the activity life cycle, but if we follow these simple rules, our game will be capable of handling pausing, resuming, and cleaning up.

In Practice

Let’s write our first test example that demonstrates the activity life cycle. We’ll want to have some sort of output that displays which state changes have happened so far. We’ll do this in two ways:

1. The sole UI component that the activity will display is a TextView. As its name suggests, it displays text, and we’ve already used it implicitly for displaying each entry in our starter activity. Each time we enter a new state, we will append a string to the TextView, which will display all the state changes that have happened so far.
2. We won’t be able to display the destruction event of our activity in the TextView because it will vanish from the screen too fast, so we will also output all state changes to LogCat. We do this with the Log class, which provides a couple of static methods with which to append messages to LogCat.

Remember what we need to do to add a test activity to our test application. First, we define it in the manifest file in the form of an <activity> element, which is a child of the <application> element:

<activity android:label="Life Cycle Test"
          android:name=".LifeCycleTest"
          android:configChanges="keyboard|keyboardHidden|orientation" />

Next we add a new Java class called LifeCycleTest to our com.badlogic.androidgames package. Finally, we add the class name to the tests member of the AndroidBasicsStarter class we defined earlier. (Of course, we already have that in there from when we wrote the class for demonstration purposes.)

We’ll have to repeat all of these steps for any test activity that we create in the following sections. For brevity, we won’t mention these steps again. Also note that we didn’t specify an orientation for the LifeCycleTest activity. In this example, we can be in either landscape mode or portrait mode, depending on the device orientation. We did this so that you can see the effect of an orientation change on the life cycle (none, due to how we set the configChanges attribute). Listing 4-2 shows the code of the entire activity.

Listing 4-2.  LifeCycleTest.java, Demonstrating the Activity Life Cycle

package com.badlogic.androidgames;

import android.app.Activity;
import android.os.Bundle;
import android.util.Log;
import android.widget.TextView;

public class LifeCycleTest extends Activity {
   StringBuilder builder = new StringBuilder();
   TextView textView;

   private void log(String text) {
       Log.d("LifeCycleTest", text);
       builder.append(text);
       builder.append('
'),
       textView.setText(builder.toString());
   }

   @Override
   public void onCreate(Bundle savedInstanceState) {
      super .onCreate(savedInstanceState);
      textView = new TextView(this );
      textView.setText(builder.toString());
        setContentView(textView);
        log("created");
   }

   @Override
   protected void onResume() {
      super .onResume();
      log("resumed");
   }

   @Override
   protected void onPause() {
      super .onPause();
      log("paused");

      if (isFinishing()) {
            log("finishing");
      }
   }
}

Let’s go through this code really quickly. The class derives from Activity—not a big surprise. We define two members: a StringBuilder, which will hold all the messages we have produced so far, and the TextView, which we use to display those messages directly in the Activity.

Next, we define a little private helper method that will log text to LogCat, append it to our StringBuilder, and update the TextView text. For the LogCat output, we use the static Log.d() method, which takes a tag as the first argument and the actual message as the second argument.

In the onCreate() method, we call the superclass method first, as always. We create the TextView and set it as the content view of our activity. It will fill the complete space of the activity. Finally, we log the message created to LogCat and update the TextView text with our previously defined helper method log().

Next, we override the onResume() method of the activity. As with any activity methods that we override, we first call the superclass method. All we do is call log() again with resumed as the argument.

The overridden onPause() method looks much like the onResume() method. We log the message as “paused” first. We also want to know whether the activity is going to be destroyed after the onPause() method call, so we check the Activity.isFinishing() method. If it returns true, we log the finishing event as well. Of course, we won’t be able to see the updated TextView text because the activity will be destroyed before the change is displayed on the screen. Thus, we also output everything to LogCat, as discussed earlier.

Run the application, and play around with this test activity a little. Here’s a sequence of actions you could execute:

1. Start up the test activity from the starter activity.
2. Lock the screen.
3. Unlock the screen.
4. Press the home button (which will take you back to the home screen).
5. On the home screen, on older Android versions (prior to version 3), hold the home button until you are presented with the currently running applications. On Android versions 3+, touch the Running Apps button. Select the Android Basics Starter app to resume (which will bring the test activity back onscreen).
6. Press the back button (which will take you back to the starter activity).

If your system didn’t decide to kill the activity silently at any point when it was paused, you will see the output in Figure 4-4 (of course, only if you haven’t pressed the back button yet).

On startup, onCreate() is called, followed by onResume(). When we lock the screen, onPause() is called. When we unlock the screen, onResume() is called. When we press the home button, onPause() is called. Going back to the activity will call onResume() again. The same messages are, of course, shown in LogCat, which you can observe in Eclipse in the LogCat view. Figure 4-5 shows what we wrote to LogCat while executing the preceding sequence of actions (plus pressing the back button).

Pressing the back button again invokes the onPause() method. As it also destroys the activity, the if-statement in onPause() also gets triggered, informing us that this is the last we’ll see of that activity.

That is the activity life cycle, demystified and simplified for our game programming needs. We now can easily handle any pause and resume events, and we are guaranteed to be notified when the activity is destroyed.

Getting (Multi-)Touch Events

The touchscreen is probably the most important way to get input from the user. Until Android version 2.0, the API only supported processing single-finger touch events. Multitouch was introduced in Android 2.0 (SDK version 5). The multitouch event reporting was tagged onto the single-touch API, with some mixed results in usability. We’ll first investigate handling single-touch events, which are available on all Android versions.

Processing Single-Touch Events

When we processed taps on a button in Chapter 2, we saw that listener interfaces are the way Android reports events to us. Touch events are no different. Touch events are passed to an OnTouchListener interface implementation that we register with a View. The OnTouchListener interface has only a single method:

public abstract boolean onTouch (View v, MotionEvent event)

The first argument is the View to which the touch events get dispatched. The second argument is what we’ll dissect to get the touch event.

An OnTouchListener can be registered with any View implementation via the View.setOnTouchListener() method. The OnTouchListener will be called before the MotionEvent is dispatched to the View itself. We can signal to the View in our implementation of the onTouch() method that we have already processed the event by returning true from the method. If we return false, the View itself will process the event.

The MotionEvent instance has three methods that are relevant to us:

• MotionEvent.getX() and MotionEvent.getY(): These methods report the x and y coordinates of the touch event relative to the View. The coordinate system is defined with the origin in the top left of the view, with the x axis pointing to the right and the y axis pointing downward. The coordinates are given in pixels. Note that the methods return floats, and thus the coordinates have subpixel accuracy.
• MotionEvent.getAction(): This method returns the type of the touch event. It is an integer that takes on one of the values MotionEvent.ACTION_DOWN, MotionEvent.ACTION_MOVE, MotionEvent.ACTION_CANCEL, or MotionEvent.ACTION_UP.

Sounds simple, and it really is. The MotionEvent.ACTION_DOWN event happens when the finger touches the screen. When the finger moves, events with type MotionEvent.ACTION_MOVE are fired. Note that you will always get MotionEvent.ACTION_MOVE events, as you can’t hold your finger still enough to avoid them. The touch sensor will recognize the slightest change. When the finger is lifted up again, the MotionEvent.ACTION_UP event is reported. MotionEvent.ACTION_CANCEL events are a bit of a mystery. The documentation says they will be fired when the current gesture is canceled. We have never seen that event in real life yet. However, we’ll still process it and pretend it is a MotionEvent.ACTION_UP event when we start implementing our first game.

Let’s write a simple test activity to see how this works in code. The activity should display the current position of the finger on the screen as well as the event type. Listing 4-3 shows what we came up with.

Listing 4-3.  SingleTouchTest.java; Testing Single-Touch Handling

package com.badlogic.androidgames;

import android.app.Activity;
import android.os.Bundle;
import android.util.Log;
import android.view.MotionEvent;
import android.view.View;
import android.view.View.OnTouchListener;
import android.widget.TextView;

public class SingleTouchTest extends Activity implements OnTouchListener {
   StringBuilder builder = new StringBuilder();
   TextView textView;

   public void onCreate(Bundle savedInstanceState) {
       super .onCreate(savedInstanceState);
       textView = new TextView(this );
       textView.setText("Touch and drag (one finger only)!");
       textView.setOnTouchListener(this );
       setContentView(textView);
   }

   public boolean onTouch(View v, MotionEvent event) {
      builder.setLength(0);
      switch (event.getAction()) {
      case MotionEvent.ACTION_DOWN:
          builder.append("down, ");
          break ;
      case MotionEvent.ACTION_MOVE:
          builder.append("move, ");
          break ;
      case MotionEvent.ACTION_CANCEL:
          builder.append("cancel", ");
          break ;
      case MotionEvent.ACTION_UP:
          builder.append("up, ");
          break ;
      }
      builder.append(event.getX());
      builder.append(", ");
      builder.append(event.getY());
      String text = builder.toString();
      Log.d("TouchTest", text);
      textView.setText(text);
      return true ;
   }
}

We let our activity implement the OnTouchListener interface. We also have two members: one for the TextView, and a StringBuilder we’ll use to construct our event strings.

The onCreate() method is pretty self-explanatory. The only novelty is the call to TextView.setOnTouchListener(), where we register our activity with the TextView so that it receives MotionEvents.

What’s left is the onTouch() method implementation itself. We ignore the view argument, as we know that it must be the TextView. All we are interested in is getting the touch event type, appending a string identifying it to our StringBuilder, appending the touch coordinates, and updating the TextView text. That’s it. We also log the event to LogCat so that we can see the order in which the events happen, as the TextView will only show the last event that we processed (we clear the StringBuilder every time onTouch() is called).

One subtle detail in the onTouch() method is the return statement, where we return true. Usually, we’d stick to the listener concept and return false in order not to interfere with the event-dispatching process. If we do this in our example, we won’t get any events other than the MotionEvent.ACTION_DOWN event. So, we tell the TextView that we just consumed the event. That behavior might differ between different View implementations. Luckily, we’ll only need three other views in the rest of this book, and those will happily let us consume any event we want.

If we fire up that application on the emulator or a connected device, we can see how the TextView will always display the last event type and position reported to the onTouch() method. Additionally, you can see the same messages in LogCat.

We did not fix the orientation of the activity in the manifest file. If you rotate your device so that the activity is in landscape mode, the coordinate system changes, of course. Figure 4-6 shows the activity in portrait mode (left) and landscape mode (right). In both cases, we tried to touch the middle of the View. Note how the x and y coordinates seem to get swapped. The figure also shows the x and y axes in both cases (the yellow lines), along with the point on the screen that we roughly touched (the green circle). In both cases, the origin is in the upper-left corner of the TextView, with the x axis pointing to the right and the y axis pointing downward.

Depending on the orientation, our maximum x and y values change, of course. The preceding images were taken on a Nexus One running Android 2.2 (Froyo), which has a screen resolution of 480×800 pixels in portrait mode (800×480 in landscape mode). Since the touch coordinates are given relative to the View, and since the view doesn’t fill the complete screen, our maximum y value will be smaller than the resolution height. We’ll see later how we can enable full-screen mode so that the title bar and notification bar don’t get in our way.

Sadly, there are a few issues with touch events on older Android versions and first-generation devices:

• Touch event flood: The driver will report as many touch events as possible when a finger is down on the touchscreen—on some devices, hundreds per second. We can fix this issue by putting a Thread.sleep(16) call into our onTouch() method, which will put to sleep for 16 ms the UI thread on which those events are dispatched. With this, we’ll get 60 events per second at most, which is more than enough to have a responsive game. This is only a problem on devices with Android version 1.5. If you don’t target that Android version, ignore this advice.
• Touching the screen eatsthe CPU: Even if we sleep in our onTouch() method, the system has to process the events in the kernel as reported by the driver. On old devices, such as the Hero or G1, this can use up to 50 percent of the CPU, which leaves a lot less processing power for our main loop thread. As a consequence, our perfectly fine frame rate will drop considerably, sometimes to the point where the game becomes unplayable. On second-generation devices, the problem is a lot less pronounced and can usually be ignored. Sadly, there’s no solution for this on older devices.

Processing Multitouch Events

Warning: Major pain ahead! The multitouch API has been tagged onto the MotionEvent class, which originally handled only single touches. This makes for some major confusion when trying to decode multitouch events. Let’s try to make some sense of it.

Handling multitouch events is very similar to handling single-touch events. We still implement the same OnTouchListener interface we implemented for single-touch events. We also get a MotionEvent instance from which to read the data. We also process the event types we processed before, like MotionEvent.ACTION_UP, plus a couple of new ones that aren’t too big of a deal.

event.getX(pointerIndex);
event.getY(pointerIndex);

int pointerIndex = (event.getAction() & MotionEvent.ACTION_POINTER_ID_MASK) >> MotionEvent.ACTION_POINTER_ID_SHIFT;

int action = event.getAction() & MotionEvent.ACTION_MASK;

package com.badlogic.androidgames;

import android.app.Activity;
import android.os.Bundle;
import android.view.MotionEvent;
import android.view.View;
import android.view.View.OnTouchListener;
import android.widget.TextView;

@TargetApi (5)
public class MultiTouchTest extends Activity implements OnTouchListener {
   StringBuilder builder = new StringBuilder();
   TextView textView;
   float [] x = new float [10];
   float [] y = new float [10];
   boolean [] touched = new boolean [10];
   int [] id = new int [10];

   private void updateTextView() {
      builder.setLength(0);
      for (int i = 0; i < 10; i++) {
          builder.append(touched[i]);
          builder.append(", ");
          builder.append(id[i]);
          builder.append(", ");
          builder.append(x[i]);
          builder.append(", ");
          builder.append(y[i]);
          builder.append("
");
        }
        textView.setText(builder.toString());
    }

    public void onCreate(Bundle savedInstanceState) {
       super .onCreate(savedInstanceState);
       textView = new TextView(this );
       textView.setText("Touch and drag (multiple fingers supported)!");
       textView.setOnTouchListener(this );
       setContentView(textView);
       for (int i = 0; i < 10; i++) {
           id[i] = -1;
       }
       updateTextView();
    }

    public boolean onTouch(View v, MotionEvent event) {
       int action = event.getAction() & MotionEvent.ACTION_MASK;
       int pointerIndex = (event.getAction() & MotionEvent.ACTION_POINTER_ID_MASK) >> MotionEvent.ACTION_POINTER_ID_SHIFT;
       int pointerCount = event.getPointerCount();
       for (int i = 0; i < 10; i++) {
             if (i >= pointerCount) {
                 touched[i] = false ;
                 id[i] = -1;
                 continue ;
             }
             if (event.getAction() != MotionEvent.ACTION_MOVE&& i != pointerIndex) {
                 // if it's an up/down/cancel/out event, mask the id to see if we should process it for this touch point
                 continue ;
             }
             int pointerId = event.getPointerId(i);
             switch (action) {

             case MotionEvent.ACTION_DOWN:
             case MotionEvent.ACTION_POINTER_DOWN:
                 touched[i] = true ;
                 id[i] = pointerId;
                 x[i] = (int ) event.getX(i);
                 y[i] = (int ) event.getY(i);
                 break ;
             case MotionEvent.ACTION_UP:
             case MotionEvent.ACTION_POINTER_UP:
     case MotionEvent.ACTION_OUTSIDE:
             case MotionEvent.ACTION_CANCEL:
                 touched[i] = false ;
                 id[i] = -1;
                 x[i] = (int ) event.getX(i);
                 y[i] = (int ) event.getY(i);
                 break ;

             case MotionEvent.ACTION_MOVE:
                 touched[i] = true ;
                 id[i] = pointerId;
                 x[i] = (int ) event.getX(i);
                 y[i] = (int ) event.getY(i);
                 break ;
             }
         }
         updateTextView();
         return true ;
     }
}

Processing Key Events

After the insanity of the last section, you deserve something dead simple. Welcome to processing key events.

To catch key events, we implement another listener interface, called OnKeyListener. It has a single method, called onKey(), with the following signature:

public boolean onKey(View view, int keyCode, KeyEvent event)

The View specifies the view that received the key event, the keyCode argument is one of the constants defined in the KeyEvent class, and the final argument is the key event itself, which has some additional information.

What is a key code? Each key on the (onscreen) keyboard and each of the system keys has a unique number assigned to it. These key codes are defined in the KeyEvent class as static public final integers. One such key code is KeyCode.KEYCODE_A, which is the code for the A key. This has nothing to do with the character that is generated in a text field when a key is pressed. It really just identifies the key itself.

The KeyEvent class is similar to the MotionEvent class. It has two methods that are relevant for us:

• KeyEvent.getAction(): This returns KeyEvent.ACTION_DOWN, KeyEvent.ACTION_UP, and KeyEvent.ACTION_MULTIPLE. For our purposes, we can ignore the last key event type. The other two will be sent when a key is either pressed or released.
• KeyEvent.getUnicodeChar(): This returns the Unicode character the key would produce in a text field. Say we hold down the Shift key and press the A key. This would be reported as an event with a key code of KeyEvent.KEYCODE_A, but with a Unicode character A. We can use this method if we want to do text input ourselves.

To receive keyboard events, a View must have the focus. This can be forced with the following method calls:

View.setFocusableInTouchMode(true);
View.requestFocus();

The first method will guarantee that the View can be focused. The second method requests that the specific View gets the focus.

Let’s implement a simple test activity to see how this works in combination. We want to get key events and display the last one we received in a TextView. The information we’ll display is the key event type, along with the key code and the Unicode character, if one would be produced. Note that some keys do not produce a Unicode character on their own, but only in combination with other characters. Listing 4-5 demonstrates how we can achieve all of this in a small number of code lines.

Listing 4-5.  KeyTest.Java; Testing the Key Event API

package com.badlogic.androidgames;

import android.app.Activity;
import android.os.Bundle;
import android.util.Log;
import android.view.KeyEvent;
import android.view.View;
import android.view.View.OnKeyListener;
import android.widget.TextView;

public class KeyTest extends Activity implements OnKeyListener {
   StringBuilder builder = new StringBuilder();
   TextView textView;

   public void onCreate(Bundle savedInstanceState) {
      super .onCreate(savedInstanceState);
      textView = new TextView(this );
      textView.setText("Press keys (if you have some)!");
      textView.setOnKeyListener(this );
      textView.setFocusableInTouchMode(true );
      textView.requestFocus();
      setContentView(textView);
   }

    public boolean onKey(View view, int keyCode, KeyEvent event) {
       builder.setLength(0);
       switch (event.getAction()) {
       case KeyEvent.ACTION_DOWN:
           builder.append("down, ");
           break ;
       case KeyEvent.ACTION_UP:
           builder.append("up, ");
           break ;
       }
       builder.append(event.getKeyCode());
       builder.append(", ");
       builder.append((char ) event.getUnicodeChar());
       String text = builder.toString();
       Log.d("KeyTest", text);
       textView.setText(text);

       return event.getKeyCode() != KeyEvent.KEYCODE_BACK;
   }
}

We start off by declaring that the activity implements the OnKeyListener interface. Next, we define two members with which we are already familiar: a StringBuilder to construct the text to be displayed and a TextView to display the text.

In the onCreate() method, we make sure the TextView has the focus so it can receive key events. We also register the activity as the OnKeyListener via the TextView.setOnKeyListener() method.

The onKey() method is also pretty straightforward. We process the two event types in the switch statement, appending a proper string to the StringBuilder. Next, we append the key code as well as the Unicode character from the KeyEvent itself and output the contents of the StringBuffer instance to LogCat as well as the TextView.

The last if statement is interesting: if the Back key is pressed, we return false from the onKey() method, making the TextView process the event. Otherwise, we return true. Why differentiate here?

If we were to return true in the case of the Back key, we’d mess with the activity life cycle a little. The activity would not be closed, as we decided to consume the Back key ourselves. Of course, there are scenarios where we’d actually want to catch the Back key so that our activity does not get closed. However, it is strongly advised not to do this unless absolutely necessary.

Figure 4-8 illustrates the output of the activity while holding down the Shift and A keys on the keyboard of a Droid.

There are a couple of things to note here:

• When you look at the LogCat output, notice that we can easily process simultaneous key events. Holding down multiple keys is not a problem.
• Pressing the D-pad and rolling the trackball are both reported as key events.
• As with touch events, key events can eat up considerable CPU resources on old Android versions and first-generation devices. However, they will not produce a flood of events.

That was pretty relaxing compared to the previous section, wasn’t it?

Reading the Accelerometer State

A very interesting input option for games is the accelerometer. All Android devices are required to contain a three-axis accelerometer. We talked about accelerometers a little bit in Chapter 3. Generally, we’ll only poll the state of the accelerometer.

So how do we get that accelerometer information? You guessed correctly—by registering a listener. The interface we need to implement is called SensorEventListener, which has two methods:

public void onSensorChanged(SensorEvent event);
public void onAccuracyChanged(Sensor sensor, int accuracy);

The first method is called when a new accelerometer event arrives. The second method is called when the accuracy of the accelerometer changes. We can safely ignore the second method for our purposes.

So where do we register our SensorEventListener? For this, we have to do a little bit of work. First, we need to check whether there actually is an accelerometer installed in the device. Now, we just told you that all Android devices must contain an accelerometer. This is still true, but it might change in the future. We therefore want to make 100 percent sure that that input method is available to us.

The first thing we need to do is get an instance of the SensorManager. That guy will tell us whether an accelerometer is installed, and it is also where we register our listener. To get the SensorManager, we use a method of the Context interface:

SensorManager manager = (SensorManager)context.getSystemService(Context.SENSOR_SERVICE);

The SensorManager is a system service that is provided by the Android system. Android is composed of multiple system services, each serving different pieces of system information to anyone who asks nicely.

Once we have the SensorManager, we can check whether the accelerometer is available:

boolean hasAccel = manager.getSensorList(Sensor.TYPE_ACCELEROMETER).size() > 0;

With this bit of code, we poll the SensorManager for all the installed sensors that have the type accelerometer. While this implies that a device can have multiple accelerometers, in reality this will only ever return one accelerometer sensor.

If an accelerometer is installed, we can fetch it from the SensorManager and register the SensorEventListener with it as follows:

Sensor sensor = manager.getSensorList(Sensor.TYPE_ACCELEROMETER).get(0);
boolean success = manager.registerListener(listener, sensor, SensorManager.SENSOR_DELAY_GAME);

The argument SensorManager.SENSOR_DELAY_GAME specifies how often the listener should be updated with the latest state of the accelerometer. This is a special constant that is specifically designed for games, so we happily use that. Notice that the SensorManager.registerListener() method returns a Boolean, indicating whether the registration process worked or not. That means we have to check the Boolean afterward to make sure we’ll actually get any events from the sensor.

Once we have registered the listener, we’ll receive SensorEvents in the SensorEventListener.onSensorChanged() method. The method name implies that it is only called when the sensor state has changed. This is a little bit confusing, since the accelerometer state is changed constantly. When we register the listener, we actually specify the desired frequency with which we want to receive our sensor state updates.

So how do we process the SensorEvent? That’s rather easy. The SensorEvent has a public float array member called SensorEvent.values that holds the current acceleration values of each of the three axes of the accelerometer. SensorEvent.values[0] holds the value of the x axis, SensorEvent.values[1] holds the value of the y axis, and SensorEvent.values[2] holds the value of the z axis. We discussed what is meant by these values in Chapter 3, so if you have forgotten that, go and check out the “Input” section again.

With this information, we can write a simple test activity. All we want to do is output the accelerometer values for each accelerometer axis in a TextView. Listing 4-6 shows how to do this.

Listing 4-6.  AccelerometerTest.java; Testing the Accelerometer API

package com.badlogic.androidgames;

import android.app.Activity;
import android.content.Context;
import android.hardware.Sensor;
import android.hardware.SensorEvent;
import android.hardware.SensorEventListener;
import android.hardware.SensorManager;
import android.os.Bundle;
import android.widget.TextView;

public class AccelerometerTest extends Activity implements SensorEventListener {
   TextView textView;
   StringBuilder builder = new StringBuilder();

   @Override
   public void onCreate(Bundle savedInstanceState) {
      super .onCreate(savedInstanceState);
      textView = new TextView(this );
      setContentView(textView);

      SensorManager manager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
      if (manager.getSensorList(Sensor.TYPE_ACCELEROMETER).size() == 0) {
          textView.setText("No accelerometer installed");
      }else {
          Sensor accelerometer = manager.getSensorList(
                  Sensor.TYPE_ACCELEROMETER).get(0);
          if (!manager.registerListener(this , accelerometer,
                  SensorManager.SENSOR_DELAY_GAME)) {
              textView.setText("Couldn't register sensor listener");
          }
      }
   }

   public void onSensorChanged(SensorEvent event) {
      builder.setLength(0);
      builder.append("x: ");
      builder.append(event.values[0]);
      builder.append(", y: ");
      builder.append(event.values[1]);
      builder.append(", z: ");
      builder.append(event.values[2]);
      textView.setText(builder.toString());
   }

   public void onAccuracyChanged(Sensor sensor, int accuracy) {
      // nothing to do here
   }
}

We start by checking whether an accelerometer sensor is available. If it is, we fetch it from the SensorManager and try to register our activity, which implements the SensorEventListener interface. If any of this fails, we set the TextView to display a proper error message.

The onSensorChanged() method simply reads the axis values from the SensorEvent that are passed to it and updates the TextView text accordingly.

The onAccuracyChanged() method is there so that we fully implement the SensorEventListener interface. It serves no real other purpose.

Figure 4-9 shows what values the axes take on in portrait and landscape modes when the device is held perpendicular to the ground.

One thing that’s a gotcha for Android accelerometer handling is the fact that the accelerometer values are relative to the default orientation of the device. This means that if your game is run only in landscape, a device where the default orientation is portrait will have values 90 degrees different from those of a device where the default orientation is landscape! This is the case on tablets, for example. So how does one cope with this? Use this handy-dandy code snippet and you should be good to go:

int screenRotation;
public void onResume() {
        WindowManager windowMgr = (WindowManager)activity.getSystemService(Activity.WINDOW_SERVICE);
                // getOrientation() is deprecated in Android 8 but is the same as getRotation(), which is the rotation from the natural orientation of the device
        screenRotation = windowMgr.getDefaultDisplay().getOrientation();
}
static final int ACCELEROMETER_AXIS_SWAP[][] = {
    {1, -1, 0, 1}, // ROTATION_0
    {-1, -1, 1, 0}, // ROTATION_90
    {-1, 1, 0, 1}, // ROTATION_180
    {1, 1, 1, 0}}; // ROTATION_270
public void onSensorChanged(SensorEvent event) {
    final int [] as =ACCELEROMETER_AXIS_SWAP[screenRotation];
    float screenX = (float )as[0] * event.values[as[2]];
    float screenY = (float )as[1] * event.values[as[3]];
    float screenZ = event.values[2];
    // use screenX, screenY, and screenZ as your accelerometer values now!
}

Here are a few closing comments on accelerometers:

• As you can see in the screenshot on the right in Figure 4-9, the accelerometer values might sometimes go over their specified range. This is due to small inaccuracies in the sensor, so you have to adjust for that if you need those values to be as exact as possible.
• The accelerometer axes always get reported in the same order, no matter the orientation of your activity.
• It is the responsibility of the application developer to rotate the accelerometer values based on the natural orientation of the device.

Reading the Compass State

Reading sensors other than the accelerometer, such as the compass, is very similar. In fact, it is so similar that you can simply replace all instances of Sensor.TYPE_ACCELEROMETER in Listing 4-6 with Sensor.TYPE_ORIENTATION and rerun the test to use our accelerometer test code as a compass test!

You will now see that your x, y, and z values are doing something very different. If you hold the device flat with the screen up and parallel to the ground, x will read the number of degrees for a compass heading and y and z should be near 0. Now tilt the device around and see how those numbers change. The x should still be the primary heading (azimuth), but y and z should show you the pitch and roll of the device, respectively. Because the constant for TYPE_ORIENTATION was deprecated, you can also receive the same compass data from a call to SensorManager.getOrientation(float[] R, float[] values), where R is a rotation matrix (see SensorManager.getRotationMatrix()) and values holds the three return values, this time in radians.

With this, we have discussed all of the input processing-related classes of the Android API that we’ll need for game development.

Reading Assets

In Chapter 2, we had a brief look at all the folders of an Android project. We identified the assets/ and res/ folders as the ones where we can put files that should get distributed with our application. When we discussed the manifest file, we stated that we’re not going to use the res/ folder, as it implies restrictions on how we structure our file set. The assets/ directory is the place to put all our files, in whatever folder hierarchy we want.

The files in the assets/ folder are exposed via a class called AssetManager. We can obtain a reference to that manager for our application as follows:

AssetManager assetManager = context.getAssets();

We already saw the Context interface; it is implemented by the Activity class. In real life, we’d fetch the AssetManager from our activity.

Once we have the AssetManager, we can start opening files like crazy:

InputStream inputStream = assetManager.open("dir/dir2/filename.txt");

This method will return a plain-old Java InputStream, which we can use to read in any sort of file. The only argument to the AssetManager.open() method is the filename relative to the asset directory. In the preceding example, we have two directories in the assets/ folder, where the second one (dir2/) is a child of the first one (dir/). In our Eclipse project, the file would be located in assets/dir/dir2/.

Let’s write a simple test activity that examines this functionality. We want to load a text file named myawesometext.txt from a subdirectory of the assets/ directory called texts. The content of the text file will be displayed in a TextView. Listing 4-7 shows the source for this awe-inspiring activity.

Listing 4-7.  AssetsTest.java, Demonstrating How to Read Asset Files

package com.badlogic.androidgames;

import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;

import android.app.Activity;
import android.content.res.AssetManager;
import android.os.Bundle;
import android.widget.TextView;

public class AssetsTest extends Activity {
   @Override
   public void onCreate(Bundle savedInstanceState) {
      super .onCreate(savedInstanceState);
      TextView textView = new TextView(this );
      setContentView(textView);

      AssetManager assetManager = getAssets();
      InputStream inputStream = null ;
      try {
          inputStream = assetManager.open("texts/myawesometext.txt");
          String text = loadTextFile(inputStream);
          textView.setText(text);
      }catch (IOException e) {
          textView.setText("Couldn't load file");
      }finally {
          if (inputStream != null )
              try {
                  inputStream.close();
              }catch (IOException e) {
                  textView.setText("Couldn't close file");
              }
      }
   }

    public String loadTextFile(InputStream inputStream)throws IOException {
       ByteArrayOutputStream byteStream = new ByteArrayOutputStream();
       byte [] bytes = new byte [4096];
       int len = 0;
       while ((len = inputStream.read(bytes)) > 0)
          byteStream.write(bytes, 0, len);
       return new String(byteStream.toByteArray(), "UTF8");
   }
}

We see no big surprises here, other than finding that loading simple text from an InputStream is rather verbose in Java. We wrote a little method called loadTextFile() that will squeeze all the bytes out of the InputStream and return the bytes in the form of a string. We assume that the text file is encoded as UTF-8. The rest is just catching and handling various exceptions. Figure 4-10 shows the output of this little activity.

You should take away the following from this section:

• Loading a text file from an InputStream in Java is a mess! Usually, we’d do that with something like Apache IOUtils. We’ll leave that for you as an exercise to perform on your own.
• We can only read assets, not write them.
• We could easily modify the loadTextFile() method to load binary data instead. We would just need to return the byte array instead of the string.

Accessing the External Storage

While assets are superb for shipping all our images and sounds with our application, there are times when we need to be able to persist some information and reload it later on. A common example would be high scores.

Android offers many different ways of doing this, such as using local shared preferences of an application, using a small SQLite database, and so on. All of these options have one thing in common: they don’t handle large binary files all that gracefully. Why would we need that anyway? While we can tell Android to install our application on the external storage device, and thus not waste memory in internal storage, this will only work on Android version 2.2 and above. For earlier versions, all our application data would get installed in internal storage. In theory, we could only include the code of our application in the APK file and download all the asset files from a server to the SD card the first time our application is started. Many of the high-profile games on Android do this.

There are also other scenarios where we’d want to have access to the SD card (which is pretty much synonymous with the term external storage on all currently available devices). We could allow our users to create their own levels with an in-game editor. We’d need to store these levels somewhere, and the SD card is perfect for just that purpose.

So, now that we’ve convinced you not to use the fancy mechanisms Android offers to store application preferences, let’s have a look at how to read and write files on the SD card.

The first thing we have to do is request permission to access the external storage. This is done in the manifest file with the <uses-permission> element discussed earlier in this chapter.

Next we have to check whether there is actually an external storage device available on the Android device of the user. For example, if you create an Android Virtual Device (AVD), you have the option of not having it simulate an SD card, so you couldn’t write to it in your application. Another reason for failing to get access to the SD card could be that the external storage device is currently in use by something else (for example, the user may be exploring it via USB on a desktop PC). So, here’s how we get the state of the external storage:

String state = Environment.getExternalStorageState();

Hmm, we get a string. The Environment class defines a couple of constants. One of these is called Environment.MEDIA_MOUNTED. It is also a string. If the string returned by the preceding method equals this constant, we have full read/write access to the external storage. Note that you really have to use the equals() method to compare the two strings; reference equality won’t work in every case.

Once we have determined that we can actually access the external storage, we need to get its root directory name. If we then want to access a specific file, we need to specify it relative to this directory. To get that root directory, we use another Environment static method:

File externalDir = Environment.getExternalStorageDirectory();

From here on, we can use the standard Java I/O classes to read and write files.

Let’s write a quick example that writes a file to the SD card, reads the file back in, displays its content in a TextView, and then deletes the file from the SD card again. Listing 4-8 shows the source code for this.

Listing 4-8.  The ExternalStorageTest Activity

package com.badlogic.androidgames;

import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.File;
import java.io.FileReader;
import java.io.FileWriter;
import java.io.IOException;

import android.app.Activity;
import android.os.Bundle;
import android.os.Environment;
import android.widget.TextView;

public class ExternalStorageTest extends Activity {
   @Override
   public void onCreate(Bundle savedInstanceState) {
      super .onCreate(savedInstanceState);
      TextView textView = new TextView(this );
      setContentView(textView);

      String state = Environment.getExternalStorageState();
      if (!state.equals(Environment.MEDIA_MOUNTED)) {
          textView.setText("No external storage mounted");
      }else {
          File externalDir = Environment.getExternalStorageDirectory();
          File textFile = new File(externalDir.getAbsolutePath()
                  + File.separator+ "text.txt");
          try {
              writeTextFile(textFile, "This is a test. Roger");
              String text = readTextFile(textFile);
              textView.setText(text);
              if (!textFile.delete()) {
                  textView.setText("Couldn't remove temporary file");
              }
          }catch (IOException e) {
              textView.setText("Something went wrong! " + e.getMessage());
           }
       }
   }

   private void writeTextFile(File file, String text)throws IOException {
      BufferedWriter writer = new BufferedWriter(new FileWriter(file));
      writer.write(text);
      writer.close();
   }

   private String readTextFile(File file)throws IOException {
      BufferedReader reader = new BufferedReader(new FileReader(file));
      StringBuilder text = new StringBuilder();
      String line;
      while ((line = reader.readLine()) != null ) {
          text.append(line);
          text.append("
");
      }
      reader.close();
      return text.toString();
   }
}

First, we check whether the SD card is actually mounted. If not, we bail out early. Next, we get the external storage directory and construct a new File instance that points to the file we are going to create in the next statement. The writeTextFile() method uses standard Java I/O classes to do its magic. If the file doesn’t exist yet, this method will create it; otherwise, it will overwrite an already existing file. After we successfully dump our test text to the file on the external storage device, we read it in again and set it as the text of the TextView. As a final step, we delete the file from external storage again. All of this is done with standard safety measures in place that will report if something goes wrong by outputting an error message to the TextView. Figure 4-11 shows the output of the activity.

Here are the lessons to take away from this section:

• Don’t mess with any files that don’t belong to you. Your users will be angry if you delete the photos of their last holiday.
• Always check whether the external storage device is mounted.
• Do not mess with any of the files on the external storage device!

Because it is very easy to delete all the files on the external storage device, you might think twice before you install your next app from Google Play that requests permissions to the SD card. The app has full control over your files once it’s installed.

Shared Preferences

Android provides a simple API for storing key-value pairs for your application, called SharedPreferences. The SharedPreferences API is not unlike the standard Java Properties API. An activity can have a default SharedPreferences instance or it can use as many different SharedPreferences instance as required. Here are the typical ways to get an instance of SharedPreferences from an activity:

SharedPreferences prefs = PreferenceManager.getDefaultSharedPreferences(this );

      or:

SharedPreferences prefs = getPreferences(Context.MODE_PRIVATE);

The first method gives a common SharedPreferences that will be shared for that context (Activity, in our case). The second method does the same, but it lets you choose the privacy of the shared preferences. The options are Context.MODE_PRIVATE, which is the default, Context.MODE_WORLD_READABLE, and Context.MODE_WORLD_WRITEABLE. Using anything other than Context.MODE_PRIVATE is more advanced, and it isn’t necessary for something like saving game settings.

To use the shared preferences, you first need to get the editor. This is done via

Editor editor = prefs.edit()

Now we can insert some values:

editor.putString("key1", "banana");
editor.putInt("key2", 5);

And finally, when we want to save, we just add

editor.commit();

Ready to read back? It’s exactly as one would expect:

String value1 = prefs.getString("key1", null);
int value2 = prefs.getInt("key2", 0);

In our example, value1 would be "banana" and value2 would be 5. The second parameter to the “get” calls of SharedPreferences are default values. These will be used if the key isn’t found in the preferences. For example, if "key1" was never set, then value1 will be null after the getString call. SharedPreferences are so simple that we don’t really need any test code to demonstrate. Just remember always to commit those edits!

Setting the Volume Controls

If you have an Android device, you will have noticed that when you press the volume up and down buttons, you control different volume settings depending on the application you are currently using. In a call, you control the volume of the incoming voice stream. In a YouTube application, you control the volume of the video’s audio. On the home screen, you control the volume of the system sounds, such as the ringer or an arriving instant message.

Android has different audio streams for different purposes. When we play back audio in our game, we use classes that output sound effects and music to a specific stream called the music stream. Before we think about playing back sound effects or music, we first have to make sure that the volume buttons will control the correct audio stream. For this, we use another method of the Context interface:

context.setVolumeControlStream(AudioManager.STREAM_MUSIC);

As always, the Context implementation of our choice will be our activity. After this call, the volume buttons will control the music stream to which we’ll later output our sound effects and music. We need to call this method only once in our activity life cycle. The Activity.onCreate() method is the best place to do this.

Writing an example that only contains a single line of code is a bit of overkill. Thus, we’ll refrain from doing that at this point. Just remember to use this method in all the activities that output sound.

Using Wake Locks

If you leave the tests we wrote so far alone for a few seconds, the screen of your phone will dim. Only if you touch the screen or hit a button will the screen go back to its full brightness. To keep our screen awake at all times, we can use a wake lock.

The first thing we need to do is to add a proper <uses-permission> tag in the manifest file with the name android.permission.WAKE_LOCK. This will allow us to use the WakeLock class.

We can get a WakeLock instance from the PowerManager like this:

PowerManager powerManager = (PowerManager)context.getSystemService(Context.POWER_SERVICE);
WakeLock wakeLock = powerManager.newWakeLock(PowerManager.FULL_WAKE_LOCK, "My Lock");

Like all other system services, we acquire the PowerManager from a Context instance. The PowerManager.newWakeLock() method takes two arguments: the type of the lock and a tag we can freely define. There are a couple of different wake lock types; for our purposes, the PowerManager.FULL_WAKE_LOCK type is the correct one. It will make sure that the screen will stay on, the CPU will work at full speed, and the keyboard will stay enabled.

To enable the wake lock, we have to call its acquire() method:

wakeLock.acquire();

The phone will be kept awake from this point on, no matter how much time passes without user interaction. When our application is paused or destroyed, we have to disable or release the wake lock again:

wakeLock.release();

Usually, we instantiate the WakeLock instance on the Activity.onCreate() method, call WakeLock.acquire() in the Activity.onResume() method, and call the WakeLock.release() method in the Activity.onPause() method. This way, we guarantee that our application still performs well in the case of being paused or resumed. Since there are only four lines of code to add, we’re not going to write a full-fledged example. Instead, we suggest you simply add the code to the full-screen example of the next section and observe the effects.

Going Full-Screen

Before we dive head first into drawing our first shapes with the Android APIs, let’s fix something else. Up until this point, all of our activities have shown their title bars. The notification bar was visible as well. We’d like to immerse our players a little bit more by getting rid of those. We can do that with two simple calls:

requestWindowFeature(Window.FEATURE_NO_TITLE);
getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN, WindowManager.LayoutParams.FLAG_FULLSCREEN);

The first call gets rid of the activity’s title bar. To make the activity go full-screen and thus eliminate the notification bar as well, we call the second method. Note that we have to call these methods before we set the content view of our activity.

Listing 4-11 shows a very simple test activity that demonstrates how to go full-screen.

Listing 4-11.  FullScreenTest.java; Making Our Activity Go Full-Screen

package com.badlogic.androidgames;

import android.os.Bundle;
import android.view.Window;
import android.view.WindowManager;

public class FullScreenTest extends SingleTouchTest {

    @Override
    public void onCreate(Bundle savedInstanceState) {
        requestWindowFeature(Window.FEATURE_NO_TITLE);
        getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN,
                WindowManager.LayoutParams.FLAG_FULLSCREEN);
        super .onCreate(savedInstanceState);
    }
}

What’s happening here? We simply derive from the TouchTest class we created earlier and override the onCreate() method. In the onCreate() method, we enable full-screen mode and then call the onCreate() method of the superclass (in this case, the TouchTest activity), which will set up all the rest of the activity. Note again that we have to call those two methods before we set the content view. Hence, the superclass onCreate() method is called after we execute these two methods.

We also fixed the orientation of the activity to portrait mode in the manifest file. You didn’t forget to add <activity> elements in the manifest file for each test we wrote, right? From now on, we’ll always fix it to either portrait mode or landscape mode, since we don’t want a changing coordinate system all the time.

By deriving from TouchTest, we have a fully working example that we can now use to explore the coordinate system in which we are going to draw. The activity will show you the coordinates where you touch the screen, as in the old TouchTest example. The difference this time is that we are full-screen, which means that the maximum coordinates of our touch events are equal to the screen resolution (minus one in each dimension, as we start at [0,0]). For a Nexus One, the coordinate system would span the coordinates (0,0) to (479,799) in portrait mode (for a total of 480×800 pixels).

While it may seem that the screen is redrawn continuously, it actually is not. Remember from our TouchTest class that we update the TextView every time a touch event is processed. This, in turn, makes the TextView redraw itself. If we don’t touch the screen, the TextView will not redraw itself. For a game, we need to be able to redraw the screen as often as possible, preferably within our main loop thread. We’ll start off easy, and begin with continuous rendering in the UI thread.

Continuous Rendering in the UI Thread

All we’ve done up until now is set the text of a TextView when needed. The actual rendering has been performed by the TextView itself. Let’s create our own custom View whose sole purpose is to let us draw stuff to the screen. We also want it to redraw itself as often as possible, and we want a simple way to perform our own drawing in that mysterious redraw method.

Although this may sound complicated, in reality Android makes it really easy for us to create such a thing. All we have to do is create a class that derives from the View class, and override a method called View.onDraw(). This method is called by the Android system every time it needs our View to redraw itself. Here’s what that could look like:

class RenderView extends View {
    public RenderView(Context context) {
        super (context);
    }

    protected void onDraw(Canvas canvas) {
        // to be implemented
    }
}

Not exactly rocket science, is it? We get an instance of a class called Canvas passed to the onDraw() method. This will be our workhorse in the following sections. It lets us draw shapes and bitmaps to either another bitmap or a View (or a Surface, which we’ll talk about in a bit).

We can use this RenderView as we’d use a TextView. We just set it as the content view of our activity and hook up any input listeners we need. However, it’s not all that useful yet, for two reasons: it doesn’t actually draw anything, and even if it were able to draw something, it would only do so when the activity needed to be redrawn (that is, when it is created or resumed, or when a dialog that overlaps it becomes invisible). How can we make it redraw itself?

Easy, like this:

protected void onDraw(Canvas canvas) {
    // all drawing goes here
    invalidate();
}

The call to the View.invalidate() method at the end of onDraw() will tell the Android system to redraw the RenderView as soon as it finds time to do that again. All of this still happens on the UI thread, which is a bit of a lazy horse. However, we actually have continuous rendering with the onDraw() method, albeit relatively slow continuous rendering. We’ll fix that later; for now, it suffices for our needs.

So, let’s get back to the mysterious Canvas class. It is a pretty powerful class that wraps a custom low-level graphics library called Skia, specifically tailored to perform 2D rendering on the CPU. The Canvas class provides us with many drawing methods for various shapes, bitmaps, and even text.

Where do the draw methods draw to? That depends. A Canvas can render to a Bitmap instance; Bitmap is another class provided by the Android’s 2D API, which we’ll look into later in this chapter. In this case, it is drawing to the area on the screen that the View is taking up. Of course, this is an insane oversimplification. Under the hood, it will not draw directly to the screen, but rather to some sort of bitmap that the system will later use in combination with the bitmaps of all other Views of the activity to composite the final output image. That image will then be handed over to the GPU, which will display it on the screen through another set of mysterious paths.

We don’t really need to care about the details. From our perspective, our View seems to stretch over the whole screen, so it may as well be drawing to the framebuffer of the system. For the rest of this discussion, we’ll pretend that we directly draw to the framebuffer, with the system doing all the nifty things like vertical retrace and double-buffering for us.

The onDraw() method will be called as often as the system permits. For us, it is very similar to the body of our theoretical game main loop. If we were to implement a game with this method, we’d place all our game logic into this method. We won’t do that for various reasons, performance being one of them.

So let’s do something interesting. Every time you get access to a new drawing API, write a little test that checks if the screen is really redrawn frequently. It’s sort of a poor man’s light show. All you need to do in each call to the redraw method is to fill the screen with a new random color. That way you only need to find the method of that API that allows you to fill the screen, without needing to know a lot about the nitty-gritty details. Let’s write such a test with our own custom RenderView implementation.

The method of the Canvas to fill its rendering target with a specific color is called Canvas.drawRGB():

Canvas.drawRGB(int r, int g, int b);

The r, g, and b arguments each stand for one component of the color that we will use to fill the “screen.” Each of them has to be in the range 0 to 255, so we actually specify a color in the RGB888 format here. If you don’t remember the details regarding colors, take a look at the “Encoding Colors Digitally” section of Chapter 3 again, as we’ll be using that info throughout the rest of this chapter.

Listing 4-12 shows the code for our little light show.

Listing 4-12.  The RenderViewTest Activity

package com.badlogic.androidgames;

import java.util.Random;

import android.app.Activity;
import android.content.Context;
import android.graphics.Canvas;
import android.os.Bundle;
import android.view.View;
import android.view.Window;
import android.view.WindowManager;

public class RenderViewTest extends Activity {
    class RenderView extends View {
        Random rand = new Random();

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

        protected void onDraw(Canvas canvas) {
            canvas.drawRGB(rand.nextInt(256), rand.nextInt(256),
                    rand.nextInt(256));
            invalidate();
        }
    }

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super .onCreate(savedInstanceState);
        requestWindowFeature(Window.FEATURE_NO_TITLE);
        getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN,
                WindowManager.LayoutParams.FLAG_FULLSCREEN);
        setContentView(new RenderView(this ));
    }
}

For our first graphics demo, this is pretty concise. We define the RenderView class as an inner class of the RenderViewTest activity. The RenderView class derives from the View class, as discussed earlier, and has a mandatory constructor as well as the overridden onDraw() method. It also has an instance of the Random class as a member; we’ll use that to generate our random colors.

The onDraw() method is dead simple. We first tell the Canvas to fill the whole view with a random color. For each color component, we simply specify a random number between 0 and 255 (Random.nextInt() is exclusive). After that, we tell the system that we want the onDraw() method to be called again as soon as possible.

The onCreate() method of the activity enables full-screen mode and sets an instance of our RenderView class as the content view. To keep the example short, we’re leaving out the wake lock for now.

Taking a screenshot of this example is a little bit pointless. All it does is fill the screen with a random color as fast as the system allows on the UI thread. It’s nothing to write home about. Let’s do something more interesting instead: draw some shapes.

Getting the Screen Resolution (and Coordinate Systems)

In Chapter 2, we talked a lot about the framebuffer and its properties. Remember that a framebuffer holds the colors of the pixels that get displayed on the screen. The number of pixels available to us is defined by the screen resolution, which is given by its width and height in pixels.

Now, with our custom View implementation, we don’t actually render directly to the framebuffer. However, since our View spans the complete screen, we can pretend it does. In order to know where we can render our game elements, we need to know how many pixels there are on the x axis and y axis, or the width and height of the screen.

The Canvas class has two methods that provide us with that information:

int width = canvas.getWidth();
int height = canvas.getHeight();

This returns the width and height in pixels of the target to which the Canvas renders. Note that, depending on the orientation of our activity, the width might be smaller or larger than the height. An HTC Thunderbolt, for example, has a resolution of 480×800 pixels in portrait mode, so the Canvas.getWidth() method would return 480 and the Canvas.getHeight() method would return 800. In landscape mode, the two values are simply swapped: Canvas.getWidth() would return 800 and Canvas.getHeight() would return 480.

The second piece of information we need to know is the organization of the coordinate system to which we render. First of all, only integer pixel coordinates make sense (there is a concept called subpixels, but we will ignore it). We also already know that the origin of that coordinate system at (0,0) is always at the top-left corner of the display, in both portrait mode and landscape mode. The positive x axis is always pointing to the right, and the y axis is always pointing downward. Figure 4-12 shows a hypothetical screen with a resolution of 48×32 pixels, in landscape mode.

Note how the origin of the coordinate system in Figure 4-12 coincides with the top-left pixel of the screen. The bottom-left pixel of the screen is thus not at (48,32) as we’d expect, but at (47,31). In general, (width – 1, height – 1) is always the position of the bottom-right pixel of the screen.

Figure 4-12 shows a hypothetical screen coordinate system in landscape mode. By now you should be able to imagine how the coordinate system would look in portrait mode.

All of the drawing methods of Canvas operate within this type of coordinate system. Usually, we can address many more pixels than we can in our 48×32-pixel example (e.g., 800×480). That said, let’s finally draw some pixels, lines, circles, and rectangles.

Drawing Simple Shapes

Deep into Chapter 4, and we are finally on our way to drawing our first pixel. We’ll quickly go over some of the drawing methods provided to us by the Canvas class.

Canvas.drawPoint(float x, float y, Paint paint);

Paint paint = new Paint();
paint.setARGB(alpha, red, green, blue);

Paint.setColor(0xff00ff00);

Canvas.drawLine(float startX, float startY, float stopX, float stopY, Paint paint);

Paint.setStrokeWidth(float widthInPixels);

Canvas.drawRect(float topleftX, float topleftY, float bottomRightX, float bottomRightY, Paint paint);

Paint.setStyle(Style style);

Canvas.drawCircle(float centerX, float centerY, float radius, Paint paint);

package com.badlogic.androidgames;

import android.app.Activity;
import android.content.Context;
import android.graphics.Canvas;
import android.graphics.Color;
import android.graphics.Paint;
import android.graphics.Paint.Style;
import android.os.Bundle;
import android.view.View;
import android.view.Window;
import android.view.WindowManager;

public class ShapeTest extends Activity {
    class RenderView extends View {
        Paint paint;
        public RenderView(Context context) {
            super (context);
            paint = new Paint();
        }
        protected void onDraw(Canvas canvas) {
            canvas.drawRGB(255, 255, 255);
            paint.setColor(Color.RED);
            canvas.drawLine(0, 0, canvas.getWidth()-1, canvas.getHeight()-1, paint);
            paint.setStyle(Style.STROKE);
            paint.setColor(0xff00ff00);
            canvas.drawCircle(canvas.getWidth() / 2, canvas.getHeight() / 2, 40, paint);
            paint.setStyle(Style.FILL);
            paint.setColor(0x770000ff);
            canvas.drawRect(100, 100, 200, 200, paint);
            invalidate();
        }
    }
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super .onCreate(savedInstanceState);
        requestWindowFeature(Window.FEATURE_NO_TITLE);
        getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN,
                             WindowManager.LayoutParams.FLAG_FULLSCREEN);
        setContentView(new RenderView(this ));
    }
}

Using Bitmaps

While making a game with basic shapes such as lines or circles is a possibility, it’s not exactly sexy. We want an awesome artist to create sprites and backgrounds and all that jazz for us, which we can then load from PNG or JPEG files. Doing this on Android is extremely easy.

InputStream inputStream = assetManager.open("bob.png");
Bitmap bitmap = BitmapFactory.decodeStream(inputStream);

int width = bitmap.getWidth();
int height = bitmap.getHeight();

Bitmap.Config config = bitmap.getConfig();

InputStream inputStream = assetManager.open("bob.png");
BitmapFactory.Options options = new BitmapFactory.Options();
options.inPreferredConfig = Bitmap.Config.ARGB_4444;
Bitmap bitmap = BitmapFactory.decodeStream(inputStream, null , options);

Bitmap bitmap = Bitmap.createBitmap(int width, int height, Bitmap.Config config);

Canvas canvas = new Canvas(bitmap);

Bitmap.recycle();

Canvas.drawBitmap(Bitmap bitmap, float topLeftX, float topLeftY, Paint paint);

Canvas.drawBitmap(Bitmap bitmap, Rect src, Rect dst, Paint paint);

package com.badlogic.androidgames;

import java.io.IOException;
import java.io.InputStream;

import android.app.Activity;
import android.content.Context;
import android.content.res.AssetManager;
import android.graphics.Bitmap;
import android.graphics.BitmapFactory;
import android.graphics.Canvas;
import android.graphics.Rect;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.view.Window;
import android.view.WindowManager;

public class BitmapTest extends Activity {
    class RenderView extends View {
        Bitmap bob565;
        Bitmap bob4444;
        Rect dst = new Rect();
        public RenderView(Context context) {
            super (context);

            try {
                AssetManager assetManager = context.getAssets();
                InputStream inputStream = assetManager.open("bobrgb888.png");
                bob565 = BitmapFactory.decodeStream(inputStream);
                inputStream.close();
                Log.d("BitmapText",
                        "bobrgb888.png format: " + bob565.getConfig());

                inputStream = assetManager.open("bobargb8888.png");
                BitmapFactory.Options options = new BitmapFactory.Options();
                options.inPreferredConfig = Bitmap.Config.ARGB_4444;
                bob4444 = BitmapFactory
                        .decodeStream(inputStream, null , options);
                inputStream.close();
                Log.d("BitmapText",
                        "bobargb8888.png format: " + bob4444.getConfig());

            }catch (IOException e) {
                // silently ignored, bad coder monkey, baaad!
            }finally {
                // we should really close our input streams here.
            }
        }

        protected void onDraw(Canvas canvas) {
            canvas.drawRGB(0, 0, 0);
            dst.set(50, 50, 350, 350);
            canvas.drawBitmap(bob565, null , dst, null );
            canvas.drawBitmap(bob4444, 100, 100, null );
            invalidate();
        }
    }

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super .onCreate(savedInstanceState);
        requestWindowFeature(Window.FEATURE_NO_TITLE);
        getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN,
                WindowManager.LayoutParams.FLAG_FULLSCREEN);
        setContentView(new RenderView(this ));
    }
}

Rendering Text

While the text we’ll output in the Mr. Nom game will be drawn by hand, it doesn’t hurt to know how to draw text via TrueType fonts. Let’s start by loading a custom TrueType font file from the assets/ directory.

Typeface font = Typeface.createFromAsset(context.getAssets(), "font.ttf");

paint.setTypeFace(font);

paint.setTextSize(30);

canvas.drawText("This is a test!", 100, 100, paint);

Paint.setTextAlign(Paint.Align align);

Paint.getTextBounds(String text, int start, int end, Rect bounds);

package com.badlogic.androidgames;

import android.app.Activity;
import android.content.Context;
import android.graphics.Canvas;
import android.graphics.Color;
import android.graphics.Paint;
import android.graphics.Rect;
import android.graphics.Typeface;
import android.os.Bundle;
import android.view.View;
import android.view.Window;
import android.view.WindowManager;

public class FontTest extends Activity {
    class RenderView extends View {
        Paint paint;
        Typeface font;
        Rect bounds = new Rect();

        public RenderView(Context context) {
            super (context);
            paint = new Paint();
            font = Typeface.createFromAsset(context.getAssets(), "font.ttf");
        }

        protected void onDraw(Canvas canvas) {
            canvas.drawRGB(0, 0, 0);
            paint.setColor(Color.YELLOW);
            paint.setTypeface(font);
            paint.setTextSize(28);
            paint.setTextAlign(Paint.Align.CENTER);
            canvas.drawText("This is a test!", canvas.getWidth() / 2, 100,
                    paint);

            String text = "This is another test o_O";
            paint.setColor(Color.WHITE);
            paint.setTextSize(18);
            paint.setTextAlign(Paint.Align.LEFT);
            paint.getTextBounds(text, 0, text.length(), bounds);
            canvas.drawText(text, canvas.getWidth() - bounds.width(), 140,
                    paint);
            invalidate();
        }
    }

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super .onCreate(savedInstanceState);
        requestWindowFeature(Window.FEATURE_NO_TITLE);
        getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN,
                WindowManager.LayoutParams.FLAG_FULLSCREEN);
        setContentView(new RenderView(this ));
    }
}

Continuous Rendering with SurfaceView

This is the section where we become real men and women. It involves threading, and all the pain that is associated with it. We’ll get through it alive. We promise!

SurfaceHolder holder = surfaceView.getHolder();

Canvas SurfaceHolder.lockCanvas();
SurfaceHolder.unlockAndPost(Canvas canvas);

boolean isCreated = surfaceHolder.getSurface().isValid();

package com.badlogic.androidgames;

import android.app.Activity;
import android.content.Context;
import android.graphics.Canvas;
import android.os.Bundle;
import android.view.SurfaceHolder;
import android.view.SurfaceView;
import android.view.Window;
import android.view.WindowManager;

public class SurfaceViewTest extends Activity {
    FastRenderView renderView;
    public void onCreate(Bundle savedInstanceState) {
        super .onCreate(savedInstanceState);
        requestWindowFeature(Window.FEATURE_NO_TITLE);
        getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN,
                             WindowManager.LayoutParams.FLAG_FULLSCREEN);
        renderView = new FastRenderView(this );
        setContentView(renderView);
    }
    protected void onResume() {
        super .onResume();
        renderView.resume();
    }
    protected void onPause() {
        super .onPause();
        renderView.pause();
    }
    class FastRenderView extends SurfaceViewimplements Runnable {
        Thread renderThread = null ;
        SurfaceHolder holder;
        volatile boolean running = false ;
        public FastRenderView(Context context) {
            super (context);
            holder = getHolder();
        }

        public void resume() {
            running = true ;
            renderThread = new Thread(this );
            renderThread.start();
        }
        public void run() {
            while (running) {
                if (!holder.getSurface().isValid())
                    continue ;
                Canvas canvas = holder.lockCanvas();
                canvas.drawRGB(255, 0, 0);
                holder.unlockCanvasAndPost(canvas);
            }
        }

        public void pause() {
            running = false ;
            while (true ) {
                try {
                    renderThread.join();
                    return ;
                }catch (InterruptedException e) {
                    // retry
                }
            }
        }
    }
}

Hardware-Accelerated Rendering with Canvas

Android 3.0 (Honeycomb) added a remarkable feature in the form of the ability to enable GPU hardware acceleration for standard 2D canvas draw calls. The value of this feature varies by application and device, as some devices will actually perform better doing 2D draws on the CPU and others will benefit from the GPU. Under the hood, the hardware acceleration analyzes the draw calls and converts them into OpenGL. For example, if we specify that a line should be drawn from 0,0 to 100,100, then the hardware acceleration will put together a special line-draw call using OpenGL and draw this to a hardware buffer that later gets composited to the screen.

Enabling this hardware acceleration is as simple as adding the following into your AndroidManifest.xml under the <application /> tag:

android:hardwareAccelerated="true"

Make sure to test your game with the acceleration turned on and off on a variety of devices, to determine if it’s right for you. In the future, it may be fine to have it always on, but as with anything, we recommend that you take the approach of testing and determining this for yourself . Of course, there are more configuration options that let you set the hardware acceleration for a specific application, activity, window, or view, but since we’re doing games, we only plan on having one of each, so setting it globally via application would make the most sense.

The developer of this feature of Android, Romain Guy, has a very detailed blog article about the dos and don’ts of hardware acceleration and some general guidelines to getting decent performance using it. The blog entry’s URL is http://android-developers.blogspot.com/2011/03/android-30-hardware-acceleration.html