WallpaperManager

ACTION_CHANGE_LIVE_WALLPAPER

static val ACTION_CHANGE_LIVE_WALLPAPER: String

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.

Value: "android.service.wallpaper.CHANGE_LIVE_WALLPAPER"

ACTION_CROP_AND_SET_WALLPAPER

static val ACTION_CROP_AND_SET_WALLPAPER: String

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

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/*"

Value: "android.service.wallpaper.CROP_AND_SET_WALLPAPER"

ACTION_LIVE_WALLPAPER_CHOOSER

static val ACTION_LIVE_WALLPAPER_CHOOSER: String

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

Value: "android.service.wallpaper.LIVE_WALLPAPER_CHOOSER"

COMMAND_DROP

static val COMMAND_DROP: String

Command for sendWallpaperCommand: 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.

Value: "android.home.drop"

COMMAND_SECONDARY_TAP

static val COMMAND_SECONDARY_TAP: String

Command for sendWallpaperCommand: 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.

Value: "android.wallpaper.secondaryTap"

COMMAND_TAP

static val COMMAND_TAP: String

Command for sendWallpaperCommand: 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.

Value: "android.wallpaper.tap"

EXTRA_LIVE_WALLPAPER_COMPONENT

static val EXTRA_LIVE_WALLPAPER_COMPONENT: String

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.

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

FLAG_LOCK

static val FLAG_LOCK: Int

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

Value: 2

FLAG_SYSTEM

static val FLAG_SYSTEM: Int

Flag: set or retrieve the general system wallpaper.

Value: 1

WALLPAPER_PREVIEW_META_DATA

static val WALLPAPER_PREVIEW_META_DATA: String

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

Value: "android.wallpaper.preview"

addOnColorsChangedListener

open fun addOnColorsChangedListener(
    listener: WallpaperManager.OnColorsChangedListener, 
    handler: Handler
): Unit

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

clear

open fun clear(): Unit

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 android.Manifest.permission#SET_WALLPAPER.
Requires android.Manifest.permission#SET_WALLPAPER

clear

open fun clear(which: Int): Unit

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.

clearWallpaper

open fun clearWallpaper(): Unit

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

clearWallpaperOffsets

open fun clearWallpaperOffsets(windowToken: IBinder!): Unit

Clear the offsets previously associated with this window through setWallpaperOffsets(android.os.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.

forgetLoadedWallpaper

open fun forgetLoadedWallpaper(): Unit

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

open fun getBuiltInDrawable(): Drawable!

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

getBuiltInDrawable

open fun getBuiltInDrawable(which: Int): Drawable!

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

getBuiltInDrawable

open fun getBuiltInDrawable(
    outWidth: Int, 
    outHeight: Int, 
    scaleToFit: Boolean, 
    horizontalAlignment: Float, 
    verticalAlignment: Float
): Drawable!

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

getBuiltInDrawable

open fun getBuiltInDrawable(
    outWidth: Int, 
    outHeight: Int, 
    scaleToFit: Boolean, 
    horizontalAlignment: Float, 
    verticalAlignment: Float, 
    which: Int
): Drawable!

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

getCropAndSetWallpaperIntent

open fun getCropAndSetWallpaperIntent(imageUri: Uri!): Intent!

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.

getDesiredMinimumHeight

open fun getDesiredMinimumHeight(): Int

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 <= 0, the caller should use the height of the default display instead.

getDesiredMinimumWidth

open fun getDesiredMinimumWidth(): Int

Returns the desired minimum width 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 width. If the returned value is <= 0, the caller should use the width of the default display instead.

getDrawable

open fun getDrawable(): Drawable?

Important note:

• Up to Android 12, this method requires the android.Manifest.permission#READ_EXTERNAL_STORAGE permission.
• Starting in Android 13, directly accessing the wallpaper is not possible anymore, instead the default system wallpaper is returned (some versions of Android 13 may throw a SecurityException).
• From Android 14, this method should not be used and will always throw a SecurityException.
• Apps with android.Manifest.permission#MANAGE_EXTERNAL_STORAGE can still access the real wallpaper on all versions.

Equivalent to getDrawable(int) with which=FLAG_SYSTEM.

getDrawable

open fun getDrawable(which: Int): Drawable?

Important note: only apps with should use this method. Otherwise, a SecurityException will be thrown.

Retrieve the requested wallpaper for the specified wallpaper type if the wallpaper is not a live wallpaper. This method should not be used to display the user wallpaper on an app: android.view.WindowManager.LayoutParams#FLAG_SHOW_WALLPAPER should be used instead.

When called with which=FLAG_SYSTEM, if there is a live wallpaper on home screen, the built-in default wallpaper is returned.

When called with which=FLAG_LOCK, if there is a live wallpaper on lock screen, or if the lock screen and home screen share the same wallpaper engine, null is returned.

getWallpaperInfo(int) can be used to determine whether there is a live wallpaper on a specified screen type.

getFastDrawable

open fun getFastDrawable(): Drawable?

Important note:

• Up to Android 12, this method requires the android.Manifest.permission#READ_EXTERNAL_STORAGE permission.
• Starting in Android 13, directly accessing the wallpaper is not possible anymore, instead the default wallpaper is returned (some versions of Android 13 may throw a SecurityException).
• From Android 14, this method should not be used and will always throw a SecurityException.
• Apps with android.Manifest.permission#MANAGE_EXTERNAL_STORAGE can still access the real wallpaper on all versions.

Equivalent to getFastDrawable(int) with which=FLAG_SYSTEM.

getFastDrawable

open fun getFastDrawable(which: Int): Drawable?

Important note: only apps with android.Manifest.permission#MANAGE_EXTERNAL_STORAGE should use this method. Otherwise, a SecurityException will be thrown. Like getDrawable(int), but the returned Drawable has a number of limitations to reduce its overhead as much as possible. It will never scale the wallpaper (only centering it if the requested bounds do match the bitmap bounds, which should not be typical), doesn't allow setting an alpha, color filter, or other attributes, etc. The bounds of the returned drawable will be initialized to the same bounds as the wallpaper, so normally you will not need to touch it. The drawable also assumes that it will be used in a context running in the same density as the screen (not in density compatibility mode).
Requires android.Manifest.permission#MANAGE_EXTERNAL_STORAGE or android.Manifest.permission.READ_WALLPAPER_INTERNAL

getInstance

open static fun getInstance(context: Context!): WallpaperManager!

Retrieve a WallpaperManager associated with the given Context.

getWallpaperColors

open fun getWallpaperColors(which: Int): WallpaperColors?

Get the primary colors of a wallpaper.

This method can return null when:

• Colors are still being processed by the system.
• The user has chosen to use a live wallpaper: live wallpapers might not implement WallpaperService.Engine#onComputeColors().

Please note that this API will go through IPC and may take some time to calculate the wallpaper color, which could block the caller thread, so it is not recommended to call this in the UI thread.

getWallpaperFile

open fun getWallpaperFile(which: Int): ParcelFileDescriptor?

Important note:

• Up to Android 12, this method requires the android.Manifest.permission#READ_EXTERNAL_STORAGE permission.
• Starting in Android 13, directly accessing the wallpaper is not possible anymore, instead the default system wallpaper is returned (some versions of Android 13 may throw a SecurityException).
• From Android 14, this method should not be used and will always throw a SecurityException.
• Apps with android.Manifest.permission#MANAGE_EXTERNAL_STORAGE can still access the real wallpaper on all versions.

If no lock-specific wallpaper has been configured for the given user, then this method will return null when requesting FLAG_LOCK rather than returning the system wallpaper's image file.
Requires android.Manifest.permission#MANAGE_EXTERNAL_STORAGE or android.Manifest.permission.READ_WALLPAPER_INTERNAL

getWallpaperId

open fun getWallpaperId(which: Int): Int

Get the ID of the current wallpaper of the given kind. If there is no such wallpaper configured, returns a negative number.

Every time the wallpaper image is set, a new ID is assigned to it. This method allows the caller to determine whether the wallpaper imagery has changed, regardless of how that change happened.

getWallpaperInfo

open fun getWallpaperInfo(): WallpaperInfo!

Returns the information about the home screen wallpaper if its current wallpaper is a live wallpaper component. Otherwise, if the wallpaper is a static image or is not set, or if the caller doesn't have the appropriate permissions, this returns null.

For devices running Android 13 or earlier, this method requires the android.Manifest.permission#QUERY_ALL_PACKAGES permission.

For devices running Android 14 or later, in order to use this, apps should declare a <queries> tag with the action "android.service.wallpaper.WallpaperService". Otherwise, this method will return null if the caller doesn't otherwise have visibility of the wallpaper package.

getWallpaperInfo

open fun getWallpaperInfo(which: Int): WallpaperInfo?

Returns the information about the designated wallpaper if its current wallpaper is a live wallpaper component. Otherwise, if the wallpaper is a static image or is not set, or if the caller doesn't have the appropriate permissions, this returns null.

In order to use this, apps should declare a <queries> tag with the action "android.service.wallpaper.WallpaperService". Otherwise, this method will return null if the caller doesn't otherwise have visibility of the wallpaper package.

hasResourceWallpaper

open fun hasResourceWallpaper(resid: Int): Boolean

Return whether any users are currently set to use the wallpaper with the given resource ID. That is, their wallpaper has been set through setResource(int) with the same resource id.

isSetWallpaperAllowed

open fun isSetWallpaperAllowed(): Boolean

Returns whether the calling package is allowed to set the wallpaper for the calling user. If this function returns false, any attempts to change the wallpaper will have no effect. Always returns true for device owner and profile owner.

isWallpaperSupported

open fun isWallpaperSupported(): Boolean

Returns whether wallpapers are supported for the calling user. If this function returns false, any attempts to changing the wallpaper will have no effect, and any attempt to obtain of the wallpaper will return null.

peekDrawable

open fun peekDrawable(): Drawable?

Important note:

• Up to Android 12, this method requires the android.Manifest.permission#READ_EXTERNAL_STORAGE permission.
• Starting in Android 13, directly accessing the wallpaper is not possible anymore, instead the default system wallpaper is returned (some versions of Android 13 may throw a SecurityException).
• From Android 14, this method should not be used and will always throw a SecurityException.
• Apps with android.Manifest.permission#MANAGE_EXTERNAL_STORAGE can still access the real wallpaper on all versions.

Equivalent to getDrawable().

peekDrawable

open fun peekDrawable(which: Int): Drawable?

Important note: only apps with should use this method. Otherwise, a SecurityException will be thrown.

Equivalent to getDrawable(int).

peekFastDrawable

open fun peekFastDrawable(): Drawable?

Important note: only apps with should use this method. Otherwise, a SecurityException will be thrown.

Equivalent to getFastDrawable().

peekFastDrawable

open fun peekFastDrawable(which: Int): Drawable?

Important note: only apps with should use this method. Otherwise, a SecurityException will be thrown.

Equivalent to getFastDrawable(int).

removeOnColorsChangedListener

open fun removeOnColorsChangedListener(callback: WallpaperManager.OnColorsChangedListener): Unit

Stop listening to color updates.

sendWallpaperCommand

open fun sendWallpaperCommand(
    windowToken: IBinder!, 
    action: String!, 
    x: Int, 
    y: Int, 
    z: Int, 
    extras: Bundle!
): Unit

Send an arbitrary command to the current active wallpaper.

setBitmap

open fun setBitmap(bitmap: Bitmap!): Unit

Change the current system wallpaper to a bitmap. The given bitmap is converted to a PNG and stored as the wallpaper. On success, the intent Intent#ACTION_WALLPAPER_CHANGED is broadcast.

This method is equivalent to calling setBitmap(android.graphics.Bitmap,android.graphics.Rect,boolean) and passing null for the visibleCrop rectangle and true for the allowBackup parameter.

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

setBitmap

open fun setBitmap(
    fullImage: Bitmap!, 
    visibleCropHint: Rect!, 
    allowBackup: Boolean
): Int

Change the current system wallpaper to a bitmap, specifying a hint about which subrectangle of the full image is to be visible. The OS will then try to best present the given portion of the full image as the static system wallpaper image. On success, the intent Intent#ACTION_WALLPAPER_CHANGED is broadcast.

Passing null as the visibleHint parameter is equivalent to passing (0, 0, fullImage.getWidth(), fullImage.getHeight()).

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

setBitmap

open fun setBitmap(
    fullImage: Bitmap!, 
    visibleCropHint: Rect!, 
    allowBackup: Boolean, 
    which: Int
): Int

Version of setBitmap(android.graphics.Bitmap,android.graphics.Rect,boolean) that allows the caller to specify which of the supported wallpaper categories to set.
Requires android.Manifest.permission#SET_WALLPAPER

setDisplayPadding

open fun setDisplayPadding(padding: Rect!): Unit

Specify extra padding that the wallpaper should have outside of the display. That is, the given padding supplies additional pixels the wallpaper should extend outside of the display itself.

This method requires the caller to hold the permission android.Manifest.permission#SET_WALLPAPER_HINTS.
Requires android.Manifest.permission#SET_WALLPAPER_HINTS

setResource

open fun setResource(resid: Int): Unit

Change the current system wallpaper to the bitmap in the given resource. The resource is opened as a raw data stream and copied into the wallpaper; it must be a valid PNG or JPEG image. On success, the intent Intent#ACTION_WALLPAPER_CHANGED is broadcast.

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

setResource

open fun setResource(
    resid: Int, 
    which: Int
): Int

Version of setResource(int) that allows the caller to specify which of the supported wallpaper categories to set.
Requires android.Manifest.permission#SET_WALLPAPER

setStream

open fun setStream(bitmapData: InputStream!): Unit

Change the current system wallpaper to a specific byte stream. The give InputStream is copied into persistent storage and will now be used as the wallpaper. Currently it must be either a JPEG or PNG image. On success, the intent Intent#ACTION_WALLPAPER_CHANGED is broadcast.

This method is equivalent to calling setStream(java.io.InputStream,android.graphics.Rect,boolean) and passing null for the visibleCrop rectangle and true for the allowBackup parameter.

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

setStream

open fun setStream(
    bitmapData: InputStream!, 
    visibleCropHint: Rect!, 
    allowBackup: Boolean
): Int

Change the current system wallpaper to a specific byte stream, specifying a hint about which subrectangle of the full image is to be visible. The OS will then try to best present the given portion of the full image as the static system wallpaper image. The data from the given InputStream is copied into persistent storage and will then be used as the system wallpaper. Currently the data must be either a JPEG or PNG image. On success, the intent Intent#ACTION_WALLPAPER_CHANGED is broadcast.

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

setStream

open fun setStream(
    bitmapData: InputStream!, 
    visibleCropHint: Rect!, 
    allowBackup: Boolean, 
    which: Int
): Int

Version of setStream(java.io.InputStream,android.graphics.Rect,boolean) that allows the caller to specify which of the supported wallpaper categories to set.
Requires android.Manifest.permission#SET_WALLPAPER

setWallpaperOffsetSteps

open fun setWallpaperOffsetSteps(
    xStep: Float, 
    yStep: Float
): Unit

For applications that use multiple virtual screens showing a wallpaper, specify the step size between virtual screens. For example, if the launcher has 3 virtual screens, it would specify an xStep of 0.5, since the X offset for those screens are 0.0, 0.5 and 1.0

setWallpaperOffsets

open fun setWallpaperOffsets(
    windowToken: IBinder!, 
    xOffset: Float, 
    yOffset: Float
): Unit

Set the display position of the current wallpaper within any larger space, when that wallpaper is visible behind the given window. The X and Y offsets are floating point numbers ranging from 0 to 1, representing where the wallpaper should be positioned within the screen space. These only make sense when the wallpaper is larger than the display.

suggestDesiredDimensions

open fun suggestDesiredDimensions(
    minimumWidth: Int, 
    minimumHeight: Int
): Unit

For use only by the current home application, to specify the size of wallpaper it would like to use. This allows such applications to have a virtual wallpaper that is larger than the physical screen, matching the size of their workspace.

Calling this method from apps other than the active home app is not guaranteed to work properly. Other apps that supply wallpaper imagery should use getDesiredMinimumWidth() and getDesiredMinimumHeight() and construct a wallpaper that matches those dimensions.

This method requires the caller to hold the permission android.Manifest.permission#SET_WALLPAPER_HINTS.