1<p>This sample demonstrates how to create a live wallpaper and bundle it in an 2<code>.apk</code> that users can install on their devices.</p> 3 4<p>In terms of implementation, a live wallpaper is very similar to a regular 5Android <a href="../../../reference/android/app/Service.html">service</a>. The 6only difference is the addition of a new method, <a 7href="../../../reference/android/service/wallpaper/WallpaperService.html#onCreateEngine()"><code> 8onCreateEngine()</code></a>, whose goal is to 9create a <a 10href="../../../reference/android/service/wallpaper/WallpaperService.Engine.html"> 11<code>WallpaperService.Engine</code></a>. The engine is responsible for 12handling the lifecycle and drawing of a wallpaper. The system provides a surface 13on which you can draw, just like you would with a <a 14href="../../../reference/android/view/SurfaceView.html"><code>SurfaceView</code></a>. 15The wallpapers you create can respond to touch events on the screen and 16have access to all the facilities of the platform: SGL (2D drawing), OpenGL (3D 17drawing), GPS, accelerometers, network access, and so on. </p> 18 19<p>The examples in this application show how to set up a wallpaper service that 20creates a <code>WallpaperService.Engine</code> to manage the service lifecycle, 21render the wallpaper, handle touch events, and so on. The examples also show how 22a wallpaper should stop drawing when its visibility changes, for example, when 23the user launches an application that covers the home screen. Drawing only when 24visible is an important implementation guideline for live wallpapers because it 25minimizes the wallpaper's impact on system performance and battery life. 26</p> 27 28<p>The application includes two wallpaper services and a wallpaper settings 29activity:<p> 30 31<ul> 32<li><a 33href="src/com/example/android/livecubes/cube1/CubeWallpaper1.html"><code> 34CubeWallpaper1</code></a> — a wallpaper service that draws and animates a 35wire-frame cube to a <a 36href="../../../reference/android/graphics/Canvas.html"><code>Canvas</code></a>. 37</li> 38<li><a 39href="src/com/example/android/livecubes/cube2/CubeWallpaper2.html"><code>CubeWallpaper2</code></a> 40— a wallpaper service that draws and animates a 41wire-frame shape to a <code>Canvas</code>. The shape is set by the user, by means 42of the <code>cube2.CubeWallpaper2Settings</code> settings activity (see below). The 43wallpaper service implements a listener callback method that captures the user's 44wallpaper shape preference. </li> 45<li><a 46href="src/com/example/android/livecubes/cube2/CubeWallpaper2Settings.html"><code>CubeWallpaper2Settings</code></a> 47— a wallpaper service that draws and 48animates a wire-frame shape to a <code>Canvas</code>. The shape is set by the 49user through a simple settings activity, 50<code>cube2.CubeWallpaper2Settings</code>, also included in the app. The 51wallpaper service implements a listener callback method that captures the user's 52wallpaper shape preference. </li> 53</ul> 54 55<p>If you are developing a live wallpaper, remember that the feature is 56supported only on Android 2.1 (API level 7) and higher versions of the platform. 57To ensure that your application can only be installed on devices that support 58live wallpapers, remember to add the following to the application's manifest 59before publishing to Google Play:</p> 60 61<ul> 62<li><code><uses-sdk android:minSdkVersion="7" /></code>, which indicates 63to Google Play and the platform that your application requires Android 2.1 or 64higher. For more information, see the <a href="../../../guide/appendix/api-levels.html">API Levels</a> 65and the documentation for the 66<a href="../../../guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> 67element.</li> 68<li><code><uses-feature android:name="android.software.live_wallpaper" /></code>, 69which tells Google Play that your application includes a live wallpaper. 70Google Play uses this feature as a filter, when presenting users lists of 71available applications. When you declaring this feature, Google Play 72displays your application only to users whose devices support live wallpapers, 73while hiding it from other devices on which it would not be able to run. For 74more information, see the documentation for the 75<a href="../../../guide/topics/manifest/uses-feature-element.html"><code><uses-feature></code></a> 76element.</li> 77</ul> 78 79<p>For more information about live wallpapers, see the 80<a href="../../articles/live-wallpapers.html">Live Wallpapers</a> article. </p> 81 82<img alt="Screenshot 1" src="../images/CubeLiveWallpaper1.png" /> 83<img alt="Screenshot 3" src="../images/CubeLiveWallpaper3.png" /> 84
