Figure 1. Screenshot of {@link android.content.Intent#ACTION_SEND} intent chooser on a handset.
When you construct an intent, you must specify the action you want the intent to "trigger." Android defines several actions, including {@link android.content.Intent#ACTION_SEND} which, as you can probably guess, indicates that the intent is sending data from one activity to another, even across process boundaries. To send data to another activity, all you need to do is specify the data and its type, the system will identify compatible receiving activities and display them to the user (if there are multiple options) or immediately start the activity (if there is only one option). Similarly, you can advertise the data types that your activities support receiving from other applications by specifying them in your manifest.
Sending and receiving data between applications with intents is most commonly used for social sharing of content. Intents allow users to share information quickly and easily, using their favorite applications.
Note: The best way to add a share action item to an {@link android.app.ActionBar} is to use {@link android.widget.ShareActionProvider}, which became available in API level 14. {@link android.widget.ShareActionProvider} is discussed in the lesson about Adding an Easy Share Action.
Figure 1. Screenshot of {@link android.content.Intent#ACTION_SEND} intent chooser on a handset.
The most straightforward and common use of the {@link android.content.Intent#ACTION_SEND} action is sending text content from one activity to another. For example, the built-in Browser app can share the URL of the currently-displayed page as text with any application. This is useful for sharing an article or website with friends via email or social networking. Here is the code to implement this type of sharing:
Intent sendIntent = new Intent();
sendIntent.setAction(Intent.ACTION_SEND);
sendIntent.putExtra(Intent.EXTRA_TEXT, "This is my text to send.");
sendIntent.setType("text/plain");
startActivity(sendIntent);
If there's an installed application with a filter that matches {@link android.content.Intent#ACTION_SEND} and MIME type text/plain, the Android system will run it; if more than one application matches, the system displays a disambiguation dialog (a "chooser") that allows the user to choose an app.
However, if you call {@link android.content.Intent#createChooser(android.content.Intent, CharSequence) Intent.createChooser()}, passing it your {@link android.content.Intent} object, it returns a version of your intent that will always display the chooser. This has some advantages:
Here's the updated code:
Intent sendIntent = new Intent();
sendIntent.setAction(Intent.ACTION_SEND);
sendIntent.putExtra(Intent.EXTRA_TEXT, "This is my text to send.");
sendIntent.setType("text/plain");
startActivity(Intent.createChooser(sendIntent, getResources().getText(R.string.send_to)));
The resulting dialog is shown in figure 1.
Optionally, you can set some standard extras for the intent: {@link android.content.Intent#EXTRA_EMAIL}, {@link android.content.Intent#EXTRA_CC}, {@link android.content.Intent#EXTRA_BCC}, {@link android.content.Intent#EXTRA_SUBJECT}. If the receiving application is not designed to use them, it simply ignores them.
Note: Some e-mail applications, such as Gmail, expect a {@link java.lang.String String[]} for extras like {@link android.content.Intent#EXTRA_EMAIL} and {@link android.content.Intent#EXTRA_CC}, use {@link android.content.Intent#putExtra(String,String[]) putExtra(String, String[])} to add these to your intent.
Binary data is shared using the {@link android.content.Intent#ACTION_SEND} action combined with setting the appropriate MIME type and placing the URI to the data in an extra named {@link android.content.Intent#EXTRA_STREAM}. This is commonly used to share an image but can be used to share any type of binary content:
Intent shareIntent = new Intent();
shareIntent.setAction(Intent.ACTION_SEND);
shareIntent.putExtra(Intent.EXTRA_STREAM, uriToImage);
shareIntent.setType("image/jpeg");
startActivity(Intent.createChooser(shareIntent, getResources().getText(R.string.send_to)));
Note the following:
To share multiple pieces of content, use the {@link android.content.Intent#ACTION_SEND_MULTIPLE} action together with a list of URIs pointing to the content. The MIME type varies according to the mix of content you're sharing. For example, if you share 3 JPEG images, the type is still {@code "image/jpeg"}. For a mixture of image types, it should be {@code "image/*"} to match an activity that handles any type of image. You should only use {@code "*/*"} if you're sharing out a wide variety of types. As previously stated, it's up to the receiving application to parse and process your data. Here's an example:
ArrayList<Uri> imageUris = new ArrayList<Uri>();
imageUris.add(imageUri1); // Add your image URIs here
imageUris.add(imageUri2);
Intent shareIntent = new Intent();
shareIntent.setAction(Intent.ACTION_SEND_MULTIPLE);
shareIntent.putParcelableArrayListExtra(Intent.EXTRA_STREAM, imageUris);
shareIntent.setType("image/*");
startActivity(Intent.createChooser(shareIntent, "Share images to.."));
As before, make sure the provided {@link android.net.Uri URIs} point to data that a receiving application can access.