Android APIs
public class

WallpaperService.Engine

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

Class Overview

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 onCreateEngine() to return your concrete Engine implementation.

Summary

Public Constructors
WallpaperService.Engine()
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.
SurfaceHolder getSurfaceHolder()
Provides access to the surface in which this wallpaper is drawn.
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 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 sendWallpaperCommand(IBinder, String, int, int, int, Bundle).
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)
void onSurfaceCreated(SurfaceHolder holder)
void onSurfaceDestroyed(SurfaceHolder holder)
void onSurfaceRedrawNeeded(SurfaceHolder holder)
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 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)
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public WallpaperService.Engine ()

Added in API level 7

Public Methods

public int getDesiredMinimumHeight ()

Added in API level 7

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

Returns
int

public int getDesiredMinimumWidth ()

Added in API level 7

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

Returns
int

public SurfaceHolder getSurfaceHolder ()

Added in API level 7

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

Returns
SurfaceHolder

public boolean isPreview ()

Added in API level 7

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

public boolean isVisible ()

Added in API level 7

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

Returns
boolean

public void onApplyWindowInsets (WindowInsets insets)

Added in API level 21

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).

Parameters
insets Insets to apply.

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

Added in API level 7

Process a command that was sent to the wallpaper with sendWallpaperCommand(IBinder, String, int, int, int, Bundle). The default implementation does nothing, and always returns null as the result.

Parameters
action The name of the command to perform. This tells you what to do and how to interpret the rest of the arguments.
x Generic integer parameter.
y Generic integer parameter.
z Generic integer parameter.
extras Any additional parameters.
resultRequested 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.

public void onCreate (SurfaceHolder surfaceHolder)

Added in API level 7

Called once to initialize the engine. After returning, the engine's surface will be created by the framework.

Parameters
surfaceHolder

public void onDesiredSizeChanged (int desiredWidth, int desiredHeight)

Added in API level 7

Called when an application has changed the desired virtual size of the wallpaper.

Parameters
desiredWidth
desiredHeight

public void onDestroy ()

Added in API level 7

Called right before the engine is going away. After this the surface will be destroyed and this Engine object is no longer valid.

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

Added in API level 7

Called to inform you of the wallpaper's offsets changing within its contain, corresponding to the container's call to WallpaperManager.setWallpaperOffsets().

Parameters
xOffset
yOffset
xOffsetStep
yOffsetStep
xPixelOffset
yPixelOffset

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

Added in API level 7

Convenience for SurfaceHolder.Callback.surfaceChanged().

Parameters
holder
format
width
height

public void onSurfaceCreated (SurfaceHolder holder)

Added in API level 7

Convenience for SurfaceHolder.Callback.surfaceCreated().

Parameters
holder

public void onSurfaceDestroyed (SurfaceHolder holder)

Added in API level 7

Convenience for SurfaceHolder.Callback.surfaceDestroyed().

Parameters
holder

public void onSurfaceRedrawNeeded (SurfaceHolder holder)

Added in API level 9

Convenience for SurfaceHolder.Callback.surfaceRedrawNeeded().

Parameters
holder

public void onTouchEvent (MotionEvent event)

Added in API level 7

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.

Parameters
event

public void onVisibilityChanged (boolean visible)

Added in API level 7

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..

Parameters
visible

public void setOffsetNotificationsEnabled (boolean enabled)

Added in API level 15

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 whether the wallpaper wants to receive offset notifications

public void setTouchEventsEnabled (boolean enabled)

Added in API level 7

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(MotionEvent).

Parameters
enabled

Protected Methods

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

Added in API level 14

Parameters
prefix
fd
out
args