Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "ShortcutManager javadoc" into nyc-mr1-dev

Browse Source
This commit is contained in:
Makoto Onuki
2016-07-11 17:48:49 +00:00
committed by Android (Google) Code Review
parent 74835504ed 4a91096a4c
commit 3746d2224d
3 changed files with 493 additions and 137 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
core/java/android/content/pm/LauncherApps.java
View File

@@ -164,17 +164,19 @@ public class LauncherApps {
}
/**
* Indicates that one or more shortcuts (which may be dynamic and/or pinned)
* Indicates that one or more shortcuts of any kinds (dynamic, pinned, or manifest)
* have been added, updated or removed.
*
* <p>Only the applications that are allowed to access the shortcut information,
* as defined in {@link #hasShortcutHostPermission()}, will receive it.
*
* @param packageName The name of the package that has the shortcuts.
* @param shortcuts all shortcuts from the package (dynamic, manifest and/or pinned).
* Only "key" information will be provided, as defined in
* @param shortcuts all shortcuts from the package (dynamic, manifest and/or pinned) will
* be passed. Only "key" information will be provided, as defined in
* {@link ShortcutInfo#hasKeyFieldsOnly()}.
* @param user The UserHandle of the profile that generated the change.
*
* @see ShortcutManager
*/
public void onShortcutsChanged(@NonNull String packageName,
@NonNull List<ShortcutInfo> shortcuts, @NonNull UserHandle user) {
@@ -222,7 +224,17 @@ public class LauncherApps {
/**
* Requests "key" fields only. See {@link ShortcutInfo#hasKeyFieldsOnly()} for which
* fields are available.
* fields are available. This allows quicker access to shortcut information in order to
* determine in-memory cache in the caller needs to be updated.
*
* <p>Typically, launcher applications cache all or most shortcuts' information
* in memory in order to show shortcuts without a delay. When they want to update their
* cache (e.g. when their process restart), they can fetch all shortcuts' information with
* with this flag, then check {@link ShortcutInfo#getLastChangedTimestamp()} for each
* shortcut and issue a second call to fetch the non-key information of only updated
* shortcuts.
*
* @see ShortcutManager
*/
public static final int FLAG_GET_KEY_FIELDS_ONLY = 1 << 2;
@@ -255,8 +267,8 @@ public class LauncherApps {
}
/**
* If non-zero, returns only shortcuts that have been added or updated since the timestamp,
* which is a milliseconds since the Epoch.
* If non-zero, returns only shortcuts that have been added or updated since the timestamp.
* Units are as per {@link System#currentTimeMillis()}.
*/
public ShortcutQuery setChangedSince(long changedSince) {
mChangedSince = changedSince;
@@ -273,7 +285,7 @@ public class LauncherApps {
/**
* If non-null, return only the specified shortcuts by ID. When setting this field,
* a packange name must also be set with {@link #setPackage}.
* a package name must also be set with {@link #setPackage}.
*/
public ShortcutQuery setShortcutIds(@Nullable List<String> shortcutIds) {
mShortcutIds = shortcutIds;
@@ -291,7 +303,13 @@ public class LauncherApps {
}
/**
* Set query options.
* Set query options. At least one of the {@code MATCH} flags should be set. (Otherwise
* no shortcuts will be returned.)
*
* @see {@link #FLAG_MATCH_DYNAMIC}
* @see {@link #FLAG_MATCH_PINNED}
* @see {@link #FLAG_MATCH_MANIFEST}
* @see {@link #FLAG_GET_KEY_FIELDS_ONLY}
*/
public ShortcutQuery setQueryFlags(@QueryFlags int queryFlags) {
mQueryFlags = queryFlags;
@@ -460,10 +478,14 @@ public class LauncherApps {
*
* <p>Only the default launcher can access the shortcut information.
*
* <p>Note when this method returns {@code false}, that may be a temporary situation because
* <p>Note when this method returns {@code false}, it may be a temporary situation because
* the user is trying a new launcher application. The user may decide to change the default
* launcher to the calling application again, so even if a launcher application loses
* launcher back to the calling application again, so even if a launcher application loses
* this permission, it does <b>not</b> have to purge pinned shortcut information.
* Also in this situation, pinned shortcuts can still be started, even though the caller
* no longer has the shortcut host permission.
*
* @see ShortcutManager
*/
public boolean hasShortcutHostPermission() {
try {
@@ -474,7 +496,7 @@ public class LauncherApps {
}
/**
* Returns the IDs of {@link ShortcutInfo}s that match {@code query}.
* Returns {@link ShortcutInfo}s that match {@code query}.
*
* <p>Callers must be allowed to access the shortcut information, as defined in {@link
* #hasShortcutHostPermission()}.
@@ -483,6 +505,8 @@ public class LauncherApps {
* @param user The UserHandle of the profile.
*
* @return the IDs of {@link ShortcutInfo}s that match the query.
*
* @see ShortcutManager
*/
@Nullable
public List<ShortcutInfo> getShortcuts(@NonNull ShortcutQuery query,
@@ -523,6 +547,8 @@ public class LauncherApps {
* @param packageName The target package name.
* @param shortcutIds The IDs of the shortcut to be pinned.
* @param user The UserHandle of the profile.
*
* @see ShortcutManager
*/
public void pinShortcuts(@NonNull String packageName, @NonNull List<String> shortcutIds,
@NonNull UserHandle user) {
@@ -586,11 +612,17 @@ public class LauncherApps {
/**
* Returns the icon for this shortcut, without any badging for the profile.
*
* <p>Callers must be allowed to access the shortcut information, as defined in {@link
* #hasShortcutHostPermission()}.
*
* @param density The preferred density of the icon, zero for default density. Use
* density DPI values from {@link DisplayMetrics}.
*
* @return The drawable associated with the shortcut.
*
* @see ShortcutManager
* @see #getShortcutBadgedIconDrawable(ShortcutInfo, int)
* @see DisplayMetrics
* @return The drawable associated with the shortcut.
*/
public Drawable getShortcutIconDrawable(@NonNull ShortcutInfo shortcut, int density) {
if (shortcut.hasIconFile()) {
@@ -628,10 +660,15 @@ public class LauncherApps {
/**
* Returns the shortcut icon with badging appropriate for the profile.
*
* <p>Callers must be allowed to access the shortcut information, as defined in {@link
* #hasShortcutHostPermission()}.
*
* @param density Optional density for the icon, or 0 to use the default density. Use
* {@link DisplayMetrics} for DPI values.
* @see DisplayMetrics
* @return A badged icon for the shortcut.
*
* @see ShortcutManager
* @see #getShortcutBadgedIconDrawable(ShortcutInfo, int)
* @see DisplayMetrics
*/
public Drawable getShortcutBadgedIconDrawable(ShortcutInfo shortcut, int density) {
final Drawable originalIcon = getShortcutIconDrawable(shortcut, density);
@@ -641,7 +678,7 @@ public class LauncherApps {
}
/**
* Launches a shortcut.
* Starts a shortcut.
*
* <p>Callers must be allowed to access the shortcut information, as defined in {@link
* #hasShortcutHostPermission()}.

174
core/java/android/content/pm/ShortcutInfo.java
View File

@@ -22,8 +22,10 @@ import android.annotation.UserIdInt;
import android.content.ComponentName;
import android.content.Context;
import android.content.Intent;
import android.content.pm.LauncherApps.ShortcutQuery;
import android.content.res.Resources;
import android.content.res.Resources.NotFoundException;
import android.graphics.Bitmap;
import android.graphics.drawable.Icon;
import android.os.Bundle;
import android.os.Parcel;
@@ -42,20 +44,10 @@ import java.lang.annotation.RetentionPolicy;
import java.util.List;
import java.util.Set;
// TODO Enhance javadoc
/**
* Represents a "launcher shortcut" that can be published via {@link ShortcutManager}.
*
* Represents a shortcut from an application.
*
* <p>Notes about icons:
* <ul>
* <li>If an {@link Icon} is a resource, the system keeps the package name and the resource ID.
* Otherwise, the bitmap is fetched when it's registered to ShortcutManager,
* then shrunk if necessary, and persisted.
* <li>The system disallows byte[] icons, because they can easily go over the binder size limit.
* </ul>
*
* @see {@link ShortcutManager}.
* @see ShortcutManager
*/
public final class ShortcutInfo implements Parcelable {
static final String TAG = "Shortcut";
@@ -149,7 +141,7 @@ public final class ShortcutInfo implements Parcelable {
public @interface CloneFlags {}
/**
* Shortcut category for
* Shortcut category for messaging related actions, such as chat.
*/
public static final String SHORTCUT_CATEGORY_CONVERSATION = "android.shortcut.conversation";
@@ -665,6 +657,8 @@ public final class ShortcutInfo implements Parcelable {
/**
* Builder class for {@link ShortcutInfo} objects.
*
* @see ShortcutManager
*/
public static class Builder {
private final Context mContext;
@@ -727,19 +721,25 @@ public final class ShortcutInfo implements Parcelable {
}
/**
* Sets the target activity. A shortcut will be shown with this activity on the launcher.
* Sets the target activity. A shortcut will be shown along with this activity's icon
* on the launcher.
*
* <p>Only "main" activities -- i.e. ones with an intent filter for
* {@link Intent#ACTION_MAIN} and {@link Intent#CATEGORY_LAUNCHER} can be target activities.
* <p>This is a mandatory field when publishing a new shortcut with
* {@link ShortcutManager#addDynamicShortcuts(List)} or
* {@link ShortcutManager#setDynamicShortcuts(List)}.
*
* <p>By default, the first main activity defined in the application manifest will be
* <ul>
* <li>Only "main" activities (ones with an intent filter for
* {@link Intent#ACTION_MAIN} and {@link Intent#CATEGORY_LAUNCHER}) can be target
* activities.
*
* <li>By default, the first main activity defined in the application manifest will be
* the target.
*
* <p>The package name of the target activity must match the package name of the shortcut
* publisher.
* <li>A target activity must belong to the publisher application.
* </ul>
*
* <p>This has nothing to do with the activity that this shortcut will launch. This is
* a hint to the launcher app about which launcher icon to associate this shortcut with.
* @see ShortcutInfo#getActivity()
*/
@NonNull
public Builder setActivity(@NonNull ComponentName activity) {
@@ -748,18 +748,23 @@ public final class ShortcutInfo implements Parcelable {
}
/**
* Sets an icon.
* Sets an icon of a shortcut.
*
* <ul>
* <li>Tints set by {@link Icon#setTint} or {@link Icon#setTintList} are not supported.
* <li>Bitmaps and resources are supported, but "content:" URIs are not supported.
* </ul>
*
* <p>For performance and security reasons, icons will <b>NOT</b> be available on instances
* returned by {@link ShortcutManager} or {@link LauncherApps}. Default launcher application
* can use {@link LauncherApps#getShortcutIconDrawable(ShortcutInfo, int)}
* <p>Icons are not available on {@link ShortcutInfo} instances
* returned by {@link ShortcutManager} or {@link LauncherApps}. The default launcher
* application can use {@link LauncherApps#getShortcutIconDrawable(ShortcutInfo, int)}
* or {@link LauncherApps#getShortcutBadgedIconDrawable(ShortcutInfo, int)} to fetch
* shortcut icons.
*
* <p>Tints set with {@link Icon#setTint} or {@link Icon#setTintList} are not supported
* and will be ignored.
*
* <p>Only icons created with {@link Icon#createWithBitmap(Bitmap)} and
* {@link Icon#createWithResource} are supported. Other types such as URI based icons
* are not supported.
*
* @see LauncherApps#getShortcutIconDrawable(ShortcutInfo, int)
* @see LauncherApps#getShortcutBadgedIconDrawable(ShortcutInfo, int)
*/
@NonNull
public Builder setIcon(Icon icon) {
@@ -781,11 +786,15 @@ public final class ShortcutInfo implements Parcelable {
/**
* Sets the short title of a shortcut.
*
* <p>This is a mandatory field, unless it's passed to
* {@link ShortcutManager#updateShortcuts(List)}.
* <p>This is a mandatory field when publishing a new shortcut with
* {@link ShortcutManager#addDynamicShortcuts(List)} or
* {@link ShortcutManager#setDynamicShortcuts(List)}.
*
* <p>This field is intended for a concise description of a shortcut displayed under
* an icon. The recommend max length is 10 characters.
* <p>This field is intended for a concise description of a shortcut.
*
* <p>The recommended max length is 10 characters.
*
* @see ShortcutInfo#getShortLabel()
*/
@NonNull
public Builder setShortLabel(@NonNull CharSequence shortLabel) {
@@ -809,8 +818,11 @@ public final class ShortcutInfo implements Parcelable {
* Sets the text of a shortcut.
*
* <p>This field is intended to be more descriptive than the shortcut title. The launcher
* shows this instead of the short title, when it has enough space.
* The recommend max length is 25 characters.
* shows this instead of the short title when it has enough space.
*
* <p>The recommend max length is 25 characters.
*
* @see ShortcutInfo#getLongLabel()
*/
@NonNull
public Builder setLongLabel(@NonNull CharSequence longLabel) {
@@ -854,6 +866,11 @@ public final class ShortcutInfo implements Parcelable {
return this;
}
/**
* Sets the message that should be shown when a shortcut is launched when disabled.
*
* @see ShortcutInfo#getDisabledMessage()
*/
@NonNull
public Builder setDisabledMessage(@NonNull CharSequence disabledMessage) {
Preconditions.checkState(
@@ -869,6 +886,7 @@ public final class ShortcutInfo implements Parcelable {
* categorise shortcuts.
*
* @see #SHORTCUT_CATEGORY_CONVERSATION
* @see ShortcutInfo#getCategories()
*/
@NonNull
public Builder setCategories(Set<String> categories) {
@@ -877,8 +895,22 @@ public final class ShortcutInfo implements Parcelable {
}
/**
* Sets the intent of a shortcut. This is a mandatory field. The extras must only contain
* persistable information. (See {@link PersistableBundle}).
* Sets the intent of a shortcut.
*
* <p>This is a mandatory field when publishing a new shortcut with
* {@link ShortcutManager#addDynamicShortcuts(List)} or
* {@link ShortcutManager#setDynamicShortcuts(List)}.
*
* <p>A shortcut can launch any intent that the publisher application has a permission to
* launch -- for example, a shortcut can launch an unexported activity within the publisher
* application.
*
* <p>A shortcut intent doesn't have to point at the target activity.
*
* <p>{@code intent} can contain extras, but only values of the primitive types are
* supported so the system can persist them.
*
* @see ShortcutInfo#getIntent()
*/
@NonNull
public Builder setIntent(@NonNull Intent intent) {
@@ -890,6 +922,8 @@ public final class ShortcutInfo implements Parcelable {
/**
* "Rank" of a shortcut, which is a non-negative value that's used by the launcher app
* to sort shortcuts.
*
* See {@link ShortcutInfo#getRank()} for details.
*/
@NonNull
public Builder setRank(int rank) {
@@ -903,7 +937,7 @@ public final class ShortcutInfo implements Parcelable {
* Extras that application can set to any purposes.
*
* <p>Applications can store any meta-data of
* shortcuts in this, and retrieve later from {@link ShortcutInfo#getExtras()}.
* shortcuts in extras, and retrieve later from {@link ShortcutInfo#getExtras()}.
*/
@NonNull
public Builder setExtras(@NonNull PersistableBundle extras) {
@@ -921,7 +955,11 @@ public final class ShortcutInfo implements Parcelable {
}
/**
* Return the ID of the shortcut.
* Returns the ID of a shortcut.
*
* <p>Shortcut IDs are unique within each publisher application, and must be stable across
* devices to that shortcuts will still be valid when restored. See {@link ShortcutManager}
* for details.
*/
@NonNull
public String getId() {
@@ -929,7 +967,7 @@ public final class ShortcutInfo implements Parcelable {
}
/**
* Return the package name of the creator application.
* Return the package name of the publisher application.
*/
@NonNull
public String getPackage() {
@@ -937,11 +975,10 @@ public final class ShortcutInfo implements Parcelable {
}
/**
* Return the target activity, which may be null, in which case the shortcut is not associated
* with a specific activity.
* Return the target activity.
*
* <p>This has nothing to do with the activity that this shortcut will launch. This is
* a hint to the launcher app that on which launcher icon this shortcut should be shown.
* <p>This has nothing to do with the activity that this shortcut will launch. Launcher
* applications should show a shortcut along with the launcher icon for this activity.
*
* @see Builder#setActivity
*/
@@ -956,11 +993,7 @@ public final class ShortcutInfo implements Parcelable {
}
/**
* Icon.
*
* For performance reasons, this will <b>NOT</b> be available when an instance is returned
* by {@link ShortcutManager} or {@link LauncherApps}. A launcher application needs to use
* other APIs in LauncherApps to fetch the bitmap.
* Returns the shortcut icon.
*
* @hide
*/
@@ -996,10 +1029,9 @@ public final class ShortcutInfo implements Parcelable {
}
/**
* Return the shorter version of the shortcut title.
* Return the shorter description of a shortcut.
*
* <p>All shortcuts must have a non-empty title, but this method will return null when
* {@link #hasKeyFieldsOnly()} is true.
* @see Builder#setShortLabel(CharSequence)
*/
@Nullable
public CharSequence getShortLabel() {
@@ -1012,7 +1044,9 @@ public final class ShortcutInfo implements Parcelable {
}
/**
* Return the shortcut text.
* Return the longer description of a shortcut.
*
* @see Builder#setLongLabel(CharSequence)
*/
@Nullable
public CharSequence getLongLabel() {
@@ -1026,6 +1060,8 @@ public final class ShortcutInfo implements Parcelable {
/**
* Return the message that should be shown when a shortcut in disabled state is launched.
*
* @see Builder#setDisabledMessage(CharSequence)
*/
@Nullable
public CharSequence getDisabledMessage() {
@@ -1039,6 +1075,8 @@ public final class ShortcutInfo implements Parcelable {
/**
* Return the categories.
*
* @see Builder#setCategories(Set)
*/
@Nullable
public Set<String> getCategories() {
@@ -1048,12 +1086,11 @@ public final class ShortcutInfo implements Parcelable {
/**
* Return the intent.
*
* <p>All shortcuts must have an intent, but this method will return null when
* {@link #hasKeyFieldsOnly()} is true.
* <p>Launcher applications <b>cannot</b> see the intent. If a {@link ShortcutInfo} is
* obtained via {@link LauncherApps}, then this method will always return null.
* Launchers can only start a shortcut intent with {@link LauncherApps#startShortcut}.
*
* <p>Launcher apps <b>cannot</b> see the intent. If a {@link ShortcutInfo} is obtained via
* {@link LauncherApps}, then this method will always return null. Launcher apps can only
* start a shortcut intent with {@link LauncherApps#startShortcut}.
* @see Builder#setIntent(Intent)
*/
@Nullable
public Intent getIntent() {
@@ -1096,6 +1133,10 @@ public final class ShortcutInfo implements Parcelable {
*
* <p>"Floating" shortcuts (i.e. shortcuts that are neither dynamic nor manifest) will all
* have rank 0, because there's no sorting for them.
*
* See the {@link ShortcutManager}'s class javadoc for details.
*
* @see Builder#setRank(int)
*/
public int getRank() {
return mRank;
@@ -1139,6 +1180,8 @@ public final class ShortcutInfo implements Parcelable {
/**
* Extras that application can set to any purposes.
*
* @see Builder#setExtras(PersistableBundle)
*/
@Nullable
public PersistableBundle getExtras() {
@@ -1151,7 +1194,7 @@ public final class ShortcutInfo implements Parcelable {
}
/**
* {@link UserHandle} on which the publisher created shortcuts.
* {@link UserHandle} on which the publisher created a shortcut.
*/
public UserHandle getUserHandle() {
return UserHandle.of(mUserId);
@@ -1201,16 +1244,13 @@ public final class ShortcutInfo implements Parcelable {
}
/**
* Return whether a shortcut is published via AndroidManifest.xml or not. If {@code true},
* Return whether a shortcut is published AndroidManifest.xml or not. If {@code true},
* it's also {@link #isImmutable()}.
*
* <p>When an app is upgraded and a shortcut is no longer published from AndroidManifest.xml,
* this will be set to {@code false}. If the shortcut is not pinned, then it'll just disappear.
* However, if it's pinned, it will still be alive, and {@link #isEnabled()} will be
* {@code false} and {@link #isImmutable()} will be {@code true}.
*
* <p>NOTE this is whether a shortcut is published from the <b>current version's</b>
* AndroidManifest.xml.
*/
public boolean isDeclaredInManifest() {
return hasFlags(FLAG_MANIFEST);
@@ -1311,6 +1351,12 @@ public final class ShortcutInfo implements Parcelable {
* <li>{@link #isEnabled()}
* <li>{@link #getUserHandle()}
* </ul>
*
* <p>{@link ShortcutInfo}s passed to
* {@link LauncherApps.Callback#onShortcutsChanged(String, List, UserHandle)}
* as well as returned by {@link LauncherApps#getShortcuts(ShortcutQuery, UserHandle)} with
* the {@link ShortcutQuery#FLAG_GET_KEY_FIELDS_ONLY} option will only have key information
* for performance reasons.
*/
public boolean hasKeyFieldsOnly() {
return hasFlags(FLAG_KEY_FIELDS_ONLY);

389
core/java/android/content/pm/ShortcutManager.java
View File

@@ -20,6 +20,7 @@ import android.annotation.TestApi;
import android.annotation.UserIdInt;
import android.app.usage.UsageStatsManager;
import android.content.Context;
import android.content.Intent;
import android.os.RemoteException;
import android.os.ServiceManager;
import android.os.UserHandle;
@@ -28,62 +29,333 @@ import com.android.internal.annotations.VisibleForTesting;
import java.util.List;
// TODO Enhance javadoc
/**
* <b>TODO: Update to reflect DR changes, such as manifest shortcuts.</b><br>
* ShortcutManager manages "launcher shortcuts" (or simply "shortcuts"). Shortcuts provide user
* with quick
* ways to access activities other than the main activity from the launcher to users. For example,
* an email application may publish the "compose new email" action which will directly open the
* compose activity. The {@link ShortcutInfo} class represents shortcuts.
*
* {@link ShortcutManager} manages shortcuts created by applications.
* <h3>Dynamic Shortcuts and Manifest Shortcuts</h3>
*
* <h3>Dynamic shortcuts and pinned shortcuts</h3>
* There are two ways to publish shortcuts: manifest shortcuts and dynamic shortcuts.
*
* An application can publish shortcuts with {@link #setDynamicShortcuts(List)} and
* {@link #addDynamicShortcuts(List)}. There can be at most
* {@link #getMaxShortcutCountPerActivity()} number of dynamic shortcuts at a time from the
* same application.
* A dynamic shortcut can be deleted with {@link #removeDynamicShortcuts(List)}, and apps
* can also use {@link #removeAllDynamicShortcuts()} to delete all dynamic shortcuts.
* <ul>
* <li>Manifest shortcuts are declared in a resource XML which is referred to from
* AndroidManifest.xml. Manifest shortcuts are published when an application is installed,
* and are updated when an application is upgraded with an updated XML file.
* Manifest shortcuts are immutable and their
* definitions (e.g. icons and labels) can not be changed dynamically (without upgrading the
* publisher application).
*
* <p>The shortcuts that are currently published by the above APIs are called "dynamic", because
* they can be removed by the creator application at any time. The user may "pin" dynamic shortcuts
* on Launcher to make "pinned" shortcuts. Pinned shortcuts <b>cannot</b> be removed by the creator
* app. An application can obtain all pinned shortcuts from itself with
* {@link #getPinnedShortcuts()}. Applications should keep the pinned shortcut information
* up-to-date using {@link #updateShortcuts(List)}.
* <li>Dynamic shortcuts are published at runtime with {@link ShortcutManager} APIs.
* Applications can publish, update and remove dynamic shortcuts at runtime with certain limitations
* described below.
* </ul>
*
* <p>The number of pinned shortcuts does not affect the number of dynamic shortcuts that can be
* published by an application at a time.
* No matter how many pinned shortcuts that Launcher has for an application, the
* application can still always publish {@link #getMaxShortcutCountPerActivity()} number of
* dynamic
* shortcuts.
* <p>Only "main" activities (i.e. activities that handle the {@code MAIN} action and the
* {@code LAUNCHER} category) can have shortcuts. If an application has multiple main activities,
* they will have different set of shortcuts.
*
* <h3>Shortcut IDs</h3>
* <p>Dynamic shortcuts and manifest shortcuts are shown by launcher applications when the user
* takes a certain action (e.g. long-press) on an application launcher icon.
*
* Each shortcut must have an ID, which must be unique within each application. When a shortcut is
* published, existing shortcuts with the same ID will be updated. Note this may include a
* pinned shortcut.
* <p>Each launcher icon can have at most {@link #getMaxShortcutCountPerActivity()} number of
* dynamic and manifest shortcuts combined.
*
*
* <h3>Pinning Shortcuts</h3>
*
* Launcher applications allow users to "pin" shortcuts so they're easier to access. Both manifest
* and dynamic shortcuts can be pinned, to avoid user's confusion.
* Pinned shortcuts <b>cannot</b> be removed by publisher
* applications -- they are only removed when the publisher is uninstalled. (Or the user performs
* "clear data" on the publisher application on the Settings application.)
*
* <p>Publisher can however "disable" pinned shortcuts so they cannot be launched. See below
* for details.
*
*
* <h3>Updating and Disabling Shortcuts</h3>
*
* <p>When a dynamic shortcut is pinned, even when the publisher removes it as a dynamic shortcut,
* the pinned shortcut will still be available and launchable. This allows an application to have
* more than {@link #getMaxShortcutCountPerActivity()} number of shortcuts -- for example, suppose
* {@link #getMaxShortcutCountPerActivity()} is 5:
* <ul>
* <li>A chat application publishes 5 dynamic shortcuts for the 5 most recent
* conversations, "c1" - "c5".
*
* <li>The user pins all of the 5 shortcuts.
*
* <li>Later, the user has 3 newer conversations ("c6", "c7" and "c8"), so the application
* re-publishes dynamic shortcuts and now it has the dynamic shortcuts "c4", "c5", "c6", "c7"
* and "c8". The publisher has to remove "c1", "c2" and "c3" because it can't have more than
* 5 dynamic shortcuts.
*
* <li>However, even though "c1", "c2" and "c3" are no longer dynamic shortcuts, the pinned
* shortcuts for those conversations are still available and launchable.
*
* <li>At this point, the application has 8 shortcuts in total, including the 3 pinned
* shortcuts, even though it's allowed to have at most 5 dynamic shortcuts.
*
* <li>The application can use {@link #updateShortcuts(List)} to update any of the existing
* 8 shortcuts, when, for example, the chat peers' icons have changed.
* </ul>
* {@link #addDynamicShortcuts(List)} and {@link #setDynamicShortcuts(List)} can also be used
* to update existing shortcuts with the same IDs, but they <b>cannot</b> be used for
* non-dynamic pinned shortcuts because these two APIs will always try to make the passed
* shortcuts dynamic.
*
*
* <h4>Disabling Manifest Shortcuts</h4>
* Sometimes pinned shortcuts become obsolete and may not be usable. For example, a pinned shortcut
* to a group chat will be unusable when the group chat room is deleted. In cases like this,
* applications should use {@link #disableShortcuts(List)}, which will remove the specified dynamic
* shortcuts and also make the pinned shortcuts un-launchable, if any.
* {@link #disableShortcuts(List, CharSequence)} can also be used to disable shortcuts with
* a custom error message that will be shown when the user starts the shortcut.
*
* <h4>Disabling Manifest Shortcuts</h4>
* When an application is upgraded and the new version no longer has a manifest shortcut that
* the previous version had, this shortcut will no longer be published as a manifest shortcut.
*
* <p>If the shortcut is pinned, then the pinned shortcut will remain on the launcher, but will be
* disabled. Note in this case, the pinned shortcut is no longer a manifest shortcut, but is
* still <b>immutable</b> and cannot be updated with the {@link ShortcutManager} APIs.
*
*
* <h3>Publishing Dynamic Shortcuts</h3>
*
* Applications can publish dynamic shortcuts with {@link #setDynamicShortcuts(List)}
* or {@link #addDynamicShortcuts(List)}. {@link #updateShortcuts(List)} can also be used to
* update existing (mutable) shortcuts.
* Use {@link #removeDynamicShortcuts(List)} or {@link #removeAllDynamicShortcuts()} to remove
* dynamic shortcuts.
*
* <p>Example:
* <pre>
* ShortcutManager shortcutManager = getSystemService(ShortcutManager.class);
*
* ShortcutInfo shortcut = new ShortcutInfo.Builder(this, "id1")
* .setIntent(new Intent(Intent.ACTION_VIEW, Uri.parse("http://www.mysite.com/")))
* .setShortLabel("Web site")
* .setLongLabel("Open the web site")
* .setIcon(Icon.createWithResource(context, R.drawable.icon_website))
* .build();
*
* shortcutManager.setDynamicShortcuts(Arrays.asList(shortcut));
* </pre>
*
*
* <h3>Publishing Manifest Shortcuts</h3>
*
* In order to add manifest shortcuts to your application, first add
* {@code <meta-data android:name="android.app.shortcuts" />} to your main activity in
* AndroidManifest.xml.
* <pre>
* &lt;manifest xmlns:android=&quot;http://schemas.android.com/apk/res/android&quot;
* package=&quot;com.example.myapplication&quot;&gt;
* &lt;application . . .&gt;
* &lt;activity android:name=&quot;Main&quot;&gt;
* &lt;intent-filter&gt;
* &lt;action android:name=&quot;android.intent.action.MAIN&quot; /&gt;
* &lt;category android:name=&quot;android.intent.category.LAUNCHER&quot; /&gt;
* &lt;/intent-filter&gt;
* <b>&lt;meta-data android:name=&quot;android.app.shortcuts&quot; android:resource=&quot;@xml/shortcuts&quot;/&gt;</b>
* &lt;/activity&gt;
* &lt;/application&gt;
* &lt;/manifest&gt;
* </pre>
*
* Then define shortcuts in res/xml/shortcuts.xml.
* <pre>
* &lt;shortcuts xmlns:android=&quot;http://schemas.android.com/apk/res/android&quot; &gt;
* &lt;shortcut
* android:shortcutId=&quot;compose&quot;
* android:enabled=&quot;true&quot;
* android:icon=&quot;@drawable/compose_icon&quot;
* android:shortcutShortLabel=&quot;@string/compose_shortcut_short_label1&quot;
* android:shortcutLongLabel=&quot;@string/compose_shortcut_short_label1&quot;
* android:shortcutDisabledMessage=&quot;@string/compose_disabled_message1&quot;
* &gt;
* &lt;intent
* android:action=&quot;android.intent.action.VIEW&quot;
* android:targetPackage=&quot;com.example.myapplication&quot;
* android:targetClass=&quot;com.example.myapplication.ComposeActivity&quot; /&gt;
* &lt;categories android:name=&quot;android.shortcut.conversation&quot; /&gt;
* &lt;/shortcut&gt;
* &lt;!-- more shortcut can go here --&gt;
* &lt;/shortcuts&gt;
* </pre>
* <ul>
* <li>{@code android:shortcutId} Mandatory shortcut ID
*
* <li>{@code android:enabled} Default is {@code true}. Can be set to {@code false} in order
* to disable a manifest shortcut that was published on a previous version with a custom
* disabled message. If a custom disabled message is not needed, then a manifest shortcut can
* be simply removed from the xml file rather than keeping it with {@code enabled="false"}.
*
* <li>{@code android:icon} Shortcut icon.
*
* <li>{@code android:shortcutShortLabel} Mandatory shortcut short label.
* See {@link ShortcutInfo.Builder#setShortLabel(CharSequence)}
*
* <li>{@code android:shortcutLongLabel} Shortcut long label.
* See {@link ShortcutInfo.Builder#setLongLabel(CharSequence)}
*
* <li>{@code android:shortcutDisabledMessage} When {@code android:enabled} is set to
* {@code false}, this can be used to set a custom disabled message.
*
* <li>{@code intent} Intent to launch. {@code android:action} is mandatory.
* See <a href="{@docRoot}guide/topics/ui/settings.html#Intents">Using intents</a> for the
* other supported tags.
* </ul>
*
* <h3>Updating Shortcuts v.s. Re-publishing New One with Different ID</h3>
* In order to avoid users' confusion, {@link #updateShortcuts(List)} should not be used to update
* a shortcut to something that is conceptually different.
*
* <p>For example, a phone application may publish the most frequently called contact as a dynamic
* shortcut. Over the time, this contact may change, but when it changes the application should
* publish a new contact with a different ID with either
* {@link #setDynamicShortcuts(List)} or {@link #addDynamicShortcuts(List)}, rather than updating
* the existing shortcut with {@link #updateShortcuts(List)}.
*
* This is because when the shortcut is pinned, changing it to a different contact
* will likely confuse the user.
*
* <p>On the other hand, when the contact's information (e.g. the name or picture) has changed,
* then the application should use {@link #updateShortcuts(List)} so that the pinned shortcut
* will be updated too.
*
*
* <h3>Shortcut Display Order</h3>
* When the launcher show the shortcuts for a launcher icon, the showing order should be the
* following:
* <ul>
* <li>First show manifest shortcuts
* ({@link ShortcutInfo#isDeclaredInManifest()} is {@code true}),
* and then dynamic shortcuts ({@link ShortcutInfo#isDynamic()} is {@code true}).
* <li>Within each category, sort by {@link ShortcutInfo#getRank()}.
* </ul>
* <p>Shortcut ranks are non-negative sequential integers for each target activity. Ranks of
* existing shortcuts can be updated with
* {@link #updateShortcuts(List)} ({@link #addDynamicShortcuts(List)} and
* {@link #setDynamicShortcuts(List)} may be used too).
*
* <p>Ranks will be auto-adjusted so that they're unique for each target activity for each category
* (dynamic or manifest). For example, if there are 3 dynamic shortcuts with ranks 0, 1 and 2,
* adding another dynamic shortcut with rank = 1 means to place this shortcut at the second
* position. The third and forth shortcuts (that were originally second and third) will be adjusted
* to 2 and 3 respectively.
*
* <h3>Rate Limiting</h3>
*
* Calls to {@link #setDynamicShortcuts(List)}, {@link #addDynamicShortcuts(List)} and
* {@link #updateShortcuts(List)} may be rate-limited when called by background applications (i.e.
* applications with no foreground activity or service). When rate-limited, these APIs will return
* {@code false}.
*
* <p>Applications with a foreground activity or service will not be rate-limited.
*
* <p>Rate-limiting will be reset upon certain events, so that even background applications
* will be able to call these APIs again (until they are rate-limited again).
* <ul>
* <li>When an application comes to foreground.
* <li>When the system locale changes.
* <li>When the user performs "inline reply" on a notification.
* </ul>
*
* <h4>Resetting rate-limiting for testing</h4>
*
* If your application is rate-limited during development or testing, you can use the
* "Reset ShortcutManager rate-limiting" development option, or the following adb command to reset
* it.
* <pre>
* adb shell cmd shortcut reset-throttling [ --user USER-ID ]
* </pre>
*
* <h3>Handling System Locale Change</h3>
*
* Applications should update dynamic and pinned shortcuts when the system locale changes
* using the {@link Intent#ACTION_LOCALE_CHANGED} broadcast.
*
* <p>When the system locale changes, rate-limiting will be reset, so even background applications
* what were previously rate-limited will be able to call {@link #updateShortcuts(List)}.
*
*
* <h3>Backup and Restore</h3>
*
* Pinned shortcuts will be backed up and restored across devices. This means all information
* within shortcuts, including IDs, must be meaningful on different devices.
* When an application has {@code android:allowBackup="true"} in its AndroidManifest.xml, pinned
* shortcuts will be backed up automatically and restored when the user sets up a new device.
*
* <h4>What will be backed up and what will not be backed up</h4>
*
* <p>Note that:
* <ul>
* <li>Dynamic shortcuts will not be backed up or restored.
* <li>Icons of pinned shortcuts will <b>not</b> be backed up for performance reasons, unless
* they refer to resources. Instead, launcher applications are supposed to back up and restore
* icons of pinned shortcuts by themselves, and thus from the user's point of view, pinned
* shortcuts will look to have icons restored.
* <li>Pinned shortcuts will be backed up. Bitmap icons will not be backed up by the system,
* but launcher applications should back them up and restore them, so the user will still get
* icons for pinned shortcuts on the launcher. Applications can always use
* {@link #updateShortcuts(List)} to re-publish icons.
*
* <li>Manifest shortcuts will not be backed up, but when an application is re-installed on a new
* device, they will be re-published from AndroidManifest.xml anyway.
*
* <li>Dynamic shortcuts will <b>not</b> be backed up.
* </ul>
*
* <p>Because dynamic shortcuts will not restored, it is recommended that applications check
* currently published dynamic shortcuts with {@link #getDynamicShortcuts()} when they start,
* and re-publish dynamic shortcuts when necessary.
*
* <h3>APIs for launcher</h3>
* <pre>
* public class MainActivity extends Activity {
* public void onCreate(Bundle savedInstanceState) {
* super.onCreate(savedInstanceState);
*
* Launcher applications should use {@link LauncherApps} to get shortcuts that are published from
* applications. Launcher applications can also pin shortcuts with
* {@link LauncherApps#pinShortcuts(String, List, UserHandle)}.
* ShortcutManager shortcutManager = getSystemService(ShortcutManager.class);
*
* if (shortcutManager.getDynamicShortcuts().size() == 0) {
* // Application restored; re-publish dynamic shortcuts.
*
* if (shortcutManager.getPinnedShortcuts().size() > 0) {
* // Pinned shortcuts have been restored. use updateShortcuts() to make sure
* // they have up-to-date information.
* }
* }
* }
* :
*
* }
* </pre>
*
*
* <h4>Backup/restore and shortcut IDs</h4>
*
* Because pinned shortcuts will be backed up and restored on new devices, shortcut IDs should be
* meaningful across devices; that is, IDs should be either stable constant strings, or server-side
* identifiers, rather than identifiers generated locally that may not make sense on other devices.
*
*
* <h3>Report Shortcut Usage and Prediction</h3>
*
* Launcher applications may be capable of predicting which shortcuts will most likely be used at
* the moment with the shortcut usage history data.
*
* <p>In order to provide launchers with such data, publisher applications should report which
* shortcut is used with {@link #reportShortcutUsed(String)} when a shortcut is started,
* <b>or when an action equivalent to a shortcut is taken by the user even if it wasn't started
* with the shortcut</b>.
*
* <p>For example, suppose a GPS navigation application exposes "navigate to work" as a shortcut.
* Then it should report it when the user starts this shortcut, and also when the user navigates
* to work within the application without using the shortcut. This helps the launcher application
* learn that the user wants to navigate to work at a certain time every weekday, so that the
* launcher can show this shortcut in a suggestion list.
*
* <h3>Launcher API</h3>
*
* {@link LauncherApps} provides APIs for launcher applications to access shortcuts.
*/
public class ShortcutManager {
private static final String TAG = "ShortcutManager";
@@ -110,14 +382,15 @@ public class ShortcutManager {
/**
* Publish a list of shortcuts. All existing dynamic shortcuts from the caller application
* will be replaced.
* will be replaced. If there's already pinned shortcuts with the same IDs, they will all be
* updated, unless they're immutable.
*
* <p>This API will be rate-limited.
*
* @return {@code true} if the call has succeeded. {@code false} if the call is rate-limited.
*
* @throws IllegalArgumentException if {@code shortcutInfoList} contains more than
* {@link #getMaxShortcutCountPerActivity()} shortcuts.
* @throws IllegalArgumentException if {@link #getMaxShortcutCountPerActivity()} is exceeded,
* or trying to update immutable shortcuts.
*/
public boolean setDynamicShortcuts(@NonNull List<ShortcutInfo> shortcutInfoList) {
try {
@@ -129,8 +402,7 @@ public class ShortcutManager {
}
/**
* Return all dynamic shortcuts from the caller application. The number of result items
* will not exceed the value returned by {@link #getMaxShortcutCountPerActivity()}.
* Return all dynamic shortcuts from the caller application.
*/
@NonNull
public List<ShortcutInfo> getDynamicShortcuts() {
@@ -143,7 +415,7 @@ public class ShortcutManager {
}
/**
* TODO Javadoc
* Return all manifest shortcuts from the caller application.
*/
@NonNull
public List<ShortcutInfo> getManifestShortcuts() {
@@ -157,14 +429,14 @@ public class ShortcutManager {
/**
* Publish list of dynamic shortcuts. If there's already dynamic or pinned shortcuts with
* the same IDs, they will all be updated.
* the same IDs, they will all be updated, unless they're immutable.
*
* <p>This API will be rate-limited.
*
* @return {@code true} if the call has succeeded. {@code false} if the call is rate-limited.
*
* @throws IllegalArgumentException if the caller application has already published the
* max number of dynamic shortcuts.
* @throws IllegalArgumentException if {@link #getMaxShortcutCountPerActivity()} is exceeded,
* or trying to update immutable shortcuts.
*/
public boolean addDynamicShortcuts(@NonNull List<ShortcutInfo> shortcutInfoList) {
try {
@@ -212,11 +484,14 @@ public class ShortcutManager {
}
/**
* Update all existing shortcuts with the same IDs. Shortcuts may be pinned and/or dynamic.
* Update all existing shortcuts with the same IDs. Target shortcuts may be pinned and/or
* dynamic, but may not be immutable.
*
* <p>This API will be rate-limited.
*
* @return {@code true} if the call has succeeded. {@code false} if the call is rate-limited.
*
* @throws IllegalArgumentException if trying to update immutable shortcuts.
*/
public boolean updateShortcuts(List<ShortcutInfo> shortcutInfoList) {
try {
@@ -228,7 +503,7 @@ public class ShortcutManager {
}
/**
* TODO Javadoc
* Disable pinned shortcuts. See {@link ShortcutManager}'s class javadoc for details.
*/
public void disableShortcuts(@NonNull List<String> shortcutIds) {
try {
@@ -261,7 +536,8 @@ public class ShortcutManager {
}
/**
* TODO Javadoc
* Disable pinned shortcuts with a custom error message.
* See {@link ShortcutManager}'s class javadoc for details.
*/
public void disableShortcuts(@NonNull List<String> shortcutIds, CharSequence disabledMessage) {
try {
@@ -274,7 +550,7 @@ public class ShortcutManager {
}
/**
* TODO Javadoc
* Re-enable disabled pinned shortcuts.
*/
public void enableShortcuts(@NonNull List<String> shortcutIds) {
try {
@@ -293,7 +569,7 @@ public class ShortcutManager {
}
/**
* Return the max number of dynamic shortcuts + manifest shortcuts that each launcher icon
* Return the max number of dynamic and manifest shortcuts that each launcher icon
* can have at a time.
*/
public int getMaxShortcutCountPerActivity() {
@@ -362,12 +638,9 @@ public class ShortcutManager {
}
/**
* Applications that publish shortcuts should call this method whenever an action that's
* equivalent to an existing shortcut has been taken by the user. This includes not only when
* the user manually taps a shortcut, but when the user takes an equivalent action within the
* application -- for example, when a music player application has a shortcut to playlist X,
* then the application should not only report it when the playlist is opened from the
* shortcut, but also when the user plays the playlist within the application.
* Applications that publish shortcuts should call this method whenever a shortcut is started
* or an action equivalent to a shortcut is taken. See the {@link ShortcutManager} class
* javadoc for details.
*
* <p>The information is accessible via {@link UsageStatsManager#queryEvents}
* Typically, launcher applications use this information to build a prediction model