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 |
static
boolean
|
isRateLimitingActive(Context context)
Return |
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.
See also:
Constant Value: 8 (0x00000008)
FLAG_MATCH_DYNAMIC
public static final int FLAG_MATCH_DYNAMIC
Include dynamic shortcuts in the result.
See also:
Constant Value: 2 (0x00000002)
FLAG_MATCH_MANIFEST
public static final int FLAG_MATCH_MANIFEST
Include manifest shortcuts in the result.
See also:
Constant Value: 1 (0x00000001)
FLAG_MATCH_PINNED
public static final int FLAG_MATCH_PINNED
Include pinned shortcuts in the result.
See also:
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 |
See also:
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:
- API 25 and above, this method matches platform behavior.
- API 24 and earlier, this method behalves the same as
removeDynamicShortcuts(Context, List
)
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:
- API 25 and above, this method matches platform behavior.
- API 24 and earlier, this method behalves the same as
addDynamicShortcuts(Context, List
)
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 ShortcutInfo
s 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 ShortcutInfoCompat
s that match matchFlags
.
Parameters | |
---|---|
context |
Context |
matchFlags |
int : result includes shortcuts matching this flags. Any combination of:
Compatibility behavior:
|
Returns | |
---|---|
List<ShortcutInfoCompat> |
list of ShortcutInfoCompat s that match the flag.
At least one of the |
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. |
See also:
NotificationManagerCompat.notify(int, android.app.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. Compatibility behavior:
- API 30 and above, this method matches platform behavior.
- API 25 to 29, this api is simulated by {@link ShortcutManager#addDynamicShortcuts(List)} and {@link ShortcutManager#removeDynamicShortcuts(List)} and thus will be rate-limited.
- API 24 and earlier, this method uses internal implementation and matches platform behavior.
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 |
See also:
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 |
See also:
removeLongLivedShortcuts
public static void removeLongLivedShortcuts (Context context, 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 behalves the same as
removeDynamicShortcuts(Context, List
)
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:
- API 25 and above, this method matches platform behavior.
- API 24 and earlier, this method is equivalent of calling
removeAllDynamicShortcuts(Context)
andaddDynamicShortcuts(Context, List
consecutively.)
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. |