ShortcutManagerCompat

public class ShortcutManagerCompat
extends Object

java.lang.Object
   ↳ androidx.core.content.pm.ShortcutManagerCompat

Helper for accessing features in ShortcutManager.

Summary

Constants

String EXTRA_SHORTCUT_ID

Key to get the shortcut ID from extras of a share intent.

int FLAG_MATCH_CACHED

Include cached shortcuts in the result.

int FLAG_MATCH_DYNAMIC

Include dynamic shortcuts in the result.

int FLAG_MATCH_MANIFEST

Include manifest shortcuts in the result.

int FLAG_MATCH_PINNED

Include pinned shortcuts in the result.

Public methods

static boolean addDynamicShortcuts(Context context, List<ShortcutInfoCompat> shortcutInfoList)

Publish the list of dynamic shortcuts.

static Intent createShortcutResultIntent(Context context, ShortcutInfoCompat shortcut)

Returns an Intent which can be used by the launcher to pin shortcut.

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

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

static void enableShortcuts(Context context, List<ShortcutInfoCompat> shortcutInfoList)

Re-enable pinned shortcuts that were previously disabled.

static List<ShortcutInfoCompat> getDynamicShortcuts(Context context)

Return all dynamic shortcuts from the caller app.

static int getIconMaxHeight(Context context)

Return the max height for icons, in pixels.

static int getIconMaxWidth(Context context)

Return the max width for icons, in pixels.

static int getMaxShortcutCountPerActivity(Context context)
static List<ShortcutInfoCompat> getShortcuts(Context context, int matchFlags)

Returns ShortcutInfoCompats that match matchFlags.

static boolean isRateLimitingActive(Context context)

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

static boolean isRequestPinShortcutSupported(Context context)
static boolean pushDynamicShortcut(Context context, ShortcutInfoCompat shortcut)

Publish a single dynamic shortcut.

static void removeAllDynamicShortcuts(Context context)

Delete all dynamic shortcuts from the caller app.

static void removeDynamicShortcuts(Context context, List<String> shortcutIds)

Delete dynamic shortcuts by ID.

static void removeLongLivedShortcuts(Context context, List<String> shortcutIds)

Delete long lived shortcuts by ID.

static void reportShortcutUsed(Context context, 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.

static boolean requestPinShortcut(Context context, ShortcutInfoCompat shortcut, IntentSender callback)

Request to create a pinned shortcut.

static boolean setDynamicShortcuts(Context context, List<ShortcutInfoCompat> shortcutInfoList)

Publish the list of shortcuts.

static boolean updateShortcuts(Context context, List<ShortcutInfoCompat> shortcutInfoList)

Update all existing shortcuts with the same IDs.

Inherited methods

Constants

EXTRA_SHORTCUT_ID

public static final String EXTRA_SHORTCUT_ID

Key to get the shortcut ID from extras of a share intent. When user selects a direct share item from ShareSheet, the app will receive a share intent which includes the ID of the corresponding shortcut in the extras field.

Constant Value: "android.intent.extra.shortcut.ID"

FLAG_MATCH_CACHED

public static final int FLAG_MATCH_CACHED

Include cached shortcuts in the result.

Constant Value: 8 (0x00000008)

FLAG_MATCH_DYNAMIC

public static final int FLAG_MATCH_DYNAMIC

Include dynamic shortcuts in the result.

Constant Value: 2 (0x00000002)

FLAG_MATCH_MANIFEST

public static final int FLAG_MATCH_MANIFEST

Include manifest shortcuts in the result.

Constant Value: 1 (0x00000001)

FLAG_MATCH_PINNED

public static final int FLAG_MATCH_PINNED

Include pinned shortcuts in the result.

Constant Value: 4 (0x00000004)

Public methods

addDynamicShortcuts

public static boolean addDynamicShortcuts (Context context, 
                List<ShortcutInfoCompat> 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
context Context

shortcutInfoList List

Returns
boolean true if the call has succeeded. false if the call fails or is rate-limited.
Throws
IllegalArgumentException if getMaxShortcutCountPerActivity(Context) is exceeded, or when trying to update immutable shortcuts.

createShortcutResultIntent

public static Intent createShortcutResultIntent (Context context, 
                ShortcutInfoCompat shortcut)

Returns an Intent which can be used by the launcher to pin shortcut.

This should be used by an Activity to set result in response to Intent.ACTION_CREATE_SHORTCUT.

Parameters
context Context

shortcut ShortcutInfoCompat: new shortcut to pin
Returns
Intent the intent that should be set as the result for the calling activity

disableShortcuts

public static void disableShortcuts (Context context, 
                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, read Disable shortcuts. Compatibility behavior:

Parameters
context Context

shortcutIds List

disabledMessage CharSequence

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

enableShortcuts

public static void enableShortcuts (Context context, 
                List<ShortcutInfoCompat> shortcutInfoList)

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

Parameters
context Context

shortcutInfoList List

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

getDynamicShortcuts

public static List<ShortcutInfoCompat> getDynamicShortcuts (Context context)

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 addDynamicShortcuts(Context, List) may cause loss of information such as icons.

Parameters
context Context

Returns
List<ShortcutInfoCompat>

getIconMaxHeight

public static int getIconMaxHeight (Context context)

Return the max height for icons, in pixels.

Parameters
context Context

Returns
int

getIconMaxWidth

public static int getIconMaxWidth (Context context)

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 * AdaptiveIconDrawable.getExtraInsetFraction() to the returned size.

Parameters
context Context

Returns
int

getMaxShortcutCountPerActivity

public static int getMaxShortcutCountPerActivity (Context context)

Parameters
context Context

Returns
int The maximum number of static and dynamic shortcuts that each launcher icon can have at a time.

getShortcuts

public static List<ShortcutInfoCompat> getShortcuts (Context context, 
                int matchFlags)

Returns ShortcutInfoCompats that match matchFlags.

Parameters
context Context

matchFlags int: result includes shortcuts matching this flags. Any combination of: Compatibility behavior:
  • API 30 and above, this method matches platform behavior.
  • API 25 through 29, this method aggregates the result from corresponding platform api.
  • API 24 and earlier, this method can only returns dynamic shortcut. Calling this method with other flag will be ignored.

Returns
List<ShortcutInfoCompat> list of ShortcutInfoCompats that match the flag.

At least one of the MATCH flags should be set. Otherwise no shortcuts will be returned.
Throws
IllegalStateException when the user is locked.

isRateLimitingActive

public static boolean isRateLimitingActive (Context context)

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

For details, see Rate limiting.

Parameters
context Context

Returns
boolean

Throws
IllegalStateException when the user is locked.

isRequestPinShortcutSupported

public static boolean isRequestPinShortcutSupported (Context context)

Parameters
context Context

Returns
boolean true if the launcher supports requestPinShortcut(Context, ShortcutInfoCompat, IntentSender), false otherwise

pushDynamicShortcut

public static boolean pushDynamicShortcut (Context context, 
                ShortcutInfoCompat shortcut)

Publish a single dynamic shortcut. If there are already dynamic or pinned shortcuts with the same ID, each mutable shortcut is updated.

This method is useful when posting notifications which are tagged with shortcut IDs; In order to make sure shortcuts exist and are up-to-date, without the need to explicitly handle the shortcut count limit.

Parameters
context Context

shortcut ShortcutInfoCompat

Returns
boolean true if the call has succeeded. false if the call fails or is rate-limited.
Throws
IllegalArgumentException if trying to update an immutable shortcut.
IllegalStateException when the user is locked.

removeAllDynamicShortcuts

public static void removeAllDynamicShortcuts (Context context)

Delete all dynamic shortcuts from the caller app. Note that if a shortcut is set as long-lived, it may still be available in the system as a cached shortcut even after being removed from the list of dynamic shortcuts.

Parameters
context Context

removeDynamicShortcuts

public static void removeDynamicShortcuts (Context context, 
                List<String> shortcutIds)

Delete dynamic shortcuts by ID. Note that if a shortcut is set as long-lived, it may still be available in the system as a cached shortcut even after being removed from the list of dynamic shortcuts.

Parameters
context Context

shortcutIds List

removeLongLivedShortcuts

public static void removeLongLivedShortcuts (Context context, 
                List<String> shortcutIds)

Delete long lived shortcuts by ID. Compatibility behavior:

Parameters
context Context

shortcutIds List

Throws
IllegalStateException when the user is locked.

reportShortcutUsed

public static void reportShortcutUsed (Context context, 
                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, read about tracking shortcut usage.

The information is accessible via UsageStatsManager.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
context Context

shortcutId String

Throws
IllegalStateException when the user is locked.

This method is not supported on devices running SDK < 25 since the platform class will not be available.

requestPinShortcut

public static boolean requestPinShortcut (Context context, 
                ShortcutInfoCompat shortcut, 
                IntentSender callback)

Request to create a pinned shortcut.

On API <= 25 it creates a legacy shortcut with the provided icon, label and intent. For newer APIs it will create a ShortcutInfo object which can be updated by the app.

Use PendingIntent.getIntentSender() to create a IntentSender.

Parameters
context Context

shortcut ShortcutInfoCompat: new shortcut to pin
callback IntentSender: if not null, this intent will be sent when the shortcut is pinned
Returns
boolean true if the launcher supports this feature

setDynamicShortcuts

public static boolean setDynamicShortcuts (Context context, 
                List<ShortcutInfoCompat> 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. Compatibility behavior:

Parameters
context Context

shortcutInfoList List

Returns
boolean true if the call has succeeded. false if the call is rate-limited.
Throws
IllegalArgumentException if getMaxShortcutCountPerActivity(Context) is exceeded, or when trying to update immutable shortcuts.
IllegalStateException when the user is locked.

updateShortcuts

public static boolean updateShortcuts (Context context, 
                List<ShortcutInfoCompat> 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
context Context

shortcutInfoList List

Returns
boolean true if the call has succeeded. false if the call fails or is rate-limited.
Throws
IllegalArgumentException If trying to update immutable shortcuts.