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 explicitIntent
). This is the class name of theActivity
or other component that should receive theIntent
; for example,com.example.SampleActivity.class
. Use theIntent
constructor or thesetComponent()
,setComponentName()
, orsetClassName()
methods to specify the class.The
Intent
data. TheIntent
data field contains a reference to the data you want the receivingActivity
to operate on as a Uri object.Intent
extras. These are key-value pairs that carry information the receivingActivity
requires to accomplish the requested action.Intent
flags. These are additional bits of metadata, defined by theIntent
class. The flags may instruct the Android system how to launch anActivity
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:
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:
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:
Create the
Intent
object.Put data or extras into that
Intent
.Start the new
Activity
withstartActivity()
.
In the second (receiving) Activity
, you:
Get the
Intent
object theActivity
was started with.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:
Use the setData()
method with a Uri object to add that URI to the Intent
. Some examples of using setData()
with URIs:
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:
Add extras to the Intent
To add Intent
extras to an explicit Intent
from the originating Activity
:
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.
Use the
putExtra()
methods to add your key/value pairs to theIntent
extras. Optionally you can create aBundle
object, add your data to theBundle
, and then add theBundle
to theIntent
.
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:
Create an Intent
object (if one does not already exist):
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:
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
.
After you've populated the Bundle
, add it to the Intent
with the putExtras()
method (note the "s" in Extras
):
Start the Activity
with the Intent
as usual:
Last updated