You learned in Chapter 2 that applications consist of a number of interrelated screens — Activities — that must be included in the application manifest. To connect them you may want to explicitly specify an Activity to open.

To explicitly select an Activity class to start, create a new Intent, specifying the current application Context and Activity class to launch. Pass this Intent in to startActivity as shown in Listing 5-1.

Intent intent = new Intent(MyActivity.this, MyOtherActivity.class);
startActivity(intent);

After startActivity is called, the new Activity (in this example MyOtherActivity) will be created and become visible and active, moving to the top of the Activity stack.

Calling finish on the new Activity, or pressing the hardware back button, will close it and remove it from the stack. Alternatively, developers can navigate to the previous Activity, or yet another Activity, by calling startActivity.

An implicit Intent is a mechanism that lets anonymous application components service action requests. That means you can ask the system to launch an Activity that can perform a given action without knowing which application, or Activity, will do so.

When constructing a new implicit Intent to use with startActivity, you nominate an action to perform and, optionally, supply the URI of the data to perform that action on. You can also send additional data to the target Activity by adding extras to the Intent.

When you use this Intent to start an Activity, Android will — at run time — resolve it into the Activity class best suited to performing the required action on the type of data specified. This means you can create projects that use functionality from other applications, without knowing exactly which application you're borrowing functionality from ahead of time.

For example, to let users make calls from your application you could implement a new dialer, or you could use an implicit Intent that requests the action (dialing) be performed on a phone number (represented as a URI), as shown in Listing 5-2.

if (somethingWeird && itDontLookGood) {
  Intent intent = new Intent(Intent.ACTION_DIAL, Uri.parse("tel:555-2368"));
  startActivity(intent);
}

Android resolves this Intent and starts an Activity that provides the dial action on a telephone number — in this case the dialer Activity.

In circumstances where multiple Activities are capable of performing a given action, the user is presented with a choice. The full process of Intent resolution is described later in this chapter.

Various native applications provide Activities to handle actions performed on specific data. Third-party applications, including your own, can be registered to support new actions, or to provide an alternative provider of native actions. You'll be introduced to some of the native actions, and how to register your own Activities to support them, later in this chapter.

An Activity started via startActivity is independent of its parent and will not provide any feedback when it closes.

Alternatively, you can start an Activity as a sub-Activity that's inherently connected to its parent. A sub-Activity triggers an event handler within its parent Activity when it closes. Sub-Activities are perfect for situations in which one Activity is providing data input (such as a user's selecting an item from a list) for another.

Sub-Activities are really just Activities opened in a different way. As such they must be registered in the application manifest — in fact any manifest-registered Activity can be opened as a sub-Activity including system or third-party application Activities.

private static final int SHOW_SUBACTIVITY = 1;

Intent intent = new Intent(this, MyOtherActivity.class);
startActivityForResult(intent, SHOW_SUBACTIVITY);

private static final int PICK_CONTACT_SUBACTIVITY = 2;

Uri uri = Uri.parse("content://contacts/people");
Intent intent = new Intent(Intent.ACTION_PICK, uri);
startActivityForResult(intent, PICK_CONTACT_SUBACTIVITY);

Button okButton = (Button) findViewById(R.id.ok_button);
  okButton.setOnClickListener(new View.OnClickListener() {
  public void onClick(View view) {
    Uri data = Uri.parse("content://horses/" + selected_horse_id);

    Intent result = new Intent(null, data);
    result.putExtra(IS_INPUT_CORRECT, inputCorrect);
    result.putExtra(SELECTED_PISTOL, selectedPistol);

setResult(RESULT_OK, result);
    finish();
  }
});

Button cancelButton = (Button) findViewById(R.id.cancel_button);
cancelButton.setOnClickListener(new View.OnClickListener() {
  public void onClick(View view) {
    setResult(RESULT_CANCELED, null);
    finish();
  }
});

private static final int SHOW_SUB_ACTIVITY_ONE = 1;
private static final int SHOW_SUB_ACTIVITY_TWO = 2;

@Override
public void onActivityResult(int requestCode,

int resultCode,
                             Intent data) {

  super.onActivityResult(requestCode, resultCode, data);

  switch(requestCode) {
    case (SHOW_SUB_ACTIVITY_ONE) : {
      if (resultCode == Activity.RESULT_OK) {
        Uri horse = data.getData();
        boolean inputCorrect = data.getBooleanExtra(IS_INPUT_CORRECT, false);
        String selectedPistol = data.getStringExtra(SELECTED_PISTOL);
      }
      break;
    }
    case (SHOW_SUB_ACTIVITY_TWO) : {
      if (resultCode == Activity.RESULT_OK) {
        // TODO: Handle OK click.
      }
      break;
    }

  }
}

Native Android applications also use Intents to launch Activities and sub-Activities.

The following non-comprehensive list shows some of the native actions available as static string constants in the Intent class. When creating implicit Intents you can use these actions, called Activity Intents, to start Activities and sub-Activities within your own applications.

When you use startActivity, the implicit Intent passed in usually resolves to a single Activity. If there are multiple Activities capable of performing the given action on the specified data, the user will be presented with a list of alternatives.

The process of deciding which Activity to start is called Intent resolution. The aim of Intent resolution is to find the best Intent Filter match possible by means of the following process:

Native Android application components are part of the Intent resolution process in exactly the same way as third-party applications. They do not have a higher priority, and can be completely replaced with new Activities that declare Intent Filters that service the same actions.

When an application component is started through an implicit Intent, it needs to find the action it's to perform and the data to perform it on.

Call the getIntent method — usually from within the onCreate method — to extract the Intent used to start a component, as in Listing 5-8.

@Override
public void onCreate(Bundle icicle) {
  super.onCreate(icicle);
  setContentView(R.layout.main);

  Intent intent = getIntent();
}

Use the getData and getAction methods to find the data and action associated with the Intent. Use the type-safe get<type>Extra methods to extract additional information stored in its extras Bundle.

String action = intent.getAction();
Uri data = intent.getData();

Use the startNextMatchingActivity method to pass responsibility for action handling to the next best matching application component, as shown in Listing 5-9.

Intent intent = getIntent();
if (isDuringBreak)
  startNextMatchingActivity(intent);

This lets you add additional conditions to your components that restrict their use beyond the ability of the Intent Filter-based Intent resolution process.

In some cases your component may wish to perform some processing, or offer the user a choice, before passing the Intent on to an alternative component.

In this example you'll create a new Activity that services ACTION_PICK for contact data. It displays each of the contacts in the contacts database and lets the user select one, before closing and returning the selected contact's URI to the calling Activity.

When your Activity is running, press the button. The contact picker Activity should be shown as in Figure 5-1.

Once you select a contact, the parent Activity should return to the foreground with the selected contact name displayed, as shown in Figure 5-2.

To use this mechanism to make your Activity's actions available anonymously for existing applications, publish them using intent-filter tags within their manifest nodes.

The Intent Filter describes the action it performs and the data upon which it can be performed. The latter will be used during the Intent resolution process to determine when this action should be available. The category tag must be either ALTERNATIVE or SELECTED_ALTERNATIVE or both. The text used for the Menu Items is specified by the android:label attribute.

Listing 5-10 shows an example of an Intent Filter used to advertise an Activity's ability to nuke moon-bases from orbit.

<activity android:name=".NostromoController">
  <intent-filter
    android:label="Nuke From Orbit">
    <action android:name="com.pad.nostromo.NUKE_FROM_ORBIT" />
    <data android:mimeType="vnd.moonbase.cursor.item/*"/>
    <category android:name="android.intent.category.ALTERNATIVE" />
    <category android:name="android.intent.category.SELECTED_ALTERNATIVE" />
  </intent-filter>
</activity>

The Content Provider and other code needed for this example to run aren't provided; in the following sections you'll see how to write the code that adds this action dynamically to another Activity's Menu.

To add Menu Items to your Menus dynamically at run time, use the addIntentOptions method on the Menu object in question: pass in an Intent that specifies the data for which you want to provide actions. Generally this will be handled within your Activities' onCreateOptionsMenu or onCreateContextMenu handlers.

The Intent you create will be used to resolve components with Intent Filters that supply actions for the data you specify. The Intent is being used to find actions, so don't assign it one; it should specify only the data to perform actions on. You should also specify the category of the action, either CATEGORY_ALTERNATIVE or CATEGORY_SELECTED_ALTERNATIVE.

The skeleton code for creating an Intent for menu-action resolution is shown here:

Intent intent = new Intent();
intent.setData(MyProvider.CONTENT_URI);
intent.addCategory(Intent.CATEGORY_ALTERNATIVE);

Pass this Intent in to addIntentOptions on the Menu you wish to populate, as well as any option flags, the name of the calling class, the menu group to use, and the menu ID values. You can also specify an array of Intents you'd like to use to create additional menu items.

Listing 5-11 gives an idea of how to dynamically populate an Activity menu that would include the "moon-base nuker" action from Listing 5-10.

@Override
public boolean onCreateOptionsMenu(Menu menu) {
  super.onCreateOptionsMenu(menu);

  // Create the intent used to resolve which actions
  // should appear in the menu.
  Intent intent = new Intent();
  intent.setData(MoonBaseProvider.CONTENT_URI);
  intent.addCategory(Intent.CATEGORY_SELECTED_ALTERNATIVE);

// Normal menu options to let you set a group and ID
  // values for the menu items you're adding.
  int menuGroup = 0;
  int menuItemId = 0;
  int menuItemOrder = Menu.NONE;

  // Provide the name of the component that's calling
  // the action -- generally the current Activity.
  ComponentName caller = getComponentName();

  // Define intents that should be added first.
  Intent[] specificIntents = null;
  // The menu items created from the previous Intents
  // will populate this array.
  MenuItem[] outSpecificItems = null;

  // Set any optional flags.
  int flags = Menu.FLAG_APPEND_TO_GROUP;

  // Populate the menu
  menu.addIntentOptions(menuGroup,
                        menuItemId,
                        menuItemOrder,
                        caller,
                        specificIntents,
                        intent,
                        flags,
                        outSpecificItems);

  return true;
}

The static Linkify.addLinks method accepts the View to linkify, and a bitmask of one or more of the default content types supported and supplied by the Linkify class: WEB_URLS, EMAIL_ADDRESSES, PHONE_NUMBERS, and ALL.

Listing 5-12 shows how to linkify a Text View to display web and e-mail addresses as hyperlinks. When clicked, they will open the browser and an e-mail application respectively.

TextView textView = (TextView)findViewById(R.id.myTextView);
Linkify.addLinks(textView, Linkify.WEB_URLS|Linkify.EMAIL_ADDRESSES);

You can also linkify Views from within a layout resource using the android:autoLink attribute. It supports one or more (separated by |) of the following self-describing values: none, web, email, phone, and all.

Listing 5-13 shows how to add hyperlinks for phone numbers and e-mail addresses:

<TextView
  android:layout_width="fill_parent"
  android:layout_height="fill_parent"
  android:text="@string/linkify_me"
  android:autoLink="phone|email"
/>

To define your own linkify strings you create a new RegEx pattern to match the text you want to display as hyperlinks.

As with the native types, you linkify the target View by calling Linkify.addLinks, but this time pass in the new RegEx pattern. You can also pass in a prefix that will be prepended to the target URI when a link is clicked.

Listing 5-14 shows a View being linkified to support earthquake data provided by an Android Content Provider (that you will create in Chapter 7). Rather than include the entire schema, the linkify pattern matches any text that starts with "quake" and is followed by a number. The content schema is then prepended to the URI before the Intent is fired.

int flags = Pattern.CASE_INSENSITIVE;
Pattern p = Pattern.compile("\bquake[0-9]*\b", flags);
Linkify.addLinks(myTextView, p,
                 "content://com.paad.earthquake/earthquakes/");

Linkify also supports TransformFilter and MatchFilter interfaces. These offer additional control over the target URI structure and the definition of matching strings, and are used as in the following skeleton code:

Linkify.addLinks(myTextView, pattern, prefixWith,
                 new MyMatchFilter(), new MyTransformFilter());

Implement the acceptMatch method in your Match Filter to add additional conditions to RegEx pattern matches. When a potential match is found acceptMatch is triggered, with the match start and end index (along with the full text being searched) passed in as parameters.

Listing 5-15 shows a MatchFilter implementation that cancels any match immediately preceded by an exclamation mark.

class MyMatchFilter implements MatchFilter {
  public boolean acceptMatch(CharSequence s, int start, int end) {
    return (start == 0 || s.charAt(start-1) != '!'),
  }
}

The Transform Filter gives you more freedom to format your text strings by letting you modify the implicit URI generated by the link text. Decoupling the link text from the target URI gives you more freedom in how you display data strings to your users.

To use the Transform Filter, implement the transformUrl method in your Transform Filter. When linkify finds a successful match it calls transformUrl, passing in the RegEx pattern used and the default URI string it creates. You can modify the matched string and return the URI as a target suitable to be "viewed" by another Android application.

The TransformFilter implementation shown in Listing 5-16 transforms the matched text into a lowercase URI.

class MyTransformFilter implements TransformFilter {
  public String transformUrl(Matcher match, String url) {
    return url.toLowerCase();
  }
}

Broadcasting Intents is simple. Within your application, construct the Intent you want to broadcast and use the sendBroadcast method to send it.

Set the action, data, and category of your Intent in a way that lets Broadcast Receivers accurately determine their interest. In this scenario the Intent action string is used to identify the event being broadcast, so it should be a unique string that identifies the event. By convention, action strings are constructed with the same form as Java package names:

public static final String NEW_LIFEFORM_DETECTED =
  "com.paad.action.NEW_LIFEFORM";

If you wish to include data within the Intent you can specify a URI using the Intent's data property. You can also include extras to add additional primitive values. Considered in terms of an event-driven paradigm, the extras equate to optional parameters passed into an event handler.

Listing 5-17 shows the basic creation of a broadcast Intent using the action defined previously, with additional event information stored as extras.

Intent intent = new Intent(NEW_LIFEFORM_DETECTED);
intent.putExtra("lifeformName", lifeformType);
intent.putExtra("longitude", currentLongitude);
intent.putExtra("latitude", currentLatitude);
sendBroadcast(intent);

Broadcast Receivers are used to listen for broadcast Intents. For a Broadcast Receiver to be enabled it needs to be registered, either in code or within the application manifest. When registering a Broadcast Receiver you must use an Intent Filter to specify which Intents it is listening for.

To create a new Broadcast Receiver, extend the BroadcastReceiver class and override the onReceive event handler as shown in Listing 5-18.

import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;

public class MyBroadcastReceiver extends BroadcastReceiver {
  @Override
  public void onReceive(Context context, Intent intent) {
    //TODO: React to the Intent received.
  }
}

The onReceive method will be executed when a broadcast Intent is received that matches the Intent Filter used to register the Receiver. The onReceive handler must complete within five seconds or the Force Close dialog will be displayed.

Applications with Broadcast Receivers registered in the manifest don't have to be running when the Intent is broadcast for the receivers to execute. They will be started automatically when a matching Intent is broadcast. This is excellent for resource management as it lets you create event-driven applications that will still respond to broadcast events even after they've been closed or killed.

Typically Broadcast Receivers will update content, launch Services, update Activity UI, or notify the user using the Notification Manager. The five-second execution limit ensures that major processing cannot, and should not, be done within the Broadcast Receiver itself.

Listing 5-19 shows how to implement a Broadcast Receiver. In the following sections you will learn how to register it in code or in your application manifest.

public class LifeformDetectedBroadcastReceiver extends BroadcastReceiver {

  public static final String BURN = "com.paad.alien.action.BURN_IT_WITH_FIRE";

  @Override
  public void onReceive(Context context, Intent intent) {
    // Get the lifeform details from the intent.
    Uri data = intent.getData();
    String type = intent.getStringExtra("type");
    double lat = intent.getDoubleExtra("latitude", 0);
    double lng = intent.getDoubleExtra("longitude", 0);
    Location loc = new Location("gps");
    loc.setLatitude(lat);
    loc.setLongitude(lng);

if (type.equals("alien")) {
      Intent startIntent = new Intent(BURN, data);
      startIntent.putExtra("latitude", lat);
      startIntent.putExtra("longitude", lng);

      context.startActivity(startIntent);
    }
  }
}

<receiver android:name=".LifeformDetectedBroadcastReceiver">
  <intent-filter>
    <action android:name="com.paad.action.NEW_LIFEFORM"/>
  </intent-filter>
</receiver>

// Create and register the broadcast receiver.
IntentFilter filter = new IntentFilter(NEW_LIFEFORM_DETECTED);
LifeformDetectedBroadcastReceiver r = new LifeformDetectedBroadcastReceiver();
registerReceiver(r, filter);

unregisterReceiver(receiver);

When broadcasting an Intent using sendBroadcast, your Intent will be received by all registered Broadcast Receivers, but you cannot control the order and they cannot propagate results.

In circumstances where the order in which the Broadcast Receivers receive the Intent is important, or where you require the Receivers to be able to affect the Intent being broadcast, you can use the sendOrderedBroadcast method.

sendOrderedBroadcast(intent, null);

Using this method, your Intent will be delivered to all registered Receivers in order of priority. You can optionally assign your own Broadcast Receiver, which will then receive the Intent after it has been handled (and potentially modified) by all the other registered Broadcast Receivers.

sendOrderedBroadcast(intent, null, myBroadcastReceiver, null,
                     Activity.RESULT_OK, null, null);

For efficiency reasons, some broadcasts are sticky. When you call registerReceiver specifying an Intent Filter that matches a sticky broadcast, the return value will be the sticky broadcast Intent. To broadcast a sticky Intent your application must have the BROADCAST_STICKY uses-permission.

sendStickyBroadcast(intent);

To remove a sticky intent call removeStickyBroadcast, passing in the sticky Intent to remove.

removeStickyBroadcast(intent);

Android broadcasts Intents for many of the system Services. You can use these messages to add functionality to your own projects based on system events such as time-zone changes, data-connection status, incoming SMS messages, or phone calls.

The following list introduces some of the native actions exposed as constants in the Intent class; these actions are used primarily to track device status changes.

A comprehensive list of the broadcast actions used and transmitted natively by Android to notify applications of system state changes is available at http://developer.android.com/reference/android/content/Intent.html

Android also uses broadcast Intents to announce application-specific events like incoming SMS messages. The actions and Intents associated with these events will be discussed in more detail in later chapters when you learn more about the associated Services.

This example extends the To-Do List project, storing each item as a ToDoItem object that includes the date each item was created.

You will extend ArrayAdapter to bind a collection of ToDoItem objects to the ListView and customize the layout used to display each List View item.

Figure 5-4. FIGURE 5-4

The SimpleCursorAdapter lets you bind a Cursor to a List View, using a custom layout definition to define the layout of each row/item, which is populated by a row's column values.

Construct a Simple Cursor Adapter by passing in the current context, a layout resource, a Cursor, and two arrays: one that contains the names of the columns to be used, and a second (equally-sized) array that has resource IDs for the Views to use to display the contents of the corresponding columns.

Listing 5-25 shows how to construct a Simple Cursor Adapter to display contact information.

String uriString = "content://contacts/people/";
Cursor myCursor = managedQuery(Uri.parse(uriString), null, null, null);

String[] fromColumns = new String[] {People.NUMBER, People.NAME};

int[] toLayoutIDs = new int[] { R.id.nameTextView, R.id.numberTextView};

SimpleCursorAdapter myAdapter;
myAdapter = new SimpleCursorAdapter(this,
                                    R.layout.simplecursorlayout,

myCursor,
                                    fromColumns,
                                    toLayoutIDs);

myListView.setAdapter(myAdapter);

The Simple Cursor Adapter was used earlier in this chapter in the Contact Picker example. You'll learn more about Content Providers and Cursors in Chapter 7, where you'll also find more Simple Cursor Adapter examples.

The AlertDialog class is one of the most versatile Dialog-class implementations. It offers a number of options that let you construct screens for some of the most common dialog-box use cases, including:

To construct the Alert Dialog us er interface, create a new AlertDialog.Builder object as follows:

AlertDialog.Builder ad = new AlertDialog.Builder(context);

You can then assign values for the title and message to display, and optionally assign values to be used for any buttons, selection items, and text input boxes you wish to display. That includes setting event listeners to handle user interaction.

Listing 5-28 gives an example of a new Alert Dialog used to display a message and offer two button options to continue. Clicking either button will close the Dialog after executing the attached Click Listener.

Context context = MyActivity.this;
String title = "It is Pitch Black";
String message = "You are likely to be eaten by a grue.";
String button1String = "Go Back";
String button2String = "Move Forward";

AlertDialog.Builder ad = new AlertDialog.Builder(context);
ad.setTitle(title);
ad.setMessage(message);
ad.setPositiveButton(button1String,

new OnClickListener() {
                       public void onClick(DialogInterface dialog, int arg1) {
                         eatenByGrue();
                       }
                     });
ad.setNegativeButton(button2String,
                     new OnClickListener(){
                       public void onClick(DialogInterface dialog, int arg1) {
                         // do nothing
                       }
                     });
ad.setCancelable(true);
ad.setOnCancelListener(new OnCancelListener() {
                             public void onCancel(DialogInterface dialog) {
                               eatenByGrue();
                             }
                       });

To display an Alert Dialog that you've created call show:

ad.show();

A better alternative is using your Activity's onCreateDialog and onPrepareDialog handlers to create dialog instances that can persist state. This technique is examined later in this chapter.

One of the major uses of dialog boxes is to provide an interface for user input. Android includes several specialist dialog boxes that encapsulate controls designed to facilitate common user-input requests. They include the following: