frameworks/base/docs/html/resources/articles/live-wallpapers.jd

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