Android 3.0 Application Development Cookbook

As with most recipes, we will be using the Eclipse IDE. If you have not done so already, start up Eclipse and ensure that you have installed the ADT Plugin.

Android projects are built against a target platform or API level. Here we have used API level 8, which corresponds to the Android 2.2 platform (FroYo). It is quite possible to use any level for this task but if you intend to make use of the 'holographic' UI you will need to look at the recipe about optimizing for 3.0 in Chapter 2, Layouts.

The Eclipse Android project wizard is as good a place to start building an application as any and it will automatically generate a manifest file that includes a basic activity declaration:

An activity represents a single task that the user can perform, such as editing some text or selecting a media file from a list. Each of our activities must be declared in the AndroidManifest XML file, which resides in the root directory of the project.

The project wizard provides us with two basic attributes:

We also added an attribute of our own, screenOrientation, which does exactly what you might expect it to.

The manifest is used to control an activity's start-up state and to apply features such as themes, or as just demonstrated, screen orientation. As we will see later though, most attributes can be set and changed dynamically through Java code as well.

To keep things simple, we are going to use an intent object to start one of Android's built-in activities, rather than create a new one. This only requires a very basic application, so start a new Android project with Eclipse and call it ActivityStarter or something like that.

We are going to edit the Java subclass responsible for the main activity: the one declared in the manifest file. This class extends the activity class, and by overriding its onCreate() method we can introduce code that will be executed when the application is first launched:

Intents operate as asynchronous messages sent between application components and they are used to activate services and broadcast receivers as well as activities. Intents are passive data structures that provide an infrastructure for our activities and other components.

The onCreate() method is called as soon as the activity starts and so calling our startActivity() method from within it means that we are immediately taken to the call log activity. More often than not we would use a button or menu item to perform such an action, and we haven't done so in order to simplify the demonstration and make it easier to incorporate in your own application.

Again, note that this project was built against Android 2.2 (API level 8) but this choice was arbitrary as the libraries used have been available since Android 1.5 and you should, ideally, build against the target device that you are testing on.

The previous example required only an action to be set but most intent objects make use of a setData() method as well as the setAction() method used.

myIntent.setAction(Intent.ACTION_VIEW);
myIntent.setData(android.provider.MediaStore.Images.Media.INTERNAL_CONTENT_URI);

Exploring other functions with auto-complete

Eclipse's auto-complete function allows us to explore Android's other baked-in activities. Simply start entering the code here and then scroll through the lists presented:

If the drop-down list fails to appear, press Ctrl + Space but note that when components share methods you may well see actions that correspond to other classes such as services or broadcasts, although the inline documentation is quite thorough and will mention when specific data or extra parameters are required.

To start an activity from a menu selection, see the recipe Handling menu selections in Chapter 4, Menus.

This recipe can be started from scratch, so create a new Android project in Eclipse and call it ActivitySwitcher. Creating a project with the wizard automatically generates the first of our activities. This example can be built against any platform target and here we have used 2.2 (API level 8).

First we create a new public class that we will use to create the second activity:

This new activity is not a very exciting application. Our activity does nothing but demonstrate how to switch from one activity to another, which of course will form a fundamental aspect of almost any application that we develop.

In most cases there would be a separate layout declaration alongside main.xml in the res/layout folder for each new activity. Also a button, or some other object, to return us to our original activity would be quite reasonable but these features have been omitted here simply to save us the extra typing, and of course, the user can always use the device's own Back button to achieve this.

We have seen how to create a new subclass for each new activity and how to declare these in the manifest. We have also seen how a UI element such as a button is declared in an XML file, main.xml, and then associated with a data member in Java with the findViewById() method.

Again we have made use of the intent object, not only to start the new activity but also to specify which activity class to run.

To learn more about embedding widgets like the Button, see Chapter 3, Widgets.

Returning a result from an activity is not that different from calling one the way we did in the previous recipe. Start up a new Android project in Eclipse and call it GettingResults.

In this recipe we will need to create a new activity class, provide it with an onCreate() method, then edit our default class and include our new activity in the manifest file:

Here, the called activity used setResult() to return a result code back to the calling activity. We used an arbitrary value in our example but a result code can be used to represent an outcome such as the index of a selected item.

The corresponding member in the calling activity is the onActivityResults() method. Besides the result code that we just sent from the called activity, the method receives a request code. This is simply the integer value that was passed with the startActivityForResult() call which takes the form:

startActivityForResult(Intent intent, int requestCode);

We used 0 as our request code because we knew where it came from—but this value can be used to identify where the request originated in less trivial applications with several activities.

Activity results are always handled by the calling activity's onActivityResults() method, which makes use of the request code as well as the result code.

We made use of the Toast object which is a neat little pop-up view that can be used to unobtrusively inform the user of some event or the other. It also functions as a handy little tool for on-the-fly debugging as it doesn't need setting up or screen estate.

In the previous example, we only returned an integer with setResult() but there is an alternative format.

setResult(int resultCode, Intent data);

Intent i = new Intent();
setResult(42, i);

finish();

To learn more about creating new activity classes refer to the previous recipe, Switching between activities.

For more information on Toasts see the recipe Making a Toast in Chapter 7, Notifying the user.

Our recipes get a little more involved from here on and so we will not be able to include all the code in the given examples. We will assume that the reader is familiar with the subjects covered in the past few recipes and will be able to create applications with the necessary elements without recourse to the exact text. If not, have a quick look through the preceding recipes. We will not introduce any new subjects without fully explaining them.

In this recipe we will create a simple application that 'remembers' a line of text that we enter when the activity is reloaded. To do this we override the activity's onSaveInstanceState() and onRestoreInstanceState() methods:

The way these state saving methods work is really quite simple. When our application is dropped from memory, a Bundle of name/value pairs can be stored with the onSaveInstanceState() method. This Bundle is then handed back when the activity restarts to both the onRestoreInstanceState() and the onCreate() methods. This is an important point as the Bundle is made available to both procedures and gives us a choice over where and how to handle activity restarts. This is because onRestoreInstanceState() is not called until after onStart() meaning we can apply any initialization that we may need before restoring our values.

The two methods introduced here are not the only way to ensure that a screen component's state is stored.

Internal memory can also be used to store other private data and details on how to do this can be found in the recipe Using internal storage for private data in Chapter 5, Data and Security.

The recipe Storing public data on external storage in Chapter 5, Data and Security demonstrates how to use SD cards to store data available from outside an application.

It is possible to use SharedPreferences in any activity (as well as other application components). The example we use here makes use of a TextView, an EditText, and a Button to permanently store the user's name:

In this recipe the persistent data that we want to store is a string value used to represent the user's name. We will store this during the activity's onPause() method and restore the value in the onCreate() method (as they are called when we most likely need to restore and retrieve our preferences) but SharedPreferences can be applied anywhere:

We stored just one value here, the string KEY, but we could have stored any number of primitive name/value pairs. Each data type has equivalent getters and setters, for example SharedPreferences.getBoolean() or SharedPreferences.setInt().

When we retrieve the value, in the onCreate() method we provided a string literal "new user". This will be used in the absence of a stored value when the file has not yet been saved and is very useful for handling first-run events.

The saving of our preferences requires the services of the SharedPreferences.Editor. This is evoked with edit() and accepts remove() and clear() procedures as well as setters like the putString() one we used. Note that we must conclude any storing we do here with the commit() statement.

There is a slightly more sophisticated variant of the getPreferences() accessor, getSharedPreferences(), which can be used for storing multiple preference sets.

getSharedPreferences(String name, int mode)

To store more complex data, see the recipe Creating an SQLite database in Chapter 5, Data and Security.

Android supplies a series of callbacks that are executed at each stage of the activity lifecycle and can be overridden, enabling us to anticipate user actions and execute code when the state of an activity changes.

To prepare for this exercise, start up a new Android project in Eclipse.

We are going to record each lifecycle state with a persistent TextView whenever any of the activity's callbacks are executed:

Take a look at the next diagram. Our activity can exist in one of three states: active, paused, or stopped. There is also a fourth state, destroyed, but we can safely ignore it:

An activity is in the active state when its interface is available to the user. It persists from onResume() until onPause() which is brought about when another activity is pushed onto the stack. If this new activity does not entirely obscure ours, then ours will remain in the paused state until the new activity is finished or dismissed. It will then immediately call onResume() and continue.

When a newly started activity fills the screen or makes our activity otherwise invisible then our activity will enter the stopped state and resumption will always invoke a call to onRestart().

When an activity is in either the paused or stopped state, the operating system can (and will) remove it from memory when memory is low or when other applications demand it.

It is worth noting that we never actually see the results of the onDestroy() method, as by this point the activity has been removed. If you want to explore these methods further then it is well worth employing Activity.isFinishing() to see if the activity is really finishing before onDestroy() is executed, as seen in the following snippet:

@Override
  public void onPause() {
  super.onPause();

  mTextView.append("\n pausing");

  if (isFinishing()){
    mTextView.append(" ... finishing");  
  }

}

Despite the effort that we have had to put into preventing Android from shutting down our components prematurely, there are times when we want to deliberately exit an activity. Despite Android's robust approach to resource management it will not wipe our application if there is no demand or if memory is readily available. Although an activity that persists in this way is unlikely to have much of a negative impact, the user will most likely not see it that way and blame our application for draining their battery.