Added in API level 7

Summary: Ctors | Methods | Protected Methods | Inherited Methods

WallpaperService.Engine

---

Kotlin |Java

public class WallpaperService.Engine
extends Object

java.lang.Object
↳	android.service.wallpaper.WallpaperService.Engine

---

The actual implementation of a wallpaper. A wallpaper service may have multiple instances running (for example as a real wallpaper and as a preview), each of which is represented by its own Engine instance. You must implement WallpaperService.onCreateEngine() to return your concrete Engine implementation.

Summary

Public constructors
Engine() Default constructor

Public methods
int	getDesiredMinimumHeight() Convenience for WallpaperManager.getDesiredMinimumHeight(), returning the height that the system would like this wallpaper to run in.
int	getDesiredMinimumWidth() Convenience for WallpaperManager.getDesiredMinimumWidth(), returning the width that the system would like this wallpaper to run in.
Context	getDisplayContext() The Context with resources that match the current display the wallpaper is on.
SurfaceHolder	getSurfaceHolder() Provides access to the surface in which this wallpaper is drawn.
int	getWallpaperFlags() Returns the current wallpaper flags indicating which screen this Engine is rendering to.
boolean	isPreview() Returns true if this engine is running in preview mode -- that is, it is being shown to the user before they select it as the actual wallpaper.
boolean	isVisible() Return whether the wallpaper is currently visible to the user, this is the last value supplied to onVisibilityChanged(boolean).
void	notifyColorsChanged() Notifies the engine that wallpaper colors changed significantly.
void	onApplyWindowInsets(WindowInsets insets) Called with the current insets that are in effect for the wallpaper.
Bundle	onCommand(String action, int x, int y, int z, Bundle extras, boolean resultRequested) Process a command that was sent to the wallpaper with WallpaperManager.sendWallpaperCommand.
WallpaperColors	onComputeColors() Called by the system when it needs to know what colors the wallpaper is using.
void	onCreate(SurfaceHolder surfaceHolder) Called once to initialize the engine.
void	onDesiredSizeChanged(int desiredWidth, int desiredHeight) Called when an application has changed the desired virtual size of the wallpaper.
void	onDestroy() Called right before the engine is going away.
void	onOffsetsChanged(float xOffset, float yOffset, float xOffsetStep, float yOffsetStep, int xPixelOffset, int yPixelOffset) Called to inform you of the wallpaper's offsets changing within its contain, corresponding to the container's call to WallpaperManager.setWallpaperOffsets().
void	onSurfaceChanged(SurfaceHolder holder, int format, int width, int height) Convenience for SurfaceHolder.Callback.surfaceChanged().
void	onSurfaceCreated(SurfaceHolder holder) Convenience for SurfaceHolder.Callback.surfaceCreated().
void	onSurfaceDestroyed(SurfaceHolder holder) Convenience for SurfaceHolder.Callback.surfaceDestroyed().
void	onSurfaceRedrawNeeded(SurfaceHolder holder) Convenience for SurfaceHolder.Callback.surfaceRedrawNeeded().
void	onTouchEvent(MotionEvent event) Called as the user performs touch-screen interaction with the window that is currently showing this wallpaper.
void	onVisibilityChanged(boolean visible) Called to inform you of the wallpaper becoming visible or hidden.
void	onWallpaperFlagsChanged(int which) Called when the current wallpaper flags change.
void	onZoomChanged(float zoom) Called when the zoom level of the wallpaper changed.
void	setOffsetNotificationsEnabled(boolean enabled) Control whether this wallpaper will receive notifications when the wallpaper has been scrolled.
void	setTouchEventsEnabled(boolean enabled) Control whether this wallpaper will receive raw touch events from the window manager as the user interacts with the window that is currently displaying the wallpaper.

Protected methods
void	dump(String prefix, FileDescriptor fd, PrintWriter out, String[] args)

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.

Public constructors

Engine

Added in API level 7

public Engine ()

Default constructor

Public methods

getDesiredMinimumHeight

Added in API level 7

public int getDesiredMinimumHeight ()

Convenience for WallpaperManager.getDesiredMinimumHeight(), returning the height that the system would like this wallpaper to run in.

Returns
int

getDesiredMinimumWidth

Added in API level 7

public int getDesiredMinimumWidth ()

Convenience for WallpaperManager.getDesiredMinimumWidth(), returning the width that the system would like this wallpaper to run in.

Returns
int

getDisplayContext

Added in API level 29

public Context getDisplayContext ()

The Context with resources that match the current display the wallpaper is on. For multiple display environment, multiple engines can be created to render on each display, but these displays may have different densities. Use this context to get the corresponding resources for currently display, avoiding the context of the service.

The display context will never be null after Engine.onCreate(SurfaceHolder) has been called.

Returns
Context	A Context for current display.

getSurfaceHolder

Added in API level 7

public SurfaceHolder getSurfaceHolder ()

Provides access to the surface in which this wallpaper is drawn.

Returns
SurfaceHolder

getWallpaperFlags

Added in API level 34

public int getWallpaperFlags ()

Returns the current wallpaper flags indicating which screen this Engine is rendering to.

Returns
int	Value is either 0 or a combination of WallpaperManager.FLAG_SYSTEM, and WallpaperManager.FLAG_LOCK

isPreview

Added in API level 7

public boolean isPreview ()

Returns true if this engine is running in preview mode -- that is, it is being shown to the user before they select it as the actual wallpaper.

Returns
boolean

isVisible

Added in API level 7

public boolean isVisible ()

Return whether the wallpaper is currently visible to the user, this is the last value supplied to onVisibilityChanged(boolean).

Returns
boolean

notifyColorsChanged

Added in API level 27

public void notifyColorsChanged ()

Notifies the engine that wallpaper colors changed significantly. This will trigger a onComputeColors() call.

onApplyWindowInsets

Added in API level 21

public void onApplyWindowInsets (WindowInsets insets)

Called with the current insets that are in effect for the wallpaper. This gives you the part of the overall wallpaper surface that will generally be visible to the user (ignoring position offsets applied to it).
This method must be called from the main thread of your app.

Parameters
insets	WindowInsets: Insets to apply.

onCommand

Added in API level 7

public Bundle onCommand (String action, 
                int x, 
                int y, 
                int z, 
                Bundle extras, 
                boolean resultRequested)

Process a command that was sent to the wallpaper with WallpaperManager.sendWallpaperCommand. The default implementation does nothing, and always returns null as the result.
This method must be called from the main thread of your app.

Parameters
action	String: The name of the command to perform. This tells you what to do and how to interpret the rest of the arguments.
x	int: Generic integer parameter.
y	int: Generic integer parameter.
z	int: Generic integer parameter.
extras	Bundle: Any additional parameters.
resultRequested	boolean: If true, the caller is requesting that a result, appropriate for the command, be returned back.

Returns
Bundle	If returning a result, create a Bundle and place the result data in to it. Otherwise return null.

onComputeColors

Added in API level 27

public WallpaperColors onComputeColors ()

Called by the system when it needs to know what colors the wallpaper is using. You might return null if no color information is available at the moment. In that case you might want to call notifyColorsChanged() when color information becomes available.

The simplest way of creating a WallpaperColors object is by using WallpaperColors.fromBitmap(Bitmap) or WallpaperColors.fromDrawable(Drawable), but you can also specify your main colors by constructing a WallpaperColors object manually.
This method must be called from the main thread of your app.

Returns
WallpaperColors	Wallpaper colors.

onCreate

Added in API level 7

public void onCreate (SurfaceHolder surfaceHolder)

Called once to initialize the engine. After returning, the engine's surface will be created by the framework.
This method must be called from the main thread of your app.

Parameters
surfaceHolder	SurfaceHolder

onDesiredSizeChanged

Added in API level 7

public void onDesiredSizeChanged (int desiredWidth, 
                int desiredHeight)

Called when an application has changed the desired virtual size of the wallpaper.
This method must be called from the main thread of your app.

Parameters
desiredWidth	int
desiredHeight	int

onDestroy

Added in API level 7

public void onDestroy ()

Called right before the engine is going away. After this the surface will be destroyed and this Engine object is no longer valid.
This method must be called from the main thread of your app.

onOffsetsChanged

Added in API level 7

public void onOffsetsChanged (float xOffset, 
                float yOffset, 
                float xOffsetStep, 
                float yOffsetStep, 
                int xPixelOffset, 
                int yPixelOffset)

Called to inform you of the wallpaper's offsets changing within its contain, corresponding to the container's call to WallpaperManager.setWallpaperOffsets().
This method must be called from the main thread of your app.

Parameters
xOffset	float
yOffset	float
xOffsetStep	float
yOffsetStep	float
xPixelOffset	int
yPixelOffset	int

onSurfaceChanged

Added in API level 7

public void onSurfaceChanged (SurfaceHolder holder, 
                int format, 
                int width, 
                int height)

Convenience for SurfaceHolder.Callback.surfaceChanged().
This method must be called from the main thread of your app.

Parameters
holder	SurfaceHolder
format	int
width	int
height	int

onSurfaceCreated

Added in API level 7

public void onSurfaceCreated (SurfaceHolder holder)

Convenience for SurfaceHolder.Callback.surfaceCreated().
This method must be called from the main thread of your app.

Parameters
holder	SurfaceHolder

onSurfaceDestroyed

Added in API level 7

public void onSurfaceDestroyed (SurfaceHolder holder)

Convenience for SurfaceHolder.Callback.surfaceDestroyed().
This method must be called from the main thread of your app.

Parameters
holder	SurfaceHolder

onSurfaceRedrawNeeded

Added in API level 9

public void onSurfaceRedrawNeeded (SurfaceHolder holder)

Convenience for SurfaceHolder.Callback.surfaceRedrawNeeded().
This method must be called from the main thread of your app.

Parameters
holder	SurfaceHolder

onTouchEvent

Added in API level 7

public void onTouchEvent (MotionEvent event)

Called as the user performs touch-screen interaction with the window that is currently showing this wallpaper. Note that the events you receive here are driven by the actual application the user is interacting with, so if it is slow you will get fewer move events.
This method must be called from the main thread of your app.

Parameters
event	MotionEvent

onVisibilityChanged

Added in API level 7

public void onVisibilityChanged (boolean visible)

Called to inform you of the wallpaper becoming visible or hidden. It is very important that a wallpaper only use CPU while it is visible..
This method must be called from the main thread of your app.

Parameters
visible	boolean

onWallpaperFlagsChanged

Added in API level 34

public void onWallpaperFlagsChanged (int which)

Called when the current wallpaper flags change.
This method must be called from the main thread of your app.

Parameters
which	int: The new flag value Value is either 0 or a combination of WallpaperManager.FLAG_SYSTEM, and WallpaperManager.FLAG_LOCK

See also:

• getWallpaperFlags()

onZoomChanged

Added in API level 30

public void onZoomChanged (float zoom)

Called when the zoom level of the wallpaper changed. This method will be called with the initial zoom level when the surface is created.
This method must be called from the main thread of your app.

Parameters
zoom	float: the zoom level, between 0 indicating fully zoomed in and 1 indicating fully zoomed out. Value is between 0f and 1f inclusive

setOffsetNotificationsEnabled

Added in API level 15

public void setOffsetNotificationsEnabled (boolean enabled)

Control whether this wallpaper will receive notifications when the wallpaper has been scrolled. By default, wallpapers will receive notifications, although the default static image wallpapers do not. It is a performance optimization to set this to false.

Parameters
enabled	boolean: whether the wallpaper wants to receive offset notifications

setTouchEventsEnabled

Added in API level 7

public void setTouchEventsEnabled (boolean enabled)

Control whether this wallpaper will receive raw touch events from the window manager as the user interacts with the window that is currently displaying the wallpaper. By default they are turned off. If enabled, the events will be received in onTouchEvent(android.view.MotionEvent).

Parameters
enabled	boolean

Protected methods

dump

Added in API level 14

protected void dump (String prefix, 
                FileDescriptor fd, 
                PrintWriter out, 
                String[] args)

Parameters
prefix	String
fd	FileDescriptor
out	PrintWriter
args	String