Using Intents and Intent Filters in your apps: A tutorial

If you haven’t already done so, maybe you’d like to read, Getting to know Intents and Intent Filters.

A number of buttons are displayed on the main screen

Starting the tutorial app displays a number of buttons. We’ll cover what happens when they’re pressed below.

Using an implicit intent to use a component in another app:

Sending an email

Here’s how you can use another application on the device to send an email from inside your app.

Pressing the Send Email button executes the sendMail() method

Note the following:

• sendIntent – our Implicit intent
• ACTION_SEND – this is our activity action which specifies that we want to send some data. We don’t know who will receive this intent. The device’s system will use the intent filters to find components capable of sending the data on our behalf
• setType – we set the MIME type of the data that we want to send. We’re using “message/rfc822”. Other common MIME types are “text/plain” and “image/jpg”
• putExtra – we use the putExtra() method to add extra information to our intent. In this case we add:
  • EXTRA_EMAIL – an array of email addresses
  • EXTRA_SUBJECT – the subject of the email that we want to send
  • EXTRA_TEXT – the body of the email

Check out Passing data between activities for more on putting data into and getting data out of intents

• startActivity – starts the intent passed as a parameter
• createChooser – creates an ACTION_CHOOSER intent. This will display a dialog listing all the apps that can perform the action specified in our intent. In other words all apps capable of sending an email. The user can then select which app they want to use to send the email

We have declared an intent filter in the manifest for one of our activities, MyActionSendActivity activity. This tells the system that our app can handle the send action:

Our MyActionSendActivity activity can send emails (well, not quite but let’s pretend) so we declare this in an intent filter in the manifest

Note the following:

• action – we declare that this activity can perform the SEND action
• category – we must include the DEFAULT category for this activity to be able to receive implicit intents
• data – the type of data that this activity can send

You can get hold of the action and data type in the activity if you need to:

You can access the action and data type in the activity

Pressing the Send Email button displays a Dialog listing the apps capable of sending an email. Note that our app is included in the list

This is the Dialog message that displays if no apps capable of sending an email were found

Making a call

Here’s how you can use another application on the device to make a call from inside your app.

Pressing the Make Phone Call button executes the makePhoneCall() method

Note the following:

• intent – our implicit intent
• ACTION_DIAL – the action that we want performed. We’re looking for a component that can dial a number
• Uri.parse – the data on which the action will be performed - this is the number that we want dialled
• packageManager – we can use the Package Manager to find out which components are on the device. We can use it to see if there are any apps that can process our intent, to make a call
• componentName – we use it as an identifier for the app component that we’re looking for
• resolveActivity – this will list all activities that can handle our intent (make a call)
• we use an if statement to check the value of componentName. If it’s empty, then there are no apps with an activity that can make a call so we display an appropriate Toast message. If it’s not empty, then there is at least one app with an activity that can make the call for us so we can go ahead and call startActivity()
• startActivity – we start the activity capable of making the call, passing the intent as a parameter

A Dialog appears listing the apps capable of making the call

Selecting a contact

Here’s how you can use another application on the device to select a contact from inside your app.

Pressing the Select Contact button executes the pickContact() method

Note the following:

• uri – the Url of the data we’re interested in
• intent – our implicit intent
• ACTION_PICK – the action that we need performed. We need to pick an item from the data specified by the uri
• setType – the MIME type. The type of data that we want returned
• ContactsContract.CommonDataKinds.Phone.CONTENT_TYPE – a data type representing a telephone number. We’re interested in a list of contacts that have a phone number
• startActivityForResult – this will start the activity capable of displaying a list of contacts. We can then select a contact, the contact list will close and the selected contact will be returned to us
• REQUEST_CODE – our unique request code to identify the result of this request

Getting the result

The onActivityResult() method is triggered when the result is returned

Note the following:

• requestCode – this is the unique identifier for this returned result
• resultCode – this is the result code returned by the activity that we started to get a result. Typically this will be either RESULT_OK or RESULT_CANCELLED
• data – an Intent containing the result
• we use an if statement to check whether it’s our result and whether the operation to get the result was a success. If both cases are true then we display an appropriate Toast message

Want to use the device’s camera app to take a photo in your app? Check out Using Android’s camera in your application.

Using explicit intents

Starting an Activity

Here’s how you can use an explicit intent to start an activity:

Pressing the Start New Activity button executes the startNewActivity() method

Note the following:

• intentNewActivity – our explicit intent. We pass two parameters:
  • the context
  • the name of the component that we want to handle the intent
• putExtra – extra data that we want to pass along with the intent. We pass the data as a name-value-pair:
  • whichIntent – the name
  • 1 – the value

We’ll extract this data in the MyActionSendActivity activity when it’s started

• startActivity – starts the activity contained in our intent which is passed as a parameter

Getting the extra data out of the intent

We can extract the extra data passed in the intent by calling getIntent() and the appropriate getExtra method for the type of data that we passed

Starting an Activity for a result

Here’s how you can use an explicit intent to start an activity for a result:

Pressing the Start Activity for Result button executes the startResultActivity() method

Note the following:

• intentResultActivity – our explicit intent. We pass it two parameters:
  • the context
  • the name of the component that we want to handle the intent
• startActivityForResult – starts the activity specified in the intent passed as a parameter. We also pass a unique identifier, REQUEST_CODE to identify the returned result

The returned result is displayed in a text view

Getting the result

• onActivityResult – this method fires when the result is returned
• requestCode – this is the unique identifier for this returned result
• resultCode – this is the result code returned by the activity that we started to get a result. Typically this will be either RESULT_OK or RESULT_CANCELLED
• data – an Intent containing the result
• we use an if statement to check whether it’s our result and whether the operation to get the result was a success. If both cases are true then we display the returned result in a text view

Here’s the code in the ResultActivity activity that returns the result:

Returning the result to the activity that requested it

Note the following:

• intentReturnResult – our intent that we’ll use to return the result
• putExtra – we include the requested result as an extra in the intent
• setResult – we set the result to be returned. We pass two parameters:
  • the result code that we want to return
  • the requested result data
• finish – closes the activity and returns the result

Have a look at the tutorial, Start an activity for a result for more on starting an activity for a result.

Starting a Service

Here’s how you can use an explicit intent to start a Service:

Pressing the Start Service button executes the startMyService() method

Note the following:

• intentStartService – our explicit intent. We pass it two parameters:
  • the context
  • the name of the component that we want to handle our intent
• putExtra – extra data that we want to pass along with the intent. We pass the data as a name-value-pair:
  • serviceString – the name
  • String extra passed via an intent – the value
• startService – starts the Service specified in the intent passed as a parameter

Want to find out more about Services? Have a look at All about Services.

Broadcasting an intent

Here’s how you would broadcast an intent:

We broadcast an intent from within our Service’s onHandleIntent() method

Note the following:

• serviceString – we use getStringExtra() to get the string out of the intent. Remember, we included it in the intent when we started the Service
• intentBroadcast – our new intent that we’ll eventually broadcast
• setAction – we set the action that we want the receiving component to perform
• ACTION_SERVICE_WORK – this is our custom action. See below

We declare our custom action as a constant. Note that we include the package name as a prefix

• putExtra – extra data that we want to pass along with the intent. We pass the data as a name-value-pair:
  • serviceString – the name
  • serviceString – the value (it’s the same string that was passed to the Service)
• sendBroadcast – we broadcast the intent (passed as a parameter) to all broadcast receivers that are able to receive it. (They’ll need an intent filter with the ACTION_SERVICE_WORK action)

Starting the Service broadcasts an intent. The broadcast receiver receives the intent and displays the above screen

Starting an activity from within a receiver

Here’s how you would start an activity from within a broadcast receiver:

 

The receiver’s onReceive() method is fired when the broadcast intent has been received by the receiver

Note the following:

• intentStartActivity – our explicit intent. It is passed two parameters:
  • the context
  • the name of the activity that we want to start
• setFlags – the flags specify how the intent should be handled
• FLAG_ACTIVITY_NEW_TASK – specifies that the activity that we want to start, should be started in a new task. This flag is required because we want to start an activity from outside an Activity’s context
• putExtra – extra data that we want to pass along with the intent. We pass the data as a name-value-pair:
  • serviceString – the name
  • intent.getStringExtra – we get the string out of the intent that was broadcast by the service and pass it as the extra value
• startActivity – we start the activity specified by the intent that we pass as a parameter. Note that we call startActivity() using the context in which the receiver is running

Pending intent

A Notification is sent when the DisplayActivity activity starts.

When the notification is clicked, it executes the intent contained in the pending intent and takes the user back to the MainActivity activity.

The Broadcast Receiver receives the intent sent by the Service and sends a Notification. Clicking the notification returns the user to the main screen

Here’s how you use a Pending Intent in a notification:

Building the Notification

Note the following regarding the Pending Intent:

• stackBuilder – app navigation using the Back key changed since Honeycomb. Our stackBuilder object allows us to build a synthetic back stack so that pressing the Back key navigates backwards as it should, no matter the build version
• addParentStack – adds the back stack for the intent
• addNextIntent – adds the intent that will start the activity to the top of the stack
• getPendingIntent – get the pending intent to launch the stack builder task. We pass two parameters:
  • unique request code for the sender
  • a flag – in this case, FLAG_UPDATE_CURRENT. This specifies that a new pending intent should be created but if it already exists, then use it and simply replace any extra data with the new data contained in the intent
• setContentIntent – supply the pending intent passed as a parameter when the notification is clicked

Check out You can master Notifications. It’s easy! for more on Notifications.

Intent Filters

Here’s how you register Intent Filters in the AndroidManifest.xml file.

The Activity’s Intent Filter

Here’s the intent filter for the MainActivity activity:

The MainActivity activity’s entry in the manifest file includes an intent filter

Note the following:

• action – the action to be performed. Here MAIN indicates that this activity is the main entry point to the app
• category – gives additional information about the action. Here LAUNCHER indicates that this activity should appear in the System’s application Launcher

The Broadcast Receiver’s Intent Filter

Here’s the intent filter for the MyBroadcastReceiver receiver:

We register our broadcast receiver in the AndroidManifest.xml file. We include an intent filter element with a custom action attribute

We use a custom action:

Our custom action includes the package name as a prefix

We set the action for the broadcast intent when we sent the broadcast in our Service:

We set the broadcast intent action in our Service

For more on Broadcast Receivers, have a look at Android Broadcast Receivers: A tutorial.

I hope that you have found this tutorial helpful.

This project was created using .

You can download the project files here 

Are you using Eclipse or another IDE? Here's how you can use this project's Android Studio files.