ShortcutManagerCompat

Added in 1.1.0

public class ShortcutManagerCompat


Helper for accessing features in android.content.pm.ShortcutManager.

Summary

Constants

static final String
EXTRA_SHORTCUT_ID = "android.intent.extra.shortcut.ID"

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

static final int

Include cached shortcuts in the result.

static final int

Include dynamic shortcuts in the result.

static final int

Include manifest shortcuts in the result.

static final int

Include pinned shortcuts in the result.

Public methods

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

Publish the list of dynamic shortcuts.

static @NonNull Intent

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

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

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

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

Re-enable pinned shortcuts that were previously disabled.

static @NonNull List<ShortcutInfoCompat>

Return all dynamic shortcuts from the caller app.

static int

Return the max height for icons, in pixels.

static int

Return the max width for icons, in pixels.

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

Returns ShortcutInfoCompats that match matchFlags.

static boolean

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

static boolean
static boolean
pushDynamicShortcut(
    @NonNull Context context,
    @NonNull ShortcutInfoCompat shortcut
)

Publish a single dynamic shortcut.

static void

Delete all dynamic shortcuts from the caller app.

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

Delete dynamic shortcuts by ID.

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

Delete long lived shortcuts by ID.

static void
reportShortcutUsed(@NonNull Context context, @NonNull 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(
    @NonNull Context context,
    @NonNull ShortcutInfoCompat shortcut,
    @Nullable IntentSender callback
)

Request to create a pinned shortcut.

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

Publish the list of shortcuts.

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

Update all existing shortcuts with the same IDs.

Constants

EXTRA_SHORTCUT_ID

Added in 1.1.0
public static final String EXTRA_SHORTCUT_ID = "android.intent.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.

FLAG_MATCH_CACHED

Added in 1.5.0
public static final int FLAG_MATCH_CACHED = 8

Include cached shortcuts in the result.

See also
getShortcuts

FLAG_MATCH_DYNAMIC

Added in 1.5.0
public static final int FLAG_MATCH_DYNAMIC = 2

Include dynamic shortcuts in the result.

See also
getShortcuts

FLAG_MATCH_MANIFEST

Added in 1.5.0
public static final int FLAG_MATCH_MANIFEST = 1

Include manifest shortcuts in the result.

See also
getShortcuts

FLAG_MATCH_PINNED

Added in 1.5.0
public static final int FLAG_MATCH_PINNED = 4

Include pinned shortcuts in the result.

See also
getShortcuts

Public methods

addDynamicShortcuts

Added in 1.1.0
public static boolean addDynamicShortcuts(
    @NonNull Context context,
    @NonNull 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.

On API <= 31 Any shortcuts that are marked as excluded from launcher will not be passed to the ShortcutManager, but they might still be available to assistant and other surfaces through alternative means.

This API will be rate-limited.

Returns
boolean

true if the call has succeeded. false if the call fails or is rate-limited.

Throws
java.lang.IllegalArgumentException

if getMaxShortcutCountPerActivity is exceeded, or when trying to update immutable shortcuts.

createShortcutResultIntent

Added in 1.1.0
public static @NonNull Intent createShortcutResultIntent(
    @NonNull Context context,
    @NonNull 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 ACTION_CREATE_SHORTCUT.

Parameters
@NonNull Context context

context to use for the intent.

@NonNull ShortcutInfoCompat shortcut

new shortcut to pin

Returns
@NonNull Intent

the intent that should be set as the result for the calling activity

disableShortcuts

Added in 1.5.0
public static void disableShortcuts(
    @NonNull Context context,
    @NonNull List<String> shortcutIds,
    @Nullable 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:

  • API 25 and above, this method matches platform behavior.
  • API 24 and earlier, this method behaves the same as removeDynamicShortcuts
Throws
java.lang.IllegalArgumentException

If trying to disable immutable shortcuts.

java.lang.IllegalStateException

when the user is locked.

enableShortcuts

Added in 1.5.0
public static void enableShortcuts(
    @NonNull Context context,
    @NonNull List<ShortcutInfoCompat> shortcutInfoList
)

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

In API 31 and below any shortcuts that are marked as excluded from launcher will be ignored. Compatibility behavior:

  • API 25 and above, this method matches platform behavior.
  • API 24 and earlier, this method behaves the same as addDynamicShortcuts
Throws
java.lang.IllegalArgumentException

If trying to enable immutable shortcuts.

java.lang.IllegalStateException

when the user is locked.

getDynamicShortcuts

Added in 1.1.0
public static @NonNull List<ShortcutInfoCompatgetDynamicShortcuts(@NonNull 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 may cause loss of information such as icons.

getIconMaxHeight

Added in 1.5.0
public static int getIconMaxHeight(@NonNull Context context)

Return the max height for icons, in pixels.

getIconMaxWidth

Added in 1.5.0
public static int getIconMaxWidth(@NonNull 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 android.graphics.drawable.AdaptiveIconDrawable. To calculate bitmap image to function as android.graphics.drawable.AdaptiveIconDrawable, multiply 1 + 2 * getExtraInsetFraction to the returned size.

getMaxShortcutCountPerActivity

Added in 1.1.0
public static int getMaxShortcutCountPerActivity(@NonNull Context context)
Returns
int

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

getShortcuts

Added in 1.5.0
public static @NonNull List<ShortcutInfoCompatgetShortcuts(@NonNull Context context, int matchFlags)

Returns ShortcutInfoCompats that match matchFlags.

Parameters
@NonNull Context context

context to use for the shortcuts.

int matchFlags

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
@NonNull 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
java.lang.IllegalStateException

when the user is locked.

isRateLimitingActive

Added in 1.5.0
public static boolean isRateLimitingActive(@NonNull Context context)

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

For details, see Rate limiting.

Throws
java.lang.IllegalStateException

when the user is locked.

isRequestPinShortcutSupported

Added in 1.1.0
public static boolean isRequestPinShortcutSupported(@NonNull Context context)
Returns
boolean

true if the launcher supports requestPinShortcut, false otherwise

pushDynamicShortcut

Added in 1.5.0
public static boolean pushDynamicShortcut(
    @NonNull Context context,
    @NonNull 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.

Returns
boolean

true if the call has succeeded. false if the call fails or is rate-limited.

Throws
java.lang.IllegalArgumentException

if trying to update an immutable shortcut.

java.lang.IllegalStateException

when the user is locked.

See also
notify
setShortcutId

If getMaxShortcutCountPerActivity is already reached, an existing shortcut with the lowest rank will be removed to add space for the new shortcut.

If the rank of the shortcut is not explicitly set, it will be set to zero, and shortcut will be added to the top of the list. Compatibility behavior:

  • API 30 and above, this method matches platform behavior.
  • API 25 to 29, this api is simulated by addDynamicShortcuts and removeDynamicShortcuts and thus will be rate-limited.
  • API 24 and earlier, this method uses internal implementation and matches platform behavior.

removeAllDynamicShortcuts

Added in 1.1.0
public static void removeAllDynamicShortcuts(@NonNull 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.

removeDynamicShortcuts

Added in 1.1.0
public static void removeDynamicShortcuts(
    @NonNull Context context,
    @NonNull 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.

removeLongLivedShortcuts

Added in 1.5.0
public static void removeLongLivedShortcuts(
    @NonNull Context context,
    @NonNull List<String> shortcutIds
)

Delete long lived shortcuts by ID. Compatibility behavior:

  • API 30 and above, this method matches platform behavior.
  • API 29 and earlier, this method behaves the same as removeDynamicShortcuts
Throws
java.lang.IllegalStateException

when the user is locked.

reportShortcutUsed

Added in 1.5.0
public static void reportShortcutUsed(@NonNull Context context, @NonNull 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 queryEvents 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.

Throws
java.lang.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

Added in 1.1.0
public static boolean requestPinShortcut(
    @NonNull Context context,
    @NonNull ShortcutInfoCompat shortcut,
    @Nullable 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 android.content.pm.ShortcutInfo object which can be updated by the app.

Use getIntentSender to create a IntentSender.

Parameters
@NonNull Context context

context to use for the request.

@NonNull ShortcutInfoCompat shortcut

new shortcut to pin

@Nullable IntentSender callback

if not null, this intent will be sent when the shortcut is pinned

Returns
boolean

true if the launcher supports this feature

setDynamicShortcuts

Added in 1.5.0
public static boolean setDynamicShortcuts(
    @NonNull Context context,
    @NonNull 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.

On API <= 31 Any shortcuts that are marked as excluded from launcher will not be passed to the ShortcutManager, but they might still be available to assistant and other surfaces through alternative means.

This API will be rate-limited. Compatibility behavior:

Returns
boolean

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

Throws
java.lang.IllegalArgumentException

if getMaxShortcutCountPerActivity is exceeded, or when trying to update immutable shortcuts.

java.lang.IllegalStateException

when the user is locked.

updateShortcuts

Added in 1.1.0
public static boolean updateShortcuts(
    @NonNull Context context,
    @NonNull 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.

On API <= 31 Any shortcuts that are marked as excluded from launcher will not be passed to the ShortcutManager, but they might still be available to assistant and other surfaces through alternative means.

This API will be rate-limited.

Returns
boolean

true if the call has succeeded. false if the call fails or is rate-limited.

Throws
java.lang.IllegalArgumentException

If trying to update immutable shortcuts.