diff --git a/docs/html/images/training/basics/intent-chooser.png b/docs/html/images/training/basics/intent-chooser.png new file mode 100644 index 0000000000000..8a8d339384a1b Binary files /dev/null and b/docs/html/images/training/basics/intent-chooser.png differ diff --git a/docs/html/training/basics/intents/sending.jd b/docs/html/training/basics/intents/sending.jd index a71c8f94340a9..bfd8f9bcf8276 100644 --- a/docs/html/training/basics/intents/sending.jd +++ b/docs/html/training/basics/intents/sending.jd @@ -17,6 +17,7 @@ next.link=result.html
+ Figure 2. Example of the chooser dialog that appears +when you use {@link android.content.Intent#createChooser createChooser()} to ensure +that the user is always shown a list of apps that respond to your intent.
+Notice that when you start an activity by passing your {@link android.content.Intent} to {@link +android.app.Activity#startActivity startActivity()} and there is more than one app that responds to +the intent, the user can select which app to use by default (by selecting a checkbox at the bottom +of the dialog; see figure 1). This is nice when performing an action for which the user +generally wants to use the same app every time, such as when opening a web page (users +likely use just one web browser) or taking a photo (users likely prefer one camera). However, if +the action to be performed could be handled by multiple apps and the user might +prefer a different app each time—such as a "share" action, for which users might have several +apps through which they might share an item—you should explicitly show a chooser dialog, +which forces the user to select which app to use for the action every time (the user cannot select a +default app for the action).
+ +To show the chooser, create an {@link android.content.Intent} using {@link +android.content.Intent#createChooser createChooser()} and pass it to {@link +android.app.Activity#startActivity startActivity()}. For example:
+ ++Intent intent = new Intent(Intent.ACTION_SEND); +... + +// Always use string resources for UI text. This says something like "Share this photo with" +String title = getResources().getText(R.string.chooser_title); +// Create and start the chooser +Intent chooser = Intent.createChooser(intent, title); +startActivity(chooser); ++ +
This displays a dialog with a list of apps that respond to the intent passed to the {@link +android.content.Intent#createChooser createChooser()} method and uses the supplied text as the +dialog title.
+ +