Tuesday, 29 November 2011

Using Intents in Android


1. Android Intents

1.1. Overview

Intents allow sending or receiving data from and to other activities or services. Intents are objects of type "android.content.Intent" and are used to send asynchronous messages within your application or between applications.
Intents can also be used to broadcast to the Android system that a certain event has occurred. Other components in Android can register to this event and will get notified.
Intents are a powerful concept as they allow the creation of loosely coupled applications. Intents can be used to communicate between any installed application component on the device.
An Intent object can contain information for the receiving component. For example if your application calls via an Intent a browser it may send the URL to the browser component. An Intent also contain information for the Android system so that the Android system can determine which component should handle the request.

1.2. Implicit vrs Explicit Intents

Android supports explicit intents and implicit intents. Explicit intent names the component, e.g. the Java class which should be called.
Implicit intents asked the system to perform a service without telling the system which Java class should do this service. In constructing an implicit Intent you specify the action which should be performed and optionally an URI which should be used for this action. For example you could tell the system that you want to view (action) a webpage (URI). By starting an intent for this data the system would try to find an application which is registered for this event, e.g. a browser.

1.3. Starting Activities and Sub-Activities

To start an activity use the method startActivity(Intent) if you do not need a return value from the called activity.
If you need some information from the called activity use the method startActivityForResult(). Once the called Activity is finished the method onActivityResult() in the calling activity will be called. If you use startActivityForResult() then the activity which is started is considered a "Sub-Activity".

2. More on Intents

2.1. Data Transfer

An Intent can contain data. This data call be filled by the component which creates the intent and can get extracted by the component which receives the intent.
You can add data to the Intent with the overloaded method putExtra() on the Intent. Extras are key/value pairs.
To get the Intent information in the called Activity use the method getIntent(). If the Activity was called via an implicit Intent you can receive the data and url from this Intent via getAction(), getData() and getExtras().

2.2. Intent Filter

The Android system will determine suitable applications for an implicit intent and if several applications exists offer the user the choice to open one. The determination is based on intent filters, e.g. the class "android.content.IntentFilter". Intent filters are typically defined via the "AndroidManifest.xml" file.
To react to a certain implicit intent an application component must register itself via an IntentFilter in the "AndroidManifest.xml" to this event. If a component does not define intent filters it can only be called by explicit intents.
Your application can also register itself for implicit intents in Android. These can be new intents or existing intents. For example you can register your own application for the intent which is triggered whenever someone wants to view a webpage. If you do this the user will get an popup which browser application he wants to use for the triggered intent.
For this you have to specify an intent filter for the selected event. Intent filters are typically declared in "AndroidManifest.xml". An intent filter must specify category, action and data filters.

2.3. Intents as event triggers

Intents can also be used to broadcast messages into the Android system. An Android application can registerBroadcast Receivers to these events and react accordingly. The Android system also uses Intents to broadcast system events. Your application can also register to these system events, e.g. a new email has arrived, system boot is complete or a phone call is received and react accordingly.

3. Finding out if an intent is available

Sometimes you want to find if an application has registered for a certain intent. For example you want to check if a certain receiver is available and if you enable some functionality in your app.
This can be done via checking the PackageManager. The following code checks if an intent exists. You can check via this method for intent and change your application behavior accordingly for example disable or hide menu items.

public boolean isIntentAvailable(Context context, String action) {
    final PackageManager packageManager = context.getPackageManager();
    final Intent intent = new Intent(action);
    List<ResolveInfo> resolveInfo =
            packageManager.queryIntentActivities(intent,
                    PackageManager.MATCH_DEFAULT_ONLY);
   if (resolveInfo.size() > 0) {
     return true;
    }
   return false;
}

  

4. Prerequisites for this tutorial

The following assumes that you have already basic knowledge in Android development. Please check the Android development tutorial to learn the basics.

5. Tutorial: Implicit Intents

The following creates an example project for calling several implicit intent. The Android system is asked to display a URI and chooses the corresponding application for the right URI. Create a new Android application "de.vogella.android.intent.implicit" with the Activity "CallIntents". Create the following view layout.

<?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"
    >

<Button android:id="@+id/Button01" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="Call browser"  android:onClick="callIntent"></Button>
<Button android:id="@+id/Button02" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="Call Someone" android:width="100px" android:onClick="callIntent"></Button>
<Button android:id="@+id/Button03" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="Dial" android:width="100px" android:onClick="callIntent"></Button>
<Button android:id="@+id/Button04" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="Show Map" android:width="100px" android:onClick="callIntent"></Button>
<Button android:id="@+id/Button05" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="Search on Map" android:width="100px" android:onClick="callIntent"></Button>
<Button android:id="@+id/Button06" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="Take picture" android:width="100px" android:onClick="callIntent"></Button>
<Button android:id="@+id/Button07" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="Show contacts" android:width="100px" android:onClick="callIntent"></Button>
<Button android:id="@+id/Button08" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="Edit first contact" android:width="100px" android:onClick="callIntent"></Button>

</LinearLayout>

  

To be able to use certain intents you need to register then for your application. Maintain the following "AndroidManifest.xml".

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="de.vogella.android.intent.implicit"
      android:versionCode="1"
      android:versionName="1.0">
    <application android:icon="@drawable/icon" android:label="@string/app_name">
        <activity android:name=".CallIntents"
                  android:label="@string/app_name">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

    </application>
    <uses-sdk android:minSdkVersion="9" />


<uses-permission android:name="android.permission.CALL_PRIVILEGED"></uses-permission>
<uses-permission android:name="android.permission.CALL_PHONE"></uses-permission>
<uses-permission android:name="android.permission.INTERNET"></uses-permission>
<uses-permission android:name="android.permission.CAMERA"></uses-permission>
<uses-permission android:name="android.permission.READ_CONTACTS"></uses-permission>
</manifest> 
  

Change your activity to the following. We will start the new intent with the method startActivityForResult() which allow us to specify a desired result code. Once the intent is finished the method onActivityResult() is called and you can perform actions based on the result of the activity.

package de.vogella.android.intent.implicit;

import android.app.Activity;
import android.content.Intent;
import android.net.Uri;
import android.os.Bundle;
import android.view.View;
import android.widget.Toast;

public class CallIntents extends Activity {
 
/** Called when the activity is first created. */
@Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.main); } public void callIntent(View view) { Intent intent = null; switch (view.getId()) { case R.id.Button01: intent = new Intent(Intent.ACTION_VIEW, Uri.parse("http://www.vogella.de")); startActivity(intent); break; case R.id.Button02: intent = new Intent(Intent.ACTION_CALL, Uri.parse("tel:(+49)12345789")); startActivity(intent); break; case R.id.Button03: intent = new Intent(Intent.ACTION_DIAL, Uri.parse("tel:(+49)12345789")); startActivity(intent); break; case R.id.Button04: intent = new Intent(Intent.ACTION_VIEW, Uri.parse("geo:50.123,7.1434?z=19")); startActivity(intent); break; case R.id.Button05: intent = new Intent(Intent.ACTION_VIEW, Uri.parse("geo:0,0?q=query")); startActivity(intent); break; case R.id.Button06: intent = new Intent("android.media.action.IMAGE_CAPTURE"); startActivityForResult(intent, 0); break; case R.id.Button07: intent = new Intent(Intent.ACTION_VIEW, Uri.parse("content://contacts/people/")); startActivity(intent); break; case R.id.Button08: intent = new Intent(Intent.ACTION_EDIT, Uri.parse("content://contacts/people/1")); startActivity(intent); break; default: break; } } @Override public void onActivityResult(int requestCode, int resultCode, Intent data) { if (resultCode == Activity.RESULT_OK && requestCode == 0) { String result = data.toURI(); Toast.makeText(this, result, Toast.LENGTH_LONG); } } }

If you start your application you should see an list of buttons and if you press the button, different activities should be performed. Note that you didn't specify any receiving application only the thing that should be done.

6. Tutorial: Explicit intents and data transfer between activities

The following demonstrates how you can transfer data between two activities. We will use explicit intents in this example and create two activities. The first activity will call the second one via an explicit intent. This second activity will receive data from the first one via the class "Bundle" which can be retrieved via intent.getExtras().
The second activity can be finished either via the back button on the phone or via the button. The method finish() is performed in this case. In this method you can transfer some data back to the calling activity. This is possible because we use the method startActivityForResult(). If you start an activity via this method the method onActivity result is called on the calling activity once the called activity is finshed.
Create a new Android application "de.vogella.android.intent.explicit" with the Activity "ActivityOne". Change the layout "main.xml" to the following.

<?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">

 <LinearLayout android:id="@+id/LinearLayout01"
  android:layout_width="wrap_content" android:layout_height="wrap_content">
  <TextView android:id="@+id/TextView01" android:layout_width="wrap_content"
   android:layout_height="wrap_content"
   android:text="First Activity. Press button to call second activity"
   android:minHeight="60dip" android:textSize="20sp"></TextView>
 </LinearLayout>
 <LinearLayout android:id="@+id/LinearLayout02"
  android:layout_width="wrap_content" android:layout_height="wrap_content"></LinearLayout>
 <Button android:id="@+id/Button01" android:layout_width="wrap_content"
  android:layout_height="wrap_content" android:onClick="onClick"
  android:text="Calling an intent"></Button>
</LinearLayout>

  

Create the layout "second.xml".

<?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">

 <LinearLayout android:id="@+id/LinearLayout01"
  android:layout_width="wrap_content" android:layout_height="wrap_content">
  <TextView android:id="@+id/TextView01" android:layout_width="wrap_content"
   android:layout_height="wrap_content" android:text="First value from Activity 1"></TextView>
  <EditText android:text="@+id/EditText01" android:id="@+id/EditText01"
   android:layout_width="wrap_content" android:layout_height="wrap_content"></EditText>
 </LinearLayout>
 <LinearLayout android:id="@+id/LinearLayout02"
  android:layout_width="wrap_content" android:layout_height="wrap_content">
  <TextView android:id="@+id/TextView02" android:layout_width="wrap_content"
   android:layout_height="wrap_content" android:text="Second Value from Activity one"></TextView>
  <EditText android:text="@+id/EditText02" android:id="@+id/EditText02"
   android:layout_width="wrap_content" android:layout_height="wrap_content"></EditText>
 </LinearLayout>
 <Button android:id="@+id/Button01" android:layout_width="wrap_content"
  android:layout_height="wrap_content" android:onClick="onClick"
  android:text="Finished this activity"></Button>
</LinearLayout>

  

Create a new activity "ActivityTwo" via the AndroidManifest.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="de.vogella.android.intent.explicit"
      android:versionCode="1"
      android:versionName="1.0">
    <application android:icon="@drawable/icon" android:label="@string/app_name">
        <activity android:name=".ActivityOne"
                  android:label="@string/app_name">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

    <activity android:label="ActivityTwo" android:name="ActivityTwo"></activity>
</application>
    <uses-sdk android:minSdkVersion="9" />

</manifest> 
  

Create the following coding for your two activities. The second activity will be called from the first one, displays the transferred data and if you select the button of the back button on the phone you send some data back tot the calling application.

package de.vogella.android.intent.explicit;

import android.app.Activity;
import android.content.Intent;
import android.os.Bundle;
import android.view.View;
import android.widget.Toast;

public class ActivityOne extends Activity {
 private static final int REQUEST_CODE = 10;

 
/** Called when the activity is first created. */
@Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.main); } public void onClick(View view) { Intent i = new Intent(this, ActivityTwo.class); i.putExtra("Value1", "This value one for ActivityTwo "); i.putExtra("Value2", "This value two ActivityTwo"); // Set the request code to any code you like, you can identify the // callback via this code startActivityForResult(i, REQUEST_CODE); } @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { if (resultCode == RESULT_OK && requestCode == REQUEST_CODE) { if (data.hasExtra("returnKey1")) { Toast.makeText(this, data.getExtras().getString("returnKey1"), Toast.LENGTH_SHORT).show(); } } } }


package de.vogella.android.intent.explicit;

import android.app.Activity;
import android.content.Intent;
import android.os.Bundle;
import android.view.View;
import android.widget.EditText;

public class ActivityTwo extends Activity {

 
/** Called when the activity is first created. */
@Override public void onCreate(Bundle bundle) { super.onCreate(bundle); setContentView(R.layout.second); Bundle extras = getIntent().getExtras(); if (extras == null) { return; } String value1 = extras.getString("Value1"); String value2 = extras.getString("Value2"); if (value1 != null && value2 != null) { EditText text1 = (EditText) findViewById(R.id.EditText01); EditText text2 = (EditText) findViewById(R.id.EditText02); text1.setText(value1); text2.setText(value2); } } public void onClick(View view) { finish(); } @Override public void finish() { Intent data = new Intent(); data.putExtra("returnKey1", "Swinging on a star. "); data.putExtra("returnKey2", "You could be better then you are. "); setResult(RESULT_OK, data); super.finish(); } }

7. Tutorial: Registering via Intentfilter

Lets create a small browser. Our application will register itself as a browser and will display the HTML code for a giving webpage.
Create the Android project "de.vogella.android.intent.browserfilter" with the activity "BrowserActivitiy". Change "AndroidManifest.mf" to the following to register your application to the browser view intent. THe following also request the permission to access the Internet.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="de.vogella.android.intent.browserfilter"
      android:versionCode="1"
      android:versionName="1.0">
    <application android:icon="@drawable/icon" android:label="@string/app_name">
        <activity android:name=".BrowserActivitiy"
                  android:label="@string/app_name">
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <data android:scheme="http"/> 
            </intent-filter>
        </activity>

    </application>
    <uses-sdk android:minSdkVersion="9" />

<uses-permission android:name="android.permission.INTERNET"></uses-permission>
</manifest> 
  

Change "main.xml" to the following.

<?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:id="@+id/textView"/>
</LinearLayout>

  

As your activity gets called with an intent you can get the data from the intent and display it in your application.

package de.vogella.android.intent.browserfilter;

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.URL;

import android.app.Activity;
import android.content.Intent;
import android.net.Uri;
import android.os.Bundle;
import android.widget.TextView;

public class BrowserActivity extends Activity {
 
/** Called when the activity is first created. */
@Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.main); Intent intent = getIntent(); TextView text = (TextView) findViewById(R.id.textView); // To get the action of the intent use System.out.println(intent.getAction()); // We current open a hard-coded URL // To get the data the intent use the following line //Uri data = intent.getData(); URL url; try { // url = new URL(data.getScheme(), data.getHost(), data.getPath()); url = new URL("http://www.vogella.de"); BufferedReader rd = new BufferedReader(new InputStreamReader( url.openStream())); String line = ""; while ((line = rd.readLine()) != null) { text.append(line); } } catch (Exception e) { e.printStackTrace(); } } }

If you call and URL you should be able to select your browser and the HTML code should be loaded into your text view.