# emacs support from sdk.git
sdk/files/android.el tools/lib/android.el
-# samples
+# samples to include in the sdk samples package
+#
+# the list here should match the list of samples that we generate docs for,
+# (see web_docs_sample_code_flags in frameworks/base/Android.mk)
development/samples/source.properties samples/${PLATFORM_NAME}/source.properties
development/apps/GestureBuilder samples/${PLATFORM_NAME}/GestureBuilder
development/samples/BluetoothChat samples/${PLATFORM_NAME}/BluetoothChat
development/samples/LunarLander samples/${PLATFORM_NAME}/LunarLander
development/samples/NotePad samples/${PLATFORM_NAME}/NotePad
development/samples/ApiDemos samples/${PLATFORM_NAME}/ApiDemos
+development/samples/SampleSyncAdapter samples/${PLATFORM_NAME}/SampleSyncAdapter
development/samples/SkeletonApp samples/${PLATFORM_NAME}/SkeletonApp
development/samples/Snake samples/${PLATFORM_NAME}/Snake
development/samples/SoftKeyboard samples/${PLATFORM_NAME}/SoftKeyboard
--- /dev/null
+<p>This sample demonstrates how to create a live wallpaper and bundle it in an
+<code>.apk</code> that users can install on their devices.</p>
+
+<p>In terms of implementation, a live wallpaper is very similar to a regular
+Android <a href="../../../reference/android/app/Service.html">service</a>. The
+only difference is the addition of a new method, <a
+href="../../../reference/android/service/wallpaper/WallpaperService.
+html#onCreateEngine()"><code>onCreateEngine()</code></a>, whose goal is to
+create a <a
+href="../../../reference/android/service/wallpaper/WallpaperService.Engine.html">
+<code>WallpaperService.Engine</code></a>. The engine is responsible for
+handling the lifecycle and drawing of a wallpaper. The system provides a surface
+on which you can draw, just like you would with a <a
+href="../../../reference/android/view/SurfaceView.html"><code>SurfaceView</code></a>.
+The wallpapers you create can respond to touch events on the screen and
+have access to all the facilities of the platform: SGL (2D drawing), OpenGL (3D
+drawing), GPS, accelerometers, network access, and so on. </p>
+
+<p>The examples in this application show how to set up a wallpaper service that
+creates a <code>WallpaperService.Engine</code> to manage the service lifecycle,
+render the wallpaper, handle touch events, and so on. The examples also show how
+a wallpaper should stop drawing when its visibility changes, for example, when
+the user launches an application that covers the home screen. Drawing only when
+visible is an important implementation guideline for live wallpapers because it
+minimizes the wallpaper's impact on system performance and battery life.
+</p>
+
+<p>The application includes two wallpaper services and a wallpaper settings
+activity:<p>
+
+<ul>
+<li><a
+href="src/com/example/android/livecubes/cube1/CubeWallpaper1.html"><code>
+CubeWallpaper1</code></a> — a wallpaper service that draws and animates a
+wire-frame cube to a <a
+href="../../../reference/android/graphics/Canvas.html"><code>Canvas</code></a>.
+</li>
+<li><a
+href="src/com/example/android/livecubes/cube2/CubeWallpaper2.html"><code>CubeWallpaper2</code></a>
+— a wallpaper service that draws and animates a
+wire-frame shape to a <code>Canvas</code>. The shape is set by the user, by means
+of the <code>cube2.CubeWallpaper2Settings</code> settings activity (see below). The
+wallpaper service implements a listener callback method that captures the user's
+wallpaper shape preference. </li>
+<li><a
+href="src/com/example/android/livecubes/cube2/CubeWallpaper2Settings.html"><code>CubeWallpaper2Settings</code></a>
+— a wallpaper service that draws and
+animates a wire-frame shape to a <code>Canvas</code>. The shape is set by the
+user through a simple settings activity,
+<code>cube2.CubeWallpaper2Settings</code>, also included in the app. The
+wallpaper service implements a listener callback method that captures the user's
+wallpaper shape preference. </li>
+</ul>
+
+<p>If you are developing a live wallpaper, remember that the feature is
+supported only on Android 2.1 (API level 7) and higher versions of the platform.
+To ensure that your application can only be installed on devices that support
+live wallpapers, remember to add the following to the application's manifest
+before publishing to Android Market:</p>
+
+<ul>
+<li><code><uses-sdk android:minSdkVersion="7" /></code>, which indicates
+to Android Market and the platform that your application requires Android 2.1 or
+higher. For more information, see the <a href="../../../guide/appendix/api-levels.html">API Levels</a>
+and the documentation for the
+<a href="../../../guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a>
+element.</li>
+<li><code><uses-feature android:name="android.software.live_wallpaper" /></code>,
+which tells Android Market that your application includes a live wallpaper.
+Android Market uses this feature as a filter, when presenting users lists of
+available applications. When you declaring this feature, Android Market
+displays your application only to users whose devices support live wallpapers,
+while hiding it from other devices on which it would not be able to run. For
+more information, see the documentation for the
+<a href="../../../guide/topics/manifest/uses-feature-element.html"><code><uses-feature></code></a>
+element.</li>
+</ul>
+
+<p>For more information about live wallpapers, see the
+<a href="../../articles/live-wallpapers.html">Live Wallpapers</a> article. </p>
+
+<img alt="Screenshot 1" src="../images/CubeLiveWallpaper1.png" />
+<img alt="Screenshot 3" src="../images/CubeLiveWallpaper3.png" />
-<p>A sample that demonstrates how an application can communicate with cloud-based services and synchronize their data with data stored locally in a content provider.
-The sample uses two related parts of the Android framework — the account manager and the synchronization manager (through a sync adapter).</p>
+<p>This sample demonstrates how an application can communicate with a
+cloud-based service and synchronize its data with data stored locally in a
+content provider. The sample uses two related parts of the Android framework
+— the account manager and the synchronization manager (through a sync
+adapter).</p>
-<p> The <a href="../../../android/accounts/AccountManager">account manager</a> allows sharing of credentials across multiple applications and services.
-Users enter the credentials for each account only once — applications with the <code>USE_CREDENTIALS</code> permission can then query the account manager
- to obtain an auth token for the account.The authenticator (a pluggable component of account manager) requests credentials from the user, validates them
- with an authentication server running in the cloud, and then stores them to the AccountManager.
-This sample demonstrates how to write an authenticator for your
-service by extending the new <code><a href="../../../android/accounts/AbstractAccountAuthenticator.html">AbstractAccountAuthenticator</a></code> abstract class.
-</p>
+<p> The <a
+href="../../../reference/android/accounts/AccountManager.html">account
+manager</a> allows sharing of credentials across multiple applications and
+services. Users enter the credentials for each account only once —
+applications with the <code>USE_CREDENTIALS</code> permission can then query the
+account manager to obtain an auth token for the account. An authenticator (a
+pluggable component of account manager) requests credentials from the user,
+validates them with an authentication server running in the cloud, and then
+stores them to the account manager. This sample demonstrates how to write an
+authenticator for your service by extending the new <code><a
+href="../../../reference/android/accounts/AbstractAccountAuthenticator.html">
+AbstractAccountAuthenticator</a></code> abstract class. </p>
-<p>The sync adapter (essential to the synchronization service) declares the account type and ContentProvider authority to the sync manager.
-This sample demosntrates how to write your own sync adapters by extending the <code><a href="../../../android/content/AbstractThreadedSyncAdapter.html">AbstractThreadedSyncAdapter</a></code>
-abstract class and implementing the onPerformSync() method that gets called whenever the sync manager issues a sync operation for that sync adapter.
-</p>
+<p>The sync adapter (essential to the synchronization service) declares the
+account type and ContentProvider authority to the sync manager. This sample
+demosntrates how to write your own sync adapters by extending the <code><a
+href="../../../reference/android/content/AbstractThreadedSyncAdapter.html">
+AbstractThreadedSyncAdapter</a></code> abstract class and implementing the
+<code>onPerformSync()</code> method, which gets called whenever the sync manager
+issues a sync operation for that sync adapter. </p>
-<p> The service for this sample application is running at: <br>
-http://samplesyncadapter.appspot.com/users
-</p>
+<p> The cloud-based service for this sample application is running at: </p>
+<p style="margin-left:2em;">http://samplesyncadapter.appspot.com/users</p>
-<p class="note">When you install this sample application, a new syncable "SampleSyncAdapter" account will be added to your phone's account manager.
-You can go to "Settings | Accounts & sync" to view the accounts that are stored in the account manager and to change their sync settings. </p>
+<p>When you install this sample application, a new syncable "SampleSyncAdapter"
+account will be added to your phone's account manager. You can go to "Settings |
+Accounts & Sync" to view the account and change its sync settings. </p>
<img alt="Screenshot 1" src="../images/SampleSyncAdapter1.png" />
<img alt="Screenshot 2" src="../images/SampleSyncAdapter2.png" />
-<img alt="Screenshot 3" src="../images/SampleSyncAdapter3.png" />
\ No newline at end of file
+<img alt="Screenshot 3" src="../images/SampleSyncAdapter3.png" />