Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit d4255a9c authored by Makoto Onuki's avatar Makoto Onuki Committed by android-build-merger
Browse files

Merge \"ShortcutManager javadoc\" into nyc-mr1-dev

am: 3746d222

Change-Id: I1a856a61c3453acd02a2541533a268ade9dd5933
parents cd8e1bea 3746d222
Loading
Loading
Loading
Loading
+52 −15
Original line number Diff line number Diff line
@@ -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()}.
+110 −64
Original line number Diff line number Diff line
@@ -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.
         *
         * <p>This field is intended for a concise description of a shortcut displayed under
         * an icon.  The recommend max length is 10 characters.
         * <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);
+331 −58

File changed.

Preview size limit exceeded, changes collapsed.