Added in API level 5

Summary: Nested Classes | Constants | Methods | Inherited Methods

WallpaperManager

Kotlin |Java

public class WallpaperManager
extends Object

java.lang.Object
↳	android.app.WallpaperManager

Provides access to the system wallpaper. With WallpaperManager, you can get the current wallpaper, get the desired dimensions for the wallpaper, set the wallpaper, and more.

An app can check whether wallpapers are supported for the current user, by calling isWallpaperSupported(), and whether setting of wallpapers is allowed, by calling isSetWallpaperAllowed(). Any public APIs added to WallpaperManager should have a corresponding stub in ERROR(DisabledWallpaperManager/android.app.DisabledWallpaperManager DisabledWallpaperManager).

Summary

Nested classes
`interface`	`WallpaperManager.OnColorsChangedListener` Interface definition for a callback to be invoked when colors change on a wallpaper.

Constants
`String`	`ACTION_CHANGE_LIVE_WALLPAPER` Directly launch live wallpaper preview, allowing the user to immediately confirm to switch to a specific live wallpaper.
`String`	`ACTION_CROP_AND_SET_WALLPAPER` Activity Action: Show settings for choosing wallpaper.
`String`	`ACTION_LIVE_WALLPAPER_CHOOSER` Launch an activity for the user to pick the current global live wallpaper.
`String`	`COMMAND_DROP` Command for `sendWallpaperCommand(IBinder, String, int, int, int, Bundle)`: reported by the wallpaper host when the user drops an object into an area of the host.
`String`	`COMMAND_SECONDARY_TAP` Command for `sendWallpaperCommand(IBinder, String, int, int, int, Bundle)`: reported by the wallpaper host when the user releases a secondary pointer on an empty area (not performing an action in the host).
`String`	`COMMAND_TAP` Command for `sendWallpaperCommand(IBinder, String, int, int, int, Bundle)`: reported by the wallpaper host when the user taps on an empty area (not performing an action in the host).
`String`	`EXTRA_LIVE_WALLPAPER_COMPONENT` Extra in `ACTION_CHANGE_LIVE_WALLPAPER` that specifies the ComponentName of a live wallpaper that should be shown as a preview, for the user to confirm.
`int`	`FLAG_LOCK` Flag: set or retrieve the lock-screen-specific wallpaper.
`int`	`FLAG_SYSTEM` Flag: set or retrieve the general system wallpaper.
`String`	`WALLPAPER_PREVIEW_META_DATA` Manifest entry for activities that respond to `Intent.ACTION_SET_WALLPAPER` which allows them to provide a custom large icon associated with this action.

Public methods
`void`	`addOnColorsChangedListener(WallpaperManager.OnColorsChangedListener listener, Handler handler)` Registers a listener to get notified when the wallpaper colors change.
`void`	`clear(int which)` Remove one or more currently set wallpapers, reverting to the system default display for each one.
`void`	`clear()` Remove any currently set system wallpaper, reverting to the system's built-in wallpaper.
`void`	`clearWallpaper()` Equivalent to `clear()`.
`void`	`clearWallpaperOffsets(IBinder windowToken)` Clear the offsets previously associated with this window through `setWallpaperOffsets(IBinder,float,float)`.
`void`	`forgetLoadedWallpaper()` Remove all internal references to the last loaded wallpaper.
`Drawable`	`getBuiltInDrawable(int outWidth, int outHeight, boolean scaleToFit, float horizontalAlignment, float verticalAlignment, int which)` Returns a drawable for the built-in static wallpaper of the specified type.
`Drawable`	`getBuiltInDrawable(int which)` Obtain a drawable for the specified built-in static system wallpaper.
`Drawable`	`getBuiltInDrawable(int outWidth, int outHeight, boolean scaleToFit, float horizontalAlignment, float verticalAlignment)` Returns a drawable for the system built-in static wallpaper.
`Drawable`	`getBuiltInDrawable()` Obtain a drawable for the built-in static system wallpaper.
`Intent`	`getCropAndSetWallpaperIntent(Uri imageUri)` Gets an Intent that will launch an activity that crops the given image and sets the device's wallpaper.
`int`	`getDesiredMinimumHeight()` Returns the desired minimum height for the wallpaper.
`int`	`getDesiredMinimumWidth()` Returns the desired minimum width for the wallpaper.
`Drawable`	`getDrawable()` Important note: Up to Android 12, this method requires the `Manifest.permission.READ_EXTERNAL_STORAGE` permission.
`Drawable`	`getDrawable(int which)` Important note: only apps with `Manifest.permission.MANAGE_EXTERNAL_STORAGE` should use this method.
`Drawable`	`getFastDrawable(int which)` Important note: only apps with `Manifest.permission.MANAGE_EXTERNAL_STORAGE` should use this method.
`Drawable`	`getFastDrawable()` Important note: Up to Android 12, this method requires the `Manifest.permission.READ_EXTERNAL_STORAGE` permission.
`static WallpaperManager`	`getInstance(Context context)` Retrieve a WallpaperManager associated with the given Context.
`WallpaperColors`	`getWallpaperColors(int which)` Get the primary colors of a wallpaper.
`ParcelFileDescriptor`	`getWallpaperFile(int which)` Important note: Up to Android 12, this method requires the `Manifest.permission.READ_EXTERNAL_STORAGE` permission.
`int`	`getWallpaperId(int which)` Get the ID of the current wallpaper of the given kind.
`WallpaperInfo`	`getWallpaperInfo(int which)` Returns the information about the designated wallpaper if its current wallpaper is a live wallpaper component.
`WallpaperInfo`	`getWallpaperInfo()` Returns the information about the home screen wallpaper if its current wallpaper is a live wallpaper component.
`boolean`	`hasResourceWallpaper(int resid)` Return whether any users are currently set to use the wallpaper with the given resource ID.
`boolean`	`isSetWallpaperAllowed()` Returns whether the calling package is allowed to set the wallpaper for the calling user.
`boolean`	`isWallpaperSupported()` Returns whether wallpapers are supported for the calling user.
`Drawable`	`peekDrawable()` Important note: Up to Android 12, this method requires the `Manifest.permission.READ_EXTERNAL_STORAGE` permission.
`Drawable`	`peekDrawable(int which)` Important note: only apps with `Manifest.permission.MANAGE_EXTERNAL_STORAGE` should use this method.
`Drawable`	`peekFastDrawable()` Important note: only apps with `Manifest.permission.MANAGE_EXTERNAL_STORAGE` should use this method.
`Drawable`	`peekFastDrawable(int which)` Important note: only apps with `Manifest.permission.MANAGE_EXTERNAL_STORAGE` should use this method.
`void`	`removeOnColorsChangedListener(WallpaperManager.OnColorsChangedListener callback)` Stop listening to color updates.
`void`	`sendWallpaperCommand(IBinder windowToken, String action, int x, int y, int z, Bundle extras)` Send an arbitrary command to the current active wallpaper.
`int`	`setBitmap(Bitmap fullImage, Rect visibleCropHint, boolean allowBackup, int which)` Version of `setBitmap(Bitmap,Rect,boolean)` that allows the caller to specify which of the supported wallpaper categories to set.
`void`	`setBitmap(Bitmap bitmap)` Change the current system wallpaper to a bitmap.
`int`	`setBitmap(Bitmap fullImage, Rect visibleCropHint, boolean allowBackup)` Change the current system wallpaper to a bitmap, specifying a hint about which subrectangle of the full image is to be visible.
`void`	`setDisplayPadding(Rect padding)` Specify extra padding that the wallpaper should have outside of the display.
`int`	`setResource(int resid, int which)` Version of `setResource(int)` that allows the caller to specify which of the supported wallpaper categories to set.
`void`	`setResource(int resid)` Change the current system wallpaper to the bitmap in the given resource.
`void`	`setStream(InputStream bitmapData)` Change the current system wallpaper to a specific byte stream.
`int`	`setStream(InputStream bitmapData, Rect visibleCropHint, boolean allowBackup, int which)` Version of `setStream(InputStream,Rect,boolean)` that allows the caller to specify which of the supported wallpaper categories to set.
`int`	`setStream(InputStream bitmapData, Rect visibleCropHint, boolean allowBackup)` Change the current system wallpaper to a specific byte stream, specifying a hint about which subrectangle of the full image is to be visible.
`void`	`setWallpaperOffsetSteps(float xStep, float yStep)` For applications that use multiple virtual screens showing a wallpaper, specify the step size between virtual screens.
`void`	`setWallpaperOffsets(IBinder windowToken, float xOffset, float yOffset)` Set the display position of the current wallpaper within any larger space, when that wallpaper is visible behind the given window.
`void`	`suggestDesiredDimensions(int minimumWidth, int minimumHeight)` For use only by the current home application, to specify the size of wallpaper it would like to use.

Inherited methods

From class


        
          java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeoutMillis, int nanos)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait()` Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

ACTION_CHANGE_LIVE_WALLPAPER

Added in API level 16

public static final String ACTION_CHANGE_LIVE_WALLPAPER

Directly launch live wallpaper preview, allowing the user to immediately confirm to switch to a specific live wallpaper. You must specify EXTRA_LIVE_WALLPAPER_COMPONENT with the ComponentName of a live wallpaper component that is to be shown.

Constant Value: "android.service.wallpaper.CHANGE_LIVE_WALLPAPER"

ACTION_CROP_AND_SET_WALLPAPER

Added in API level 19

public static final String ACTION_CROP_AND_SET_WALLPAPER

Activity Action: Show settings for choosing wallpaper. Do not use directly to construct an intent; instead, use getCropAndSetWallpaperIntent(Uri).

Input: Intent.getData is the URI of the image to crop and set as wallpaper.

Output: RESULT_OK if user decided to crop/set the wallpaper, RESULT_CANCEL otherwise Activities that support this intent should specify a MIME filter of "image/*"

Constant Value: "android.service.wallpaper.CROP_AND_SET_WALLPAPER"

ACTION_LIVE_WALLPAPER_CHOOSER

Added in API level 7

public static final String ACTION_LIVE_WALLPAPER_CHOOSER

Launch an activity for the user to pick the current global live wallpaper.

Constant Value: "android.service.wallpaper.LIVE_WALLPAPER_CHOOSER"

COMMAND_DROP

Added in API level 7

public static final String COMMAND_DROP

Command for sendWallpaperCommand(IBinder, String, int, int, int, Bundle): reported by the wallpaper host when the user drops an object into an area of the host. The x and y arguments are the location of the drop.

Constant Value: "android.home.drop"

COMMAND_SECONDARY_TAP

Added in API level 11

public static final String COMMAND_SECONDARY_TAP

Command for sendWallpaperCommand(IBinder, String, int, int, int, Bundle): reported by the wallpaper host when the user releases a secondary pointer on an empty area (not performing an action in the host). The x and y arguments are the location of the secondary tap in screen coordinates.

Constant Value: "android.wallpaper.secondaryTap"

COMMAND_TAP

Added in API level 7

public static final String COMMAND_TAP

Command for sendWallpaperCommand(IBinder, String, int, int, int, Bundle): reported by the wallpaper host when the user taps on an empty area (not performing an action in the host). The x and y arguments are the location of the tap in screen coordinates.

Constant Value: "android.wallpaper.tap"

EXTRA_LIVE_WALLPAPER_COMPONENT

Added in API level 16

public static final String EXTRA_LIVE_WALLPAPER_COMPONENT

Extra in ACTION_CHANGE_LIVE_WALLPAPER that specifies the ComponentName of a live wallpaper that should be shown as a preview, for the user to confirm.

Constant Value: "android.service.wallpaper.extra.LIVE_WALLPAPER_COMPONENT"

FLAG_LOCK

Added in API level 24

public static final int FLAG_LOCK

Flag: set or retrieve the lock-screen-specific wallpaper.

Constant Value: 2 (0x00000002)

FLAG_SYSTEM

Added in API level 24

public static final int FLAG_SYSTEM

Flag: set or retrieve the general system wallpaper.

Constant Value: 1 (0x00000001)

WALLPAPER_PREVIEW_META_DATA

Added in API level 11

public static final String WALLPAPER_PREVIEW_META_DATA

Manifest entry for activities that respond to Intent.ACTION_SET_WALLPAPER which allows them to provide a custom large icon associated with this action.

Constant Value: "android.wallpaper.preview"

Public methods

addOnColorsChangedListener

Added in API level 27

public void addOnColorsChangedListener (WallpaperManager.OnColorsChangedListener listener, 
                Handler handler)

Registers a listener to get notified when the wallpaper colors change.

Parameters
`listener`	`WallpaperManager.OnColorsChangedListener`: A listener to register. This value cannot be `null`.
`handler`	`Handler`: Where to call it from. Will be called from the main thread if null.

clear

Added in API level 24

public void clear (int which)

Remove one or more currently set wallpapers, reverting to the system default display for each one. On success, the intent Intent.ACTION_WALLPAPER_CHANGED is broadcast.

When called with which=FLAG_LOCK, clear the lockscreen wallpaper. The home screen wallpaper will become visible on the lock screen.
When called with which=FLAG_SYSTEM, revert the home screen wallpaper to default. The lockscreen wallpaper will be unchanged: if the previous wallpaper was shared between home and lock screen, it will become lock screen only.
When called with which=(FLAG_LOCK | FLAG_SYSTEM), put the default wallpaper on both home and lock screen, removing any user defined wallpaper.

.
Requires Manifest.permission.SET_WALLPAPER

Parameters
`which`	`int`: A bitwise combination of `FLAG_SYSTEM` or `FLAG_LOCK` Value is either `0` or a combination of the following: `FLAG_SYSTEM` `FLAG_LOCK`

Throws
`IOException`	If an error occurs reverting to the built-in wallpaper.

clear

Added in API level 5

public void clear ()

Remove any currently set system wallpaper, reverting to the system's built-in wallpaper. On success, the intent Intent.ACTION_WALLPAPER_CHANGED is broadcast.

This method requires the caller to hold the permission Manifest.permission.SET_WALLPAPER.
Requires Manifest.permission.SET_WALLPAPER

Throws
`IOException`	If an error occurs reverting to the built-in wallpaper.

clearWallpaper

Added in API level 28

public void clearWallpaper ()

Equivalent to clear().
Requires Manifest.permission.SET_WALLPAPER

See also:

clear()

clearWallpaperOffsets

Added in API level 5

public void clearWallpaperOffsets (IBinder windowToken)

Clear the offsets previously associated with this window through setWallpaperOffsets(IBinder,float,float). This reverts the window to its default state, where it does not cause the wallpaper to scroll from whatever its last offsets were.

Parameters
`windowToken`	`IBinder`: The window who these offsets should be associated with, as returned by `View.getWindowToken()`.

forgetLoadedWallpaper

Added in API level 14

public void forgetLoadedWallpaper ()

Remove all internal references to the last loaded wallpaper. Useful for apps that want to reduce memory usage when they only temporarily need to have the wallpaper. After calling, the next request for the wallpaper will require reloading it again from disk.

getBuiltInDrawable

Added in API level 24

public Drawable getBuiltInDrawable (int outWidth, 
                int outHeight, 
                boolean scaleToFit, 
                float horizontalAlignment, 
                float verticalAlignment, 
                int which)

Returns a drawable for the built-in static wallpaper of the specified type. Based on the parameters, the drawable can be cropped and scaled.

Parameters
`outWidth`	`int`: The width of the returned drawable
`outHeight`	`int`
`scaleToFit`	`boolean`: If true, scale the wallpaper down rather than just cropping it
`horizontalAlignment`	`float`: A float value between 0 and 1 specifying where to crop the image; 0 for left-aligned, 0.5 for horizontal center-aligned, and 1 for right-aligned
`verticalAlignment`	`float`: A float value between 0 and 1 specifying where to crop the image; 0 for top-aligned, 0.5 for vertical center-aligned, and 1 for bottom-aligned
`which`	`int`: The `FLAG_*` identifier of a valid wallpaper type. Throws IllegalArgumentException if an invalid wallpaper is requested. Value is either `0` or a combination of the following: `FLAG_SYSTEM` `FLAG_LOCK`

Returns
`Drawable`	A Drawable presenting the built-in default wallpaper image of the given type, or `null` if no default image of that type is defined on this device.

getBuiltInDrawable

Added in API level 24

public Drawable getBuiltInDrawable (int which)

Obtain a drawable for the specified built-in static system wallpaper.

Parameters
`which`	`int`: The `FLAG_*` identifier of a valid wallpaper type. Throws IllegalArgumentException if an invalid wallpaper is requested. Value is either `0` or a combination of the following: `FLAG_SYSTEM` `FLAG_LOCK`

Returns
`Drawable`	A Drawable presenting the specified wallpaper image, or `null` if no built-in default image for that wallpaper type exists.

getBuiltInDrawable

Added in API level 19

public Drawable getBuiltInDrawable (int outWidth, 
                int outHeight, 
                boolean scaleToFit, 
                float horizontalAlignment, 
                float verticalAlignment)

Returns a drawable for the system built-in static wallpaper. Based on the parameters, the drawable can be cropped and scaled

Parameters
`outWidth`	`int`: The width of the returned drawable
`outHeight`	`int`
`scaleToFit`	`boolean`: If true, scale the wallpaper down rather than just cropping it
`horizontalAlignment`	`float`: A float value between 0 and 1 specifying where to crop the image; 0 for left-aligned, 0.5 for horizontal center-aligned, and 1 for right-aligned
`verticalAlignment`	`float`: A float value between 0 and 1 specifying where to crop the image; 0 for top-aligned, 0.5 for vertical center-aligned, and 1 for bottom-aligned

Returns
`Drawable`	A Drawable presenting the built-in default system wallpaper image, or `null` if no such default image is defined on this device.

getBuiltInDrawable

Added in API level 19

public Drawable getBuiltInDrawable ()

Obtain a drawable for the built-in static system wallpaper.

Returns
`Drawable`

getCropAndSetWallpaperIntent

Added in API level 19

public Intent getCropAndSetWallpaperIntent (Uri imageUri)

Gets an Intent that will launch an activity that crops the given image and sets the device's wallpaper. If there is a default HOME activity that supports cropping wallpapers, it will be preferred as the default. Use this method instead of directly creating a ACTION_CROP_AND_SET_WALLPAPER intent.

Parameters
`imageUri`	`Uri`: The image URI that will be set in the intent. The must be a content URI and its provider must resolve its type to "image/*"

Returns
`Intent`

Throws
`IllegalArgumentException`	if the URI is not a content URI or its MIME type is not "image/*"

getDesiredMinimumHeight

Added in API level 5

public int getDesiredMinimumHeight ()

Returns the desired minimum height for the wallpaper. Callers of setBitmap(android.graphics.Bitmap) or setStream(java.io.InputStream) should check this value beforehand to make sure the supplied wallpaper respects the desired minimum height. If the returned value is

Web Proxy Viewer | New URL | Original Page

WallpaperManager

Summary

Nested classes

Constants

Public methods

Inherited methods

Constants

ACTION_CHANGE_LIVE_WALLPAPER

ACTION_CROP_AND_SET_WALLPAPER

ACTION_LIVE_WALLPAPER_CHOOSER

COMMAND_DROP

COMMAND_SECONDARY_TAP

COMMAND_TAP

EXTRA_LIVE_WALLPAPER_COMPONENT

FLAG_LOCK

FLAG_SYSTEM

WALLPAPER_PREVIEW_META_DATA

Public methods

addOnColorsChangedListener

clear

clear

clearWallpaper

clearWallpaperOffsets

forgetLoadedWallpaper

getBuiltInDrawable

getBuiltInDrawable

getBuiltInDrawable

getBuiltInDrawable

getCropAndSetWallpaperIntent

getDesiredMinimumHeight