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