Intents

What is Intents ?

Each activity is started or activated with an Intent, which is a message object that makes a request to the Android runtime to start an activity or other app component in your app or in some other app.

When your app is first started from the device home screen, the Android runtime sends an Intent to your app to start your app's main activity (the one defined with the MAIN action and the LAUNCHER category in the AndroidManifest.xml file). To start another activity in your app, or to request that some other activity available on the device perform an action, you build your own intent and call the startActivity() method to send the intent.

In addition to starting an activity, an intent can also be used to pass data between one activity and another. When you create an intent to start a new activity, you can include information about the data you want that new activity to operate on. So, for example, an email Activity that displays a list of messages can send an Intent to the Activity that displays that message. The display activity needs data about the message to display, and you can include that data in the intent.

In this chapter you learn about using intents with activities, but intents can also be used to start services or broadcast receivers. You learn how to use those app components in another practical.

Intent types

Intents can be explicit or implicit:

• Explicit intent: You specify the receiving activity (or other component) using the activity's fully qualified class name. You use explicit intents to start components in your own app (for example, to move between screens in the UI), because you already know the package and class name of that component.

• Implicit intent: You do not specify a specific activity or other component to receive the intent. Instead, you declare a general action to perform, and the Android system matches your request to an activity or other component that can handle the requested action. You learn more about using implicit intents in another practical.

Intent objects and fields

For an explicit Intent, the key fields include the following:

• The Activity class (for an explicit Intent). This is the class name of the Activity or other component that should receive the Intent; for example, com.example.SampleActivity.class. Use the Intent constructor or the setComponent(), setComponentName(), or setClassName() methods to specify the class.

• The Intent data. The Intent data field contains a reference to the data you want the receiving Activity to operate on as a Uri object.

• Intent extras. These are key-value pairs that carry information the receiving Activity requires to accomplish the requested action.

• Intent flags. These are additional bits of metadata, defined by the Intent class. The flags may instruct the Android system how to launch an Activity or how to treat it after it's launched.

For an implicit Intent, you may need to also define the Intent action and category. You learn more about Intent actions and categories in another chapter.

Starting an Activity with an explicit Intent

To start a specific Activity from another Activity, use an explicit Intent and the startActivity() method. An explicit Intent includes the fully qualified class name for the Activity or other component in the Intent object. All the other Intent fields are optional, and null by default.

For example, if you want to start the ShowMessageActivity to show a specific message in an email app, use code like this:

Intent messageIntent = new Intent(this, ShowMessageActivity.class);
startActivity(messageIntent);

The intent constructor takes two arguments for an explicit Intent:

• An application context. In this example, the Activity class provides the context (this).

• The specific component to start (ShowMessageActivity.class).

Use the startActivity() method with the new Intent object as the only argument. The startActivity() method sends the Intent to the Android system, which launches the ShowMessageActivity class on behalf of your app. The new Activity appears on the screen, and the originating Activity is paused.

The started Activity remains on the screen until the user taps the Back button on the device, at which time that Activity closes and is reclaimed by the system, and the originating Activity is resumed. You can also manually close the started Activity in response to a user action (such as a Button click) with the finish() method:

public void closeActivity (View view) {
    finish();
}

Passing data from one Activity to another

In addition to simply starting one Activity from another Activity, you also use an Intent to pass information from one Activity to another. The Intent object you use to start an Activity can include Intent data (the URI of an object to act on), or Intent extras, which are bits of additional data the Activity might need.

In the first (sending) Activity, you:

1. Create the Intent object.

2. Put data or extras into that Intent.

3. Start the new Activity with startActivity().

In the second (receiving) Activity, you:

1. Get the Intent object the Activity was started with.

2. Retrieve the data or extras from the Intent object.

When to use Intent data or Intent extras

You can use either Intent data or Intent extras to pass data from one Activity to another. There are several key differences between data and extras that determine which you should use.

The Intent data can hold only one piece of information: a URI representing the location of the data you want to operate on. That URI could be a web page URL (http://), a telephone number (tel://), a geographic location (geo://) or any other custom URI you define.

Use the Intent data field:

• When you only have one piece of information you need to send to the started Activity.

• When that information is a data location that can be represented by a URI.

Intent extras are for any other arbitrary data you want to pass to the started Activity. Intent extras are stored in a Bundle object as key and value pairs. A Bundle is a map, optimized for Android, in which a key is a string, and a value can be any primitive or object type (objects must implement the Parcelable interface). To put data into the Intent extras you can use any of the Intent class putExtra() methods, or create your own Bundle and put it into the Intent with putExtras().

Use the Intent extras:

• If you want to pass more than one piece of information to the started Activity.

• If any of the information you want to pass is not expressible by a URI.

Intent data and extras are not exclusive; you can use data for a URI and extras for any additional information the started Activity needs to process the data in that URI.

Add data to the Intent

To add data to an explicit Intent from the originating Activity, create the Intent object as you did before:

Intent messageIntent = new Intent(this, ShowMessageActivity.class);

Use the setData() method with a Uri object to add that URI to the Intent. Some examples of using setData() with URIs:

// A web page URL
messageIntent.setData(Uri.parse("http://www.google.com")); 
// a Sample file URI
messageIntent.setData(Uri.fromFile(new File("/sdcard/sample.jpg")));
// A sample content: URI for your app's data model
messageIntent.setData(Uri.parse("content://mysample.provider/data")); 
// Custom URI 
messageIntent.setData(Uri.parse("custom:" + dataID + buttonId));

Keep in mind that the data field can only contain a single URI; if you call setData() multiple times only the last value is used. Use Intent extras to include additional information (including URIs.)

After you've added the data, you can start the Activity with the Intent as usual:

startActivity(messageIntent);

Add extras to the Intent

To add Intent extras to an explicit Intent from the originating Activity:

1. Determine the keys to use for the information you want to put into the extras, or define your own. Each piece of information needs its own unique key.

2. Use the putExtra() methods to add your key/value pairs to the Intent extras. Optionally you can create a Bundle object, add your data to the Bundle, and then add the Bundle to the Intent.

The Intent class includes extra keys you can use, defined as constants that begin with the word EXTRA_. For example, you could use Intent.EXTRA_EMAIL to indicate an array of email addresses (as strings), or Intent.EXTRA_REFERRER to specify information about the originating Activity that sent the Intent.

You can also define your own Intent extra keys. Conventionally you define Intent extra keys as static variables with names that begin with EXTRA_. To guarantee that the key is unique, the string value for the key itself should be prefixed with your app's fully qualified class name. For example:

public final static String EXTRA_MESSAGE = 
                                        "com.example.mysampleapp.MESSAGE";
public final static String EXTRA_POSITION_X = "com.example.mysampleapp.X";
public final static String EXTRA_POSITION_Y = "com.example.mysampleapp.Y";

Create an Intent object (if one does not already exist):

Intent messageIntent = new Intent(this, ShowMessageActivity.class);

Use a putExtra() method with a key to put data into the Intent extras. The Intent class defines many putExtra() methods for different kinds of data:

messageIntent.putExtra(EXTRA_MESSAGE, "this is my message");
messageIntent.putExtra(EXTRA_POSITION_X, 100);
messageIntent.putExtra(EXTRA_POSITION_Y, 500);

Alternately, you can create a new Bundle and populate that Bundle with your Intent extras. Bundle defines many "put" methods for different kinds of primitive data as well as objects that implement Android's Parcelable interface or Java's Serializable.

Bundle extras = new Bundle();
extras.putString(EXTRA_MESSAGE, "this is my message");
extras.putInt(EXTRA_POSITION_X, 100);
extras.putInt(EXTRA_POSITION_Y, 500);

After you've populated the Bundle, add it to the Intent with the putExtras() method (note the "s" in Extras):

messageIntent.putExtras(extras);

Start the Activity with the Intent as usual:

startActivity(messageIntent);