Explicit intents use the component portion of the Intent object via the ComponentName data field. You'll generally use these when working with applications you have developed, as you'll know which packages and classes are appropriate for the Intent object to send an action message and data to be acted on. Because the component is specified explicitly, this type of intent is also safer as there is zero room for error in interpretation. Best programming practices dictate that you thoroughly document your code and thereby give other programmers using your intent code the proper component name information. However in the real world, this best case does not always happen and thus Android also has implicit intents and intent filters to handle other scenarios.

Other developers may not know what components to explicitly declare when working with your application, and thus explicit intents are a better fit for non-public inter-application communication. In fact, developing your application so that other developers can use the intents is what implicit intents and intent filters are all about. As noted earlier, if there is a component name specified, it will override all of the other parts of the Intent object as far as determining what code will handle the intent resolution.

There are two ways to specify a component. One way is via the setComponent() method, which uses the ComponentName object:

.setComponent(ComponentName);

The other way is using the setClass(Context, Class) method to provide the exact class to use to process the intent. Sometimes this is the only information in the intent, especially if the desired result from using the intent is simply to launch parallel activities that are internal to the application when they are needed by the user.

Implicit intents are those that don't specify the component within the intent object. This means that Android has to infer from the other parameters in the intent object what code it needs to pass the intent message to for successful processing.

Android does this inference based on a comparison of the various actions, data, and categories defined in the intent object with the code components that are available to process the intent. This is usually done via intent filters that are defined in the AndroidManifest.xml file.

Although designing classes that utilize implicit intents and intent filters is beyond the scope of an introductory book on Android programming, we will go over the concept here just to give you an idea of what can be done in Android and in what situations you would use implicit intents and intent filters. You can find more information at

developer.android.com/reference/android/content/IntentFilter.html.

Intent filters are declared in AndroidManifest.xml using the <intent-filter> tag, and they filter based on three of the seven attributes of the Intent object; action, data, and category.

Intent filters provide a description of intent object structures that need to be matched as well as a priority attribute to be used if more than one match is encountered. If no action filters are specified, the action parameter of the intent will not be tested at all, moving the testing on to the data parameter of the intent. If no data filters are specified, then only intents that contain no data will be matched. Here is an example intent-filter definition from an AndroidManifest.xml file that specifies that video MPEG4 and audio MPEG3 can be retrieved from the internet via HTTP:

<intent-filter>
<data android:mimeType="video/mp4" android:scheme="http" />
<data android:mimeType="audio/mp3" android:scheme="http" />
</intent-filter>

For Intent filtering based on data characteristics, the data parameter gets broken down into four subcategories:

Any of these you specify will be matched precisely to the content of the intent itself, for example:

content://com.apress.project:300/datafolder/files/file1

In this example, the scheme is content, the host is com.apress.project, the port is 300, and the path is datafolder/files/file1.

Since we can specify intents explicitly, we can use intent objects productively via the methodologies outlined in the rest of this chapter without having to learn the convoluted hierarchy of how to match unspecified intents. If you wish to delve into the complexities of how to set up levels of intent filters for implicit intent matching, visit the Android developer site and get ready to wrap your mind around some intense global logic structures.

Now let's copy the user interface we just developed in our main.xml to use for our second activity, which we've already created a DigitalClockActivity.java class for.

When you're done, the whole UI layout should look like this (also shown in Figure 11-5):

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent">

    <TextView    android:layout_width="fill_parent"
                 android:layout_height="wrap_content"
                 android:text="You Are Currently in: Activity #2"
                 android:textColor="#adf"
                 android:textSize="22dip"
                 android:paddingBottom="30dip"/>

    <Button android:id="@+id/Button01"
            android:text="Go to Analog Watch: Activity #1"
            android:textSize="18px"
            android:layout_width="280px"
            android:layout_height="60px"
            android:layout_gravity="center"/>

    <DigitalClock    android:id="@+id/DigitalClock01"
                     android:layout_width="wrap_content"
                     android:layout_height="wrap_content"
                     android:layout_gravity="center"
                     android:layout_marginTop="30dip"
                     android:textSize="32dip"
                     android:textColor="#adf"
                     android:typeface="monospace"/>
</LinearLayout>

Figure 11.5. XML mark-up for the digital_clock.xml user interface activity

While we're working with XML files, let's add an activity tag in our AndroidManifest.xml file so our second activity can be recognized by Android, before finishing off the configuration.

Right-click on the AndroidManifest.xml file name under your Chapter11 folder (at the bottom of the list), and select Open or hit F3. Add a second activity tag after the first tag (which our New Android Project dialog has already created) that points to the new DigitalClockActivity.java class we created earlier (see Figure 11-6). Here is the code:

<activity android:name=".DigitalClockActivity"></activity>

Figure 11.6. Adding the DigitalClockActivity tag to our AndroidManifest.xml file

Now let's make sure both Activities have user interfaces. Thanks to our handy New Android Project dialog, our IntentExamples class is ready and pointing to the main.xml file so that the Activity #1 side of the equation is already taken care of. So all we have to worry about is the DigitalClockActivity class.

Copy the import android.os.Bundle statement and the onCreate() method over to the DigitalClockActivity.java class and change the R.layout specification to point to the digital_clock XML user interface specification. Now we've implemented our user interface logic for each of our two Activity classes as follows (and as shown in Figure 11-7):

public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.digital_clock);
    }

Figure 11.7. Adding the digital clock user interface layout

Now we need to add in our Button object and Intent object code to the onClick() event handler in each activity so each can send an intent to the other activity, allowing us to switch between the two activities using the button.

So let's get started with the main IntentExamples activity class first, and add in our familiar Button object instantiation and an onClick() event handler that will contain the code that creates our Intent object. Remember to also add in (or have Eclipse add in for you using the hover-over-redline method we learned earlier) the import statements for the android.view.View and android.widget.Button packages, as well as a new import we haven't used before called android.contact.Intent, which defines our Intent object class.

Since we've already covered adding a button and attaching it to an onClick() event handler routine, we'll get right into the two lines of code that create our Intent object and send it over to the second activity. Here is the code, which you'll also see in Figure 11-8. The screenshot shows what your Eclipse editor pane for IntentExamples.java will look like when we are finished.

Button Activity1 = (Button) findViewById(R.id.Button01);
        Activity1.setOnClickListener(new View.OnClickListener() {
            public void onClick(View view) {
                Intent myIntent =
                  new Intent(view.getContext(), DigitalClockActivity.class);
                startActivityForResult(myIntent, 0);
            }
        });

Figure 11.8. Adding the Java code for the UI button, event listener, and Intent object

To create an Intent object, we use the now familiar structure where we declare the object type (Intent) and our name for it (myIntent). We set it equal to a new Intent object using the new keyword, along with a call to the Intent class's constructor. The constructor takes the context this intent is created in (in this case, a button obtained from the View via a view.getContext() method call) and the activity class (DigitalClockActivity.class) into which we want to pass our Intent object.

We then use the startActivityForResult() method (part of the android.content.Intent class we imported) to pass the intent object we just created, myIntent, and a parameter of zero; this is what we are sending to the other activity to be acted on. This would typically consist of data that your application wants to pass from one activity class to another via the Intent object for further processing. In this case, we are simply calling (switching to) the other user interface activity.

Now let's look at the code in our DigitalClockActivity class and see how the second activity talks back to the first activity. We will skip over the Button instantiation and onClick() event handling explanations, and get right into the intent declaration and the Java code that returns a result to the calling activity class via yet another Intent object. Here's the code (also shown in Figure 11-9).

Button activity2 = (Button) findViewById(R.id.Button01);
        activity2.setOnClickListener(new View.OnClickListener() {
            public void onClick(View view) {
                Intent replyIntent = new Intent();
                setResult(RESULT_OK, replyIntent);
                finish();
            }
        });

Figure 11.9. Java Code for the DigitalClockActivity, event listener, and intent object

In this activity class, in the onClick() listener we create a new (empty) intent object called replyIntent, then load it with the setResult() method, which loads a constant called RESULT_OK. When we have finished handling the intent (in this case by loading a new intent with the reply data), we call the finish() method to send the intent back, after the button in the second activity is clicked on to send us back to the first activity.

Now let's right-click on our Chapter11 folder and then Run As

Figure 11.10. Running our app in the Android 1.5 emulator and switching back and forth between activities

Next we will use an intent object to call a service, the MediaPlayer, to play some music in the background and allow us to start the music and stop the music.

To do this we first must learn what services are and how they can help us do things in the background without affecting our application's user interface functionality. We will then get into an example that uses intents with both services and activities.

To see how to control a service class via intent objects, we will need to add some user interface elements to our Chapter11 IntentExamples activity, namely two button objects that will start and stop our service. In this case, the service is the Android MediaPlayer, which needs to run in the background, independently of our user interface elements.

Next we need to let our Android application know that we are going to be calling a service, and this is done via the AndroidManifest.xml file. We will edit that file next to add a service tag that points to our MediaPlayerService class, which we are going to code next. We will add this service tag right after the second activity tag we added in the previous example (see Figure 11-13 for context). This is how the service tag is structured:

<service android:enabled="true" android:name=".MediaPlayerService" />

The first attribute of the service tag android:enabled indicates that the service is enabled for use. If you set this attribute to false, the service is still declared to Android for the application and can later be enabled via Java code. As we have seen, everything that can be done in XML can also be accessed and changed in our Java code.

The second attribute, android:name, specifies the name of the service class that we will code. We are going to name it MediaPlayerService.java so we specify that in XML as .MediaPlayerService. Now we are ready to start coding the service that will play media files without interfering with the user interface code in our activity class.

Note that if you haven't created the MediaPlayerService.java class before you add the service tag, Eclipse may highlight this fact with a red X in the margin to the left of the service tag, as shown circled in Figure 11-13.

Figure 11.13. Adding a Media Player Service Tag to the AndroidManifest.xml file in Eclipse

Now that we've added the XML mark-up, let's create the MediaPlayerService.java class, extending the Android Service class to create our own custom service class that we'll call from our IntentExamples Activity class.

To do this, we will use the same work process as before:

The completed dialog is shown in Figure 11-14. It will create an empty class where we can put our media player logic for creating, starting, and stopping the media player.

Figure 11.14. Creating the MediaPlayerService.java class via the New Java Class dialog

Below (and in Figure 11-15) is the empty class that the NewJavaClass dialog created for us, complete with the import statements that let us use the Service class, the Intent class, and the IBinder interface. We won't actually be using the IBinder interface in this example but will leave in the code. This won't affect how the app runs because it is used by a null method, onBind(). We need to keep this method here because Android expects it to be implemented when we extend the Service class, but we'll just leave it as is.

package intent.filters;

import android.app.Service;
import android.content.Intent;
import android.os.IBinder;

public class MediaPlayerService extends Service {
    @Override
    public IBinder onBind(Intent intent) {
        // TODO Auto-generated method stub
        return null;
    }
}

Figure 11.15. Android-created MediaPlayerService base service class

Here is the code that lets our MediaPlayerService class do things. I'll show you each of the bold sections in turn as I describe what they do, so you can type them in as we go:

package intent.filters;

import android.app.Service;
import android.content.Intent;
import android.os.IBinder;
import android.media.MediaPlayer;

public class MediaPlayerService extends Service {
    MediaPlayer myMediaPlayer;

    @Override
    public IBinder onBind(Intent intent) {
        // TODO Auto-generated method stub
        return null;
    }

    @Override
    public void onCreate() {
        myMediaPlayer = MediaPlayer.create(this, R.raw.mindtaffy);
        myMediaPlayer.setLooping(true);
    }

@Override
    public void onStart(Intent intent, int startid) {
        myMediaPlayer.start();
    }

    @Override
    public void onDestroy() {
        myMediaPlayer.stop();
    }
}

The results are shown in Figure 11-16.

Figure 11.16. Adding our MediaPlayer onCreate, onStart and onStop methods

The first code structure we always add to a new class is the onCreate() method, which tells the class what to do to set itself up when it is called the first time (i.e., created).

We will use the onCreate() method to instantiate and configure our MediaPlayer object and load it with our audio file. Since the audio file is an MP3 file and already optimized for compression, we will put it in the /res/raw folder. Files in the /raw folder are left alone by the Android app compression process and are simply put into the .apk file as is. We'll do that now before explaining the code in detail.

Now it's time to go into the code so you can add the media player functionality to your own app:

Now let's go back into our IntentExamples.java class using the Eclipse editor tab and add our Button objects, associated onClick() event handlers for each button, and the necessary calls to our Service class onStart() and onDestroy() methods, as shown in Figure 11-17.

Figure 11.17. Implementing the start and stop buttons to control the media player

First we have the start button.

Button startButton = (Button) findViewById(R.id.startButton);
        startButton.setOnClickListener(new View.OnClickListener() {
            public void onClick(View view) {
                startService(new Intent(getBaseContext(), MediaPlayerService.class));
            }
        });

As usual, we declare our startButtonButton object with the startButton ID reference, then use the setOnClickListener() method to add onClick() event handling to the startButton. We are now ready to call the startService() method inside the onClick() programming construct.

startService() calls the onStart() method of the Service class we just wrote, and requires an intent object; this intent object tells Android what service to start and call the onStart() method on. We will get a little tricky here and create a new intent object inside of the startService() call using the following code structure:

startService(new Intent(getBaseContext(), MediaPlayerService.class));

To create a new intent object, we need to declare the current context as the first parameter and then pass the name of the service class we wish to call as the second parameter. In a third level of nesting (inside the new intent creation), we use another method called getBaseContext() to obtain the current context for the new intent object. As the second parameter, we will declare the name of the MediaPlayerService.class to complete the creation of a valid intent object.

Now let's go through the same procedure with the stopButtonButton object, inserting the stopButton ID reference and then using the trusty setOnClickListener() method to add onClick() event handling to our new stopButton. Now we're ready to call the stopService() method in our newest onClick() programming routine.

Button stopButton = (Button) findViewById(R.id.stopButton);
        stopButton.setOnClickListener(new View.OnClickListener() {
            public void onClick(View view) {
                stopService(new Intent(getBaseContext(), MediaPlayerService.class));
            }
        });

The stopService() method calls the onDestroy() method of our Service class and requires an intent object that tells Android what service to stop (destroy) and call the onDestroy() method on.

We will create yet another new intent object in the stopService() call, using the following code structure:

stopService(new Intent(getBaseContext(), MediaPlayerService.class));

To create our final intent object, we will declare the current context as our first parameter and then pass the name of our MediaPlayerService() class as our second parameter.

Now we are ready to right-click our Chapter11 folder and Run As

Figure 11.18. Running our media player service inside the Android 1.5 emulator

Next we are going to take a look at using Intent objects with broadcast receivers, and then we will have covered all three areas of Intent use within Android.

So, first, let's add an EditText tag so we can let users enter their own custom timer duration. Place the following markup in your digital_clock.xml file after the DigitalClock tag:

<EditText android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:id="@+id/timeInSeconds"
        android:layout_gravity="center"
        android:hint="Enter Number of Seconds Here!"
        android:inputType="numberDecimal"
        android:layout_marginTop="30dip"
        android:layout_marginBottom="30dip" />

The EditText tag has an ID of timeInSeconds and a layout gravity of center for consistency with our prior UI design. Since EditText is a new user interface object for us, we will add an android:hint attribute that says "Enter Number of Seconds Here!"

Next we have an important android:inputType attribute, which tells us what data type the field will contain, in this case a real number that is represented by the numberDecimal constant. The timer uses milliseconds, so if we want the timer to count 1534 milliseconds, we can type 1.534 in this field and achieve this precise result. Finally, we add two margin attributes (top and bottom) of 30dip each to space the user interface out and to make it more visually attractive to the end user.

We'll also add a Button tag called startTimer to, well, start the timer. Let's use an ID of startTimer and an android:text value of "Start Timer Countdown" to prompt the user. And we'll also use our familiar android:layout_gravity="center" to center our button, so that the UI remains consistent.

<Button android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_gravity="center"
        android:id="@+id/startTimer"
        android:text="Start Timer Countdown" />

Figure 11-20 shows how our digital_clock.xml file should look in the Eclipse IDE.

Figure 11.20. Adding our timer user interface elements to the digital_clock.xml file

Now let's create our TimerBroadcastReceiver class, which is a subclass of the BroadcastReceiver class.

Figure 11-21 shows what your New Java Class dialog should look like when you've entered all of the relevant new Java class information.

Figure 11.21. Creating a new TimerBroadcastReceiver class via the New Java Class dialog in Eclipse

Now we have an empty class shell with all of the import statements that we need for our BroadcastReceiver class and an empty onReceive() method for us to fill out with our programming logic. The onReceive()method will receive our intent and broadcast a message via the Toast class, which will notify us regarding the alarm status.

Let's add an import statement for the Toast widget so we can use it to broadcast a message to the user when the broadcast receiver is used. It is important to note that this Toast message could be replaced by anything we want to happen when our timer goes off, including but not limited to playing a song, playing a ringtone, vibrating the phone, playing a video, or anything else you can think of.

import android.widget.Toast;

The Toast widget's makeText() method can be coded as follows:

public void onReceive(Context context, Intent intent) {
        Toast.makeText(context, "Alarm Notification", Toast.LENGTH_LONG).show();
    }

We first pass the Toast widget the context parameter received along with the onReceive() call and then tell it what to write to the screen (our "Alarm Notification" string) and how long to show it on the screen (the LENGTH_LONG constant). We then append the show() method to makeText() to draw the message to the screen.

Figure 11-22 shows how all of this should look on the TimerBroadcastReceiver tab in the Eclipse IDE.

Figure 11.22. Our TimerBroadcastReceiver class

Now we need to declare our broadcast receiver using the receiver tag in our AndroidManifest.xml file so it is registered for use with Android. We will do this right after the service tag that we added in the previous section, entering the following line of XML mark-up code:

<receiver android:name=".TimerBroadcastReceiver" android:enabled="true" />

This is fairly straightforward. We use the name attribute to assign our TimerBroadcastReceiver class name to the receiver declaration tag and then enable it for use in our application by setting the android:enabled attribute to true so that the broadcast receiver is live (Figure 11-23).

Figure 11.23. Adding a <receiver> tag to our AndroidManifest.xml file

Now our broadcast receiver is set up to notify users via a Toast message when the broadcast receiver is utilized. The next thing we need to do is add the code to our DigitalClockActivity class to implement an alarm clock function that triggers this Broadcast Receiver class via an intent object, so we can see how all this works together.

The modifications to our DigitalClockActivity class will be done via several new import statements, an event handler for a click on our start timer countdown button, and the timerAlert() method that we will write to do all the heavy lifting to implement the new timer functionality to our application and to trigger our broadcast receiver class using intent objects.

Let's start with the onCreate() method:

public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.digital_clock);

        Button activity2 = (Button) findViewById(R.id.Button01);
        activity2.setOnClickListener(new View.OnClickListener() {
            public void onClick(View view) {
                Intent replyIntent = new Intent();
                setResult(RESULT_OK, replyIntent);
                finish();
            }
        });

        Button startTimer = (Button) findViewById(R.id.startTimer);
        startTimer.setOnClickListener(new View.OnClickListener() {
            public void onClick(View view) {
                timerAlert(view);
            }
        });
    }

Now let's see how to add the highlighted code, starting with the import statements needed.

We will pass the view variable (the onClick view or button that was passed from the onClick() method) to the timerAlert() method so that it has the context needed for the PendingIntent. Here is the code for the timerAlert() method, which we will go over line by line:

public void timerAlert(View view) {
    EditText textField = (EditText) findViewById(R.id.timeInSeconds);
    int i = Integer.parseInt(textField.getText().toString());
    Intent timerIntent = new Intent(this, TimerBroadcastReceiver.class);
    PendingIntent myPendingIntent =
      PendingIntent.getBroadcast(this.getApplicationContext(), 0, timerIntent, 0);
    AlarmManager myAlarmManager = (AlarmManager) getSystemService(ALARM_SERVICE);
    myAlarmManager.set(AlarmManager.RTC_WAKEUP, System.currentTimeMillis() +
      (i * 1000), myPendingIntent);
    Toast.makeText(this, "Alarm is set for " + i + " seconds!",
                   Toast.LENGTH_LONG).show();
}

In our incarnation of the set() method on the myAlarmManager object, we first specify the AlarmManager.RTC_WAKEUP, which uses the Real Time Clock (RTC) method and wakeup constant to specify that we want to wake up the phone (if it is asleep) to deliver the alarm. The RTC method uses the system clock in milliseconds as its time reference.

Using RTC only (without the _WAKEUP) will not wake the phone up if it triggers while the phone is asleep, and thus will be delivered only when the phone wakes up again. This makes it not nearly as accurate as the RTC_WAKEUP constant. You can imagine how handy it is to be able to wake up your phone at a certain discreet time even if it is asleep, so it's a good thing we are exposing you to this handy class here.

The next parameter we need to specify is the precise system time, in milliseconds, to trigger the alarm. We will wax a bit tricky here, and we will specify this middle parameter using a bit of inline programming logic.

We call the currentTimeMillis() method on the Android System object to get the current system time in milliseconds, then we add to the system time the number of seconds specified by our user in milliseconds, by multiplying the number of seconds in variable i by 1000, since there are 1000 milliseconds in one second. The system time is calculated in milliseconds since 1970, so it is a discrete number that we can simply add our timer milliseconds value to.

This numeric result gives us the exact system time in milliseconds when the alarm needs to be triggered, and puts it into the set() method's second parameter, when our inline code is evaluated at runtime. As we have seen, Java allows some fairly powerful programming constructs to be created using just a single line of programming code.

Finally, we will specify the myPendingIntent object as our third parameter. This object, created earlier with two lines of code, was loaded with the current context and the timerIntent object that we created earlier with three lines of code. The timerIntent object references our TimerBroadcastReceiver class, which will ultimately be called when the alarm is triggered, and will send a Toast to the screen to tell our end user that the time is up.

The final line of code sends a familiar Toast message to the end user, confirming that the alarm has been set for the proper number of seconds. This is done by passing the Toast makeText() method the current context (this) along with the Toast.LENGTH_LONG constant and two strings with the i variable between them like this:

Toast.makeText(this, "Alarm is set for " + i + " seconds!", Toast.LENGTH_LONG).show();

As we've seen here, Java is very flexible in how it allows us to mix different data types. Figure 11-24 shows our newly enhanced DigitalClockActivity class with the new import statements, onCreate() method and timerAlert() method modifications shown. Notice along the top of the IDE that we now have seven open tabs with XML and Java code that we have either modified or written. This is the most robust application we've written so far! Now we will run and test our new app.

Figure 11.24. Adding the startTimer button UI code and timerAlert() method

Let's right-click on our Chapter11 folder and select Run As

This shows us that all of the different types of intents can work seamlessly together in Android and that they don't interfere with each other, as we noted at the beginning of the chapter.

We can now go back and forth between the analog and digital activities using the intents we created; turn on the music and go back and forth while it is playing; and use the timer function while the digital audio is playing back as a service.

In the digital clock activity, we can use the editable text field to set our timer value and the start timer countdown button to trigger the broadcast intent, which broadcasts a Toast to the screen when the specified number of seconds has passed.

Figure 11-25 shows the application running in the Android 1.5 emulator displaying the digital clock, the timer function, and the button that allows us to switch back and forth between our two different activities and their user interfaces.

Figure 11.25. Running our timerAlert() method in the Android 1.5 emulator to show broadcast receiver intents