This sample demonstrates how to create a live wallpaper and bundle it in an .apk that users can install on their devices.

In terms of implementation, a live wallpaper is very similar to a regular Android service. The only difference is the addition of a new method, onCreateEngine(), whose goal is to create a WallpaperService.Engine. The engine is responsible for handling the lifecycle and drawing of a wallpaper. The system provides a surface on which you can draw, just like you would with a SurfaceView. The wallpapers you create can respond to touch events on the screen and have access to all the facilities of the platform: SGL (2D drawing), OpenGL (3D drawing), GPS, accelerometers, network access, and so on.

The examples in this application show how to set up a wallpaper service that creates a WallpaperService.Engine to manage the service lifecycle, render the wallpaper, handle touch events, and so on. The examples also show how a wallpaper should stop drawing when its visibility changes, for example, when the user launches an application that covers the home screen. Drawing only when visible is an important implementation guideline for live wallpapers because it minimizes the wallpaper's impact on system performance and battery life.

The application includes two wallpaper services and a wallpaper settings activity:

• CubeWallpaper1 — a wallpaper service that draws and animates a wire-frame cube to a Canvas.
• CubeWallpaper2 — a wallpaper service that draws and animates a wire-frame shape to a Canvas. The shape is set by the user, by means of the cube2.CubeWallpaper2Settings settings activity (see below). The wallpaper service implements a listener callback method that captures the user's wallpaper shape preference.
• CubeWallpaper2Settings — a wallpaper service that draws and animates a wire-frame shape to a Canvas. The shape is set by the user through a simple settings activity, cube2.CubeWallpaper2Settings, also included in the app. The wallpaper service implements a listener callback method that captures the user's wallpaper shape preference.

If you are developing a live wallpaper, remember that the feature is supported only on Android 2.1 (API level 7) and higher versions of the platform. To ensure that your application can only be installed on devices that support live wallpapers, remember to add the following to the application's manifest before publishing to Google Play:

• <uses-sdk android:minSdkVersion="7" />, which indicates to Google Play and the platform that your application requires Android 2.1 or higher. For more information, see the API Levels and the documentation for the <uses-sdk> element.
• <uses-feature android:name="android.software.live_wallpaper" />, which tells Google Play that your application includes a live wallpaper. Google Play uses this feature as a filter, when presenting users lists of available applications. When you declaring this feature, Google Play displays your application only to users whose devices support live wallpapers, while hiding it from other devices on which it would not be able to run. For more information, see the documentation for the <uses-feature> element.

For more information about live wallpapers, see the Live Wallpapers article.