Added in API level 25

Summary: Constants | Methods | Inherited Methods

ShortcutManager

---

Kotlin |Java

public class ShortcutManager
extends Object

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

---

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.

To learn about methods that retrieve information about a single shortcut—including identifiers, type, and status—read the ShortcutInfo reference.

For guidance about using shortcuts, see App shortcuts.

Retrieving class instances

Summary

Constants
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
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.
List<ShortcutInfo>	getShortcuts(int matchFlags) Returns ShortcutInfos that match matchFlags.
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(android.content.pm.ShortcutInfo, android.content.IntentSender).
void	pushDynamicShortcut(ShortcutInfo shortcut) Publish a single dynamic shortcut.
void	removeAllDynamicShortcuts() Delete all dynamic shortcuts from the caller app.
void	removeDynamicShortcuts(List<String> shortcutIds) Delete dynamic shortcuts by ID.
void	removeLongLivedShortcuts(List<String> shortcutIds) Delete long lived 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 Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

FLAG_MATCH_CACHED

Added in API level 30

public static final int FLAG_MATCH_CACHED

Include cached shortcuts in the result.

See also:

• getShortcuts(int)

Constant Value: 8 (0x00000008)

FLAG_MATCH_DYNAMIC

Added in API level 30

public static final int FLAG_MATCH_DYNAMIC

Include dynamic shortcuts in the result.

See also:

• getShortcuts(int)

Constant Value: 2 (0x00000002)

FLAG_MATCH_MANIFEST

Added in API level 30

public static final int FLAG_MATCH_MANIFEST

Include manifest shortcuts in the result.

See also:

• getShortcuts(int)

Constant Value: 1 (0x00000001)

FLAG_MATCH_PINNED

Added in API level 30

public static final int FLAG_MATCH_PINNED

Include pinned shortcuts in the result.

See also:

• getShortcuts(int)

Constant Value: 4 (0x00000004)

Public methods

addDynamicShortcuts

Added in API level 25

public 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.
This method may take several seconds to complete, so it should only be called from a worker thread.

Parameters
shortcutInfoList	List: This value cannot 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

Added in API level 26

public 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 Intent#ACTION_CREATE_SHORTCUT.
This method may take several seconds to complete, so it should only be called from a worker thread.

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 cannot 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:

• Intent.ACTION_CREATE_SHORTCUT

disableShortcuts

Added in API level 25

public void disableShortcuts (List<String> shortcutIds)

Disable pinned shortcuts. For more details, read Disable shortcuts.

Parameters
shortcutIds	List: This value cannot be null.

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

disableShortcuts

Added in API level 25

public 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, read Disable shortcuts.

Parameters
shortcutIds	List: This value cannot be null.
disabledMessage	CharSequence

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

enableShortcuts

Added in API level 25

public 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 cannot be null.

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

getDynamicShortcuts

Added in API level 25

public 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(java.util.List) may cause loss of information such as icons.
This method may take several seconds to complete, so it should only be called from a worker thread.

Returns
List<ShortcutInfo>	This value cannot be null.

Throws
IllegalStateException	when the user is locked.

getIconMaxHeight

Added in API level 25

public int getIconMaxHeight ()

Return the max height for icons, in pixels.

Returns
int

getIconMaxWidth

Added in API level 25

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

Returns
int

getManifestShortcuts

Added in API level 25

public 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(java.util.List) may cause loss of information such as icons.
This method may take several seconds to complete, so it should only be called from a worker thread.

Returns
List<ShortcutInfo>	This value cannot be null.

Throws
IllegalStateException	when the user is locked.

getMaxShortcutCountPerActivity

Added in API level 25

public 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

public 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(java.util.List) may cause loss of information such as icons.
This method may take several seconds to complete, so it should only be called from a worker thread.

Returns
List<ShortcutInfo>	This value cannot be null.

Throws
IllegalStateException	when the user is locked.

getShortcuts

Added in API level 30

public List<ShortcutInfo> getShortcuts (int matchFlags)

Returns ShortcutInfos that match matchFlags.
This method may take several seconds to complete, so it should only be called from a worker thread.

Parameters
matchFlags	int: result includes shortcuts matching this flags. Any combination of: FLAG_MATCH_MANIFEST FLAG_MATCH_DYNAMIC FLAG_MATCH_PINNED FLAG_MATCH_CACHED Value is either 0 or a combination of FLAG_MATCH_MANIFEST, FLAG_MATCH_DYNAMIC, FLAG_MATCH_PINNED, and FLAG_MATCH_CACHED

Returns
List<ShortcutInfo>	list of ShortcutInfos that match the flag. At least one of the MATCH flags should be set. Otherwise no shortcuts will be returned. This value cannot be null.

Throws
IllegalStateException	when the user is locked.

isRateLimitingActive

Added in API level 25

public boolean isRateLimitingActive ()

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

For details, see Rate limiting.

Returns
boolean

Throws
IllegalStateException	when the user is locked.

isRequestPinShortcutSupported

Added in API level 26

public boolean isRequestPinShortcutSupported ()

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

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

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

Returns
boolean

See also:

• requestPinShortcut(ShortcutInfo, IntentSender)

pushDynamicShortcut

Added in API level 30

public void pushDynamicShortcut (ShortcutInfo 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
shortcut	ShortcutInfo: This value cannot be null.

Throws
IllegalArgumentException	if trying to update an immutable shortcut.
IllegalStateException	when the user is locked.

See also:

• NotificationManager.notify(int, Notification)

• If {@link #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.

removeAllDynamicShortcuts

Added in API level 25

public void removeAllDynamicShortcuts ()

Delete all dynamic shortcuts from the caller app.

Throws
IllegalStateException	when the user is locked.

removeDynamicShortcuts

Added in API level 25

public void removeDynamicShortcuts (List<String> shortcutIds)

Delete dynamic shortcuts by ID.

Parameters
shortcutIds	List: This value cannot be null.

Throws
IllegalStateException	when the user is locked.

removeLongLivedShortcuts

Added in API level 30

public void removeLongLivedShortcuts (List<String> shortcutIds)

Delete long lived shortcuts by ID.

Parameters
shortcutIds	List: This value cannot be null.

Throws
IllegalStateException	when the user is locked.

reportShortcutUsed

Added in API level 25

public 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, read about tracking shortcut usage.

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

Parameters
shortcutId	String

Throws
IllegalStateException	when the user is locked.

requestPinShortcut

Added in API level 26

public 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 ShortcutManagerCompat.requestPinShortcut(Context, ShortcutInfoCompat, IntentSender), which supports Android versions lower than VERSION_CODES#O using the legacy private intent com.android.launcher.action.INSTALL_SHORTCUT.
This method may take several seconds to complete, so it should only be called from a worker thread.

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 cannot be null.
resultIntent	IntentSender: If not null, this intent will be sent when the shortcut is pinned. Use PendingIntent.getIntentSender() to create an IntentSender. To avoid background execution limits, use an unexported, manifest-declared receiver. For more details, see Creating pinned shortcuts.

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 or if calling app belongs to a user-profile with items restricted on home screen.

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:

• isRequestPinShortcutSupported()
• IntentSender
• PendingIntent.getIntentSender()

setDynamicShortcuts

Added in API level 25

public 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.
This method may take several seconds to complete, so it should only be called from a worker thread.

Parameters
shortcutInfoList	List: This value cannot 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

public 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.
This method may take several seconds to complete, so it should only be called from a worker thread.

Parameters
shortcutInfoList	List: This value cannot 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.