ShortcutManager
open class ShortcutManager
| kotlin.Any | |
| ↳ | 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 | |
|---|---|
| static Int |
Include cached shortcuts in the result. |
| static Int |
Include dynamic shortcuts in the result. |
| static Int |
Include manifest shortcuts in the result. |
| static Int |
Include pinned shortcuts in the result. |
| Public methods | |
|---|---|
| open Boolean |
addDynamicShortcuts(shortcutInfoList: MutableList<ShortcutInfo!>)Publish the list of dynamic shortcuts. |
| open Intent! |
createShortcutResultIntent(shortcut: ShortcutInfo)Returns an Intent which can be used by the default launcher to pin a shortcut containing the given |
| open Unit |
disableShortcuts(shortcutIds: MutableList<String!>)Disable pinned shortcuts. |
| open Unit |
disableShortcuts(shortcutIds: MutableList<String!>, disabledMessage: CharSequence!)Disable pinned shortcuts, showing the user a custom error message when they try to select the disabled shortcuts. |
| open Unit |
enableShortcuts(shortcutIds: MutableList<String!>)Re-enable pinned shortcuts that were previously disabled. |
| open MutableList<ShortcutInfo!> |
Return all dynamic shortcuts from the caller app. |
| open Int |
Return the max height for icons, in pixels. |
| open Int |
Return the max width for icons, in pixels. |
| open MutableList<ShortcutInfo!> |
Return all static (manifest) shortcuts from the caller app. |
| open Int |
Return the maximum number of static and dynamic shortcuts that each launcher icon can have at a time. |
| open MutableList<ShortcutInfo!> |
Return all pinned shortcuts from the caller app. |
| open MutableList<ShortcutInfo!> |
getShortcuts(matchFlags: Int)Returns |
| open Boolean |
Return |
| open Boolean |
Return |
| open Unit |
pushDynamicShortcut(shortcut: ShortcutInfo)Publish a single dynamic shortcut. |
| open Unit |
Delete all dynamic shortcuts from the caller app. |
| open Unit |
removeDynamicShortcuts(shortcutIds: MutableList<String!>)Delete dynamic shortcuts by ID. |
| open Unit |
removeLongLivedShortcuts(shortcutIds: MutableList<String!>)Delete long lived shortcuts by ID. |
| open Unit |
reportShortcutUsed(shortcutId: String!)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. |
| open Boolean |
requestPinShortcut(shortcut: ShortcutInfo, resultIntent: IntentSender?)Request to create a pinned shortcut. |
| open Boolean |
setDynamicShortcuts(shortcutInfoList: MutableList<ShortcutInfo!>)Publish the list of shortcuts. |
| open Boolean |
updateShortcuts(shortcutInfoList: MutableList<ShortcutInfo!>)Update all existing shortcuts with the same IDs. |
Constants
FLAG_MATCH_CACHED
static val FLAG_MATCH_CACHED: Int
Include cached shortcuts in the result.
Value: 8See Also
FLAG_MATCH_DYNAMIC
static val FLAG_MATCH_DYNAMIC: Int
Include dynamic shortcuts in the result.
Value: 2See Also
FLAG_MATCH_MANIFEST
static val FLAG_MATCH_MANIFEST: Int
Include manifest shortcuts in the result.
Value: 1See Also
FLAG_MATCH_PINNED
static val FLAG_MATCH_PINNED: Int
Include pinned shortcuts in the result.
Value: 4See Also
Public methods
addDynamicShortcuts
open fun addDynamicShortcuts(shortcutInfoList: MutableList<ShortcutInfo!>): Boolean
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 |
MutableList<ShortcutInfo!>: This value cannot be null. |
| Return | |
|---|---|
Boolean |
true if the call has succeeded. false if the call is rate-limited. |
| Exceptions | |
|---|---|
java.lang.IllegalArgumentException |
if getMaxShortcutCountPerActivity() is exceeded, or when trying to update immutable shortcuts. |
java.lang.IllegalStateException |
when the user is locked. |
createShortcutResultIntent
open fun createShortcutResultIntent(shortcut: ShortcutInfo): Intent!
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. |
| Return | |
|---|---|
Intent! |
The intent that should be set as the result for the calling activity, or null if the current launcher doesn't support shortcuts. |
| Exceptions | |
|---|---|
java.lang.IllegalArgumentException |
if a shortcut with the same ID exists and is disabled. |
disableShortcuts
open fun disableShortcuts(shortcutIds: MutableList<String!>): Unit
Disable pinned shortcuts. For more details, read Disable shortcuts.
| Parameters | |
|---|---|
shortcutIds |
MutableList<String!>: This value cannot be null. |
| Exceptions | |
|---|---|
java.lang.IllegalArgumentException |
If trying to disable immutable shortcuts. |
java.lang.IllegalStateException |
when the user is locked. |
disableShortcuts
open fun disableShortcuts(
shortcutIds: MutableList<String!>,
disabledMessage: CharSequence!
): Unit
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 |
MutableList<String!>: This value cannot be null. |
| Exceptions | |
|---|---|
java.lang.IllegalArgumentException |
If trying to disable immutable shortcuts. |
java.lang.IllegalStateException |
when the user is locked. |
enableShortcuts
open fun enableShortcuts(shortcutIds: MutableList<String!>): Unit
Re-enable pinned shortcuts that were previously disabled. If the target shortcuts are already enabled, this method does nothing.
| Parameters | |
|---|---|
shortcutIds |
MutableList<String!>: This value cannot be null. |
| Exceptions | |
|---|---|
java.lang.IllegalArgumentException |
If trying to enable immutable shortcuts. |
java.lang.IllegalStateException |
when the user is locked. |
getDynamicShortcuts
open fun getDynamicShortcuts(): MutableList<ShortcutInfo!>
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.
| Return | |
|---|---|
MutableList<ShortcutInfo!> |
This value cannot be null. |
| Exceptions | |
|---|---|
java.lang.IllegalStateException |
when the user is locked. |
getIconMaxHeight
open fun getIconMaxHeight(): Int
Return the max height for icons, in pixels.
getIconMaxWidth
open fun getIconMaxWidth(): Int
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.
getManifestShortcuts
open fun getManifestShortcuts(): MutableList<ShortcutInfo!>
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.
| Return | |
|---|---|
MutableList<ShortcutInfo!> |
This value cannot be null. |
| Exceptions | |
|---|---|
java.lang.IllegalStateException |
when the user is locked. |
getMaxShortcutCountPerActivity
open fun getMaxShortcutCountPerActivity(): Int
Return the maximum number of static and dynamic shortcuts that each launcher icon can have at a time.
getPinnedShortcuts
open fun getPinnedShortcuts(): MutableList<ShortcutInfo!>
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.
| Return | |
|---|---|
MutableList<ShortcutInfo!> |
This value cannot be null. |
| Exceptions | |
|---|---|
java.lang.IllegalStateException |
when the user is locked. |
getShortcuts
open fun getShortcuts(matchFlags: Int): MutableList<ShortcutInfo!>
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:
Value is either 0 or a combination of android.content.pm.ShortcutManager#FLAG_MATCH_MANIFEST, android.content.pm.ShortcutManager#FLAG_MATCH_DYNAMIC, android.content.pm.ShortcutManager#FLAG_MATCH_PINNED, and android.content.pm.ShortcutManager#FLAG_MATCH_CACHED |
| Return | |
|---|---|
MutableList<ShortcutInfo!> |
list of ShortcutInfos that match the flag.
At least one of the |
| Exceptions | |
|---|---|
java.lang.IllegalStateException |
when the user is locked. |
isRateLimitingActive
open fun isRateLimitingActive(): Boolean
Return true when rate-limiting is active for the caller app.
For details, see Rate limiting.
| Exceptions | |
|---|---|
java.lang.IllegalStateException |
when the user is locked. |
isRequestPinShortcutSupported
open fun isRequestPinShortcutSupported(): Boolean
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 androidx.core.content.pm.ShortcutManagerCompat#isRequestPinShortcutSupported( * Context), which supports Android versions lower than VERSION_CODES.O using the legacy private intent com.android.launcher.action.INSTALL_SHORTCUT.
pushDynamicShortcut
open fun pushDynamicShortcut(shortcut: ShortcutInfo): Unit
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. |
| Exceptions | |
|---|---|
java.lang.IllegalArgumentException |
if trying to update an immutable shortcut. |
java.lang.IllegalStateException |
when the user is locked. |
removeAllDynamicShortcuts
open fun removeAllDynamicShortcuts(): Unit
Delete all dynamic shortcuts from the caller app.
| Exceptions | |
|---|---|
java.lang.IllegalStateException |
when the user is locked. |
removeDynamicShortcuts
open fun removeDynamicShortcuts(shortcutIds: MutableList<String!>): Unit
Delete dynamic shortcuts by ID.
| Parameters | |
|---|---|
shortcutIds |
MutableList<String!>: This value cannot be null. |
| Exceptions | |
|---|---|
java.lang.IllegalStateException |
when the user is locked. |
removeLongLivedShortcuts
open fun removeLongLivedShortcuts(shortcutIds: MutableList<String!>): Unit
Delete long lived shortcuts by ID.
| Parameters | |
|---|---|
shortcutIds |
MutableList<String!>: This value cannot be null. |
| Exceptions | |
|---|---|
java.lang.IllegalStateException |
when the user is locked. |
reportShortcutUsed
open fun reportShortcutUsed(shortcutId: String!): Unit
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 android.app.usage.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.
| Exceptions | |
|---|---|
java.lang.IllegalStateException |
when the user is locked. |
requestPinShortcut
open fun requestPinShortcut(
shortcut: ShortcutInfo,
resultIntent: IntentSender?
): Boolean
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 androidx.core.content.pm.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 |
resultIntent |
IntentSender?: If not null, this intent will be sent when the shortcut is pinned. Use android.app.PendingIntent#getIntentSender() to create an IntentSender. To avoid background execution limits, use an unexported, manifest-declared receiver. For more details, see Creating pinned shortcuts. |
| Return | |
|---|---|
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. |
| Exceptions | |
|---|---|
java.lang.IllegalArgumentException |
if a shortcut with the same ID exists and is disabled. |
java.lang.IllegalStateException |
The caller doesn't have a foreground activity or a foreground service, or the device is locked. |
setDynamicShortcuts
open fun setDynamicShortcuts(shortcutInfoList: MutableList<ShortcutInfo!>): Boolean
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 |
MutableList<ShortcutInfo!>: This value cannot be null. |
| Return | |
|---|---|
Boolean |
true if the call has succeeded. false if the call is rate-limited. |
| Exceptions | |
|---|---|
java.lang.IllegalArgumentException |
if getMaxShortcutCountPerActivity() is exceeded, or when trying to update immutable shortcuts. |
java.lang.IllegalStateException |
when the user is locked. |
updateShortcuts
open fun updateShortcuts(shortcutInfoList: MutableList<ShortcutInfo!>): Boolean
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 |
MutableList<ShortcutInfo!>: This value cannot be null. |
| Return | |
|---|---|
Boolean |
true if the call has succeeded. false if the call is rate-limited. |
| Exceptions | |
|---|---|
java.lang.IllegalArgumentException |
If trying to update immutable shortcuts. |
java.lang.IllegalStateException |
when the user is locked. |