Merge "Debugging code for #6169553: Make Phone launch faster" into ics-mr1
diff --git a/core/java/android/hardware/GeomagneticField.java b/core/java/android/hardware/GeomagneticField.java
index 96fbe77..0369825 100644
--- a/core/java/android/hardware/GeomagneticField.java
+++ b/core/java/android/hardware/GeomagneticField.java
@@ -19,7 +19,7 @@
import java.util.GregorianCalendar;
/**
- * This class is used to estimated estimate magnetic field at a given point on
+ * Estimates magnetic field at a given point on
* Earth, and in particular, to compute the magnetic declination from true
* north.
*
diff --git a/core/res/res/drawable/activated_background.xml b/core/res/res/drawable/activated_background.xml
index 1047e5b..d92fba1 100644
--- a/core/res/res/drawable/activated_background.xml
+++ b/core/res/res/drawable/activated_background.xml
@@ -14,8 +14,7 @@
limitations under the License.
-->
-<selector xmlns:android="http://schemas.android.com/apk/res/android"
- android:exitFadeDuration="@android:integer/config_mediumAnimTime">
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
<item android:state_activated="true" android:drawable="@android:drawable/list_selector_background_selected" />
<item android:drawable="@color/transparent" />
</selector>
diff --git a/core/res/res/drawable/activated_background_holo_dark.xml b/core/res/res/drawable/activated_background_holo_dark.xml
index a29bcb9..febf2c4 100644
--- a/core/res/res/drawable/activated_background_holo_dark.xml
+++ b/core/res/res/drawable/activated_background_holo_dark.xml
@@ -14,8 +14,7 @@
limitations under the License.
-->
-<selector xmlns:android="http://schemas.android.com/apk/res/android"
- android:exitFadeDuration="@android:integer/config_mediumAnimTime">
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
<item android:state_activated="true" android:drawable="@android:drawable/list_activated_holo" />
<item android:drawable="@color/transparent" />
</selector>
diff --git a/core/res/res/drawable/activated_background_holo_light.xml b/core/res/res/drawable/activated_background_holo_light.xml
index a29bcb9..febf2c4 100644
--- a/core/res/res/drawable/activated_background_holo_light.xml
+++ b/core/res/res/drawable/activated_background_holo_light.xml
@@ -14,8 +14,7 @@
limitations under the License.
-->
-<selector xmlns:android="http://schemas.android.com/apk/res/android"
- android:exitFadeDuration="@android:integer/config_mediumAnimTime">
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
<item android:state_activated="true" android:drawable="@android:drawable/list_activated_holo" />
<item android:drawable="@color/transparent" />
</selector>
diff --git a/core/res/res/drawable/activated_background_light.xml b/core/res/res/drawable/activated_background_light.xml
index 7d737db..5d5681d 100644
--- a/core/res/res/drawable/activated_background_light.xml
+++ b/core/res/res/drawable/activated_background_light.xml
@@ -14,8 +14,7 @@
limitations under the License.
-->
-<selector xmlns:android="http://schemas.android.com/apk/res/android"
- android:exitFadeDuration="@android:integer/config_mediumAnimTime">
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
<item android:state_activated="true" android:drawable="@drawable/list_selector_background_selected_light" />
<item android:drawable="@color/transparent" />
</selector>
diff --git a/core/res/res/drawable/btn_cab_done_holo_dark.xml b/core/res/res/drawable/btn_cab_done_holo_dark.xml
index 65d3496..fe42951 100644
--- a/core/res/res/drawable/btn_cab_done_holo_dark.xml
+++ b/core/res/res/drawable/btn_cab_done_holo_dark.xml
@@ -14,8 +14,7 @@
limitations under the License.
-->
-<selector xmlns:android="http://schemas.android.com/apk/res/android"
- android:exitFadeDuration="@android:integer/config_mediumAnimTime">
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
<item android:state_pressed="true"
android:drawable="@drawable/btn_cab_done_pressed_holo_dark" />
<item android:state_focused="true" android:state_enabled="true"
diff --git a/core/res/res/drawable/btn_cab_done_holo_light.xml b/core/res/res/drawable/btn_cab_done_holo_light.xml
index f6a63f4..f362774 100644
--- a/core/res/res/drawable/btn_cab_done_holo_light.xml
+++ b/core/res/res/drawable/btn_cab_done_holo_light.xml
@@ -14,8 +14,7 @@
limitations under the License.
-->
-<selector xmlns:android="http://schemas.android.com/apk/res/android"
- android:exitFadeDuration="@android:integer/config_mediumAnimTime">
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
<item android:state_pressed="true"
android:drawable="@drawable/btn_cab_done_pressed_holo_light" />
<item android:state_focused="true" android:state_enabled="true"
diff --git a/core/res/res/drawable/item_background.xml b/core/res/res/drawable/item_background.xml
index f7fef82..a1c9ff8 100644
--- a/core/res/res/drawable/item_background.xml
+++ b/core/res/res/drawable/item_background.xml
@@ -14,8 +14,7 @@
limitations under the License.
-->
-<selector xmlns:android="http://schemas.android.com/apk/res/android"
- android:exitFadeDuration="@android:integer/config_mediumAnimTime">
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
<item android:state_window_focused="false" android:drawable="@color/transparent" />
diff --git a/core/res/res/drawable/item_background_holo_dark.xml b/core/res/res/drawable/item_background_holo_dark.xml
index f188df7..7c8590c 100644
--- a/core/res/res/drawable/item_background_holo_dark.xml
+++ b/core/res/res/drawable/item_background_holo_dark.xml
@@ -14,8 +14,7 @@
limitations under the License.
-->
-<selector xmlns:android="http://schemas.android.com/apk/res/android"
- android:exitFadeDuration="@android:integer/config_mediumAnimTime">
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
<!-- Even though these two point to the same resource, have two states so the drawable will invalidate itself when coming out of pressed state. -->
<item android:state_focused="true" android:state_enabled="false" android:state_pressed="true" android:drawable="@drawable/list_selector_disabled_holo_dark" />
diff --git a/core/res/res/drawable/item_background_holo_light.xml b/core/res/res/drawable/item_background_holo_light.xml
index ee3f4d8..99b5ac2 100644
--- a/core/res/res/drawable/item_background_holo_light.xml
+++ b/core/res/res/drawable/item_background_holo_light.xml
@@ -14,8 +14,7 @@
limitations under the License.
-->
-<selector xmlns:android="http://schemas.android.com/apk/res/android"
- android:exitFadeDuration="@android:integer/config_mediumAnimTime">
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
<!-- Even though these two point to the same resource, have two states so the drawable will invalidate itself when coming out of pressed state. -->
<item android:state_focused="true" android:state_enabled="false" android:state_pressed="true" android:drawable="@drawable/list_selector_disabled_holo_light" />
diff --git a/core/res/res/drawable/list_selector_background.xml b/core/res/res/drawable/list_selector_background.xml
index 1222155..eaf86ca 100644
--- a/core/res/res/drawable/list_selector_background.xml
+++ b/core/res/res/drawable/list_selector_background.xml
@@ -14,8 +14,7 @@
limitations under the License.
-->
-<selector xmlns:android="http://schemas.android.com/apk/res/android"
- android:exitFadeDuration="@android:integer/config_mediumAnimTime">
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
<item android:state_window_focused="false" android:drawable="@color/transparent" />
diff --git a/core/res/res/drawable/list_selector_background_light.xml b/core/res/res/drawable/list_selector_background_light.xml
index 50a821b..4da7e21 100644
--- a/core/res/res/drawable/list_selector_background_light.xml
+++ b/core/res/res/drawable/list_selector_background_light.xml
@@ -14,8 +14,7 @@
limitations under the License.
-->
-<selector xmlns:android="http://schemas.android.com/apk/res/android"
- android:exitFadeDuration="@android:integer/config_mediumAnimTime">
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
<item android:state_window_focused="false" android:drawable="@color/transparent" />
diff --git a/core/res/res/drawable/list_selector_holo_dark.xml b/core/res/res/drawable/list_selector_holo_dark.xml
index 9a6cb89..e4c5c52 100644
--- a/core/res/res/drawable/list_selector_holo_dark.xml
+++ b/core/res/res/drawable/list_selector_holo_dark.xml
@@ -14,8 +14,7 @@
limitations under the License.
-->
-<selector xmlns:android="http://schemas.android.com/apk/res/android"
- android:exitFadeDuration="@android:integer/config_mediumAnimTime">
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
<item android:state_window_focused="false" android:drawable="@color/transparent" />
diff --git a/core/res/res/drawable/list_selector_holo_light.xml b/core/res/res/drawable/list_selector_holo_light.xml
index 844259e..17631bd 100644
--- a/core/res/res/drawable/list_selector_holo_light.xml
+++ b/core/res/res/drawable/list_selector_holo_light.xml
@@ -14,8 +14,7 @@
limitations under the License.
-->
-<selector xmlns:android="http://schemas.android.com/apk/res/android"
- android:exitFadeDuration="@android:integer/config_mediumAnimTime">
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
<item android:state_window_focused="false" android:drawable="@color/transparent" />
diff --git a/docs/html/guide/developing/device.jd b/docs/html/guide/developing/device.jd
index d22dca1..d91551a 100644
--- a/docs/html/guide/developing/device.jd
+++ b/docs/html/guide/developing/device.jd
@@ -134,11 +134,11 @@
</tr>
<tr>
<td>ASUS</td>
- <td><code>0B05</code></td>
+ <td><code>0b05</code></td>
</tr>
<tr>
<td>Dell</td>
- <td><code>413C</code></td>
+ <td><code>413c</code></td>
</tr>
<tr>
<td>Foxconn</td>
@@ -146,35 +146,35 @@
</tr>
<tr>
<td>Fujitsu</td>
- <td><code>04C5</code></td>
+ <td><code>04c5</code></td>
</tr>
<tr>
<td>Fujitsu Toshiba</td>
- <td><code>04C5</code></td>
+ <td><code>04c5</code></td>
</tr>
<tr>
<td>Garmin-Asus</td>
- <td><code>091E</code></td>
+ <td><code>091e</code></td>
</tr>
<tr>
<td>Google</td>
- <td><code>18D1</code></td>
+ <td><code>18d1</code></td>
</tr>
<tr>
<td>Hisense</td>
- <td><code>109B</code></td>
+ <td><code>109b</code></td>
</tr>
<tr>
<td>HTC</td>
- <td><code>0BB4</code></td>
+ <td><code>0bb4</code></td>
</tr>
<tr>
<td>Huawei</td>
- <td><code>12D1</code></td>
+ <td><code>12d1</code></td>
</tr>
<tr>
<td>K-Touch</td>
- <td><code>24E3</code></td>
+ <td><code>24e3</code></td>
</tr>
<tr>
<td>KT Tech</td>
@@ -185,8 +185,8 @@
<td><code>0482</code></td>
</tr>
<tr>
- <td>Lenevo</td>
- <td><code>17EF</code></td>
+ <td>Lenovo</td>
+ <td><code>17ef</code></td>
</tr>
<tr>
<td>LG</td>
@@ -194,7 +194,7 @@
</tr>
<tr>
<td>Motorola</td>
- <td><code>22B8</code></td>
+ <td><code>22b8</code></td>
</tr>
<tr>
<td>NEC</td>
@@ -214,11 +214,11 @@
</tr>
<tr>
<td>Pantech</td>
- <td><code>10A9</code></td>
+ <td><code>10a9</code></td>
</tr>
<tr>
<td>Pegatron</td>
- <td><code>1D4D</code></td>
+ <td><code>1d4d</code></td>
</tr>
<tr>
<td>Philips</td>
@@ -226,31 +226,31 @@
</tr>
<tr>
<td>PMC-Sierra</td>
- <td><code>04DA</code></td>
+ <td><code>04da</code></td>
</tr>
<tr>
<td>Qualcomm</td>
- <td><code>05C6</code></td>
+ <td><code>05c6</code></td>
</tr>
<tr>
<td>SK Telesys</td>
- <td><code>1F53</code></td>
+ <td><code>1f53</code></td>
</tr>
<tr>
<td>Samsung</td>
- <td><code>04E8</code></td>
+ <td><code>04e8</code></td>
</tr>
<tr>
<td>Sharp</td>
- <td><code>04DD</code></td>
+ <td><code>04dd</code></td>
</tr>
<tr>
<td>Sony</td>
- <td><code>054C</code></td>
+ <td><code>054c</code></td>
</tr>
<tr>
<td>Sony Ericsson</td>
- <td><code>0FCE</code></td>
+ <td><code>0fce</code></td>
</tr>
<tr>
<td>Teleepoch</td>
@@ -262,6 +262,6 @@
</tr>
<tr>
<td>ZTE</td>
- <td><code>19D2</code></td>
+ <td><code>19d2</code></td>
</tr>
</table>
diff --git a/docs/html/guide/developing/devices/emulator.jd b/docs/html/guide/developing/devices/emulator.jd
index c217790..5edd1f5 100644
--- a/docs/html/guide/developing/devices/emulator.jd
+++ b/docs/html/guide/developing/devices/emulator.jd
@@ -9,28 +9,58 @@
<h2>In this document</h2>
<ol>
<li><a href="#overview">Overview</a></li>
+ <li><a href="#avds">Android Virtual Devices and the Emulator</a></li>
<li><a href="#starting">Starting and Stopping the Emulator</a></li>
- <li><a href="#starting">Android Virtual Devices and the Emulator</a></li>
- <li><a href="#controlling">Controlling the Emulator</a></li>
- <li><a href="#startup-options">Emulator Startup Options</a></li>
+ <li><a href="#apps">Installing Applications on the Emulator</a></li>
+ <li><a href="#acceleration">Using Hardware Acceleration</a>
+ <ol>
+ <li><a href="#accel-graphics">Configuring Graphics Acceleration</a></li>
+ <li><a href="#accel-vm">Configuring Virtual Machine Acceleration</a></li>
+ </ol>
+ </li>
+ <li><a href="#sdcard">SD Card Emulation</a>
+ <ol>
+ <li><a href="#sdcard-creating">Creating an SD card image</a></li>
+ <li><a href="#sdcard-files">Copying files to an SD card image</a></li>
+ <li><a href="#sdcard-loading">Loading an SD card image</a></li>
+ </ol>
+ </li>
<li><a href="#diskimages">Working with Emulator Disk Images</a>
<ol>
- <li><a href="#defaultimages">Default Images</a></li>
- <li><a href="#runtimeimages">Runtime Images: User Data and SD Card</a></li>
- <li><a href="#temporaryimages">Temporary Images</a></li>
+ <li><a href="#defaultimages">Default image files</a></li>
+ <li><a href="#runtimeimages">Runtime images: user data and SD card</a></li>
+ <li><a href="#temporaryimages">Temporary images</a></li>
</ol>
</li>
<li><a href="#emulatornetworking">Emulator Networking</a>
<ol>
<li><a href="#networkaddresses">Network Address Space</a></li>
<li><a href="#networkinglimitations">Local Networking Limitations</a></li>
- <li><a href="#redirections">Using Network Redirections</a></li>
+ <li><a href="#redirection">Using Network Redirection</a></li>
<li><a href="#dns">Configuring the Emulator's DNS Settings</a></li>
<li><a href="#proxy">Using the Emulator with a Proxy</a></li>
<li><a href="#connecting">Interconnecting Emulator Instances</a></li>
<li><a href="#calling">Sending a Voice Call or SMS to Another Emulator Instance</a></li>
</ol>
</li>
+ <li><a href="#console">Using the Emulator Console</a>
+ <ol>
+ <li><a href="#portredirection">Port Redirection</a></li>
+ <li><a href="#geo">Geo Location Provider Emulation</a></li>
+ <li><a href="#events">Hardware Events Emulation</a></li>
+ <li><a href="#power">Device Power Characteristics</a></li>
+ <li><a href="#netstatus">Network Status</a></li>
+ <li><a href="#netdelay">Network Delay Emulation</a></li>
+ <li><a href="#netspeed">Network Speed Emulation</a></li>
+ <li><a href="#telephony">Telephony Emulation</a></li>
+ <li><a href="#sms">SMS Emulation</a></li>
+ <li><a href="#vm">VM State</a></li>
+ <li><a href="#window">Emulator Window</a></li>
+ <li><a href="#terminating">Terminating an Emulator Instance</a></li>
+ </ol>
+ </li>
+ <li><a href="#limitations">Emulator Limitations</a></li>
+ <li><a href="#troubleshooting">Troubleshooting Emulator Problems</a></li>
</ol>
<h2>See also</h2>
@@ -44,7 +74,7 @@
<img src="{@docRoot}images/emulator-wvga800l.png" alt="Image of the Android Emulator"
width="367" height="349" style="margin-left:2em;float:right;"/>
<p>The Android SDK includes a virtual mobile device emulator
-that runs on your computer. The emulator lets you prototype, develop, and test
+that runs on your computer. The emulator lets you prototype, develop and test
Android applications without using a physical device. </p>
<p>The Android emulator mimics all of the hardware and software features
@@ -52,7 +82,7 @@
calls. It provides a variety of navigation and control keys, which you can "press"
using your mouse or keyboard to generate events for your application. It also
provides a screen in which your application is displayed, together with any other
-Android applications running. </p>
+active Android applications. </p>
<p>To let you model and test your application more easily, the emulator utilizes
Android Virtual Device (AVD) configurations. AVDs let you define certain hardware
@@ -62,16 +92,16 @@
applications, access the network, play audio and video, store and retrieve data,
notify the user, and render graphical transitions and themes. </p>
-<p>The emulator also includes a variety of debug capabilities, such as a console
-from which you can log kernel output, simulate application interrupts (such as
-arriving SMS messages or phone calls), and simulate latency effects and dropouts
-on the data channel.</p>
+<p>The emulator also includes a variety of debug capabilities, such as a console
+from which you can log kernel output, simulate application interrupts (such as
+arriving SMS messages or phone calls), and simulate latency effects and dropouts
+on the data network.</p>
-<h2 id="overview">Overview</h2>
+<h2 id="overview">Overview</h2>
-<p>The Android emulator is a QEMU-based application that provides a virtual ARM
+<p>The Android emulator is an application that provides a virtual
mobile device on which you can run your Android applications. It runs a full
Android system stack, down to the kernel level, that includes a set of
preinstalled applications (such as the dialer) that you can access from your
@@ -81,16 +111,15 @@
you can use a variety of commands and options to control its behavior.
</p>
-<p>The Android system image distributed in the SDK contains ARM machine code for
-the Android Linux kernel, the native libraries, the Dalvik VM, and the various
-Android package files (such as for for the Android framework and preinstalled
-applications). The emulator's QEMU layers provide dynamic binary translation of
-the ARM machine code to the OS and processor architecture of your development
-machine. </p>
+<p>The Android system images available through the Android SDK Manager contain
+code for the Android Linux kernel, the native libraries, the Dalvik VM, and the
+various Android packages (such as the Android framework and preinstalled
+applications). The emulator provides dynamic binary translation of device
+machine code to the OS and processor architecture of your development
+machine.</p>
-<p>Adding custom capabilities to the underlying QEMU services, the Android
-emulator supports many hardware features likely to be found on mobile devices,
-including: </p>
+<p>The Android emulator supports many hardware features likely to be found on
+mobile devices, including: </p>
<ul>
<li>An ARMv5 CPU and the corresponding memory-management unit (MMU)</li>
@@ -101,41 +130,37 @@
<li>Flash memory partitions (emulated through disk image files on the
development machine)</li>
<li>A GSM modem, including a simulated SIM Card</li>
+ <li>A camera, using a webcam connected to your development computer.</li>
+ <li>Sensors like an accelerometer, using data from a USB-connected Android device.</li>
</ul>
-<p>The sections below provide more information about the emulator and how to use
-it for developing Android applications.</p>
+<p>The following sections describe the emulator and its use for development of Android
+applications in more detail.</p>
-<a name="avds"></a>
-
-<h2>Android Virtual Devices and the Emulator</h2>
+<h2 id="avds">Android Virtual Devices and the Emulator</h2>
<p>To use the emulator, you first must create one or more AVD configurations. In each
configuration, you specify an Android platform to run in the emulator and the set of hardware
options and emulator skin you want to use. Then, when you launch the emulator, you specify
the AVD configuration that you want to load. </p>
-<p>To specify the AVD you want to load when starting the emulator, you use the
-<code>-avd</code> argument, as shown in the previous section. </p>
-
<p>Each AVD functions as an independent device, with its own private storage for
user data, SD card, and so on. When you launch the emulator with an AVD configuration,
it automatically loads the user data and SD card data from the AVD directory. By default,
the emulator stores the user data, SD card data, and cache in the AVD directory.</p>
<p>To create and manage AVDs you use the AVD Manager UI or the <code>android</code> tool
-that is included in the SDK.
+that is included in the SDK.
For complete information about how to set up AVDs, see <a
href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a>.</p>
-<a name="starting"></a>
-<h2>Starting and Stopping the Emulator</h2>
+<h2 id="starting">Starting and Stopping the Emulator</h2>
<p>During development and testing of your application, you install and run your
application in the Android emulator. You can launch the emulator as a standalone
-application, from a command line, or you can use it as part of your Eclipse
+application from a command line, or you can run it from within your Eclipse
development environment. In either case, you specify the AVD configuration to
load and any startup options you want to use, as described in this document.
</p>
@@ -144,20 +169,24 @@
depending on your needs, you can start multiple emulator instances and run your
application in more than one emulated device. You can use the emulator's
built-in commands to simulate GSM phone calling or SMS between emulator
-instances, and you can set up network redirections that allow emulators to send
+instances, and you can set up network redirection that allows emulators to send
data to one another. For more information, see <a href="#telephony">Telephony
Emulation</a>, <a href="#sms">SMS Emulation</a>, and
<a href="#emulatornetworking">Emulator Networking</a></p>
-<p>To start an instance of the emulator from the command line, change to the
+<p>To start an instance of the emulator from the command line, navigate to the
<code>tools/</code> folder of the SDK. Enter <code>emulator</code> command
like this: </p>
-<pre>emulator -avd <avd_name></pre>
+<pre>emulator -avd <avd_name> [<options>]</pre>
-<p>This initializes the emulator and loads an AVD configuration (see the next
-section for more information about AVDs). You will see the emulator window
-appear on your screen. </p>
+<p>This initializes the emulator, loads an AVD configuration and displays the emulator
+window. For more information about command line options for the emulator, see the
+<a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> tool reference.</p>
+
+<p class="note"><strong>Note:</strong> You can run multiple
+instances of the emulator concurrently, each with its own AVD configuration and
+storage area for user data, SD card, and so on.</p>
<p>If you are working in Eclipse, the ADT plugin for Eclipse installs your
application and starts the emulator automatically, when you run or debug
@@ -171,585 +200,435 @@
<p>To stop an emulator instance, just close the emulator's window.</p>
<p>For a reference of the emulator's startup commands and keyboard mapping, see
-the <a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> document.</p>
+the <a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> tool
+reference.</p>
+<h2 id="apps">Installing Applications on the Emulator</h2>
+
+<p>If you don't have access to Eclipse or the ADT Plugin, you can install your application on the
+emulator using the <a href="{@docRoot}guide/developing/tools/adb.html#move">adb</a> utility. Before
+installing the application, you need to build and package it into an <code>.apk</code> as described
+in <a href="{@docRoot}guide/developing/building/index.html">Building and
+Running Apps</a>. Once the application is installed, you can start the emulator from the command
+line as described previously, using any startup options necessary.
+When the emulator is running, you can also connect to the emulator instance's
+<a href="#console">console</a> to issue commands as needed.</p>
+
+<p>As you update your code, you periodically package and install it on the emulator.
+The emulator preserves the application and its state data across restarts,
+in a user-data disk partition. To ensure that the application runs properly
+as you update it, you may need to delete the emulator's user-data partition.
+To do so, start the emulator with the <code>-wipe-data</code> option.
+For more information about the user-data partition and other emulator storage,
+see <a href="#diskimages">Working with Emulator Disk Images</a>.</p>
+<h2 id="acceleration">Using Hardware Acceleration</h2>
-<a name="controlling"></a>
+<p>In order to make the Android emulator run faster and be more responsive, you can configure it to
+take advantage of hardware acceleration, using a combination of configuration options, specific
+Android system images and hardware drivers.</p>
-<h2>Controlling the Emulator</h2>
+<h3 id="accel-graphics">Configuring Graphics Acceleration</h3>
-<p>You can use emulator <a href="#startup-options">startup options</a> and <a
-href="#console">console commands</a> to control the behaviors and
-characteristics of the emulated environment itself.
+<p class="caution"><strong>Caution:</strong> As of SDK Tools Revision 17, the graphics
+acceleration feature for the emulator is experimental; be alert for incompatibilities and
+errors when using this feature. </p>
+
+<p>Graphics acceleration for the emulator takes advantage of your development computer's graphics
+hardware, specifically its graphics processing unit (GPU), to make screen drawing faster. To use
+the graphics acceleration feature, you must have the following versions of the Android development
+tools installed:</p>
+
+<ul>
+ <li>Android SDK Tools, Revision 17 or higher</li>
+ <li>Android SDK Platform API 15, Revision 3 or higher</li>
+</ul>
+
+<p>Use the <a href="{@docRoot}sdk/installing.html#AddingComponents">Android SDK
+Manager</a> to install these components:</p>
+
+<p class="note"><strong>Note:</strong> Not all applications are compatible with graphics hardware
+acceleration. In particular, the Browser application and applications using the {@link
+android.webkit.WebView} component are not compatible with graphics acceleration.</p>
+
+<p>To configure an AVD to use graphics acceleration:</p>
+
+<ol>
+ <li>Make sure you have the required SDK components installed (listed above).</li>
+ <li>Start the AVD Manager and create a new AVD with the <strong>Target</strong> value of
+<strong>Android 4.0.3 (API Level 15)</strong>, revision 3 or higher.</li>
+ <li>If you want to have graphics acceleration enabled by default for this AVD, in the
+<strong>Hardware</strong> section, click <strong>New</strong>, select <strong>GPU emulation</strong>
+and set the value to <strong>Yes</strong>.
+ <p class="note"><strong>Note:</strong> You can also enable graphics acceleration when you
+start an emulator using command line options as describe in the next section.</p>
+ </li>
+ <li>Name the AVD instance and select any other configuration options.
+ <p class="caution"><strong>Caution:</strong> Do not select the <strong>Snapshot: Enabled</strong>
+option. Snapshots are not supported for emulators with graphics acceleration enabled.</p>
+ </li>
+ <li>Click <strong>Create AVD</strong> to save the emulator configuration.</li>
+</ol>
+
+<p>If you set <strong>GPU emulation</strong> to <strong>Yes</strong> for your AVD, then graphics
+acceleration is automatically enabled when you run it. If you did not enable <strong>GPU
+emulation</strong> when you created the AVD, you can still enable it at runtime.</p>
+
+<p>To enable graphics acceleration at runtime for an AVD:</p>
+
+<ul>
+ <li>If you are running the emulator from the command line, just include the {@code -gpu on}
+option:
+<pre>emulator -avd <avd_name> -gpu on</pre>
+ <p class="note"><strong>Note:</strong> You must specify an AVD configuration that uses
+Android 4.0.3 (API Level 15, revision 3) or higher system image target. Graphics acceleration is not
+available for earlier system images.</p>
+ </li>
+ <li>If you are running the emulator from Eclipse, run your Android application using an AVD with
+the {@code -gpu on} option enabled:
+ <ol>
+ <li>In Eclipse, click your Android project folder and then select <strong>Run > Run
+Configurations...</strong></li>
+ <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android
+project run configuration or create a new configuration.</li>
+ <li>Click the <strong>Target</strong> tab.</li>
+ <li>Select the AVD you created in the previous procedure.</li>
+ <li>In the <strong>Additional Emulator Command Line Options</strong> field, enter:<br>
+ {@code -gpu on}</li>
+ <li>Run your Android project using this run configuration.</li>
+ </ol>
+ </li>
+</ul>
+
+
+<h3 id="accel-vm">Configuring Virtual Machine Acceleration</h2>
+
+<p class="caution"><strong>Caution:</strong> As of SDK Tools Revision 17, the virtual machine
+acceleration feature for the emulator is experimental; be alert for incompatibilities and errors
+when using this feature.</p>
+
+<p>Many modern CPUs provide extensions for running virtual machines (VMs) more efficiently. Taking
+advantage of these extensions with the Android emulator requires some additional configuration of
+your development system, but can significantly improve the execution speed. Before attempting to use
+this type of acceleration, you should first determine if your development system’s CPU supports one
+of the following virtualization extensions technologies:</p>
+
+<ul>
+ <li>Intel Virtualization Technology (VT, VT-x, vmx) extensions</li>
+ <li>AMD Virtualization (AMD-V, SVM) extensions (only supported for Linux)</li>
+</ul>
+
+<p>The specifications from the manufacturer of your CPU should indicate if it supports
+virtualization extensions. If your CPU does not support one of these virtualization technologies,
+then you cannot use virtual machine acceleration.</p>
+
+<p class="note"><strong>Note:</strong> Virtualization extensions are typically enabled through
+your computer's BIOS and are frequently turned off by default. Check the documentation for your
+system's motherboard to find out how to enable virtualization extensions.</p>
+
+<p>Once you have determined that your CPU supports virtualization extensions, make sure you can work
+within these additional requirements of running an emulator inside an accelerated virtual
+machine:</p>
+
+<ul>
+ <li><strong>x86 AVD Only</strong> - You must use an AVD that is uses an x86 system image target.
+AVDs that use ARM-based system images cannot be accelerated using the emulator configurations
+described here.</li>
+ <li><strong>Not Inside a VM</strong> - You cannot run a VM-accelerated emulator inside another
+virtual machine, such as a VirtualBox or VMWare-hosted virtual machine. You must run the emulator
+directly on your system hardware.</li>
+ <li><strong>Other VM Drivers</strong> - If you are running another virtualization technology on
+your system such as VirtualBox or VMWare, you may need to unload the driver for that virtual machine
+hosting software before running an accelerated emulator.</li>
+ <li><strong>OpenGL® Graphics</strong> - Emulation of OpenGL ES graphics may not perform at the
+same level as an actual device.</li>
+</ul>
+
+<p>To use virtual machine acceleration with the emulator, you need the following version of Android
+development tools. Use the <a href="{@docRoot}sdk/installing.html#AddingComponents">Android SDK
+Manager</a> to install these components:</p>
+
+<ul>
+ <li>Android SDK Tools, Revision 17 or higher</li>
+ <li>Android x86-based system image</li>
+</ul>
+
+<p>If your development environment meets all of the requirements for running a VM-accelerated
+emulator, you can use the AVD Manager to create an x86-based AVD configuration:</p>
+
+<ol>
+ <li>In the Android SDK Manager, make sure you have an x86-based <strong>System Image</strong>
+ installed for your target Android version. If you do not have an x86 <strong>System
+ Image</strong> installed, select one in the Android SDK Manager and install it.
+ <p class="note"><strong>Tip:</strong> System images are listed under each API Level in the SDK
+ Manager. An x86 system image may not be available for all API levels.</p>
+ </li>
+ <li>Start the AVD Manager and create a new AVD with an x86 value for the
+<strong>CPU/ABI</strong> field. You may need to select a specific <strong>Target</strong> value, or
+select a <strong>Target</strong> value and then select a specific <strong>CPU/ABI</strong>
+option.</li>
+ <li>Name the emulator instance and select any other configuration options.</li>
+ <li>Click <strong>Create AVD</strong> to save the emulator configuration.</li>
+</ol>
+
+<h4 id="vm-windows">Configuring VM Acceleration on Windows</h4>
+
+<p>Virtual machine acceleration for Windows requires the installation of the Intel Hardware
+Accelerated Execution Manager (Intel HAXM). The software requires an Intel CPU with
+Virtualization Technology (VT) support and one of the following operating systems:</p>
+
+<ul>
+ <li>Windows 7 (32/64-bit)</li>
+ <li>Windows Vista (32/64-bit)</li>
+ <li>Windows XP (32-bit only)</li>
+</ul>
+
+<p>To install the virtualization driver:</p>
+
+<ol>
+ <li>Start the Android SDK Manager, select <strong>Extras</strong> and then select <strong>Intel
+Hardware Accelerated Execution Manager</strong>.</li>
+ <li>After the download completes, execute {@code
+<sdk>/extras/intel/Hardware_Accelerated_Execution_Manager/IntelHAXM.exe}.</li>
+ <li>Follow the on-screen instructions to complete installation.</li>
+ <li>After installation completes, confirm that the virtualization driver is operating correctly by
+opening a command prompt window and running the following command:
+ <pre>sc query intelhaxm</pre>
+ <p>You should see a status message including the following information:</p>
+<pre>
+SERVICE_NAME: intelhaxm
+ ...
+ STATE : 4 RUNNING
+ ...
+</pre>
+ </li>
+</ol>
+
+<p>To run an x86-based emulator with VM acceleration:</p>
+<ul>
+ <li>If you are running the emulator from the command line, just specify an x86-based AVD:
+<pre>emulator -avd <avd_name></pre>
+ <p class="note"><strong>Note:</strong> You must provide an x86-based AVD configuration
+name, otherwise VM acceleration will not be enabled.</p>
+ </li>
+ <li>If you are running the emulator from Eclipse, run your Android application with an x86-based
+AVD:
+ <ol>
+ <li>In Eclipse, click your Android project folder and then select <strong>Run > Run
+Configurations...</strong></li>
+ <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android
+project run configuration or create a new configuration.</li>
+ <li>Click the <strong>Target</strong> tab.</li>
+ <li>Select the x86-based AVD you created previously.</li>
+ <li>Run your Android project using this run configuration.</li>
+ </ol>
+ </li>
+</ul>
+
+<p>You can adjust the amount of memory available to the Intel HAXM kernel extension by re-running
+its installer.</p>
+
+<p>You can stop using the virtualization driver by uninstalling it. Re-run the installer or use
+the Control Panel to remove the software.</p>
+
+
+<h4 id="vm-mac">Configuring VM Acceleration on Mac</h4>
+
+<p>Virtual machine acceleration on a Mac requires the installation of the Intel Hardware Accelerated
+Execution Manager (Intel HAXM) kernel extension to allow the Android emulator to make use of CPU
+virtualization extensions. The kernel extension is compatible with Mac OS X Snow Leopard (version
+10.6.0) and higher.</p>
+
+<p>To install the Intel HAXM kernel extension:</p>
+
+<ol>
+ <li>Start the Android SDK Manager, select <strong>Extras</strong> and then select <strong>Intel
+Hardware Accelerated Execution Manager</strong>.
+ <li>After the download completes, execute
+ {@code <sdk>/extras/intel/Hardware_Accelerated_Execution_Manager/IntelHAXM.dmg}.</li>
+ <li>Double click the <strong>IntelHAXM.mpkg</strong> icon to begin installation.</li>
+ <li>Follow the on-screen instructions to complete installation.</li>
+ <li>After installation completes, confirm that the new kernel extension is operating correctly by
+opening a terminal window and running the following command:
+ <pre>kextstat | grep intel</pre>
+ <p>You should see a status message containing the following extension name, indicating that the
+ kernel extension is loaded:</p>
+ <pre>com.intel.kext.intelhaxm</pre>
+ </li>
+</ol>
+
+<p>To run an x86-based emulator with VM acceleration:</p>
+<ul>
+ <li>If you are running the emulator from the command line, just specify an x86-based AVD:
+<pre>emulator -avd <avd_name></pre>
+ <p class="note"><strong>Note:</strong> You must provide an x86-based AVD configuration
+name, otherwise VM acceleration will not be enabled.</p>
+ </li>
+ <li>If you are running the emulator from Eclipse, run your Android application with an x86-based
+AVD:
+ <ol>
+ <li>In Eclipse, click your Android project folder and then select <strong>Run > Run
+Configurations...</strong></li>
+ <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android
+project run configuration or create a new configuration.</li>
+ <li>Click the <strong>Target</strong> tab.</li>
+ <li>Select the x86-based AVD you created previously.</li>
+ <li>Run your Android project using this run configuration.</li>
+ </ol>
+ </li>
+</ul>
+
+<p>You can adjust the amount of memory available to the Intel HAXM kernel extension by re-running
+the installer.</p>
+
+<p>You can stop using the virtualization kernel driver by uninstalling it. Before removing it, shut
+down any running x86 emulators. To unload the virtualization kernel driver, run the following
+command in a terminal window:</p>
+
+<pre>sudo /System/Library/Extensions/intelhaxm.kext/Contents/Resources/uninstall.sh</pre>
+
+<h4 id="vm-linux">Configuring VM Acceleration on Linux</h4>
+
+<p>Linux-based systems support virtual machine acceleration through the KVM software package. Follow
+<a href="https://www.google.com/?q=kvm+installation">instructions for installing KVM</a> on your
+Linux system, and verify that KVM is enabled. In addition to following the installation
+instructions, be aware of these configuration requirements:</p>
+
+<ul>
+ <li>Running KVM requires specific user permissions, make sure you have sufficient permissions
+according to the KVM installation instructions.</li>
+ <li>If you use another virtualization technology in your Linux platform, unload its kernel driver
+before running the x86 emulator. For example, the VirtualBox driver program is {@code vboxdrv}.</li>
+</ul>
+
+<p>To run an x86-based emulator with VM acceleration:</p>
+
+<ul>
+ <li>If you are running the emulator from the command line, start the emulator with an x86-based
+AVD and include the KVM options:
+<pre>emulator -avd <avd_name> -qemu -m 512 -enable-kvm</pre>
+ <p class="note"><strong>Note:</strong> You must provide an x86-based AVD configuration
+name, otherwise VM acceleration will not be enabled.</p>
+ </li>
+ <li>If you are running the emulator from Eclipse, run your Android application with an x86-based
+AVD and include the KVM options:
+ <ol>
+ <li>In Eclipse, click your Android project folder and then select <strong>Run > Run
+Configurations...</strong></li>
+ <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android
+project run configuration or create a new configuration.</li>
+ <li>Click the <strong>Target</strong> tab.</li>
+ <li>Select the x86-based AVD you created previously.</li>
+ <li>In the <strong>Additional Emulator Command Line Options</strong> field, enter:
+ <pre>-qemu -m 512 -enable-kvm</pre>
+ </li>
+ <li>Run your Android project using this run configuration.</li>
+ </ol>
+ </li>
+</ul>
+
+<p class="note"><strong>Important:</strong> When using the {@code -qemu} command line option, make sure
+it is the last parameter in your command. All subsequent options are interpreted as qemu-specific
+parameters.</p>
+
+
+<h2 id="sdcard">SD Card Emulation</h2>
+
+<p>You can create a disk image and then load it to the emulator at startup, to
+simulate the presence of a user's SD card in the device. To do this, you can specify
+an SD card image when you create an AVD, or you can use the mksdcard utility included
+in the SDK.</p>
+
+<p>The following sections describe how to create an SD card disk image, how to copy
+files to it, and how to load it in the emulator at startup. </p>
+
+<p>Note that you can only load a disk image at emulator startup. Similarly, you
+can not remove a simulated SD card from a running emulator. However, you can
+browse, send files to, and copy/remove files from a simulated SD card either
+with adb or the emulator. </p>
+
+<p>The emulator supports emulated SDHC cards, so you can create an SD card image
+of any size up to 128 gigabytes.</p>
+
+
+<h3 id="sdcard-creating">Creating an SD card image</h3>
+
+<p>There are several ways of creating an SD card image. The easiest way is to use the
+<strong>AVD Manager</strong> to create a new SD card by specifying a size when you create an AVD.
+You can also use the {@code android} command line tool when creating an AVD. Just add the
+<code>-c</code> option to your command: </p>
+
+<pre>android create avd -n <avd_name> -t <targetID> -c <size>[K|M]</pre>
+
+<p>The <code>-c</code> option can also be used to to specify a path to an SD card
+image for the new AVD. For more information, see <a
+href="{@docRoot}guide/developing/devices/managing-avds-cmdline.html">Managing Virtual Devices
+from the Command Line</a>.
</p>
-<p>When the emulator is running, you can interact with the emulated mobile
-device just as you would an actual mobile device, except that you use your mouse
-pointer to "touch" the touchscreen and your keyboard keys to
-"press" the simulated device keys. </p>
+<p>You can also use the mksdcard tool, included in the SDK, to create a FAT32 disk
+image that you can load in the emulator at startup. You can access mksdcard in
+the tools/ directory of the SDK and create a disk image like this: </p>
-<p>The table below summarizes the mappings between the emulator keys and and
-the keys of your keyboard. </p>
+<pre>mksdcard <size> <file></pre>
-<table border="0" style="clear:left;">
- <tr>
- <th>Emulated Device Key </th>
- <th>Keyboard Key </th>
- </tr>
- <tr>
- <td>Home</td>
- <td>HOME</td>
- </tr>
- <tr>
- <td>Menu (left softkey)</td>
- <td>F2 <em>or</em> Page-up button</td>
- </tr>
- <tr>
- <td>Star (right softkey)</td>
- <td>Shift-F2 <em>or </em>Page Down</td>
- </tr>
- <tr>
- <td>Back</td>
- <td>ESC</td>
- </tr>
- <tr>
- <td>Call/dial button </td>
- <td>F3</td>
- </tr>
- <tr>
- <td>Hangup/end call button</td>
- <td>F4</td>
- </tr>
- <tr>
- <td>Search</td>
- <td>F5 </td>
- </tr>
- <tr>
- <td>Power button</td>
- <td>F7 </td>
- </tr>
- <tr>
- <td>Audio volume up button</td>
- <td>KEYPAD_PLUS, Ctrl-5</td>
- </tr>
+<p>For example:</p>
- <tr>
- <td>Audio volume down button</td>
- <td>KEYPAD_MINUS, Ctrl-F6</td>
- </tr>
- <tr>
- <td>Camera button</td>
- <td>Ctrl-KEYPAD_5, Ctrl-F3</td>
- </tr>
- <tr>
- <td>Switch to previous layout orientation (for example, portrait, landscape)</td>
- <td>KEYPAD_7, Ctrl-F11</td>
- </tr>
- <tr>
- <td>Switch to next layout orientation (for example, portrait, landscape)</td>
- <td>KEYPAD_9, Ctrl-F12</td>
- </tr>
- <tr>
- <td>Toggle cell networking on/off</td>
- <td>F8</td>
- </tr>
- <tr>
- <td>Toggle code profiling</td>
- <td>F9 (only with <code>-trace</code> startup option)</td>
- </tr>
- <tr>
- <td>Toggle fullscreen mode</td>
- <td>Alt-Enter</td>
- </tr>
- <tr>
- <td>Toggle trackball mode</td>
- <td>F6</td>
- </tr>
- <tr>
- <td>Enter trackball mode temporarily (while key is pressed)</td>
- <td>Delete</td>
- </tr>
- <tr>
- <td>DPad left/up/right/down</td>
- <td>KEYPAD_4/8/6/2</td>
- </tr>
- <tr>
- <td>DPad center click</td>
- <td>KEYPAD_5</td>
- </tr>
- <tr>
- <td>Onion alpha increase/decrease</td>
- <td>KEYPAD_MULTIPLY(*) / KEYPAD_DIVIDE(/)</td>
- </tr>
-</table>
+<pre>mksdcard 1024M sdcard1.iso</pre>
-<p>Note that, to use keypad keys, you must first disable NumLock on your development computer. </p>
-
-<h2 id="emulator">Emulator Startup Options</h2>
-
-<p>The emulator supports a variety of options that you can specify
-when launching the emulator, to control its appearance or behavior.
-Here's the command-line usage for launching the emulator with options: </p>
-
-<pre>emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]</pre>
-
-<p>The table below summarizes the available options.</p>
-
-<table>
-<tr>
- <th width="10%" >Category</th>
- <th width="20%" >Option</th>
- <th width="30%" >Description</th>
- <th width="40%" >Comments</th>
-</tr>
-
-<tr>
- <td rowspan="9">Help</td>
- <td><code>-help</code></td>
- <td>Print a list of all emulator options.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-help-all</code></td>
- <td>Print help for all startup options.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-help-<option></code></td>
- <td>Print help for a specific startup option.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-help-debug-tags</code></td>
- <td>Print a list of all tags for <code>-debug <tags></code>.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-help-disk-images</code></td>
- <td>Print help for using emulator disk images.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-help-environment</code></td>
- <td>Print help for emulator environment variables.</td>
- <td> </td>
-</tr><tr>
- <td><code>-help-keys</code></td>
- <td>Print the current mapping of keys.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-help-keyset-file</code></td>
- <td>Print help for defining a custom key mappings file.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-help-virtual-device</code></td>
- <td>Print help for Android Virtual Device usage.</td>
- <td> </td>
-</tr>
-<tr>
- <td>AVD</td>
- <td><code>-avd <avd_name></code> or <br>
- <code>@<avd_name></code></td>
- <td><strong>Required</strong>. Specifies the AVD to load for this emulator
- instance.</td>
- <td>You must create an AVD configuration before launching the emulator. For
- information, see <a href="{@docRoot}guide/developing/devices/managing-avds.html">Managing
- Virtual Devices with AVD Manager</a>.</td>
-<tr>
- <td rowspan="7">Disk Images</td>
- <td><code>-cache <filepath></code></td>
- <td>Use <filepath> as the working cache partition image. </td>
- <td>Optionally, you can specify a path relative to the current working directory.
- If no cache file is specified, the emulator's default behavior is to use a temporary file instead.
- <p>For more information on disk images, use <code>-help-disk-images</code>.</p>
-</td></tr>
-<tr>
- <td><code>-data <filepath></code></td>
- <td>Use <filepath> as the working user-data disk image. </td>
- <td>Optionally, you can specify a path relative to the current working directory.
- If <code>-data</code> is not used, the emulator looks for a file named "userdata-qemu.img"
- in the storage area of the AVD being used (see <code>-avd</code>).
-</td></tr>
-<!--
-<tr>
- <td><code>-datadir <dir></code></td>
- <td>Search for the user-data disk image specified in <code>-data</code> in <dir></td>
- <td><code><dir></code> is a path relative to the current working directory.
-
-<p>If you do not specify <code>-datadir</code>, the emulator looks for the user-data image
-in the storage area of the AVD being used (see <code>-avd</code>)</p><p>For more information
-on disk images, use <code>-help-disk-images</code>.</p>
-</td></tr>
--->
-<!--
-<tr>
- <td><code>-image <filepath></code></td>
- <td>Use <filepath> as the system image.</td>
- <td>Optionally, you can specify a path relative to the current working directory.
- Default is <system>/system.img.</td>
-</tr>
--->
-<tr>
- <td><code>-initdata <filepath></code></td>
- <td>When resetting the user-data image (through <code>-wipe-data</code>), copy the contents
- of this file to the new user-data disk image. By default, the emulator copies the <code><system>/userdata.img</code>.</td>
- <td>Optionally, you can specify a path relative to the current working directory. See also <code>-wipe-data</code>.
- <p>For more information on disk images, use <code>-help-disk-images</code>.</p></td>
-</tr>
-<!--
-<tr>
- <td><code>-kernel <filepath></code></td>
- <td>Use <filepath> as the emulated kernel.</td>
- <td>Optionally, you can specify a path relative to the current working directory. </td>
-</tr>
--->
-<tr>
- <td><code>-nocache</code></td>
- <td>Start the emulator without a cache partition.</td>
- <td>See also <code>-cache <file></code>.</td>
-</tr>
-<tr>
- <td><code>-ramdisk <filepath></code></td>
- <td>Use <filepath> as the ramdisk image.</td>
- <td>Default value is <code><system>/ramdisk.img</code>.
- <p>Optionally, you can specify a path relative to the current working directory.
- For more information on disk images, use <code>-help-disk-images</code>.</p>
-</td>
-</tr>
-<tr>
- <td><code>-sdcard <filepath></code></td>
- <td>Use <file> as the SD card image.</td>
- <td>Default value is <code><system>/sdcard.img</code>.
- <p>Optionally, you can specify a path relative to the current working directory. For more information on disk images, use <code>-help-disk-images</code>.</p>
-</td>
-</tr>
-<!--
-<tr>
- <td><code>-system <dirpath></code></td>
- <td>Search for system, ramdisk and user data images in <dir>.</td>
- <td><code><dir></code> is a directory path relative to the current
- working directory.</td>
-</tr>
--->
-<tr>
- <td><code>-wipe-data</code></td>
- <td>Reset the current user-data disk image (that is, the file specified by <code>-datadir</code> and
- <code>-data</code>, or the default file). The emulator deletes all data from the user data image file,
- then copies the contents of the file at <code>-inidata</code> data to the image file before starting.
- </td>
- <td>See also <code>-initdata</code>.
- <p>For more information on disk images, use <code>-help-disk-images</code>.</p>
-</td>
-</tr>
-<tr>
- <td rowspan="9">Debug</td>
- <td><code>-debug <tags></code></td>
- <td>Enable/disable debug messages for the specified debug tags.</td>
- <td><code><tags></code> is a space/comma/column-separated list of debug component names.
- Use <code>-help-debug-tags</code> to print a list of debug component names that you can use. </td>
-</tr>
-<tr>
- <td><code>-debug-<tag></code></td>
- <td>Enable/disable debug messages for the specified debug tag.</td>
- <td rowspan="2">Use <code>-help-debug-tags</code> to print a list of debug component names that you can use in <code><tag></code>. </td>
-</tr>
-<tr>
- <td><code>-debug-no-<tag></code></td>
- <td>Disable debug messages for the specified debug tag.</td>
-</tr>
-<tr>
- <td><code>-logcat <logtags></code></td>
- <td>Enable logcat output with given tags.</td>
- <td>If the environment variable ANDROID_LOG_TAGS is defined and not
- empty, its value will be used to enable logcat output by default.</td>
-</tr>
-<tr>
- <td><code>-shell</code></td>
- <td>Create a root shell console on the current terminal.</td>
- <td>You can use this command even if the adb daemon in the emulated system is broken.
- Pressing Ctrl-c from the shell stops the emulator instead of the shell.</td>
-</tr>
-<tr>
- <td><code>-shell-serial <device></code></td>
- <td>Enable the root shell (as in <code>-shell</code> and specify the QEMU character
- device to use for communication with the shell.</td>
- <td><device> must be a QEMU device type. See the documentation for '-serial <em>dev</em>' at
- <a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>
- for a list of device types.
-
-<p>Here are some examples: </p>
-<ul>
- <li><code>-shell-serial stdio</code> is identical to <code>-shell</code></li>
- <li><code>-shell-serial tcp::4444,server,nowait</code> lets you communicate with the shell over TCP port 4444</li>
- <li><code>-shell-serial fdpair:3:6</code> lets a parent process communicate with the shell using fds 3 (in) and 6 (out)</li>
- <li><code>-shell-serial fdpair:0:1</code> uses the normal stdin and stdout fds, except that QEMU won't tty-cook the data.</li>
- </ul>
-</td>
-</tr>
-<tr>
- <td><code>-show-kernel <name></code></td>
- <td>Display kernel messages.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-trace <name></code></td>
- <td>Enable code profiling (press F9 to start), written to a specified file.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-verbose</code></td>
- <td>Enable verbose output.</td>
- <td>Equivalent to <code>-debug-init</code>.
-<p>You can define the default verbose output options used by emulator instances in the Android environment variable
-ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, specifying only the stem of each option:
-<code>-debug-<tags>.</code> </p>
-<p>Here's an example showing ANDROID_VERBOSE defined with the <code>-debug-init</code> and <code>-debug-modem</code> options:
-<p><code>ANDROID_VERBOSE=init,modem</code></p>
-<p>For more information about debug tags, use <code><-help-debug-tags></code>.</p>
-</td>
-</tr>
-<tr>
- <td rowspan="6">Media</td>
- <td><code>-audio <backend></code></td>
- <td>Use the specified audio backend.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-audio-in <backend></code></td>
- <td>Use the specified audio-input backend.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-audio-out <backend></code></td>
- <td>Use the specified audio-output backend.</td>
- <td> </td>
-</tr>
-<!--<tr>
- <td><code>-mic <device or file></code></td>
- <td>Use device or WAV file for audio input.</td>
- <td> </td>
-</tr>
--->
-<tr>
- <td><code>-noaudio</code></td>
- <td>Disable audio support in the current emulator instance.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-radio <device></code></td>
- <td>Redirect radio modem interface to a host character device.</td>
- <td> </td></tr>
-<tr>
- <td><code>-useaudio</code></td>
- <td>Enable audio support in the current emulator instance.</td>
- <td>Enabled by default. </td>
-</tr>
-
-<tr>
- <td rowspan="7">Network</td>
- <td><code>-dns-server <servers></code></td>
- <td>Use the specified DNS server(s). </td>
- <td>The value of <code><servers></code> must be a comma-separated list of up to 4 DNS server names or
- IP addresses.</td>
-</tr>
-<tr>
- <td><code>-http-proxy <proxy></code></td>
- <td>Make all TCP connections through a specified HTTP/HTTPS proxy</td>
- <td>The value of <code><proxy></code> can be one of the following:<br>
- <code>http://<server>:<port></code><br>
- <code>http://<username>:<password>@<server>:<port></code>
- <p>The <code>http://</code> prefix can be omitted. If the <code>-http-proxy <proxy></code> command is not supplied,
- the emulator looks up the <code>http_proxy</code> environment variable and automatically uses any value matching
- the <code><proxy></code> format described above.</p></td>
-</tr>
-<tr>
- <td><code>-netdelay <delay></code></td>
- <td>Set network latency emulation to <delay>.</td>
- <td>Default value is <code>none</code>. See the table in <a href="#netdelay">Network Delay Emulation</a> for
- supported <code><delay></code> values. </td>
-</tr>
-<tr>
- <td><code>-netfast</code></td>
- <td>Shortcut for <code>-netspeed full -netdelay none</code></td>
- <td> </td></tr>
-<tr>
- <td><code>-netspeed <speed></code></td>
- <td>Set network speed emulation to <speed>.</td>
- <td>Default value is <code>full</code>. See the table in <a href="#netspeed">Network Speed Emulation</a> for
- supported <code><speed></code> values. </td>
-</tr>
-<tr>
- <td><code>-port <port></code></td>
- <td>Set the console port number for this emulator instance to <code><port></code>.</td>
- <td>The console port number must be an even integer between 5554 and 5584, inclusive. <code><port></code>+1
- must also be free and will be reserved for ADB.</td>
-</tr>
-<tr>
- <td><code>-report-console <socket></code></td>
- <td>Report the assigned console port for this emulator instance to a remote third party
- before starting the emulation. </td>
- <td><code><socket></code> must use one of these formats:
-
-<p><code>tcp:<port>[,server][,max=<seconds>]</code></br>
-<code>unix:<port>[,server][,max=<seconds>]</code></p>
-
-<p>Use <code>-help-report-console</code></p> to view more information about this topic. </td>
-</tr>
-<tr>
- <td rowspan="8">System</td>
- <td><code>-cpu-delay <delay></code></td>
- <td>Slow down emulated CPU speed by <delay> </td>
- <td>Supported values for <delay> are integers between 0 and 1000.
-
-<p>Note that the <delay> does not correlate to clock speed or other absolute metrics
-— it simply represents an abstract, relative delay factor applied non-deterministically
-in the emulator. Effective performance does not always
-scale in direct relationship with <delay> values.</p>
-</td>
-</tr>
-<tr>
- <td><code>-gps <device></code></td>
- <td>Redirect NMEA GPS to character device.</td>
- <td>Use this command to emulate an NMEA-compatible GPS unit connected to
- an external character device or socket. The format of <code><device></code> must be QEMU-specific
- serial device specification. See the documentation for 'serial -dev' at
- <a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>.
-</td>
-</tr>
-<tr>
- <td><code>-nojni</code></td>
- <td>Disable JNI checks in the Dalvik runtime.</td><td> </td></tr>
-<tr>
- <td><code>-qemu</code></td>
- <td>Pass arguments to qemu.</td>
- <td> </td></tr>
-<tr>
- <td><code>-qemu -h</code></td>
- <td>Display qemu help.</td>
- <td></td></tr>
-<tr>
- <td><code>-radio <device></code></td>
- <td>Redirect radio mode to the specified character device.</td>
- <td>The format of <code><device></code> must be QEMU-specific
- serial device specification. See the documentation for 'serial -dev' at
-<a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>.
-</td>
-</tr>
-<tr>
- <td><code>-timezone <timezone></code></td>
- <td>Set the timezone for the emulated device to <timezone>, instead of the host's timezone.</td>
- <td><code><timezone></code> must be specified in zoneinfo format. For example:
-<p>"America/Los_Angeles"<br>
-"Europe/Paris"</p>
-</td>
-</tr>
-<tr>
- <td><code>-version</code></td>
- <td>Display the emulator's version number.</td>
- <td> </td>
-</tr>
-<tr>
- <td rowspan="12">UI</td>
- <td><code>-dpi-device <dpi></code></td>
- <td>Scale the resolution of the emulator to match the screen size
- of a physical device.</td>
- <td>The default value is 165. See also <code>-scale</code>.</td>
-</tr>
-<tr>
- <td><code>-no-boot-anim</code></td>
- <td>Disable the boot animation during emulator startup.</td>
- <td>Disabling the boot animation can speed the startup time for the emulator.</td>
-</tr>
-<tr>
- <td><code>-no-window</code></td>
- <td>Disable the emulator's graphical window display.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-scale <scale></code></td>
- <td>Scale the emulator window. </td>
- <td><code><scale></code> is a number between 0.1 and 3 that represents the desired scaling factor. You can
- also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto"
- tells the emulator to select the best window size.</td>
-</tr>
-<tr>
- <td><code>-raw-keys</code></td>
- <td>Disable Unicode keyboard reverse-mapping.</td>
- <td> </td></tr>
-<tr>
- <td><code>-noskin</code></td>
- <td>Don't use any emulator skin.</td>
- <td> </td></tr>
-<tr>
- <td><code>-keyset <file></code></td>
- <td>Use the specified keyset file instead of the default.</td>
- <td>The keyset file defines the list of key bindings between the emulator and the host keyboard.
- For more information, use <code>-help-keyset</code> to print information about this topic.
-</td>
-</tr>
-<tr>
- <td><code>-onion <image></code></td>
- <td>Use overlay image over screen.</td>
- <td>No support for JPEG. Only PNG is supported.</td></tr>
-<tr>
- <td><code>-onion-alpha <percent></code></td>
- <td>Specify onion skin translucency value (as percent).
- <td>Default is 50.</td>
-</tr>
-<tr>
- <td><code>-onion-rotation <position></code></td>
- <td>Specify onion skin rotation.
- <td><code><position></code> must be one of the values 0, 1, 2, 3.</td>
-</tr>
-<tr>
- <td><code>-skin <skinID></code></td>
- <td>This emulator option is deprecated. </td>
- <td>Please set skin options using AVDs, rather than by using this emulator
-option. Using this option may yield unexpected and in some cases misleading
-results, since the density with which to render the skin may not be defined.
-AVDs let you associate each skin with a default density and override the default
-as needed. For more information, see <a
-href="{@docRoot}guide/developing/devices/managing-avds.html">Managing Virtual Devices
-with AVD Manager</a>.
-</td>
-</tr>
-<tr>
- <td><code>-skindir <dir></code></td>
- <td>This emulator option is deprecated. </td>
- <td>See comments for <code>-skin</code>, above.</td></tr>
-</table>
+<p>For more information, see <a
+href="{@docRoot}guide/developing/tools/mksdcard.html"><code>mksdcard</code></a>.</p>
-<a name="diskimages"></a>
+<h3 id="sdcard-files">Copying files to an SD card image</h3>
-<h2>Working with Emulator Disk Images</h2>
+<p>Once you have created the disk image, you can copy files to it prior to
+loading it in the emulator. To copy files, you can mount the image as a loop
+device and then copy the files to it, or you can use a utility such as {@code mtools} to
+copy the files directly to the image. The {@code mtools} package is available for Linux,
+Mac, and Windows.</p>
+
+<p>Alternatively, you can use the {@code adb push} command to move files onto an SD card image
+while it is loaded in an emulator. For more information see the <a
+href="{@docRoot}guide/developing/tools/adb.html#copyfiles">{@code adb push}</a> documentation.</p>
+
+<h3 id="sdcard-loading">Loading an SD card image</h3>
+
+<p>By default, the emulator loads the SD card image that is stored with the active
+AVD (see the <code>-avd</code> startup option).</p>
+
+<p>Alternatively, you can start the emulator with the
+<code>-sdcard</code> flag and specify the name and path of your image (relative
+to the current working directory): </p>
+
+<pre>emulator -sdcard <filepath></pre>
+
+
+<h2 id="diskimages">Working with Emulator Disk Images</h2>
<p>The emulator uses mountable disk images stored on your development machine to
-simulate flash (or similar) partitions on an actual device. For example, it uses
+simulate flash (or similar) partitions on an actual device. For example, it uses a
disk image containing an emulator-specific kernel, the Android system, a
ramdisk image, and writeable images for user data and simulated SD card.</p>
<p>To run properly, the emulator requires access to a specific set of disk image
-files. By default, the Emulator always looks for the disk images in the
-private storage area of the AVD in use. If no images exist there when
-the Emulator is launched, it creates the images in the AVD directory based on
+files. By default, the Emulator always looks for the disk images in the
+private storage area of the AVD in use. If no images exist there when
+the Emulator is launched, it creates the images in the AVD directory based on
default versions stored in the SDK. </p>
-<p class="note"><strong>Note:</strong> The default storage location for
-AVDs is in <code>~/.android/avd</code> on OS X and Linux, <code>C:\Documents and
-Settings\<user>\.android\</code> on Windows XP, and
+<p class="note"><strong>Note:</strong> The default storage location for
+AVDs is in <code>~/.android/avd</code> on OS X and Linux, <code>C:\Documents and
+Settings\<user>\.android\</code> on Windows XP, and
<code>C:\Users\<user>\.android\</code>
on Windows Vista.</p>
<p>To let you use alternate or custom versions of the image files, the emulator
provides startup options that override the default locations and filenames of
-the image files. When you use the options, the emulator searches for the image
+the image files. When you use one of these options, the emulator searches for the image
file under the image name or location that you specify; if it can not locate the
image, it reverts to using the default names and location.</p>
@@ -757,20 +636,19 @@
image files, and temporary image files. The sections below describe how to
override the location/name of each type of file. </p>
-<a name="defaultimages"></a>
-<h3>Default Images</h3>
+<h3 id="defaultimages">Default image files</h3>
-<p>When the emulator launches but does not find an existing user data image in
+<p>When the emulator launches, but does not find an existing user data image in
the active AVD's storage area, it creates a new one from a default version
-included in the SDK. The default user data image is read-only. The image
+included in the SDK. The default user data image is read-only. The image
files are read-only.</p>
<p>The emulator provides the <code>-system <dir></code> startup option to
-let you override the location under which the emulator looks for the default
+let you override the location where the emulator looks for the default
user data image. </p>
<p>The emulator also provides a startup option that lets you override the name
-of the default user data image, as described in the table below. When you use the
+of the default user data image, as described in the following table. When you use the
option, the emulator looks in the default directory, or in a custom location
(if you specified <code>-system <dir></code>). </p>
@@ -810,25 +688,24 @@
</table>
-<a name="runtimeimages"></a>
-<h3>Runtime Images: User Data and SD Card</h3>
+<h3 id="runtimeimages">Runtime images: user data and SD card</h3>
-<p>At runtime, the emulator reads and writes data on two disk images: a
-user-data image and (optionally) an SD card image. This emulates the user-data
+<p>At runtime, the emulator reads and writes data to two disk images: a
+user-data image and (optionally) an SD card image. These images emulate the user-data
partition and removable storage media on actual device. </p>
-<p>The emulator provides a default user-data disk image. At startup, the emulator
-creates the default image as a copy of the system user-data image (user-data.img),
+<p>The emulator provides a default user-data disk image. At startup, the emulator
+creates the default image as a copy of the system user-data image (user-data.img),
described above. The emulator stores the new image with the files of the active AVD.</p>
<!--
-<p>The emulator provides a startup option, <code>-datadir <dir></code>,
+<p>The emulator provides a startup option, <code>-datadir <dir></code>,
that you can use to override the location under which the emulator looks for the runtime
image files. </p>
-->
-<p>The emulator provides startup options to let you override the actual names and storage
-locations of the runtime images to load, as described in the table below. When you use one
+<p>The emulator provides startup options to let you override the actual names and storage
+locations of the runtime images to load, as described in the following table. When you use one
of these options, the emulator looks for the specified file(s) in the current working directory,
in the AVD directory, or in a custom location (if you specified a path with the filename). </p>
@@ -842,7 +719,7 @@
<td><code>userdata-qemu.img</code></td>
<td>An image to which the emulator writes runtime user-data for a unique user.</td>
<td>Override using <code>-data <filepath></code>, where <code><filepath></code> is the
-path the image, relative to the current working directory. If you supply a filename only,
+path the image, relative to the current working directory. If you supply a filename only,
the emulator looks for the file in the current working directory. If the file at <code><filepath></code> does
not exist, the emulator creates an image from the default userdata.img, stores it under the name you
specified, and persists user data to it at shutdown. </td>
@@ -852,7 +729,7 @@
<td><code>sdcard.img</code></td>
<td>An image representing an SD card inserted into the emulated device.</td>
<td>Override using <code>-sdcard <filepath></code>, where <code><filepath></code> is the
-path the image, relative to the current working directory. If you supply a filename only,
+path the image, relative to the current working directory. If you supply a filename only,
the emulator looks for the file in the current working directory. </td>
</tr>
@@ -864,38 +741,38 @@
session-specific data. For example, it uses the image to store a unique user's
installed application data, settings, databases, and files. </p>
-<p>At startup, the emulator attempts to load a user-data image stored during
-a previous session. It looks for the file in the current working directory,
-in the AVD directory as described above, and at the custom location/name
+<p>At startup, the emulator attempts to load a user-data image stored during
+a previous session. It looks for the file in the current working directory,
+in the AVD directory described in a previous section and at the custom location/name
that you specified at startup. </p>
<ul>
-<li>If it finds a user-data image, it mounts the image and makes it available
-to the system for reading/writing of user data. </li>
+<li>If it finds a user-data image, it mounts the image and makes it available
+to the system for reading and writing of user data. </li>
<li>If it does not find one, it creates an image by copying the system user-data
image (userdata.img), described above. At device power-off, the system persists
-the user data to the image, so that it will be available in the next session.
+the user data to the image, so that it will be available in the next session.
Note that the emulator stores the new disk image at the location/name that you
specify in <code>-data</code> startup option.</li>
</ul>
<p class="note"><strong>Note:</strong> Because of the AVD configurations used in the emulator,
-each emulator instance now gets its own dedicated storage. There is no need
+each emulator instance gets its own dedicated storage. There is no longer a need
to use the <code>-d</code> option to specify an instance-specific storage area.</p>
<h4>SD Card</h4>
<P>Optionally, you can create a writeable disk image that the emulator can use
-to simulate removeable storage in an actual device. For information about how to create an
+to simulate removeable storage in an actual device. For information about how to create an
emulated SD card and load it in the emulator, see <a href="#sdcard">SD Card Emulation</a></p>
<p>You can also use the android tool to automatically create an SD Card image
-for you, when creating an AVD. For more information, see <a
+for you, when creating an AVD. For more information, see <a
href="{@docRoot}guide/developing/devices/managing-avds.html">Managing Virtual Devices with AVD
Manager</a>.
-<a name="temporaryimages"></a>
-<h3>Temporary Images</h3>
+
+<h3 id="temporaryimages">Temporary Images</h3>
<p>The emulator creates two writeable images at startup that it deletes at
device power-off. The images are: </p>
@@ -909,8 +786,8 @@
persisting it at device power-off. </p>
<p>The <code>/cache</code> partition image is initially empty, and is used by
-the browser to cache downloaded web pages and images. The emulator provides an
-<code>-cache <file></code>, which specifies the name of the file at which
+the browser to cache downloaded web pages and images. The emulator provides an
+<code>-cache <file></code>, which specifies the name of the file in which
to persist the <code>/cache</code> image at device power-off. If <code><file>
</code> does not exist, the emulator creates it as an empty file. </p>
@@ -918,16 +795,14 @@
<code>-nocache</code> option at startup. </p>
-<a name="emulatornetworking"></a>
-<h2>Emulator Networking</h2>
+<h2 id="emulatornetworking">Emulator Networking</h2>
<p>The emulator provides versatile networking capabilities that you can use to
set up complex modeling and testing environments for your application. The
sections below introduce the emulator's network architecture and capabilities.
</p>
-<a name="networkaddresses"></a>
-<h3>Network Address Space</h3>
+<h3 id="networkaddresses">Network Address Space</h3>
<p>Each instance of the emulator runs behind a virtual router/firewall service
that isolates it from your development machine's network interfaces and settings
@@ -990,14 +865,13 @@
devices (which are also very likely to be NAT-ed, i.e., behind a
router/firewall)</p>
-<a name="networkinglimitations"></a>
-<h3>Local Networking Limitations</h3>
-<p>Each emulator instance runs behind a virtual router, but unlike an actual
-device connected to a physical router, the emulated device doesn't have access
-to a physical network. Instead it runs as part of a normal application on your
-development machine. This means that it is subject to the same networking
-limitations as other applications on your machine:</p>
+<h3 id="networkinglimitations">Local Networking Limitations</h3>
+
+<p>Android applications running in an emulator can connect to the network available on your
+workstation. However, they connect through the emulator, not directly to hardware, and the emulator
+acts like a normal application on your workstation. This means that the emulator, and thus your
+Android applications, are subject to some limitations:</p>
<ul>
<li>Communication with the emulated device may be blocked by a firewall
@@ -1016,25 +890,24 @@
protocols (such as ICMP, used for "ping") might not be supported. Currently, the
emulator does not support IGMP or multicast. </p>
-<a name="redirections"></a>
-<h3>Using Network Redirections</h3>
+<h3 id="redirection">Using Network Redirection</h3>
<p>To communicate with an emulator instance behind its virtual router, you need
-to set up network redirections on the virtual router. Clients can then connect
+to set up network redirection on the virtual router. Clients can then connect
to a specified guest port on the router, while the router directs traffic
to/from that port to the emulated device's host port. </p>
-<p>To set up the network redirections, you create a mapping of host and guest
+<p>To set up the network redirection, you create a mapping of host and guest
ports/addresses on the the emulator instance. There are two ways to set up
-network redirections: using emulator console commands and using the ADB tool, as
+network redirection: using emulator console commands and using the ADB tool, as
described below. </p>
-<a name="consoleredir"></a>
-<h4>Setting up Redirections through the Emulator Console</h4>
+
+<h4 id="consoleredir">Setting up Redirection through the Emulator Console</h4>
<p>Each emulator instance provides a control console the you can connect to, to
issue commands that are specific to that instance. You can use the
-<code>redir</code> console command to set up redirections as needed for an
+<code>redir</code> console command to set up redirection as needed for an
emulator instance. </p>
<p>First, determine the console port number for the target emulator instance.
@@ -1044,25 +917,25 @@
<pre><code>telnet localhost 5554</code></pre>
-<p>Once connected, use the <code>redir</code> command to work with redirections.
+<p>Once connected, use the <code>redir</code> command to work with redirection.
To add a redirection, use:</p>
<pre><code>add <protocol>:<host-port>:<guest-port></code>
</pre>
-<p>where <code><protocol></code> is either <code>tcp</code> or <code>udp</code>,
-and <code><host-port></code> and <code><guest-port></code> sets the
+<p>where <code><protocol></code> is either <code>tcp</code> or <code>udp</code>,
+and <code><host-port></code> and <code><guest-port></code> sets the
mapping between your own machine and the emulated system, respectively. </p>
-<p>For example, the following command sets up a redirection that will handle all
+<p>For example, the following command sets up a redirection that handles all
incoming TCP connections to your host (development) machine on 127.0.0.1:5000
and will pass them through to the emulated system's 10.0.2.15:6000.:</p>
<pre>redir add tcp:5000:6000</pre>
<p>To delete a redirection, you can use the <code>redir del</code> command. To
-list all redirections for a specific instance, you can use <code>redir
-list</code>. For more information about these and other console commands, see
+list all redirection for a specific instance, you can use <code>redir
+list</code>. For more information about these and other console commands, see
<a href="#console">Using the Emulator Console</a>. </p>
<p>Note that port numbers are restricted by your local environment. this typically
@@ -1071,29 +944,28 @@
host port that is already in use by another process on your machine. In that
case, <code>redir</code> generates an error message to that effect. </p>
-<a name="adbredir"></a>
-<h4>Setting Up Redirections through ADB</h4>
+<h4 id="adbredir">Setting Up Redirection through ADB</h4>
<p>The Android Debug Bridge (ADB) tool provides port forwarding, an alternate
-way for you to set up network redirections. For more information, see <a
+way for you to set up network redirection. For more information, see <a
href="{@docRoot}guide/developing/tools/adb.html#forwardports">Forwarding Ports</a> in the ADB
documentation.</p>
<p>Note that ADB does not currently offer any way to remove a redirection,
except by killing the ADB server.</p>
-<a name="dns"></a>
-<h3>Configuring the Emulator's DNS Settings</h3>
+
+<h3 id="dns">Configuring the Emulator's DNS Settings</h3>
<p>At startup, the emulator reads the list of DNS servers that your system is
currently using. It then stores the IP addresses of up to four servers on this
list and sets up aliases to them on the emulated addresses 10.0.2.3, 10.0.2.4,
10.0.2.5 and 10.0.2.6 as needed. </p>
-<p>On Linux and OS X, the emulator obtains the DNS server addresses by parsing
-the file <code>/etc/resolv.conf</code>. On Windows, the emulator obtains the
-addresses by calling the <code>GetNetworkParams()</code> API. Note that this
-usually means that the emulator ignores the content of your "hosts" file
+<p>On Linux and OS X, the emulator obtains the DNS server addresses by parsing
+the file <code>/etc/resolv.conf</code>. On Windows, the emulator obtains the
+addresses by calling the <code>GetNetworkParams()</code> API. Note that this
+usually means that the emulator ignores the content of your "hosts" file
(<code>/etc/hosts</code> on Linux/OS X, <code>%WINDOWS%/system32/HOSTS</code>
on Windows).</P>
@@ -1104,8 +976,8 @@
encounter DNS resolution problems in the emulated network (for example, an
"Unknown Host error" message that appears when using the web browser).</p>
-<a name="proxy"></a>
-<h3>Using the Emulator with a Proxy</h3>
+
+<h3 id="proxy">Using the Emulator with a Proxy</h3>
<p>If your emulator must access the Internet through a proxy server, you can use
the <code>-http-proxy <proxy></code> option when starting the emulator, to
@@ -1132,18 +1004,18 @@
<p>You can use the <code>-verbose-proxy</code> option to diagnose proxy
connection problems.</p>
-<a name="connecting"></a>
-<h3>Interconnecting Emulator Instances</h3>
+
+<h3 id="connecting">Interconnecting Emulator Instances</h3>
<p>To allow one emulator instance to communicate with another, you must set up
-the necessary network redirections as illustrated below. </p>
+the necessary network redirection as illustrated below. </p>
<p>Assume that your environment is</p>
<ul>
<li>A is you development machine</li>
<li>B is your first emulator instance, running on A</li>
- <li>C is your second emulator instance, running on A too</li>
+ <li>C is your second emulator instance, also running on A</li>
</ul>
<p>and you want to run a server on B, to which C will connect, here is how you
@@ -1168,10 +1040,11 @@
<li>C connects to 10.0.2.2:8080</li>
</ul>
-<a name="calling"></a>
-<h3>Sending a Voice Call or SMS to Another Emulator Instance</h3>
+<h3 id="calling">Sending a Voice Call or SMS to Another Emulator Instance</h3>
-<p>The emulator automatically forwards simulated voice calls and SMS messages from one instance to another. To send a voice call or SMS, you use the dialer application and SMS application (if available) installed on one emulator </p>
+<p>The emulator automatically forwards simulated voice calls and SMS messages from one instance to
+another. To send a voice call or SMS, use the dialer application or SMS application, respectively,
+from one of the emulators.</p>
<p>To initiate a simulated voice call to another emulator instance:</p>
<ol>
@@ -1186,16 +1059,23 @@
<p>You can also connect to an emulator instance's console to simulate an incoming voice call or SMS. For more information, see <a href="#telephony">Telephony Emulation</a> and <a href="#sms">SMS Emulation</a>.
-<a name="console"></a>
-<h2>Using the Emulator Console</h2>
+<h2 id="console">Using the Emulator Console</h2>
-<p>Each running emulator instance includes a console facility that lets you dynamically query and control the simulated device environment. For example, you can use the console to dynamically manage port redirections and network characteristics and simulate telephony events. To access the console and enter commands, you use telnet to connect to the console's port number. </p>
+<p>Each running emulator instance provides a console that lets you query and control the emulated
+device environment. For example, you can use the console to manage port redirection, network
+characteristics, and telephony events while your application is running on the emulator. To
+access the console and enter commands, use telnet to connect to the console's port number.</p>
+
<p>To connect to the console of any running emulator instance at any time, use this command: </p>
<pre>telnet localhost <console-port></pre>
-<p>An emulator instance occupies a pair of adjacent ports: a console port and an adb port. The port numbers differ by 1, with the adb port having the higher port number. The console of the first emulator instance running on a given machine uses console port 5554 and adb port 5555. Subsequent instances use port numbers increasing by two — for example, 5556/5557, 5558/5559, and so on. Up to 16 concurrent emulator instances can run a console facility. </p>
+<p>An emulator instance occupies a pair of adjacent ports: a console port and an {@code adb} port.
+The port numbers differ by 1, with the {@code adb} port having the higher port number. The console
+of the first emulator instance running on a given machine uses console port 5554 and {@code adb}
+port 5555. Subsequent instances use port numbers increasing by two — for example, 5556/5557,
+5558/5559, and so on. Up to 16 concurrent emulator instances can run a console facility. </p>
<p>To connect to the emulator console, you must specify a valid console port. If multiple emulator instances are running, you need to determine the console port of the emulator instance you want to connect to. You can find the instance's console port listed in the title of the instance window. For example, here's the window title for an instance whose console port is 5554:</p>
@@ -1209,12 +1089,14 @@
<p>To exit the console session, use <code>quit</code> or <code>exit</code>.</p>
-<p>The sections below describe the major functional areas of the console.</p>
+<p>The following sections below describe the major functional areas of the console.</p>
-<a name="portredirection"></a>
-<h3>Port Redirection</h3>
-<p>You can use the console to add and remove port redirections while the emulator is running. After connecting to the console, you can manage port redirections in this way:</p>
+<h3 id="portredirection">Port Redirection</h3>
+
+<p>You can use the console to add and remove port redirection while the emulator is running. After
+you connect to the console, manage port redirection by entering the following command:</p>
+
<pre>redir <list|add|del> </pre>
<p>The <code>redir</code> command supports the subcommands listed in the table below. </p>
@@ -1225,14 +1107,14 @@
<th width="30%" >Description</th>
<th width="35%">Comments</th>
</tr>
-
+
<tr>
<td><code>list</code></td>
- <td>List the current port redirections.</td>
+ <td>List the current port redirection.</td>
<td> </td>
</tr>
-
+
<tr>
<td><code>add <protocol>:<host-port>:<guest-port></code></td>
<td>Add a new port redirection.</td>
@@ -1244,16 +1126,16 @@
<tr>
<td><code>del <protocol>:<host-port></code></td>
<td>Delete a port redirection.</td>
-<td>See above for meanings of <protocol> and <host-port>.</td>
+<td>The meanings of <protocol> and <host-port> are listed in the previous row.</td>
</tr>
</table>
-<a name="geo"></a>
-<h3>Geo Location Provider Emulation</h3>
-<p>The console provides commands to let you set the geo position used by an emulator emulated device.
-You can use the <code>geo</code> command to send a simple GPS fix to the emulator, without needing to
-use NMEA 1083 formatting. The usage for the command is:</p>
+<h3 id="geo">Geo Location Provider Emulation</h3>
+
+<p>You can use the console to set the geographic location reported to the applications running
+inside an emulator. Use the <code>geo</code> command to send a simple GPS fix to the
+emulator, with or without NMEA 1083 formatting:</p>
<pre>geo <fix|nmea></pre>
@@ -1261,11 +1143,11 @@
<table>
<tr>
- <th width="25%" >Subcommand
- <th width="30%" >Description</th>
+ <th width="25%">Subcommand</th>
+ <th width="30%">Description</th>
<th width="35%">Comments</th>
</tr>
-
+
<tr>
<td><code>fix <longitude> <latitude> [<altitude>]</code></td>
<td>Send a simple GPS fix to the emulator instance.</td>
@@ -1278,19 +1160,21 @@
</tr>
</table>
-<p>You can issue the <code>geo</code> command to fix the GPS location as soon as an emulator instance is running.
-The emulator creates a mock location provider that sends it to GPS-aware applications as soon as they start and
-register location listeners. Any application can query the location manager to obtain the current GPS fix for the
-emulated device by calling:
+<p>You can issue the <code>geo</code> command as soon as an emulator instance is running. The
+emulator sets the location you enter by creating a mock location provider. This provider responds to
+location listeners set by applications, and also supplies the location to the {@link
+android.location.LocationManager}. Any application can query the location manager to obtain the
+current GPS fix for the emulated device by calling:
<pre>LocationManager.getLastKnownLocation("gps")</pre>
-<p>For more information about the Location Manager, see {@link android.location.LocationManager} and its methods.</p>
+<p>For more information about the Location Manager, see {@link android.location.LocationManager}.
+</p>
-<a name="events"></a>
-<h3>Hardware Events Emulation</h3>
+<h3 id="events">Hardware Events Emulation</h3>
-<p>You can use the <code>event</code> command to send various events to the emulator.The usage for the command is: </p>
+<p>The {@code event} console commands sends hardware events to the emulator. The syntax for this
+command is as follows:</p>
<pre>event <send|types|codes|text></pre>
@@ -1302,7 +1186,7 @@
<th width="30%" >Description</th>
<th width="35%">Comments</th>
</tr>
-
+
<tr>
<td><code>send <type>:<code>:<value> [...]</code></td>
<td>Send one or more events to the Android kernel. </td>
@@ -1315,7 +1199,7 @@
</tr>
<tr>
<td><code>codes <type></code></td>
- <td>List all <code><codes></code> string aliases supported by the <code>event</code>
+ <td>List all <code><codes></code> string aliases supported by the <code>event</code>
subcommands for the specified <code><type></code>.</td>
<td> </td>
</tr>
@@ -1326,10 +1210,11 @@
</tr>
</table>
-<a name="power"></a>
-<h3>Device Power Characteristics</h3>
-<p>You can use the <code>power</code> command to control the simulated power state of the emulator instance.The usage for the command is: </p>
+<h3 id="power">Device Power Characteristics</h3>
+
+<p>The {@code power} command controls the power state reported by the emulator to applications. The
+syntax for this command is as follows: </p>
<pre>power <display|ac|status|present|health|capacity></pre>
@@ -1341,7 +1226,7 @@
<th width="30%" >Description</th>
<th width="35%">Comments</th>
</tr>
-
+
<tr>
<td><code>display</code></td>
<td>Display battery and charger state.</td>
@@ -1375,23 +1260,32 @@
</tr>
</table>
-<a name="netstatus"></a>
-<h3>Network Status</h3>
+
+<h3 id="netstatus">Network Status</h3>
<p>You can use the console to check the network status and current delay and speed characteristics. To do so, connect to the console and use the <code>netstatus</code> command. Here's an example of the command and its output. </p>
<pre>network status
</pre>
-<a name="netdelay"></a>
-<h3>Network Delay Emulation</h3>
-<p>The emulator lets you simulate various network latency levels, so that you can test your application in an environment more typical of the actual conditions in which it will run. You can set a latency level or range at emulator startup or you can use the console to change the latency dynamically, while the application is running in the emulator. </p>
-<p>To set latency at emulator startup, use the <code>-netdelay</code> emulator option with a supported <code><delay></code> value, as listed in the table below. Here are some examples:</p>
+<h3 id="netdelay">Network Delay Emulation</h3>
+
+<p>The emulator lets you simulate various network latency levels, so that you can test your
+application in an environment more typical of the actual conditions in which it will run. You can
+set a latency level or range at emulator startup or you can use the console to change the latency,
+while the application is running in the emulator. </p>
+
+<p>To set latency at emulator startup, use the <code>-netdelay</code> emulator option with a
+supported <code><delay></code> value, as listed in the table below. Here are some
+examples:</p>
+
<pre>emulator -netdelay gprs
emulator -netdelay 40 100</pre>
-<p>To make dynamic changes to network delay while the emulator is running, connect to the console and use the <code>netdelay</code> command with a supported <code><delay></code> value from the table below. </p>
+<p>To make changes to network delay while the emulator is running, connect to the console and use
+the <code>netdelay</code> command with a supported <code><delay></code> value from the table
+below.</p>
<pre>network delay gprs</pre>
@@ -1401,7 +1295,7 @@
<tr>
<th width="30%" >Value</th>
<th width="35%" >Description</th><th width="35%">Comments</th></tr>
-
+
<tr><td><code>gprs</code></td><td>GPRS</td>
<td>(min 150, max 550)</td>
</tr>
@@ -1421,19 +1315,22 @@
<td> </td></tr>
</table>
-<a name="netspeed"></a>
-<h3>Network Speed Emulation</h3>
-<p>The emulator also lets you simulate various network transfer rates.
-You can set a transfer rate or range at emulator startup or you can use the console to change the rate dynamically,
-while the application is running in the emulator.</p>
+<h3 id="netspeed">Network Speed Emulation</h3>
+
+<p>The emulator also lets you simulate various network transfer rates.
+You can set a transfer rate or range at emulator startup or you can use the console to change the
+rate, while the application is running in the emulator.</p>
<p>To set the network speed at emulator startup, use the <code>-netspeed</code> emulator option with a supported
<code><speed></code> value, as listed in the table below. Here are some examples:</p>
+
<pre>emulator -netspeed gsm
emulator -netspeed 14.4 80</pre>
-<p>To make dynamic changes to network speed while the emulator is running, connect to the console and use the <code>netspeed</code> command with a supported <code><speed></code> value from the table below. </p>
+<p>To make changes to network speed while the emulator is running, connect to the console and use
+the <code>netspeed</code> command with a supported <code><speed></code> value from the table
+below.</p>
<pre>network speed 14.4 80</pre>
@@ -1444,7 +1341,7 @@
<tr>
<th width="30%">Value</th>
<th width="35%">Description</th><th width="35%">Comments</th></tr>
-
+
<tr>
<td><code>gsm</code></td>
<td>GSM/CSD</td><td>(Up: 14.4, down: 14.4)</td></tr>
@@ -1476,14 +1373,19 @@
<td>Set exact rates for upload and download separately.</td><td></td></tr>
</table>
-<a name="telephony"></a>
-<h3>Telephony Emulation</h3>
+<h3 id="telephony">Telephony Emulation</h3>
-<p>The Android emulator includes its own GSM emulated modem that lets you simulate telephony functions in the emulator. For example, you can simulate inbound phone calls and establish/terminate data connections. The Android system handles simulated calls exactly as it would actual calls. The emulator does not support call audio in this release. </p>
-<p>You can use the console to access the emulator's telephony functions. After connecting to the console, you can use</p>
+<p>The Android emulator includes its own GSM emulated modem that lets you simulate telephony
+functions in the emulator. For example, you can simulate inbound phone calls, establish data
+connections and terminate them. The Android system handles simulated calls exactly as it would
+actual calls. The emulator does not support call audio.</p>
+
+<p>You can use the {@code gsm} command to access the emulator's telephony functions after connecting
+to the console. The syntax for this command is as follows:</p>
+
<pre>gsm <call|accept|busy|cancel|data|hold|list|voice|status> </pre>
-<p>to invoke telephony functions. </p>
+
<p>The <code>gsm</code> command supports the subcommands listed in the table below. </p>
<table>
<tr>
@@ -1559,11 +1461,12 @@
</tr>
</table>
-<a name="sms"></a>
-<h3>SMS Emulation</h3>
+<h3 id="sms">SMS Emulation</h3>
-<p>The Android emulator console lets you generate an SMS message and direct it to an emulator instance. Once you connect to an emulator instance, you can generate an emulated incoming SMS using this command:</p>
+<p>The Android emulator console lets you generate an SMS message and direct it to an emulator
+instance. Once you connect to an emulator instance, you can generate an emulated incoming SMS using
+the following command:</p>
<pre>sms send <senderPhoneNumber> <textmessage></pre>
@@ -1571,11 +1474,11 @@
<p>The console forwards the SMS message to the Android framework, which passes it through to an application that handles that message type. </p>
-<a name="vm"></a>
-<h3>VM State</h3>
+<h3 id="vm">VM State</h3>
-<p>You can use the <code>vm</code> command to control the VM on an emulator instance.The usage for the command is: </p>
+<p>You can use the <code>vm</code> command to control the VM on an emulator instance. The syntax for
+this command is as follows: </p>
<pre>vm <start|stop|status></pre>
@@ -1583,8 +1486,8 @@
<table>
<tr>
- <th width="25%" >Subcommand </th>
- <th width="30%" >Description</th>
+ <th width="25%">Subcommand</th>
+ <th width="30%">Description</th>
<th width="35%">Comments</th>
</tr>
<tr>
@@ -1605,11 +1508,10 @@
</table>
-<a name="window"></a>
+<h3 id="window">Emulator Window</h3>
-<h3>Emulator Window</h3>
-
-<p>You can use the <code>window</code> command to manage the emulator window. The usage for the command is: </p>
+<p>You can use the <code>window</code> command to manage the emulator window. The syntax for this
+command is as follows: </p>
<pre>window <scale></pre>
@@ -1617,158 +1519,53 @@
<table>
<tr>
- <th width="25%" >Subcommand
- <th width="30%" >Description</th>
+ <th width="25%">Subcommand</th>
+ <th width="30%">Description</th>
<th width="35%">Comments</th>
</tr>
<tr>
<td><code>scale <scale></code></td>
<td>Scale the emulator window.</td>
- <td><scale> must be a number between 0.1 and 3 that describes the desired scaling factor. You can
- also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto"
+ <td>A number between 0.1 and 3 that sets the scaling factor. You can
+ also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto"
tells the emulator to select the best window size.</td>
</tr>
</table>
-<a name="terminating"></a>
-
-<h3>Terminating an Emulator Instance</h3>
+<h3 id="terminating">Terminating an Emulator Instance</h3>
<p>You can terminate an emulator instance through the console, using the <code>kill</code> command.</p>
-<a name="skins"></a>
+<h2 id="limitations">Emulator Limitations</h2>
-<h2>Using Emulator Skins</h2>
-
-<p>The Android SDK includes several Emulator skins that you can use to control the resolution and density of the emulated device's screen. To select a specific skin for running the emulator, create an AVD that uses that skin. Please do not use deprecated emulator options such as <code>-skin</code> to control the skin used by an emulator instance. For more information about AVDs, see <a
-href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a>.</p>
+<p>The functional limitations of the emulator include: </p>
+<ul>
+ <li>No support for placing or receiving actual phone calls. You can simulate phone calls (placed
+ and received) through the emulator console, however. </li>
+ <li>No support for USB connections</li>
+ <li>No support for device-attached headphones</li>
+ <li>No support for determining network connected state</li>
+ <li>No support for determining battery charge level and AC charging state</li>
+ <li>No support for determining SD card insert/eject</li>
+ <li>No support for Bluetooth</li>
+</ul>
-<a name="multipleinstances"></a>
+<h2 id="troubleshooting">Troubleshooting Emulator Problems</h2>
-<h2>Running Multiple Emulator Instances</h2>
+<p>The {@code adb} utility sees the emulator as an actual physical device. For this reason, you
+might have to use the {@code -d} flag with some common {@code adb} commands, such as
+<code>install</code>. The {@code -d} flag lets you specify which of several connected devices to use
+as the target of a command. If you don't specify {@code -d}, the emulator targets the first
+device in its list. For more information about {@code adb}, see <a
+href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>.</p>
-<p>Through the AVDs configurations used by the emulator, you can run multiple
-instances of the emulator concurrently, each with its own AVD configuration and
-storage area for user data, SD card, and so on. You no longer need to use the
-<code>-d</code> option when launching the emulator, to point to an
-instance-specific storage area. </p>
-
-<a name="apps"></a>
-
-<h2>Installing Applications on the Emulator</h2>
-
-<p>If you don't have access to Eclipse or the ADT Plugin, you can install
-your application on the emulator <a href="{@docRoot}guide/developing/tools/adb.html#move">using
-the adb utility</a>. Before installing the application, you need to build and package it
-into an <code>.apk</code> as described in <a href="{@docRoot}guide/developing/building/index.html">Building and
-Running Apps</a>. Once the application is installed, you can start the emulator from the command
-line, as described in this document, using any startup options necessary.
-When the emulator is running, you can also connect to the emulator instance's
-console to issue commands as needed.</p>
-
-<p>As you update your code, you periodically package and install it on the emulator.
-The emulator preserves the application and its state data across restarts,
-in a user-data disk partition. To ensure that the application runs properly
-as you update it, you may need to delete the emulator's user-data partition.
-To do so, start the emulator with the <code>-wipe-data</code> option.
-For more information about the user-data partition and other emulator storage,
-see <a href="#diskimages">Working with Emulator Disk Images</a>.</p>
-
-<a name="sdcard"></a>
-<a name="creating"></a>
-
-<h2>SD Card Emulation</h2>
-
-<p>You can create a disk image and then load it to the emulator at startup, to
-simulate the presence of a user's SD card in the device. To do this, you can use
-the android tool to create a new SD card image with a new AVD, or you can use
-the mksdcard utility included in the SDK. </p>
-
-<p>The sections below describe how to create an SD card disk image, how to copy
-files to it, and how to load it in the emulator at startup. </p>
-
-<p>Note that you can only load disk image at emulator startup. Similarly, you
-can not remove a simulated SD card from a running emulator. However, you can
-browse, send files to, and copy/remove files from a simulated SD card either
-with adb or the emulator. </p>
-
-<p>The emulator supports emulated SDHC cards, so you can create an SD card image
-of any size up to 128 gigabytes.</p>
-
-<h3 id="creatinga">Creating an SD card image using the android tool</h3>
-
-<p>The easiest way to create a new SD card is to use the android tool. When
-creating an AVD, you simply specify the <code>-c</code> option, like this: </p>
-
-<pre>android create avd -n <avd_name> -t <targetID> -c <size>[K|M]</pre>
-
-<p>You can also use the <code>-c</code> option to specify a path to an SD card
-image to use in the new AVD. For more information, see <a
-href="{@docRoot}guide/developing/devices/managing-avds-cmdline.html">Managing Virtual Devices
-from the Command Line</a>.
-</p>
-
-<h3 id="creatingm">Creating an SD card image using mksdcard</h3>
-
-<p>You can use the mksdcard tool, included in the SDK, to create a FAT32 disk
-image that you can load in the emulator at startup. You can access mksdcard in
-the tools/ directory of the SDK and create a disk image like this: </p>
-
-<pre>mksdcard <size> <file></pre>
-
-<p>For example:</p>
-
-<pre>mksdcard 1024M sdcard1.iso</pre>
-
-<p>For more information, see <a href="{@docRoot}guide/developing/tools/mksdcard.html"><code>mksdcard</code></a>.</p>
-
-<a name="copying"></a>
-<h3>Copying Files to a Disk Image</h3>
-
-<p>Once you have created the disk image, you can copy files to it prior to
-loading it in the emulator. To copy files, you can mount the image as a loop
-device and then copy the files to it, or you can use a utility such as mtools to
-copy the files directly to the image. The mtools package is available for Linux,
-Mac, and Windows.</p>
-
-<a name="loading"></a>
-<a name="step3" id="step3"></a>
-
-<h3>Loading the Disk Image at Emulator Startup</h3>
-
-<p>By default, the emulator loads the SD card image that is stored with the active
-AVD (see the <code>-avd</code> startup option).</p>
-
-<p>Alternatively, you ca start the emulator with the
-<code>-sdcard</code> flag and specify the name and path of your image (relative
-to the current working directory): </p>
-
-<pre>emulator -sdcard <filepath></pre>
-
-<a name="troubleshooting"></a>
-
-<h2>Troubleshooting Emulator Problems</h2>
-
-<p>The adb utility sees the emulator as an actual physical device. For this reason, you might have to use the -d flag with some common adb commands, such as <code>install</code>. The -d flag lets you specify which of several connected devices to use as the target of a command. If you don't specify -d, the emulator will target the first device in its list. For more information about adb, see <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>.</p>
-
-<p>For emulators running on Mac OS X, if you see an error "Warning: No DNS servers found" when starting the emulator, check to see whether you have an <code>/etc/resolv.conf</code> file. If not, please run the following line in a command window:</p>
+<p>For emulators running on Mac OS X, if you see an error {@code Warning: No DNS servers found}
+when starting the emulator, check to see whether you have an <code>/etc/resolv.conf</code> file. If
+not, please run the following line in a command window:</p>
<pre>ln -s /private/var/run/resolv.conf /etc/resolv.conf</pre>
-<p>See <a href="{@docRoot}resources/faq/index.html">Frequently Asked Questions</a> for more troubleshooting information. </p>
-
-<a name="limitations"></a>
- <h2>Emulator Limitations</h2>
- <p>In this release, the limitations of the emulator include: </p>
- <ul>
- <li>No support for placing or receiving actual phone calls. You can simulate phone calls (placed and received) through the emulator console, however. </li>
- <li>No support for USB connections</li>
- <li>No support for camera/video capture (input).</li>
- <li>No support for device-attached headphones</li>
- <li>No support for determining connected state</li>
- <li>No support for determining battery charge level and AC charging state</li>
- <li>No support for determining SD card insert/eject</li>
- <li>No support for Bluetooth</li>
- </ul>
+<p>See <a href="{@docRoot}resources/faq/index.html">Frequently Asked Questions</a> for more
+troubleshooting information. </p>
diff --git a/docs/html/guide/developing/tools/emulator.jd b/docs/html/guide/developing/tools/emulator.jd
index 09e41c3..21d4263 100644
--- a/docs/html/guide/developing/tools/emulator.jd
+++ b/docs/html/guide/developing/tools/emulator.jd
@@ -8,8 +8,8 @@
<h2>In this document</h2>
<ol>
- <li><a href="#startup-options">Emulator Startup Options</a></li>
- <li><a href="#KeyMapping">Emulator Keyboard Mapping</a></li>
+ <li><a href="#KeyMapping">Keyboard Commands</a></li>
+ <li><a href="#startup-options">Command Line Parameters</a></li>
</ol>
<h2>See also</h2>
@@ -22,461 +22,21 @@
</div>
-<p>The Android SDK includes a mobile device emulator — a virtual mobile device
+<p>The Android SDK includes a mobile device emulator — a virtual mobile device
that runs on your computer. The emulator lets you develop and test
Android applications without using a physical device.</p>
-<p>When the emulator is running, you can interact with the emulated mobile
-device just as you would an actual mobile device, except that you use your mouse
-pointer to "touch" the touchscreen and can use some keyboard keys to
-invoke certain keys on the device. </p>
-
-<p>This document is a reference to the available command line options and the keyboard mapping to device keys.
-For a complete guide to using the Android Emulator, see
+<p>This document is a reference to the available command line options and the keyboard mapping to
+device keys.
+For a complete guide to using the Android Emulator, see
<a href="{@docRoot}guide/developing/devices/emulator.html">Using the Android Emulator</a>.
-<h2 id="startup-options">Emulator Startup Options</h2>
+<h2 id="KeyMapping">Keyboard Commands</h2>
-<p>The emulator supports a variety of options that you can specify
-when launching the emulator, to control its appearance or behavior.
-Here's the command-line usage for launching the emulator with options: </p>
+<p>Table 1 summarizes the mappings between the emulator keys and the keys of your keyboard.</p>
-<pre>emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]</pre>
-
-<p class="table-caption"><strong>Table 1.</strong>Emulator startup options</p>
-
-<table>
-<tr>
- <th width="10%" >Category</th>
- <th width="20%" >Option</th>
- <th width="30%" >Description</th>
- <th width="40%" >Comments</th>
-</tr>
-
-<tr>
- <td rowspan="9">Help</td>
- <td><code>-help</code></td>
- <td>Print a list of all emulator options.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-help-all</code></td>
- <td>Print help for all startup options.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-help-<option></code></td>
- <td>Print help for a specific startup option.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-help-debug-tags</code></td>
- <td>Print a list of all tags for <code>-debug <tags></code>.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-help-disk-images</code></td>
- <td>Print help for using emulator disk images.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-help-environment</code></td>
- <td>Print help for emulator environment variables.</td>
- <td> </td>
-</tr><tr>
- <td><code>-help-keys</code></td>
- <td>Print the current mapping of keys.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-help-keyset-file</code></td>
- <td>Print help for defining a custom key mappings file.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-help-virtual-device</code></td>
- <td>Print help for Android Virtual Device usage.</td>
- <td> </td>
-</tr>
-<tr>
- <td>AVD</td>
- <td><code>-avd <avd_name></code> or <br>
- <code>@<avd_name></code></td>
- <td><strong>Required</strong>. Specifies the AVD to load for this emulator
- instance.</td>
- <td>You must create an AVD configuration before launching the emulator. For
- information, see <a href="{@docRoot}guide/developing/devices/managing-avds.html#createavd">
- Managing AVDs with AVD Manager</a>.</td>
-<tr>
- <td rowspan="7">Disk Images</td>
- <td><code>-cache <filepath></code></td>
- <td>Use <filepath> as the working cache partition image. </td>
- <td>Optionally, you can specify a path relative to the current working directory.
- If no cache file is specified, the emulator's default behavior is to use a temporary file instead.
- <p>For more information on disk images, use <code>-help-disk-images</code>.</p>
-</td></tr>
-<tr>
- <td><code>-data <filepath></code></td>
- <td>Use <filepath> as the working user-data disk image. </td>
- <td>Optionally, you can specify a path relative to the current working directory.
- If <code>-data</code> is not used, the emulator looks for a file named "userdata-qemu.img"
- in the storage area of the AVD being used (see <code>-avd</code>).
-</td></tr>
-<!--
-<tr>
- <td><code>-datadir <dir></code></td>
- <td>Search for the user-data disk image specified in <code>-data</code> in <dir></td>
- <td><code><dir></code> is a path relative to the current working directory.
-
-<p>If you do not specify <code>-datadir</code>, the emulator looks for the user-data image
-in the storage area of the AVD being used (see <code>-avd</code>)</p><p>For more information
-on disk images, use <code>-help-disk-images</code>.</p>
-</td></tr>
--->
-<!--
-<tr>
- <td><code>-image <filepath></code></td>
- <td>Use <filepath> as the system image.</td>
- <td>Optionally, you can specify a path relative to the current working directory.
- Default is <system>/system.img.</td>
-</tr>
--->
-<tr>
- <td><code>-initdata <filepath></code></td>
- <td>When resetting the user-data image (through <code>-wipe-data</code>), copy the contents
- of this file to the new user-data disk image. By default, the emulator copies the <code><system>/userdata.img</code>.</td>
- <td>Optionally, you can specify a path relative to the current working directory. See also <code>-wipe-data</code>. <p>For more information on disk images, use <code>-help-disk-images</code>.</p></td>
-</tr>
-<!--
-<tr>
- <td><code>-kernel <filepath></code></td>
- <td>Use <filepath> as the emulated kernel.</td>
- <td>Optionally, you can specify a path relative to the current working directory. </td>
-</tr>
--->
-<tr>
- <td><code>-nocache</code></td>
- <td>Start the emulator without a cache partition.</td>
- <td>See also <code>-cache <file></code>.</td>
-</tr>
-<tr>
- <td><code>-ramdisk <filepath></code></td>
- <td>Use <filepath> as the ramdisk image.</td>
- <td>Default value is <code><system>/ramdisk.img</code>.
- <p>Optionally, you can specify a path relative to the current working directory. For more information on disk images, use <code>-help-disk-images</code>.</p>
-</td>
-</tr>
-<tr>
- <td><code>-sdcard <filepath></code></td>
- <td>Use <file> as the SD card image.</td>
- <td>Default value is <code><system>/sdcard.img</code>.
- <p>Optionally, you can specify a path relative to the current working directory. For more information on disk images, use <code>-help-disk-images</code>.</p>
-</td>
-</tr>
-<!--
-<tr>
- <td><code>-system <dirpath></code></td>
- <td>Search for system, ramdisk and user data images in <dir>.</td>
- <td><code><dir></code> is a directory path relative to the current
- working directory.</td>
-</tr>
--->
-<tr>
- <td><code>-wipe-data</code></td>
- <td>Reset the current user-data disk image (that is, the file specified by <code>-datadir</code> and
- <code>-data</code>, or the default file). The emulator deletes all data from the user data image file,
- then copies the contents of the file at <code>-inidata</code> data to the image file before starting.
- </td>
- <td>See also <code>-initdata</code>.
- <p>For more information on disk images, use <code>-help-disk-images</code>.</p>
-</td>
-</tr>
-<tr>
- <td rowspan="9">Debug</td>
- <td><code>-debug <tags></code></td>
- <td>Enable/disable debug messages for the specified debug tags.</td>
- <td><code><tags></code> is a space/comma/column-separated list of debug component names.
- Use <code>-help-debug-tags</code> to print a list of debug component names that you can use. </td>
-</tr>
-<tr>
- <td><code>-debug-<tag></code></td>
- <td>Enable/disable debug messages for the specified debug tag.</td>
- <td rowspan="2">Use <code>-help-debug-tags</code> to print a list of debug component names that you can use in <code><tag></code>. </td>
-</tr>
-<tr>
- <td><code>-debug-no-<tag></code></td>
- <td>Disable debug messages for the specified debug tag.</td>
-</tr>
-<tr>
- <td><code>-logcat <logtags></code></td>
- <td>Enable logcat output with given tags.</td>
- <td>If the environment variable ANDROID_LOG_TAGS is defined and not
- empty, its value will be used to enable logcat output by default.</td>
-</tr>
-<tr>
- <td><code>-shell</code></td>
- <td>Create a root shell console on the current terminal.</td>
- <td>You can use this command even if the adb daemon in the emulated system is broken.
- Pressing Ctrl-c from the shell stops the emulator instead of the shell.</td>
-</tr>
-<tr>
- <td><code>-shell-serial <device></code></td>
- <td>Enable the root shell (as in <code>-shell</code> and specify the QEMU character
- device to use for communication with the shell.</td>
- <td><device> must be a QEMU device type. See the documentation for '-serial <em>dev</em>' at
- <a href="http://wiki.qemu.org/download/qemu-doc.html">wiki.qemu.org</a>
- for more information.</p>
-
-<p>Here are some examples: </p>
-<ul>
- <li><code>-shell-serial stdio</code> is identical to <code>-shell</code></li>
- <li><code>-shell-serial tcp::4444,server,nowait</code> lets you communicate with the shell over TCP port 4444</li>
- <li><code>-shell-serial fdpair:3:6</code> lets a parent process communicate with the shell using fds 3 (in) and 6 (out)</li>
- <li><code>-shell-serial fdpair:0:1</code> uses the normal stdin and stdout fds, except that QEMU won't tty-cook the data.</li>
- </ul>
-</td>
-</tr>
-<tr>
- <td><code>-show-kernel <name></code></td>
- <td>Display kernel messages.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-trace <name></code></td>
- <td>Enable code profiling (press F9 to start), written to a specified file.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-verbose</code></td>
- <td>Enable verbose output.</td>
- <td>Equivalent to <code>-debug-init</code>.
-<p>You can define the default verbose output options used by emulator instances in the Android environment variable
-ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, specifying only the stem of each option:
-<code>-debug-<tags>.</code> </p>
-<p>Here's an example showing ANDROID_VERBOSE defined with the <code>-debug-init</code> and <code>-debug-modem</code> options:
-<p><code>ANDROID_VERBOSE=init,modem</code></p>
-<p>For more information about debug tags, use <code><-help-debug-tags></code>.</p>
-</td>
-</tr>
-<tr>
- <td rowspan="6">Media</td>
- <td><code>-audio <backend></code></td>
- <td>Use the specified audio backend.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-audio-in <backend></code></td>
- <td>Use the specified audio-input backend.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-audio-out <backend></code></td>
- <td>Use the specified audio-output backend.</td>
- <td> </td>
-</tr>
-<!--<tr>
- <td><code>-mic <device or file></code></td>
- <td>Use device or WAV file for audio input.</td>
- <td> </td>
-</tr>
--->
-<tr>
- <td><code>-noaudio</code></td>
- <td>Disable audio support in the current emulator instance.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-radio <device></code></td>
- <td>Redirect radio modem interface to a host character device.</td>
- <td> </td></tr>
-<tr>
- <td><code>-useaudio</code></td>
- <td>Enable audio support in the current emulator instance.</td>
- <td>Enabled by default. </td>
-</tr>
-
-<tr>
- <td rowspan="7">Network</td>
- <td><code>-dns-server <servers></code></td>
- <td>Use the specified DNS server(s). </td>
- <td>The value of <code><servers></code> must be a comma-separated list of up to 4 DNS server names or
- IP addresses.</td>
-</tr>
-<tr>
- <td><code>-http-proxy <proxy></code></td>
- <td>Make all TCP connections through a specified HTTP/HTTPS proxy</td>
- <td>The value of <code><proxy></code> can be one of the following:<br>
- <code>http://<server>:<port></code><br>
- <code>http://<username>:<password>@<server>:<port></code>
- <p>The <code>http://</code> prefix can be omitted. If the <code>-http-proxy <proxy></code> command is not supplied,
- the emulator looks up the <code>http_proxy</code> environment variable and automatically uses any value matching
- the <code><proxy></code> format described above.</p></td>
-</tr>
-<tr>
- <td><code>-netdelay <delay></code></td>
- <td>Set network latency emulation to <delay>.</td>
- <td>Default value is <code>none</code>. See the table in <a href="#netdelay">Network Delay Emulation</a> for
- supported <code><delay></code> values. </td>
-</tr>
-<tr>
- <td><code>-netfast</code></td>
- <td>Shortcut for <code>-netspeed full -netdelay none</code></td>
- <td> </td></tr>
-<tr>
- <td><code>-netspeed <speed></code></td>
- <td>Set network speed emulation to <speed>.</td>
- <td>Default value is <code>full</code>. See the table in <a href="#netspeed">Network Speed Emulation</a> for
- supported <code><speed></code> values. </td>
-</tr>
-<tr>
- <td><code>-port <port></code></td>
- <td>Set the console port number for this emulator instance to <code><port></code>.</td>
- <td>The console port number must be an even integer between 5554 and 5584, inclusive. <code><port></code>+1
- must also be free and will be reserved for ADB.</td>
-</tr>
-<tr>
- <td><code>-report-console <socket></code></td>
- <td>Report the assigned console port for this emulator instance to a remote third party
- before starting the emulation. </td>
- <td><code><socket></code> must use one of these formats:
-
-<p><code>tcp:<port>[,server][,max=<seconds>]</code></br>
-<code>unix:<port>[,server][,max=<seconds>]</code></p>
-
-<p>Use <code>-help-report-console</code></p> to view more information about this topic. </td>
-</tr>
-<tr>
- <td rowspan="8">System</td>
- <td><code>-cpu-delay <delay></code></td>
- <td>Slow down emulated CPU speed by <delay> </td>
- <td>Supported values for <delay> are integers between 0 and 1000.
-
-<p>Note that the <delay> does not correlate to clock speed or other absolute metrics
-— it simply represents an abstract, relative delay factor applied non-deterministically
-in the emulator. Effective performance does not always
-scale in direct relationship with <delay> values.</p>
-</td>
-</tr>
-<tr>
- <td><code>-gps <device></code></td>
- <td>Redirect NMEA GPS to character device.</td>
- <td>Use this command to emulate an NMEA-compatible GPS unit connected to
- an external character device or socket. The format of <code><device></code> must be QEMU-specific
- serial device specification. See the documentation for 'serial -dev' at
- <a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>.
-</td>
-</tr>
-<tr>
- <td><code>-nojni</code></td>
- <td>Disable JNI checks in the Dalvik runtime.</td><td> </td></tr>
-<tr>
- <td><code>-qemu</code></td>
- <td>Pass arguments to qemu.</td>
- <td> </td></tr>
-<tr>
- <td><code>-qemu -h</code></td>
- <td>Display qemu help.</td>
- <td></td></tr>
-<tr>
- <td><code>-radio <device></code></td>
- <td>Redirect radio mode to the specified character device.</td>
- <td>The format of <code><device></code> must be QEMU-specific
- serial device specification. See the documentation for 'serial -dev' at
-<a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>.
-</td>
-</tr>
-<tr>
- <td><code>-timezone <timezone></code></td>
- <td>Set the timezone for the emulated device to <timezone>, instead of the host's timezone.</td>
- <td><code><timezone></code> must be specified in zoneinfo format. For example:
-<p>"America/Los_Angeles"<br>
-"Europe/Paris"</p>
-</td>
-</tr>
-<tr>
- <td><code>-version</code></td>
- <td>Display the emulator's version number.</td>
- <td> </td>
-</tr>
-<tr>
- <td rowspan="12">UI</td>
- <td><code>-dpi-device <dpi></code></td>
- <td>Scale the resolution of the emulator to match the screen size
- of a physical device.</td>
- <td>The default value is 165. See also <code>-scale</code>.</td>
-</tr>
-<tr>
- <td><code>-no-boot-anim</code></td>
- <td>Disable the boot animation during emulator startup.</td>
- <td>Disabling the boot animation can speed the startup time for the emulator.</td>
-</tr>
-<tr>
- <td><code>-no-window</code></td>
- <td>Disable the emulator's graphical window display.</td>
- <td> </td>
-</tr>
-<tr>
- <td><code>-scale <scale></code></td>
- <td>Scale the emulator window. </td>
- <td><code><scale></code> is a number between 0.1 and 3 that represents the desired scaling factor. You can
- also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto"
- tells the emulator to select the best window size.</td>
-</tr>
-<tr>
- <td><code>-raw-keys</code></td>
- <td>Disable Unicode keyboard reverse-mapping.</td>
- <td> </td></tr>
-<tr>
- <td><code>-noskin</code></td>
- <td>Don't use any emulator skin.</td>
- <td> </td></tr>
-<tr>
- <td><code>-keyset <file></code></td>
- <td>Use the specified keyset file instead of the default.</td>
- <td>The keyset file defines the list of key bindings between the emulator and the host keyboard.
- For more information, use <code>-help-keyset</code> to print information about this topic.
-</td>
-</tr>
-<tr>
- <td><code>-onion <image></code></td>
- <td>Use overlay image over screen.</td>
- <td>No support for JPEG. Only PNG is supported.</td></tr>
-<tr>
- <td><code>-onion-alpha <percent></code></td>
- <td>Specify onion skin translucency value (as percent).
- <td>Default is 50.</td>
-</tr>
-<tr>
- <td><code>-onion-rotation <position></code></td>
- <td>Specify onion skin rotation.
- <td><code><position></code> must be one of the values 0, 1, 2, 3.</td>
-</tr>
-<tr>
- <td><code>-skin <skinID></code></td>
- <td>This emulator option is deprecated. </td>
- <td>Please set skin options using AVDs, rather than by using this emulator
-option. Using this option may yield unexpected and in some cases misleading
-results, since the density with which to render the skin may not be defined.
-AVDs let you associate each skin with a default density and override the default
-as needed. For more information, see <a
-href="{@docRoot}guide/developing/devices/managing-avds.html#createavd">
-Managing Virtual Devices with AVD Manager</a>.
-</td>
-</tr>
-<tr>
- <td><code>-skindir <dir></code></td>
- <td>This emulator option is deprecated. </td>
- <td>See comments for <code>-skin</code>, above.</td></tr>
-</table>
-
-
-
-<h2 id="KeyMapping">Emulator Keyboard Mapping</h2>
-
-<p>The table below summarizes the mappings between the emulator keys and and
-the keys of your keyboard. </p>
-<p class="table-caption"><strong>Table 2.</strong> Emulator keyboard mapping</p>
+<p class="table-caption"><strong>Table 1.</strong> Emulator keyboard mapping</p>
<table border="0" style="clear:left;">
<tr>
<th>Emulated Device Key </th>
@@ -569,4 +129,453 @@
</tr>
</table>
-<p>Note that, to use keypad keys, you must first disable NumLock on your development computer. </p>
+
+<h2 id="startup-options">Command Line Parameters</h2>
+
+<p>The emulator supports a variety of options that you can specify
+when launching the emulator, to control its appearance or behavior.
+Here's the command-line syntax of the options available to the {@code emulator} program:</p>
+
+<pre>emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]</pre>
+
+<p class="table-caption"><strong>Table 2.</strong> Emulator command line parameters</p>
+<table>
+<tr>
+ <th width="10%" >Category</th>
+ <th width="20%" >Option</th>
+ <th width="30%" >Description</th>
+ <th width="40%" >Comments</th>
+</tr>
+
+<tr>
+ <td>AVD</td>
+ <td><code>-avd <avd_name></code> or <br>
+ <code>@<avd_name></code></td>
+ <td><strong>Required</strong>. Specifies the AVD to load for this emulator
+ instance.</td>
+ <td>You must create an AVD configuration before launching the emulator. For
+ information, see <a href="{@docRoot}guide/developing/devices/managing-avds.html">Managing
+ AVDs with AVD Manager</a>.</td>
+<tr>
+ <td rowspan="7">Disk Images</td>
+ <td><code>-cache <filepath></code></td>
+ <td>Use <filepath> as the working cache partition image. </td>
+ <td>An absolute or relative path to the current working directory.
+ If no cache file is specified, the emulator's default behavior is to use a temporary file instead.
+ <p>For more information on disk images, use <code>-help-disk-images</code>.</p>
+</td></tr>
+<tr>
+ <td><code>-data <filepath></code></td>
+ <td>Use {@code <filepath>} as the working user-data disk image. </td>
+ <td>Optionally, you can specify a path relative to the current working directory.
+ If <code>-data</code> is not used, the emulator looks for a file named {@code userdata-qemu.img}
+ in the storage area of the AVD being used (see <code>-avd</code>).
+</td></tr>
+<!--
+<tr>
+ <td><code>-datadir <dir></code></td>
+ <td>Search for the user-data disk image specified in <code>-data</code> in <dir></td>
+ <td><code><dir></code> is a path relative to the current working directory.
+
+<p>If you do not specify <code>-datadir</code>, the emulator looks for the user-data image
+in the storage area of the AVD being used (see <code>-avd</code>)</p><p>For more information
+on disk images, use <code>-help-disk-images</code>.</p>
+</td></tr>
+-->
+<!--
+<tr>
+ <td><code>-image <filepath></code></td>
+ <td>Use <filepath> as the system image.</td>
+ <td>Optionally, you can specify a path relative to the current working directory.
+ Default is <system>/system.img.</td>
+</tr>
+-->
+<tr>
+ <td><code>-initdata <filepath></code></td>
+ <td>When resetting the user-data image (through <code>-wipe-data</code>), copy the contents
+ of this file to the new user-data disk image. By default, the emulator copies the <code><system>/userdata.img</code>.</td>
+ <td>Optionally, you can specify a path relative to the current working directory. See also <code>-wipe-data</code>.
+ <p>For more information on disk images, use <code>-help-disk-images</code>.</p></td>
+</tr>
+<tr>
+ <td><code>-nocache</code></td>
+ <td>Start the emulator without a cache partition.</td>
+ <td>See also <code>-cache <file></code>.</td>
+</tr>
+<tr>
+ <td><code>-ramdisk <filepath></code></td>
+ <td>Use <filepath> as the ramdisk image.</td>
+ <td>Default value is <code><system>/ramdisk.img</code>.
+ <p>Optionally, you can specify a path relative to the current working directory.
+ For more information on disk images, use <code>-help-disk-images</code>.</p>
+</td>
+</tr>
+<tr>
+ <td><code>-sdcard <filepath></code></td>
+ <td>Use <file> as the SD card image.</td>
+ <td>Default value is <code><system>/sdcard.img</code>.
+ <p>Optionally, you can specify a path relative to the current working directory. For more information on disk images, use <code>-help-disk-images</code>.</p>
+</td>
+</tr>
+<!--
+<tr>
+ <td><code>-system <dirpath></code></td>
+ <td>Search for system, ramdisk and user data images in <dir>.</td>
+ <td><code><dir></code> is a directory path relative to the current
+ working directory.</td>
+</tr>
+-->
+<tr>
+ <td><code>-wipe-data</code></td>
+ <td>Reset the current user-data disk image (that is, the file specified by <code>-datadir</code> and
+ <code>-data</code>, or the default file). The emulator deletes all data from the user data image file,
+ then copies the contents of the file at <code>-inidata</code> data to the image file before starting.
+ </td>
+ <td>See also <code>-initdata</code>.
+ <p>For more information on disk images, use <code>-help-disk-images</code>.</p>
+</td>
+</tr>
+<tr>
+ <td rowspan="9">Debug</td>
+ <td><code>-debug <tags></code></td>
+ <td>Enable/disable debug messages for the specified debug tags.</td>
+ <td><code><tags></code> is a space/comma/column-separated list of debug component names.
+ Use <code>-help-debug-tags</code> to print a list of debug component names that you can use. </td>
+</tr>
+<tr>
+ <td><code>-debug-<tag></code></td>
+ <td>Enable/disable debug messages for the specified debug tag.</td>
+ <td rowspan="2">Use <code>-help-debug-tags</code> to print a list of debug component names that you can use in <code><tag></code>. </td>
+</tr>
+<tr>
+ <td><code>-debug-no-<tag></code></td>
+ <td>Disable debug messages for the specified debug tag.</td>
+</tr>
+<tr>
+ <td><code>-logcat <logtags></code></td>
+ <td>Enable logcat output with given tags.</td>
+ <td>If the environment variable ANDROID_LOG_TAGS is defined and not
+ empty, its value will be used to enable logcat output by default.</td>
+</tr>
+<tr>
+ <td><code>-shell</code></td>
+ <td>Create a root shell console on the current terminal.</td>
+ <td>You can use this command even if the adb daemon in the emulated system is broken.
+ Pressing Ctrl-c from the shell stops the emulator instead of the shell.</td>
+</tr>
+<tr>
+ <td><code>-shell-serial <device></code></td>
+ <td>Enable the root shell (as in <code>-shell</code> and specify the QEMU character
+ device to use for communication with the shell.</td>
+ <td><device> must be a QEMU device type. See the documentation for '-serial <em>dev</em>' at
+ <a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>
+ for a list of device types.
+
+<p>Here are some examples: </p>
+<ul>
+ <li><code>-shell-serial stdio</code> is identical to <code>-shell</code></li>
+ <li><code>-shell-serial tcp::4444,server,nowait</code> lets you communicate with the shell over TCP port 4444</li>
+ <li><code>-shell-serial fdpair:3:6</code> lets a parent process communicate with the shell using fds 3 (in) and 6 (out)</li>
+ <li><code>-shell-serial fdpair:0:1</code> uses the normal stdin and stdout fds, except that QEMU won't tty-cook the data.</li>
+ </ul>
+</td>
+</tr>
+<tr>
+ <td><code>-show-kernel <name></code></td>
+ <td>Display kernel messages.</td>
+ <td> </td>
+</tr>
+<tr>
+ <td><code>-trace <name></code></td>
+ <td>Enable code profiling (press F9 to start), written to a specified file.</td>
+ <td> </td>
+</tr>
+<tr>
+ <td><code>-verbose</code></td>
+ <td>Enable verbose output.</td>
+ <td>Equivalent to <code>-debug-init</code>.
+<p>You can define the default verbose output options used by emulator instances in the Android environment variable
+ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, specifying only the stem of each option:
+<code>-debug-<tags>.</code> </p>
+<p>Here's an example showing ANDROID_VERBOSE defined with the <code>-debug-init</code> and <code>-debug-modem</code> options:
+<p><code>ANDROID_VERBOSE=init,modem</code></p>
+<p>For more information about debug tags, use <code><-help-debug-tags></code>.</p>
+</td>
+</tr>
+<tr>
+ <td rowspan="6">Media</td>
+ <td><code>-audio <backend></code></td>
+ <td>Use the specified audio backend.</td>
+ <td> </td>
+</tr>
+<tr>
+ <td><code>-audio-in <backend></code></td>
+ <td>Use the specified audio-input backend.</td>
+ <td> </td>
+</tr>
+<tr>
+ <td><code>-audio-out <backend></code></td>
+ <td>Use the specified audio-output backend.</td>
+ <td> </td>
+</tr>
+<!--<tr>
+ <td><code>-mic <device or file></code></td>
+ <td>Use device or WAV file for audio input.</td>
+ <td> </td>
+</tr>
+-->
+<tr>
+ <td><code>-noaudio</code></td>
+ <td>Disable audio support in the current emulator instance.</td>
+ <td> </td>
+</tr>
+<tr>
+ <td><code>-radio <device></code></td>
+ <td>Redirect radio modem interface to a host character device.</td>
+ <td> </td></tr>
+<tr>
+ <td><code>-useaudio</code></td>
+ <td>Enable audio support in the current emulator instance.</td>
+ <td>Enabled by default. </td>
+</tr>
+
+<tr>
+ <td rowspan="7">Network</td>
+ <td><code>-dns-server <servers></code></td>
+ <td>Use the specified DNS server(s). </td>
+ <td>The value of <code><servers></code> must be a comma-separated list of up to 4 DNS server names or
+ IP addresses.</td>
+</tr>
+<tr>
+ <td><code>-http-proxy <proxy></code></td>
+ <td>Make all TCP connections through a specified HTTP/HTTPS proxy</td>
+ <td>The value of <code><proxy></code> can be one of the following:<br>
+ <code>http://<server>:<port></code><br>
+ <code>http://<username>:<password>@<server>:<port></code>
+ <p>The <code>http://</code> prefix can be omitted. If the <code>-http-proxy <proxy></code> command is not supplied,
+ the emulator looks up the <code>http_proxy</code> environment variable and automatically uses any value matching
+ the <code><proxy></code> format described above.</p></td>
+</tr>
+<tr>
+ <td><code>-netdelay <delay></code></td>
+ <td>Set network latency emulation to <delay>.</td>
+ <td>Default value is <code>none</code>. See the table in
+ <a href="{@docRoot}guide/developing/devices/emulator.html#netdelay">Network Delay Emulation</a>
+ for supported <code><delay></code> values. </td>
+</tr>
+<tr>
+ <td><code>-netfast</code></td>
+ <td>Shortcut for <code>-netspeed full -netdelay none</code></td>
+ <td> </td></tr>
+<tr>
+ <td><code>-netspeed <speed></code></td>
+ <td>Set network speed emulation to <speed>.</td>
+ <td>Default value is <code>full</code>. See the table in
+ <a href="{@docRoot}guide/developing/devices/emulator.html#netspeed">Network Speed Emulation</a> for
+ supported <code><speed></code> values. </td>
+</tr>
+<tr>
+ <td><code>-port <port></code></td>
+ <td>Set the console port number for this emulator instance to <code><port></code>.</td>
+ <td>The console port number must be an even integer between 5554 and 5584, inclusive. <code><port></code>+1
+ must also be free and will be reserved for ADB.</td>
+</tr>
+<tr>
+ <td><code>-report-console <socket></code></td>
+ <td>Report the assigned console port for this emulator instance to a remote third party
+ before starting the emulation. </td>
+ <td><code><socket></code> must use one of these formats:
+
+<p><code>tcp:<port>[,server][,max=<seconds>]</code></br>
+<code>unix:<port>[,server][,max=<seconds>]</code></p>
+
+<p>Use <code>-help-report-console</code></p> to view more information about this topic. </td>
+</tr>
+<tr>
+ <td rowspan="10">System</td>
+ <td><code>-cpu-delay <delay></code></td>
+ <td>Slow down emulated CPU speed by <delay> </td>
+ <td>Supported values for <delay> are integers between 0 and 1000.
+
+<p>Note that the <delay> does not correlate to clock speed or other absolute metrics
+— it simply represents an abstract, relative delay factor applied non-deterministically
+in the emulator. Effective performance does not always
+scale in direct relationship with <delay> values.</p>
+</td>
+</tr>
+<tr>
+ <td><code>-gps <device></code></td>
+ <td>Redirect NMEA GPS to character device.</td>
+ <td>Use this command to emulate an NMEA-compatible GPS unit connected to
+ an external character device or socket. The format of <code><device></code> must be QEMU-specific
+ serial device specification. See the documentation for 'serial -dev' at
+ <a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>.
+</td>
+</tr>
+<tr>
+ <td><code>-nojni</code></td>
+ <td>Disable JNI checks in the Dalvik runtime.</td><td> </td></tr>
+<tr>
+ <td><code>-qemu</code></td>
+ <td>Pass arguments to the qemu emulator software.</td>
+ <td><p class="caution"><strong>Important:</strong> When using this option, make sure it is the
+ <em>last option</em> specified, since all options after it are interpretted as qemu-specific
+ options.</p></td></tr>
+<tr>
+ <td><code>-qemu -enable-kvm</code></td>
+ <td>Enable KVM acceleration of the emulator virtual machine.</td>
+ <td>This option is only effective when your system is set up to use
+ <a href="{@docRoot}guide/developing/devices/emulator.html#vm-linux">KVM-based VM acceleration</a>.
+ You can optionally specify a memory size ({@code -m <size>}) for the VM, which should match
+ your emulator's memory size:</p>
+ {@code -qemu -m 512 -enable-kvm}<br>
+ {@code -qemu -m 1024 -enable-kvm}
+ </td></tr>
+<tr>
+ <td><code>-qemu -h</code></td>
+ <td>Display qemu help.</td>
+ <td></td></tr>
+<tr>
+ <td><code>-gpu on</code></td>
+ <td>Turn on graphics acceleration for the emulator.</td>
+ <td>This option is only available for emulators using a system image with API Level 15, revision 3
+ and higher. For more information, see
+ <a href="{@docRoot}guide/developing/devices/emulator.html#accel-graphics">Using the Android
+ Emulator</a>.</td></tr>
+<tr>
+ <td><code>-radio <device></code></td>
+ <td>Redirect radio mode to the specified character device.</td>
+ <td>The format of <code><device></code> must be QEMU-specific
+ serial device specification. See the documentation for 'serial -dev' at
+<a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>.
+</td>
+</tr>
+<tr>
+ <td><code>-timezone <timezone></code></td>
+ <td>Set the timezone for the emulated device to <timezone>, instead of the host's timezone.</td>
+ <td><code><timezone></code> must be specified in zoneinfo format. For example:
+<p>"America/Los_Angeles"<br>
+"Europe/Paris"</p>
+</td>
+</tr>
+<tr>
+ <td><code>-version</code></td>
+ <td>Display the emulator's version number.</td>
+ <td> </td>
+</tr>
+<tr>
+ <td rowspan="12">UI</td>
+ <td><code>-dpi-device <dpi></code></td>
+ <td>Scale the resolution of the emulator to match the screen size
+ of a physical device.</td>
+ <td>The default value is 165. See also <code>-scale</code>.</td>
+</tr>
+<tr>
+ <td><code>-no-boot-anim</code></td>
+ <td>Disable the boot animation during emulator startup.</td>
+ <td>Disabling the boot animation can speed the startup time for the emulator.</td>
+</tr>
+<tr>
+ <td><code>-no-window</code></td>
+ <td>Disable the emulator's graphical window display.</td>
+ <td> </td>
+</tr>
+<tr>
+ <td><code>-scale <scale></code></td>
+ <td>Scale the emulator window. </td>
+ <td><code><scale></code> is a number between 0.1 and 3 that represents the desired scaling factor. You can
+ also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto"
+ tells the emulator to select the best window size.</td>
+</tr>
+<tr>
+ <td><code>-raw-keys</code></td>
+ <td>Disable Unicode keyboard reverse-mapping.</td>
+ <td> </td></tr>
+<tr>
+ <td><code>-noskin</code></td>
+ <td>Don't use any emulator skin.</td>
+ <td> </td></tr>
+<tr>
+ <td><code>-keyset <file></code></td>
+ <td>Use the specified keyset file instead of the default.</td>
+ <td>The keyset file defines the list of key bindings between the emulator and the host keyboard.
+ For more information, use <code>-help-keyset</code> to print information about this topic.
+</td>
+</tr>
+<tr>
+ <td><code>-onion <image></code></td>
+ <td>Use overlay image over screen.</td>
+ <td>No support for JPEG. Only PNG is supported.</td></tr>
+<tr>
+ <td><code>-onion-alpha <percent></code></td>
+ <td>Specify onion skin translucency value (as percent).
+ <td>Default is 50.</td>
+</tr>
+<tr>
+ <td><code>-onion-rotation <position></code></td>
+ <td>Specify onion skin rotation.
+ <td><code><position></code> must be one of the values 0, 1, 2, 3.</td>
+</tr>
+<tr>
+ <td><code>-skin <skinID></code></td>
+ <td>This emulator option is deprecated. </td>
+ <td>Please set skin options using AVDs, rather than by using this emulator
+option. Using this option may yield unexpected and in some cases misleading
+results, since the density with which to render the skin may not be defined.
+AVDs let you associate each skin with a default density and override the default
+as needed. For more information, see <a
+href="{@docRoot}guide/developing/devices/managing-avds.html">Managing Virtual Devices
+with AVD Manager</a>.
+</td>
+</tr>
+<tr>
+ <td><code>-skindir <dir></code></td>
+ <td>This emulator option is deprecated. </td>
+ <td>See comments for <code>-skin</code>, above.</td>
+</tr>
+<tr>
+ <td rowspan="9">Help</td>
+ <td><code>-help</code></td>
+ <td>Print a list of all emulator options.</td>
+ <td> </td>
+</tr>
+<tr>
+ <td><code>-help-all</code></td>
+ <td>Print help for all startup options.</td>
+ <td> </td>
+</tr>
+<tr>
+ <td><code>-help-<option></code></td>
+ <td>Print help for a specific startup option.</td>
+ <td> </td>
+</tr>
+<tr>
+ <td><code>-help-debug-tags</code></td>
+ <td>Print a list of all tags for <code>-debug <tags></code>.</td>
+ <td> </td>
+</tr>
+<tr>
+ <td><code>-help-disk-images</code></td>
+ <td>Print help for using emulator disk images.</td>
+ <td> </td>
+ </tr>
+<tr>
+ <td><code>-help-environment</code></td>
+ <td>Print help for emulator environment variables.</td>
+ <td> </td>s
+</tr><tr>
+ <td><code>-help-keys</code></td>
+ <td>Print the current mapping of keys.</td>
+ <td> </td>
+</tr>
+<tr>
+ <td><code>-help-keyset-file</code></td>
+ <td>Print help for defining a custom key mappings file.</td>
+ <td> </td>
+</tr>
+<tr>
+ <td><code>-help-virtual-device</code></td>
+ <td>Print help for Android Virtual Device usage.</td>
+ <td> </td>
+</tr>
+</table>
diff --git a/docs/html/guide/developing/tools/monkeyrunner_concepts.jd b/docs/html/guide/developing/tools/monkeyrunner_concepts.jd
index 499b610..346a0c6 100644
--- a/docs/html/guide/developing/tools/monkeyrunner_concepts.jd
+++ b/docs/html/guide/developing/tools/monkeyrunner_concepts.jd
@@ -236,7 +236,7 @@
You can generate an API reference for monkeyrunner by running:
</p>
<pre>
-monkeyrunner <format> help.py <outfile>
+monkeyrunner help.py <format> <outfile>
</pre>
<p>
The arguments are:
diff --git a/docs/html/guide/market/expansion-files.jd b/docs/html/guide/market/expansion-files.jd
index 01acb33..36b8f9c 100644
--- a/docs/html/guide/market/expansion-files.jd
+++ b/docs/html/guide/market/expansion-files.jd
@@ -1088,12 +1088,8 @@
<dd>Most applications don't need to use this class. This class defines a {@link
android.content.ContentProvider} that marshals the data from the ZIP files through a content
provider {@link android.net.Uri} in order to provide file access for certain Android APIs that
-expect {@link android.net.Uri} access to media files.
- <p>The sample application available in the
-Apk Expansion package demonstrates a scenario in which this class is useful
-to specify a video with {@link android.widget.VideoView#setVideoURI
-VideoView.setVideoURI()}. See the sample app's class {@code SampleZipfileProvider} for an
-example of how to extend this class to use in your application.</p></dd>
+expect {@link android.net.Uri} access to media files. For example, this is useful if you want to
+play a video with {@link android.widget.VideoView#setVideoURI VideoView.setVideoURI()}.</p></dd>
</dl>
<h4>Reading from a ZIP file</h4>
diff --git a/docs/html/guide/market/licensing/setting-up.jd b/docs/html/guide/market/licensing/setting-up.jd
index 15214d1..41e3bc4 100644
--- a/docs/html/guide/market/licensing/setting-up.jd
+++ b/docs/html/guide/market/licensing/setting-up.jd
@@ -177,12 +177,6 @@
<strong>Google APIs Add-On, API 8 (release 2) or higher</strong> includes the necessary Google
Play services.</p>
-
-<img src="{@docRoot}images/licensing_gapis_8.png" alt=""/>
-<p class="img-caption"><strong>Figure 2.</strong> Google APIs
-Add-On, API 8 (release 2) or higher lets you debug and test your licensing
-implementation in an emulator.</p>
-
<p>To set up an emulator for adding licensing to an application, follow
these steps: </p>
@@ -190,7 +184,7 @@
<li>Launch the Android SDK Manager. </li>
<li>In the <strong>Available Packages</strong> panel, select and download the
SDK component "Google APIs (Google Inc.) - API Level 8" (or higher) from the SDK
-repository, as shown in figure 2.
+repository.
<p>When the download is complete, use the Android SDK Manager to
create a new AVD based on that component, described next.</p></li>
<li>In the <strong>Virtual
@@ -256,11 +250,11 @@
<p>To download the LVL component into your development environment, use the
Android SDK Manager. Launch the Android SDK Manager and then
-select the "Google Market Licensing" component, as shown in figure 3.
+select the "Google Market Licensing" component, as shown in figure 2.
Accept the terms and click <strong>Install Selected</strong> to begin the download. </p>
<img src="{@docRoot}images/licensing_package.png" alt=""/>
-<p class="img-caption"><strong>Figure 3.</strong> The Licensing package contains the LVL and
+<p class="img-caption"><strong>Figure 2.</strong> The Licensing package contains the LVL and
the LVL sample application.</p>
<p>When the download is complete, the Android SDK Manager installs both
@@ -390,7 +384,7 @@
<img src="{@docRoot}images/licensing_add_library.png" alt=""/>
-<p class="img-caption"><strong>Figure 4.</strong> If you are
+<p class="img-caption"><strong>Figure 3.</strong> If you are
working in Eclipse with ADT, you can add the LVL library project to your
application from the application's project properties.</p>
@@ -494,7 +488,7 @@
href="{@docRoot}guide/market/licensing/licensing-reference.html">Licensing Reference</a>.</p>
<img src="{@docRoot}images/licensing_test_response.png" alt=""/>
-<p class="img-caption"><strong>Figure 5.</strong> The Licensing
+<p class="img-caption"><strong>Figure 4.</strong> The Licensing
panel of your account's Edit Profile page, showing the Test Accounts field and the
Test Response menu.</p>
@@ -586,7 +580,7 @@
<h4 id="reg-test-acct">Registering test accounts on the publisher account</h4>
<p>To get started, you need to register each test account in your publisher
-account. As shown in Figure 5, you
+account. As shown in Figure 4, you
register test accounts in the Licensing panel of your publisher account's Edit
Profile page. Simply enter the accounts as a comma-delimited list and click
<strong>Save</strong> to save your profile changes.</p>
diff --git a/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd b/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd
index 465cf54..0880614 100644
--- a/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd
+++ b/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd
@@ -154,7 +154,7 @@
<p>Because the activities in the back stack are never rearranged, if your application allows
users to start a particular activity from more than one activity, a new instance of
-that activity is created and popped onto the stack (rather than bringing any previous instance of
+that activity is created and pushed onto the stack (rather than bringing any previous instance of
the activity to the top). As such, one activity in your application might be instantiated multiple
times (even from different tasks), as shown in figure 3. As such, if the user navigates backward
using the <em>Back</em> button, each instance of the activity is revealed in the order they were
@@ -291,7 +291,7 @@
should associate with a task, then Activity A's request (as defined in the intent) is honored
over Activity B's request (as defined in its manifest).</p>
-<p class="note"><strong>Note:</strong> Some the launch modes available in the manifest
+<p class="note"><strong>Note:</strong> Some launch modes available for the manifest file
are not available as flags for an intent and, likewise, some launch modes available as flags
for an intent cannot be defined in the manifest.</p>
diff --git a/docs/html/guide/topics/manifest/manifest-element.jd b/docs/html/guide/topics/manifest/manifest-element.jd
index 9788945..98968d7 100644
--- a/docs/html/guide/topics/manifest/manifest-element.jd
+++ b/docs/html/guide/topics/manifest/manifest-element.jd
@@ -37,7 +37,7 @@
<dt>description:</dt>
<dd>The root element of the AndroidManifest.xml file. It must
contain an <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element
-and specify {@code xlmns:android} and {@code package} attributes.</dd>
+and specify {@code xmlns:android} and {@code package} attributes.</dd>
<dt>attributes:</dt>
<dd>
diff --git a/docs/html/guide/topics/providers/content-provider-basics.jd b/docs/html/guide/topics/providers/content-provider-basics.jd
index 40b5c3f..de89568 100644
--- a/docs/html/guide/topics/providers/content-provider-basics.jd
+++ b/docs/html/guide/topics/providers/content-provider-basics.jd
@@ -123,7 +123,7 @@
<!-- Intro paragraphs -->
<p>
- A content provider manages access to a central repository of data. The provider and
+ A content provider manages access to a central repository of data. A provider
is part of an Android application, which often provides its own UI for working with
the data. However, content providers are primarily intended to be used by other
applications, which access the provider using a provider client object. Together, providers
@@ -569,7 +569,7 @@
</pre>
<p>
A selection clause that uses <code>?</code> as a replaceable parameter and an array of
- selection arguments array are preferred way to specify a selection, even the provider isn't
+ selection arguments array are preferred way to specify a selection, even if the provider isn't
based on an SQL database.
</p>
<!-- Displaying the results -->
diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd
index 380791a..b33a097 100644
--- a/docs/html/guide/topics/resources/providing-resources.jd
+++ b/docs/html/guide/topics/resources/providing-resources.jd
@@ -287,9 +287,8 @@
from the SIM card in the device. For example, <code>mcc310</code> is U.S. on any carrier,
<code>mcc310-mnc004</code> is U.S. on Verizon, and <code>mcc208-mnc00</code> is France on
Orange.</p>
- <p>If the device uses a radio connection (GSM phone), the MCC comes
- from the SIM, and the MNC comes from the network to which the
- device is connected.</p>
+ <p>If the device uses a radio connection (GSM phone), the MCC and MNC values come
+ from the SIM card.</p>
<p>You can also use the MCC alone (for example, to include country-specific legal
resources in your application). If you need to specify based on the language only, then use the
<em>language and region</em> qualifier instead (discussed next). If you decide to use the MCC and
diff --git a/docs/html/guide/topics/resources/string-resource.jd b/docs/html/guide/topics/resources/string-resource.jd
index ecd2d48..5f5484e 100644
--- a/docs/html/guide/topics/resources/string-resource.jd
+++ b/docs/html/guide/topics/resources/string-resource.jd
@@ -358,11 +358,14 @@
<pre>
int count = getNumberOfsongsAvailable();
Resources res = {@link android.content.Context#getResources()};
-String songsFound = res.{@link android.content.res.Resources#getQuantityString(int,int)
-getQuantityString}(R.plurals.numberOfSongsAvailable, count, count);
+String songsFound = res.<a
+href="{@docRoot}reference/android/content/res/Resources.html#getQuantityString(int, int, java.lang.Object...)"
+>getQuantityString</a>(R.plurals.numberOfSongsAvailable, count, count);
</pre>
-<p>When using the {@link android.content.res.Resources#getQuantityString(int,int)
-getQuantityString()} method, you need to pass the {@code count} twice if your string includes
+
+<p>When using the <a
+href="{@docRoot}reference/android/content/res/Resources.html#getQuantityString(int, int, java.lang.Object...)">{@code
+getQuantityString()}</a> method, you need to pass the {@code count} twice if your string includes
<a href="#FormattingAndStyling">string formatting</a> with a number. For example, for the string
{@code %d songs found}, the first {@code count} parameter selects the appropriate plural string and
the second {@code count} parameter is inserted into the {@code %d} placeholder. If your plural
diff --git a/docs/html/guide/topics/sensors/index.jd b/docs/html/guide/topics/sensors/index.jd
index 75a1716..43903dc 100644
--- a/docs/html/guide/topics/sensors/index.jd
+++ b/docs/html/guide/topics/sensors/index.jd
@@ -43,7 +43,7 @@
application might use the geomagnetic field sensor and accelerometer to report a compass
bearing.</p>
-<p>The Android platform supports four broad categories of sensors:</p>
+<p>The Android platform supports three broad categories of sensors:</p>
<ul>
<li>Motion sensors
diff --git a/docs/html/guide/topics/ui/layout-objects.jd b/docs/html/guide/topics/ui/layout-objects.jd
index 8b2792d..e251fe9 100644
--- a/docs/html/guide/topics/ui/layout-objects.jd
+++ b/docs/html/guide/topics/ui/layout-objects.jd
@@ -163,7 +163,7 @@
<td>
<pre>
<?xml version="1.0" encoding="utf-8"?>
-<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android
+<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:background="@drawable/blue"
diff --git a/docs/html/guide/topics/wireless/wifip2p.jd b/docs/html/guide/topics/wireless/wifip2p.jd
index 4dd3d26..ec8e71e 100644
--- a/docs/html/guide/topics/wireless/wifip2p.jd
+++ b/docs/html/guide/topics/wireless/wifip2p.jd
@@ -333,7 +333,7 @@
...
mManager = (WifiP2pManager) getSystemService(Context.WIFI_P2P_SERVICE);
mChannel = mManager.initialize(this, getMainLooper(), null);
- Receiver = new WiFiDirectBroadcastReceiver(manager, channel, this);
+ mReceiver = new WiFiDirectBroadcastReceiver(manager, channel, this);
...
}
</pre>
@@ -364,13 +364,13 @@
@Override
protected void onResume() {
super.onResume();
- registerReceiver(receiver, intentFilter);
+ registerReceiver(mReceiver, mIntentFilter);
}
/* unregister the broadcast receiver */
@Override
protected void onPause() {
super.onPause();
- unregisterReceiver(receiver);
+ unregisterReceiver(mReceiver);
}
</pre>
diff --git a/docs/html/images/avd-manager.png b/docs/html/images/avd-manager.png
index c33d8a8..fd373f9 100644
--- a/docs/html/images/avd-manager.png
+++ b/docs/html/images/avd-manager.png
Binary files differ
diff --git a/docs/html/images/billing_package.png b/docs/html/images/billing_package.png
index 951e117..6e673c8 100644
--- a/docs/html/images/billing_package.png
+++ b/docs/html/images/billing_package.png
Binary files differ
diff --git a/docs/html/images/developing/avd-dialog.png b/docs/html/images/developing/avd-dialog.png
index d0e2eec..9dfbd68 100644
--- a/docs/html/images/developing/avd-dialog.png
+++ b/docs/html/images/developing/avd-dialog.png
Binary files differ
diff --git a/docs/html/images/developing/sdk-usb-driver.png b/docs/html/images/developing/sdk-usb-driver.png
index 207d3d7..3489991 100644
--- a/docs/html/images/developing/sdk-usb-driver.png
+++ b/docs/html/images/developing/sdk-usb-driver.png
Binary files differ
diff --git a/docs/html/images/emulator-wvga800l.png b/docs/html/images/emulator-wvga800l.png
index a214033..c92c1b9 100644
--- a/docs/html/images/emulator-wvga800l.png
+++ b/docs/html/images/emulator-wvga800l.png
Binary files differ
diff --git a/docs/html/images/licensing_add_library.png b/docs/html/images/licensing_add_library.png
index 3bbe6d5..257a628 100644
--- a/docs/html/images/licensing_add_library.png
+++ b/docs/html/images/licensing_add_library.png
Binary files differ
diff --git a/docs/html/images/licensing_gapis_8.png b/docs/html/images/licensing_gapis_8.png
deleted file mode 100644
index 480d989..0000000
--- a/docs/html/images/licensing_gapis_8.png
+++ /dev/null
Binary files differ
diff --git a/docs/html/images/licensing_package.png b/docs/html/images/licensing_package.png
index eb2c5cf..dc34473 100644
--- a/docs/html/images/licensing_package.png
+++ b/docs/html/images/licensing_package.png
Binary files differ
diff --git a/docs/html/images/sdk_manager_packages.png b/docs/html/images/sdk_manager_packages.png
index 19a7cb9..a0e8108 100644
--- a/docs/html/images/sdk_manager_packages.png
+++ b/docs/html/images/sdk_manager_packages.png
Binary files differ
diff --git a/docs/html/resources/resources_toc.cs b/docs/html/resources/resources_toc.cs
index 8483037..e1a5e0f 100644
--- a/docs/html/resources/resources_toc.cs
+++ b/docs/html/resources/resources_toc.cs
@@ -99,6 +99,27 @@
</li>
<li class="toggle-list">
+ <div><a href="<?cs var:toroot ?>training/search/index.html">
+ <span class="en">Adding Search Functionality</span>
+ </a> <span class="new">new!</span>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>training/search/setup.html">
+ <span class="en">Setting up the Search Interface</span>
+ </a>
+ </li>
+ <li><a href="<?cs var:toroot ?>training/search/search.html">
+ <span class="en">Storing and Searching for Data</span>
+ </a>
+ </li>
+ <li><a href="<?cs var:toroot ?>training/search/backward-compat.html">
+ <span class="en">Remaining Backward Compatible</span>
+ </a>
+ </li>
+ </ul>
+ </li>
+
+ <li class="toggle-list">
<div><a href="<?cs var:toroot ?>training/id-auth/index.html">
<span class="en">Remembering Users</span>
</a></div>
diff --git a/docs/html/resources/tutorials/views/hello-webview.jd b/docs/html/resources/tutorials/views/hello-webview.jd
index 2d07647..f6a6a71 100644
--- a/docs/html/resources/tutorials/views/hello-webview.jd
+++ b/docs/html/resources/tutorials/views/hello-webview.jd
@@ -52,7 +52,7 @@
<li>While you're in the manifest, give some more space for web pages by removing the title
bar, with the "NoTitleBar" theme:
<pre>
-<activity android:name=".HelloGoogleMaps" android:label="@string/app_name"
+<activity android:name=".HelloWebView" android:label="@string/app_name"
<strong>android:theme="@android:style/Theme.NoTitleBar"</strong>>
</pre>
</li>
diff --git a/docs/html/sdk/android-4.0-highlights.jd b/docs/html/sdk/android-4.0-highlights.jd
index 50e9a14..98f467d 100644
--- a/docs/html/sdk/android-4.0-highlights.jd
+++ b/docs/html/sdk/android-4.0-highlights.jd
@@ -343,7 +343,7 @@
<p>The Camera app includes many new features that let users capture special moments
with great photos and videos. After capturing images, they can edit and share
-them easily with friemds. </p>
+them easily with friends. </p>
<p>When taking pictures, <strong>continuous focus</strong>, <strong>zero shutter
lag exposure</strong>, and decreased shot-to-shot speed help capture clear,
diff --git a/docs/html/sdk/win-usb.jd b/docs/html/sdk/win-usb.jd
index 2bd031e..6869d74 100644
--- a/docs/html/sdk/win-usb.jd
+++ b/docs/html/sdk/win-usb.jd
@@ -147,7 +147,7 @@
<h2 id="WinUsbDriver">Downloading the Google USB Driver</h2>
-<div class="figure" style="width:498px;margin:0">
+<div class="figure" style="width:536px;margin:0">
<img src="{@docRoot}images/developing/sdk-usb-driver.png" alt="" />
<p class="img-caption"><strong>Figure 1.</strong> The SDK and AVD Manager
with the Google USB Driver selected.</p>
diff --git a/docs/html/training/monitoring-device-state/docking-monitoring.jd b/docs/html/training/monitoring-device-state/docking-monitoring.jd
index 392ce30..82d655e 100644
--- a/docs/html/training/monitoring-device-state/docking-monitoring.jd
+++ b/docs/html/training/monitoring-device-state/docking-monitoring.jd
@@ -15,7 +15,7 @@
<h2>This lesson teaches you to</h2>
<ol>
- <li><a href="#CurrentDockState">Request the Audio Focus</a></li>
+ <li><a href="#CurrentDockState">Determine the Current Docking State</a></li>
<li><a href="#DockType">Determine the Current Dock Type</a></li>
<li><a href="#MonitorDockState">Monitor for Changes in the Dock State or Type</a></li>
</ol>
diff --git a/docs/html/training/search/backward-compat.jd b/docs/html/training/search/backward-compat.jd
new file mode 100644
index 0000000..0894fa9
--- /dev/null
+++ b/docs/html/training/search/backward-compat.jd
@@ -0,0 +1,87 @@
+page.title=Remaining Backward Compatible
+trainingnavtop=true
+previous.title=Storing and Searching for Data
+previous.link=search.html
+
+@jd:body
+
+ <div id="tb-wrapper">
+ <div id="tb">
+ <h2>This lesson teaches you to</h2>
+
+ <ul>
+ <li><a href="{@docRoot}training/search/backward-compat.html#set-sdk">Set Minimum
+ and Target API levels</a></li>
+
+ <li><a href="{@docRoot}training/search/backward-compat.html#provide-sd">Provide the Search
+ Dialog for Older Devices</a></li>
+
+ <li><a href="{@docRoot}training/search/backward-compat.html#check-ver">Check the Android Build
+ Version at Runtime</a></li>
+ </ul>
+ </div>
+ </div>
+
+ <p>The {@link android.widget.SearchView} and action bar are only available on Android 3.0 and
+ later. To support older platforms, you can fall back to the search dialog. The search dialog is a
+ system provided UI that overlays on top of your application when invoked.</p>
+
+ <h2 id="set-sdk">Set Minimum and Target API levels</h2>
+
+ <p>To setup the search dialog, first declare in your manifest that you want to support older
+ devices, but want to target Android 3.0 or later versions. When you do this, your application
+ automatically uses the action bar on Android 3.0 or later and uses the traditional menu system on
+ older devices:</p>
+ <pre>
+<uses-sdk android:minSdkVersion="7" android:targetSdkVersion="15" />
+
+<application>
+...
+</pre>
+
+ <h2 id="provide-sd">Provide the Search Dialog for Older Devices</h2>
+
+ <p>To invoke the search dialog on older devices, call {@link
+ android.app.Activity#onSearchRequested onSearchRequested()} whenever a user selects the search
+ menu item from the options menu. Because Android 3.0 and higher devices show the
+ {@link android.widget.SearchView} in the action bar (as demonstrated in the first lesson), only versions
+ older than 3.0 call {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} when the
+ user selects the search menu item.
+ </p>
+ <pre>
+@Override
+public boolean onOptionsItemSelected(MenuItem item) {
+ switch (item.getItemId()) {
+ case R.id.search:
+ onSearchRequested();
+ return true;
+ default:
+ return false;
+ }
+}
+</pre>
+
+ <h2 id="check-ver">Check the Android Build Version at Runtime</h2>
+
+ <p>At runtime, check the device version to make sure an unsupported use of {@link
+ android.widget.SearchView} does not occur on older devices. In our example code, this happens in
+ the {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method:</p>
+ <pre>
+@Override
+public boolean onCreateOptionsMenu(Menu menu) {
+
+ MenuInflater inflater = getMenuInflater();
+ inflater.inflate(R.menu.options_menu, menu);
+
+ if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) {
+ SearchManager searchManager =
+ (SearchManager) getSystemService(Context.SEARCH_SERVICE);
+ SearchView searchView =
+ (SearchView) menu.findItem(R.id.search).getActionView();
+ searchView.setSearchableInfo(
+ searchManager.getSearchableInfo(getComponentName()));
+ searchView.setIconifiedByDefault(false);
+ }
+ return true;
+}
+</pre>
diff --git a/docs/html/training/search/index.jd b/docs/html/training/search/index.jd
new file mode 100644
index 0000000..bfd1618
--- /dev/null
+++ b/docs/html/training/search/index.jd
@@ -0,0 +1,53 @@
+page.title=Adding Search Functionality
+trainingnavtop=true
+startpage=true
+next.title=Setting Up the Search Interface
+next.link=setup.html
+
+@jd:body
+
+ <div id="tb-wrapper">
+ <div id="tb">
+ <h2>Dependencies and prerequisites</h2>
+
+ <ul>
+ <li>Android 3.0 or later (with some support for Android 2.1)</li>
+
+ <li>Experience building an Android <a href="{@docRoot}guide/topics/ui/index.html">User
+ Interface</a></li>
+ </ul>
+
+ <h2>You should also read</h2>
+
+ <ul>
+ <li><a href="{@docRoot}guide/topics/search/index.html">Search</a></li>
+
+ <li><a href="{@docRoot}resources/samples/SearchableDictionary/index.html">Searchable
+ Dictionary Sample App</a></li>
+ </ul>
+ </div>
+ </div>
+
+ <p>Android's built-in search features offer apps an easy way to provide a
+ consistent search experience for all users. There are two ways to implement search in your app
+ depending on the version of Android that is running on the device. This class covers how to add
+ search with {@link android.widget.SearchView}, which was introduced in Android 3.0, while
+ maintaining backward compatibility with older versions of Android by using the default search
+ dialog provided by the system.</p>
+
+ <h2>Lessons</h2>
+
+ <dl>
+ <dt><b><a href="setup.html">Setting Up the Search Interface</a></b></dt>
+
+ <dd>Learn how to add a search interface to your app and how to configure an activity to handle
+ search queries.</dd>
+
+ <dt><b><a href="search.html">Storing and Searching for Data</a></b></dt>
+
+ <dd>Learn a simple way to store and search for data in a SQLite virtual database table.</dd>
+
+ <dt><b><a href="backward-compat.html">Remaining Backward Compatible</a></b></dt>
+
+ <dd>Learn how to keep search features backward compatible with older devices by using.</dd>
+ </dl>
\ No newline at end of file
diff --git a/docs/html/training/search/search.jd b/docs/html/training/search/search.jd
new file mode 100644
index 0000000..17e7640
--- /dev/null
+++ b/docs/html/training/search/search.jd
@@ -0,0 +1,217 @@
+page.title=Storing and Searching for Data
+trainingnavtop=true
+previous.title=Setting Up the Search Interface
+previous.link=setup.html
+next.title=Remaining Backward Compatible
+next.link=backward-compat.html
+
+@jd:body
+
+ <div id="tb-wrapper">
+ <div id="tb">
+ <h2>This lesson teaches you to</h2>
+
+ <ul>
+ <li><a href="{@docRoot}training/search/search.html#create">Create the Virtual
+ Table</a></li>
+
+ <li><a href="{@docRoot}training/search/search.html#populate">Populate the Virtual
+ Table</a></li>
+
+ <li><a href="{@docRoot}training/search/search.html#search">Search for the Query</a></li>
+ </ul>
+ </div>
+ </div>
+
+ <p>There are many ways to store your data, such as in an online database, in a local SQLite
+ database, or even in a text file. It is up to you to decide what is the best solution for your
+ application. This lesson shows you how to create a SQLite virtual table that can provide robust
+ full-text searching. The table is populated with data from a text file that contains a word and
+ definition pair on each line in the file.</p>
+
+ <h2 id="create">Create the Virtual Table</h2>
+
+ <p>A virtual table behaves similarly to a SQLite table, but reads and writes to an object in
+ memory via callbacks, instead of to a database file. To create a virtual table, create a class
+ for the table:</p>
+ <pre>
+public class DatabaseTable {
+ private final DatabaseOpenHelper mDatabaseOpenHelper;
+
+ public DatabaseTable(Context context) {
+ mDatabaseOpenHelper = new DatabaseOpenHelper(context);
+ }
+}
+</pre>
+
+ <p>Create an inner class in <code>DatabaseTable</code> that extends {@link
+ android.database.sqlite.SQLiteOpenHelper}. The {@link android.database.sqlite.SQLiteOpenHelper} class
+ defines abstract methods that you must override so that your database table can be created and
+ upgraded when necessary. For example, here is some code that declares a database table that will
+ contain words for a dictionary app:</p>
+ <pre>
+public class DatabaseTable {
+
+ private static final String TAG = "DictionaryDatabase";
+
+ //The columns we'll include in the dictionary table
+ public static final String COL_WORD = "WORD";
+ public static final String COL_DEFINITION = "DEFINITION";
+
+ private static final String DATABASE_NAME = "DICTIONARY";
+ private static final String FTS_VIRTUAL_TABLE = "FTS";
+ private static final int DATABASE_VERSION = 1;
+
+ private final DatabaseOpenHelper mDatabaseOpenHelper;
+
+ public DatabaseTable(Context context) {
+ mDatabaseOpenHelper = new DatabaseOpenHelper(context);
+ }
+
+ private static class DatabaseOpenHelper extends SQLiteOpenHelper {
+
+ private final Context mHelperContext;
+ private SQLiteDatabase mDatabase;
+
+ private static final String FTS_TABLE_CREATE =
+ "CREATE VIRTUAL TABLE " + FTS_VIRTUAL_TABLE +
+ " USING fts3 (" +
+ COL_WORD + ", " +
+ COL_DEFINITION + ")";
+
+ DatabaseOpenHelper(Context context) {
+ super(context, DATABASE_NAME, null, DATABASE_VERSION);
+ mHelperContext = context;
+ }
+
+ @Override
+ public void onCreate(SQLiteDatabase db) {
+ mDatabase = db;
+ mDatabase.execSQL(FTS_TABLE_CREATE);
+ }
+
+ @Override
+ public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
+ Log.w(TAG, "Upgrading database from version " + oldVersion + " to "
+ + newVersion + ", which will destroy all old data");
+ db.execSQL("DROP TABLE IF EXISTS " + FTS_VIRTUAL_TABLE);
+ onCreate(db);
+ }
+ }
+}
+</pre>
+
+ <h2 id="populate">Populate the Virtual Table</h2>
+
+ <p>The table now needs data to store. The following code shows you how to read a text file
+ (located in <code>res/raw/definitions.txt</code>) that contains words and their definitions, how
+ to parse that file, and how to insert each line of that file as a row in the virtual table. This
+ is all done in another thread to prevent the UI from locking. Add the following code to your
+ <code>DatabaseOpenHelper</code> inner class.</p>
+
+ <p class="note"><strong>Tip:</strong> You also might want to set up a callback to notify your UI
+ activity of this thread's completion.</p>
+ <pre>
+private void loadDictionary() {
+ new Thread(new Runnable() {
+ public void run() {
+ try {
+ loadWords();
+ } catch (IOException e) {
+ throw new RuntimeException(e);
+ }
+ }
+ }).start();
+ }
+
+private void loadWords() throws IOException {
+ final Resources resources = mHelperContext.getResources();
+ InputStream inputStream = resources.openRawResource(R.raw.definitions);
+ BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
+
+ try {
+ String line;
+ while ((line = reader.readLine()) != null) {
+ String[] strings = TextUtils.split(line, "-");
+ if (strings.length < 2) continue;
+ long id = addWord(strings[0].trim(), strings[1].trim());
+ if (id < 0) {
+ Log.e(TAG, "unable to add word: " + strings[0].trim());
+ }
+ }
+ } finally {
+ reader.close();
+ }
+}
+
+public long addWord(String word, String definition) {
+ ContentValues initialValues = new ContentValues();
+ initialValues.put(COL_WORD, word);
+ initialValues.put(COL_DEFINITION, definition);
+
+ return mDatabase.insert(FTS_VIRTUAL_TABLE, null, initialValues);
+}
+</pre>
+
+ <p>Call the <code>loadDictionary()</code> method wherever appropriate to populate the table. A
+ good place would be in the {@link android.database.sqlite.SQLiteOpenHelper#onCreate onCreate()}
+ method of the <code>DatabaseOpenHelper</code> class, right after you create the table:</p>
+ <pre>
+@Override
+public void onCreate(SQLiteDatabase db) {
+ mDatabase = db;
+ mDatabase.execSQL(FTS_TABLE_CREATE);
+ loadDictionary();
+}
+</pre>
+
+ <h2 id="search">Search for the Query</h2>
+
+ <p>When you have the virtual table created and populated, use the query supplied by your {@link
+ android.widget.SearchView} to search the data. Add the following methods to the
+ <code>DatabaseTable</code> class to build a SQL statement that searches for the query:</p>
+ <pre>
+public Cursor getWordMatches(String query, String[] columns) {
+ String selection = COL_WORD + " MATCH ?";
+ String[] selectionArgs = new String[] {query+"*"};
+
+ return query(selection, selectionArgs, columns);
+}
+
+private Cursor query(String selection, String[] selectionArgs, String[] columns) {
+ SQLiteQueryBuilder builder = new SQLiteQueryBuilder();
+ builder.setTables(FTS_VIRTUAL_TABLE);
+
+ Cursor cursor = builder.query(mDatabaseOpenHelper.getReadableDatabase(),
+ columns, selection, selectionArgs, null, null, null);
+
+ if (cursor == null) {
+ return null;
+ } else if (!cursor.moveToFirst()) {
+ cursor.close();
+ return null;
+ }
+ return cursor;
+}
+</pre>
+
+ <p>Search for a query by calling <code>getWordMatches()</code>. Any matching results are returned
+ in a {@link android.database.Cursor} that you can iterate through or use to build a {@link android.widget.ListView}.
+ This example calls <code>getWordMatches()</code> in the <code>handleIntent()</code> method of the searchable
+ activity. Remember that the searchable activity receives the query inside of the {@link
+ android.content.Intent#ACTION_SEARCH} intent as an extra, because of the intent filter that you
+ previously created:</p>
+ <pre>
+DatabaseTable db = new DatabaseTable(this);
+
+...
+
+private void handleIntent(Intent intent) {
+
+ if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
+ String query = intent.getStringExtra(SearchManager.QUERY);
+ Cursor c = db.getWordMatches(query, null);
+ //process Cursor and display results
+ }
+}
+</pre>
\ No newline at end of file
diff --git a/docs/html/training/search/setup.jd b/docs/html/training/search/setup.jd
new file mode 100644
index 0000000..044e422
--- /dev/null
+++ b/docs/html/training/search/setup.jd
@@ -0,0 +1,197 @@
+page.title=Setting Up the Search Interface
+trainingnavtop=true
+next.title=Storing and Searching for Data
+next.link=search.html
+
+@jd:body
+
+ <div id="tb-wrapper">
+ <div id="tb">
+ <h2>This lesson teaches you to</h2>
+
+ <ul>
+ <li><a href="{@docRoot}training/search/setup.html#add-sv">Add the Search View to the Action
+ Bar</a></li>
+
+ <li><a href="{@docRoot}training/search/setup.html#create-sc">Create a Searchable
+ Configuration</a></li>
+
+ <li><a href="{@docRoot}training/search/setup.html#create-sa">Create a Searchable
+ Activity</a></li>
+ </ul>
+
+ <h2>You should also read:</h2>
+
+ <ul>
+ <li><a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a></li>
+ </ul>
+ </div>
+ </div>
+
+ <p>Beginning in Android 3.0, using the {@link android.widget.SearchView} widget as an item in
+ the action bar is the preferred way to provide search in your app. Like with all items in
+ the action bar, you can define the {@link android.widget.SearchView} to show at all times, only
+ when there is room, or as a collapsible action, which displays the {@link
+ android.widget.SearchView} as an icon initially, then takes up the entire action bar as a search
+ field when the user clicks the icon.</p>
+
+ <p class="note"><strong>Note:</strong> Later in this class, you will learn how to make your
+ app compatible down to Android 2.1 (API level 7) for devices that do not support
+ {@link android.widget.SearchView}.</p>
+
+ <h2 id="add-sv">Add the Search View to the Action Bar</h2>
+
+ <p>To add a {@link android.widget.SearchView} widget to the action bar, create a file named
+ <code>res/menu/options_menu.xml</code> in your project and add the following code to the file.
+ This code defines how to create the search item, such as the icon to use and the title of the
+ item. The <code>collapseActionView</code> attribute allows your {@link android.widget.SearchView}
+ to expand to take up the whole action bar and collapse back down into a
+ normal action bar item when not in use. Because of the limited action bar space on handset devices,
+ using the <code>collapsibleActionView</code> attribute is recommended to provide a better
+ user experience.</p>
+ <pre>
+<?xml version="1.0" encoding="utf-8"?>
+<menu xmlns:android="http://schemas.android.com/apk/res/android">
+ <item android:id="@+id/search"
+ android:title="@string/search_title"
+ android:icon="@drawable/ic_search"
+ android:showAsAction="collapseActionView|ifRoom"
+ android:actionViewClass="android.widget.SearchView" />
+</menu>
+</pre>
+
+ <p class="note"><strong>Note:</strong> If you already have an existing XML file for your menu
+ items, you can add the <code><item></code> element to that file instead.</p>
+
+ <p>To display the {@link android.widget.SearchView} in the action bar, inflate the XML menu
+ resource (<code>res/menu/options_menu.xml</code>) in the {@link
+ android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method of your activity:</p>
+ <pre>
+@Override
+public boolean onCreateOptionsMenu(Menu menu) {
+ MenuInflater inflater = getMenuInflater();
+ inflater.inflate(R.menu.options_menu, menu);
+
+ return true;
+}
+</pre>
+
+ <p>If you run your app now, the {@link android.widget.SearchView} appears in your app's action
+ bar, but it isn't functional. You now need to define <em>how</em> the {@link
+ android.widget.SearchView} behaves.</p>
+
+ <h2 id="create-sc">Create a Searchable Configuration</h2>
+
+ <p>A <a href="http://developer.android.com/guide/topics/search/searchable-config.html">searchable
+ configuration</a> defines how the {@link android.widget.SearchView} behaves and is defined in a
+ <code>res/xml/searchable.xml</code> file. At a minimum, a searchable configuration must contain
+ an <code>android:label</code> attribute that has the same value as the
+ <code>android:label</code> attribute of the <a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a> or
+ <a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a> element in your Android manifest.
+ However, we also recommend adding an <code>android:hint</code> attribute to give the user an idea of what to enter into the search
+ box:</p>
+ <pre>
+<?xml version="1.0" encoding="utf-8"?>
+
+<searchable xmlns:android="http://schemas.android.com/apk/res/android"
+ android:label="@string/app_name"
+ android:hint="@string/search_hint" />
+</pre>
+
+ <p>In your application's manifest file, declare a <a href="{@docRoot}guide/topics/manifest/meta-data-element.html">
+ <code><meta-data></code></a> element that points to the <code>res/xml/searchable.xml</code> file,
+ so that your application knows where to find it. Declare the element in an <code><activity></code>
+ that you want to display the {@link android.widget.SearchView} in:</p>
+ <pre>
+<activity ... >
+ ...
+ <meta-data android:name="android.app.searchable"
+ android:resource="@xml/searchable" />
+
+</activity>
+</pre>
+
+ <p>In the {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method that you
+ created before, associate the searchable configuration with the {@link android.widget.SearchView}
+ by calling {@link android.widget.SearchView#setSearchableInfo}:</p>
+ <pre>
+@Override
+public boolean onCreateOptionsMenu(Menu menu) {
+ MenuInflater inflater = getMenuInflater();
+ inflater.inflate(R.menu.options_menu, menu);
+
+ // Associate searchable configuration with the SearchView
+ SearchManager searchManager =
+ (SearchManager) getSystemService(Context.SEARCH_SERVICE);
+ SearchView searchView =
+ (SearchView) menu.findItem(R.id.search).getActionView();
+ searchView.setSearchableInfo(
+ searchManager.getSearchableInfo(getComponentName()));
+
+ return true;
+}
+</pre>
+
+ <p>The call to {@link android.app.SearchManager#getSearchableInfo getSearchableInfo()} obtains a
+ {@link android.app.SearchableInfo} object that is created from the searchable configuration XML
+ file. When the searchable configuration is correctly associated with your {@link
+ android.widget.SearchView}, the {@link android.widget.SearchView} starts an activity with the
+ {@link android.content.Intent#ACTION_SEARCH} intent when a user submits a query. You now need an
+ activity that can filter for this intent and handle the search query.</p>
+
+ <h2 id="create-sa">Create a Searchable Activity</h2>
+
+ <p>A {@link android.widget.SearchView} tries to start an activity with the {@link
+ android.content.Intent#ACTION_SEARCH} when a user submits a search query. A searchable activity
+ filters for the {@link android.content.Intent#ACTION_SEARCH} intent and searches for the query in
+ some sort of data set. To create a searchable activity, declare an activity of your choice to
+ filter for the {@link android.content.Intent#ACTION_SEARCH} intent:</p>
+ <pre>
+<activity android:name=".SearchResultsActivity" ... >
+ ...
+ <intent-filter>
+ <action android:name="android.intent.action.SEARCH" />
+ </intent-filter>
+ ...
+</activity>
+</pre>
+
+ <p>In your searchable activity, handle the {@link android.content.Intent#ACTION_SEARCH} intent by
+ checking for it in your {@link android.app.Activity#onCreate onCreate()} method.</p>
+
+ <p class="note"><strong>Note:</strong> If your searchable activity launches in single top mode
+ (<code>android:launchMode="singleTop"</code>), also handle the {@link
+ android.content.Intent#ACTION_SEARCH} intent in the {@link android.app.Activity#onNewIntent
+ onNewIntent()} method. In single top mode, only one instance of your activity is created and
+ subsequent calls to start your activity do not create a new activity on the
+ stack. This launch mode is useful so users can perform searches from the same activity
+ without creating a new activity instance every time.</p>
+ <pre>
+public class SearchResultsActivity extends Activity {
+
+ @Override
+ public void onCreate(Bundle savedInstanceState) {
+ ...
+ handleIntent(getIntent());
+ }
+
+ @Override
+ protected void onNewIntent(Intent intent) {
+ ...
+ handleIntent(intent);
+ }
+
+ private void handleIntent(Intent intent) {
+
+ if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
+ String query = intent.getStringExtra(SearchManager.QUERY);
+ //use the query to search your data somehow
+ }
+ }
+ ...
+}
+</pre>
+
+ <p>If you run your app now, the {@link android.widget.SearchView} can accept the user's query and
+ start your searchable activity with the {@link android.content.Intent#ACTION_SEARCH} intent. It
+ is now up to you to figure out how to store and search your data given a query.</p>
\ No newline at end of file
