Skip to content

Most visited

Recently visited

navigation

ShortcutManager

public class ShortcutManager
extends Object

java.lang.Object
   ↳ android.content.pm.ShortcutManager


The ShortcutManager manages an app's shortcuts. Shortcuts provide users with quick access to activities other than an app's main activity in the currently-active launcher. For example, an email app may publish the "compose new email" action, which will directly open the compose activity. The ShortcutInfo class contains information about each of the shortcuts themselves.

Static Shortcuts and Dynamic Shortcuts

There are several different types of shortcuts:

  • Static shortcuts are declared in a resource XML file, which is referenced in the publisher app's AndroidManifest.xml file. These shortcuts are visually associated with an app's launcher icon.

    Static shortcuts are published when an app is installed, and the details of these shortcuts change when an app is upgraded with an updated XML file. Static shortcuts are immutable, and their definitions, such as icons and labels, cannot be changed dynamically without upgrading the publisher app.

  • Dynamic shortcuts are published at runtime using this class's APIs. These shortcuts are visually associated with an app's launcher icon. Apps can publish, update, and remove dynamic shortcuts at runtime.

Only main activities—activities that handle the MAIN action and the LAUNCHER category—can have shortcuts. If an app has multiple main activities, these activities have different sets of shortcuts.

Static shortcuts and dynamic shortcuts are shown in a supported launcher when the user long-presses on an app's launcher icon. Note that the actual gesture may be different depending on the launcher app.

Each launcher icon can have at most getMaxShortcutCountPerActivity() number of static and dynamic shortcuts combined.

Pinning Shortcuts

Apps running in the foreground can also pin shortcuts at runtime, subject to user permission, using this class's APIs. Each pinned shortcut is a copy of a static shortcut or a dynamic shortcut. Although users can pin a shortcut multiple times, the system calls the pinning API only once to complete the pinning process. Unlike static and dynamic shortcuts, pinned shortcuts appear as separate icons, visually distinct from the app's launcher icon, in the launcher. There is no limit to the number of pinned shortcuts that an app can create.

Pinned shortcuts cannot be removed by publisher apps. They're removed only when the user removes them, when the publisher app is uninstalled, or when the user performs the clear data action on the publisher app from the device's Settings app.

However, the publisher app can disable pinned shortcuts so they cannot be started. See the following sections for details.

Updating and Disabling Shortcuts

When a dynamic shortcut is pinned, even when the publisher removes it as a dynamic shortcut, the pinned shortcut will still be visible and launchable. This allows an app to have more than getMaxShortcutCountPerActivity() number of shortcuts.

For example, suppose getMaxShortcutCountPerActivity() is 5:

  1. A chat app publishes 5 dynamic shortcuts for the 5 most recent conversations (c1, c2, ..., c5).
  2. The user pins all 5 of the shortcuts.
  3. Later, the user has started 3 additional conversations (c6, c7, and c8), so the publisher app re-publishes its dynamic shortcuts. The new dynamic shortcut list is: c4, c5, ..., c8. The publisher app has to remove c1, c2, and c3 because it can't have more than 5 dynamic shortcuts.
  4. However, even though c1, c2, and c3 are no longer dynamic shortcuts, the pinned shortcuts for these conversations are still available and launchable.
  5. 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.
  6. The app can use updateShortcuts(List) to update any of the existing 8 shortcuts, when, for example, the chat peers' icons have changed.
The addDynamicShortcuts(List) and 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 two methods try to convert the given lists of shortcuts to dynamic shortcuts.

Disabling Static Shortcuts

When an app is upgraded and the new version no longer uses a static shortcut that appeared in the previous version, this deprecated shortcut isn't published as a static shortcut.

If the deprecated shortcut is pinned, then the pinned shortcut will remain on the launcher, but it's disabled automatically. When a pinned shortcut is disabled, this class's APIs cannot update it.

Disabling Dynamic Shortcuts

Sometimes pinned shortcuts become obsolete and may not be usable. For example, a pinned shortcut to a group chat becomes unusable when the associated group chat is deleted. In cases like this, apps should use disableShortcuts(List), which removes the specified dynamic shortcuts and also makes any specified pinned shortcuts un-launchable. The disableShortcuts(List, CharSequence) method can also be used to disable shortcuts and show users a custom error message when they attempt to launch the disabled shortcuts.

Publishing Static Shortcuts

In order to add static shortcuts to your app, first add <meta-data android:name="android.app.shortcuts" /> to your main activity in AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
             package="com.example.myapplication">
  <application ... >
    <activity android:name="Main">
      <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
      </intent-filter>
      <meta-data android:name="android.app.shortcuts"
                 android:resource="@xml/shortcuts" />
    </activity>
  </application>
</manifest>
 
Then, define your app's static shortcuts in the res/xml/shortcuts.xml file:
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <shortcut
    android:shortcutId="compose"
    android:enabled="true"
    android:icon="@drawable/compose_icon"
    android:shortcutShortLabel="@string/compose_shortcut_short_label1"
    android:shortcutLongLabel="@string/compose_shortcut_long_label1"
    android:shortcutDisabledMessage="@string/compose_disabled_message1">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.example.myapplication"
      android:targetClass="com.example.myapplication.ComposeActivity" />
    <!-- If your shortcut is associated with multiple intents, include them
         here. The last intent in the list is what the user sees when they
         launch this shortcut. -->
    <categories android:name="android.shortcut.conversation" />
  </shortcut>
  <!-- Specify more shortcuts here. -->
</shortcuts>
 
The following list includes descriptions for the different attributes within a static shortcut:
android:shortcutId
Mandatory shortcut ID.

This must be a string literal. A resource string, such as @string/foo, cannot be used.

android:enabled
Default is true. Can be set to false in order to disable a static shortcut that was published in a previous version and set a custom disabled message. If a custom disabled message is not needed, then a static shortcut can be simply removed from the XML file rather than keeping it with enabled="false".
android:icon
Shortcut icon.
android:shortcutShortLabel
Mandatory shortcut short label. See setShortLabel(CharSequence).

This must be a resource string, such as @string/shortcut_label.

android:shortcutLongLabel
Shortcut long label. See setLongLabel(CharSequence).

This must be a resource string, such as @string/shortcut_long_label.

android:shortcutDisabledMessage
When android:enabled is set to false, this attribute is used to display a custom disabled message.

This must be a resource string, such as @string/shortcut_disabled_message.

intent
Intent to launch when the user selects the shortcut. android:action is mandatory. See Using intents for the other supported tags. You can provide multiple intents for a single shortcut so that the last defined activity is launched with the other activities in the back stack. See TaskStackBuilder for details.

Note: String resources may not be used within an <intent> element.

categories
Specify shortcut categories. Currently only SHORTCUT_CATEGORY_CONVERSATION is defined in the framework.

Publishing Dynamic Shortcuts

Apps can publish dynamic shortcuts with setDynamicShortcuts(List) or addDynamicShortcuts(List). The updateShortcuts(List) method can also be used to update existing, mutable shortcuts. Use removeDynamicShortcuts(List) or removeAllDynamicShortcuts() to remove dynamic shortcuts.

The following code snippet shows how to create a single dynamic shortcut:

ShortcutManager shortcutManager = getSystemService(ShortcutManager.class);

ShortcutInfo shortcut = new ShortcutInfo.Builder(this, "id1")
    .setShortLabel("Web site")
    .setLongLabel("Open the web site")
    .setIcon(Icon.createWithResource(context, R.drawable.icon_website))
    .setIntent(new Intent(Intent.ACTION_VIEW,
                   Uri.parse("https://www.mysite.example.com/")))
    .build();

shortcutManager.setDynamicShortcuts(Arrays.asList(shortcut));
 

Publishing Pinned Shortcuts

Apps can pin an existing shortcut (either static or dynamic) or an entirely new shortcut to a supported launcher programatically using requestPinShortcut(ShortcutInfo, IntentSender). You pass two arguments into this method:

  • A ShortcutInfo object – If the shortcut already exists, this object should contain only the shortcut's ID. Otherwise, the new ShortcutInfo object must contain an ID, an intent, and a short label for the new shortcut.
  • A PendingIntent object – This intent represents the callback that your app receives if the shortcut is successfully pinned to the device's launcher.

    Note: If the user doesn't allow the shortcut to be pinned to the launcher, the pinning process fails, and the Intent object that is passed into this PendingIntent object isn't executed.

    Note: Due to background execution limits introduced in Android O, it's best to use a manifest-declared receiver to receive a callback.

    Also, to prevent other apps from invoking the receiver, add the attribute assignment android:exported="false" to the receiver's manifest entry.

The following code snippet shows how to pin a single shortcut that already exists and is enabled:
ShortcutManager mShortcutManager =
        context.getSystemService(ShortcutManager.class);

if (mShortcutManager.isRequestPinShortcutSupported()) {

    // This example defines a new shortcut; that is, this shortcut hasn't
    // been published before.
    ShortcutInfo pinShortcutInfo = new ShortcutInfo.Builder()
            .setIcon(myIcon)
            .setShortLabel("My awesome shortcut")
            .setIntent(myIntent)
            .build();

    PendingIntent resultPendingIntent = null;

    // Create the following Intent and PendingIntent objects only if your app
    // needs to be notified that the user allowed the shortcut to be pinned.
    // Use a boolean value, such as "appNeedsNotifying", to define this behavior.
    if (appNeedsNotifying) {
        // We assume here the app has a manifest-declared receiver "MyReceiver".
        Intent pinnedShortcutCallbackIntent = new Intent(context, MyReceiver.class);

        // Configure the intent so that your app's broadcast receiver gets
        // the callback successfully.
        PendingIntent successCallback = PendingIntent.createBroadcast(context, 0,
                pinnedShortcutCallbackIntent);

        resultPendingIntent = successCallback.getIntentSender();
    }

    mShortcutManager.requestPinShortcut(pinShortcutInfo, resultPendingIntent);
}
 

Note: As you add logic in your app to make requests to pin shortcuts, keep in mind that not all launchers support pinning of shortcuts. To determine whether your app can complete this process on a particular device, check the return value of isRequestPinShortcutSupported(). Based on this return value, you might decide to hide the option in your app that allows users to pin a shortcut.

Note: See also the support library APIs isRequestPinShortcutSupported(Context) and requestPinShortcut(Context, ShortcutInfoCompat, IntentSender), which works on Android versions lower than O by falling back to the deprecated private intent com.android.launcher.action.INSTALL_SHORTCUT.

Custom Activity for Pinning Shortcuts

You can also create a specialized activity that helps users create shortcuts, complete with custom options and a confirmation button. In your app's manifest file, add ACTION_CREATE_SHORTCUT to the activity's <intent-filter> element, as shown in the following snippet:

<manifest>
    ...
    <application>
        <activity android:name="com.example.MyCustomPromptToPinShortcut" ... >
            <intent-filter
                    action android:name="android.intent.action.ACTION_CREATE_SHORTCUT">
            ...
            </intent-filter>
        </activity>
        ...
    </application>
</manifest>
 

When you use this specialized activity in your app, the following sequence of steps takes place:

  1. The user attempts to create a shortcut, triggering the system to start the specialized activity.
  2. The user sets options for the shortcut.
  3. The user selects the confirmation button, allowing your app to create the shortcut using the createShortcutResultIntent(ShortcutInfo) method. This method returns an Intent, which your app relays back to the previously-executing activity using setResult(int).
  4. Your app calls finish() on the activity used for creating the customized shortcut.

Shortcut Intents

Dynamic shortcuts can be published with any set of Intent flags. Typically, 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 may not appear.

The setIntents(Intent[]) method can be used instead of setIntent(Intent) with TaskStackBuilder in order to launch an activity with other activities in the back stack. When the user selects a shortcut to load an activity with a back stack, then presses the back key, a parent activity from the same app will be shown instead of the user being navigated back to the launcher.

Static shortcuts can also have multiple intents to achieve the same effect. In order to associate multiple Intent objects with a shortcut, simply list multiple <intent> elements within a single <shortcut> element. The last intent specifies what the user sees when they launch a shortcut.

Static shortcuts cannot have custom intent flags. The first intent of a static shortcut will always have FLAG_ACTIVITY_NEW_TASK and FLAG_ACTIVITY_CLEAR_TASK set. This means, when the app is already running, all the existing activities will be 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 onCreate(Bundle), then calls finish(). The first activity should include an attribute setting of android:taskAffinity="" in the app's AndroidManifest.xml file, and the intent within the static shortcut should point at this first activity.

Showing New Information in a Shortcut

In order to avoid confusion, you should not use updateShortcuts(List) to update a shortcut so that it contains conceptually different information.

For example, a phone app may publish the most frequently called contact as a dynamic shortcut. Over time, this contact may change. When it does, the app should represent the changed contact with a new shortcut that contains a different ID, using either setDynamicShortcuts(List) or addDynamicShortcuts(List), rather than updating the existing shortcut with updateShortcuts(List). This is because when the shortcut is pinned, changing it to reference a different contact will likely confuse the user.

On the other hand, when the contact's information has changed, such as the name or picture, the app should use updateShortcuts(List) so that the pinned shortcut is updated too.

Shortcut Display Order

When the launcher displays the shortcuts that are associated with a particular launcher icon, the shortcuts should appear in the following order:
  • First show static shortcuts (if isDeclaredInManifest() is true), and then show dynamic shortcuts (if isDynamic() is true).
  • Within each category of shortcuts (static and dynamic), sort the shortcuts in order of increasing rank according to 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. Ranks of existing shortcuts can be updated with updateShortcuts(List). You can also use addDynamicShortcuts(List) and setDynamicShortcuts(List).

Ranks are auto-adjusted so that they're unique for each target activity in each category (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.

Rate Limiting

Calls to setDynamicShortcuts(List), addDynamicShortcuts(List), and updateShortcuts(List) may be rate-limited when called by background apps, or apps with no foreground activity or service. When you attempt to call these methods from a background app after exceeding the rate limit, these APIs return false.

Apps with a foreground activity or service are not rate-limited.

Rate-limiting is reset upon certain events, so that even background apps can call these APIs until the rate limit is reached again. These events include the following:

  • An app comes to the foreground.
  • The system locale changes.
  • The user performs the inline reply action on a notification.

When rate-limiting is active, isRateLimitingActive() returns true.

Resetting rate-limiting for testing

If your app is rate-limited during development or testing, you can use the Reset ShortcutManager rate-limiting development option or the following adb command to reset it:

$ adb shell cmd shortcut reset-throttling [ --user USER-ID ]
 

Handling System Locale Changes

Apps should update dynamic and pinned shortcuts when the system locale changes using the ACTION_LOCALE_CHANGED broadcast.

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.

Backup and Restore

When an app has the android:allowBackup="true" attribute assignment included in its AndroidManifest.xml file, pinned shortcuts are backed up automatically and are restored when the user sets up a new device.

Categories of shortcuts that are backed up

  • Pinned shortcuts are backed up. Bitmap icons are not backed up by the system, so launcher apps should back them up and restore them so that the user still sees icons for pinned shortcuts on the launcher. Apps can always use updateShortcuts(List) to re-publish icons.
  • Static shortcuts aren't backed up, but when an app is re-installed on a new device, they are re-published from the AndroidManifest.xml file.
  • Dynamic shortcuts aren't backed up.

Because dynamic shortcuts are not restored, it is recommended that apps check currently-published dynamic shortcuts using getDynamicShortcuts() each time they are launched, and they should re-publish dynamic shortcuts when necessary.

public class MainActivity extends Activity {
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ShortcutManager shortcutManager =
                getSystemService(ShortcutManager.class);

        if (shortcutManager.getDynamicShortcuts().size() == 0) {
            // Application restored. Need to re-publish dynamic shortcuts.
            if (shortcutManager.getPinnedShortcuts().size() > 0) {
                // Pinned shortcuts have been restored. Use
                // updateShortcuts() to make sure they contain
                // up-to-date information.
            }
        }
    }
    // ...
}
 

Backup/restore and shortcut IDs

Because pinned shortcuts are backed up and restored on new devices, shortcut IDs should contain either stable, constant strings or server-side identifiers, rather than identifiers generated locally that might not make sense on other devices.

Report Shortcut Usage and Prediction

Launcher apps may be capable of predicting which shortcuts will most likely be used at a given time by examining the shortcut usage history data.

In order to provide launchers with such data, publisher apps should report the shortcuts that are used with reportShortcutUsed(String) when a shortcut is selected, or when an action equivalent to a shortcut is taken by the user even if it wasn't started with the shortcut.

For example, suppose a navigation app supports "navigate to work" as a shortcut. It should then report when the user selects this shortcut and when the user chooses to navigate to work within the app itself. This helps the launcher app learn that the user wants to navigate to work at a certain time every weekday, and it can then show this shortcut in a suggestion list at the right time.

Launcher API

The LauncherApps class provides APIs for launcher apps to access shortcuts.

Direct Boot and Shortcuts

All shortcut information is stored in credential encrypted storage, so no shortcuts can be accessed when the user is locked.

Instances of this class must be obtained using Context.getSystemService(Class) with the argument ShortcutManager.class or Context.getSystemService(String) with the argument Context.SHORTCUT_SERVICE.

Summary

Public methods

boolean addDynamicShortcuts(List<ShortcutInfo> shortcutInfoList)

Publish the list of dynamic shortcuts.

Intent createShortcutResultIntent(ShortcutInfo shortcut)

Returns an Intent which can be used by the default launcher to pin a shortcut containing the given ShortcutInfo.

void disableShortcuts(List<String> shortcutIds)

Disable pinned shortcuts.

void disableShortcuts(List<String> shortcutIds, CharSequence disabledMessage)

Disable pinned shortcuts, showing the user a custom error message when they try to select the disabled shortcuts.

void enableShortcuts(List<String> shortcutIds)

Re-enable pinned shortcuts that were previously disabled.

List<ShortcutInfo> getDynamicShortcuts()

Return all dynamic shortcuts from the caller app.

int getIconMaxHeight()

Return the max height for icons, in pixels.

int getIconMaxWidth()

Return the max width for icons, in pixels.

List<ShortcutInfo> getManifestShortcuts()

Return all static (manifest) shortcuts from the caller app.

int getMaxShortcutCountPerActivity()

Return the maximum number of static and dynamic shortcuts that each launcher icon can have at a time.

List<ShortcutInfo> getPinnedShortcuts()

Return all pinned shortcuts from the caller app.

boolean isRateLimitingActive()

Return true when rate-limiting is active for the caller app.

boolean isRequestPinShortcutSupported()

Return TRUE if the app is running on a device whose default launcher supports requestPinShortcut(ShortcutInfo, IntentSender).

void removeAllDynamicShortcuts()

Delete all dynamic shortcuts from the caller app.

void removeDynamicShortcuts(List<String> shortcutIds)

Delete dynamic shortcuts by ID.

void reportShortcutUsed(String shortcutId)

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.

boolean requestPinShortcut(ShortcutInfo shortcut, IntentSender resultIntent)

Request to create a pinned shortcut.

boolean setDynamicShortcuts(List<ShortcutInfo> shortcutInfoList)

Publish the list of shortcuts.

boolean updateShortcuts(List<ShortcutInfo> shortcutInfoList)

Update all existing shortcuts with the same IDs.

Inherited methods

From class java.lang.Object

Public methods

addDynamicShortcuts

added in API level 25
boolean addDynamicShortcuts (List<ShortcutInfo> shortcutInfoList)

Publish the list of dynamic shortcuts. If there are already dynamic or pinned shortcuts with the same IDs, each mutable shortcut is updated.

This API will be rate-limited.

Parameters
shortcutInfoList List

This value must never be null.

Returns
boolean true if the call has succeeded. false if the call is rate-limited.

Throws
IllegalArgumentException if getMaxShortcutCountPerActivity() is exceeded, or when trying to update immutable shortcuts.
IllegalStateException when the user is locked.

createShortcutResultIntent

Intent createShortcutResultIntent (ShortcutInfo shortcut)

Returns an Intent which can be used by the default launcher to pin a shortcut containing the given ShortcutInfo. This method should be used by an Activity to set a result in response to ACTION_CREATE_SHORTCUT.

Parameters
shortcut ShortcutInfo: New shortcut to pin. If an app wants to pin an existing (either dynamic or manifest) shortcut, then it only needs to have an ID, and other fields don't have to be set, in which case, the target shortcut must be enabled. If it's a new shortcut, all the mandatory fields, such as a short label, must be set.

This value must never be null.

Returns
Intent The intent that should be set as the result for the calling activity, or null if the current launcher doesn't support shortcuts.

Throws
IllegalArgumentException if a shortcut with the same ID exists and is disabled.

See also:

disableShortcuts

added in API level 25
void disableShortcuts (List<String> shortcutIds)

Disable pinned shortcuts. For more details, see the Javadoc for the ShortcutManager class.

Parameters
shortcutIds List

This value must never be null.

Throws
IllegalArgumentException If trying to disable immutable shortcuts.
IllegalStateException when the user is locked.

disableShortcuts

added in API level 25
void disableShortcuts (List<String> shortcutIds, 
                CharSequence disabledMessage)

Disable pinned shortcuts, showing the user a custom error message when they try to select the disabled shortcuts. For more details, see the Javadoc for the ShortcutManager class.

Parameters
shortcutIds List

This value must never be null.

disabledMessage CharSequence

Throws
IllegalArgumentException If trying to disable immutable shortcuts.
IllegalStateException when the user is locked.

enableShortcuts

added in API level 25
void enableShortcuts (List<String> shortcutIds)

Re-enable pinned shortcuts that were previously disabled. If the target shortcuts are already enabled, this method does nothing.

Parameters
shortcutIds List

This value must never be null.

Throws
IllegalArgumentException If trying to enable immutable shortcuts.
IllegalStateException when the user is locked.

getDynamicShortcuts

added in API level 25
List<ShortcutInfo> getDynamicShortcuts ()

Return all dynamic shortcuts from the caller app.

This API is intended to be used for examining what shortcuts are currently published. Re-publishing returned ShortcutInfos via APIs such as setDynamicShortcuts(List) may cause loss of information such as icons.

Returns
List<ShortcutInfo>

This value will never be null.

Throws
IllegalStateException when the user is locked.

getIconMaxHeight

added in API level 25
int getIconMaxHeight ()

Return the max height for icons, in pixels.

Returns
int

getIconMaxWidth

added in API level 25
int getIconMaxWidth ()

Return the max width for icons, in pixels.

Note that this method returns max width of icon's visible part. Hence, it does not take into account the inset introduced by AdaptiveIconDrawable. To calculate bitmap image to function as AdaptiveIconDrawable, multiply 1 + 2 * getExtraInsetFraction() to the returned size.

Returns
int

getManifestShortcuts

added in API level 25
List<ShortcutInfo> getManifestShortcuts ()

Return all static (manifest) shortcuts from the caller app.

This API is intended to be used for examining what shortcuts are currently published. Re-publishing returned ShortcutInfos via APIs such as setDynamicShortcuts(List) may cause loss of information such as icons.

Returns
List<ShortcutInfo>

This value will never be null.

Throws
IllegalStateException when the user is locked.

getMaxShortcutCountPerActivity

added in API level 25
int getMaxShortcutCountPerActivity ()

Return the maximum number of static and dynamic shortcuts that each launcher icon can have at a time.

Returns
int

getPinnedShortcuts

added in API level 25
List<ShortcutInfo> getPinnedShortcuts ()

Return all pinned shortcuts from the caller app.

This API is intended to be used for examining what shortcuts are currently published. Re-publishing returned ShortcutInfos via APIs such as setDynamicShortcuts(List) may cause loss of information such as icons.

Returns
List<ShortcutInfo>

This value will never be null.

Throws
IllegalStateException when the user is locked.

isRateLimitingActive

added in API level 25
boolean isRateLimitingActive ()

Return true when rate-limiting is active for the caller app.

See the class level javadoc for details.

Returns
boolean

Throws
IllegalStateException when the user is locked.

isRequestPinShortcutSupported

boolean isRequestPinShortcutSupported ()

Return TRUE if the app is running on a device whose default launcher supports requestPinShortcut(ShortcutInfo, IntentSender).

The return value may change in subsequent calls if the user changes the default launcher app.

Note: See also the support library counterpart isRequestPinShortcutSupported(Context), which supports Android versions lower than O using the legacy private intent com.android.launcher.action.INSTALL_SHORTCUT.

Returns
boolean

See also:

removeAllDynamicShortcuts

added in API level 25
void removeAllDynamicShortcuts ()

Delete all dynamic shortcuts from the caller app.

Throws
IllegalStateException when the user is locked.

removeDynamicShortcuts

added in API level 25
void removeDynamicShortcuts (List<String> shortcutIds)

Delete dynamic shortcuts by ID.

Parameters
shortcutIds List

This value must never be null.

Throws
IllegalStateException when the user is locked.

reportShortcutUsed

added in API level 25
void reportShortcutUsed (String shortcutId)

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 ShortcutManager class

The information is accessible via queryEvents(long, long) Typically, launcher apps use this information to build a prediction model so that they can promote the shortcuts that are likely to be used at the moment.

Parameters
shortcutId String

Throws
IllegalStateException when the user is locked.

requestPinShortcut

boolean requestPinShortcut (ShortcutInfo shortcut, 
                IntentSender resultIntent)

Request to create a pinned shortcut. The default launcher will receive this request and ask the user for approval. If the user approves it, the shortcut will be created, and resultIntent will be sent. If a request is denied by the user, however, no response will be sent to the caller.

Only apps with a foreground activity or a foreground service can call this method. Otherwise, it'll throw IllegalStateException.

It's up to the launcher to decide how to handle previous pending requests when the same package calls this API multiple times in a row. One possible strategy is to ignore any previous requests.

Note: See also the support library counterpart requestPinShortcut(Context, ShortcutInfoCompat, IntentSender), which supports Android versions lower than O using the legacy private intent com.android.launcher.action.INSTALL_SHORTCUT.

Parameters
shortcut ShortcutInfo: Shortcut to pin. If an app wants to pin an existing (either static or dynamic) shortcut, then it only needs to have an ID. Although other fields don't have to be set, the target shortcut must be enabled.

If it's a new shortcut, all the mandatory fields, such as a short label, must be set.

This value must never be null.

resultIntent IntentSender: If not null, this intent will be sent when the shortcut is pinned. Use getIntentSender() to create an IntentSender. To avoid background execution limits, use an unexported, manifest-declared receiver. For more details, see the overview documentation for the ShortcutManager class.

Returns
boolean TRUE if the launcher supports this feature. Note the API will return without waiting for the user to respond, so getting TRUE from this API does *not* mean the shortcut was pinned successfully. FALSE if the launcher doesn't support this feature.

Throws
IllegalArgumentException if a shortcut with the same ID exists and is disabled.
IllegalStateException The caller doesn't have a foreground activity or a foreground service, or the device is locked.

See also:

setDynamicShortcuts

added in API level 25
boolean setDynamicShortcuts (List<ShortcutInfo> shortcutInfoList)

Publish the list of shortcuts. All existing dynamic shortcuts from the caller app will be replaced. If there are already pinned shortcuts with the same IDs, the mutable pinned shortcuts are updated.

This API will be rate-limited.

Parameters
shortcutInfoList List

This value must never be null.

Returns
boolean true if the call has succeeded. false if the call is rate-limited.

Throws
IllegalArgumentException if getMaxShortcutCountPerActivity() is exceeded, or when trying to update immutable shortcuts.
IllegalStateException when the user is locked.

updateShortcuts

added in API level 25
boolean updateShortcuts (List<ShortcutInfo> shortcutInfoList)

Update all existing shortcuts with the same IDs. Target shortcuts may be pinned and/or dynamic, but they must not be immutable.

This API will be rate-limited.

Parameters
shortcutInfoList List

This value must never be null.

Returns
boolean true if the call has succeeded. false if the call is rate-limited.

Throws
IllegalArgumentException If trying to update immutable shortcuts.
IllegalStateException when the user is locked.
This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a one-minute survey?
Help us improve Android tools and documentation.