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