Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)
Android APIs
public class

WallpaperManager

extends Object
java.lang.Object
   ↳ android.app.WallpaperManager

Class Overview

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. Get an instance of WallpaperManager with getInstance() .

Summary

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.
String WALLPAPER_PREVIEW_META_DATA Manifest entry for activities that respond to ACTION_SET_WALLPAPER which allows them to provide a custom large icon associated with this action.
Public Methods
void clear ()
Remove any currently set wallpaper, reverting to the system's built-in wallpaper.
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 ()
Returns a drawable for the system built-in static wallpaper .
Drawable getBuiltInDrawable (int outWidth, int outHeight, boolean scaleToFit, float horizontalAlignment, float verticalAlignment)
Returns a drawable for the system built-in static 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 ()
Retrieve the current system wallpaper; if no wallpaper is set, the system built-in static wallpaper is returned.
Drawable getFastDrawable ()
Like getDrawable() , but the returned Drawable has a number of limitations to reduce its overhead as much as possible.
static WallpaperManager getInstance ( Context context)
Retrieve a WallpaperManager associated with the given Context.
WallpaperInfo getWallpaperInfo ()
If the current wallpaper is a live wallpaper component, return the information about that wallpaper.
boolean hasResourceWallpaper (int resid)
Return whether any users are currently set to use the wallpaper with the given resource ID.
Drawable peekDrawable ()
Retrieve the current system wallpaper; if there is no wallpaper set, a null pointer is returned.
Drawable peekFastDrawable ()
Like getFastDrawable() , but if there is no wallpaper set, a null pointer is returned.
void sendWallpaperCommand ( IBinder windowToken, String action, int x, int y, int z, Bundle extras)
Send an arbitrary command to the current active wallpaper.
void setBitmap ( Bitmap bitmap)
Change the current system wallpaper to a bitmap.
void setResource (int resid)
Change the current system wallpaper to the bitmap in the given resource.
void setStream ( InputStream data)
Change the current system wallpaper to a specific byte stream.
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 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.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

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"

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: 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"

public static final String ACTION_LIVE_WALLPAPER_CHOOSER

Added in API level 7

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

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

public static final String COMMAND_DROP

Added in API level 7

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"

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"

public static final String COMMAND_TAP

Added in API level 7

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"

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"

public static final String WALLPAPER_PREVIEW_META_DATA

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

Constant Value: "android.wallpaper.preview"

Public Methods

public void clear ()

Added in API level 5

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

This method requires the caller to hold the permission SET_WALLPAPER .

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

public void clearWallpaperOffsets ( IBinder windowToken)

Added in API level 5

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 The window who these offsets should be associated with, as returned by View.getWindowToken() .

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.

public Drawable getBuiltInDrawable ()

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

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 The height of the returned drawable
scaleToFit If true, scale the wallpaper down rather than just cropping it
horizontalAlignment 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 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

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 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/*"
Throws
IllegalArgumentException if the URI is not a content URI or its MIME type is not "image/*"

public int getDesiredMinimumHeight ()

Added in API level 5

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.

Returns
  • The desired minimum height for the wallpaper. This value should be honored by applications that set the wallpaper but it is not mandatory.

public int getDesiredMinimumWidth ()

Added in API level 5

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.

Returns
  • The desired minimum width for the wallpaper. This value should be honored by applications that set the wallpaper but it is not mandatory.

public Drawable getDrawable ()

Added in API level 5

Retrieve the current system wallpaper; if no wallpaper is set, the system built-in static wallpaper is returned. This is returned as an abstract Drawable that you can install in a View to display whatever wallpaper the user has currently set.

Returns
  • Returns a Drawable object that will draw the wallpaper.

public Drawable getFastDrawable ()

Added in API level 5

Like getDrawable() , 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).

Returns
  • Returns a Drawable object that will draw the wallpaper.

public static WallpaperManager getInstance ( Context context)

Added in API level 5

Retrieve a WallpaperManager associated with the given Context.

public WallpaperInfo getWallpaperInfo ()

Added in API level 7

If the current wallpaper is a live wallpaper component, return the information about that wallpaper. Otherwise, if it is a static image, simply return null.

public boolean hasResourceWallpaper (int resid)

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.

public Drawable peekDrawable ()

Added in API level 5

Retrieve the current system wallpaper; if there is no wallpaper set, a null pointer is returned. This is returned as an abstract Drawable that you can install in a View to display whatever wallpaper the user has currently set.

Returns
  • Returns a Drawable object that will draw the wallpaper or a null pointer if these is none.

public Drawable peekFastDrawable ()

Added in API level 5

Like getFastDrawable() , but if there is no wallpaper set, a null pointer is returned.

Returns
  • Returns an optimized Drawable object that will draw the wallpaper or a null pointer if these is none.

public void sendWallpaperCommand ( IBinder windowToken, String action, int x, int y, int z, Bundle extras)

Added in API level 7

Send an arbitrary command to the current active wallpaper.

Parameters
windowToken The window who these offsets should be associated with, as returned by View.getWindowToken() .
action Name of the command to perform. This must be a scoped name to avoid collisions, such as "com.mycompany.wallpaper.DOIT".
x Arbitrary integer argument based on command.
y Arbitrary integer argument based on command.
z Arbitrary integer argument based on command.
extras Optional additional information for the command, or null.

public void setBitmap ( Bitmap bitmap)

Added in API level 5

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 ACTION_WALLPAPER_CHANGED is broadcast.

This method requires the caller to hold the permission SET_WALLPAPER .

Parameters
bitmap The bitmap to save.
Throws
IOException If an error occurs reverting to the built-in wallpaper.

public void setResource (int resid)

Added in API level 5

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 ACTION_WALLPAPER_CHANGED is broadcast.

This method requires the caller to hold the permission SET_WALLPAPER .

Parameters
resid The bitmap to save.
Throws
IOException If an error occurs reverting to the built-in wallpaper.

public void setStream ( InputStream data)

Added in API level 5

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 ACTION_WALLPAPER_CHANGED is broadcast.

This method requires the caller to hold the permission SET_WALLPAPER .

Parameters
data A stream containing the raw data to install as a wallpaper.
Throws
IOException If an error occurs reverting to the built-in wallpaper.

public void setWallpaperOffsetSteps (float xStep, float yStep)

Added in API level 7

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

Parameters
xStep The X offset delta from one screen to the next one
yStep The Y offset delta from one screen to the next one

public void setWallpaperOffsets ( IBinder windowToken, float xOffset, float yOffset)

Added in API level 5

Set the 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 screen.

Parameters
windowToken The window who these offsets should be associated with, as returned by View.getWindowToken() .
xOffset The offset along the X dimension, from 0 to 1.
yOffset The offset along the Y dimension, from 0 to 1.

public void suggestDesiredDimensions (int minimumWidth, int minimumHeight)

Added in API level 5

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.

Note developers, who don't seem to be reading this. This is for home screens to tell what size wallpaper they would like. Nobody else should be calling this! Certainly not other non-home-screen apps that change the wallpaper. Those apps are supposed to retrieve the suggested size so they can construct a wallpaper that matches it.

This method requires the caller to hold the permission SET_WALLPAPER_HINTS .

Parameters
minimumWidth Desired minimum width
minimumHeight Desired minimum height