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

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

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.

public SurfaceHolder getSurfaceHolder ()

Added in API level 7

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

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.

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

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

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.

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

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

Added in API level 7

public void onSurfaceCreated ( SurfaceHolder holder)

Added in API level 7

public void onSurfaceDestroyed ( SurfaceHolder holder)

Added in API level 7

public void onSurfaceRedrawNeeded ( SurfaceHolder holder)

Added in API level 9

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.

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

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

Protected Methods

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