1page.title=Live Wallpapers 2parent.title=Articles 3parent.link=../browser.html?tag=article 4@jd:body 5 6 7<div id="qv-wrapper"> 8<div id="qv"> 9 10 <h2>See also</h2> 11 <ol> 12 <li><a href="{@docRoot}resources/samples/CubeLiveWallpaper/index.html">Live Wallpaper 13sample</a></li> 14 </ol> 15 16</div> 17</div> 18 19<p>Starting with Android 2.1 (API Level 7), users can now enjoy <em>live 20wallpapers</em> — richer, animated, interactive backgrounds — on 21their home screens. A live wallpaper is very similar to a normal Android 22application and has access to all the facilities of the platform: SGL (2D 23drawing), OpenGL (3D drawing), GPS, accelerometers, network access, etc. The 24live wallpapers included on Nexus One demonstrate the use of some of these APIs 25to create fun and interesting user experiences. For instance, the Grass 26wallpaper uses the phone's location to compute sunrise and sunset times in order 27to display the appropriate sky.</p> 28 29<img src="images/live_wallpapers_small.png" style="align:center" /> 30 31<p>Creating your own live wallpaper is easy, especially if you have had 32previous experience with {@link android.view.SurfaceView} or {@link 33android.graphics.Canvas}. 34To learn how to create a live wallpaper, you should check out the <a 35href="../samples/CubeLiveWallpaper/index.html">CubeLiveWallpaper sample code</a>.</p> 36 37<p>In terms of implementation, a live wallpaper is very similar to a {@link android.app.Service}. 38The only difference is the addition of a new method, {@link 39android.service.wallpaper.WallpaperService#onCreateEngine()}, whose goal is to create a {@link 40android.service.wallpaper.WallpaperService.Engine}. The engine is responsible for 41handling the lifecycle and drawing of a wallpaper. The system provides a surface 42on which you can draw, just like you would with a {@link android.view.SurfaceView}. 43Drawing a wallpaper can be very expensive so you should optimize your code 44as much as possible to avoid using too much CPU, not only for battery life 45but also to avoid slowing down the rest of the system. That is also why the 46most important part of the lifecycle of a wallpaper is when it becomes visible, as indicated 47by a call to {@link android.service.wallpaper.WallpaperService.Engine#onVisibilityChanged 48onVisibilityChanged()}. 49When invisible, such as when the user launches an application that covers 50the home screen, a wallpaper must stop all activity.</p> 51 52<p>The engine can also implement several methods to interact with the user 53or the home application. For instance, if you want your wallpaper to scroll 54along when the user swipes from one home screen to another, you can use 55{@link android.service.wallpaper.WallpaperService.Engine#onOffsetsChanged 56onOffsetsChanged()}. 57To react to touch events, simply implement {@link 58android.service.wallpaper.WallpaperService.Engine#onTouchEvent onTouchEvent()}. 59Finally, applications can send arbitrary commands to the live wallpaper. 60Currently, only the standard home application sends commands to the 61{@link android.service.wallpaper.WallpaperService.Engine#onCommand onCommand()} 62method of the live wallpaper:</p> 63 64<ul> 65<li><code>android.wallpaper.tap</code>: When the user taps an empty space 66on the workspace. This command is interpreted by the Nexus and Water live 67wallpapers to make the wallpaper react to user interaction. For instance, 68if you tap an empty space on the Water live wallpaper, new ripples appear 69under your finger.</li> 70<li><code>android.home.drop</code>: When the user drops an icon or a widget 71on the workspace. This command is also interpreted by the Nexus and Water 72live wallpapers.</li> 73</ul> 74 75<p>If you are developing a live wallpaper, remember that the feature is 76supported only on Android 2.1 (API level 7) and higher versions of the platform. 77To ensure that your application can only be installed on devices that support 78live wallpapers, remember to add the following to the application's manifest 79before publishing to Android Market:</p> 80 81<ul> 82<li><code><uses-sdk android:minSdkVersion="7" /></code>, which indicates 83to Android Market and the platform that your application requires Android 2.1 or 84higher. For more information, see the <a href="{@docRoot}guide/appendix/api-levels.html">API 85Levels</a> and the documentation for the 86<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> 87element.</li> 88<li><code><uses-feature android:name="android.software.live_wallpaper" /></code>, 89which tells Android Market that your application includes a live wallpaper 90Android Market uses this feature as a filter, when presenting users lists of 91available applications. When you declaring this feature, Android Market 92displays your application only to users whose devices support live wallpapers, 93while hiding it from other devices on which it would not be able to run. For 94more information, see the documentation for the 95<a 96href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code 97<uses-feature></a> 98element.</li> 99</ul> 100 101<p>Many great live wallpapers are already available on Android Market and 102we can't wait to see more!</p> 103
