ShortcutManager executes operations on an app's set of shortcuts, which
+ * represent specific tasks and actions that users can perform within your app. This page lists
+ * components of the ShortcutManager class that you can use to create and manage
+ * sets of shortcuts.
*
- *
An app's shortcuts represent specific tasks and actions that users can perform within your - * app. When a user selects a shortcut in the currently-active launcher, your app opens an activity - * other than the app's starting activity, provided that the currently-active launcher supports app - * shortcuts.
+ *To learn about methods that retrieve information about a single shortcut—including
+ * identifiers, type, and status—read the
+ * ShortcutInfo reference.
*
- *
The types of shortcuts that you create for your app depend on the app's key use cases. For - * example, an email app may publish the "compose new email" shortcut, which allows the app to - * directly open the compose activity.
- * - *Note: Only main activities—activities that handle the - * {@link Intent#ACTION_MAIN} action and the {@link Intent#CATEGORY_LAUNCHER} category—can - * have shortcuts. If an app has multiple main activities, you need to define the set of shortcuts - * for each activity. - * - *
This page discusses the implementation details of the ShortcutManager class. For
- * definitions of key terms and guidance on performing operations on shortcuts within your app, see
- * the App Shortcuts feature guide.
- *
- *
Important security note: All shortcut information is stored in - * credential encrypted storage, so your app - * cannot access a user's shortcuts until after they've unlocked the device. - * - *
Static shortcuts and dynamic shortcuts are shown in a supported launcher when the user - * performs a specific gesture. On currently-supported launchers, the gesture is a long-press on the - * app's launcher icon, but the actual gesture may be different on other launcher apps. - * - *
The {@link LauncherApps} class provides APIs for launcher apps to access shortcuts. - * - *
Because pinned shortcuts appear in the launcher itself, they're always visible. A pinned - * shortcut is removed from the launcher only in the following situations: - *
Because the system performs - * backup and restore on pinned - * shortcuts automatically, these shortcuts' IDs should contain either stable, constant strings or - * server-side identifiers, rather than identifiers generated locally that might not make sense on - * other devices. - * - *
When the launcher displays an app's shortcuts, they should appear in the following order: - * - *
Within each shortcut type (static and dynamic), shortcuts are sorted in order of increasing - * rank according to {@link ShortcutInfo#getRank()}.
- * - *Shortcut ranks are non-negative, sequential integers that determine the order in which - * shortcuts appear, assuming that the shortcuts are all in the same category. You can update ranks - * of existing shortcuts when you call {@link #updateShortcuts(List)}, - * {@link #addDynamicShortcuts(List)}, or {@link #setDynamicShortcuts(List)}. - * - *
Note: Ranks are auto-adjusted so that they're unique for each type of - * shortcut (static or dynamic). For example, if there are 3 dynamic shortcuts with ranks 0, 1 and - * 2, adding another dynamic shortcut with a rank of 1 represents a request to place this shortcut - * at the second position. In response, the third and fourth shortcuts move closer to the bottom of - * the shortcut list, with their ranks changing to 2 and 3, respectively. - * - *
A string literal, which represents the shortcut when a {@code ShortcutManager} object - * performs operations on it.
- *Note: You cannot set this attribute's value to a resource string, such
- * as @string/foo.
Whether the user can interact with the shortcut from a supported launcher.
- *The default value is {@code true}. If you set it to {@code false}, you should also set - * {@code android:shortcutDisabledMessage} to a message that explains why you've disabled the - * shortcut. If you don't think you need to provide such a message, it's easiest to just remove - * the shortcut from the XML file entirely, rather than changing the values of the shortcut's - * {@code android:enabled} and {@code android:shortcutDisabledMessage} attributes. - *
The bitmap or - * adaptive icon that the - * launcher uses when displaying the shortcut to the user. This value can be either the path to an - * image or the resource file that contains the image. Use adaptive icons whenever possible to - * improve performance and consistency.
- *Note: Shortcut icons cannot include - * tints. - *
A concise phrase that describes the shortcut's purpose. For more information, see - * {@link ShortcutInfo.Builder#setShortLabel(CharSequence)}.
- *Note: This attribute's value must be a resource string, such as
- * @string/shortcut_short_label.
An extended phrase that describes the shortcut's purpose. If there's enough space, the - * launcher displays this value instead of {@code android:shortcutShortLabel}. For more - * information, see {@link ShortcutInfo.Builder#setLongLabel(CharSequence)}.
- *Note: This attribute's value must be a resource string, such as
- * @string/shortcut_long_label.
The message that appears in a supported launcher when the user attempts to launch a - * disabled shortcut. The message should explain to the user why the shortcut is now disabled. - * This attribute's value has no effect if {@code android:enabled} is {@code true}.
- *Note: This attribute's value must be a resource string, such as
- * @string/shortcut_disabled_message.
The XML file that lists an app's static shortcuts supports the following elements inside each
- * {@code
The action that the system launches when the user selects the shortcut. This intent must - * provide a value for the {@code android:action} attribute.
- *You can provide multiple intents for a single shortcut. If you do so, the last defined - * activity is launched, and the other activities are placed in the - * back stack. See - * Using Static Shortcuts and the - * {@link android.app.TaskStackBuilder} class reference for details.
- *Note: This {@code intent} element cannot include string resources.
- *To learn more about how to configure intents, see - * Using intents.
- *Provides a grouping for the types of actions that your app's shortcuts perform, such as - * creating new chat messages.
- *For a list of supported shortcut categories, see the {@link ShortcutInfo} class reference - * for a list of supported shortcut categories. - *
Each app's launcher icon can contain at most {@link #getMaxShortcutCountPerActivity()} number - * of static and dynamic shortcuts combined. There is no limit to the number of pinned shortcuts - * that an app can create, though. - * - *
When a dynamic shortcut is pinned, even when the publisher removes it as a dynamic shortcut, - * the pinned shortcut is still visible and launchable. This allows an app to have more than - * {@link #getMaxShortcutCountPerActivity()} number of shortcuts. - * - *
As an example, suppose {@link #getMaxShortcutCountPerActivity()} is 5: - *
The publisher app has to remove c1, c2, and c3 because it can't have more than 5 dynamic - * shortcuts. However, c1, c2, and c3 are still pinned shortcuts that the user can access and - * launch. - *
At this point, the user can access a total of 8 shortcuts that link to activities in the - * publisher app, including the 3 pinned shortcuts, even though an app can have at most 5 - * dynamic shortcuts. - * - *
The {@link #addDynamicShortcuts(List)} and {@link #setDynamicShortcuts(List)} methods - * can also be used to update existing shortcuts with the same IDs, but they cannot be - * used for updating non-dynamic, pinned shortcuts because these 2 methods try to convert the - * given lists of shortcuts to dynamic shortcuts. - *
- * Dynamic shortcuts can be published with any set of {@link Intent#addFlags Intent} flags. - * Typically, {@link Intent#FLAG_ACTIVITY_CLEAR_TASK} is specified, possibly along with other - * flags; otherwise, if the app is already running, the app is simply brought to - * the foreground, and the target activity might not appear. - * - *
Static shortcuts cannot have custom intent flags. - * The first intent of a static shortcut will always have {@link Intent#FLAG_ACTIVITY_NEW_TASK} - * and {@link Intent#FLAG_ACTIVITY_CLEAR_TASK} set. This means, when the app is already running, all - * the existing activities in your app are destroyed when a static shortcut is launched. - * If this behavior is not desirable, you can use a trampoline activity, or an invisible - * activity that starts another activity in {@link Activity#onCreate}, then calls - * {@link Activity#finish()}: - *
AndroidManifest.xml file, the trampoline activity should include the
- * attribute assignment {@code android:taskAffinity=""}.
- * When rate limiting is active, - * {@link #isRateLimitingActive()} returns {@code true}. - * - *
Rate limiting is reset upon certain events, so even background apps can call these APIs until - * the rate limit is reached again. These events include the following: - *
Apps should update dynamic and pinned shortcuts when they receive the - * {@link Intent#ACTION_LOCALE_CHANGED} broadcast, indicating that the system locale has changed. - *
When the system locale changes, rate - * limiting is reset, so even background apps can add and update dynamic shortcuts until the - * rate limit is reached again. + *
For guidance about using shortcuts, see + * App shortcuts. * *
See the class level javadoc for details. + *
For details, see + * Rate limiting. * * @throws IllegalStateException when the user is locked. */ @@ -632,7 +402,9 @@ public class ShortcutManager { * Apps that publish shortcuts should call this method whenever the user * selects the shortcut containing the given ID or when the user completes * an action in the app that is equivalent to selecting the shortcut. - * For more details, see the Javadoc for the {@link ShortcutManager} class + * For more details, read about + * + * tracking shortcut usage. * *
The information is accessible via {@link UsageStatsManager#queryEvents} * Typically, launcher apps use this information to build a prediction model @@ -700,7 +472,9 @@ public class ShortcutManager { * @param resultIntent If not null, this intent will be sent when the shortcut is pinned. * Use {@link android.app.PendingIntent#getIntentSender()} to create an {@link IntentSender}. * To avoid background execution limits, use an unexported, manifest-declared receiver. - * For more details, see the overview documentation for the {@link ShortcutManager} class. + * For more details, see + * + * Creating pinned shortcuts. * * @return {@code TRUE} if the launcher supports this feature. Note the API will return without * waiting for the user to respond, so getting {@code TRUE} from this API does *not* mean