From edf7d04003890d3b673ab804f5b739e143f4faca Mon Sep 17 00:00:00 2001 From: Christopher Tate Date: Tue, 29 Mar 2016 18:24:25 -0700 Subject: [PATCH] API review: WallpaperManager - Rename FLAG_SET_* to simply FLAG_* - Improve documentation Bug 27365822 Change-Id: I10e85aeaa462a8ae092938c0ccd55d171f02c20a --- api/current.txt | 4 +- api/system-current.txt | 4 +- api/test-current.txt | 4 +- core/java/android/app/WallpaperManager.java | 79 +++++++++++-------- .../statusbar/phone/LockscreenWallpaper.java | 2 +- .../wallpaper/WallpaperManagerService.java | 44 +++++------ 6 files changed, 76 insertions(+), 61 deletions(-) diff --git a/api/current.txt b/api/current.txt index 298f6c4b192ff..9c660c484741f 100644 --- a/api/current.txt +++ b/api/current.txt @@ -5754,8 +5754,8 @@ package android.app { field public static final java.lang.String COMMAND_SECONDARY_TAP = "android.wallpaper.secondaryTap"; field public static final java.lang.String COMMAND_TAP = "android.wallpaper.tap"; field public static final java.lang.String EXTRA_LIVE_WALLPAPER_COMPONENT = "android.service.wallpaper.extra.LIVE_WALLPAPER_COMPONENT"; - field public static final int FLAG_SET_LOCK = 2; // 0x2 - field public static final int FLAG_SET_SYSTEM = 1; // 0x1 + field public static final int FLAG_LOCK = 2; // 0x2 + field public static final int FLAG_SYSTEM = 1; // 0x1 field public static final java.lang.String WALLPAPER_PREVIEW_META_DATA = "android.wallpaper.preview"; } diff --git a/api/system-current.txt b/api/system-current.txt index 0651c6170bd84..d3b9b7cb1147d 100644 --- a/api/system-current.txt +++ b/api/system-current.txt @@ -5891,8 +5891,8 @@ package android.app { field public static final java.lang.String COMMAND_SECONDARY_TAP = "android.wallpaper.secondaryTap"; field public static final java.lang.String COMMAND_TAP = "android.wallpaper.tap"; field public static final java.lang.String EXTRA_LIVE_WALLPAPER_COMPONENT = "android.service.wallpaper.extra.LIVE_WALLPAPER_COMPONENT"; - field public static final int FLAG_SET_LOCK = 2; // 0x2 - field public static final int FLAG_SET_SYSTEM = 1; // 0x1 + field public static final int FLAG_LOCK = 2; // 0x2 + field public static final int FLAG_SYSTEM = 1; // 0x1 field public static final java.lang.String WALLPAPER_PREVIEW_META_DATA = "android.wallpaper.preview"; } diff --git a/api/test-current.txt b/api/test-current.txt index 2a9f452058bf4..df159309e5ca7 100644 --- a/api/test-current.txt +++ b/api/test-current.txt @@ -5758,8 +5758,8 @@ package android.app { field public static final java.lang.String COMMAND_SECONDARY_TAP = "android.wallpaper.secondaryTap"; field public static final java.lang.String COMMAND_TAP = "android.wallpaper.tap"; field public static final java.lang.String EXTRA_LIVE_WALLPAPER_COMPONENT = "android.service.wallpaper.extra.LIVE_WALLPAPER_COMPONENT"; - field public static final int FLAG_SET_LOCK = 2; // 0x2 - field public static final int FLAG_SET_SYSTEM = 1; // 0x1 + field public static final int FLAG_LOCK = 2; // 0x2 + field public static final int FLAG_SYSTEM = 1; // 0x1 field public static final java.lang.String WALLPAPER_PREVIEW_META_DATA = "android.wallpaper.preview"; } diff --git a/core/java/android/app/WallpaperManager.java b/core/java/android/app/WallpaperManager.java index b52af2762fed7..72b9318c2acd3 100644 --- a/core/java/android/app/WallpaperManager.java +++ b/core/java/android/app/WallpaperManager.java @@ -161,8 +161,8 @@ public class WallpaperManager { /** @hide */ @IntDef(flag = true, value = { - FLAG_SET_SYSTEM, - FLAG_SET_LOCK + FLAG_SYSTEM, + FLAG_LOCK }) @Retention(RetentionPolicy.SOURCE) public @interface SetWallpaperFlags {} @@ -170,12 +170,12 @@ public class WallpaperManager { /** * Flag: use the supplied imagery as the general system wallpaper. */ - public static final int FLAG_SET_SYSTEM = 1 << 0; + public static final int FLAG_SYSTEM = 1 << 0; /** * Flag: use the supplied imagery as the lock-screen wallpaper. */ - public static final int FLAG_SET_LOCK = 1 << 1; + public static final int FLAG_LOCK = 1 << 1; private final Context mContext; @@ -336,7 +336,7 @@ public class WallpaperManager { try { Bundle params = new Bundle(); - ParcelFileDescriptor fd = mService.getWallpaper(this, FLAG_SET_SYSTEM, + ParcelFileDescriptor fd = mService.getWallpaper(this, FLAG_SYSTEM, params, userId); if (fd != null) { try { @@ -663,11 +663,18 @@ public class WallpaperManager { /** * Get an open, readable file descriptor to the given wallpaper image file. - * The callee is resopnsible for closing the fd when done ingesting the file. + * The caller is responsible for closing the file descriptor when done ingesting the file. * *

If no lock-specific wallpaper has been configured for the given user, then - * this method will return {@code null} when requesting {@link #FLAG_SET_LOCK} rather than + * this method will return {@code null} when requesting {@link #FLAG_LOCK} rather than * returning the system wallpaper's image file. + * + * @param which The wallpaper whose image file is to be retrieved. Must be a single + * defined kind of wallpaper, either {@link #FLAG_SYSTEM} or + * {@link #FLAG_LOCK}. + * + * @see #FLAG_LOCK + * @see #FLAG_SYSTEM */ public ParcelFileDescriptor getWallpaperFile(int which) { return getWallpaperFile(which, mContext.getUserId()); @@ -677,10 +684,19 @@ public class WallpaperManager { * Version of {@link #getWallpaperFile(int)} that can access the wallpaper data * for a given user. The caller must hold the INTERACT_ACROSS_USERS_FULL * permission to access another user's wallpaper data. + * + * @param which The wallpaper whose image file is to be retrieved. Must be a single + * defined kind of wallpaper, either {@link #FLAG_SYSTEM} or + * {@link #FLAG_LOCK}. + * @param userId The user or profile whose imagery is to be retrieved + * + * @see #FLAG_LOCK + * @see #FLAG_SYSTEM + * * @hide */ public ParcelFileDescriptor getWallpaperFile(int which, int userId) { - if (which != FLAG_SET_SYSTEM && which != FLAG_SET_LOCK) { + if (which != FLAG_SYSTEM && which != FLAG_LOCK) { throw new IllegalArgumentException("Must request exactly one kind of wallpaper"); } @@ -730,8 +746,8 @@ public class WallpaperManager { * such wallpaper configured, returns a negative number. * * @param which The wallpaper whose ID is to be returned. Must be a single - * defined kind of wallpaper, either {@link #FLAG_SET_SYSTEM} or - * {@link #FLAG_SET_LOCK}. + * defined kind of wallpaper, either {@link #FLAG_SYSTEM} or + * {@link #FLAG_LOCK}. * @return The positive numeric ID of the current wallpaper of the given kind, * or a negative value if no such wallpaper is configured. */ @@ -823,24 +839,24 @@ public class WallpaperManager { *

This method requires the caller to hold the permission * {@link android.Manifest.permission#SET_WALLPAPER}. * - * @param resid The bitmap to save. + * @param resid The resource ID of the bitmap to be used as the wallpaper image * * @throws IOException If an error occurs reverting to the built-in * wallpaper. */ public void setResource(@RawRes int resid) throws IOException { - setResource(resid, FLAG_SET_SYSTEM); + setResource(resid, FLAG_SYSTEM); } /** - * Version of {@link #setResource(int)} that takes an optional Bundle for returning - * metadata about the operation to the caller. + * Version of {@link #setResource(int)} that allows the caller to specify which + * of the supported wallpaper categories to set. * - * @param resid - * @param which Flags indicating which wallpaper(s) to configure with the new imagery. + * @param resid The resource ID of the bitmap to be used as the wallpaper image + * @param which Flags indicating which wallpaper(s) to configure with the new imagery * - * @see #FLAG_SET_LOCK - * @see #FLAG_SET_SYSTEM + * @see #FLAG_LOCK + * @see #FLAG_SYSTEM * * @return An integer ID assigned to the newly active wallpaper; or zero on failure. * @@ -934,10 +950,9 @@ public class WallpaperManager { */ public int setBitmap(Bitmap fullImage, Rect visibleCropHint, boolean allowBackup) throws IOException { - return setBitmap(fullImage, visibleCropHint, allowBackup, FLAG_SET_SYSTEM); + return setBitmap(fullImage, visibleCropHint, allowBackup, FLAG_SYSTEM); } - /** /** * Version of {@link #setBitmap(Bitmap, Rect, boolean)} that allows the caller * to specify which of the supported wallpaper categories to set. @@ -951,8 +966,8 @@ public class WallpaperManager { * image for restore to a future device; {@code false} otherwise. * @param which Flags indicating which wallpaper(s) to configure with the new imagery. * - * @see #FLAG_SET_LOCK - * @see #FLAG_SET_SYSTEM + * @see #FLAG_LOCK + * @see #FLAG_SYSTEM * * @return An integer ID assigned to the newly active wallpaper; or zero on failure. * @@ -1054,7 +1069,7 @@ public class WallpaperManager { */ public int setStream(InputStream bitmapData, Rect visibleCropHint, boolean allowBackup) throws IOException { - return setStream(bitmapData, visibleCropHint, allowBackup, FLAG_SET_SYSTEM); + return setStream(bitmapData, visibleCropHint, allowBackup, FLAG_SYSTEM); } /** @@ -1070,8 +1085,8 @@ public class WallpaperManager { * image for restore to a future device; {@code false} otherwise. * @param which Flags indicating which wallpaper(s) to configure with the new imagery. * - * @see #FLAG_SET_LOCK - * @see #FLAG_SET_SYSTEM + * @see #FLAG_LOCK + * @see #FLAG_SYSTEM * * @throws IOException */ @@ -1287,7 +1302,7 @@ public class WallpaperManager { */ @SystemApi public void clearWallpaper() { - clearWallpaper(FLAG_SET_SYSTEM, mContext.getUserId()); + clearWallpaper(FLAG_SYSTEM, mContext.getUserId()); } /** @@ -1467,20 +1482,20 @@ public class WallpaperManager { /** * Remove one or more currently set wallpapers, reverting to the system default - * display for each one. If {@link #FLAG_SET_SYSTEM} is set in the {@code which} + * display for each one. If {@link #FLAG_SYSTEM} is set in the {@code which} * parameter, the intent {@link Intent#ACTION_WALLPAPER_CHANGED} will be broadcast * upon success. * - * @param which A bitwise combination of {@link #FLAG_SET_SYSTEM} or - * {@link #FLAG_SET_LOCK} + * @param which A bitwise combination of {@link #FLAG_SYSTEM} or + * {@link #FLAG_LOCK} * @throws IOException If an error occurs reverting to the built-in wallpaper. */ public void clear(int which) throws IOException { - if ((which & FLAG_SET_SYSTEM) != 0) { + if ((which & FLAG_SYSTEM) != 0) { clear(); } - if ((which & FLAG_SET_LOCK) != 0) { - clearWallpaper(FLAG_SET_LOCK, mContext.getUserId()); + if ((which & FLAG_LOCK) != 0) { + clearWallpaper(FLAG_LOCK, mContext.getUserId()); } } diff --git a/packages/SystemUI/src/com/android/systemui/statusbar/phone/LockscreenWallpaper.java b/packages/SystemUI/src/com/android/systemui/statusbar/phone/LockscreenWallpaper.java index 65e797379fef9..3812429b5f054 100644 --- a/packages/SystemUI/src/com/android/systemui/statusbar/phone/LockscreenWallpaper.java +++ b/packages/SystemUI/src/com/android/systemui/statusbar/phone/LockscreenWallpaper.java @@ -85,7 +85,7 @@ public class LockscreenWallpaper extends IWallpaperManagerCallback.Stub implemen // wallpaper. final int lockWallpaperUserId = mSelectedUser != null ? mSelectedUser.getIdentifier() : mCurrentUserId; - ParcelFileDescriptor fd = mService.getWallpaper(null, WallpaperManager.FLAG_SET_LOCK, + ParcelFileDescriptor fd = mService.getWallpaper(null, WallpaperManager.FLAG_LOCK, new Bundle(), lockWallpaperUserId); if (fd != null) { try { diff --git a/services/core/java/com/android/server/wallpaper/WallpaperManagerService.java b/services/core/java/com/android/server/wallpaper/WallpaperManagerService.java index 4848523bb3f0a..1c5556f238118 100644 --- a/services/core/java/com/android/server/wallpaper/WallpaperManagerService.java +++ b/services/core/java/com/android/server/wallpaper/WallpaperManagerService.java @@ -16,8 +16,8 @@ package com.android.server.wallpaper; -import static android.app.WallpaperManager.FLAG_SET_SYSTEM; -import static android.app.WallpaperManager.FLAG_SET_LOCK; +import static android.app.WallpaperManager.FLAG_SYSTEM; +import static android.app.WallpaperManager.FLAG_LOCK; import static android.os.ParcelFileDescriptor.*; import android.app.ActivityManager; @@ -231,7 +231,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub { false, wallpaper, null); } if (lockWallpaperChanged - || (wallpaper.whichPending & FLAG_SET_LOCK) != 0) { + || (wallpaper.whichPending & FLAG_LOCK) != 0) { if (DEBUG) { Slog.i(TAG, "Lock-relevant wallpaper changed"); } @@ -505,7 +505,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub { && mWallpaper.lastDiedTime + MIN_WALLPAPER_CRASH_TIME > SystemClock.uptimeMillis()) { Slog.w(TAG, "Reverting to built-in wallpaper!"); - clearWallpaperLocked(true, FLAG_SET_SYSTEM, mWallpaper.userId, null); + clearWallpaperLocked(true, FLAG_SYSTEM, mWallpaper.userId, null); } else { mWallpaper.lastDiedTime = SystemClock.uptimeMillis(); } @@ -584,7 +584,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub { if (!bindWallpaperComponentLocked(comp, false, false, wallpaper, null)) { Slog.w(TAG, "Wallpaper no longer available; reverting to default"); - clearWallpaperLocked(false, FLAG_SET_SYSTEM, wallpaper.userId, null); + clearWallpaperLocked(false, FLAG_SYSTEM, wallpaper.userId, null); } } } @@ -664,7 +664,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub { if (doit) { Slog.w(TAG, "Wallpaper uninstalled, removing: " + wallpaper.wallpaperComponent); - clearWallpaperLocked(false, FLAG_SET_SYSTEM, wallpaper.userId, null); + clearWallpaperLocked(false, FLAG_SYSTEM, wallpaper.userId, null); } } } @@ -684,7 +684,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub { } catch (NameNotFoundException e) { Slog.w(TAG, "Wallpaper component gone, removing: " + wallpaper.wallpaperComponent); - clearWallpaperLocked(false, FLAG_SET_SYSTEM, wallpaper.userId, null); + clearWallpaperLocked(false, FLAG_SYSTEM, wallpaper.userId, null); } } if (wallpaper.nextWallpaperComponent != null @@ -746,7 +746,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub { if (DEBUG) { Slog.i(TAG, "Unable to regenerate crop; resetting"); } - clearWallpaperLocked(false, FLAG_SET_SYSTEM, UserHandle.USER_SYSTEM, null); + clearWallpaperLocked(false, FLAG_SYSTEM, UserHandle.USER_SYSTEM, null); } } else { if (DEBUG) { @@ -842,7 +842,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub { void switchUser(int userId, IRemoteCallback reply) { synchronized (mLock) { mCurrentUserId = userId; - WallpaperData wallpaper = getWallpaperSafeLocked(userId, FLAG_SET_SYSTEM); + WallpaperData wallpaper = getWallpaperSafeLocked(userId, FLAG_SYSTEM); // Not started watching yet, in case wallpaper data was loaded for other reasons. if (wallpaper.wallpaperObserver == null) { wallpaper.wallpaperObserver = new WallpaperObserver(wallpaper); @@ -865,7 +865,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub { e = e1; } Slog.w(TAG, "Failure starting previous wallpaper", e); - clearWallpaperLocked(false, FLAG_SET_SYSTEM, wallpaper.userId, reply); + clearWallpaperLocked(false, FLAG_SYSTEM, wallpaper.userId, reply); } } @@ -885,12 +885,12 @@ public class WallpaperManagerService extends IWallpaperManager.Stub { } void clearWallpaperLocked(boolean defaultFailed, int which, int userId, IRemoteCallback reply) { - if (which != FLAG_SET_SYSTEM && which != FLAG_SET_LOCK) { + if (which != FLAG_SYSTEM && which != FLAG_LOCK) { throw new IllegalArgumentException("Must specify exactly one kind of wallpaper to read"); } WallpaperData wallpaper = null; - if (which == FLAG_SET_LOCK) { + if (which == FLAG_LOCK) { wallpaper = mLockWallpaperMap.get(userId); if (wallpaper == null) { // It's already gone; we're done. @@ -916,7 +916,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub { if (wallpaper.wallpaperFile.exists()) { wallpaper.wallpaperFile.delete(); wallpaper.cropFile.delete(); - if (which == FLAG_SET_LOCK) { + if (which == FLAG_LOCK) { mLockWallpaperMap.remove(userId); final IWallpaperManagerCallback cb = mKeyguardListener; if (cb != null) { @@ -1008,7 +1008,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub { } synchronized (mLock) { int userId = UserHandle.getCallingUserId(); - WallpaperData wallpaper = getWallpaperSafeLocked(userId, FLAG_SET_SYSTEM); + WallpaperData wallpaper = getWallpaperSafeLocked(userId, FLAG_SYSTEM); if (width <= 0 || height <= 0) { throw new IllegalArgumentException("width and height must be > 0"); } @@ -1070,7 +1070,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub { } synchronized (mLock) { int userId = UserHandle.getCallingUserId(); - WallpaperData wallpaper = getWallpaperSafeLocked(userId, FLAG_SET_SYSTEM); + WallpaperData wallpaper = getWallpaperSafeLocked(userId, FLAG_SYSTEM); if (padding.left < 0 || padding.top < 0 || padding.right < 0 || padding.bottom < 0) { throw new IllegalArgumentException("padding must be positive: " + padding); } @@ -1103,13 +1103,13 @@ public class WallpaperManagerService extends IWallpaperManager.Stub { wallpaperUserId = ActivityManager.handleIncomingUser(Binder.getCallingPid(), Binder.getCallingUid(), wallpaperUserId, false, true, "getWallpaper", null); - if (which != FLAG_SET_SYSTEM && which != FLAG_SET_LOCK) { + if (which != FLAG_SYSTEM && which != FLAG_LOCK) { throw new IllegalArgumentException("Must specify exactly one kind of wallpaper to read"); } synchronized (mLock) { final SparseArray whichSet = - (which == FLAG_SET_LOCK) ? mLockWallpaperMap : mWallpaperMap; + (which == FLAG_LOCK) ? mLockWallpaperMap : mWallpaperMap; WallpaperData wallpaper = whichSet.get(wallpaperUserId); if (wallpaper == null) { // common case, this is the first lookup post-boot of the system or @@ -1157,12 +1157,12 @@ public class WallpaperManagerService extends IWallpaperManager.Stub { userId = ActivityManager.handleIncomingUser(Binder.getCallingPid(), Binder.getCallingUid(), userId, false, true, "getWallpaperIdForUser", null); - if (which != FLAG_SET_SYSTEM && which != FLAG_SET_LOCK) { + if (which != FLAG_SYSTEM && which != FLAG_LOCK) { throw new IllegalArgumentException("Must specify exactly one kind of wallpaper"); } final SparseArray map = - (which == FLAG_SET_LOCK) ? mLockWallpaperMap : mWallpaperMap; + (which == FLAG_LOCK) ? mLockWallpaperMap : mWallpaperMap; synchronized (mLock) { WallpaperData wallpaper = map.get(userId); if (wallpaper != null) { @@ -1186,7 +1186,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub { Rect cropHint, Bundle extras, int which, IWallpaperManagerCallback completion) { checkPermission(android.Manifest.permission.SET_WALLPAPER); - if ((which & (FLAG_SET_LOCK|FLAG_SET_SYSTEM)) == 0) { + if ((which & (FLAG_LOCK|FLAG_SYSTEM)) == 0) { Slog.e(TAG, "Must specify a valid wallpaper category to set"); return null; } @@ -1637,7 +1637,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub { // Combined or just-system operations use the 'system' WallpaperData // for this use; lock-only operations use the dedicated one. final SparseArray whichSet = - (which == FLAG_SET_LOCK) ? mLockWallpaperMap : mWallpaperMap; + (which == FLAG_LOCK) ? mLockWallpaperMap : mWallpaperMap; WallpaperData wallpaper = whichSet.get(userId); if (wallpaper == null) { // common case, this is the first lookup post-boot of the system or @@ -1648,7 +1648,7 @@ public class WallpaperManagerService extends IWallpaperManager.Stub { // yet a lock-only wallpaper set for this user, so we need to establish // it now. if (wallpaper == null) { - if (which == FLAG_SET_LOCK) { + if (which == FLAG_LOCK) { wallpaper = new WallpaperData(userId, WALLPAPER_LOCK_ORIG, WALLPAPER_LOCK_CROP); mLockWallpaperMap.put(userId, wallpaper);