diff options
Diffstat (limited to 'docs/html/guide/topics')
135 files changed, 8516 insertions, 10376 deletions
diff --git a/docs/html/guide/topics/admin/index.jd b/docs/html/guide/topics/admin/index.jd new file mode 100644 index 0000000..b2a896f --- /dev/null +++ b/docs/html/guide/topics/admin/index.jd @@ -0,0 +1,22 @@ +page.title=Administration +page.landing=true +page.landing.intro=If you are an enterprise administrator, you can take advantage of APIs and system capabilities to manage Android devices and control access. +page.landing.image= + +@jd:body + +<div class="landing-docs"> + + <div class="col-12"> + <h3>Blog Articles</h3> + <a +href="http://android-developers.blogspot.com/2012/03/unifying-key-store-access-in-ics.html"> + <h4>Unifying Key Store Access in ICS</h4> + <p>Android 4.0 (ICS) comes with a number of enhancements that make it easier for people to +bring their personal Android devices to work. In this post, we’re going to have a look at the key +store functionality.</p> + </a> + </div> + + +</div>
\ No newline at end of file diff --git a/docs/html/guide/topics/admin/keychain.jd b/docs/html/guide/topics/admin/keychain.jd new file mode 100644 index 0000000..2ea2408 --- /dev/null +++ b/docs/html/guide/topics/admin/keychain.jd @@ -0,0 +1,4 @@ +page.title=Text and Input +@jd:body + +<p>Add contnet here</p> diff --git a/docs/html/guide/topics/appwidgets/index.jd b/docs/html/guide/topics/appwidgets/index.jd index ba7b67c..a46f9a7 100644 --- a/docs/html/guide/topics/appwidgets/index.jd +++ b/docs/html/guide/topics/appwidgets/index.jd @@ -295,7 +295,7 @@ Guidelines</a>.</p> <p>Creating the App Widget layout is simple if you're familiar with <a -href="{@docRoot}guide/topics/ui/declaring-layout.html">XML Layouts</a>. +href="{@docRoot}guide/topics/ui/declaring-layout.html">Layouts</a>. However, you must be aware that App Widget layouts are based on {@link android.widget.RemoteViews}, which do not support every kind of layout or view widget.</p> @@ -516,7 +516,7 @@ consider starting a {@link android.app.Service} in the {@link android.appwidget.AppWidgetProvider#onUpdate(Context,AppWidgetManager,int[]) onUpdate()} method. From within the Service, you can perform your own updates to the App Widget without worrying about the AppWidgetProvider closing down due -to an <a href="{@docRoot}guide/practices/design/responsiveness.html">Application +to an <a href="{@docRoot}guide/practices/responsiveness.html">Application Not Responding</a> (ANR) error. See the <a href="http://code.google.com/p/wiktionary-android/source/browse/trunk/Wiktionary/src/com/example/android/wiktionary/WordWidget.java">Wiktionary sample's AppWidgetProvider</a> for an example of an App Widget running a {@link android.app.Service}.</p> diff --git a/docs/html/guide/topics/wireless/bluetooth.jd b/docs/html/guide/topics/connectivity/bluetooth.jd index 0567799..832b850 100644 --- a/docs/html/guide/topics/wireless/bluetooth.jd +++ b/docs/html/guide/topics/connectivity/bluetooth.jd @@ -912,7 +912,7 @@ profiles:</p> Bluetooth headsets to be used with mobile phones. Android provides the {@link android.bluetooth.BluetoothHeadset} class, which is a proxy for controlling the Bluetooth Headset Service via interprocess communication (<a -href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#IPC">IPC</a +href="{@docRoot}guide/components/processes-and-threads.html#IPC">IPC</a >). This includes both Bluetooth Headset and Hands-Free (v1.5) profiles. The {@link android.bluetooth.BluetoothHeadset} class includes support for AT commands. For more discussion of this topic, see <a href="#AT-Commands">Vendor-specific AT commands</a></li> @@ -940,7 +940,7 @@ HDP, see <a href="#HDP">Health Device Profile</a>.</li> <ol> <li>Get the default adapter, as described in - <a href="{@docRoot}guide/topics/wireless/bluetooth.html#SettingUp">Setting Up + <a href="{@docRoot}guide/topics/connectivity/bluetooth.html#SettingUp">Setting Up Bluetooth</a>.</li> <li>Use {@link diff --git a/docs/html/guide/topics/connectivity/index.jd b/docs/html/guide/topics/connectivity/index.jd new file mode 100644 index 0000000..322518e --- /dev/null +++ b/docs/html/guide/topics/connectivity/index.jd @@ -0,0 +1,42 @@ +page.title=Connectivity +page.landing=true +page.landing.intro=Android provides rich APIs to let your app connect and interact with other devices over Bluetooth, NFC, Wi-Fi Direct, USB, and SIP, in addition to standard network connections. +page.landing.image=images/develop/connectivity.png + +@jd:body + +<div class="landing-docs"> + + <div class="col-6"> + <h3>Blog Articles</h3> + + <a href="http://android-developers.blogspot.com/2011/09/androids-http-clients.html"> + <h4>Android’s HTTP Clients</h4> + <p>Most network-connected Android apps will use HTTP to send and receive data. Android +includes two HTTP clients: HttpURLConnection and Apache HTTP Client. Both support HTTPS, streaming +uploads and downloads, configurable timeouts, IPv6 and connection pooling.</p> + </a> + + </div> + + <div class="col-6"> + <h3>Training</h3> + + <a href="http://developer.android.com/training/efficient-downloads/index.html"> + <h4>Transferring Data Without Draining the Battery</h4> + <p>This class demonstrates the best practices for scheduling and executing downloads using +techniques such as caching, polling, and prefetching. You will learn how the power-use profile of +the wireless radio can affect your choices on when, what, and how to transfer data in order to +minimize impact on battery life.</p> + </a> + + <a href="http://developer.android.com/training/cloudsync/index.html"> + <h4>Syncing to the Cloud</h4> + <p>This class covers different strategies for cloud enabled applications. It covers syncing +data with the cloud using your own back-end web application, and backing up data using the cloud so +that users can restore their data when installing your application on a new device.</p> + </a> + + </div> + +</div>
\ No newline at end of file diff --git a/docs/html/guide/topics/nfc/advanced-nfc.jd b/docs/html/guide/topics/connectivity/nfc/advanced-nfc.jd index b43b559..9d6cda5 100644 --- a/docs/html/guide/topics/nfc/advanced-nfc.jd +++ b/docs/html/guide/topics/connectivity/nfc/advanced-nfc.jd @@ -128,12 +128,12 @@ tag technologies are as follows:</p> <ol> <li>Filter for an {@link android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED} intent specifying the tag technologies that you want to handle. See <a -href="{@docRoot}guide/topics/nfc/nfc.html#tech-disc">Filtering for NFC +href="{@docRoot}guide/topics/connectivity/nfc/nfc.html#tech-disc">Filtering for NFC intents</a> for more information. In general, the tag dispatch system tries to start a {@link android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED} intent when an NDEF message cannot be mapped to a MIME type or URI, or if the tag scanned did not contain NDEF data. For more information on how this is determined, see <a -href="{@docRoot}guide/topics/nfc/nfc.html#tag-dispatch">The Tag Dispatch System</a>.</li> +href="{@docRoot}guide/topics/connectivity/nfc/nfc.html#tag-dispatch">The Tag Dispatch System</a>.</li> <li>When your application receives the intent, obtain the {@link android.nfc.Tag} object from the intent: <pre>Tag tagFromIntent = intent.getParcelableExtra(NfcAdapter.EXTRA_TAG);</pre></li> diff --git a/docs/html/guide/topics/nfc/index.jd b/docs/html/guide/topics/connectivity/nfc/index.jd index b86d72d..88c206f 100644 --- a/docs/html/guide/topics/nfc/index.jd +++ b/docs/html/guide/topics/connectivity/nfc/index.jd @@ -15,13 +15,13 @@ page.title=Near Field Communication called NDEF (NFC Data Exchange Format).</p> <dl> - <dt><strong><a href="{@docRoot}guide/topics/nfc/nfc.html">NFC Basics</a></strong></dt> + <dt><strong><a href="{@docRoot}guide/topics/connectivity/nfc/nfc.html">NFC Basics</a></strong></dt> <dd>This document describes how Android handles discovered NFC tags and how it notifies applications of data that is relevant to the application. It also goes over how to work with the NDEF data in your applications and gives an overview of the framework APIs that support the basic NFC feature set of Android.</dd> - <dt><strong><a href="{@docRoot}guide/topics/nfc/advanced-nfc.html">Advanced + <dt><strong><a href="{@docRoot}guide/topics/connectivity/nfc/advanced-nfc.html">Advanced NFC</a></strong></dt> <dd>This document goes over the APIs that enable use of the various tag technologies that Android supports. When you are not working with NDEF data, or when you are working with NDEF diff --git a/docs/html/guide/topics/nfc/nfc.jd b/docs/html/guide/topics/connectivity/nfc/nfc.jd index 834656a..51c7bee 100644 --- a/docs/html/guide/topics/nfc/nfc.jd +++ b/docs/html/guide/topics/connectivity/nfc/nfc.jd @@ -39,7 +39,7 @@ page.title=NFC Basics <p>This document describes the basic NFC tasks you perform in Android. It explains how to send and receive NFC data in the form of NDEF messages and describes the Android framework APIs that support these features. For more advanced topics, including a discussion of working with non-NDEF data, -see <a href="{@docRoot}guide/topics/nfc/advanced-nfc.html">Advanced NFC</a>.</p> +see <a href="{@docRoot}guide/topics/connectivity/nfc/advanced-nfc.html">Advanced NFC</a>.</p> <p>There are two major uses cases when working with NDEF data and Android:</p> @@ -105,7 +105,7 @@ or more records ({@link android.nfc.NdefRecord}). Each NDEF record must be well- the specification of the type of record that you want to create. Android also supports other types of tags that do not contain NDEF data, which you can work with by using the classes in the {@link android.nfc.tech} package. To learn more -about these technologies, see the <a href="{@docRoot}guide/topics/nfc/advanced-nfc.html">Advanced +about these technologies, see the <a href="{@docRoot}guide/topics/connectivity/nfc/advanced-nfc.html">Advanced NFC</a> topic. Working with these other types of tags involves writing your own protocol stack to communicate with the tags, so we recommend using NDEF when possible for ease of development and maximum support for Android-powered devices. @@ -454,7 +454,7 @@ within a <code>tech-list</code> set. Your activity is <p>For more information about working with tag technologies and the {@link android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED} intent, see <a -href="{@docRoot}guide/topics/nfc/advanced-nfc.html#tag-tech">Working with Supported Tag +href="{@docRoot}guide/topics/connectivity/nfc/advanced-nfc.html#tag-tech">Working with Supported Tag Technologies</a> in the Advanced NFC document.</p> <h3 id="tag-disc">ACTION_TAG_DISCOVERED</h3> <p>To filter for {@link android.nfc.NfcAdapter#ACTION_TAG_DISCOVERED} use the following intent @@ -685,7 +685,7 @@ application based on the AAR.</li> </p> <p class="note"><strong>Note:</strong> You can override AARs and the intent dispatch system with the <a -href="{@docRoot}guide/topics/nfc/advanced-nfc.html#foreground-dispatch">foreground dispatch +href="{@docRoot}guide/topics/connectivity/nfc/advanced-nfc.html#foreground-dispatch">foreground dispatch system</a>, which allows a foreground activity to have priority when an NFC tag is discovered. With this method, the activity must be in the foreground to override AARs and the intent dispatch system.</p> @@ -766,7 +766,7 @@ API level 14 (Android 4.0) and later.</li> <p class="note"><strong>Note:</strong> If your activity enables Android Beam and is in the foreground, the standard intent dispatch system is disabled. However, if your activity also -enables <a href="{@docRoot}guide/topics/nfc/advanced-nfc.html#foreground-dispatch">foreground +enables <a href="{@docRoot}guide/topics/connectivity/nfc/advanced-nfc.html#foreground-dispatch">foreground dispatching</a>, then it can still scan tags that match the intent filters set in the foreground dispatching.</p> diff --git a/docs/html/guide/topics/network/sip.jd b/docs/html/guide/topics/connectivity/sip.jd index 600da78..a5f0e2e 100644 --- a/docs/html/guide/topics/network/sip.jd +++ b/docs/html/guide/topics/connectivity/sip.jd @@ -140,7 +140,7 @@ manifest:</p> <ul> <li><code><uses-sdk android:minSdkVersion="9" /></code>. This indicates that your application requires Android 2.3 or higher. For more -information, see <a href="{@docRoot}guide/appendix/api-levels.html">API +information, see <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">API Levels</a> and the documentation for the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a > element.</li> @@ -479,9 +479,9 @@ wireless, so you must test on an actual device. Testing on AVD won't work.</li> <li>On your device, connect to wireless (<strong>Settings > Wireless & networks > Wi-Fi > Wi-Fi settings</strong>)</li> <li>Set up your mobile device for testing, as described in <a -href="{@docRoot}guide/developing/device.html">Developing on a Device</a>.</li> +href="{@docRoot}tools/device.html">Developing on a Device</a>.</li> <li>Run your application on your mobile device, as described in <a -href="{@docRoot}guide/developing/device.html">Developing on a Device</a>.</li> +href="{@docRoot}tools/device.html">Developing on a Device</a>.</li> <li>If you are using Eclipse, you can view the application log output in Eclipse using LogCat (<strong>Window > Show View > Other > Android > diff --git a/docs/html/guide/topics/usb/accessory.jd b/docs/html/guide/topics/connectivity/usb/accessory.jd index 8b74bc0..a217767 100644 --- a/docs/html/guide/topics/usb/accessory.jd +++ b/docs/html/guide/topics/connectivity/usb/accessory.jd @@ -433,7 +433,7 @@ private void openAccessory() { protocol bundles the packets together for both speeds into one logical packet for simplicity.</p> <p>For more information about using threads in Android, see <a href= - "{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes and + "{@docRoot}guide/components/processes-and-threads.html#Threads">Processes and Threads</a>.</p> <h3 id="terminating-a">Terminating communication with an accessory</h3> diff --git a/docs/html/guide/topics/usb/adk.jd b/docs/html/guide/topics/connectivity/usb/adk.jd index c8949a3..034728c 100644 --- a/docs/html/guide/topics/usb/adk.jd +++ b/docs/html/guide/topics/connectivity/usb/adk.jd @@ -63,7 +63,7 @@ page.title=Android Open Accessory Development Kit <ol> <li><a href="http://www.youtube.com/watch?v=s7szcpXf2rE">Google I/O Session Video</a></li> - <li><a href="{@docRoot}guide/topics/usb/accessory.html">USB Accessory Dev Guide</a></li> + <li><a href="{@docRoot}guide/topics/connectivity/usb/accessory.html">USB Accessory Dev Guide</a></li> </ol> <h2>Where to buy</h2> @@ -121,7 +121,7 @@ page.title=Android Open Accessory Development Kit hardware and not all devices will support accessory mode. Devices that support accessory mode can be filtered using a <code><uses-feature></code> element in your corresponding application's Android manifest. For more information, see the <a href= - "{@docRoot}guide/topics/usb/accessory.html#manifest">USB Accessory</a> Developer Guide.</p> + "{@docRoot}guide/topics/connectivity/usb/accessory.html#manifest">USB Accessory</a> Developer Guide.</p> <p>The following list of distributers are currently producing Android Open Accessory compatible development boards:</p> @@ -168,7 +168,7 @@ page.title=Android Open Accessory Development Kit prototyping platform</a>, the accessory's hardware design files, code that implements the accessory's firmware, and the Android application that interacts with the accessory. The hardware design files and firmware code are contained in the <a href= - "https://dl-ssl.google.com/android/adk/adk_release_0512.zip">ADK package download</a>.</p> + "https://dl-ssl.google.com/android/adk/adk_release_20120606.zip">ADK package download</a>.</p> <p>The main hardware and software components of the ADK include:</p> <ul> @@ -190,18 +190,19 @@ page.title=Android Open Accessory Development Kit "http://www.circuitsathome.com/arduino_usb_host_shield_projects">Arduino USB Host Shield</a> library provides the logic for the USB micro-controller board to act as a USB Host. This allows the board to initiate transactions with USB devices. Describing how to use this entire library - is out of the scope of this document. Where needed, this document points out important + is beyond the scope of this document. Where needed, this document points out important interactions with the library. For more information, see the source code for the Arduino USB - Host Shield library in the <code>firmware/arduino_libs/USB_Host_Shield</code> directory.</li> + Host Shield library in the <code>arduino_libs/USB_Host_Shield</code> directory.</li> - <li>An Arduino sketch, <code>firmware/demokit/demokit.pde</code>, defines the firmware that + <li>An Arduino sketch, <code>arduino_libs/AndroidAccessory/examples/demokit/demokit.pde</code>, + defines the firmware that runs on the ADK board and is written in C++. The sketch calls the Android accessory protocol library to interact with the Android-powered device. It also sends data from the ADK board and shield to the Android application and receives data from the Android application and outputs it to the ADK board and shield.</li> <li>The Android accessory protocol library, which is located in the - <code>firmware/arduino_libs/AndroidAccessory</code> directory. This library defines how to + <code>arduino_libs/AndroidAccessory</code> directory. This library defines how to enumerate the bus, find a connected Android-powered device that supports accessory mode, and how to setup communication with the device.</li> @@ -228,20 +229,21 @@ page.title=Android Open Accessory Development Kit <h2 id="getting-started">Getting Started with the ADK</h2> <p>The following sections describe how to install the Arduino software on your computer, use the - Arduino software to install the ADK board's firmware, and install and run the accompanying + Arduino IDE to install the ADK board's firmware, and install and run the accompanying Android application for the ADK board. Before you begin, download the following items to set up your development environment:</p> <ul> - <li><a href="http://www.arduino.cc/en/Main/software">Arduino Software</a>: contains libraries - and an IDE for coding and installing firmware to the ADK board.</li> + <li><a href="http://arduino.cc/en/Main/Software">Arduino 1.0 or higher</a>: contains + libraries and an IDE for coding and installing firmware to the ADK board.</li> - <li><a href="http://www.arduino.cc/playground/Main/CapSense">CapSense library</a>: contains the - libraries to sense human capacitance. This is needed for the capacative button that is located - on the ADK shield.</li> + <li><a href="http://www.arduino.cc/playground/Main/CapSense">CapSense library v.04</a>: + contains the libraries to sense human capacitance. This library is needed for the capacitive + button that is located on the ADK shield.</li> - <li><a href="https://dl-ssl.google.com/android/adk/adk_release_0512.zip">The ADK package</a>: contains the firmware for the ADK board and hardware design - files for the ADK board and shield.</li> + <li><a href="https://dl-ssl.google.com/android/adk/adk_release_20120606.zip">ADK software + package</a>: contains the firmware for the ADK board and hardware design files for the ADK + board and shield.</li> </ul> <h3 id="installing">Installing the Arduino software and necessary libraries</h3> @@ -250,35 +252,33 @@ page.title=Android Open Accessory Development Kit <ol> <li> - <a href="http://arduino.cc/en/Guide/HomePage">Download and install</a> the Arduino Software - as described on the Arduino website. + <a href="http://arduino.cc/en/Main/Software">Download and install</a> the Arduino 1.0 or + higher as described on the Arduino website. <p class="note"><strong>Note:</strong> If you are on a Mac, install the FTDI USB Serial Driver that is included in the Arduino package, even though the installation instructions say otherwise.</p> </li> - <li><a href="https://dl-ssl.google.com/android/adk/adk_release_0512.zip">Download</a> and + <li><a href="https://dl-ssl.google.com/android/adk/adk_release_20120606.zip">Download</a> and extract the ADK package to a directory of your choice. You should have an <code>app</code>, - <code>firmware</code>, and <code>hardware</code> directories.</li> + <code>arduino_libs</code>, and <code>hardware</code> directories.</li> - <li>Extract the CapSense download to a directory of your choice.</li> + <li><a href="http://www.arduino.cc/playground/Main/CapSense">Download</a> and extract + the CapSense package to a directory of your choice.</li> <li>Install the necessary libraries: <p>On Windows:</p> <ol type="a"> - <li>Copy the <code>firmware/arduino_libs/AndroidAccessory</code> and - <code>firmware/arduino_libs/USB_Host_Shield</code> directories (the complete directories, + <li>Copy the <code>arduino_libs/AndroidAccessory</code> and + <code>arduino_libs/USB_Host_Shield</code> directories (the complete directories, not just the files within) to the <code><arduino_installation_root>/libraries/</code> directory.</li> - <li>Create a CapSense directory in the - <code><arduino_installation_root>/libraries/</code> directory</li> - - <li>Copy <code>CapSense.cpp</code> and <code>CapSense.h</code> from the unzipped CapSense - download to the <code>CapSense</code> directory.</li> + <li>Copy the extracted <code>CapSense/</code> library directory and its contents to the + <code><arduino_installation_root>/libraries/</code> directory.</li> </ol> <p>On Mac:</p> @@ -288,16 +288,13 @@ page.title=Android Open Accessory Development Kit directory inside your user account's <code>Documents</code> directory, and within that, a <code>libraries</code> directory.</li> - <li>Copy the <code>firmware/arduino_libs/AndroidAccessory</code> and - <code>firmware/arduino_libs/USB_Host_Shield</code> directories (the + <li>Copy the <code>arduino_libs/AndroidAccessory</code> and + <code>arduino_libs/USB_Host_Shield</code> directories (the complete directories, not just the files within) to your <code>Documents/Arduino/libraries/</code> directory.</li> - <li>Create a <code>CapSense</code> directory in your - <code>Documents/Arduino/libraries/</code> directory.</li> - - <li>Copy <code>CapSense.cpp</code> and <code>CapSense.h</code> from the unzipped CapSense - download to the <code>CapSense</code> directory.</li> + <li>Copy the extracted <code>CapSense/</code> library directory and its contents to the + <code>Documents/Arduino/libraries/</code> directory. </ol> <p>On Linux (Ubuntu):</p> @@ -308,19 +305,16 @@ page.title=Android Open Accessory Development Kit not just the files within) to the <code><arduino_installation_root>/libraries/</code> directory.</li> - <li>Create a <code>CapSense</code> directory in the + <li>Copy the extracted <code>CapSense/</code> library directory and its contents to the <code><arduino_installation_root>/libraries/</code> directory.</li> - <li>Copy <code>CapSense.cpp</code> and <code>CapSense.h</code> from the unzipped CapSense - download to the <code>CapSense</code> directory.</li> - <li>Install the avr-libc library by entering <code>sudo apt-get install avr-libc</code> from a shell prompt.</li> </ol> </li> </ol> - <p>You should now have three new directories in the Arduino libraries directory: + <p>You should now have three new directories in the Arduino <code>libraries/</code> directory: <code>AndroidAccessory</code>, <code>USB_Host_Shield</code>, and <code>CapSense</code>.</p> <h3 id="installing-firmware">Installing the firmware to the ADK board</h3> @@ -331,7 +325,7 @@ page.title=Android Open Accessory Development Kit <li>Connect the ADK board to your computer using the micro-USB port, which allows two-way communication and provides power to the ADK board.</li> - <li>Launch Arduino.</li> + <li>Launch the Arduino IDE.</li> <li>Click <strong>Tools > Board > Arduino Mega 2560</strong> to specify the ADK board's type.</li> @@ -351,13 +345,13 @@ page.title=Android Open Accessory Development Kit </ul> </li> - <li>To open the firmware code (a sketch), click <strong>File > Open</strong> and select - <code>firmware/demokit/demokit.pde</code>.</li> + <li>To open the Demokit sketch (firmware code), click <strong>File > Examples > + AndroidAccessory > demokit</strong>.</li> <li>Click <strong>Sketch > Verify/Compile</strong> to ensure that the sketch has no errors.</li> - <li>Select <strong>File > Upload to I/O Board</strong>. When Arduino outputs <strong>Done + <li>Select <strong>File > Upload</strong>. When Arduino outputs <strong>Done uploading.</strong>, the board is ready to communicate with your Android-powered device.</li> </ol> @@ -375,7 +369,7 @@ page.title=Android Open Accessory Development Kit 2.3.4 devices that support accessory mode. This library is also forward compatible with Android 3.1 or newer devices that support accessory mode. If you only care about Android 3.1 or newer devices, all you need is API Level 12. For more information on deciding which API level to use, - see the <a href="{@docRoot}guide/topics/usb/accessory.html#choosing">USB Accessory</a> + see the <a href="{@docRoot}guide/topics/connectivity/usb/accessory.html#choosing">USB Accessory</a> documentation.</li> <li>Click <strong>File > New > Project...</strong>, then select <strong>Android > @@ -414,12 +408,12 @@ page.title=Android Open Accessory Development Kit <h3 id="monitoring">Monitoring the ADK Board</h3> <p>The ADK firmware consists of a few files that you should be looking at if you want to build - your own accessory. The files in the <code>firmware/arduino_libs/AndroidAccessory</code> + your own accessory. The files in the <code>arduino_libs/AndroidAccessory</code> directory are the most important files and have the logic to detect and connect to Android-powered devices that support accessory mode. Feel free to add debug statements (Arduino - <code>Serial.print()</code> statements) to the code located in the - <code>arduino_libraries_directory/AndroidAccessory</code> directory and - <code>firmware/demokit/demokit.pde</code> sketch and re-upload the sketch to the ADK board to + <code>Serial.println()</code> statements) to the code located in the + <code><arduino_installation_root>/libraries/AndroidAccessory</code> directory and + <code>demokit.pde</code> sketch and re-upload the sketch to the ADK board to discover more about how the firmware works.</p> <p>You can view the debug statements in the Arduino Serial Monitor by clicking <strong>Tools > @@ -575,11 +569,11 @@ data: none useful if you want to port the code over for your own accessories.</p> <p>The important pieces of the firmware are the - <code>accessory/demokit/demokit/demokit.pde</code> sketch, which is the code that receives and - sends data to the DemoKit application running on the Android-powered device. The code to detect - and set up communication with the Android-powered device is contained in the - <code>accessory/arduino_libs/AndroidAccessory/AndroidAccessory.h</code> and - <code>accessory/arduino_libs/AndroidAccessory/AndroidAccessory.cpp</code> files. This code + <code>arduino_libs/AndroidAccessory/examples/demokit/demokit/demokit.pde</code> sketch, which is + the code that receives and sends data to the DemoKit application running on the Android-powered + device. The code to detect and set up communication with the Android-powered device is contained + in the <code>arduino_libs/AndroidAccessory/AndroidAccessory.h</code> and + <code>arduino_libs/AndroidAccessory/AndroidAccessory.cpp</code> files. This code includes most of the logic that will help you implement your own accessory's firmware. It might be useful to have all three of these files open in a text editor as you read through these next sections.</p> @@ -909,8 +903,7 @@ int AndroidAccessory::read(void *buff, int len, unsigned int nakLimit) { int AndroidAccessory::write(void *buff, int len) { usb.outTransfer(1, out, len, (char *)buff); return len; } - </pre> - <p>See the <code>firmware/demokit/demokit.pde</code> file for information about how the ADK board + <p>See the <code>demokit.pde</code> sketch for information about how the ADK board reads and writes data.</p> diff --git a/docs/html/guide/topics/usb/host.jd b/docs/html/guide/topics/connectivity/usb/host.jd index b561754..355dd2d 100644 --- a/docs/html/guide/topics/usb/host.jd +++ b/docs/html/guide/topics/connectivity/usb/host.jd @@ -380,7 +380,7 @@ mUsbManager.requestPermission(device, mPermissionIntent); android.hardware.usb.UsbDeviceConnection#controlTransfer controlTransfer()} method. You should carry out this step in another thread to prevent blocking the main UI thread. For more information about using threads in Android, see <a href= - "{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes and + "{@docRoot}guide/components/processes-and-threads.html#Threads">Processes and Threads</a>.</li> </ul> diff --git a/docs/html/guide/topics/usb/index.jd b/docs/html/guide/topics/connectivity/usb/index.jd index ef53bdf..7086ab1 100644 --- a/docs/html/guide/topics/usb/index.jd +++ b/docs/html/guide/topics/connectivity/usb/index.jd @@ -6,9 +6,9 @@ page.title=USB Host and Accessory <h2>Topics</h2> <ol> - <li><a href="{@docRoot}guide/topics/usb/accessory.html">USB Accessory</a></li> + <li><a href="{@docRoot}guide/topics/connectivity/usb/accessory.html">USB Accessory</a></li> - <li><a href="{@docRoot}guide/topics/usb/host.html">USB Host</a></li> + <li><a href="{@docRoot}guide/topics/connectivity/usb/host.html">USB Host</a></li> </ol> </div> </div> @@ -42,8 +42,8 @@ page.title=USB Host and Accessory dependant on the device's hardware, regardless of platform level. You can filter for devices that support USB host and accessory through a <a href= "{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a> element. See - the USB <a href="{@docRoot}guide/topics/usb/accessory.html">accessory</a> and <a href= - "{@docRoot}guide/topics/usb/host.html">host</a> documentation for more details.</p> + the USB <a href="{@docRoot}guide/topics/connectivity/usb/accessory.html">accessory</a> and <a href= + "{@docRoot}guide/topics/connectivity/usb/host.html">host</a> documentation for more details.</p> <h2>Debugging considerations</h2> diff --git a/docs/html/guide/topics/wireless/wifip2p.jd b/docs/html/guide/topics/connectivity/wifip2p.jd index 82c9abd..82c9abd 100644 --- a/docs/html/guide/topics/wireless/wifip2p.jd +++ b/docs/html/guide/topics/connectivity/wifip2p.jd diff --git a/docs/html/guide/topics/data/backup.jd b/docs/html/guide/topics/data/backup.jd index d91e422..602b6e8 100644 --- a/docs/html/guide/topics/data/backup.jd +++ b/docs/html/guide/topics/data/backup.jd @@ -47,7 +47,7 @@ data onto the new device</li> <h2>See also</h2> <ol> - <li><a href="{@docRoot}guide/developing/tools/bmgr.html">{@code bmgr} tool</a></li> + <li><a href="{@docRoot}tools/help/bmgr.html">{@code bmgr} tool</a></li> </ol> </div> @@ -316,7 +316,7 @@ backup for all applications that have requested a backup since the last backup w <p class="note"><strong>Tip:</strong> While developing your application, you can initiate an immediate backup operation from the Backup Manager with the <a -href="{@docRoot}guide/developing/tools/bmgr.html">{@code bmgr} tool</a>.</p> +href="{@docRoot}tools/help/bmgr.html">{@code bmgr} tool</a>.</p> <p>When the Backup Manager calls your {@link android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) @@ -460,7 +460,7 @@ android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore( href="#RequestingRestore">Requesting restore</a> for more information).</p> <p class="note"><strong>Note:</strong> While developing your application, you can also request a -restore operation with the <a href="{@docRoot}guide/developing/tools/bmgr.html">{@code bmgr} +restore operation with the <a href="{@docRoot}tools/help/bmgr.html">{@code bmgr} tool</a>.</p> <p>When the Backup Manager calls your {@link @@ -863,7 +863,7 @@ onBackup()}.</p> <p class="note"><strong>Note:</strong> While developing your application, you can request a backup and initiate an immediate backup operation with the <a -href="{@docRoot}guide/developing/tools/bmgr.html">{@code bmgr} +href="{@docRoot}tools/help/bmgr.html">{@code bmgr} tool</a>.</p> @@ -878,7 +878,7 @@ android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescripto implementation, passing the data from the current set of backup data.</p> <p class="note"><strong>Note:</strong> While developing your application, you can request a -restore operation with the <a href="{@docRoot}guide/developing/tools/bmgr.html">{@code bmgr} +restore operation with the <a href="{@docRoot}tools/help/bmgr.html">{@code bmgr} tool</a>.</p> @@ -886,7 +886,7 @@ tool</a>.</p> <p>Once you've implemented your backup agent, you can test the backup and restore functionality with the following procedure, using <a -href="{@docRoot}guide/developing/tools/bmgr.html">{@code bmgr}</a>.</p> +href="{@docRoot}tools/help/bmgr.html">{@code bmgr}</a>.</p> <ol> <li>Install your application on a suitable Android system image diff --git a/docs/html/guide/topics/data/data-storage.jd b/docs/html/guide/topics/data/data-storage.jd index d31afa5..e9d2d25 100644 --- a/docs/html/guide/topics/data/data-storage.jd +++ b/docs/html/guide/topics/data/data-storage.jd @@ -1,4 +1,4 @@ -page.title=Data Storage +page.title=Storage Options @jd:body @@ -16,22 +16,9 @@ page.title=Data Storage <h2>In this document</h2> <ol> <li><a href="#pref">Using Shared Preferences</a></li> - <li><a href="#filesInternal">Using the Internal Storage</a> - <ol> - <li><a href="#InternalCache">Saving cache files</a></li> - <li><a href="#InternalMethods">Other useful methods</a></li> - </ol></li> - <li><a href="#filesExternal">Using the External Storage</a> - <ol> - <li><a href="#MediaAvail">Checking media availability</a></li> - <li><a href="#AccessingExtFiles">Accessing files on external storage</a></li> - <li><a href="#SavingSharedFiles">Saving files that should be shared</a></li> - <li><a href="#ExternalCache">Saving cache files</a></li> - </ol></li> - <li><a href="#db">Using Databases</a> - <ol> - <li><a href="#dbDebugging">Database debugging</a></li> - </ol></li> + <li><a href="#filesInternal">Using the Internal Storage</a></li> + <li><a href="#filesExternal">Using the External Storage</a></li> + <li><a href="#db">Using Databases</a></li> <li><a href="#netw">Using a Network Connection</a></li> </ol> @@ -449,7 +436,7 @@ applications.</p> <p>The Android SDK includes a {@code sqlite3} database tool that allows you to browse table contents, run SQL commands, and perform other useful functions on SQLite -databases. See <a href="{@docRoot}guide/developing/tools/adb.html#sqlite">Examining sqlite3 +databases. See <a href="{@docRoot}tools/help/adb.html#sqlite">Examining sqlite3 databases from a remote shell</a> to learn how to run this tool. </p> diff --git a/docs/html/guide/topics/data/index.html b/docs/html/guide/topics/data/index.html deleted file mode 100644 index a94f8c0..0000000 --- a/docs/html/guide/topics/data/index.html +++ /dev/null @@ -1,9 +0,0 @@ -<html> -<head> -<meta http-equiv="refresh" content="0;url=data-storage.html"> -<title>Redirecting...</title> -</head> -<body> -<a href="data-storage.html">click here</a> if you are not redirected. -</body> -</html>
\ No newline at end of file diff --git a/docs/html/guide/topics/data/index.jd b/docs/html/guide/topics/data/index.jd new file mode 100644 index 0000000..1e082b3 --- /dev/null +++ b/docs/html/guide/topics/data/index.jd @@ -0,0 +1,23 @@ +page.title=Data Storage +page.landing=true +page.landing.intro=Store application data in databases, files, or preferences, in internal or removeable storage. You can also add a data backup service to let users store and recover application and system data. +page.landing.image= + +@jd:body + +<div class="landing-docs"> + + + <div class="col-12"> + <h3>Training</h3> + + <a href="http://developer.android.com/training/cloudsync/index.html"> + <h4>Syncing to the Cloud</h4> + <p>This class covers different strategies for cloud enabled applications. It covers syncing +data with the cloud using your own back-end web application, and backing up data using the cloud so +that users can restore their data when installing your application on a new device.</p> + </a> + + </div> + +</div>
\ No newline at end of file diff --git a/docs/html/guide/topics/data/install-location.jd b/docs/html/guide/topics/data/install-location.jd new file mode 100644 index 0000000..19c4b39 --- /dev/null +++ b/docs/html/guide/topics/data/install-location.jd @@ -0,0 +1,206 @@ +page.title=App Install Location +@jd:body + + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Quickview</h2> + <ul> + <li>You can allow your application to install on the device's external storage.</li> + <li>Some types of applications should <strong>not</strong> allow installation on the external +storage.</li> + <li>Installing on the external storage is ideal for large applications that are not tightly +integrated with the system (most commonly, games).</li> + </ul> + + <h2>In this document</h2> + <ol> + <li><a href="#Compatiblity">Backward Compatibility</a></li> + <li><a href="#ShouldNot">Applications That Should NOT Install on External Storage</a></li> + <li><a href="#Should">Applications That Should Install on External Storage</a></li> + </ol> + + <h2>See also</h2> + <ol> + <li><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"> +<manifest></a></code></li> + </ol> + +</div> +</div> + +<p>Beginning with API Level 8, you can allow your application to be installed on the +external storage (for example, the device's SD card). This is an optional feature you can declare +for your application with the <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#install">{@code +android:installLocation}</a> manifest attribute. If you do +<em>not</em> declare this attribute, your application will be installed on the internal storage +only and it cannot be moved to the external storage.</p> + +<p>To allow the system to install your application on the external storage, modify your +manifest file to include the <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#install">{@code +android:installLocation}</a> attribute in the <code><a +href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element, +with a value of either "{@code preferExternal}" or "{@code auto}". For example:</p> + +<pre> +<manifest xmlns:android="http://schemas.android.com/apk/res/android" + android:installLocation="preferExternal" + ... > +</pre> + +<p>If you declare "{@code preferExternal}", you request that your application be installed on the +external storage, but the system does not guarantee that your application will be installed on +the external storage. If the external storage is full, the system will install it on the internal +storage. The user can also move your application between the two locations.</p> + +<p>If you declare "{@code auto}", you indicate that your application may be installed on the +external storage, but you don't have a preference of install location. The system will +decide where to install your application based on several factors. The user can also move your +application between the two locations.</p> + +<p>When your application is installed on the external storage:</p> +<ul> + <li>There is no effect on the application performance so long +as the external storage is mounted on the device.</li> + <li>The {@code .apk} file is saved on the external storage, but all private user data, +databases, optimized {@code .dex} files, and extracted native code are saved on the +internal device memory.</li> + <li>The unique container in which your application is stored is encrypted with a randomly +generated key that can be decrypted only by the device that originally installed it. Thus, an +application installed on an SD card works for only one device.</li> + <li>The user can move your application to the internal storage through the system settings.</li> +</ul> + +<p class="warning"><strong>Warning:</strong> When the user enables USB mass storage to share files +with a computer or unmounts the SD card via the system settings, the external storage is unmounted +from the device and all applications running on the external storage are immediately killed.</p> + + + +<h2 id="Compatiblity">Backward Compatibility</h2> + +<p>The ability for your application to install on the external storage is a feature available only +on devices running API Level 8 (Android 2.2) or greater. Existing applications that were built prior +to API Level 8 will always install on the internal storage and cannot be moved to the external +storage (even on devices with API Level 8). However, if your application is designed to support an +API Level <em>lower than</em> 8, you can choose to support this feature for devices with API Level 8 +or greater and still be compatible with devices using an API Level lower than 8.</p> + +<p>To allow installation on external storage and remain compatible with versions lower than API +Level 8:</p> +<ol> + <li>Include the {@code android:installLocation} attribute with a value of "{@code auto}" or +"{@code preferExternal}" in the <code><a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><manifest></a></code> +element.</li> + <li>Leave your {@code android:minSdkVersion} attribute as is (something <em>less +than</em> "8") and be certain that your application code uses only APIs compatible with that +level.</li> + <li>In order to compile your application, change your build target to API Level 8. This is +necessary because older Android libraries don't understand the {@code android:installLocation} +attribute and will not compile your application when it's present.</li> +</ol> + +<p>When your application is installed on a device with an API Level lower than 8, the {@code +android:installLocation} attribute is ignored and the application is installed on the internal +storage.</p> + +<p class="caution"><strong>Caution:</strong> Although XML markup such as this will be ignored by +older platforms, you must be careful not to use programming APIs introduced in API Level 8 +while your {@code minSdkVersion} is less than "8", unless you perform the work necessary to +provide backward compatibility in your code. For information about building +backward compatibility in your application code, see the <a +href="{@docRoot}resources/articles/backward-compatibility.html">Backward Compatibility</a> +article.</p> + + + +<h2 id="ShouldNot">Applications That Should NOT Install on External Storage</h2> + +<p>When the user enables USB mass storage to share files with their computer (or otherwise +unmounts or removes the external storage), any application +installed on the external storage and currently running is killed. The system effectively becomes +unaware of the application until mass storage is disabled and the external storage is +remounted on the device. Besides killing the application and making it unavailable to the user, +this can break some types of applications in a more serious way. In order for your application to +consistently behave as expected, you <strong>should not</strong> allow your application to be +installed on the external storage if it uses any of the following features, due to the cited +consequences when the external storage is unmounted:</p> + +<dl> + <dt>Services</dt> + <dd>Your running {@link android.app.Service} will be killed and will not be restarted when +external storage is remounted. You can, however, register for the {@link +android.content.Intent#ACTION_EXTERNAL_APPLICATIONS_AVAILABLE} broadcast Intent, which will notify +your application when applications installed on external storage have become available to the +system again. At which time, you can restart your Service.</dd> + <dt>Alarm Services</dt> + <dd>Your alarms registered with {@link android.app.AlarmManager} will be cancelled. You must +manually re-register any alarms when external storage is remounted.</dd> + <dt>Input Method Engines</dt> + <dd>Your <a href="{@docRoot}resources/articles/on-screen-inputs.html">IME</a> will be +replaced by the default IME. When external storage is remounted, the user can open system settings +to enable your IME again.</dd> + <dt>Live Wallpapers</dt> + <dd>Your running <a href="{@docRoot}resources/articles/live-wallpapers.html">Live Wallpaper</a> +will be replaced by the default Live Wallpaper. When external storage is remounted, the user can +select your Live Wallpaper again.</dd> + <dt>Live Folders</dt> + <dd>Your <a href="{@docRoot}resources/articles/live-folders.html">Live Folder</a> will be +removed from the home screen. When external storage is remounted, the user can add your Live Folder +to the home screen again.</dd> + <dt>App Widgets</dt> + <dd>Your <a href="{@docRoot}guide/topics/appwidgets/index.html">App Widget</a> will be removed +from the home screen. When external storage is remounted, your App Widget will <em>not</em> be +available for the user to select until the system resets the home application (usually not until a +system reboot).</dd> + <dt>Account Managers</dt> + <dd>Your accounts created with {@link android.accounts.AccountManager} will disappear until +external storage is remounted.</dd> + <dt>Sync Adapters</dt> + <dd>Your {@link android.content.AbstractThreadedSyncAdapter} and all its sync functionality will +not work until external storage is remounted.</dd> + <dt>Device Administrators</dt> + <dd>Your {@link android.app.admin.DeviceAdminReceiver} and all its admin capabilities will +be disabled, which can have unforeseeable consequences for the device functionality, which may +persist after external storage is remounted.</dd> + <dt>Broadcast Receivers listening for "boot completed"</dt> + <dd>The system delivers the {@link android.content.Intent#ACTION_BOOT_COMPLETED} broadcast +before the external storage is mounted to the device. If your application is installed on the +external storage, it can never receive this broadcast.</dd> + <dt>Copy Protection</dt> + <dd>Your application cannot be installed to a device's SD card if it uses Google Play's + Copy Protection feature. However, if you use Google Play's + <a href="{@docRoot}guide/google/play/licensing.html">Application Licensing</a> instead, your + application <em>can</em> be installed to internal or external storage, including SD cards.</dd> +</dl> + +<p>If your application uses any of the features listed above, you <strong>should not</strong> allow +your application to install on external storage. By default, the system <em>will not</em> allow your +application to install on the external storage, so you don't need to worry about your existing +applications. However, if you're certain that your application should never be installed on the +external storage, then you should make this clear by declaring <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#install">{@code +android:installLocation}</a> with a value of "{@code internalOnly}". Though this does not +change the default behavior, it explicitly states that your application should only be installed +on the internal storage and serves as a reminder to you and other developers that this decision has +been made.</p> + + +<h2 id="Should">Applications That Should Install on External Storage</h2> + +<p>In simple terms, anything that does not use the features listed in the previous section +are safe when installed on external storage. Large games are more commonly the types of +applications that should allow installation on external storage, because games don't typically +provide additional services when inactive. When external storage becomes unavailable and a game +process is killed, there should be no visible effect when the storage becomes available again and +the user restarts the game (assuming that the game properly saved its state during the normal +<a href="{@docRoot}guide/components/activities.html#Lifecycle">Activity lifecycle</a>).</p> + +<p>If your application requires several megabytes for the APK file, you should +carefully consider whether to enable the application to install on the external storage so that +users can preserve space on their internal storage.</p> + diff --git a/docs/html/guide/topics/drawing/index.html b/docs/html/guide/topics/drawing/index.html deleted file mode 100644 index 43c1499..0000000 --- a/docs/html/guide/topics/drawing/index.html +++ /dev/null @@ -1,9 +0,0 @@ -<html> -<head> -<meta http-equiv="refresh" content="0;url=opengl.html"> -<title>Redirecting...</title> -</head> -<body> -<a href="opengl.html">click here</a> if you are not redirected. -</body> -</html>
\ No newline at end of file diff --git a/docs/html/guide/topics/drawing/opengl.jd b/docs/html/guide/topics/drawing/opengl.jd deleted file mode 100644 index e22a251..0000000 --- a/docs/html/guide/topics/drawing/opengl.jd +++ /dev/null @@ -1,53 +0,0 @@ -page.title=OpenGL -@jd:body - -<p>Android includes support for 3D hardware acceleration. This functionality is -accessed via the OpenGL API — specifically, the OpenGL ES API.</p> - -<p>OpenGL ES is a flavor of the OpenGL specification intended for embedded -devices. Versions of OpenGL ES are loosely peered to versions of the primary -OpenGL standard. Android currently supports OpenGL ES 1.0, which corresponds -to OpenGL 1.3. So, if the application you have in mind is possible with OpenGL -1.3 on a desktop system, it should be possible on Android.</p> - -<p>The specific API provided by Android is similar to the J2ME JSR239 OpenGL -ES API. However, it may not be identical, so watch out for deviations.</p> - -<h2>Using the API</h2> - -<p>Here's how to use the API at an extremely high level:</p> - -<ol> -<li>Write a custom View subclass.</li> -<li>Obtain a handle to an OpenGLContext, which provides access to the OpenGL functionality.</li> -<li>In your View's onDraw() method, get a handle to a GL object, and use its methods to perform GL operations.</li> -</ol> - -<p>For an example of this usage model (based on the classic GL ColorCube), -see -<a href="{@docRoot}samples/ApiDemos/src/com/example/android/apis/graphics/GLView1.html">com.android.samples.graphics.GLView1.java</a> -in the ApiDemos sample code project. A slightly more sophisticated version showing how to use -it with threads can be found in -<a href="{@docRoot}samples/ApiDemos/src/com/example/android/apis/graphics/GLSurfaceViewActivity.html">com.android.samples.graphics.GLSurfaceViewActivity.java</a>. -</p> - -<p>Writing a summary of how to actually write 3D applications using OpenGL is -beyond the scope of this text and is left as an exercise for the reader.</p> - -<h2>Links to Additional Information</h2> - -<p>Information about OpenGL ES can be -found at <a title="http://www.khronos.org/opengles/" -href="http://www.khronos.org/opengles/">http://www.khronos.org/opengles/</a>.</p> - -<p>Information specifically -about OpenGL ES 1.0 (including a detailed specification) can be found -at <a title="http://www.khronos.org/opengles/1_X/" -href="http://www.khronos.org/opengles/1_X/">http://www.khronos.org/opengles/1_X/</a>.</p> - -<p>The documentation for the Android {@link javax.microedition.khronos.opengles.GL -OpenGL ES implementations} are also available.</p> - -<p>Finally, note that though Android does include some basic support for -OpenGL ES 1.1, the support is <strong>not complete</strong>, and should not be relied -upon at this time.</p> diff --git a/docs/html/guide/topics/fundamentals.jd b/docs/html/guide/topics/fundamentals.jd deleted file mode 100644 index a86d905..0000000 --- a/docs/html/guide/topics/fundamentals.jd +++ /dev/null @@ -1,518 +0,0 @@ -page.title=Application Fundamentals -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - -<h2>Quickview</h2> -<ul> - <li>Android applications are composed of one or more application components (activities, -services, content providers, and broadcast receivers)</li> - <li>Each component performs a different role in the overall application behavior, and each -one can be activated individually (even by other applications)</li> - <li>The manifest file must declare all components in the application and should also declare -all application requirements, such as the minimum version of Android required and any hardware -configurations required</li> - <li>Non-code application resources (images, strings, layout files, etc.) should include -alternatives for different device configurations (such as different strings for different -languages and different layouts for different screen sizes)</li> -</ul> - - -<h2>In this document</h2> -<ol> -<li><a href="#Components">Application Components</a> - <ol> - <li><a href="#ActivatingComponents">Activating components</a></li> - </ol> -</li> -<li><a href="#Manifest">The Manifest File</a> - <ol> - <li><a href="#DeclaringComponents">Declaring components</a></li> - <li><a href="#DeclaringRequirements">Declaring application requirements</a></li> - </ol> -</li> -<li><a href="#Resources">Application Resources</a></li> -</ol> -</div> -</div> - -<p>Android applications are written in the Java programming language. The Android SDK tools compile -the code—along with any data and resource files—into an <i>Android package</i>, an -archive file with an {@code .apk} suffix. All the code in a single {@code .apk} file is considered -to be one application and is the file that Android-powered devices use to install the -application.</p> - -<p>Once installed on a device, each Android application lives in its own security sandbox: </p> - -<ul> - <li>The Android operating system is a multi-user Linux system in which each application is a -different user.</li> - -<li>By default, the system assigns each application a unique Linux user ID (the ID is used only by -the system and is unknown to the application). The system sets permissions for all the files in an -application so that only the user ID assigned to that application can access them. </li> - -<li>Each process has its own virtual machine (VM), so an application's code runs in isolation from -other applications.</li> - -<li>By default, every application runs in its own Linux process. Android starts the process when any -of the application's components need to be executed, then shuts down the process when it's no longer -needed or when the system must recover memory for other applications.</li> -</ul> - -<p>In this way, the Android system implements the <em>principle of least privilege</em>. That is, -each application, by default, has access only to the components that it requires to do its work and -no more. This creates a very secure environment in which an application cannot access parts of -the system for which it is not given permission.</p> - -<p>However, there are ways for an application to share data with other applications and for an -application to access system services:</p> - -<ul> - <li>It's possible to arrange for two applications to share the same Linux user ID, in which case -they are able to access each other's files. To conserve system resources, applications with the -same user ID can also arrange to run in the same Linux process and share the same VM (the -applications must also be signed with the same certificate).</li> - <li>An application can request permission to access device data such as the user's -contacts, SMS messages, the mountable storage (SD card), camera, Bluetooth, and more. All -application permissions must be granted by the user at install time.</li> -</ul> - -<p>That covers the basics regarding how an Android application exists within the system. The rest of -this document introduces you to:</p> -<ul> - <li>The core framework components that define your application.</li> - <li>The manifest file in which you declare components and required device features for your -application.</li> - <li>Resources that are separate from the application code and allow your application to -gracefully optimize its behavior for a variety of device configurations.</li> -</ul> - -<!-- -<p class="note"><strong>Tip:</strong> If you're new to Android development, we suggest that you -follow the Beginner's Path link at the bottom of this page. For each document in the Application -Fundamentals, the Beginner's Path points you to the document we suggest you read next, in order -to get up to speed on the core Android concepts.</p> ---> - - -<h2 id="Components">Application Components</h2> - -<p>Application components are the essential building blocks of an Android application. Each -component is a different point through which the system can enter your application. Not all -components are actual entry points for the user and some depend on each other, but each one exists -as its own entity and plays a specific role—each one is a unique building block that -helps define your application's overall behavior.</p> - -<p>There are four different types of application components. Each type serves a distinct purpose -and has a distinct lifecycle that defines how the component is created and destroyed.</p> - -<p>Here are the four types of application components:</p> - -<dl> - -<dt><b>Activities</b></dt> - -<dd>An <i>activity</i> represents a single screen with a user interface. For example, -an email application might have one activity that shows a list of new -emails, another activity to compose an email, and another activity for reading emails. Although -the activities work together to form a cohesive user experience in the email application, each one -is independent of the others. As such, a different application can start any one of these -activities (if the email application allows it). For example, a camera application can start the -activity in the email application that composes new mail, in order for the user to share a picture. - -<p>An activity is implemented as a subclass of {@link android.app.Activity} and you can learn more -about it in the <a href="{@docRoot}guide/topics/fundamentals/activities.html">Activities</a> -developer guide.</p> -</dd> - - -<dt><b>Services</b></dt> - -<dd>A <i>service</i> is a component that runs in the background to perform long-running -operations or to perform work for remote processes. A service -does not provide a user interface. For example, a service might play music in the background while -the user is in a different application, or it might fetch data over the network without -blocking user interaction with an activity. Another component, such as an activity, can start the -service and let it run or bind to it in order to interact with it. - -<p>A service is implemented as a subclass of {@link android.app.Service} and you can learn more -about it in the <a href="{@docRoot}guide/topics/fundamentals/services.html">Services</a> developer -guide.</p> -</dd> - - -<dt><b>Content providers</b></dt> - -<dd>A <i>content provider</i> manages a shared set of application data. You can store the data in -the file system, an SQLite database, on the web, or any other persistent storage location your -application can access. Through the content provider, other applications can query or even modify -the data (if the content provider allows it). For example, the Android system provides a content -provider that manages the user's contact information. As such, any application with the proper -permissions can query part of the content provider (such as {@link -android.provider.ContactsContract.Data}) to read and write information about a particular person. - -<p>Content providers are also useful for reading and writing data that is private to your -application and not shared. For example, the <a -href="{@docRoot}resources/samples/NotePad/index.html">Note Pad</a> sample application uses a -content provider to save notes.</p> - -<p>A content provider is implemented as a subclass of {@link android.content.ContentProvider} -and must implement a standard set of APIs that enable other applications to perform -transactions. For more information, see the <a -href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> developer -guide.</p> -</dd> - - -<dt><b>Broadcast receivers</b></dt> - -<dd>A <i>broadcast receiver</i> is a component that responds to system-wide broadcast -announcements. Many broadcasts originate from the system—for example, a broadcast announcing -that the screen has turned off, the battery is low, or a picture was captured. -Applications can also initiate broadcasts—for example, to let other applications know that -some data has been downloaded to the device and is available for them to use. Although broadcast -receivers don't display a user interface, they may <a -href="{@docRoot}guide/topics/ui/notifiers/notifications.html">create a status bar notification</a> -to alert the user when a broadcast event occurs. More commonly, though, a broadcast receiver is -just a "gateway" to other components and is intended to do a very minimal amount of work. For -instance, it might initiate a service to perform some work based on the event. - -<p>A broadcast receiver is implemented as a subclass of {@link android.content.BroadcastReceiver} -and each broadcast is delivered as an {@link android.content.Intent} object. For more information, -see the {@link android.content.BroadcastReceiver} class.</p> -</dd> - -</dl> - - - -<p>A unique aspect of the Android system design is that any application can start another -application’s component. For example, if you want the user to capture a -photo with the device camera, there's probably another application that does that and your -application can use it, instead of developing an activity to capture a photo yourself. You don't -need to incorporate or even link to the code from the camera application. -Instead, you can simply start the activity in the camera application that captures a -photo. When complete, the photo is even returned to your application so you can use it. To the user, -it seems as if the camera is actually a part of your application.</p> - -<p>When the system starts a component, it starts the process for that application (if it's not -already running) and instantiates the classes needed for the component. For example, if your -application starts the activity in the camera application that captures a photo, that activity -runs in the process that belongs to the camera application, not in your application's process. -Therefore, unlike applications on most other systems, Android applications don't have a single entry -point (there's no {@code main()} function, for example).</p> - -<p>Because the system runs each application in a separate process with file permissions that -restrict access to other applications, your application cannot directly activate a component from -another application. The Android system, however, can. So, to activate a component in -another application, you must deliver a message to the system that specifies your <em>intent</em> to -start a particular component. The system then activates the component for you.</p> - - -<h3 id="ActivatingComponents">Activating Components</h3> - -<p>Three of the four component types—activities, services, and -broadcast receivers—are activated by an asynchronous message called an <em>intent</em>. -Intents bind individual components to each other at runtime (you can think of them -as the messengers that request an action from other components), whether the component belongs -to your application or another.</p> - -<p>An intent is created with an {@link android.content.Intent} object, which defines a message to -activate either a specific component or a specific <em>type</em> of component—an intent -can be either explicit or implicit, respectively.</p> - -<p>For activities and services, an intent defines the action to perform (for example, to "view" or -"send" something) and may specify the URI of the data to act on (among other things that the -component being started might need to know). For example, an intent might convey a request for an -activity to show an image or to open a web page. In some cases, you can start an -activity to receive a result, in which case, the activity also returns -the result in an {@link android.content.Intent} (for example, you can issue an intent to let -the user pick a personal contact and have it returned to you—the return intent includes a -URI pointing to the chosen contact).</p> - -<p>For broadcast receivers, the intent simply defines the -announcement being broadcast (for example, a broadcast to indicate the device battery is low -includes only a known action string that indicates "battery is low").</p> - -<p>The other component type, content provider, is not activated by intents. Rather, it is -activated when targeted by a request from a {@link android.content.ContentResolver}. The content -resolver handles all direct transactions with the content provider so that the component that's -performing transactions with the provider doesn't need to and instead calls methods on the {@link -android.content.ContentResolver} object. This leaves a layer of abstraction between the content -provider and the component requesting information (for security).</p> - -<p>There are separate methods for activating each type of component:</p> -<ul> - <li>You can start an activity (or give it something new to do) by -passing an {@link android.content.Intent} to {@link android.content.Context#startActivity -startActivity()} or {@link android.app.Activity#startActivityForResult startActivityForResult()} -(when you want the activity to return a result).</li> - <li>You can start a service (or give new instructions to an ongoing service) by -passing an {@link android.content.Intent} to {@link android.content.Context#startService -startService()}. Or you can bind to the service by passing an {@link android.content.Intent} to -{@link android.content.Context#bindService bindService()}.</li> - <li>You can initiate a broadcast by passing an {@link android.content.Intent} to methods like -{@link android.content.Context#sendBroadcast(Intent) sendBroadcast()}, {@link -android.content.Context#sendOrderedBroadcast(Intent, String) sendOrderedBroadcast()}, or {@link -android.content.Context#sendStickyBroadcast sendStickyBroadcast()}.</li> - <li>You can perform a query to a content provider by calling {@link -android.content.ContentProvider#query query()} on a {@link android.content.ContentResolver}.</li> -</ul> - -<p>For more information about using intents, see the <a -href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and -Intent Filters</a> document. More information about activating specific components is also provided -in the following documents: <a -href="{@docRoot}guide/topics/fundamentals/activities.html">Activities</a>, <a -href="{@docRoot}guide/topics/fundamentals/services.html">Services</a>, {@link -android.content.BroadcastReceiver} and <a -href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>.</p> - - -<h2 id="Manifest">The Manifest File</h2> - -<p>Before the Android system can start an application component, the system must know that the -component exists by reading the application's {@code AndroidManifest.xml} file (the "manifest" -file). Your application must declare all its components in this file, which must be at the root of -the application project directory.</p> - -<p>The manifest does a number of things in addition to declaring the application's components, -such as:</p> -<ul> - <li>Identify any user permissions the application requires, such as Internet access or -read-access to the user's contacts.</li> - <li>Declare the minimum <a href="{@docRoot}guide/appendix/api-levels.html">API Level</a> -required by the application, based on which APIs the application uses.</li> - <li>Declare hardware and software features used or required by the application, such as a camera, -bluetooth services, or a multitouch screen.</li> - <li>API libraries the application needs to be linked against (other than the Android framework -APIs), such as the <a -href="http://code.google.com/android/add-ons/google-apis/maps-overview.html">Google Maps -library</a>.</li> - <li>And more</li> -</ul> - - -<h3 id="DeclaringComponents">Declaring components</h3> - -<p>The primary task of the manifest is to inform the system about the application's components. For -example, a manifest file can declare an activity as follows: </p> - -<pre> -<?xml version="1.0" encoding="utf-8"?> -<manifest ... > - <application android:icon="@drawable/app_icon.png" ... > - <activity android:name="com.example.project.ExampleActivity" - android:label="@string/example_label" ... > - </activity> - ... - </application> -</manifest></pre> - -<p>In the <code><a -href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -element, the {@code android:icon} attribute points to resources for an icon that identifies the -application.</p> - -<p>In the <code><a -href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element, -the {@code android:name} attribute specifies the fully qualified class name of the {@link -android.app.Activity} subclass and the {@code android:label} attributes specifies a string -to use as the user-visible label for the activity.</p> - -<p>You must declare all application components this way:</p> -<ul> - <li><code><a -href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> elements -for activities</li> - <li><code><a -href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> elements for -services</li> - <li><code><a -href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> elements -for broadcast receivers</li> - <li><code><a -href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> elements -for content providers</li> -</ul> - -<p>Activities, services, and content providers that you include in your source but do not declare -in the manifest are not visible to the system and, consequently, can never run. However, -broadcast -receivers can be either declared in the manifest or created dynamically in code (as -{@link android.content.BroadcastReceiver} objects) and registered with the system by calling -{@link android.content.Context#registerReceiver registerReceiver()}.</p> - -<p>For more about how to structure the manifest file for your application, see the <a -href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a> -documentation. </p> - - - -<h3 id="DeclaringComponentCapabilities">Declaring component capabilities</h3> - -<p>As discussed above, in <a href="#ActivatingComponents">Activating Components</a>, you can use an -{@link android.content.Intent} to start activities, services, and broadcast receivers. You can do so -by explicitly naming the target component (using the component class name) in the intent. However, -the real power of intents lies in the concept of intent actions. With intent actions, you simply -describe the type of action you want to perform (and optionally, the data upon which you’d like to -perform the action) and allow the system to find a component on the device that can perform the -action and start it. If there are multiple components that can perform the action described by the -intent, then the user selects which one to use.</p> - -<p>The way the system identifies the components that can respond to an intent is by comparing the -intent received to the <i>intent filters</i> provided in the manifest file of other applications on -the device.</p> - -<p>When you declare a component in your application's manifest, you can optionally include -intent filters that declare the capabilities of the component so it can respond to intents -from other applications. You can declare an intent filter for your component by -adding an <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code -<intent-filter>}</a> element as a child of the component's declaration element.</p> - -<p>For example, an email application with an activity for composing a new email might declare an -intent filter in its manifest entry to respond to "send" intents (in order to send email). An -activity in your application can then create an intent with the “send” action ({@link -android.content.Intent#ACTION_SEND}), which the system matches to the email application’s “send” -activity and launches it when you invoke the intent with {@link android.app.Activity#startActivity -startActivity()}.</p> - -<p>For more about creating intent filters, see the <a -href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Filters</a> document. -</p> - - - -<h3 id="DeclaringRequirements">Declaring application requirements</h3> - -<p>There are a variety of devices powered by Android and not all of them provide the -same features and capabilities. In order to prevent your application from being installed on devices -that lack features needed by your application, it's important that you clearly define a profile for -the types of devices your application supports by declaring device and software requirements in your -manifest file. Most of these declarations are informational only and the system does not read -them, but external services such as Google Play do read them in order to provide filtering -for users when they search for applications from their device.</p> - -<p>For example, if your application requires a camera and uses APIs introduced in Android 2.1 (<a -href="{@docRoot}guide/appendix/api-levels.html">API Level</a> 7), you should declare these as -requirements in your manifest file. That way, devices that do <em>not</em> have a camera and have an -Android version <em>lower</em> than 2.1 cannot install your application from Google Play.</p> - -<p>However, you can also declare that your application uses the camera, but does not -<em>require</em> it. In that case, your application must perform a check at runtime to determine -if the device has a camera and disable any features that use the camera if one is not available.</p> - -<p>Here are some of the important device characteristics that you should consider as you design and -develop your application:</p> - -<dl> - <dt>Screen size and density</dt> - <dd>In order to categorize devices by their screen type, Android defines two characteristics for -each device: screen size (the physical dimensions of the screen) and screen density (the physical -density of the pixels on the screen, or dpi—dots per inch). To simplify all the different -types of screen configurations, the Android system generalizes them into select groups that make -them easier to target. -<p>The screen sizes are: small, normal, large, and extra large.<br/> -The screen densities are: low density, medium density, high density, and extra high density.</p> - -<p>By default, your application is compatible with all screen sizes and densities, -because the Android system makes the appropriate adjustments to your UI layout and image -resources. However, you should create specialized layouts for certain screen sizes and provide -specialized images for certain densities, using alternative layout resources, and by declaring in -your manifest exactly which screen sizes your application supports with the <a -href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code -<supports-screens>}</a> element.</p> -<p>For more information, see the <a -href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> -document.</p></dd> - - <dt>Input configurations</dt> - <dd>Many devices provide a different type of user input mechanism, such as a hardware keyboard, a -trackball, or a five-way navigation pad. If your application requires a particular kind of input -hardware, then you should declare it in your manifest with the <a -href="{@docRoot}guide/topics/manifest/uses-configuration-element.html">{@code -<uses-configuration>}</a> element. However, it is rare that an application should require -a certain input configuration.</dd> - - <dt>Device features</dt> - <dd>There are many hardware and software features that may or may not exist on a given -Android-powered device, such as a camera, a light sensor, bluetooth, a certain -version of OpenGL, or the fidelity of the touchscreen. You should never assume that a certain -feature is available on all Android-powered devices (other than the availability of the standard -Android library), so you should declare any features used by your application with the <a -href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> -element.</dd> - - <dt>Platform Version</dt> - <dd>Different Android-powered devices often run different versions of the Android platform, -such as Android 1.6 or Android 2.3. Each successive version often includes additional APIs not -available in the previous version. In order to indicate which set of APIs are available, each -platform version specifies an <a -href="{@docRoot}guide/appendix/api-levels.html">API Level</a> (for example, Android 1.0 is API Level -1 and Android 2.3 is API Level 9). If you use any APIs that were added to the platform after -version 1.0, you should declare the minimum API Level in which those APIs were introduced using the -<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> -element.</dd> -</dl> - -<p>It's important that you declare all such requirements for your application, because, when you -distribute your application on Google Play, the store uses these declarations to filter which -applications are available on each device. As such, your application should be available only to -devices that meet all your application requirements.</p> - -<p>For more information about how Google Play filters applications based on these (and other) -requirements, see the <a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a> -document.</p> - - - -<h2 id="Resources">Application Resources</h2> - -<p>An Android application is composed of more than just code—it requires resources that are -separate from the source code, such as images, audio files, and anything relating to the visual -presentation of the application. For example, you should define animations, menus, styles, colors, -and the layout of activity user interfaces with XML files. Using application resources makes it easy -to update various characteristics of your application without modifying code and—by providing -sets of alternative resources—enables you to optimize your application for a variety of -device configurations (such as different languages and screen sizes).</p> - -<p>For every resource that you include in your Android project, the SDK build tools define a unique -integer ID, which you can use to reference the resource from your application code or from -other resources defined in XML. For example, if your application contains an image file named {@code -logo.png} (saved in the {@code res/drawable/} directory), the SDK tools generate a resource ID -named {@code R.drawable.logo}, which you can use to reference the image and insert it in your -user interface.</p> - -<p>One of the most important aspects of providing resources separate from your source code -is the ability for you to provide alternative resources for different device -configurations. For example, by defining UI strings in XML, you can translate the strings into other -languages and save those strings in separate files. Then, based on a language <em>qualifier</em> -that you append to the resource directory's name (such as {@code res/values-fr/} for French string -values) and the user's language setting, the Android system applies the appropriate language strings -to your UI.</p> - -<p>Android supports many different <em>qualifiers</em> for your alternative resources. The -qualifier is a short string that you include in the name of your resource directories in order to -define the device configuration for which those resources should be used. As another -example, you should often create different layouts for your activities, depending on the -device's screen orientation and size. For example, when the device screen is in portrait -orientation (tall), you might want a layout with buttons to be vertical, but when the screen is in -landscape orientation (wide), the buttons should be aligned horizontally. To change the layout -depending on the orientation, you can define two different layouts and apply the appropriate -qualifier to each layout's directory name. Then, the system automatically applies the appropriate -layout depending on the current device orientation.</p> - -<p>For more about the different kinds of resources you can include in your application and how -to create alternative resources for various device configurations, see the <a -href="{@docRoot}guide/topics/resources/index.html">Application Resources</a> developer guide.</p> - - -<!-- -<h2>Beginner's Path</h2> - -<p>For a close look at implementing activities—the components your users use to -interact with your application—continue with the <b><a -href="{@docRoot}guide/topics/fundamentals/activities.html">Activities</a></b> document.</p> ---> diff --git a/docs/html/guide/topics/fundamentals/activities.jd b/docs/html/guide/topics/fundamentals/activities.jd deleted file mode 100644 index b79136c..0000000 --- a/docs/html/guide/topics/fundamentals/activities.jd +++ /dev/null @@ -1,777 +0,0 @@ -page.title=Activities -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> -<h2>Quickview</h2> -<ul> - <li>An activity provides a user interface for a single screen in your application</li> - <li>Activities can move into the background and then be resumed with their state restored</li> -</ul> - -<h2>In this document</h2> -<ol> - <li><a href="#Creating">Creating an Activity</a> - <ol> - <li><a href="#UI">Implementing a user interface</a></li> - <li><a href="#Declaring">Declaring the activity in the manifest</a></li> - </ol> - </li> - <li><a href="#StartingAnActivity">Starting an Activity</a> - <ol> - <li><a href="#StartingAnActivityForResult">Starting an activity for a result</a></li> - </ol> - </li> - <li><a href="#ShuttingDown">Shutting Down an Activity</a></li> - <li><a href="#Lifecycle">Managing the Activity Lifecycle</a> - <ol> - <li><a href="#ImplementingLifecycleCallbacks">Implementing the lifecycle callbacks</a></li> - <li><a href="#SavingActivityState">Saving activity state</a></li> - <li><a href="#ConfigurationChanges">Handling configuration changes</a></li> - <li><a href="#CoordinatingActivities">Coordinating activities</a></li> - </ol> - </li> -</ol> - -<h2>Key classes</h2> -<ol> - <li>{@link android.app.Activity}</li> -</ol> - -<h2>See also</h2> -<ol> - <li><a href="{@docRoot}resources/tutorials/hello-world.html">Hello World Tutorial</a></li> - <li><a href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back -Stack</a></li> -</ol> - -</div> -</div> - - - -<p>An {@link android.app.Activity} is an application component that provides a screen with which -users can interact in order to do something, such as dial the phone, take a photo, send an email, or -view a map. Each activity is given a window in which to draw its user interface. The window -typically fills the screen, but may be smaller than the screen and float on top of other -windows.</p> - -<p> An application usually consists of multiple activities that are loosely bound -to each other. Typically, one activity in an application is specified as the "main" activity, which -is presented to the user when launching the application for the first time. Each -activity can then start another activity in order to perform different actions. Each time a new -activity starts, the previous activity is stopped, but the system preserves the activity -in a stack (the "back stack"). When a new activity starts, it is pushed onto the back stack and -takes user focus. The back stack abides to the basic "last in, first out" stack mechanism, -so, when the user is done with the current activity and presses the <em>Back</em> button, it -is popped from the stack (and destroyed) and the previous activity resumes. (The back stack is -discussed more in the <a href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks -and Back Stack</a> document.)</p> - -<p>When an activity is stopped because a new activity starts, it is notified of this change in state -through the activity's lifecycle callback methods. -There are several callback methods that an activity might receive, due to a change in its -state—whether the system is creating it, stopping it, resuming it, or destroying it—and -each callback provides you the opportunity to perform specific work that's -appropriate to that state change. For instance, when stopped, your activity should release any -large objects, such as network or database connections. When the activity resumes, you can -reacquire the necessary resources and resume actions that were interrupted. These state transitions -are all part of the activity lifecycle.</p> - -<p>The rest of this document discusses the basics of how to build and use an activity, -including a complete discussion of how the activity lifecycle works, so you can properly manage -the transition between various activity states.</p> - - - -<h2 id="Creating">Creating an Activity</h2> - -<p>To create an activity, you must create a subclass of {@link android.app.Activity} (or -an existing subclass of it). In your subclass, you need to implement callback methods that the -system calls when the activity transitions between various states of its lifecycle, such as when -the activity is being created, stopped, resumed, or destroyed. The two most important callback -methods are:</p> - -<dl> - <dt>{@link android.app.Activity#onCreate onCreate()}</dt> - <dd>You must implement this method. The system calls this when creating your - activity. Within your implementation, you should initialize the essential components of your -activity. - Most importantly, this is where you must call {@link android.app.Activity#setContentView - setContentView()} to define the layout for the activity's user interface.</dd> - <dt>{@link android.app.Activity#onPause onPause()}</dt> - <dd>The system calls this method as the first indication that the user is leaving your -activity (though it does not always mean the activity is being destroyed). This is usually where you -should commit any changes that should be persisted beyond the current user session (because -the user might not come back).</dd> -</dl> - -<p>There are several other lifecycle callback methods that you should use in order to provide a -fluid user experience between activities and handle unexpected interuptions that cause your activity -to be stopped and even destroyed. All of the lifecycle callback methods are discussed later, in -the section about <a href="#Lifecycle">Managing the Activity Lifecycle</a>.</p> - - - -<h3 id="UI">Implementing a user interface</h3> - -<p> The user interface for an activity is provided by a hierarchy of views—objects derived -from the {@link android.view.View} class. Each view controls a particular rectangular space -within the activity's window and can respond to user interaction. For example, a view might be a -button that initiates an action when the user touches it.</p> - -<p>Android provides a number of ready-made views that you can use to design and organize your -layout. "Widgets" are views that provide a visual (and interactive) elements for the screen, such -as a button, text field, checkbox, or just an image. "Layouts" are views derived from {@link -android.view.ViewGroup} that provide a unique layout model for its child views, such as a linear -layout, a grid layout, or relative layout. You can also subclass the {@link android.view.View} and -{@link android.view.ViewGroup} classes (or existing subclasses) to create your own widgets and -layouts and apply them to your activity layout.</p> - -<p>The most common way to define a layout using views is with an XML layout file saved in your -application resources. This way, you can maintain the design of your user interface separately from -the source code that defines the activity's behavior. You can set the layout as the UI for your -activity with {@link android.app.Activity#setContentView(int) setContentView()}, passing the -resource ID for the layout. However, you can also create new {@link android.view.View}s in your -activity code and build a view hierarchy by inserting new {@link -android.view.View}s into a {@link android.view.ViewGroup}, then use that layout by passing the root -{@link android.view.ViewGroup} to {@link android.app.Activity#setContentView(View) -setContentView()}.</p> - -<p>For information about creating a user interface, see the <a -href="{@docRoot}guide/topics/ui/index.html">User Interface</a> documentation.</p> - - - -<h3 id="Declaring">Declaring the activity in the manifest</h3> - -<p>You must declare your activity in the manifest file in order for it to -be accessible to the system. To declare your activity, open your manifest file and add an <a -href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element -as a child of the <a -href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> -element. For example:</p> - -<pre> -<manifest ... > - <application ... > - <activity android:name=".ExampleActivity" /> - ... - </application ... > - ... -</manifest > -</pre> - -<p>There are several other attributes that you can include in this element, to define properties -such as the label for the activity, an icon for the activity, or a theme to style the activity's -UI. The <a href="{@docRoot}guide/topics/manifest/activity-element.html#nm">{@code android:name}</a> -attribute is the only required attribute—it specifies the class name of the activity. Once -you publish your application, you should not change this name, because if you do, you might break -some functionality, such as application shortcuts (read the blog post, <a -href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">Things -That Cannot Change</a>).</p> - -<p>See the <a -href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element -reference for more information about declaring your activity in the manifest.</p> - - -<h4>Using intent filters</h4> - -<p>An <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code -<activity>}</a> element can also specify various intent filters—using the <a -href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code -<intent-filter>}</a> element—in order to declare how other application components may -activate it.</p> - -<p>When you create a new application using the Android SDK tools, the stub activity -that's created for you automatically includes an intent filter that declares the activity -responds to the "main" action and should be placed in the "launcher" category. The intent filter -looks like this:</p> - -<pre> -<activity android:name=".ExampleActivity" android:icon="@drawable/app_icon"> - <intent-filter> - <action android:name="android.intent.action.MAIN" /> - <category android:name="android.intent.category.LAUNCHER" /> - </intent-filter> -</activity> -</pre> - -<p>The <a href="{@docRoot}guide/topics/manifest/action-element.html">{@code -<action>}</a> element specifies that this is the "main" entry point to the application. The <a -href="{@docRoot}guide/topics/manifest/category-element.html">{@code -<category>}</a> element specifies that this activity should be listed in the -system's application launcher (to allow users to launch this activity).</p> - -<p>If you intend for your application to be self-contained and not allow other applications to -activate its activities, then you don't need any other intent filters. Only one activity should -have the "main" action and "launcher" category, as in the previous example. Activities that -you don't want to make available to other applications should have no intent filters and you can -start them yourself using explicit intents (as discussed in the following section).</p> - -<p>However, if you want your activity to respond to implicit intents that are delivered from -other applications (and your own), then you must define additional intent filters for your -activity. For each type of intent to which you want to respond, you must include an <a -href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code -<intent-filter>}</a> that includes an -<a href="{@docRoot}guide/topics/manifest/action-element.html">{@code -<action>}</a> element and, optionally, a <a -href="{@docRoot}guide/topics/manifest/category-element.html">{@code -<category>}</a> element and/or a <a -href="{@docRoot}guide/topics/manifest/data-element.html">{@code -<data>}</a> element. These elements specify the type of intent to which your activity can -respond.</p> - -<p>For more information about how your activities can respond to intents, see the <a -href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Filters</a> -document.</p> - - - -<h2 id="StartingAnActivity">Starting an Activity</h2> - -<p>You can start another activity by calling {@link android.app.Activity#startActivity - startActivity()}, passing it an {@link android.content.Intent} that describes the activity you - want to start. The intent specifies either the exact activity you want to start or describes the - type of action you want to perform (and the system selects the appropriate activity for you, -which - can even be from a different application). An intent can also carry small amounts of data to be - used by the activity that is started.</p> - -<p>When working within your own application, you'll often need to simply launch a known activity. - You can do so by creating an intent that explicitly defines the activity you want to start, -using the class name. For example, here's how one activity starts another activity named {@code -SignInActivity}:</p> - -<pre> -Intent intent = new Intent(this, SignInActivity.class); -startActivity(intent); -</pre> - -<p>However, your application might also want to perform some action, such as send an email, text - message, or status update, using data from your activity. In this case, your application might - not have its own activities to perform such actions, so you can instead leverage the activities - provided by other applications on the device, which can perform the actions for you. This is where -intents are really valuable—you can create an intent that describes an action you want to -perform and the system - launches the appropriate activity from another application. If there are - multiple activities that can handle the intent, then the user can select which one to use. For - example, if you want to allow the user to send an email message, you can create the - following intent:</p> - -<pre> -Intent intent = new Intent(Intent.ACTION_SEND); -intent.putExtra(Intent.EXTRA_EMAIL, recipientArray); -startActivity(intent); -</pre> - -<p>The {@link android.content.Intent#EXTRA_EMAIL} extra added to the intent is a string array of - email addresses to which the email should be sent. When an email application responds to this - intent, it reads the string array provided in the extra and places them in the "to" field of the - email composition form. In this situation, the email application's activity starts and when the - user is done, your activity resumes.</p> - - - - -<h3 id="StartingAnActivityForResult">Starting an activity for a result</h3> - -<p>Sometimes, you might want to receive a result from the activity that you start. In that case, - start the activity by calling {@link android.app.Activity#startActivityForResult - startActivityForResult()} (instead of {@link android.app.Activity#startActivity - startActivity()}). To then receive the result from the subsequent -activity, implement the {@link android.app.Activity#onActivityResult onActivityResult()} callback - method. When the subsequent activity is done, it returns a result in an {@link -android.content.Intent} to your {@link android.app.Activity#onActivityResult onActivityResult()} -method.</p> - -<p>For example, perhaps you want the user to pick one of their contacts, so your activity can -do something with the information in that contact. Here's how you can create such an intent and -handle the result:</p> - -<pre> -private void pickContact() { - // Create an intent to "pick" a contact, as defined by the content provider URI - Intent intent = new Intent(Intent.ACTION_PICK, Contacts.CONTENT_URI); - startActivityForResult(intent, PICK_CONTACT_REQUEST); -} - -@Override -protected void onActivityResult(int requestCode, int resultCode, Intent data) { - // If the request went well (OK) and the request was PICK_CONTACT_REQUEST - if (resultCode == Activity.RESULT_OK && requestCode == PICK_CONTACT_REQUEST) { - // Perform a query to the contact's content provider for the contact's name - Cursor cursor = getContentResolver().query(data.getData(), - new String[] {Contacts.DISPLAY_NAME}, null, null, null); - if (cursor.moveToFirst()) { // True if the cursor is not empty - int columnIndex = cursor.getColumnIndex(Contacts.DISPLAY_NAME); - String name = cursor.getString(columnIndex); - // Do something with the selected contact's name... - } - } -} -</pre> - -<p>This example shows the basic logic you should use in your {@link -android.app.Activity#onActivityResult onActivityResult()} method in order to handle an -activity result. The first condition checks whether the request was successful—if it was, then -the {@code resultCode} will be {@link android.app.Activity#RESULT_OK}—and whether the request -to which this result is responding is known—in this case, the {@code requestCode} matches the -second parameter sent with {@link android.app.Activity#startActivityForResult -startActivityForResult()}. From there, the code handles the activity result by querying the -data returned in an {@link android.content.Intent} (the {@code data} parameter).</p> - -<p>What happens is, a {@link -android.content.ContentResolver} performs a query against a content provider, which returns a -{@link android.database.Cursor} that allows the queried data to be read. For more information, see -the <a -href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> document.</p> - -<p>For more information about using intents, see the <a -href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent -Filters</a> document.</p> - - -<h2 id="ShuttingDown">Shutting Down an Activity</h2> - -<p>You can shut down an activity by calling its {@link android.app.Activity#finish -finish()} method. You can also shut down a separate activity that you previously started by calling -{@link android.app.Activity#finishActivity finishActivity()}.</p> - -<p class="note"><strong>Note:</strong> In most cases, you should not explicitly finish an activity -using these methods. As discussed in the following section about the activity lifecycle, the -Android system manages the life of an activity for you, so you do not need to finish your own -activities. Calling these methods could adversely affect the expected user -experience and should only be used when you absolutely do not want the user to return to this -instance of the activity.</p> - - -<h2 id="Lifecycle">Managing the Activity Lifecycle</h2> - -<p>Managing the lifecycle of your activities by implementing callback methods is -crucial to developing a strong -and flexible application. The lifecycle of an activity is directly affected by its association with -other activities, its task and back stack.</p> - -<p>An activity can exist in essentially three states:</p> - -<dl> - <dt><i>Resumed</i></dt> - <dd>The activity is in the foreground of the screen and has user focus. (This state is -also sometimes referred to as "running".)</dd> - - <dt><i>Paused</i></dt> - <dd>Another activity is in the foreground and has focus, but this one is still visible. That is, -another activity is visible on top of this one and that activity is partially transparent or doesn't -cover the entire screen. A paused activity is completely alive (the {@link android.app.Activity} -object is retained in memory, it maintains all state and member information, and remains attached to -the window manager), but can be killed by the system in extremely low memory situations.</dd> - - <dt><i>Stopped</i></dt> - <dd>The activity is completely obscured by another activity (the activity is now in the -"background"). A stopped activity is also still alive (the {@link android.app.Activity} -object is retained in memory, it maintains all state and member information, but is <em>not</em> -attached to the window manager). However, it is no longer visible to the user and it -can be killed by the system when memory is needed elsewhere.</dd> -</dl> - -<p>If an activity is paused or stopped, the system can drop it from memory either by asking it to -finish (calling its {@link android.app.Activity#finish finish()} method), or simply killing its -process. When the activity is opened again (after being finished or killed), it must be created all -over.</p> - - - -<h3 id="ImplementingLifecycleCallbacks">Implementing the lifecycle callbacks</h3> - -<p>When an activity transitions into and out of the different states described above, it is notified -through various callback methods. All of the callback methods are hooks that you -can override to do appropriate work when the state of your activity changes. The following skeleton -activity includes each of the fundamental lifecycle methods:</p> - - -<pre> -public class ExampleActivity extends Activity { - @Override - public void {@link android.app.Activity#onCreate onCreate}(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - // The activity is being created. - } - @Override - protected void {@link android.app.Activity#onStart onStart()} { - super.onStart(); - // The activity is about to become visible. - } - @Override - protected void {@link android.app.Activity#onResume onResume()} { - super.onResume(); - // The activity has become visible (it is now "resumed"). - } - @Override - protected void {@link android.app.Activity#onPause onPause()} { - super.onPause(); - // Another activity is taking focus (this activity is about to be "paused"). - } - @Override - protected void {@link android.app.Activity#onStop onStop()} { - super.onStop(); - // The activity is no longer visible (it is now "stopped") - } - @Override - protected void {@link android.app.Activity#onDestroy onDestroy()} { - super.onDestroy(); - // The activity is about to be destroyed. - } -} -</pre> - -<p class="note"><strong>Note:</strong> Your implementation of these lifecycle methods must -always call the superclass implementation before doing any work, as shown in the examples above.</p> - -<p>Taken together, these methods define the entire lifecycle of an activity. By implementing these -methods, you can monitor three nested loops in the activity lifecycle: </p> - -<ul> -<li>The <b>entire lifetime</b> of an activity happens between the call to {@link -android.app.Activity#onCreate onCreate()} and the call to {@link -android.app.Activity#onDestroy}. Your activity should perform setup of -"global" state (such as defining layout) in {@link android.app.Activity#onCreate onCreate()}, and -release all remaining resources in {@link android.app.Activity#onDestroy}. For example, if your -activity has a thread running in the background to download data from the network, it might create -that thread in {@link android.app.Activity#onCreate onCreate()} and then stop the thread in {@link -android.app.Activity#onDestroy}.</li> - -<li><p>The <b>visible lifetime</b> of an activity happens between the call to {@link -android.app.Activity#onStart onStart()} and the call to {@link -android.app.Activity#onStop onStop()}. During this time, the user can see the activity -on-screen and interact with it. For example, {@link android.app.Activity#onStop onStop()} is called -when a new activity starts and this one is no longer visible. Between these two methods, you can -maintain resources that are needed to show the activity to the user. For example, you can register a -{@link android.content.BroadcastReceiver} in {@link -android.app.Activity#onStart onStart()} to monitor changes that impact your UI, and unregister -it in {@link android.app.Activity#onStop onStop()} when the user can no longer see what you are -displaying. The system might call {@link android.app.Activity#onStart onStart()} and {@link -android.app.Activity#onStop onStop()} multiple times during the entire lifetime of the activity, as -the activity alternates between being visible and hidden to the user.</p></li> - -<li><p>The <b>foreground lifetime</b> of an activity happens between the call to {@link -android.app.Activity#onResume onResume()} and the call to {@link android.app.Activity#onPause -onPause()}. During this time, the activity is in front of all other activities on screen and has -user input focus. An activity can frequently transition in and out of the foreground—for -example, {@link android.app.Activity#onPause onPause()} is called when the device goes to sleep or -when a dialog appears. Because this state can transition often, the code in these two methods should -be fairly lightweight in order to avoid slow transitions that make the user wait.</p></li> -</ul> - -<p>Figure 1 illustrates these loops and the paths an activity might take between states. -The rectangles represent the callback methods you can implement to perform operations when -the activity transitions between states. <p> - -<img src="{@docRoot}images/activity_lifecycle.png" alt="" /> -<p class="img-caption"><strong>Figure 1.</strong> The activity lifecycle.</p> - -<p>The same lifecycle callback methods are listed in table 1, which describes each of the callback -methods in more detail and locates each one within the -activity's overall lifecycle, including whether the system can kill the activity after the -callback method completes.</p> - -<p class="table-caption"><strong>Table 1.</strong> A summary of the activity lifecycle's -callback methods.</p> - -<table border="2" width="85%" frame="hsides" rules="rows"> -<colgroup align="left" span="3"></colgroup> -<colgroup align="left"></colgroup> -<colgroup align="center"></colgroup> -<colgroup align="center"></colgroup> - -<thead> -<tr><th colspan="3">Method</th> <th>Description</th> <th>Killable after?</th> <th>Next</th></tr> -</thead> - -<tbody> -<tr> - <td colspan="3" align="left"><code>{@link android.app.Activity#onCreate onCreate()}</code></td> - <td>Called when the activity is first created. - This is where you should do all of your normal static set up — - create views, bind data to lists, and so on. This method is passed - a Bundle object containing the activity's previous state, if that - state was captured (see <a href="#actstate">Saving Activity State</a>, - later). - <p>Always followed by {@code onStart()}.</p></td> - <td align="center">No</td> - <td align="center">{@code onStart()}</td> -</tr> - -<tr> - <td rowspan="5" style="border-left: none; border-right: none;"> </td> - <td colspan="2" align="left"><code>{@link android.app.Activity#onRestart -onRestart()}</code></td> - <td>Called after the activity has been stopped, just prior to it being - started again. - <p>Always followed by {@code onStart()}</p></td> - <td align="center">No</td> - <td align="center">{@code onStart()}</td> -</tr> - -<tr> - <td colspan="2" align="left"><code>{@link android.app.Activity#onStart onStart()}</code></td> - <td>Called just before the activity becomes visible to the user. - <p>Followed by {@code onResume()} if the activity comes - to the foreground, or {@code onStop()} if it becomes hidden.</p></td> - <td align="center">No</td> - <td align="center">{@code onResume()} <br/>or<br/> {@code onStop()}</td> -</tr> - -<tr> - <td rowspan="2" style="border-left: none;"> </td> - <td align="left"><code>{@link android.app.Activity#onResume onResume()}</code></td> - <td>Called just before the activity starts - interacting with the user. At this point the activity is at - the top of the activity stack, with user input going to it. - <p>Always followed by {@code onPause()}.</p></td> - <td align="center">No</td> - <td align="center">{@code onPause()}</td> -</tr> - -<tr> - <td align="left"><code>{@link android.app.Activity#onPause onPause()}</code></td> - <td>Called when the system is about to start resuming another - activity. This method is typically used to commit unsaved changes to - persistent data, stop animations and other things that may be consuming - CPU, and so on. It should do whatever it does very quickly, because - the next activity will not be resumed until it returns. - <p>Followed either by {@code onResume()} if the activity - returns back to the front, or by {@code onStop()} if it becomes - invisible to the user.</td> - <td align="center"><strong style="color:#800000">Yes</strong></td> - <td align="center">{@code onResume()} <br/>or<br/> {@code onStop()}</td> -</tr> - -<tr> - <td colspan="2" align="left"><code>{@link android.app.Activity#onStop onStop()}</code></td> - <td>Called when the activity is no longer visible to the user. This - may happen because it is being destroyed, or because another activity - (either an existing one or a new one) has been resumed and is covering it. - <p>Followed either by {@code onRestart()} if - the activity is coming back to interact with the user, or by - {@code onDestroy()} if this activity is going away.</p></td> - <td align="center"><strong style="color:#800000">Yes</strong></td> - <td align="center">{@code onRestart()} <br/>or<br/> {@code onDestroy()}</td> -</tr> - -<tr> - <td colspan="3" align="left"><code>{@link android.app.Activity#onDestroy -onDestroy()}</code></td> - <td>Called before the activity is destroyed. This is the final call - that the activity will receive. It could be called either because the - activity is finishing (someone called <code>{@link android.app.Activity#finish - finish()}</code> on it), or because the system is temporarily destroying this - instance of the activity to save space. You can distinguish - between these two scenarios with the <code>{@link - android.app.Activity#isFinishing isFinishing()}</code> method.</td> - <td align="center"><strong style="color:#800000">Yes</strong></td> - <td align="center"><em>nothing</em></td> -</tr> -</tbody> -</table> - -<p>The column labeled "Killable after?" indicates whether or not the system can -kill the process hosting the activity at any time <em>after the method returns</em>, without -executing another line of the activity's code. Three methods are marked "yes": ({@link -android.app.Activity#onPause -onPause()}, {@link android.app.Activity#onStop onStop()}, and {@link android.app.Activity#onDestroy -onDestroy()}). Because {@link android.app.Activity#onPause onPause()} is the first -of the three, once the activity is created, {@link android.app.Activity#onPause onPause()} is the -last method that's guaranteed to be called before the process <em>can</em> be killed—if -the system must recover memory in an emergency, then {@link -android.app.Activity#onStop onStop()} and {@link android.app.Activity#onDestroy onDestroy()} might -not be called. Therefore, you should use {@link android.app.Activity#onPause onPause()} to write -crucial persistent data (such as user edits) to storage. However, you should be selective about -what information must be retained during {@link android.app.Activity#onPause onPause()}, because any -blocking procedures in this method block the transition to the next activity and slow the user -experience.</p> - -<p> Methods that are marked "No" in the <b>Killable</b> column protect the process hosting the -activity from being killed from the moment they are called. Thus, an activity is killable -from the time {@link android.app.Activity#onPause onPause()} returns to the time -{@link android.app.Activity#onResume onResume()} is called. It will not again be killable until -{@link android.app.Activity#onPause onPause()} is again called and returns. </p> - -<p class="note"><strong>Note:</strong> An activity that's not technically "killable" by this -definition in table 1 might still be killed by the system—but that would happen only in -extreme circumstances when there is no other recourse. When an activity might be killed is -discussed more in the <a -href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html">Processes and -Threading</a> document.</p> - - -<h3 id="SavingActivityState">Saving activity state</h3> - -<p>The introduction to <a href="#Lifecycle">Managing the Activity Lifecycle</a> briefly mentions -that -when an activity is paused or stopped, the state of the activity is retained. This is true because -the {@link android.app.Activity} object is still held in memory when it is paused or -stopped—all information about its members and current state is still alive. Thus, any changes -the user made within the activity are retained so that when the activity returns to the -foreground (when it "resumes"), those changes are still there.</p> - -<p>However, when the system destroys an activity in order to recover memory, the {@link -android.app.Activity} object is destroyed, so the system cannot simply resume it with its state -intact. Instead, the system must recreate the {@link android.app.Activity} object if the user -navigates back to it. Yet, the user is unaware -that the system destroyed the activity and recreated it and, thus, probably -expects the activity to be exactly as it was. In this situation, you can ensure that -important information about the activity state is preserved by implementing an additional -callback method that allows you to save information about the state of your activity: {@link -android.app.Activity#onSaveInstanceState onSaveInstanceState()}.</p> - -<p>The system calls {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} -before making the activity vulnerable to destruction. The system passes this method -a {@link android.os.Bundle} in which you can save -state information about the activity as name-value pairs, using methods such as {@link -android.os.Bundle#putString putString()} and {@link -android.os.Bundle#putInt putInt()}. Then, if the system kills your application -process and the user navigates back to your activity, the system recreates the activity and passes -the {@link android.os.Bundle} to both {@link android.app.Activity#onCreate onCreate()} and {@link -android.app.Activity#onRestoreInstanceState onRestoreInstanceState()}. Using either of these -methods, you can extract your saved state from the {@link android.os.Bundle} and restore the -activity state. If there is no state information to restore, then the {@link -android.os.Bundle} passed to you is null (which is the case when the activity is created for -the first time).</p> - -<img src="{@docRoot}images/fundamentals/restore_instance.png" alt="" /> -<p class="img-caption"><strong>Figure 2.</strong> The two ways in which an activity returns to user -focus with its state intact: either the activity is destroyed, then recreated and the activity must restore -the previously saved state, or the activity is stopped, then resumed and the activity state -remains intact.</p> - -<p class="note"><strong>Note:</strong> There's no guarantee that {@link -android.app.Activity#onSaveInstanceState onSaveInstanceState()} will be called before your -activity is destroyed, because there are cases in which it won't be necessary to save the state -(such as when the user leaves your activity using the <em>Back</em> button, because the user is -explicitly -closing the activity). If the system calls {@link android.app.Activity#onSaveInstanceState -onSaveInstanceState()}, it does so before {@link -android.app.Activity#onStop onStop()} and possibly before {@link android.app.Activity#onPause -onPause()}.</p> - -<p>However, even if you do nothing and do not implement {@link -android.app.Activity#onSaveInstanceState onSaveInstanceState()}, some of the activity state is -restored by the {@link android.app.Activity} class's default implementation of {@link -android.app.Activity#onSaveInstanceState onSaveInstanceState()}. Specifically, the default -implementation calls the corresponding {@link -android.view.View#onSaveInstanceState onSaveInstanceState()} method for every {@link -android.view.View} in the layout, which allows each view to provide information about itself -that should be saved. Almost every widget in the Android framework implements this method as -appropriate, such that any visible changes to the UI are automatically saved and restored when your -activity is recreated. For example, the {@link android.widget.EditText} widget saves any text -entered by the user and the {@link android.widget.CheckBox} widget saves whether it's checked or -not. The only work required by you is to provide a unique ID (with the <a -href="{@docRoot}guide/topics/resources/layout-resource.html#idvalue">{@code android:id}</a> -attribute) for each widget you want to save its state. If a widget does not have an ID, then the -system cannot save its state.</p> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<p>You can also explicitly stop a view in your layout from saving its state by setting the -{@link android.R.attr#saveEnabled android:saveEnabled} attribute to {@code "false"} or by calling -the {@link android.view.View#setSaveEnabled setSaveEnabled()} method. Usually, you should not -disable this, but you might if you want to restore the state of the activity UI differently.</p> -</div> -</div> - -<p>Although the default implementation of {@link -android.app.Activity#onSaveInstanceState onSaveInstanceState()} saves useful information about -your activity's UI, you still might need to override it to save additional information. -For example, you might need to save member values that changed during the activity's life (which -might correlate to values restored in the UI, but the members that hold those UI values are not -restored, by default).</p> - -<p>Because the default implementation of {@link -android.app.Activity#onSaveInstanceState onSaveInstanceState()} helps save the state of the UI, if -you override the method in order to save additional state information, you should always call the -superclass implementation of {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} -before doing any work. Likewise, you should also call the supercall implementation of {@link -android.app.Activity#onRestoreInstanceState onRestoreInstanceState()} if you override it, so the -default implementation can restore view states.</p> - -<p class="note"><strong>Note:</strong> Because {@link android.app.Activity#onSaveInstanceState -onSaveInstanceState()} is not guaranteed -to be called, you should use it only to record the transient state of the activity (the state of -the UI)—you should never use it to store persistent data. Instead, you should use {@link -android.app.Activity#onPause onPause()} to store persistent data (such as data that should be saved -to a database) when the user leaves the activity.</p> - -<p>A good way to test your application's ability to restore its state is to simply rotate the -device so that the screen orientation changes. When the screen orientation changes, the system -destroys and recreates the activity in order to apply alternative resources that might be available -for the new screen configuration. For this reason alone, it's very important that your activity -completely restores its state when it is recreated, because users regularly rotate the screen while -using applications.</p> - - -<h3 id="ConfigurationChanges">Handling configuration changes</h3> - -<p>Some device configurations can change during runtime (such as screen orientation, keyboard -availability, and language). When such a change occurs, Android recreates the running activity -(the system calls {@link android.app.Activity#onDestroy}, then immediately calls {@link -android.app.Activity#onCreate onCreate()}). This behavior is -designed to help your application adapt to new configurations by automatically reloading your -application with alternative resources that you've provided (such as different layouts for -different screen orientations and sizes).</p> - -<p>If you properly design your activity to handle a restart due to a screen orientation change and -restore the activity state as described above, your application will be more resilient to other -unexpected events in the activity lifecycle.</p> - -<p>The best way to handle such a restart is - to save and restore the state of your activity using {@link - android.app.Activity#onSaveInstanceState onSaveInstanceState()} and {@link -android.app.Activity#onRestoreInstanceState onRestoreInstanceState()} (or {@link -android.app.Activity#onCreate onCreate()}), as discussed in the previous section.</p> - -<p>For more information about configuration changes that happen at runtime and how you can handle -them, read the guide to <a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling -Runtime Changes</a>.</p> - - - -<h3 id="CoordinatingActivities">Coordinating activities</h3> - - <p>When one activity starts another, they both experience lifecycle transitions. The first activity -pauses and stops (though, it won't stop if it's still visible in the background), while the other -activity is created. In case these activities share data saved to disc or elsewhere, it's important -to understand that the first activity is not completely stopped before the second one is created. -Rather, the process of starting the second one overlaps with the process of stopping the first -one.</p> - -<p>The order of lifecycle callbacks is well defined, particularly when the two activities are in the -same process and one is starting the other. Here's the order of operations that occur when Activity -A starts Acivity B: </p> - -<ol> -<li>Activity A's {@link android.app.Activity#onPause onPause()} method executes.</li> - -<li>Activity B's {@link android.app.Activity#onCreate onCreate()}, {@link -android.app.Activity#onStart onStart()}, and {@link android.app.Activity#onResume onResume()} -methods execute in sequence. (Activity B now has user focus.)</li> - -<li>Then, if Activity A is no longer visible on screen, its {@link -android.app.Activity#onStop onStop()} method executes.</li> -</ol> - - <p>This predictable sequence of lifecycle callbacks allows you to manage the transition of -information from one activity to another. For example, if you must write to a database when the -first activity stops so that the following activity can read it, then you should write to the -database during {@link android.app.Activity#onPause onPause()} instead of during {@link -android.app.Activity#onStop onStop()}.</p> - -<!-- -<h2>Beginner's Path</h2> - -<p>For more information about how Android maintains a history of activities and -enables user multitasking, continue with the <b><a -href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back -Stack</a></b> document.</p> --->
\ No newline at end of file diff --git a/docs/html/guide/topics/fundamentals/bound-services.jd b/docs/html/guide/topics/fundamentals/bound-services.jd deleted file mode 100644 index ec7d723..0000000 --- a/docs/html/guide/topics/fundamentals/bound-services.jd +++ /dev/null @@ -1,675 +0,0 @@ -page.title=Bound Services -parent.title=Services -parent.link=services.html -@jd:body - - -<div id="qv-wrapper"> -<ol id="qv"> -<h2>Quickview</h2> -<ul> - <li>A bound service allows other components to bind to it, in order to interact with it and -perform interprocess communication</li> - <li>A bound service is destroyed once all clients unbind, unless the service was also started</li> -</ul> -<h2>In this document</h2> -<ol> - <li><a href="#Basics">The Basics</a></li> - <li><a href="#Creating">Creating a Bound Service</a> - <ol> - <li><a href="#Binder">Extending the Binder class</a></li> - <li><a href="#Messenger">Using a Messenger</a></li> - </ol> - </li> - <li><a href="#Binding">Binding to a Service</a></li> - <li><a href="#Lifecycle">Managing the Lifecycle of a Bound Service</a></li> -</ol> - -<h2>Key classes</h2> -<ol> - <li>{@link android.app.Service}</li> - <li>{@link android.content.ServiceConnection}</li> - <li>{@link android.os.IBinder}</li> -</ol> - -<h2>Samples</h2> -<ol> - <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.html">{@code - RemoteService}</a></li> - <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalService.html">{@code - LocalService}</a></li> -</ol> - -<h2>See also</h2> -<ol> - <li><a href="{@docRoot}guide/topics/fundamentals/services.html">Services</a></li> -</ol> -</div> - - -<p>A bound service is the server in a client-server interface. A bound service allows components -(such as activities) to bind to the service, send requests, receive responses, and even perform -interprocess communication (IPC). A bound service typically lives only while it serves another -application component and does not run in the background indefinitely.</p> - -<p>This document shows you how to create a bound service, including how to bind -to the service from other application components. However, you should also refer to the <a -href="{@docRoot}guide/topics/fundamentals/services.html">Services</a> document for additional -information about services in general, such as how to deliver notifications from a service, set -the service to run in the foreground, and more.</p> - - -<h2 id="Basics">The Basics</h2> - -<p>A bound service is an implementation of the {@link android.app.Service} class that allows -other applications to bind to it and interact with it. To provide binding for a -service, you must implement the {@link android.app.Service#onBind onBind()} callback method. This -method returns an {@link android.os.IBinder} object that defines the programming interface that -clients can use to interact with the service.</p> - -<div class="sidebox-wrapper"> -<div class="sidebox"> - <h3>Binding to a Started Service</h3> - -<p>As discussed in the <a href="{@docRoot}guide/topics/fundamentals/services.html">Services</a> -document, you can create a service that is both started and bound. That is, the service can be -started by calling {@link android.content.Context#startService startService()}, which allows the -service to run indefinitely, and also allow a client to bind to the service by calling {@link -android.content.Context#bindService bindService()}. - <p>If you do allow your service to be started and bound, then when the service has been -started, the system does <em>not</em> destroy the service when all clients unbind. Instead, you must -explicitly stop the service, by calling {@link android.app.Service#stopSelf stopSelf()} or {@link -android.content.Context#stopService stopService()}.</p> - -<p>Although you should usually implement either {@link android.app.Service#onBind onBind()} -<em>or</em> {@link android.app.Service#onStartCommand onStartCommand()}, it's sometimes necessary to -implement both. For example, a music player might find it useful to allow its service to run -indefinitely and also provide binding. This way, an activity can start the service to play some -music and the music continues to play even if the user leaves the application. Then, when the user -returns to the application, the activity can bind to the service to regain control of playback.</p> - -<p>Be sure to read the section about <a href="#Lifecycle">Managing the Lifecycle of a Bound -Service</a>, for more information about the service lifecycle when adding binding to a -started service.</p> -</div> -</div> - -<p>A client can bind to the service by calling {@link android.content.Context#bindService -bindService()}. When it does, it must provide an implementation of {@link -android.content.ServiceConnection}, which monitors the connection with the service. The {@link -android.content.Context#bindService bindService()} method returns immediately without a value, but -when the Android system creates the connection between the -client and service, it calls {@link -android.content.ServiceConnection#onServiceConnected onServiceConnected()} on the {@link -android.content.ServiceConnection}, to deliver the {@link android.os.IBinder} that -the client can use to communicate with the service.</p> - -<p>Multiple clients can connect to the service at once. However, the system calls your service's -{@link android.app.Service#onBind onBind()} method to retrieve the {@link android.os.IBinder} only -when the first client binds. The system then delivers the same {@link android.os.IBinder} to any -additional clients that bind, without calling {@link android.app.Service#onBind onBind()} again.</p> - -<p>When the last client unbinds from the service, the system destroys the service (unless the -service was also started by {@link android.content.Context#startService startService()}).</p> - -<p>When you implement your bound service, the most important part is defining the interface -that your {@link android.app.Service#onBind onBind()} callback method returns. There are a few -different ways you can define your service's {@link android.os.IBinder} interface and the following -section discusses each technique.</p> - - - -<h2 id="Creating">Creating a Bound Service</h2> - -<p>When creating a service that provides binding, you must provide an {@link android.os.IBinder} -that provides the programming interface that clients can use to interact with the service. There -are three ways you can define the interface:</p> - -<dl> - <dt><a href="#Binder">Extending the Binder class</a></dt> - <dd>If your service is private to your own application and runs in the same process as the client -(which is common), you should create your interface by extending the {@link android.os.Binder} class -and returning an instance of it from -{@link android.app.Service#onBind onBind()}. The client receives the {@link android.os.Binder} and -can use it to directly access public methods available in either the {@link android.os.Binder} -implementation or even the {@link android.app.Service}. - <p>This is the preferred technique when your service is merely a background worker for your own -application. The only reason you would not create your interface this way is because -your service is used by other applications or across separate processes.</dd> - - <dt><a href="#Messenger">Using a Messenger</a></dt> - <dd>If you need your interface to work across different processes, you can create -an interface for the service with a {@link android.os.Messenger}. In this manner, the service -defines a {@link android.os.Handler} that responds to different types of {@link -android.os.Message} objects. This {@link android.os.Handler} -is the basis for a {@link android.os.Messenger} that can then share an {@link android.os.IBinder} -with the client, allowing the client to send commands to the service using {@link -android.os.Message} objects. Additionally, the client can define a {@link android.os.Messenger} of -its own so the service can send messages back. - <p>This is the simplest way to perform interprocess communication (IPC), because the {@link -android.os.Messenger} queues all requests into a single thread so that you don't have to design -your service to be thread-safe.</p> - </dd> - - <dt>Using AIDL</dt> - <dd>AIDL (Android Interface Definition Language) performs all the work to decompose objects into -primitives that the operating system can understand and marshall them across processes to perform -IPC. The previous technique, using a {@link android.os.Messenger}, is actually based on AIDL as -its underlying structure. As mentioned above, the {@link android.os.Messenger} creates a queue of -all the client requests in a single thread, so the service receives requests one at a time. If, -however, you want your service to handle multiple requests simultaneously, then you can use AIDL -directly. In this case, your service must be capable of multi-threading and be built thread-safe. - <p>To use AIDL directly, you must -create an {@code .aidl} file that defines the programming interface. The Android SDK tools use -this file to generate an abstract class that implements the interface and handles IPC, which you -can then extend within your service.</p> - </dd> -</dl> - - <p class="note"><strong>Note:</strong> Most applications <strong>should not</strong> use AIDL to -create a bound service, because it may require multithreading capabilities and -can result in a more complicated implementation. As such, AIDL is not suitable for most applications -and this document does not discuss how to use it for your service. If you're certain that you need -to use AIDL directly, see the <a href="{@docRoot}guide/developing/tools/aidl.html">AIDL</a> -document.</p> - - - - -<h3 id="Binder">Extending the Binder class</h3> - -<p>If your service is used only by the local application and does not need to work across processes, -then you can implement your own {@link android.os.Binder} class that provides your client direct -access to public methods in the service.</p> - -<p class="note"><strong>Note:</strong> This works only if the client and service are in the same -application and process, which is most common. For example, this would work well for a music -application that needs to bind an activity to its own service that's playing music in the -background.</p> - -<p>Here's how to set it up:</p> -<ol> - <li>In your service, create an instance of {@link android.os.Binder} that either: - <ul> - <li>contains public methods that the client can call</li> - <li>returns the current {@link android.app.Service} instance, which has public methods the -client can call</li> - <li>or, returns an instance of another class hosted by the service with public methods the -client can call</li> - </ul> - <li>Return this instance of {@link android.os.Binder} from the {@link -android.app.Service#onBind onBind()} callback method.</li> - <li>In the client, receive the {@link android.os.Binder} from the {@link -android.content.ServiceConnection#onServiceConnected onServiceConnected()} callback method and -make calls to the bound service using the methods provided.</li> -</ol> - -<p class="note"><strong>Note:</strong> The reason the service and client must be in the same -application is so the client can cast the returned object and properly call its APIs. The service -and client must also be in the same process, because this technique does not perform any -marshalling across processes.</p> - -<p>For example, here's a service that provides clients access to methods in the service through -a {@link android.os.Binder} implementation:</p> - -<pre> -public class LocalService extends Service { - // Binder given to clients - private final IBinder mBinder = new LocalBinder(); - // Random number generator - private final Random mGenerator = new Random(); - - /** - * Class used for the client Binder. Because we know this service always - * runs in the same process as its clients, we don't need to deal with IPC. - */ - public class LocalBinder extends Binder { - LocalService getService() { - // Return this instance of LocalService so clients can call public methods - return LocalService.this; - } - } - - @Override - public IBinder onBind(Intent intent) { - return mBinder; - } - - /** method for clients */ - public int getRandomNumber() { - return mGenerator.nextInt(100); - } -} -</pre> - -<p>The {@code LocalBinder} provides the {@code getService()} method for clients to retrieve the -current instance of {@code LocalService}. This allows clients to call public methods in the -service. For example, clients can call {@code getRandomNumber()} from the service.</p> - -<p>Here's an activity that binds to {@code LocalService} and calls {@code getRandomNumber()} -when a button is clicked:</p> - -<pre> -public class BindingActivity extends Activity { - LocalService mService; - boolean mBound = false; - - @Override - protected void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - setContentView(R.layout.main); - } - - @Override - protected void onStart() { - super.onStart(); - // Bind to LocalService - Intent intent = new Intent(this, LocalService.class); - bindService(intent, mConnection, Context.BIND_AUTO_CREATE); - } - - @Override - protected void onStop() { - super.onStop(); - // Unbind from the service - if (mBound) { - unbindService(mConnection); - mBound = false; - } - } - - /** Called when a button is clicked (the button in the layout file attaches to - * this method with the android:onClick attribute) */ - public void onButtonClick(View v) { - if (mBound) { - // Call a method from the LocalService. - // However, if this call were something that might hang, then this request should - // occur in a separate thread to avoid slowing down the activity performance. - int num = mService.getRandomNumber(); - Toast.makeText(this, "number: " + num, Toast.LENGTH_SHORT).show(); - } - } - - /** Defines callbacks for service binding, passed to bindService() */ - private ServiceConnection mConnection = new ServiceConnection() { - - @Override - public void onServiceConnected(ComponentName className, - IBinder service) { - // We've bound to LocalService, cast the IBinder and get LocalService instance - LocalBinder binder = (LocalBinder) service; - mService = binder.getService(); - mBound = true; - } - - @Override - public void onServiceDisconnected(ComponentName arg0) { - mBound = false; - } - }; -} -</pre> - -<p>The above sample shows how the client binds to the service using an implementation of -{@link android.content.ServiceConnection} and the {@link -android.content.ServiceConnection#onServiceConnected onServiceConnected()} callback. The next -section provides more information about this process of binding to the service.</p> - -<p class="note"><strong>Note:</strong> The example above doesn't explicitly unbind from the service, -but all clients should unbind at an appropriate time (such as when the activity pauses).</p> - -<p>For more sample code, see the <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalService.html">{@code -LocalService.java}</a> class and the <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalServiceActivities.html">{@code -LocalServiceActivities.java}</a> class in <a -href="{@docRoot}resources/samples/ApiDemos/index.html">ApiDemos</a>.</p> - - - - - -<h3 id="Messenger">Using a Messenger</h3> - -<div class="sidebox-wrapper"> -<div class="sidebox"> - <h4>Compared to AIDL</h4> - <p>When you need to perform IPC, using a {@link android.os.Messenger} for your interface is -simpler than implementing it with AIDL, because {@link android.os.Messenger} queues -all calls to the service, whereas, a pure AIDL interface sends simultaneous requests to the -service, which must then handle multi-threading.</p> - <p>For most applications, the service doesn't need to perform multi-threading, so using a {@link -android.os.Messenger} allows the service to handle one call at a time. If it's important -that your service be multi-threaded, then you should use <a -href="{@docRoot}guide/developing/tools/aidl.html">AIDL</a> to define your interface.</p> -</div> -</div> - -<p>If you need your service to communicate with remote processes, then you can use a -{@link android.os.Messenger} to provide the interface for your service. This technique allows -you to perform interprocess communication (IPC) without the need to use AIDL.</p> - -<p>Here's a summary of how to use a {@link android.os.Messenger}:</p> - -<ul> - <li>The service implements a {@link android.os.Handler} that receives a callback for each -call from a client.</li> - <li>The {@link android.os.Handler} is used to create a {@link android.os.Messenger} object -(which is a reference to the {@link android.os.Handler}).</li> - <li>The {@link android.os.Messenger} creates an {@link android.os.IBinder} that the service -returns to clients from {@link android.app.Service#onBind onBind()}.</li> - <li>Clients use the {@link android.os.IBinder} to instantiate the {@link android.os.Messenger} -(that references the service's {@link android.os.Handler}), which the client uses to send -{@link android.os.Message} objects to the service.</li> - <li>The service receives each {@link android.os.Message} in its {@link -android.os.Handler}—specifically, in the {@link android.os.Handler#handleMessage -handleMessage()} method.</li> -</ul> - - -<p>In this way, there are no "methods" for the client to call on the service. Instead, the -client delivers "messages" ({@link android.os.Message} objects) that the service receives in -its {@link android.os.Handler}.</p> - -<p>Here's a simple example service that uses a {@link android.os.Messenger} interface:</p> - -<pre> -public class MessengerService extends Service { - /** Command to the service to display a message */ - static final int MSG_SAY_HELLO = 1; - - /** - * Handler of incoming messages from clients. - */ - class IncomingHandler extends Handler { - @Override - public void handleMessage(Message msg) { - switch (msg.what) { - case MSG_SAY_HELLO: - Toast.makeText(getApplicationContext(), "hello!", Toast.LENGTH_SHORT).show(); - break; - default: - super.handleMessage(msg); - } - } - } - - /** - * Target we publish for clients to send messages to IncomingHandler. - */ - final Messenger mMessenger = new Messenger(new IncomingHandler()); - - /** - * When binding to the service, we return an interface to our messenger - * for sending messages to the service. - */ - @Override - public IBinder onBind(Intent intent) { - Toast.makeText(getApplicationContext(), "binding", Toast.LENGTH_SHORT).show(); - return mMessenger.getBinder(); - } -} -</pre> - -<p>Notice that the {@link android.os.Handler#handleMessage handleMessage()} method in the -{@link android.os.Handler} is where the service receives the incoming {@link android.os.Message} -and decides what to do, based on the {@link android.os.Message#what} member.</p> - -<p>All that a client needs to do is create a {@link android.os.Messenger} based on the {@link -android.os.IBinder} returned by the service and send a message using {@link -android.os.Messenger#send send()}. For example, here's a simple activity that binds to the -service and delivers the {@code MSG_SAY_HELLO} message to the service:</p> - -<pre> -public class ActivityMessenger extends Activity { - /** Messenger for communicating with the service. */ - Messenger mService = null; - - /** Flag indicating whether we have called bind on the service. */ - boolean mBound; - - /** - * Class for interacting with the main interface of the service. - */ - private ServiceConnection mConnection = new ServiceConnection() { - public void onServiceConnected(ComponentName className, IBinder service) { - // This is called when the connection with the service has been - // established, giving us the object we can use to - // interact with the service. We are communicating with the - // service using a Messenger, so here we get a client-side - // representation of that from the raw IBinder object. - mService = new Messenger(service); - mBound = true; - } - - public void onServiceDisconnected(ComponentName className) { - // This is called when the connection with the service has been - // unexpectedly disconnected -- that is, its process crashed. - mService = null; - mBound = false; - } - }; - - public void sayHello(View v) { - if (!mBound) return; - // Create and send a message to the service, using a supported 'what' value - Message msg = Message.obtain(null, MessengerService.MSG_SAY_HELLO, 0, 0); - try { - mService.send(msg); - } catch (RemoteException e) { - e.printStackTrace(); - } - } - - @Override - protected void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - setContentView(R.layout.main); - } - - @Override - protected void onStart() { - super.onStart(); - // Bind to the service - bindService(new Intent(this, MessengerService.class), mConnection, - Context.BIND_AUTO_CREATE); - } - - @Override - protected void onStop() { - super.onStop(); - // Unbind from the service - if (mBound) { - unbindService(mConnection); - mBound = false; - } - } -} -</pre> - -<p>Notice that this example does not show how the service can respond to the client. If you want the -service to respond, then you need to also create a {@link android.os.Messenger} in the client. Then -when the client receives the {@link android.content.ServiceConnection#onServiceConnected -onServiceConnected()} callback, it sends a {@link android.os.Message} to the service that includes -the client's {@link android.os.Messenger} in the {@link android.os.Message#replyTo} parameter -of the {@link android.os.Messenger#send send()} method.</p> - -<p>You can see an example of how to provide two-way messaging in the <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/MessengerService.html">{@code -MessengerService.java}</a> (service) and <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/MessengerServiceActivities.html">{@code -MessengerServiceActivities.java}</a> (client) samples.</p> - - - - - -<h2 id="Binding">Binding to a Service</h2> - -<p>Application components (clients) can bind to a service by calling -{@link android.content.Context#bindService bindService()}. The Android -system then calls the service's {@link android.app.Service#onBind -onBind()} method, which returns an {@link android.os.IBinder} for interacting with the service.</p> - -<p>The binding is asynchronous. {@link android.content.Context#bindService -bindService()} returns immediately and does <em>not</em> return the {@link android.os.IBinder} to -the client. To receive the {@link android.os.IBinder}, the client must create an instance of {@link -android.content.ServiceConnection} and pass it to {@link android.content.Context#bindService -bindService()}. The {@link android.content.ServiceConnection} includes a callback method that the -system calls to deliver the {@link android.os.IBinder}.</p> - -<p class="note"><strong>Note:</strong> Only activities, services, and content providers can bind -to a service—you <strong>cannot</strong> bind to a service from a broadcast receiver.</p> - -<p>So, to bind to a service from your client, you must: </p> -<ol> - <li>Implement {@link android.content.ServiceConnection}. - <p>Your implementation must override two callback methods:</p> - <dl> - <dt>{@link android.content.ServiceConnection#onServiceConnected onServiceConnected()}</dt> - <dd>The system calls this to deliver the {@link android.os.IBinder} returned by -the service's {@link android.app.Service#onBind onBind()} method.</dd> - <dt>{@link android.content.ServiceConnection#onServiceDisconnected -onServiceDisconnected()}</dt> - <dd>The Android system calls this when the connection to the service is unexpectedly -lost, such as when the service has crashed or has been killed. This is <em>not</em> called when the -client unbinds.</dd> - </dl> - </li> - <li>Call {@link -android.content.Context#bindService bindService()}, passing the {@link -android.content.ServiceConnection} implementation. </li> - <li>When the system calls your {@link android.content.ServiceConnection#onServiceConnected -onServiceConnected()} callback method, you can begin making calls to the service, using -the methods defined by the interface.</li> - <li>To disconnect from the service, call {@link -android.content.Context#unbindService unbindService()}. - <p>When your client is destroyed, it will unbind from the service, but you should always unbind -when you're done interacting with the service or when your activity pauses so that the service can -shutdown while its not being used. (Appropriate times to bind and unbind is discussed -more below.)</p> - </li> -</ol> - -<p>For example, the following snippet connects the client to the service created above by -<a href="#Binder">extending the Binder class</a>, so all it must do is cast the returned -{@link android.os.IBinder} to the {@code LocalService} class and request the {@code -LocalService} instance:</p> - -<pre> -LocalService mService; -private ServiceConnection mConnection = new ServiceConnection() { - // Called when the connection with the service is established - public void onServiceConnected(ComponentName className, IBinder service) { - // Because we have bound to an explicit - // service that is running in our own process, we can - // cast its IBinder to a concrete class and directly access it. - LocalBinder binder = (LocalBinder) service; - mService = binder.getService(); - mBound = true; - } - - // Called when the connection with the service disconnects unexpectedly - public void onServiceDisconnected(ComponentName className) { - Log.e(TAG, "onServiceDisconnected"); - mBound = false; - } -}; -</pre> - -<p>With this {@link android.content.ServiceConnection}, the client can bind to a service by passing -this it to {@link android.content.Context#bindService bindService()}. For example:</p> - -<pre> -Intent intent = new Intent(this, LocalService.class); -bindService(intent, mConnection, Context.BIND_AUTO_CREATE); -</pre> - -<ul> - <li>The first parameter of {@link android.content.Context#bindService bindService()} is an -{@link android.content.Intent} that explicitly names the service to bind (thought the intent -could be implicit).</li> -<li>The second parameter is the {@link android.content.ServiceConnection} object.</li> -<li>The third parameter is a flag indicating options for the binding. It should usually be {@link -android.content.Context#BIND_AUTO_CREATE} in order to create the service if its not already alive. -Other possible values are {@link android.content.Context#BIND_DEBUG_UNBIND} -and {@link android.content.Context#BIND_NOT_FOREGROUND}, or {@code 0} for none.</li> -</ul> - - -<h3>Additional notes</h3> - -<p>Here are some important notes about binding to a service:</p> -<ul> - <li>You should always trap {@link android.os.DeadObjectException} exceptions, which are thrown -when the connection has broken. This is the only exception thrown by remote methods.</li> - <li>Objects are reference counted across processes. </li> - <li>You should usually pair the binding and unbinding during -matching bring-up and tear-down moments of the client's lifecycle. For example: - <ul> - <li>If you only need to interact with the service while your activity is visible, you -should bind during {@link android.app.Activity#onStart onStart()} and unbind during {@link -android.app.Activity#onStop onStop()}.</li> - <li>If you want your activity to receive responses even while it is stopped in the -background, then you can bind during {@link android.app.Activity#onCreate onCreate()} and unbind -during {@link android.app.Activity#onDestroy onDestroy()}. Beware that this implies that your -activity needs to use the service the entire time it's running (even in the background), so if -the service is in another process, then you increase the weight of the process and it becomes -more likely that the system will kill it.</li> - </ul> - <p class="note"><strong>Note:</strong> You should usually <strong>not</strong> bind and unbind -during your activity's {@link android.app.Activity#onResume onResume()} and {@link -android.app.Activity#onPause onPause()}, because these callbacks occur at every lifecycle transition -and you should keep the processing that occurs at these transitions to a minimum. Also, if -multiple activities in your application bind to the same service and there is a transition between -two of those activities, the service may be destroyed and recreated as the current activity unbinds -(during pause) before the next one binds (during resume). (This activity transition for how -activities coordinate their lifecycles is described in the <a -href="{@docRoot}guide/topics/fundamentals/activities.html#CoordinatingActivities">Activities</a> -document.)</p> -</ul> - -<p>For more sample code, showing how to bind to a service, see the <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.html">{@code -RemoteService.java}</a> class in <a -href="{@docRoot}resources/samples/ApiDemos/index.html">ApiDemos</a>.</p> - - - - - -<h2 id="Lifecycle">Managing the Lifecycle of a Bound Service</h2> - -<div class="figure" style="width:588px"> -<img src="{@docRoot}images/fundamentals/service_binding_tree_lifecycle.png" alt="" /> -<p class="img-caption"><strong>Figure 1.</strong> The lifecycle for a service that is started -and also allows binding.</p> -</div> - -<p>When a service is unbound from all clients, the Android system destroys it (unless it was also -started with {@link android.app.Service#onStartCommand onStartCommand()}). As such, you don't have -to manage the lifecycle of your service if it's purely a bound -service—the Android system manages it for you based on whether it is bound to any clients.</p> - -<p>However, if you choose to implement the {@link android.app.Service#onStartCommand -onStartCommand()} callback method, then you must explicitly stop the service, because the -service is now considered to be <em>started</em>. In this case, the service runs until the service -stops itself with {@link android.app.Service#stopSelf()} or another component calls {@link -android.content.Context#stopService stopService()}, regardless of whether it is bound to any -clients.</p> - -<p>Additionally, if your service is started and accepts binding, then when the system calls -your {@link android.app.Service#onUnbind onUnbind()} method, you can optionally return -{@code true} if you would like to receive a call to {@link android.app.Service#onRebind -onRebind()} the next time a client binds to the service (instead of receiving a call to {@link -android.app.Service#onBind onBind()}). {@link android.app.Service#onRebind -onRebind()} returns void, but the client still receives the {@link android.os.IBinder} in its -{@link android.content.ServiceConnection#onServiceConnected onServiceConnected()} callback. -Below, figure 1 illustrates the logic for this kind of lifecycle.</p> - -<p>For more information about the lifecycle of an started service, see the <a -href="{@docRoot}guide/topics/fundamentals/services.html#Lifecycle">Services</a> document.</p> - - - - diff --git a/docs/html/guide/topics/fundamentals/fragments.jd b/docs/html/guide/topics/fundamentals/fragments.jd deleted file mode 100644 index 2a22394..0000000 --- a/docs/html/guide/topics/fundamentals/fragments.jd +++ /dev/null @@ -1,836 +0,0 @@ -page.title=Fragments -parent.title=Activities -parent.link=activities.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>Quickview</h2> - <ul> - <li>Fragments decompose application functionality and UI into reusable modules</li> - <li>Add multiple fragments to a screen to avoid switching activities</li> - <li>Fragments have their own lifecycle, state, and back stack</li> - <li>Fragments require API Level 11 or greater</li> - </ul> - - <h2>In this document</h2> - <ol> - <li><a href="#Design">Design Philosophy</a></li> - <li><a href="#Creating">Creating a Fragment</a> - <ol> - <li><a href="#UI">Adding a user interface</a></li> - <li><a href="#Adding">Adding a fragment to an activity</a></li> - </ol> - </li> - <li><a href="#Managing">Managing Fragments</a></li> - <li><a href="#Transactions">Performing Fragment Transactions</a></li> - <li><a href="#CommunicatingWithActivity">Communicating with the Activity</a> - <ol> - <li><a href="#EventCallbacks">Creating event callbacks to the activity</a></li> - <li><a href="#ActionBar">Adding items to the Action Bar</a></li> - </ol> - </li> - <li><a href="#Lifecycle">Handling the Fragment Lifecycle</a> - <ol> - <li><a href="#CoordinatingWithActivity">Coordinating with the activity lifecycle</a></li> - </ol> - </li> - <li><a href="#Example">Example</a></li> - </ol> - - <h2>Key classes</h2> - <ol> - <li>{@link android.app.Fragment}</li> - <li>{@link android.app.FragmentManager}</li> - <li>{@link android.app.FragmentTransaction}</li> - </ol> - - <h2>Related samples</h2> - <ol> - <li><a -href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a></li> - <li><a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#Fragment">ApiDemos</a></li> - </ol> - - <h2>See also</h2> - <ol> - <li><a href="{@docRoot}guide/practices/tablets-and-handsets.html">Supporting Tablets -and Handsets</a></li> - </ol> -</div> -</div> - -<p>A {@link android.app.Fragment} represents a behavior or a portion of user interface in an -{@link android.app.Activity}. You can combine multiple fragments in a single activity to build a -multi-pane UI and reuse a fragment in multiple activities. You can think of a fragment as a -modular section of an activity, which has its own lifecycle, receives its own input events, and -which you can add or remove while the activity is running (sort of like a "sub activity" that -you can reuse in different activities).</p> - -<p>A fragment must always be embedded in an activity and the fragment's lifecycle is directly -affected by the host activity's lifecycle. For example, when the activity is paused, so are all -fragments in it, and when the activity is destroyed, so are all fragments. However, while an -activity is running (it is in the <em>resumed</em> <a -href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">lifecycle state</a>), you can -manipulate each fragment independently, such as add or remove them. When you perform such a -fragment transaction, you can also add it to a back stack that's managed by the -activity—each back stack entry in the activity is a record of the fragment transaction that -occurred. The back stack allows the user to reverse a fragment transaction (navigate backwards), -by pressing the <em>Back</em> button.</p> - -<p>When you add a fragment as a part of your activity layout, it lives in a {@link -android.view.ViewGroup} inside the activity's view hierarchy and the fragment defines its own view -layout. -You can insert a fragment into your activity layout by declaring the fragment in the activity's -layout file, as a {@code <fragment>} element, or from your application code by adding it to an -existing {@link android.view.ViewGroup}. However, a fragment is not required to be a part of the -activity layout; you may also use a fragment without its own UI as an invisible worker for the -activity.</p> - -<p>This document describes how to build your application to use fragments, including -how fragments can maintain their state when added to the activity's back stack, share -events with the activity and other fragments in the activity, contribute to the activity's action -bar, and more.</p> - - -<h2 id="Design">Design Philosophy</h2> - -<p>Android introduced fragments in Android 3.0 (API level 11), primarily to support more -dynamic and flexible UI designs on large screens, such as tablets. Because a -tablet's screen is much larger than that of a handset, there's more room to combine and -interchange UI components. Fragments allow such designs without the need for you to manage complex -changes to the view hierarchy. By dividing the layout of an activity into fragments, you become able -to modify the activity's appearance at runtime and preserve those changes in a back stack -that's managed by the activity.</p> - -<p>For example, a news application can use one fragment to show a list of articles on the -left and another fragment to display an article on the right—both fragments appear in one -activity, side by side, and each fragment has its own set of lifecycle callback methods and handle -their own user input events. Thus, instead of using one activity to select an article and another -activity to read the article, the user can select an article and read it all within the same -activity, as illustrated in the tablet layout in figure 1.</p> - -<p>You should design each fragment as a modular and reusable activity component. That is, because -each fragment defines its own layout and its own behavior with its own lifecycle callbacks, you can -include one fragment in multiple activities, so you should design for reuse and avoid directly -manipulating one fragment from another fragment. This is especially important because a modular -fragment allows you to change your fragment combinations for different screen sizes. When designing -your application to support both tablets and handsets, you can reuse your fragments in different -layout configurations to optimize the user experience based on the available screen space. For -example, on a handset, it might be necessary to separate fragments to provide a single-pane UI when -more than one cannot fit within the same activity.</p> - -<img src="{@docRoot}images/fundamentals/fragments.png" alt="" /> -<p class="img-caption"><strong>Figure 1.</strong> An example of how two UI modules defined by -fragments can be combined into one activity for a tablet design, but separated for a -handset design.</p> - -<p>For example—to continue with the news application example—the application can embed -two fragments in <em>Activity A</em>, when running on a tablet-sized device. However, on a -handset-sized screen, there's not enough room for both fragments, so <em>Activity A</em> includes -only the fragment for the list of articles, and when the user selects an article, it starts -<em>Activity B</em>, which includes the second fragment to read the article. Thus, the application -supports both tablets and handsets by reusing fragments in different combinations, as illustrated in -figure 1.</p> - -<p>For more information about designing your application with different fragment combinations for -different screen configurations, see the guide to <a -href="{@docRoot}guide/practices/tablets-and-handsets.html">Supporting Tablets and Handsets</a>.</p> - - - -<h2 id="Creating">Creating a Fragment</h2> - -<div class="figure" style="width:327px"> -<img src="{@docRoot}images/fragment_lifecycle.png" alt="" /> -<p class="img-caption"><strong>Figure 2.</strong> The lifecycle of a fragment (while its -activity is running).</p> -</div> - -<p>To create a fragment, you must create a subclass of {@link android.app.Fragment} (or an existing -subclass of it). The {@link android.app.Fragment} class has code that looks a lot like -an {@link android.app.Activity}. It contains callback methods similar to an activity, such -as {@link android.app.Fragment#onCreate onCreate()}, {@link android.app.Fragment#onStart onStart()}, -{@link android.app.Fragment#onPause onPause()}, and {@link android.app.Fragment#onStop onStop()}. In -fact, if you're converting an existing Android application to use fragments, you might simply move -code from your activity's callback methods into the respective callback methods of your -fragment.</p> - -<p>Usually, you should implement at least the following lifecycle methods:</p> - -<dl> - <dt>{@link android.app.Fragment#onCreate onCreate()}</dt> - <dd>The system calls this when creating the fragment. Within your implementation, you should -initialize essential components of the fragment that you want to retain when the fragment is -paused or stopped, then resumed.</dd> - <dt>{@link android.app.Fragment#onCreateView onCreateView()}</dt> - <dd>The system calls this when it's time for the fragment to draw its user interface for the -first time. To draw a UI for your fragment, you must return a {@link android.view.View} from this -method that is the root of your fragment's layout. You can return null if the fragment does not -provide a UI.</dd> - <dt>{@link android.app.Activity#onPause onPause()}</dt> - <dd>The system calls this method as the first indication that the user is leaving the -fragment (though it does not always mean the fragment is being destroyed). This is usually where you -should commit any changes that should be persisted beyond the current user session (because -the user might not come back).</dd> -</dl> - -<p>Most applications should implement at least these three methods for every fragment, but there are -several other callback methods you should also use to handle various stages of the -fragment lifecycle. All the lifecycle callback methods are discussed more later, in the section -about <a href="#Lifecycle">Handling the Fragment Lifecycle</a>.</p> - - -<p>There are also a few subclasses that you might want to extend, instead of the base {@link -android.app.Fragment} class:</p> - -<dl> - <dt>{@link android.app.DialogFragment}</dt> - <dd>Displays a floating dialog. Using this class to create a dialog is a good alternative to using -the dialog helper methods in the {@link android.app.Activity} class, because you can -incorporate a fragment dialog into the back stack of fragments managed by the activity, -allowing the user to return to a dismissed fragment.</dd> - - <dt>{@link android.app.ListFragment}</dt> - <dd>Displays a list of items that are managed by an adapter (such as a {@link -android.widget.SimpleCursorAdapter}), similar to {@link android.app.ListActivity}. It provides -several methods for managing a list view, such as the {@link -android.app.ListFragment#onListItemClick(ListView,View,int,long) onListItemClick()} callback to -handle click events.</dd> - - <dt>{@link android.preference.PreferenceFragment}</dt> - <dd>Displays a hierarchy of {@link android.preference.Preference} objects as a list, similar to -{@link android.preference.PreferenceActivity}. This is useful when creating a "settings" -activity for your application.</dd> -</dl> - - -<h3 id="UI">Adding a user interface</h3> - -<p>A fragment is usually used as part of an activity's user interface and contributes its own -layout to the activity.</p> - -<p>To provide a layout for a fragment, you must implement the {@link -android.app.Fragment#onCreateView onCreateView()} callback method, which the Android system calls -when it's time for the fragment to draw its layout. Your implementation of this method must return a -{@link android.view.View} that is the root of your fragment's layout.</p> - -<p class="note"><strong>Note:</strong> If your fragment is a subclass of {@link -android.app.ListFragment}, the default implementation returns a {@link android.widget.ListView} from -{@link android.app.Fragment#onCreateView onCreateView()}, so you don't need to implement it.</p> - -<p>To return a layout from {@link -android.app.Fragment#onCreateView onCreateView()}, you can inflate it from a <a -href="{@docRoot}guide/topics/resources/layout-resource.html">layout resource</a> defined in XML. To -help you do so, {@link android.app.Fragment#onCreateView onCreateView()} provides a -{@link android.view.LayoutInflater} object.</p> - -<p>For example, here's a subclass of {@link android.app.Fragment} that loads a layout from the -{@code example_fragment.xml} file:</p> - -<pre> -public static class ExampleFragment extends Fragment { - @Override - public View onCreateView(LayoutInflater inflater, ViewGroup container, - Bundle savedInstanceState) { - // Inflate the layout for this fragment - return inflater.inflate(R.layout.example_fragment, container, false); - } -} -</pre> - -<div class="sidebox-wrapper"> -<div class="sidebox"> - <h3>Creating a layout</h3> - <p>In the sample above, {@code R.layout.example_fragment} is a reference to a layout resource -named {@code example_fragment.xml} saved in the application resources. For information about how to -create a layout in XML, see the <a href="{@docRoot}guide/topics/ui/index.html">User Interface</a> -documentation.</p> -</div> -</div> - -<p>The {@code container} parameter passed to {@link android.app.Fragment#onCreateView -onCreateView()} is the parent {@link android.view.ViewGroup} (from the activity's layout) in which -your fragment layout -will be inserted. The {@code savedInstanceState} parameter is a {@link android.os.Bundle} that -provides data about the previous instance of the fragment, if the fragment is being resumed -(restoring state is discussed more in the section about <a href="#Lifecycle">Handling the -Fragment Lifecycle</a>).</p> - -<p>The {@link android.view.LayoutInflater#inflate(int,ViewGroup,boolean) inflate()} method takes -three arguments:</p> -<ul> - <li>The resource ID of the layout you want to inflate.</li> - <li>The {@link android.view.ViewGroup} to be the parent of the inflated layout. Passing the {@code -container} is important in order for the system to apply layout parameters to the root view of the -inflated layout, specified by the parent view in which it's going.</li> - <li>A boolean indicating whether the inflated layout should be attached to the {@link -android.view.ViewGroup} (the second parameter) during inflation. (In this case, this -is false because the system is already inserting the inflated layout into the {@code -container}—passing true would create a redundant view group in the final layout.)</li> -</ul> - -<p>Now you've seen how to create a fragment that provides a layout. Next, you need to add -the fragment to your activity.</p> - - - -<h3 id="Adding">Adding a fragment to an activity</h3> - -<p>Usually, a fragment contributes a portion of UI to the host activity, which is embedded as a part -of the activity's overall view hierarchy. There are two ways you can add a fragment to the activity -layout:</p> - -<ul> - <li><b>Declare the fragment inside the activity's layout file.</b> -<p>In this case, you can -specify layout properties for the fragment as if it were a view. For example, here's the layout -file for an activity with two fragments:</p> -<pre> -<?xml version="1.0" encoding="utf-8"?> -<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" - android:orientation="horizontal" - android:layout_width="match_parent" - android:layout_height="match_parent"> - <fragment android:name="com.example.news.ArticleListFragment" - android:id="@+id/list" - android:layout_weight="1" - android:layout_width="0dp" - android:layout_height="match_parent" /> - <fragment android:name="com.example.news.ArticleReaderFragment" - android:id="@+id/viewer" - android:layout_weight="2" - android:layout_width="0dp" - android:layout_height="match_parent" /> -</LinearLayout> -</pre> - <p>The {@code android:name} attribute in the {@code <fragment>} specifies the {@link -android.app.Fragment} class to instantiate in the layout.</p> - -<p>When the system creates this activity layout, it instantiates each fragment specified in the -layout and calls the {@link android.app.Fragment#onCreateView onCreateView()} method for each one, -to retrieve each fragment's layout. The system inserts the {@link android.view.View} returned by the -fragment directly in place of the {@code <fragment>} element.</p> - -<div class="note"> - <p><strong>Note:</strong> Each fragment requires a unique identifier that -the system can use to restore the fragment if the activity is restarted (and which you can use to -capture the fragment to perform transactions, such as remove it). There are three ways to provide an -ID for a fragment:</p> - <ul> - <li>Supply the {@code android:id} attribute with a unique ID.</li> - <li>Supply the {@code android:tag} attribute with a unique string.</li> - <li>If you provide neither of the previous two, the system uses the ID of the container -view.</li> - </ul> -</div> - </li> - - <li><b>Or, programmatically add the fragment to an existing {@link android.view.ViewGroup}.</b> -<p>At any time while your activity is running, you can add fragments to your activity layout. You -simply need to specify a {@link -android.view.ViewGroup} in which to place the fragment.</p> - <p>To make fragment transactions in your activity (such as add, remove, or replace a -fragment), you must use APIs from {@link android.app.FragmentTransaction}. You can get an instance -of {@link android.app.FragmentTransaction} from your {@link android.app.Activity} like this:</p> - -<pre> -FragmentManager fragmentManager = {@link android.app.Activity#getFragmentManager()} -FragmentTransaction fragmentTransaction = fragmentManager.{@link android.app.FragmentManager#beginTransaction()}; -</pre> - -<p>You can then add a fragment using the {@link -android.app.FragmentTransaction#add(int,Fragment) add()} method, specifying the fragment to add and -the view in which to insert it. For example:</p> - -<pre> -ExampleFragment fragment = new ExampleFragment(); -fragmentTransaction.add(R.id.fragment_container, fragment); -fragmentTransaction.commit(); -</pre> - - <p>The first argument passed to {@link android.app.FragmentTransaction#add(int,Fragment) add()} -is the {@link android.view.ViewGroup} in which the fragment should be placed, specified by -resource ID, and the second parameter is the fragment to add.</p> - <p>Once you've made your changes with -{@link android.app.FragmentTransaction}, you must -call {@link android.app.FragmentTransaction#commit} for the changes to take effect.</p> - </li> -</ul> - - -<h4 id="AddingWithoutUI">Adding a fragment without a UI</h4> - -<p>The examples above show how to add a fragment to your activity in order to provide a UI. However, -you can also use a fragment to provide a background behavior for the activity without presenting -additional UI.</p> - -<p>To add a fragment without a UI, add the fragment from the activity using {@link -android.app.FragmentTransaction#add(Fragment,String)} (supplying a unique string "tag" for the -fragment, rather than a view ID). This adds the fragment, but, because it's not associated with a -view in the activity layout, it does not receive a call to {@link -android.app.Fragment#onCreateView onCreateView()}. So you don't need to implement that method.</p> - -<p>Supplying a string tag for the fragment isn't strictly for non-UI fragments—you can also -supply string tags to fragments that do have a UI—but if the fragment does not have a -UI, then the string tag is the only way to identify it. If you want to get the fragment from the -activity later, you need to use {@link android.app.FragmentManager#findFragmentByTag -findFragmentByTag()}.</p> - -<p>For an example activity that uses a fragment as a background worker, without a UI, see the <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/FragmentRetainInstance.html">{@code -FragmentRetainInstance.java}</a> sample.</p> - - - -<h2 id="Managing">Managing Fragments</h2> - -<p>To manage the fragments in your activity, you need to use {@link android.app.FragmentManager}. To -get it, call {@link android.app.Activity#getFragmentManager()} from your activity.</p> - -<p>Some things that you can do with {@link android.app.FragmentManager} include:</p> - -<ul> - <li>Get fragments that exist in the activity, with {@link -android.app.FragmentManager#findFragmentById findFragmentById()} (for fragments that provide a UI in -the activity layout) or {@link android.app.FragmentManager#findFragmentByTag -findFragmentByTag()} (for fragments that do or don't provide a UI).</li> - <li>Pop fragments off the back stack, with {@link -android.app.FragmentManager#popBackStack()} (simulating a <em>Back</em> command by the user).</li> - <li>Register a listener for changes to the back stack, with {@link -android.app.FragmentManager#addOnBackStackChangedListener addOnBackStackChangedListener()}.</li> -</ul> - -<p>For more information about these methods and others, refer to the {@link -android.app.FragmentManager} class documentation.</p> - -<p>As demonstrated in the previous section, you can also use {@link android.app.FragmentManager} -to open a {@link android.app.FragmentTransaction}, which allows you to perform transactions, such as -add and remove fragments.</p> - - -<h2 id="Transactions">Performing Fragment Transactions</h2> - -<p>A great feature about using fragments in your activity is the ability to add, remove, replace, -and perform other actions with them, in response to user interaction. Each set of changes that you -commit to the activity is called a transaction and you can perform one using APIs in {@link -android.app.FragmentTransaction}. You can also save each transaction to a back stack managed by the -activity, allowing the user to navigate backward through the fragment changes (similar to navigating -backward through activities).</p> - -<p>You can acquire an instance of {@link android.app.FragmentTransaction} from the {@link -android.app.FragmentManager} like this:</p> - -<pre> -FragmentManager fragmentManager = {@link android.app.Activity#getFragmentManager()}; -FragmentTransaction fragmentTransaction = fragmentManager.{@link android.app.FragmentManager#beginTransaction()}; -</pre> - -<p>Each transaction is a set of changes that you want to perform at the same time. You can set -up all the changes you want to perform for a given transaction using methods such as {@link -android.app.FragmentTransaction#add add()}, {@link android.app.FragmentTransaction#remove remove()}, -and {@link android.app.FragmentTransaction#replace replace()}. Then, to apply the transaction -to the activity, you must call {@link android.app.FragmentTransaction#commit()}.</p> -</dl> - -<p>Before you call {@link -android.app.FragmentTransaction#commit()}, however, you might want to call {@link -android.app.FragmentTransaction#addToBackStack addToBackStack()}, in order to add the transaction -to a back stack of fragment transactions. This back stack is managed by the activity and allows -the user to return to the previous fragment state, by pressing the <em>Back</em> button.</p> - -<p>For example, here's how you can replace one fragment with another, and preserve the previous -state in the back stack:</p> - -<pre> -// Create new fragment and transaction -Fragment newFragment = new ExampleFragment(); -FragmentTransaction transaction = getFragmentManager().beginTransaction(); - -// Replace whatever is in the fragment_container view with this fragment, -// and add the transaction to the back stack -transaction.replace(R.id.fragment_container, newFragment); -transaction.addToBackStack(null); - -// Commit the transaction -transaction.commit(); -</pre> - -<p>In this example, {@code newFragment} replaces whatever fragment (if any) is currently in the -layout container identified by the {@code R.id.fragment_container} ID. By calling {@link -android.app.FragmentTransaction#addToBackStack addToBackStack()}, the replace transaction is -saved to the back stack so the user can reverse the transaction and bring back the -previous fragment by pressing the <em>Back</em> button.</p> - -<p>If you add multiple changes to the transaction (such as another {@link -android.app.FragmentTransaction#add add()} or {@link android.app.FragmentTransaction#remove -remove()}) and call {@link -android.app.FragmentTransaction#addToBackStack addToBackStack()}, then all changes applied -before you call {@link android.app.FragmentTransaction#commit commit()} are added to the -back stack as a single transaction and the <em>Back</em> button will reverse them all together.</p> - -<p>The order in which you add changes to a {@link android.app.FragmentTransaction} doesn't matter, -except:</p> -<ul> - <li>You must call {@link android.app.FragmentTransaction#commit()} last</li> - <li>If you're adding multiple fragments to the same container, then the order in which -you add them determines the order they appear in the view hierarchy</li> -</ul> - -<p>If you do not call {@link android.app.FragmentTransaction#addToBackStack(String) -addToBackStack()} when you perform a transaction that removes a fragment, then that fragment is -destroyed when the transaction is committed and the user cannot navigate back to it. Whereas, if you -do call {@link android.app.FragmentTransaction#addToBackStack(String) addToBackStack()} when -removing a fragment, then the fragment is <em>stopped</em> and will be resumed if the user navigates -back.</p> - -<p class="note"><strong>Tip:</strong> For each fragment transaction, you can apply a transition -animation, by calling {@link android.app.FragmentTransaction#setTransition setTransition()} before -you commit.</p> - -<p>Calling {@link android.app.FragmentTransaction#commit()} does not perform the transaction -immediately. Rather, it schedules it to run on the activity's UI thread (the "main" thread) as soon -as the thread is able to do so. If necessary, however, you may call {@link -android.app.FragmentManager#executePendingTransactions()} from your UI thread to immediately execute -transactions submitted by {@link android.app.FragmentTransaction#commit()}. Doing so is -usually not necessary unless the transaction is a dependency for jobs in other threads.</p> - -<p class="caution"><strong>Caution:</strong> You can commit a transaction using {@link -android.app.FragmentTransaction#commit commit()} only prior to the activity <a -href="{@docRoot}guide/topics/fundamentals/activities.html#SavingActivityState">saving its -state</a> (when the user leaves the activity). If you attempt to commit after that point, an -exception will be thrown. This is because the state after the commit can be lost if the activity -needs to be restored. For situations in which its okay that you lose the commit, use {@link -android.app.FragmentTransaction#commitAllowingStateLoss()}.</p> - - - - -<h2 id="CommunicatingWithActivity">Communicating with the Activity</h2> - -<p>Although a {@link android.app.Fragment} is implemented as an object that's independent from an -{@link android.app.Activity} and can be used inside multiple activities, a given instance of -a fragment is directly tied to the activity that contains it.</p> - -<p>Specifically, the fragment can access the {@link android.app.Activity} instance with {@link -android.app.Fragment#getActivity()} and easily perform tasks such as find a view in the -activity layout:</p> - -<pre> -View listView = {@link android.app.Fragment#getActivity()}.{@link android.app.Activity#findViewById findViewById}(R.id.list); -</pre> - -<p>Likewise, your activity can call methods in the fragment by acquiring a reference to the -{@link android.app.Fragment} from {@link android.app.FragmentManager}, using {@link -android.app.FragmentManager#findFragmentById findFragmentById()} or {@link -android.app.FragmentManager#findFragmentByTag findFragmentByTag()}. For example:</p> - -<pre> -ExampleFragment fragment = (ExampleFragment) getFragmentManager().findFragmentById(R.id.example_fragment); -</pre> - - -<h3 id="EventCallbacks">Creating event callbacks to the activity</h3> - -<p>In some cases, you might need a fragment to share events with the activity. A good way to do that -is to define a callback interface inside the fragment and require that the host activity implement -it. When the activity receives a callback through the interface, it can share the information with -other fragments in the layout as necessary.</p> - -<p>For example, if a news application has two fragments in an activity—one to show a list of -articles (fragment A) and another to display an article (fragment B)—then fragment A must tell -the activity when a list item is selected so that it can tell fragment B to display the article. In -this case, the {@code OnArticleSelectedListener} interface is declared inside fragment A:</p> - -<pre> -public static class FragmentA extends ListFragment { - ... - // Container Activity must implement this interface - public interface OnArticleSelectedListener { - public void onArticleSelected(Uri articleUri); - } - ... -} -</pre> - -<p>Then the activity that hosts the fragment implements the {@code OnArticleSelectedListener} -interface and -overrides {@code onArticleSelected()} to notify fragment B of the event from fragment A. To ensure -that the host activity implements this interface, fragment A's {@link -android.app.Fragment#onAttach onAttach()} callback method (which the system calls when adding -the fragment to the activity) instantiates an instance of {@code OnArticleSelectedListener} by -casting the {@link android.app.Activity} that is passed into {@link android.app.Fragment#onAttach -onAttach()}:</p> - -<pre> -public static class FragmentA extends ListFragment { - OnArticleSelectedListener mListener; - ... - @Override - public void onAttach(Activity activity) { - super.onAttach(activity); - try { - mListener = (OnArticleSelectedListener) activity; - } catch (ClassCastException e) { - throw new ClassCastException(activity.toString() + " must implement OnArticleSelectedListener"); - } - } - ... -} -</pre> - -<p>If the activity has not implemented the interface, then the fragment throws a -{@link java.lang.ClassCastException}. -On success, the {@code mListener} member holds a reference to activity's implementation of -{@code OnArticleSelectedListener}, so that fragment A can share events with the activity by calling -methods defined by the {@code OnArticleSelectedListener} interface. For example, if fragment A is an -extension of {@link android.app.ListFragment}, each time -the user clicks a list item, the system calls {@link android.app.ListFragment#onListItemClick -onListItemClick()} in the fragment, which then calls {@code onArticleSelected()} to share -the event with the activity:</p> - -<pre> -public static class FragmentA extends ListFragment { - OnArticleSelectedListener mListener; - ... - @Override - public void onListItemClick(ListView l, View v, int position, long id) { - // Append the clicked item's row ID with the content provider Uri - Uri noteUri = ContentUris.{@link android.content.ContentUris#withAppendedId withAppendedId}(ArticleColumns.CONTENT_URI, id); - // Send the event and Uri to the host activity - mListener.onArticleSelected(noteUri); - } - ... -} -</pre> - -<p>The {@code id} parameter passed to {@link -android.app.ListFragment#onListItemClick onListItemClick()} is the row ID of the clicked item, -which the activity (or other fragment) uses to fetch the article from the application's {@link -android.content.ContentProvider}.</p> - -<p><!--To see a complete implementation of this kind of callback interface, see the <a -href="{@docRoot}resources/samples/NotePad/index.html">NotePad sample</a>. -->More information about -using a content provider is available in the <a -href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> document.</p> - - - -<h3 id="ActionBar">Adding items to the Action Bar</h3> - -<p>Your fragments can contribute menu items to the activity's <a -href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options Menu</a> (and, consequently, the <a -href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>) by implementing -{@link android.app.Fragment#onCreateOptionsMenu(Menu,MenuInflater) onCreateOptionsMenu()}. In order -for this method to receive calls, however, you must call {@link -android.app.Fragment#setHasOptionsMenu(boolean) setHasOptionsMenu()} during {@link -android.app.Fragment#onCreate(Bundle) onCreate()}, to indicate that the fragment -would like to add items to the Options Menu (otherwise, the fragment will not receive a call to -{@link android.app.Fragment#onCreateOptionsMenu onCreateOptionsMenu()}).</p> - -<p>Any items that you then add to the Options Menu from the fragment are appended to the existing -menu items. The fragment also receives callbacks to {@link -android.app.Fragment#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} when a menu item -is selected.</p> - -<p>You can also register a view in your fragment layout to provide a context menu by calling {@link -android.app.Fragment#registerForContextMenu(View) registerForContextMenu()}. When the user opens -the context menu, the fragment receives a call to {@link -android.app.Fragment#onCreateContextMenu(ContextMenu,View,ContextMenu.ContextMenuInfo) -onCreateContextMenu()}. When the user selects an item, the fragment receives a call to {@link -android.app.Fragment#onContextItemSelected(MenuItem) onContextItemSelected()}.</p> - -<p class="note"><strong>Note:</strong> Although your fragment receives an on-item-selected callback -for each menu item it adds, the activity is first to receive the respective callback when the user -selects a menu item. If the activity's implementation of the on-item-selected callback does not -handle the selected item, then the event is passed to the fragment's callback. This is true for -the Options Menu and context menus.</p> - -<p>For more information about menus, see the <a -href="{@docRoot}guide/topics/ui/menus.html">Menus</a> and <a -href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guides.</p> - - - - -<h2 id="Lifecycle">Handling the Fragment Lifecycle</h2> - -<div class="figure" style="width:350px"> -<img src="{@docRoot}images/activity_fragment_lifecycle.png" alt=""/> -<p class="img-caption"><strong>Figure 3.</strong> The effect of the activity lifecycle on the fragment -lifecycle.</p> -</div> - -<p>Managing the lifecycle of a fragment is a lot like managing the lifecycle of an activity. Like -an activity, a fragment can exist in three states:</p> - -<dl> - <dt><i>Resumed</i></dt> - <dd>The fragment is visible in the running activity.</dd> - - <dt><i>Paused</i></dt> - <dd>Another activity is in the foreground and has focus, but the activity in which this -fragment lives is still visible (the foreground activity is partially transparent or doesn't -cover the entire screen).</dd> - - <dt><i>Stopped</i></dt> - <dd>The fragment is not visible. Either the host activity has been stopped or the -fragment has been removed from the activity but added to the back stack. A stopped fragment is -still alive (all state and member information is retained by the system). However, it is no longer -visible to the user and will be killed if the activity is killed.</dd> -</dl> - -<p>Also like an activity, you can retain the state of a fragment using a {@link -android.os.Bundle}, in case the activity's process is killed and you need to restore the -fragment state when the activity is recreated. You can save the state during the fragment's {@link -android.app.Fragment#onSaveInstanceState onSaveInstanceState()} callback and restore it during -either {@link android.app.Fragment#onCreate onCreate()}, {@link -android.app.Fragment#onCreateView onCreateView()}, or {@link -android.app.Fragment#onActivityCreated onActivityCreated()}. For more information about saving -state, see the <a -href="{@docRoot}guide/topics/fundamentals/activities.html#SavingActivityState">Activities</a> -document.</p> - -<p>The most significant difference in lifecycle between an activity and a fragment is how one is -stored in its respective back stack. An activity is placed into a back stack of activities -that's managed by the system when it's stopped, by default (so that the user can navigate back -to it with the <em>Back</em> button, as discussed in <a -href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back Stack</a>). -However, a fragment is placed into a back stack managed by the host activity only when you -explicitly request that the instance be saved by calling {@link -android.app.FragmentTransaction#addToBackStack(String) addToBackStack()} during a transaction that -removes the fragment.</p> - -<p>Otherwise, managing the fragment lifecycle is very similar to managing the activity -lifecycle. So, the same practices for <a -href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">managing the activity -lifecycle</a> also apply to fragments. What you also need to understand, though, is how the life -of the activity affects the life of the fragment.</p> - - -<h3 id="CoordinatingWithActivity">Coordinating with the activity lifecycle</h3> - -<p>The lifecycle of the activity in which the fragment lives directly affects the lifecycle of the -fragment, such that each lifecycle callback for the activity results in a similar callback for each -fragment. For example, when the activity receives {@link android.app.Activity#onPause}, each -fragment in the activity receives {@link android.app.Fragment#onPause}.</p> - -<p>Fragments have a few extra lifecycle callbacks, however, that handle unique interaction with the -activity in order to perform actions such as build and destroy the fragment's UI. These additional -callback methods are:</p> - -<dl> - <dt>{@link android.app.Fragment#onAttach onAttach()}</dt> - <dd>Called when the fragment has been associated with the activity (the {@link -android.app.Activity} is passed in here).</dd> - <dt>{@link android.app.Fragment#onCreateView onCreateView()}</dt> - <dd>Called to create the view hierarchy associated with the fragment.</dd> - <dt>{@link android.app.Fragment#onActivityCreated onActivityCreated()}</dt> - <dd>Called when the activity's {@link android.app.Activity#onCreate -onCreate()} method has returned.</dd> - <dt>{@link android.app.Fragment#onDestroyView onDestroyView()}</dt> - <dd>Called when the view hierarchy associated with the fragment is being removed.</dd> - <dt>{@link android.app.Fragment#onDetach onDetach()}</dt> - <dd>Called when the fragment is being disassociated from the activity.</dd> -</dl> - -<p>The flow of a fragment's lifecycle, as it is affected by its host activity, is illustrated -by figure 3. In this figure, you can see how each successive state of the activity determines which -callback methods a fragment may receive. For example, when the activity has received its {@link -android.app.Activity#onCreate onCreate()} callback, a fragment in the activity receives no more than -the {@link android.app.Fragment#onActivityCreated onActivityCreated()} callback.</p> - -<p>Once the activity reaches the resumed state, you can freely add and remove fragments to the -activity. Thus, only while the activity is in the resumed state can the lifecycle of a fragment -change independently.</p> - -<p>However, when the activity leaves the resumed state, the fragment again is pushed through its -lifecycle by the activity.</p> - - - - -<h2 id="Example">Example</h2> - -<p>To bring everything discussed in this document together, here's an example of an activity -using two fragments to create a two-pane layout. The activity below includes one fragment to -show a list of Shakespeare play titles and another to show a summary of the play when selected -from the list. It also demonstrates how to provide different configurations of the fragments, -based on the screen configuration.</p> - -<p class="note"><strong>Note:</strong> The complete source code for this activity is available in -<a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.html">{@code -FragmentLayout.java}</a>.</p> - -<p>The main activity applies a layout in the usual way, during {@link -android.app.Activity#onCreate onCreate()}:</p> - -{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java main} - -<p>The layout applied is {@code fragment_layout.xml}:</p> - -{@sample development/samples/ApiDemos/res/layout-land/fragment_layout.xml layout} - -<p>Using this layout, the system instantiates the {@code TitlesFragment} (which lists the play -titles) as soon as the activity loads the layout, while the {@link android.widget.FrameLayout} -(where the fragment for showing the play summary will go) consumes space on the right side of the -screen, but remains empty at first. As you'll see below, it's not until the user selects an item -from the list that a fragment is placed into the {@link android.widget.FrameLayout}.</p> - -<p>However, not all screen configurations are wide enough to show both the list of -plays and the summary, side by side. So, the layout above is used only for the landscape -screen configuration, by saving it at {@code res/layout-land/fragment_layout.xml}.</p> - -<p>Thus, when the screen is in portrait orientation, the system applies the following layout, which -is saved at {@code res/layout/fragment_layout.xml}:</p> - -{@sample development/samples/ApiDemos/res/layout/fragment_layout.xml layout} - -<p>This layout includes only {@code TitlesFragment}. This means that, when the device is in -portrait orientation, only the list of play titles is visible. So, when the user clicks a list -item in this configuration, the application will start a new activity to show the summary, -instead of loading a second fragment.</p> - -<p>Next, you can see how this is accomplished in the fragment classes. First is {@code -TitlesFragment}, which shows the list of Shakespeare play titles. This fragment extends {@link -android.app.ListFragment} and relies on it to handle most of the list view work.</p> - -<p>As you inspect this code, notice that there are two possible behaviors when the user clicks a -list item: depending on which of the two layouts is active, it can either create and display a new -fragment to show the details in the same activity (adding the fragment to the {@link -android.widget.FrameLayout}), or start a new activity (where the fragment can be shown).</p> - -{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java titles} - -<p>The second fragment, {@code DetailsFragment} shows the play summary for the item selected from -the list from {@code TitlesFragment}:</p> - -{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java details} - -<p>Recall from the {@code TitlesFragment} class, that, if the user clicks a list item and the -current layout does <em>not</em> include the {@code R.id.details} view (which is where the -{@code DetailsFragment} belongs), then the application starts the {@code DetailsActivity} -activity to display the content of the item.</p> - -<p>Here is the {@code DetailsActivity}, which simply embeds the {@code DetailsFragment} to display -the selected play summary when the screen is in portrait orientation:</p> - -{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java -details_activity} - -<p>Notice that this activity finishes itself if the configuration is landscape, so that the main -activity can take over and display the {@code DetailsFragment} alongside the {@code TitlesFragment}. -This can happen if the user begins the {@code DetailsActivity} while in portrait orientation, but -then rotates to landscape (which restarts the current activity).</p> - - -<p>For more samples using fragments (and complete source files for this example), -see the sample code available in <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#Fragment"> -ApiDemos</a> (available for download from the <a -href="{@docRoot}resources/samples/get.html">Samples SDK component</a>).</p> - - diff --git a/docs/html/guide/topics/fundamentals/loaders.jd b/docs/html/guide/topics/fundamentals/loaders.jd deleted file mode 100644 index ddd513b..0000000 --- a/docs/html/guide/topics/fundamentals/loaders.jd +++ /dev/null @@ -1,500 +0,0 @@ -page.title=Loaders -parent.title=Activities -parent.link=activities.html -@jd:body -<div id="qv-wrapper"> -<div id="qv"> - <h2>In this document</h2> - <ol> - <li><a href="#summary">Loader API Summary</a></li> - <li><a href="#app">Using Loaders in an Application</a> - <ol> - <li><a href="#requirements"></a></li> - <li><a href="#starting">Starting a Loader</a></li> - <li><a href="#restarting">Restarting a Loader</a></li> - <li><a href="#callback">Using the LoaderManager Callbacks</a></li> - </ol> - </li> - <li><a href="#example">Example</a> - <ol> - <li><a href="#more_examples">More Examples</a></li> - </ol> - </li> - </ol> - - <h2>Key classes</h2> - <ol> - <li>{@link android.app.LoaderManager}</li> - <li>{@link android.content.Loader}</li> - - </ol> - - <h2>Related samples</h2> - <ol> - <li> <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderCursor.html"> -LoaderCursor</a></li> - <li> <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> -LoaderThrottle</a></li> - </ol> - </div> -</div> - -<p>Introduced in Android 3.0, loaders make it easy to asynchronously load data -in an activity or fragment. Loaders have these characteristics:</p> - <ul> - <li>They are available to every {@link android.app.Activity} and {@link -android.app.Fragment}.</li> - <li>They provide asynchronous loading of data.</li> - <li>They monitor the source of their data and deliver new results when the -content changes.</li> - <li>They automatically reconnect to the last loader's cursor when being -recreated after a configuration change. Thus, they don't need to re-query their -data.</li> - </ul> - -<h2 id="summary">Loader API Summary</h2> - -<p>There are multiple classes and interfaces that may be involved in using -loaders in an application. They are summarized in this table:</p> - -<table> - <tr> - <th>Class/Interface</th> - <th>Description</th> - </tr> - <tr> - <td>{@link android.app.LoaderManager}</td> - <td>An abstract class associated with an {@link android.app.Activity} or -{@link android.app.Fragment} for managing one or more {@link -android.content.Loader} instances. This helps an application manage -longer-running operations in conjunction with the {@link android.app.Activity} -or {@link android.app.Fragment} lifecycle; the most common use of this is with a -{@link android.content.CursorLoader}, however applications are free to write -their own loaders for loading other types of data. - <br /> - <br /> - There is only one {@link android.app.LoaderManager} per activity or fragment. But a {@link android.app.LoaderManager} can have -multiple loaders.</td> - </tr> - <tr> - <td>{@link android.app.LoaderManager.LoaderCallbacks}</td> - <td>A callback interface for a client to interact with the {@link -android.app.LoaderManager}. For example, you use the {@link -android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()} -callback method to create a new loader.</td> - </tr> - <tr> - <td>{@link android.content.Loader}</td> - <td>An abstract class that performs asynchronous loading of data. This is -the base class for a loader. You would typically use {@link -android.content.CursorLoader}, but you can implement your own subclass. While -loaders are active they should monitor the source of their data and deliver new -results when the contents change. </td> - </tr> - <tr> - <td>{@link android.content.AsyncTaskLoader}</td> - <td>Abstract loader that provides an {@link android.os.AsyncTask} to do the work.</td> - </tr> - <tr> - <td>{@link android.content.CursorLoader}</td> - <td>A subclass of {@link android.content.AsyncTaskLoader} that queries the -{@link android.content.ContentResolver} and returns a {@link -android.database.Cursor}. This class implements the {@link -android.content.Loader} protocol in a standard way for querying cursors, -building on {@link android.content.AsyncTaskLoader} to perform the cursor query -on a background thread so that it does not block the application's UI. Using -this loader is the best way to asynchronously load data from a {@link -android.content.ContentProvider}, instead of performing a managed query through -the fragment or activity's APIs.</td> - </tr> -</table> - -<p>The classes and interfaces in the above table are the essential components -you'll use to implement a loader in your application. You won't need all of them -for each loader you create, but you'll always need a reference to the {@link -android.app.LoaderManager} in order to initialize a loader and an implementation -of a {@link android.content.Loader} class such as {@link -android.content.CursorLoader}. The following sections show you how to use these -classes and interfaces in an application.</p> - -<h2 id ="app">Using Loaders in an Application</h2> -<p>This section describes how to use loaders in an Android application. An -application that uses loaders typically includes the following:</p> -<ul> - <li>An {@link android.app.Activity} or {@link android.app.Fragment}.</li> - <li>An instance of the {@link android.app.LoaderManager}.</li> - <li>A {@link android.content.CursorLoader} to load data backed by a {@link -android.content.ContentProvider}. Alternatively, you can implement your own subclass -of {@link android.content.Loader} or {@link android.content.AsyncTaskLoader} to -load data from some other source.</li> - <li>An implementation for {@link android.app.LoaderManager.LoaderCallbacks}. -This is where you create new loaders and manage your references to existing -loaders.</li> -<li>A way of displaying the loader's data, such as a {@link -android.widget.SimpleCursorAdapter}.</li> - <li>A data source, such as a {@link android.content.ContentProvider}, when using a -{@link android.content.CursorLoader}.</li> -</ul> -<h3 id="starting">Starting a Loader</h3> - -<p>The {@link android.app.LoaderManager} manages one or more {@link -android.content.Loader} instances within an {@link android.app.Activity} or -{@link android.app.Fragment}. There is only one {@link -android.app.LoaderManager} per activity or fragment.</p> - -<p>You typically -initialize a {@link android.content.Loader} within the activity's {@link -android.app.Activity#onCreate onCreate()} method, or within the fragment's -{@link android.app.Fragment#onActivityCreated onActivityCreated()} method. You -do this as follows:</p> - -<pre>// Prepare the loader. Either re-connect with an existing one, -// or start a new one. -getLoaderManager().initLoader(0, null, this);</pre> - -<p>The {@link android.app.LoaderManager#initLoader initLoader()} method takes -the following parameters:</p> -<ul> - <li>A unique ID that identifies the loader. In this example, the ID is 0.</li> -<li>Optional arguments to supply to the loader at -construction (<code>null</code> in this example).</li> - -<li>A {@link android.app.LoaderManager.LoaderCallbacks} implementation, which -the {@link android.app.LoaderManager} calls to report loader events. In this -example, the local class implements the {@link -android.app.LoaderManager.LoaderCallbacks} interface, so it passes a reference -to itself, {@code this}.</li> -</ul> -<p>The {@link android.app.LoaderManager#initLoader initLoader()} call ensures that a loader -is initialized and active. It has two possible outcomes:</p> -<ul> - <li>If the loader specified by the ID already exists, the last created loader -is reused.</li> - <li>If the loader specified by the ID does <em>not</em> exist, -{@link android.app.LoaderManager#initLoader initLoader()} triggers the -{@link android.app.LoaderManager.LoaderCallbacks} method {@link android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}. -This is where you implement the code to instantiate and return a new loader. -For more discussion, see the section <a -href="#onCreateLoader">onCreateLoader</a>.</li> -</ul> -<p>In either case, the given {@link android.app.LoaderManager.LoaderCallbacks} -implementation is associated with the loader, and will be called when the -loader state changes. If at the point of this call the caller is in its -started state, and the requested loader already exists and has generated its -data, then the system calls {@link -android.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()} -immediately (during {@link android.app.LoaderManager#initLoader initLoader()}), -so you must be prepared for this to happen. See <a href="#onLoadFinished"> -onLoadFinished</a> for more discussion of this callback</p> - -<p>Note that the {@link android.app.LoaderManager#initLoader initLoader()} -method returns the {@link android.content.Loader} that is created, but you don't -need to capture a reference to it. The {@link android.app.LoaderManager} manages -the life of the loader automatically. The {@link android.app.LoaderManager} -starts and stops loading when necessary, and maintains the state of the loader -and its associated content. As this implies, you rarely interact with loaders -directly (though for an example of using loader methods to fine-tune a loader's -behavior, see the <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> LoaderThrottle</a> sample). -You most commonly use the {@link -android.app.LoaderManager.LoaderCallbacks} methods to intervene in the loading -process when particular events occur. For more discussion of this topic, see <a -href="#callback">Using the LoaderManager Callbacks</a>.</p> - -<h3 id="restarting">Restarting a Loader</h3> - -<p>When you use {@link android.app.LoaderManager#initLoader initLoader()}, as -shown above, it uses an existing loader with the specified ID if there is one. -If there isn't, it creates one. But sometimes you want to discard your old data -and start over.</p> - -<p>To discard your old data, you use {@link -android.app.LoaderManager#restartLoader restartLoader()}. For example, this -implementation of {@link android.widget.SearchView.OnQueryTextListener} restarts -the loader when the user's query changes. The loader needs to be restarted so -that it can use the revised search filter to do a new query:</p> - -<pre> -public boolean onQueryTextChanged(String newText) { - // Called when the action bar search text has changed. Update - // the search filter, and restart the loader to do a new query - // with this filter. - mCurFilter = !TextUtils.isEmpty(newText) ? newText : null; - getLoaderManager().restartLoader(0, null, this); - return true; -}</pre> - -<h3 id="callback">Using the LoaderManager Callbacks</h3> - -<p>{@link android.app.LoaderManager.LoaderCallbacks} is a callback interface -that lets a client interact with the {@link android.app.LoaderManager}. </p> -<p>Loaders, in particular {@link android.content.CursorLoader}, are expected to -retain their data after being stopped. This allows applications to keep their -data across the activity or fragment's {@link android.app.Activity#onStop -onStop()} and {@link android.app.Activity#onStart onStart()} methods, so that -when users return to an application, they don't have to wait for the data to -reload. You use the {@link android.app.LoaderManager.LoaderCallbacks} methods -when to know when to create a new loader, and to tell the application when it is - time to stop using a loader's data.</p> - -<p>{@link android.app.LoaderManager.LoaderCallbacks} includes these -methods:</p> -<ul> - <li>{@link android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()} — -Instantiate and return a new {@link android.content.Loader} for the given ID. -</li></ul> -<ul> - <li> {@link android.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()} -— Called when a previously created loader has finished its load. -</li></ul> -<ul> - <li>{@link android.app.LoaderManager.LoaderCallbacks#onLoaderReset onLoaderReset()} - — Called when a previously created loader is being reset, thus making its -data unavailable. -</li> -</ul> -<p>These methods are described in more detail in the following sections.</p> - -<h4 id ="onCreateLoader">onCreateLoader</h4> - -<p>When you attempt to access a loader (for example, through {@link -android.app.LoaderManager#initLoader initLoader()}), it checks to see whether -the loader specified by the ID exists. If it doesn't, it triggers the {@link -android.app.LoaderManager.LoaderCallbacks} method {@link -android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}. This -is where you create a new loader. Typically this will be a {@link -android.content.CursorLoader}, but you can implement your own {@link -android.content.Loader} subclass. </p> - -<p>In this example, the {@link -android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()} -callback method creates a {@link android.content.CursorLoader}. You must build -the {@link android.content.CursorLoader} using its constructor method, which -requires the complete set of information needed to perform a query to the {@link -android.content.ContentProvider}. Specifically, it needs:</p> -<ul> - <li><em>uri</em> — The URI for the content to retrieve. </li> - <li><em>projection</em> — A list of which columns to return. Passing -<code>null</code> will return all columns, which is inefficient. </li> - <li><em>selection</em> — A filter declaring which rows to return, -formatted as an SQL WHERE clause (excluding the WHERE itself). Passing -<code>null</code> will return all rows for the given URI. </li> - <li><em>selectionArgs</em> — You may include ?s in the selection, which will -be replaced by the values from <em>selectionArgs</em>, in the order that they appear in -the selection. The values will be bound as Strings. </li> - <li><em>sortOrder</em> — How to order the rows, formatted as an SQL -ORDER BY clause (excluding the ORDER BY itself). Passing <code>null</code> will -use the default sort order, which may be unordered.</li> -</ul> -<p>For example:</p> -<pre> - // If non-null, this is the current filter the user has provided. -String mCurFilter; -... -public Loader<Cursor> onCreateLoader(int id, Bundle args) { - // This is called when a new Loader needs to be created. This - // sample only has one Loader, so we don't care about the ID. - // First, pick the base URI to use depending on whether we are - // currently filtering. - Uri baseUri; - if (mCurFilter != null) { - baseUri = Uri.withAppendedPath(Contacts.CONTENT_FILTER_URI, - Uri.encode(mCurFilter)); - } else { - baseUri = Contacts.CONTENT_URI; - } - - // Now create and return a CursorLoader that will take care of - // creating a Cursor for the data being displayed. - String select = "((" + Contacts.DISPLAY_NAME + " NOTNULL) AND (" - + Contacts.HAS_PHONE_NUMBER + "=1) AND (" - + Contacts.DISPLAY_NAME + " != '' ))"; - return new CursorLoader(getActivity(), baseUri, - CONTACTS_SUMMARY_PROJECTION, select, null, - Contacts.DISPLAY_NAME + " COLLATE LOCALIZED ASC"); -}</pre> -<h4 id="onLoadFinished">onLoadFinished</h4> - -<p>This method is called when a previously created loader has finished its load. -This method is guaranteed to be called prior to the release of the last data -that was supplied for this loader. At this point you should remove all use of -the old data (since it will be released soon), but should not do your own -release of the data since its loader owns it and will take care of that.</p> - - -<p>The loader will release the data once it knows the application is no longer -using it. For example, if the data is a cursor from a {@link -android.content.CursorLoader}, you should not call {@link -android.database.Cursor#close close()} on it yourself. If the cursor is being -placed in a {@link android.widget.CursorAdapter}, you should use the {@link -android.widget.SimpleCursorAdapter#swapCursor swapCursor()} method so that the -old {@link android.database.Cursor} is not closed. For example:</p> - -<pre> -// This is the Adapter being used to display the list's data.<br -/>SimpleCursorAdapter mAdapter; -... - -public void onLoadFinished(Loader<Cursor> loader, Cursor data) { - // Swap the new cursor in. (The framework will take care of closing the - // old cursor once we return.) - mAdapter.swapCursor(data); -}</pre> - -<h4 id="onLoaderReset">onLoaderReset</h4> - -<p>This method is called when a previously created loader is being reset, thus -making its data unavailable. This callback lets you find out when the data is -about to be released so you can remove your reference to it. </p> -<p>This implementation calls -{@link android.widget.SimpleCursorAdapter#swapCursor swapCursor()} -with a value of <code>null</code>:</p> - -<pre> -// This is the Adapter being used to display the list's data. -SimpleCursorAdapter mAdapter; -... - -public void onLoaderReset(Loader<Cursor> loader) { - // This is called when the last Cursor provided to onLoadFinished() - // above is about to be closed. We need to make sure we are no - // longer using it. - mAdapter.swapCursor(null); -}</pre> - - -<h2 id="example">Example</h2> - -<p>As an example, here is the full implementation of a {@link -android.app.Fragment} that displays a {@link android.widget.ListView} containing -the results of a query against the contacts content provider. It uses a {@link -android.content.CursorLoader} to manage the query on the provider.</p> - -<p>For an application to access a user's contacts, as shown in this example, its -manifest must include the permission -{@link android.Manifest.permission#READ_CONTACTS READ_CONTACTS}.</p> - -<pre> -public static class CursorLoaderListFragment extends ListFragment - implements OnQueryTextListener, LoaderManager.LoaderCallbacks<Cursor> { - - // This is the Adapter being used to display the list's data. - SimpleCursorAdapter mAdapter; - - // If non-null, this is the current filter the user has provided. - String mCurFilter; - - @Override public void onActivityCreated(Bundle savedInstanceState) { - super.onActivityCreated(savedInstanceState); - - // Give some text to display if there is no data. In a real - // application this would come from a resource. - setEmptyText("No phone numbers"); - - // We have a menu item to show in action bar. - setHasOptionsMenu(true); - - // Create an empty adapter we will use to display the loaded data. - mAdapter = new SimpleCursorAdapter(getActivity(), - android.R.layout.simple_list_item_2, null, - new String[] { Contacts.DISPLAY_NAME, Contacts.CONTACT_STATUS }, - new int[] { android.R.id.text1, android.R.id.text2 }, 0); - setListAdapter(mAdapter); - - // Prepare the loader. Either re-connect with an existing one, - // or start a new one. - getLoaderManager().initLoader(0, null, this); - } - - @Override public void onCreateOptionsMenu(Menu menu, MenuInflater inflater) { - // Place an action bar item for searching. - MenuItem item = menu.add("Search"); - item.setIcon(android.R.drawable.ic_menu_search); - item.setShowAsAction(MenuItem.SHOW_AS_ACTION_IF_ROOM); - SearchView sv = new SearchView(getActivity()); - sv.setOnQueryTextListener(this); - item.setActionView(sv); - } - - public boolean onQueryTextChange(String newText) { - // Called when the action bar search text has changed. Update - // the search filter, and restart the loader to do a new query - // with this filter. - mCurFilter = !TextUtils.isEmpty(newText) ? newText : null; - getLoaderManager().restartLoader(0, null, this); - return true; - } - - @Override public boolean onQueryTextSubmit(String query) { - // Don't care about this. - return true; - } - - @Override public void onListItemClick(ListView l, View v, int position, long id) { - // Insert desired behavior here. - Log.i("FragmentComplexList", "Item clicked: " + id); - } - - // These are the Contacts rows that we will retrieve. - static final String[] CONTACTS_SUMMARY_PROJECTION = new String[] { - Contacts._ID, - Contacts.DISPLAY_NAME, - Contacts.CONTACT_STATUS, - Contacts.CONTACT_PRESENCE, - Contacts.PHOTO_ID, - Contacts.LOOKUP_KEY, - }; - public Loader<Cursor> onCreateLoader(int id, Bundle args) { - // This is called when a new Loader needs to be created. This - // sample only has one Loader, so we don't care about the ID. - // First, pick the base URI to use depending on whether we are - // currently filtering. - Uri baseUri; - if (mCurFilter != null) { - baseUri = Uri.withAppendedPath(Contacts.CONTENT_FILTER_URI, - Uri.encode(mCurFilter)); - } else { - baseUri = Contacts.CONTENT_URI; - } - - // Now create and return a CursorLoader that will take care of - // creating a Cursor for the data being displayed. - String select = "((" + Contacts.DISPLAY_NAME + " NOTNULL) AND (" - + Contacts.HAS_PHONE_NUMBER + "=1) AND (" - + Contacts.DISPLAY_NAME + " != '' ))"; - return new CursorLoader(getActivity(), baseUri, - CONTACTS_SUMMARY_PROJECTION, select, null, - Contacts.DISPLAY_NAME + " COLLATE LOCALIZED ASC"); - } - - public void onLoadFinished(Loader<Cursor> loader, Cursor data) { - // Swap the new cursor in. (The framework will take care of closing the - // old cursor once we return.) - mAdapter.swapCursor(data); - } - - public void onLoaderReset(Loader<Cursor> loader) { - // This is called when the last Cursor provided to onLoadFinished() - // above is about to be closed. We need to make sure we are no - // longer using it. - mAdapter.swapCursor(null); - } -}</pre> -<h3 id="more_examples">More Examples</h3> - -<p>There are a few different samples in <strong>ApiDemos</strong> that -illustrate how to use loaders:</p> -<ul> - <li><a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderCursor.html"> -LoaderCursor</a> — A complete version of the -snippet shown above.</li> - <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> LoaderThrottle</a> — An example of how to use throttling to -reduce the number of queries a content provider does when its data changes.</li> -</ul> - -<p>For information on downloading and installing the SDK samples, see <a -href="http://developer.android.com/resources/samples/get.html"> Getting the -Samples</a>. </p> - diff --git a/docs/html/guide/topics/fundamentals/processes-and-threads.jd b/docs/html/guide/topics/fundamentals/processes-and-threads.jd deleted file mode 100644 index 814d34e..0000000 --- a/docs/html/guide/topics/fundamentals/processes-and-threads.jd +++ /dev/null @@ -1,486 +0,0 @@ -page.title=Processes and Threads -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> -<h2>Quickview</h2> -<ul> - <li>Every application runs in its own process and all components of the application run in that -process, by default</li> - <li>Any slow, blocking operations in an activity should be done in a new thread, to avoid slowing -down the user interface</li> -</ul> - -<h2>In this document</h2> -<ol> -<li><a href="#Processes">Processes</a> - <ol> - <li><a href="#Lifecycle">Process lifecycle</a></li> - </ol> -</li> -<li><a href="#Threads">Threads</a> - <ol> - <li><a href="#WorkerThreads">Worker threads</a></li> - <li><a href="#ThreadSafe">Thread-safe methods</a></li> - </ol> -</li> -<li><a href="#IPC">Interprocess Communication</a></li> -</ol> - -</div> -</div> - -<p>When an application component starts and the process that should host that thread is not already -running, the Android system starts a new Linux process for the application with a single thread of -execution. By default, all components of the same application run in the same process and thread -(called the "main" thread). If an application component starts and there already exists a process -for that application (because another component from the application exists or Android has been -able to retain its previous process cached in the background), then the component is -started within that process and uses the same thread of execution. However, you can arrange for -different components in your application to run in separate processes, and you can create additional -threads for any process.</p> - -<p>This document discusses how processes and threads work in an Android application.</p> - - -<h2 id="Processes">Processes</h2> - -<p>By default, all components of the same application run in the same process and most applications -should not change this. However, if you find that you need to control which process a certain -component belongs to, you can do so in the manifest file.</p> - -<p>The manifest entry for each type of component element—<a -href="{@docRoot}guide/topics/manifest/activity-element.html">{@code -<activity>}</a>, <a href="{@docRoot}guide/topics/manifest/service-element.html">{@code -<service>}</a>, <a href="{@docRoot}guide/topics/manifest/receiver-element.html">{@code -<receiver>}</a>, and <a href="{@docRoot}guide/topics/manifest/provider-element.html">{@code -<provider>}</a>—supports an {@code android:process} attribute that can specify a -process in which that component should run. You can set this attribute so that each component runs -in its own process or so that some components share a process while others do not. You can also set -{@code android:process} so that components of different applications run in the same -process—provided that the applications share the same Linux user ID and are signed with the -same certificates.</p> - -<p>The <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code -<application>}</a> element also supports an {@code android:process} attribute, to set a -default value that applies to all components.</p> - -<p>Android might decide to shut down a process at some point, when memory is low and required by -other processes that are more immediately serving the user. Application -components running in the process that's killed are consequently destroyed. A process is started -again for those components when there's again work for them to do.</p> - -<p>When deciding which processes to kill, the Android system weighs their relative importance to -the user. For example, it more readily shuts down a process hosting activities that are no longer -visible on screen, compared to a process hosting visible activities. The decision whether to -terminate a process, therefore, depends on the state of the components running in that process. The -rules used to decide which processes to terminate is discussed below. </p> - - -<h3 id="Lifecycle">Process lifecycle</h3> - -<p>The Android system tries to maintain an application process for as long as possible, but -eventually needs to remove old processes to reclaim memory for new or more important processes. To -determine which processes to keep -and which to kill, the system places each process into an "importance hierarchy" based on the -components running in the process and the state of those components. Processes with the lowest -importance are eliminated first, then those with the next lowest importance, and so on, as necessary -to recover system resources.</p> - -<p>The exact mapping of processes to importance and the management of these processes is -an implementation detail of the platform that changes over time. Broadly speaking, there -are five levels in the current implementation that are of most relevance to application -developers. The following list presents these different -types of processes in order of importance (the first process is <em>most important</em> and is -<em>killed last</em>):</p> - -<ol> - <li><b>Foreground process</b> - <p>A process that is required for what the user is currently doing. A - process is considered to be in the foreground if any of the following conditions are true:</p> - - <ul> - <li>It hosts an {@link android.app.Activity} that the user is interacting with (the {@link -android.app.Activity}'s {@link android.app.Activity#onResume onResume()} method has been -called).</li> - - <li>It hosts a {@link android.app.Service} that's executing one of its lifecycle -callbacks ({@link android.app.Service#onCreate onCreate()}, {@link android.app.Service#onStart -onStart()}, or {@link android.app.Service#onDestroy onDestroy()}).</li> - - <li>It hosts a {@link android.content.BroadcastReceiver} that's executing its {@link - android.content.BroadcastReceiver#onReceive onReceive()} method.</li> - - <li>Another foreground process has a dependency on this one: either bound - to a Service in this process, or using a Content Provider of the process.</li> - </ul> - - <p>Generally, only a few foreground processes exist at any given time. They are killed only as -a last resort—if memory is so low that they cannot all continue to run. Generally, at that -point, the device has reached a memory paging state, so killing some foreground processes is -required to keep the user interface responsive.</p></li> - - <li><b>Visible process</b> - <p>A process that doesn't have any foreground components, but still can - affect what the user sees on screen. A process is considered to be visible if either of the - following conditions are true:</p> - - <ul> - <li>It hosts an {@link android.app.Activity} that is not in the foreground, but is still -visible to the user (its {@link android.app.Activity#onPause onPause()} method has been called). -This might occur, for example, if the foreground activity started a dialog, which allows the -previous activity to be seen behind it.</li> - - <li>Another visible process has a dependency on this one: either bound - to a Service in this process, or using a Content Provider of the process.</li> - </ul> - - <p>A visible process is considered extremely important and will not be killed unless doing so -is required to keep all foreground processes running. </p> - </li> - - <li><b>Perceptible process</b> - <p>A process that doesn't have any foreground or visible components, but is still - doing something that is directly perceptible by the user. A classic example of such - a process would be one doing background music playback. The main way applications - get into this state is through {@link android.app.Service#startForeground} or because - another perceptible process has a dependency on one of its services or content - providers. In addition, as of {@link android.os.Build.VERSION_CODES#HONEYCOMB}, - processes can go into this state when {@link android.app.Activity#onStop - Activity.onStop()} is executing, allowing the process to continue executing - critical code after no longer being visible to the user but before going - fully into the background.</p> - - <p>Like visible processes, a perceptible process is considered extremely important - and will not be killed unless doing so is required to keep all foreground and - visible processes running. </p> - </li> - - <li><b>Service process</b> - <p>A process that is running a service that has been started with the {@link -android.content.Context#startService startService()} method and does not fall into any of the -higher categories. Although service processes are not directly tied to anything the user sees, they -are generally doing things that the user cares about (such as downloading a file the user has requested), -so the system keeps them running unless there's not enough memory to retain them along with all -foreground and visible processes. </p> - - <p>Even though Android tries to keep these processes running, it is considered normal - operation for them to temporarily be killed to support the needs of more important - processes. For example, if the user opens a very heavy-weight web page that needs - most of the device's RAM, background services may be temporarily killed to satisfy - those needs. Services in these processes thus must be prepared to deal gracefully - with being killed while doing their work and later restarted.</p> - - <p>In recent implementations of Android, there are actually a number of sub-divisions - in this area for processes that Android considers more important to the user and so - would like to try harder to keep around. For example, the process hosting the current - home app is generally kept in this area so that the user will not see long delays in - returning home because that process has been killed.</p> - </li> - - <li><b>Background (cached) process</b> - <p>The final importance level is for processes that are not of current significance. - This is basically any process that does not fall into one of the previous levels. - These processes have no direct impact on the user experience, and the system can kill - them at any time to reclaim memory for the other more important processes. - This includes everything from processes holding running activity objects that are not currently - visible to the user (the activity's {@link android.app.Activity#onStop onStop()} - method has been called) to processes that have no active code at all but may be - useful to keep around in case they are needed in the near future.</p> - - <p>Usually there are many background processes being maintained, so they are kept - in an LRU list to allow older processes to be killed before more recent ones. This - helps reduce the frequency that new processes need to be creating, facilitating things - like more rapid switching between the applications the user has recently visited. - However, processes in this state must deal correctly with being killed and later - restarted when needed. For example, if an activity implements its lifecycle methods -correctly, and saves its current state, killing its process will not have a visible effect on -the user experience, because when the user navigates back to the activity, the activity restores -all of its visible state. See the <a -href="{@docRoot}guide/topics/fundamentals/activities.html#SavingActivityState">Activities</a> -document for information about saving and restoring state.</p> - - <p>Android may also employ other additional policies for killing background processes. For - example, there are typically restrictions on a maximum number of such processes to - keep around, and limits on the amount of time they can spend holding wake locks - or consuming CPU power until they will be removed.</p> - </li> -</ol> - - - <p>Android ranks a process at the highest level it can, based upon the importance of the -components currently active in the process. For example, if a process hosts a service and a visible -activity, the process is ranked as a visible process, not a service process.</p> - - <p>In addition, a process's ranking might be increased because other processes are dependent on -it—a process that is serving another process can not generally be ranked lower than the process it is -serving. For example, if a content provider in process A is serving a client in process B, or if a -service in process A has been bound to by a client in process B, process A is always considered at least -as important as process B.</p> - - <p>Because a process running a service is ranked higher than a process with background activities, -an activity that initiates a long-running operation may sometimes start a <a -href="{@docRoot}guide/topics/fundamentals/services.html">service</a> for that operation, rather than -simply create a worker thread—but only when the operation is a specific task that needs -to be accomplished regardless of whether the user returns to the application. -For example, an activity that's uploading a picture to a web site should start a service to perform -the upload so that the upload can continue in the background even if the user leaves the activity. -Using a service guarantees that the operation will have at least "service process" priority, -regardless of what happens to the activity. This is not however an approach that should always -be used. It would not be appropriate when simply downloading the data for a web page, since -that can easily be restarted later if the user returns to the web browser. Allowing -such a process to be in the background (instead of running a service) gives Android better -information about how to manage that process in relation to others. - - <p>For a similar reason, broadcast receivers will often employ services rather than - simply put time-consuming operations in a thread.</p> - - <p>Some command line tools are available to help you understand how Android is managing - its processes. The most common command is <code>adb shell dumpsys activity</code> - which provides a summary of various key state, including at the end a list of the - process states, one per line (plus an optional second line for any key dependency - on that process), ordered from higher importance to lowest. The exact - contents of these lines has changed across different versions of Android, but the - typical state for one process in the list would be:</p> - <pre> -Proc # 2: adj=prcp /F trm= 0 848:com.google.android.inputmethod.latin/u0a32 (service) - com.google.android.inputmethod.latin/com.android.inputmethod.latin.LatinIME<=Proc{417:system/1000} -</pre> - - <p>This is a perceptible process (adj=prcp) that is running with the foreground - scheduling class (/F), and has not recently been told to trim any memory - (trm= 0). Its process id is 848; its name is com.google.android.inputmethod.latin; - its Linux uid is u0a32 (10032), and the key state contributing to its current - importance level is a service.</p> - - <p>The second line provides the name of the service that is important, because another - process has a dependency on it (here the system process).</p> - -<h2 id="Threads">Threads</h2> - -<p>When an application is launched, the system creates a thread of execution for the application, -called "main." This thread is very important because it is in charge of dispatching events to -the appropriate user interface widgets, including drawing events. It is also the thread in which -your application interacts with components from the Android UI toolkit (components from the {@link -android.widget} and {@link android.view} packages). As such, the main thread is also sometimes -called the UI thread.</p> - -<p>The system does <em>not</em> create a separate thread for each instance of a component. All -components that run in the same process are instantiated in the UI thread, and system calls to -each component are dispatched from that thread. Consequently, methods that respond to system -callbacks (such as {@link android.view.View#onKeyDown onKeyDown()} to report user actions -or a lifecycle callback method) always run in the UI thread of the process.</p> - -<p>For instance, when the user touches a button on the screen, your app's UI thread dispatches the -touch event to the widget, which in turn sets its pressed state and posts an invalidate request to -the event queue. The UI thread dequeues the request and notifies the widget that it should redraw -itself.</p> - -<p>When your app performs intensive work in response to user interaction, this single thread model -can yield poor performance unless you implement your application properly. Specifically, if -everything is happening in the UI thread, performing long operations such as network access or -database queries will block the whole UI. When the thread is blocked, no events can be dispatched, -including drawing events. From the user's perspective, the -application appears to hang. Even worse, if the UI thread is blocked for more than a few seconds -(about 5 seconds currently) the user is presented with the infamous "<a -href="http://developer.android.com/guide/practices/design/responsiveness.html">application not -responding</a>" (ANR) dialog. The user might then decide to quit your application and uninstall it -if they are unhappy.</p> - -<p>Additionally, the Andoid UI toolkit is <em>not</em> thread-safe. So, you must not manipulate -your UI from a worker thread—you must do all manipulation to your user interface from the UI -thread. Thus, there are simply two rules to Android's single thread model:</p> - -<ol> -<li>Do not block the UI thread -<li>Do not access the Android UI toolkit from outside the UI thread -</ol> - -<h3 id="WorkerThreads">Worker threads</h3> - -<p>Because of the single thread model described above, it's vital to the responsiveness of your -application's UI that you do not block the UI thread. If you have operations to perform -that are not instantaneous, you should make sure to do them in separate threads ("background" or -"worker" threads).</p> - -<p>For example, below is some code for a click listener that downloads an image from a separate -thread and displays it in an {@link android.widget.ImageView}:</p> - -<pre> -public void onClick(View v) { - new Thread(new Runnable() { - public void run() { - Bitmap b = loadImageFromNetwork("http://example.com/image.png"); - mImageView.setImageBitmap(b); - } - }).start(); -} -</pre> - -<p>At first, this seems to work fine, because it creates a new thread to handle the network -operation. However, it violates the second rule of the single-threaded model: <em>do not access the -Android UI toolkit from outside the UI thread</em>—this sample modifies the {@link -android.widget.ImageView} from the worker thread instead of the UI thread. This can result in -undefined and unexpected behavior, which can be difficult and time-consuming to track down.</p> - -<p>To fix this problem, Android offers several ways to access the UI thread from other -threads. Here is a list of methods that can help:</p> - -<ul> -<li>{@link android.app.Activity#runOnUiThread(java.lang.Runnable) -Activity.runOnUiThread(Runnable)}</li> -<li>{@link android.view.View#post(java.lang.Runnable) View.post(Runnable)}</li> -<li>{@link android.view.View#postDelayed(java.lang.Runnable, long) View.postDelayed(Runnable, -long)}</li> -</ul> - -<p>For example, you can fix the above code by using the {@link -android.view.View#post(java.lang.Runnable) View.post(Runnable)} method:</p> - -<pre> -public void onClick(View v) { - new Thread(new Runnable() { - public void run() { - final Bitmap bitmap = loadImageFromNetwork("http://example.com/image.png"); - mImageView.post(new Runnable() { - public void run() { - mImageView.setImageBitmap(bitmap); - } - }); - } - }).start(); -} -</pre> - -<p>Now this implementation is thread-safe: the network operation is done from a separate thread -while the {@link android.widget.ImageView} is manipulated from the UI thread.</p> - -<p>However, as the complexity of the operation grows, this kind of code can get complicated and -difficult to maintain. To handle more complex interactions with a worker thread, you might consider -using a {@link android.os.Handler} in your worker thread, to process messages delivered from the UI -thread. Perhaps the best solution, though, is to extend the {@link android.os.AsyncTask} class, -which simplifies the execution of worker thread tasks that need to interact with the UI.</p> - - -<h4 id="AsyncTask">Using AsyncTask</h4> - -<p>{@link android.os.AsyncTask} allows you to perform asynchronous work on your user -interface. It performs the blocking operations in a worker thread and then publishes the results on -the UI thread, without requiring you to handle threads and/or handlers yourself.</p> - -<p>To use it, you must subclass {@link android.os.AsyncTask} and implement the {@link -android.os.AsyncTask#doInBackground doInBackground()} callback method, which runs in a pool of -background threads. To update your UI, you should implement {@link -android.os.AsyncTask#onPostExecute onPostExecute()}, which delivers the result from {@link -android.os.AsyncTask#doInBackground doInBackground()} and runs in the UI thread, so you can safely -update your UI. You can then run the task by calling {@link android.os.AsyncTask#execute execute()} -from the UI thread.</p> - -<p>For example, you can implement the previous example using {@link android.os.AsyncTask} this -way:</p> - -<pre> -public void onClick(View v) { - new DownloadImageTask().execute("http://example.com/image.png"); -} - -private class DownloadImageTask extends AsyncTask<String, Void, Bitmap> { - /** The system calls this to perform work in a worker thread and - * delivers it the parameters given to AsyncTask.execute() */ - protected Bitmap doInBackground(String... urls) { - return loadImageFromNetwork(urls[0]); - } - - /** The system calls this to perform work in the UI thread and delivers - * the result from doInBackground() */ - protected void onPostExecute(Bitmap result) { - mImageView.setImageBitmap(result); - } -} -</pre> - -<p>Now the UI is safe and the code is simpler, because it separates the work into the -part that should be done on a worker thread and the part that should be done on the UI thread.</p> - -<p>You should read the {@link android.os.AsyncTask} reference for a full understanding on -how to use this class, but here is a quick overview of how it works:</p> - -<ul> -<li>You can specify the type of the parameters, the progress values, and the final -value of the task, using generics</li> -<li>The method {@link android.os.AsyncTask#doInBackground doInBackground()} executes automatically -on a worker thread</li> -<li>{@link android.os.AsyncTask#onPreExecute onPreExecute()}, {@link -android.os.AsyncTask#onPostExecute onPostExecute()}, and {@link -android.os.AsyncTask#onProgressUpdate onProgressUpdate()} are all invoked on the UI thread</li> -<li>The value returned by {@link android.os.AsyncTask#doInBackground doInBackground()} is sent to -{@link android.os.AsyncTask#onPostExecute onPostExecute()}</li> -<li>You can call {@link android.os.AsyncTask#publishProgress publishProgress()} at anytime in {@link -android.os.AsyncTask#doInBackground doInBackground()} to execute {@link -android.os.AsyncTask#onProgressUpdate onProgressUpdate()} on the UI thread</li> -<li>You can cancel the task at any time, from any thread</li> -</ul> - -<p class="caution"><strong>Caution:</strong> Another problem you might encounter when using a worker -thread is unexpected restarts in your activity due to a <a -href="{@docRoot}guide/topics/resources/runtime-changes.html">runtime configuration change</a> -(such as when the user changes the screen orientation), which may destroy your worker thread. To -see how you can persist your task during one of these restarts and how to properly cancel the task -when the activity is destroyed, see the source code for the <a -href="http://code.google.com/p/shelves/">Shelves</a> sample application.</p> - - -<h3 id="ThreadSafe">Thread-safe methods</h3> - -<p> In some situations, the methods you implement might be called from more than one thread, and -therefore must be written to be thread-safe. </p> - -<p>This is primarily true for methods that can be called remotely—such as methods in a <a -href="{@docRoot}guide/topics/fundamentals/bound-services.html">bound service</a>. When a call on a -method implemented in an {@link android.os.IBinder} originates in the same process in which the -{@link android.os.IBinder IBinder} is running, the method is executed in the caller's thread. -However, when the call originates in another process, the method is executed in a thread chosen from -a pool of threads that the system maintains in the same process as the {@link android.os.IBinder -IBinder} (it's not executed in the UI thread of the process). For example, whereas a service's -{@link android.app.Service#onBind onBind()} method would be called from the UI thread of the -service's process, methods implemented in the object that {@link android.app.Service#onBind -onBind()} returns (for example, a subclass that implements RPC methods) would be called from threads -in the pool. Because a service can have more than one client, more than one pool thread can engage -the same {@link android.os.IBinder IBinder} method at the same time. {@link android.os.IBinder -IBinder} methods must, therefore, be implemented to be thread-safe.</p> - -<p> Similarly, a content provider can receive data requests that originate in other processes. -Although the {@link android.content.ContentResolver} and {@link android.content.ContentProvider} -classes hide the details of how the interprocess communication is managed, {@link -android.content.ContentProvider} methods that respond to those requests—the methods {@link -android.content.ContentProvider#query query()}, {@link android.content.ContentProvider#insert -insert()}, {@link android.content.ContentProvider#delete delete()}, {@link -android.content.ContentProvider#update update()}, and {@link android.content.ContentProvider#getType -getType()}—are called from a pool of threads in the content provider's process, not the UI -thread for the process. Because these methods might be called from any number of threads at the -same time, they too must be implemented to be thread-safe. </p> - - -<h2 id="IPC">Interprocess Communication</h2> - -<p>Android offers a mechanism for interprocess communication (IPC) using remote procedure calls -(RPCs), in which a method is called by an activity or other application component, but executed -remotely (in another process), with any result returned back to the -caller. This entails decomposing a method call and its data to a level the operating system can -understand, transmitting it from the local process and address space to the remote process and -address space, then reassembling and reenacting the call there. Return values are then -transmitted in the opposite direction. Android provides all the code to perform these IPC -transactions, so you can focus on defining and implementing the RPC programming interface. </p> - -<p>To perform IPC, your application must bind to a service, using {@link -android.content.Context#bindService bindService()}. For more information, see the <a -href="{@docRoot}guide/topics/fundamentals/services.html">Services</a> developer guide.</p> - - -<!-- -<h2>Beginner's Path</h2> - -<p>For information about how to perform work in the background for an indefinite period of time -(without a user interface), continue with the <b><a -href="{@docRoot}guide/topics/fundamentals/services.html">Services</a></b> document.</p> ---> diff --git a/docs/html/guide/topics/fundamentals/services.jd b/docs/html/guide/topics/fundamentals/services.jd deleted file mode 100644 index 9c38897..0000000 --- a/docs/html/guide/topics/fundamentals/services.jd +++ /dev/null @@ -1,874 +0,0 @@ -page.title=Services -@jd:body - -<div id="qv-wrapper"> -<ol id="qv"> -<h2>Quickview</h2> -<ul> - <li>A service can run in the background to perform work even while the user is in a different -application</li> - <li>A service can allow other components to bind to it, in order to interact with it and -perform interprocess communication</li> - <li>A service runs in the main thread of the application that hosts it, by default</li> -</ul> -<h2>In this document</h2> -<ol> -<li><a href="#Basics">The Basics</a></li> -<ol> - <li><a href="#Declaring">Declaring a service in the manifest</a></li> -</ol> -<li><a href="#CreatingAService">Creating a Started Service</a> - <ol> - <li><a href="#ExtendingIntentService">Extending the IntentService class</a></li> - <li><a href="#ExtendingService">Extending the Service class</a></li> - <li><a href="#StartingAService">Starting a service</a></li> - <li><a href="#Stopping">Stopping a service</a></li> - </ol> -</li> -<li><a href="#CreatingBoundService">Creating a Bound Service</a></li> -<li><a href="#Notifications">Sending Notifications to the User</a></li> -<li><a href="#Foreground">Running a Service in the Foreground</a></li> -<li><a href="#Lifecycle">Managing the Lifecycle of a Service</a> -<ol> - <li><a href="#LifecycleCallbacks">Implementing the lifecycle callbacks</a></li> -</ol> -</li> -</ol> - -<h2>Key classes</h2> -<ol> - <li>{@link android.app.Service}</li> - <li>{@link android.app.IntentService}</li> -</ol> - -<h2>Samples</h2> -<ol> - <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ServiceStartArguments.html">{@code - ServiceStartArguments}</a></li> - <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalService.html">{@code - LocalService}</a></li> -</ol> - -<h2>Articles</h2> -<ol> - <li><a href="{@docRoot}resources/articles/multitasking-android-way.html">Multitasking the Android Way</a></li> - <li><a href="{@docRoot}resources/articles/service-api-changes-starting-with.html">Service API changes starting - with Android 2.0</a></li> -</ol> - -<h2>See also</h2> -<ol> -<li><a href="{@docRoot}guide/topics/fundamentals/bound-services.html">Bound Services</a></li> -</ol> - -</div> - - -<p>A {@link android.app.Service} is an application component that can perform -long-running operations in the background and does not provide a user interface. Another -application component can start a service and it will continue to run in the background even if the -user switches to another application. Additionally, a component can bind to a service to -interact with it and even perform interprocess communication (IPC). For example, a service might -handle network transactions, play music, perform file I/O, or interact with a content provider, all -from the background.</p> - -<p>A service can essentially take two forms:</p> - -<dl> - <dt>Started</dt> - <dd>A service is "started" when an application component (such as an activity) starts it by -calling {@link android.content.Context#startService startService()}. Once started, a service -can run in the background indefinitely, even if the component that started it is destroyed. Usually, -a started service performs a single operation and does not return a result to the caller. -For example, it might download or upload a file over the network. When the operation is done, the -service should stop itself.</dd> - <dt>Bound</dt> - <dd>A service is "bound" when an application component binds to it by calling {@link -android.content.Context#bindService bindService()}. A bound service offers a client-server -interface that allows components to interact with the service, send requests, get results, and even -do so across processes with interprocess communication (IPC). A bound service runs only as long as -another application component is bound to it. Multiple components can bind to the service at once, -but when all of them unbind, the service is destroyed.</dd> -</dl> - -<p>Although this documentation generally discusses these two types of services separately, your -service can work both ways—it can be started (to run indefinitely) and also allow binding. -It's simply a matter of whether you implement a couple callback methods: {@link -android.app.Service#onStartCommand onStartCommand()} to allow components to start it and {@link -android.app.Service#onBind onBind()} to allow binding.</p> - -<p>Regardless of whether your application is started, bound, or both, any application component -can use the service (even from a separate application), in the same way that any component can use -an activity—by starting it with an {@link android.content.Intent}. However, you can declare -the service as private, in the manifest file, and block access from other applications. This is -discussed more in the section about <a href="#Declaring">Declaring the service in the -manifest</a>.</p> - -<p class="caution"><strong>Caution:</strong> A service runs in the -main thread of its hosting process—the service does <strong>not</strong> create its own thread -and does <strong>not</strong> run in a separate process (unless you specify otherwise). This means -that, if your service is going to do any CPU intensive work or blocking operations (such as MP3 -playback or networking), you should create a new thread within the service to do that work. By using -a separate thread, you will reduce the risk of Application Not Responding (ANR) errors and the -application's main thread can remain dedicated to user interaction with your activities.</p> - - -<h2 id="Basics">The Basics</h2> - -<div class="sidebox-wrapper"> -<div class="sidebox"> - <h3>Should you use a service or a thread?</h3> - <p>A service is simply a component that can run in the background even when the user is not -interacting with your application. Thus, you should create a service only if that is what you -need.</p> - <p>If you need to perform work outside your main thread, but only while the user is interacting -with your application, then you should probably instead create a new thread and not a service. For -example, if you want to play some music, but only while your activity is running, you might create -a thread in {@link android.app.Activity#onCreate onCreate()}, start running it in {@link -android.app.Activity#onStart onStart()}, then stop it in {@link android.app.Activity#onStop -onStop()}. Also consider using {@link android.os.AsyncTask} or {@link android.os.HandlerThread}, -instead of the traditional {@link java.lang.Thread} class. See the <a -href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#Threads">Processes and -Threading</a> document for more information about threads.</p> - <p>Remember that if you do use a service, it still runs in your application's main thread by -default, so you should still create a new thread within the service if it performs intensive or -blocking operations.</p> -</div> -</div> - -<p>To create a service, you must create a subclass of {@link android.app.Service} (or one -of its existing subclasses). In your implementation, you need to override some callback methods that -handle key aspects of the service lifecycle and provide a mechanism for components to bind to -the service, if appropriate. The most important callback methods you should override are:</p> - -<dl> - <dt>{@link android.app.Service#onStartCommand onStartCommand()}</dt> - <dd>The system calls this method when another component, such as an activity, -requests that the service be started, by calling {@link android.content.Context#startService -startService()}. Once this method executes, the service is started and can run in the -background indefinitely. If you implement this, it is your responsibility to stop the service when -its work is done, by calling {@link android.app.Service#stopSelf stopSelf()} or {@link -android.content.Context#stopService stopService()}. (If you only want to provide binding, you don't -need to implement this method.)</dd> - <dt>{@link android.app.Service#onBind onBind()}</dt> - <dd>The system calls this method when another component wants to bind with the -service (such as to perform RPC), by calling {@link android.content.Context#bindService -bindService()}. In your implementation of this method, you must provide an interface that clients -use to communicate with the service, by returning an {@link android.os.IBinder}. You must always -implement this method, but if you don't want to allow binding, then you should return null.</dd> - <dt>{@link android.app.Service#onCreate()}</dt> - <dd>The system calls this method when the service is first created, to perform one-time setup -procedures (before it calls either {@link android.app.Service#onStartCommand onStartCommand()} or -{@link android.app.Service#onBind onBind()}). If the service is already running, this method is not -called.</dd> - <dt>{@link android.app.Service#onDestroy()}</dt> - <dd>The system calls this method when the service is no longer used and is being destroyed. -Your service should implement this to clean up any resources such as threads, registered -listeners, receivers, etc. This is the last call the service receives.</dd> -</dl> - -<p>If a component starts the service by calling {@link -android.content.Context#startService startService()} (which results in a call to {@link -android.app.Service#onStartCommand onStartCommand()}), then the service -remains running until it stops itself with {@link android.app.Service#stopSelf()} or another -component stops it by calling {@link android.content.Context#stopService stopService()}.</p> - -<p>If a component calls -{@link android.content.Context#bindService bindService()} to create the service (and {@link -android.app.Service#onStartCommand onStartCommand()} is <em>not</em> called), then the service runs -only as long as the component is bound to it. Once the service is unbound from all clients, the -system destroys it.</p> - -<p>The Android system will force-stop a service only when memory is low and it must recover system -resources for the activity that has user focus. If the service is bound to an activity that has user -focus, then it's less likely to be killed, and if the service is declared to <a -href="#Foreground">run in the foreground</a> (discussed later), then it will almost never be killed. -Otherwise, if the service was started and is long-running, then the system will lower its position -in the list of background tasks over time and the service will become highly susceptible to -killing—if your service is started, then you must design it to gracefully handle restarts -by the system. If the system kills your service, it restarts it as soon as resources become -available again (though this also depends on the value you return from {@link -android.app.Service#onStartCommand onStartCommand()}, as discussed later). For more information -about when the system might destroy a service, see the <a -href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html">Processes and Threading</a> -document.</p> - -<p>In the following sections, you'll see how you can create each type of service and how to use -it from other application components.</p> - - - -<h3 id="Declaring">Declaring a service in the manifest</h3> - -<p>Like activities (and other components), you must declare all services in your application's -manifest file.</p> - -<p>To declare your service, add a <a -href="{@docRoot}guide/topics/manifest/service-element.html">{@code <service>}</a> element -as a child of the <a -href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> -element. For example:</p> - -<pre> -<manifest ... > - ... - <application ... > - <service android:name=".ExampleService" /> - ... - </application> -</manifest> -</pre> - -<p>There are other attributes you can include in the <a -href="{@docRoot}guide/topics/manifest/service-element.html">{@code <service>}</a> element to -define properties such as permissions required to start the service and the process in -which the service should run. The <a -href="{@docRoot}guide/topics/manifest/service-element.html#nm">{@code android:name}</a> -attribute is the only required attribute—it specifies the class name of the service. Once -you publish your application, you should not change this name, because if you do, you might break -some functionality where explicit intents are used to reference your service (read the blog post, <a -href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">Things -That Cannot Change</a>). - -<p>See the <a -href="{@docRoot}guide/topics/manifest/service-element.html">{@code <service>}</a> element -reference for more information about declaring your service in the manifest.</p> - -<p>Just like an activity, a service can define intent filters that allow other components to -invoke the service using implicit intents. By declaring intent filters, components -from any application installed on the user's device can potentially start your service if your -service declares an intent filter that matches the intent another application passes to {@link -android.content.Context#startService startService()}.</p> - -<p>If you plan on using your service only locally (other applications do not use it), then you -don't need to (and should not) supply any intent filters. Without any intent filters, you must -start the service using an intent that explicitly names the service class. More information -about <a href="#StartingAService">starting a service</a> is discussed below.</p> - -<p>Additionally, you can ensure that your service is private to your application only if -you include the <a -href="{@docRoot}guide/topics/manifest/service-element.html#exported">{@code android:exported}</a> -attribute and set it to {@code "false"}. This is effective even if your service supplies intent -filters.</p> - -<p>For more information about creating intent filters for your service, see the <a -href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Filters</a> -document.</p> - - - -<h2 id="CreatingStartedService">Creating a Started Service</h2> - -<div class="sidebox-wrapper"> -<div class="sidebox"> - <h2>Targeting Android 1.6 or lower</h2> - <p>If you're building an application for Android 1.6 or lower, you need -to implement {@link android.app.Service#onStart onStart()}, instead of {@link -android.app.Service#onStartCommand onStartCommand()} (in Android 2.0, -{@link android.app.Service#onStart onStart()} was deprecated in favor of {@link -android.app.Service#onStartCommand onStartCommand()}).</p> - <p>For more information about providing compatibility with versions of Android older than 2.0, see -the {@link android.app.Service#onStartCommand onStartCommand()} documentation.</p> -</div> -</div> - -<p>A started service is one that another component starts by calling {@link -android.content.Context#startService startService()}, resulting in a call to the service's -{@link android.app.Service#onStartCommand onStartCommand()} method.</p> - -<p>When a service is started, it has a lifecycle that's independent of the -component that started it and the service can run in the background indefinitely, even if -the component that started it is destroyed. As such, the service should stop itself when its job -is done by calling {@link android.app.Service#stopSelf stopSelf()}, or another component can stop it -by calling {@link android.content.Context#stopService stopService()}.</p> - -<p>An application component such as an activity can start the service by calling {@link -android.content.Context#startService startService()} and passing an {@link android.content.Intent} -that specifies the service and includes any data for the service to use. The service receives -this {@link android.content.Intent} in the {@link android.app.Service#onStartCommand -onStartCommand()} method.</p> - -<p>For instance, suppose an activity needs to save some data to an online database. The activity can -start a companion service and deliver it the data to save by passing an intent to {@link -android.content.Context#startService startService()}. The service receives the intent in {@link -android.app.Service#onStartCommand onStartCommand()}, connects to the Internet and performs the -database transaction. When the transaction is done, the service stops itself and it is -destroyed.</p> - -<p class="caution"><strong>Caution:</strong> A services runs in the same process as the application -in which it is declared and in the main thread of that application, by default. So, if your service -performs intensive or blocking operations while the user interacts with an activity from the same -application, the service will slow down activity performance. To avoid impacting application -performance, you should start a new thread inside the service.</p> - -<p>Traditionally, there are two classes you can extend to create a started service:</p> -<dl> - <dt>{@link android.app.Service}</dt> - <dd>This is the base class for all services. When you extend this class, it's important that -you create a new thread in which to do all the service's work, because the service uses your -application's main thread, by default, which could slow the performance of any activity your -application is running.</dd> - <dt>{@link android.app.IntentService}</dt> - <dd>This is a subclass of {@link android.app.Service} that uses a worker thread to handle all -start requests, one at a time. This is the best option if you don't require that your service -handle multiple requests simultaneously. All you need to do is implement {@link -android.app.IntentService#onHandleIntent onHandleIntent()}, which receives the intent for each -start request so you can do the background work.</dd> -</dl> - -<p>The following sections describe how you can implement your service using either one for these -classes.</p> - - -<h3 id="ExtendingIntentService">Extending the IntentService class</h3> - -<p>Because most started services don't need to handle multiple requests simultaneously -(which can actually be a dangerous multi-threading scenario), it's probably best if you -implement your service using the {@link android.app.IntentService} class.</p> - -<p>The {@link android.app.IntentService} does the following:</p> - -<ul> - <li>Creates a default worker thread that executes all intents delivered to {@link -android.app.Service#onStartCommand onStartCommand()} separate from your application's main -thread.</li> - <li>Creates a work queue that passes one intent at a time to your {@link -android.app.IntentService#onHandleIntent onHandleIntent()} implementation, so you never have to -worry about multi-threading.</li> - <li>Stops the service after all start requests have been handled, so you never have to call -{@link android.app.Service#stopSelf}.</li> - <li>Provides default implementation of {@link android.app.IntentService#onBind onBind()} that -returns null.</li> - <li>Provides a default implementation of {@link android.app.IntentService#onStartCommand -onStartCommand()} that sends the intent to the work queue and then to your {@link -android.app.IntentService#onHandleIntent onHandleIntent()} implementation.</li> -</ul> - -<p>All this adds up to the fact that all you need to do is implement {@link -android.app.IntentService#onHandleIntent onHandleIntent()} to do the work provided by the -client. (Though, you also need to provide a small constructor for the service.)</p> - -<p>Here's an example implementation of {@link android.app.IntentService}:</p> - -<pre> -public class HelloIntentService extends IntentService { - - /** - * A constructor is required, and must call the super {@link android.app.IntentService#IntentService} - * constructor with a name for the worker thread. - */ - public HelloIntentService() { - super("HelloIntentService"); - } - - /** - * The IntentService calls this method from the default worker thread with - * the intent that started the service. When this method returns, IntentService - * stops the service, as appropriate. - */ - @Override - protected void onHandleIntent(Intent intent) { - // Normally we would do some work here, like download a file. - // For our sample, we just sleep for 5 seconds. - long endTime = System.currentTimeMillis() + 5*1000; - while (System.currentTimeMillis() < endTime) { - synchronized (this) { - try { - wait(endTime - System.currentTimeMillis()); - } catch (Exception e) { - } - } - } - } -} -</pre> - -<p>That's all you need: a constructor and an implementation of {@link -android.app.IntentService#onHandleIntent onHandleIntent()}.</p> - -<p>If you decide to also override other callback methods, such as {@link -android.app.IntentService#onCreate onCreate()}, {@link -android.app.IntentService#onStartCommand onStartCommand()}, or {@link -android.app.IntentService#onDestroy onDestroy()}, be sure to call the super implementation, so -that the {@link android.app.IntentService} can properly handle the life of the worker thread.</p> - -<p>For example, {@link android.app.IntentService#onStartCommand onStartCommand()} must return -the default implementation (which is how the intent gets delivered to {@link -android.app.IntentService#onHandleIntent onHandleIntent()}):</p> - -<pre> -@Override -public int onStartCommand(Intent intent, int flags, int startId) { - Toast.makeText(this, "service starting", Toast.LENGTH_SHORT).show(); - return super.onStartCommand(intent,flags,startId); -} -</pre> - -<p>Besides {@link android.app.IntentService#onHandleIntent onHandleIntent()}, the only method -from which you don't need to call the super class is {@link android.app.IntentService#onBind -onBind()} (but you only need to implement that if your service allows binding).</p> - -<p>In the next section, you'll see how the same kind of service is implemented when extending -the base {@link android.app.Service} class, which is a lot more code, but which might be -appropriate if you need to handle simultaneous start requests.</p> - - -<h3 id="ExtendingService">Extending the Service class</h3> - -<p>As you saw in the previous section, using {@link android.app.IntentService} makes your -implementation of a started service very simple. If, however, you require your service to -perform multi-threading (instead of processing start requests through a work queue), then you -can extend the {@link android.app.Service} class to handle each intent.</p> - -<p>For comparison, the following example code is an implementation of the {@link -android.app.Service} class that performs the exact same work as the example above using {@link -android.app.IntentService}. That is, for each start request, it uses a worker thread to perform the -job and processes only one request at a time.</p> - -<pre> -public class HelloService extends Service { - private Looper mServiceLooper; - private ServiceHandler mServiceHandler; - - // Handler that receives messages from the thread - private final class ServiceHandler extends Handler { - public ServiceHandler(Looper looper) { - super(looper); - } - @Override - public void handleMessage(Message msg) { - // Normally we would do some work here, like download a file. - // For our sample, we just sleep for 5 seconds. - long endTime = System.currentTimeMillis() + 5*1000; - while (System.currentTimeMillis() < endTime) { - synchronized (this) { - try { - wait(endTime - System.currentTimeMillis()); - } catch (Exception e) { - } - } - } - // Stop the service using the startId, so that we don't stop - // the service in the middle of handling another job - stopSelf(msg.arg1); - } - } - - @Override - public void onCreate() { - // Start up the thread running the service. Note that we create a - // separate thread because the service normally runs in the process's - // main thread, which we don't want to block. We also make it - // background priority so CPU-intensive work will not disrupt our UI. - HandlerThread thread = new HandlerThread("ServiceStartArguments", - Process.THREAD_PRIORITY_BACKGROUND); - thread.start(); - - // Get the HandlerThread's Looper and use it for our Handler - mServiceLooper = thread.getLooper(); - mServiceHandler = new ServiceHandler(mServiceLooper); - } - - @Override - public int onStartCommand(Intent intent, int flags, int startId) { - Toast.makeText(this, "service starting", Toast.LENGTH_SHORT).show(); - - // For each start request, send a message to start a job and deliver the - // start ID so we know which request we're stopping when we finish the job - Message msg = mServiceHandler.obtainMessage(); - msg.arg1 = startId; - mServiceHandler.sendMessage(msg); - - // If we get killed, after returning from here, restart - return START_STICKY; - } - - @Override - public IBinder onBind(Intent intent) { - // We don't provide binding, so return null - return null; - } - - @Override - public void onDestroy() { - Toast.makeText(this, "service done", Toast.LENGTH_SHORT).show(); - } -} -</pre> - -<p>As you can see, it's a lot more work than using {@link android.app.IntentService}.</p> - -<p>However, because you handle each call to {@link android.app.Service#onStartCommand -onStartCommand()} yourself, you can perform multiple requests simultaneously. That's not what -this example does, but if that's what you want, then you can create a new thread for each -request and run them right away (instead of waiting for the previous request to finish).</p> - -<p>Notice that the {@link android.app.Service#onStartCommand onStartCommand()} method must return an -integer. The integer is a value that describes how the system should continue the service in the -event that the system kills it (as discussed above, the default implementation for {@link -android.app.IntentService} handles this for you, though you are able to modify it). The return value -from {@link android.app.Service#onStartCommand onStartCommand()} must be one of the following -constants:</p> - -<dl> - <dt>{@link android.app.Service#START_NOT_STICKY}</dt> - <dd>If the system kills the service after {@link android.app.Service#onStartCommand -onStartCommand()} returns, <em>do not</em> recreate the service, unless there are pending -intents to deliver. This is the safest option to avoid running your service when not necessary -and when your application can simply restart any unfinished jobs.</dd> - <dt>{@link android.app.Service#START_STICKY}</dt> - <dd>If the system kills the service after {@link android.app.Service#onStartCommand -onStartCommand()} returns, recreate the service and call {@link -android.app.Service#onStartCommand onStartCommand()}, but <em>do not</em> redeliver the last intent. -Instead, the system calls {@link android.app.Service#onStartCommand onStartCommand()} with a -null intent, unless there were pending intents to start the service, in which case, -those intents are delivered. This is suitable for media players (or similar services) that are not -executing commands, but running indefinitely and waiting for a job.</dd> - <dt>{@link android.app.Service#START_REDELIVER_INTENT}</dt> - <dd>If the system kills the service after {@link android.app.Service#onStartCommand -onStartCommand()} returns, recreate the service and call {@link -android.app.Service#onStartCommand onStartCommand()} with the last intent that was delivered to the -service. Any pending intents are delivered in turn. This is suitable for services that are -actively performing a job that should be immediately resumed, such as downloading a file.</dd> -</dl> -<p>For more details about these return values, see the linked reference documentation for each -constant.</p> - - - -<h3 id="StartingAService">Starting a Service</h3> - -<p>You can start a service from an activity or other application component by passing an -{@link android.content.Intent} (specifying the service to start) to {@link -android.content.Context#startService startService()}. The Android system calls the service's {@link -android.app.Service#onStartCommand onStartCommand()} method and passes it the {@link -android.content.Intent}. (You should never call {@link android.app.Service#onStartCommand -onStartCommand()} directly.)</p> - -<p>For example, an activity can start the example service in the previous section ({@code -HelloSevice}) using an explicit intent with {@link android.content.Context#startService -startService()}:</p> - -<pre> -Intent intent = new Intent(this, HelloService.class); -startService(intent); -</pre> - -<p>The {@link android.content.Context#startService startService()} method returns immediately and -the Android system calls the service's {@link android.app.Service#onStartCommand -onStartCommand()} method. If the service is not already running, the system first calls {@link -android.app.Service#onCreate onCreate()}, then calls {@link android.app.Service#onStartCommand -onStartCommand()}.</p> - -<p>If the service does not also provide binding, the intent delivered with {@link -android.content.Context#startService startService()} is the only mode of communication between the -application component and the service. However, if you want the service to send a result back, then -the client that starts the service can create a {@link android.app.PendingIntent} for a broadcast -(with {@link android.app.PendingIntent#getBroadcast getBroadcast()}) and deliver it to the service -in the {@link android.content.Intent} that starts the service. The service can then use the -broadcast to deliver a result.</p> - -<p>Multiple requests to start the service result in multiple corresponding calls to the service's -{@link android.app.Service#onStartCommand onStartCommand()}. However, only one request to stop -the service (with {@link android.app.Service#stopSelf stopSelf()} or {@link -android.content.Context#stopService stopService()}) is required to stop it.</p> - - -<h3 id="Stopping">Stopping a service</h3> - -<p>A started service must manage its own lifecycle. That is, the system does not stop or -destroy the service unless it must recover system memory and the service -continues to run after {@link android.app.Service#onStartCommand onStartCommand()} returns. So, -the service must stop itself by calling {@link android.app.Service#stopSelf stopSelf()} or another -component can stop it by calling {@link android.content.Context#stopService stopService()}.</p> - -<p>Once requested to stop with {@link android.app.Service#stopSelf stopSelf()} or {@link -android.content.Context#stopService stopService()}, the system destroys the service as soon as -possible.</p> - -<p>However, if your service handles multiple requests to {@link -android.app.Service#onStartCommand onStartCommand()} concurrently, then you shouldn't stop the -service when you're done processing a start request, because you might have since received a new -start request (stopping at the end of the first request would terminate the second one). To avoid -this problem, you can use {@link android.app.Service#stopSelf(int)} to ensure that your request to -stop the service is always based on the most recent start request. That is, when you call {@link -android.app.Service#stopSelf(int)}, you pass the ID of the start request (the <code>startId</code> -delivered to {@link android.app.Service#onStartCommand onStartCommand()}) to which your stop request -corresponds. Then if the service received a new start request before you were able to call {@link -android.app.Service#stopSelf(int)}, then the ID will not match and the service will not stop.</p> - -<p class="caution"><strong>Caution:</strong> It's important that your application stops its services -when it's done working, to avoid wasting system resources and consuming battery power. If necessary, -other components can stop the service by calling {@link -android.content.Context#stopService stopService()}. Even if you enable binding for the service, -you must always stop the service yourself if it ever received a call to {@link -android.app.Service#onStartCommand onStartCommand()}.</p> - -<p>For more information about the lifecycle of a service, see the section below about <a -href="#Lifecycle">Managing the Lifecycle of a Service</a>.</p> - - - -<h2 id="CreatingBoundService">Creating a Bound Service</h2> - -<p>A bound service is one that allows application components to bind to it by calling {@link -android.content.Context#bindService bindService()} in order to create a long-standing connection -(and generally does not allow components to <em>start</em> it by calling {@link -android.content.Context#startService startService()}).</p> - -<p>You should create a bound service when you want to interact with the service from activities -and other components in your application or to expose some of your application's functionality to -other applications, through interprocess communication (IPC).</p> - -<p>To create a bound service, you must implement the {@link -android.app.Service#onBind onBind()} callback method to return an {@link android.os.IBinder} that -defines the interface for communication with the service. Other application components can then call -{@link android.content.Context#bindService bindService()} to retrieve the interface and -begin calling methods on the service. The service lives only to serve the application component that -is bound to it, so when there are no components bound to the service, the system destroys it -(you do <em>not</em> need to stop a bound service in the way you must when the service is started -through {@link android.app.Service#onStartCommand onStartCommand()}).</p> - -<p>To create a bound service, the first thing you must do is define the interface that specifies -how a client can communicate with the service. This interface between the service -and a client must be an implementation of {@link android.os.IBinder} and is what your service must -return from the {@link android.app.Service#onBind -onBind()} callback method. Once the client receives the {@link android.os.IBinder}, it can begin -interacting with the service through that interface.</p> - -<p>Multiple clients can bind to the service at once. When a client is done interacting with the -service, it calls {@link android.content.Context#unbindService unbindService()} to unbind. Once -there are no clients bound to the service, the system destroys the service.</p> - -<p>There are multiple ways to implement a bound service and the implementation is more -complicated than a started service, so the bound service discussion appears in a separate -document about <a -href="{@docRoot}guide/topics/fundamentals/bound-services.html">Bound Services</a>.</p> - - - -<h2 id="Notifications">Sending Notifications to the User</h2> - -<p>Once running, a service can notify the user of events using <a -href="{@docRoot}guide/topics/ui/notifiers/toasts.html">Toast Notifications</a> or <a -href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Status Bar Notifications</a>.</p> - -<p>A toast notification is a message that appears on the surface of the current window for a -moment then disappears, while a status bar notification provides an icon in the status bar with a -message, which the user can select in order to take an action (such as start an activity).</p> - -<p>Usually, a status bar notification is the best technique when some background work has completed -(such as a file completed -downloading) and the user can now act on it. When the user selects the notification from the -expanded view, the notification can start an activity (such as to view the downloaded file).</p> - -<p>See the <a -href="{@docRoot}guide/topics/ui/notifiers/toasts.html">Toast Notifications</a> or <a -href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Status Bar Notifications</a> -developer guides for more information.</p> - - - -<h2 id="Foreground">Running a Service in the Foreground</h2> - -<p>A foreground service is a service that's considered to be something the -user is actively aware of and thus not a candidate for the system to kill when low on memory. A -foreground service must provide a notification for the status bar, which is placed under the -"Ongoing" heading, which means that the notification cannot be dismissed unless the service is -either stopped or removed from the foreground.</p> - -<p>For example, a music player that plays music from a service should be set to run in the -foreground, because the user is explicitly aware -of its operation. The notification in the status bar might indicate the current song and allow -the user to launch an activity to interact with the music player.</p> - -<p>To request that your service run in the foreground, call {@link -android.app.Service#startForeground startForeground()}. This method takes two parameters: an integer -that uniquely identifies the notification and the {@link -android.app.Notification} for the status bar. For example:</p> - -<pre> -Notification notification = new Notification(R.drawable.icon, getText(R.string.ticker_text), - System.currentTimeMillis()); -Intent notificationIntent = new Intent(this, ExampleActivity.class); -PendingIntent pendingIntent = PendingIntent.getActivity(this, 0, notificationIntent, 0); -notification.setLatestEventInfo(this, getText(R.string.notification_title), - getText(R.string.notification_message), pendingIntent); -startForeground(ONGOING_NOTIFICATION, notification); -</pre> - - -<p>To remove the service from the foreground, call {@link -android.app.Service#stopForeground stopForeground()}. This method takes a boolean, indicating -whether to remove the status bar notification as well. This method does <em>not</em> stop the -service. However, if you stop the service while it's still running in the foreground, then the -notification is also removed.</p> - -<p class="note"><strong>Note:</strong> The methods {@link -android.app.Service#startForeground startForeground()} and {@link -android.app.Service#stopForeground stopForeground()} were introduced in Android 2.0 (API Level -5). In order to run your service in the foreground on older versions of the platform, you must -use the previous {@code setForeground()} method—see the {@link -android.app.Service#startForeground startForeground()} documentation for information about how -to provide backward compatibility.</p> - -<p>For more information about notifications, see <a -href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Creating Status Bar -Notifications</a>.</p> - - - -<h2 id="Lifecycle">Managing the Lifecycle of a Service</h2> - -<p>The lifecycle of a service is much simpler than that of an activity. However, it's even more important -that you pay close attention to how your service is created and destroyed, because a service -can run in the background without the user being aware.</p> - -<p>The service lifecycle—from when it's created to when it's destroyed—can follow two -different paths:</p> - -<ul> -<li>A started service - <p>The service is created when another component calls {@link -android.content.Context#startService startService()}. The service then runs indefinitely and must -stop itself by calling {@link -android.app.Service#stopSelf() stopSelf()}. Another component can also stop the -service by calling {@link android.content.Context#stopService -stopService()}. When the service is stopped, the system destroys it..</p></li> - -<li>A bound service - <p>The service is created when another component (a client) calls {@link -android.content.Context#bindService bindService()}. The client then communicates with the service -through an {@link android.os.IBinder} interface. The client can close the connection by calling -{@link android.content.Context#unbindService unbindService()}. Multiple clients can bind to -the same service and when all of them unbind, the system destroys the service. (The service -does <em>not</em> need to stop itself.)</p></li> -</ul> - -<p>These two paths are not entirely separate. That is, you can bind to a service that was already -started with {@link android.content.Context#startService startService()}. For example, a background -music service could be started by calling {@link android.content.Context#startService -startService()} with an {@link android.content.Intent} that identifies the music to play. Later, -possibly when the user wants to exercise some control over the player or get information about the -current song, an activity can bind to the service by calling {@link -android.content.Context#bindService bindService()}. In cases like this, {@link -android.content.Context#stopService stopService()} or {@link android.app.Service#stopSelf -stopSelf()} does not actually stop the service until all clients unbind. </p> - - -<h3 id="LifecycleCallbacks">Implementing the lifecycle callbacks</h3> - -<p>Like an activity, a service has lifecycle callback methods that you can implement to monitor -changes in the service's state and perform work at the appropriate times. The following skeleton -service demonstrates each of the lifecycle methods:</p> - - -<div class="figure" style="width:432px"> -<img src="{@docRoot}images/service_lifecycle.png" alt="" /> -<p class="img-caption"><strong>Figure 2.</strong> The service lifecycle. The diagram on the left -shows the lifecycle when the service is created with {@link android.content.Context#startService -startService()} and the diagram on the right shows the lifecycle when the service is created -with {@link android.content.Context#bindService bindService()}.</p> -</div> - -<pre> -public class ExampleService extends Service { - int mStartMode; // indicates how to behave if the service is killed - IBinder mBinder; // interface for clients that bind - boolean mAllowRebind; // indicates whether onRebind should be used - - @Override - public void {@link android.app.Service#onCreate onCreate}() { - // The service is being created - } - @Override - public int {@link android.app.Service#onStartCommand onStartCommand}(Intent intent, int flags, int startId) { - // The service is starting, due to a call to {@link android.content.Context#startService startService()} - return <em>mStartMode</em>; - } - @Override - public IBinder {@link android.app.Service#onBind onBind}(Intent intent) { - // A client is binding to the service with {@link android.content.Context#bindService bindService()} - return <em>mBinder</em>; - } - @Override - public boolean {@link android.app.Service#onUnbind onUnbind}(Intent intent) { - // All clients have unbound with {@link android.content.Context#unbindService unbindService()} - return <em>mAllowRebind</em>; - } - @Override - public void {@link android.app.Service#onRebind onRebind}(Intent intent) { - // A client is binding to the service with {@link android.content.Context#bindService bindService()}, - // after onUnbind() has already been called - } - @Override - public void {@link android.app.Service#onDestroy onDestroy}() { - // The service is no longer used and is being destroyed - } -} -</pre> - -<p class="note"><strong>Note:</strong> Unlike the activity lifecycle callback methods, you are -<em>not</em> required to call the superclass implementation of these callback methods.</p> - -<p>By implementing these methods, you can monitor two nested loops of the service's lifecycle: </p> - -<ul> -<li>The <strong>entire lifetime</strong> of a service happens between the time {@link -android.app.Service#onCreate onCreate()} is called and the time {@link -android.app.Service#onDestroy} returns. Like an activity, a service does its initial setup in -{@link android.app.Service#onCreate onCreate()} and releases all remaining resources in {@link -android.app.Service#onDestroy onDestroy()}. For example, a -music playback service could create the thread where the music will be played in {@link -android.app.Service#onCreate onCreate()}, then stop the thread in {@link -android.app.Service#onDestroy onDestroy()}. - -<p>The {@link android.app.Service#onCreate onCreate()} and {@link android.app.Service#onDestroy -onDestroy()} methods are called for all services, whether -they're created by {@link android.content.Context#startService startService()} or {@link -android.content.Context#bindService bindService()}.</p></li> - -<li>The <strong>active lifetime</strong> of a service begins with a call to either {@link -android.app.Service#onStartCommand onStartCommand()} or {@link android.app.Service#onBind onBind()}. -Each method is handed the {@link -android.content.Intent} that was passed to either {@link android.content.Context#startService -startService()} or {@link android.content.Context#bindService bindService()}, respectively. -<p>If the service is started, the active lifetime ends the same time that the entire lifetime -ends (the service is still active even after {@link android.app.Service#onStartCommand -onStartCommand()} returns). If the service is bound, the active lifetime ends when {@link -android.app.Service#onUnbind onUnbind()} returns.</p> -</li> -</ul> - -<p class="note"><strong>Note:</strong> Although a started service is stopped by a call to -either {@link android.app.Service#stopSelf stopSelf()} or {@link -android.content.Context#stopService stopService()}, there is not a respective callback for the -service (there's no {@code onStop()} callback). So, unless the service is bound to a client, -the system destroys it when the service is stopped—{@link -android.app.Service#onDestroy onDestroy()} is the only callback received.</p> - -<p>Figure 2 illustrates the typical callback methods for a service. Although the figure separates -services that are created by {@link android.content.Context#startService startService()} from those -created by {@link android.content.Context#bindService bindService()}, keep -in mind that any service, no matter how it's started, can potentially allow clients to bind to it. -So, a service that was initially started with {@link android.app.Service#onStartCommand -onStartCommand()} (by a client calling {@link android.content.Context#startService startService()}) -can still receive a call to {@link android.app.Service#onBind onBind()} (when a client calls -{@link android.content.Context#bindService bindService()}).</p> - -<p>For more information about creating a service that provides binding, see the <a -href="{@docRoot}guide/topics/fundamentals/bound-services.html">Bound Services</a> document, -which includes more information about the {@link android.app.Service#onRebind onRebind()} -callback method in the section about <a -href="{@docRoot}guide/topics/fundamentals/bound-services.html#Lifecycle">Managing the Lifecycle of -a Bound Service</a>.</p> - - -<!-- -<h2>Beginner's Path</h2> - -<p>To learn how to query data from the system or other applications (such as contacts or media -stored on the device), continue with the <b><a -href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a></b> -document.</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 deleted file mode 100644 index 0880614..0000000 --- a/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd +++ /dev/null @@ -1,596 +0,0 @@ -page.title=Tasks and Back Stack -parent.title=Activities -parent.link=activities.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> -<h2>Quickview</h2> -<ul> - <li>All activities belong to a task</li> - <li>A task contains a collection of activities in the order in which the user interacts with -them</li> - <li>Tasks can move to the background and retain the state of each activity in order for users -to perform other tasks without losing their work</li> -</ul> - -<h2>In this document</h2> -<ol> -<li><a href="#ActivityState">Saving Activity State</a></li></li> -<li><a href="#ManagingTasks">Managing Tasks</a> - <ol> - <li><a href="#TaskLaunchModes">Defining launch modes</a></li> - <li><a href="#Affinities">Handling affinities</a></li> - <li><a href="#Clearing">Clearing the back stack</a></li> - <li><a href="#Starting">Starting a task</a></li> - </ol> -</li> -</ol> - -<h2>Articles</h2> -<ol> - <li><a href="{@docRoot}resources/articles/multitasking-android-way.html">Multitasking the Android Way</a></li> -</ol> - -<h2>See also</h2> -<ol> - <li><a href="{@docRoot}design/patterns/navigation.html">Android Design: -Navigation</a></li> - <li><a href="{@docRoot}videos/index.html#v=fL6gSd4ugSI">Application Lifecycle video</a></li> - <li><a -href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>} manifest -element</a></li> -</ol> -</div> -</div> - - -<p>An application usually contains multiple <a -href="{@docRoot}guide/topics/fundamentals/activities.html">activities</a>. Each activity -should be designed around a specific kind of action the user can perform and can start other -activities. For example, an email application might have one activity to show a list of new email. -When the user selects an email, a new activity opens to view that email.</p> - -<p>An activity can even start activities that exist in other applications on the device. For -example, if your application wants to send an email, you can define an intent to perform a "send" -action and include some data, such as an email address and a message. An activity from another -application that declares itself to handle this kind of intent then opens. In this case, the intent -is to send an email, so an email application's "compose" activity starts (if multiple activities -support the same intent, then the system lets the user select which one to use). When the email is -sent, your activity resumes and it seems as if the email activity was part of your application. Even -though the activities may be from different applications, Android maintains this seamless user -experience by keeping both activities in the same <em>task</em>.</p> - -<p>A task is a collection of activities that users interact with -when performing a certain job. The activities are arranged in a stack (the "back stack"), in the -order in which each activity is opened.</p> - -<!-- SAVE FOR WHEN THE FRAGMENT DOC IS ADDED -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h3>Adding fragments to a task's back stack</h3> - -<p>Your activity can also include {@link android.app.Fragment}s to the back stack. For example, -suppose you have a two-pane layout using fragments, one of which is a list view (fragment A) and the -other being a layout to display an item from the list (fragment B). When the user selects an item -from the list, fragment B is replaced by a new fragment (fragment C). In this case, it might be -desireable for the user to navigate back to reveal fragment B, using the <em>Back</em> button.</p> -<p>In order to add fragment B to the back stack so that this is possible, you must call {@link -android.app.FragmentTransaction#addToBackStack addToBackStack()} before you {@link -android.app.FragmentTransaction#commit()} the transaction that replaces fragment B with fragment -C.</p> -<p>For more information about using fragments and adding them to the back stack, see the {@link -android.app.Fragment} class documentation.</p> - -</div> -</div> ---> - -<p>The device Home screen is the starting place for most tasks. When the user touches an icon in the -application -launcher (or a shortcut on the Home screen), that application's task comes to the foreground. If no -task exists for the application (the application has not been used recently), then a new task -is created and the "main" activity for that application opens as the root activity in the stack.</p> - -<p>When the current activity starts another, the new activity is pushed on the top of the stack and -takes focus. The previous activity remains in the stack, but is stopped. When an activity -stops, the system retains the current state of its user interface. When the user presses the -<em>Back</em> -button, the current activity is popped from the top of the stack (the activity is destroyed) and the -previous activity resumes (the previous state of its UI is restored). Activities in the stack are -never rearranged, only pushed and popped from the stack—pushed onto the stack when started by -the current activity and popped off when the user leaves it using the <em>Back</em> button. As such, -the back -stack operates as a "last in, first out" object structure. Figure 1 visualizes -this behavior with a timeline showing the progress between activities along with the current back -stack at each point in time.</p> - -<img src="{@docRoot}images/fundamentals/diagram_backstack.png" alt="" /> -<p class="img-caption"><strong>Figure 1.</strong> A representation of how each new activity in a -task adds an item to the back stack. When the user presses the <em>Back</em> button, the current -activity is -destroyed and the previous activity resumes.</p> - - -<p>If the user continues to press <em>Back</em>, then each activity in the stack is popped off to -reveal the -previous one, until the user returns to the Home screen (or to whichever activity was running when -the task began). When all activities are removed from the stack, the task no longer exists.</p> - -<div class="figure" style="width:287px"> -<img src="{@docRoot}images/fundamentals/diagram_multitasking.png" alt="" /> <p -class="img-caption"><strong>Figure 2.</strong> Two tasks: Task B receives user interaction -in the foreground, while Task A is in the background, waiting to be resumed.</p> -</div> -<div class="figure" style="width:215px"> - <img src="{@docRoot}images/fundamentals/diagram_multiple_instances.png" alt="" /> <p -class="img-caption"><strong>Figure 3.</strong> A single activity is instantiated multiple times.</p> -</div> - -<p>A task is a cohesive unit that can move to the "background" when users begin a new task or go -to the Home screen, via the <em>Home</em> button. While in the background, all the activities in the -task are -stopped, but the back stack for the task remains intact—the task has simply lost focus while -another task takes place, as shown in figure 2. A task can then return to the "foreground" so users -can pick up where they left off. Suppose, for example, that the current task (Task A) has three -activities in its stack—two under the current activity. The user presses the <em>Home</em> -button, then -starts a new application from the application launcher. When the Home screen appears, Task A goes -into the background. When the new application starts, the system starts a task for that application -(Task B) with its own stack of activities. After interacting with -that application, the user returns Home again and selects the application that originally -started Task A. Now, Task A comes to the -foreground—all three activities in its stack are intact and the activity at the top of the -stack resumes. At -this point, the user can also switch back to Task B by going Home and selecting the application icon -that started that task (or by touching and holding the <em>Home</em> button to reveal recent tasks -and selecting -one). This is an example of multitasking on Android.</p> - -<p class="note"><strong>Note:</strong> Multiple tasks can be held in the background at once. -However, if the user is running many background tasks at the same time, the system might begin -destroying background activities in order to recover memory, causing the activity states to be lost. -See the following section about <a href="#ActivityState">Activity state</a>.</p> - -<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 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 -opened (each -with their own UI state). However, you can modify this behavior if you do not want an activity to be -instantiated more than once. How to do so is discussed in the later section about <a -href="#ManagingTasks">Managing Tasks</a>.</p> - - -<p>To summarize the default behavior for activities and tasks:</p> - -<ul> - <li>When Activity A starts Activity B, Activity A is stopped, but the system retains its state -(such as scroll position and text entered into forms). -If the user presses the <em>Back</em> button while in Activity B, Activity A resumes with its state -restored.</li> - <li>When the user leaves a task by pressing the <em>Home</em> button, the current activity is -stopped and -its task goes into the background. The system retains the state of every activity in the task. If -the user later resumes the task by selecting the launcher icon that began the task, the task comes -to the foreground and resumes the activity at the top of the stack.</li> - <li>If the user presses the <em>Back</em> button, the current activity is popped from the stack -and -destroyed. The previous activity in the stack is resumed. When an activity is destroyed, the system -<em>does not</em> retain the activity's state.</li> - <li>Activities can be instantiated multiple times, even from other tasks.</li> -</ul> - - -<div class="design-announce"> -<p><strong>Navigation Design</strong></p> - <p>For more about how app navigation works on Android, read Android Design's <a -href="{@docRoot}design/patterns/navigation.html">Navigation</a> guide.</p> -</div> - - -<h2 id="ActivityState">Saving Activity State</h2> - -<p>As discussed above, the system's default behavior preserves the state of an activity when it is -stopped. This way, when users navigate back to a previous activity, its user interface appears -the way they left it. However, you can—and <strong>should</strong>—proactively retain -the state of your activities using callback methods, in case the activity is destroyed and must -be recreated.</p> - -<p>When the system stops one of your activities (such as when a new activity starts or the task -moves to the background), the system might destroy that activity completely if it needs to recover -system memory. When this happens, information about the activity state is lost. If this happens, the -system still -knows that the activity has a place in the back stack, but when the activity is brought to the -top of the stack the system must recreate it (rather than resume it). In order to -avoid losing the user's work, you should proactively retain it by implementing the {@link -android.app.Activity#onSaveInstanceState onSaveInstanceState()} callback -methods in your activity.</p> - -<p>For more information about how to save your activity state, see the <a -href="{@docRoot}guide/topics/fundamentals/activities.html#SavingActivityState">Activities</a> -document.</p> - - - -<h2 id="ManagingTasks">Managing Tasks</h2> - -<p>The way Android manages tasks and the back stack, as described above—by placing all -activities started in succession in the same task and in a "last in, first out" stack—works -great for most applications and you shouldn't have to worry about how your activities are associated -with tasks or how they exist in the back stack. However, you might decide that you want to interrupt -the normal behavior. Perhaps you want an activity in your application to begin a new task when it is -started (instead of being placed within the current task); or, when you start an activity, you want -to bring forward an existing instance of it (instead of creating a new -instance on top of the back stack); or, you want your back stack to be cleared of all -activities except for the root activity when the user leaves the task.</p> - -<p>You can do these things and more, with attributes in the -<a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code -<activity>}</a> manifest element and with flags in the intent that you pass to {@link -android.app.Activity#startActivity startActivity()}.</p> - -<p>In this regard, the the principal <a -href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> -attributes you can use are:</p> - -<ul class="nolist"> - <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">{@code -taskAffinity}</a></li> - <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code -launchMode}</a></li> - <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">{@code -allowTaskReparenting}</a></li> - <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#clear">{@code -clearTaskOnLaunch}</a></li> - <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#always">{@code -alwaysRetainTaskState}</a></li> - <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#finish">{@code -finishOnTaskLaunch}</a></li> -</ul> - -<p>And the principal intent flags you can use are:</p> - -<ul class="nolist"> - <li>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</li> - <li>{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}</li> - <li>{@link android.content.Intent#FLAG_ACTIVITY_SINGLE_TOP}</li> -</ul> - -<p>In the following sections, you'll see how you can use these manifest attributes and intent -flags to define how activities are associated with tasks and how the behave in the back stack.</p> - - -<p class="caution"><strong>Caution:</strong> Most applications should not interrupt the default -behavior for activities and tasks. If you determine that it's necessary for your activity to modify -the default behaviors, use caution and be sure to test the usability of the activity during -launch and when navigating back to it from other activities and tasks with the <em>Back</em> button. -Be sure -to test for navigation behaviors that might conflict with the user's expected behavior.</p> - - -<h3 id="TaskLaunchModes">Defining launch modes</h3> - -<p>Launch modes allow you to define how a new instance of an activity is associated with the -current task. You can define different launch modes in two ways:</p> -<ul class="nolist"> - <li><a href="#ManifestForTasks">Using the manifest file</a> - <p>When you declare an activity in your manifest file, you can specify how the activity -should associate with tasks when it starts.</li> - <li><a href="#IntentFlagsForTasks">Using Intent flags</a> - <p>When you call {@link android.app.Activity#startActivity startActivity()}, -you can include a flag in the {@link android.content.Intent} that declares how (or -whether) the new activity should associate with the current task.</p></li> -</ul> - -<p>As such, if Activity A starts Activity B, Activity B can define in its manifest how it -should associate with the current task (if at all) and Activity A can also request how Activity -B should associate with current task. If both activities define how Activity B -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 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> - - -<h4 id="ManifestForTasks">Using the manifest file</h4> - -<p>When declaring an activity in your manifest file, you can specify how the activity should -associate with a task using the <a -href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> -element's <a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code -launchMode}</a> attribute.</p> - -<p>The <a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code -launchMode}</a> attribute specifies an instruction on how the activity should be launched into a -task. There are four different launch modes you can assign to the -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">launchMode</a></code> -attribute:</p> - -<dl> -<dt>{@code "standard"} (the default mode)</dt> - <dd>Default. The system creates a new instance of the activity in the task from -which it was started and routes the intent to it. The activity can be instantiated multiple times, -each instance can belong to different tasks, and one task can have multiple instances.</dd> -<dt>{@code "singleTop"}</dt> - <dd>If an instance of the activity already exists at the top of the current task, the system -routes the intent to that instance through a call to its {@link -android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a new instance of the -activity. The activity can be instantiated multiple times, each instance can -belong to different tasks, and one task can have multiple instances (but only if the the -activity at the top of the back stack is <em>not</em> an existing instance of the activity). - <p>For example, suppose a task's back stack consists of root activity A with activities B, C, -and D on top (the stack is A-B-C-D; D is on top). An intent arrives for an activity of type D. -If D has the default {@code "standard"} launch mode, a new instance of the class is launched and the -stack becomes A-B-C-D-D. However, if D's launch mode is {@code "singleTop"}, the existing instance -of D receives the intent through {@link -android.app.Activity#onNewIntent onNewIntent()}, because it's at the top of the stack—the -stack remains A-B-C-D. However, if an intent arrives for an activity of type B, then a new -instance of B is added to the stack, even if its launch mode is {@code "singleTop"}.</p> - <p class="note"><strong>Note:</strong> When a new instance of an activity is created, -the user can press the <em>Back</em> button to return to the previous activity. But when an existing -instance of -an activity handles a new intent, the user cannot press the <em>Back</em> button to return to the -state of -the activity before the new intent arrived in {@link android.app.Activity#onNewIntent -onNewIntent()}.</p> -</dd> - -<dt>{@code "singleTask"}</dt> - <dd>The system creates a new task and instantiates the activity at the root of the new task. -However, if an instance of the activity already exists in a separate task, the system routes the -intent to the existing instance through a call to its {@link -android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a new instance. Only -one instance of the activity can exist at a time. - <p class="note"><strong>Note:</strong> Although the activity starts in a new task, the -<em>Back</em> button still returns the user to the previous activity.</p></dd> -<dt>{@code "singleInstance"}.</dt> - <dd>Same as {@code "singleTask"}, except that the system doesn't launch any other activities into -the task holding the instance. The activity is always the single and only member of its task; -any activities started by this one open in a separate task.</dd> -</dl> - - -<p>As another example, the Android Browser application declares that the web browser activity should -always open in its own task—by specifying the {@code singleTask} launch mode in the <a -href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element. -This means that if your application issues an -intent to open the Android Browser, its activity is <em>not</em> placed in the same -task as your application. Instead, either a new task starts for the Browser or, if the Browser -already has a task running in the background, that task is brought forward to handle the new -intent.</p> - -<p>Regardless of whether an activity starts in a new task or in the same task as the activity that -started it, the <em>Back</em> button always takes the user to the previous activity. However, if you -start an activity that specifies the {@code singleTask} launch mode, then if an instance of -that activity exists in a background task, that whole task is brought to the foreground. At this -point, the back stack now includes all activities from the task brought forward, at the top of the -stack. Figure 4 illustrates this type of scenario.</p> - -<img src="{@docRoot}images/fundamentals/diagram_backstack_singletask_multiactivity.png" alt="" /> -<p class="img-caption"><strong>Figure 4.</strong> A representation of how an activity with -launch mode "singleTask" is added to the back stack. If the activity is already a part of a -background task with its own back stack, then the entire back stack also comes -forward, on top of the current task.</p> - -<p>For more information about using launch modes in the manifest file, see the -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> -element documentation, where the {@code launchMode} attribute and the accepted values are -discussed more.</p> - -<p class="note"><strong>Note:</strong> The behaviors that you specify for your activity with the <a -href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a> attribute -can be overridden by flags included with the intent that start your activity, as discussed in the -next section.</p> - - - -<h4 id="#IntentFlagsForTasks">Using Intent flags</h4> - -<p>When starting an activity, you can modify the default association of an activity to its task -by including flags in the intent that you deliver to {@link -android.app.Activity#startActivity startActivity()}. The flags you can use to modify the -default behavior are:</p> - -<p> - <dt>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</dt> - <dd>Start the activity in a new task. If a task is already running for the activity you are now -starting, that task is brought to the foreground with its last state restored and the activity -receives the new intent in {@link android.app.Activity#onNewIntent onNewIntent()}. - <p>This produces the same behavior as the {@code "singleTask"} <a -href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a> value, -discussed in the previous section.</p></dd> - <dt>{@link android.content.Intent#FLAG_ACTIVITY_SINGLE_TOP}</dt> - <dd>If the activity being started is the current activity (at the top of the back stack), then -the existing instance receives a call to {@link android.app.Activity#onNewIntent onNewIntent()}, -instead of creating a new instance of the activity. - <p>This produces the same behavior as the {@code "singleTop"} <a -href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a> value, -discussed in the previous section.</p></dd> - <dt>{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}</dt> - <dd>If the activity being started is already running in the current task, then instead -of launching a new instance of that activity, all of the other activities on top of it are -destroyed and this intent is delivered to the resumed instance of the activity (now on top), -through {@link android.app.Activity#onNewIntent onNewIntent()}). - <p>There is no value for the <a -href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a> -attribute that produces this behavior.</p> - <p>{@code FLAG_ACTIVITY_CLEAR_TOP} is most often used in conjunction with {@code -FLAG_ACTIVITY_NEW_TASK}. When used together, these flags are a way of locating an existing activity -in another task and putting it in a position where it can respond to the intent. </p> - <p class="note"><strong>Note:</strong> If the launch mode of the designated activity is {@code -"standard"}, it too is removed from the stack and a new instance is launched in its place to handle -the incoming intent. That's because a new instance is always created for a new intent when the -launch mode is {@code "standard"}. </p> -</dd> -</dl> - - - - - -<h3 id="Affinities">Handling affinities</h3> - -<p>The <em>affinity</em> indicates which task an activity prefers to belong to. By default, all the -activities from the same application have an affinity for each other. So, by default, all -activities in the same application prefer to be in the same task. However, you can modify -the default affinity for an activity. Activities defined in -different applications can share an affinity, or activities defined in the same application can be -assigned different task affinities.</p> - -<p>You can modify the affinity for any given activity with the <a -href="{@docRoot}guide/topics/manifest/activity-element.html#aff">{@code taskAffinity}</a> attribute -of the <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> -element.</p> - -<p>The <a -href="{@docRoot}guide/topics/manifest/activity-element.html#aff">{@code taskAffinity}</a> -attribute takes a string value, which must be unique from the default package name -declared in the <a href="{@docRoot}guide/topics/manifest/manifest-element.html">{@code -<manifest>}</a> element, because the system uses that name to identify the default task -affinity for the application.</p> - -<p>The affinity comes into play in two circumstances:</p> -<ul> - <li>When the intent that launches an activity contains the {@link -android.content.Intent#FLAG_ACTIVITY_NEW_TASK} flag. - -<p>A new activity is, by default, launched into the task of the activity -that called {@link android.app.Activity#startActivity startActivity()}. It's pushed onto the same -back stack as the caller. However, if the intent passed to {@link -android.app.Activity#startActivity startActivity()} contains the {@link -android.content.Intent#FLAG_ACTIVITY_NEW_TASK} -flag, the system looks for a different task to house the new activity. Often, it's a new task. -However, it doesn't have to be. If there's already an existing task with the same affinity as the -new activity, the activity is launched into that task. If not, it begins a new task.</p> - -<p>If this flag causes an activity to begin a new task and the user presses the <em>Home</em> button -to leave -it, there must be some way for the user to navigate back to the task. Some entities (such as the -notification manager) always start activities in an external task, never as part of their own, so -they always put {@code FLAG_ACTIVITY_NEW_TASK} in the intents they pass to {@link -android.app.Activity#startActivity startActivity()}. If you have an activity that can be invoked by -an external entity that might use this flag, take care that the user has a independent way to get -back to the task that's started, such as with a launcher icon (the root activity of the task -has a {@link android.content.Intent#CATEGORY_LAUNCHER} intent filter; see the <a -href="#Starting">Starting a task</a> section below).</p> -</li> - - <li>When an activity has its <a -href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">{@code -allowTaskReparenting}</a> attribute set to {@code "true"}. - <p>In this case, the activity can move from the task it starts to the task it has an affinity -for, when that task comes to the foreground.</p> - <p>For example, suppose that an activity that reports weather conditions in selected cities is -defined as part of a travel application. It has the same affinity as other activities in the same -application (the default application affinity) and it allows re-parenting with this attribute. -When one of your activities starts the weather reporter activity, it initially belongs to the same -task as your activity. However, when the travel application's task comes to the foreground, the -weather reporter activity is reassigned to that task and displayed within it.</p> -</li> -</ul> - -<p class="note"><strong>Tip:</strong> If an {@code .apk} file contains more than one "application" -from the user's point of view, you probably want to use the <a -href="{@docRoot}guide/topics/manifest/activity-element.html#aff">{@code taskAffinity}</a> -attribute to assign different affinities to the activities associated with each "application".</p> - - - -<h3 id="Clearing">Clearing the back stack</h3> - -<p>If the user leaves a task for a long time, the system clears the task of all activities except -the root activity. When the user returns to the task again, only the root activity is restored. -The system behaves this way, because, after an extended amount of time, users likely have abandoned -what they were doing before and are returning to the task to begin something new. </p> - -<p>There are some activity attributes that you can use to modify this behavior: </p> - -<dl> -<dt><code><a -href="{@docRoot}guide/topics/manifest/activity-element.html#always">alwaysRetainTaskState</a></code> -</dt> -<dd>If this attribute is set to {@code "true"} in the root activity of a task, -the default behavior just described does not happen. -The task retains all activities in its stack even after a long period.</dd> - -<dt><code><a -href="{@docRoot}guide/topics/manifest/activity-element.html#clear">clearTaskOnLaunch</a></code></dt> -<dd>If this attribute is set to {@code "true"} in the root activity of a task, -the stack is cleared down to the root activity whenever the user leaves the task -and returns to it. In other words, it's the opposite of <a -href="{@docRoot}guide/topics/manifest/activity-element.html#always">{@code -alwaysRetainTaskState}</a>. The user always returns to the task in its -initial state, even after a leaving the task for only a moment.</dd> - -<dt><code><a -href="{@docRoot}guide/topics/manifest/activity-element.html#finish">finishOnTaskLaunch</a></code> -</dt> -<dd>This attribute is like <a -href="{@docRoot}guide/topics/manifest/activity-element.html#clear">{@code clearTaskOnLaunch}</a>, -but it operates on a -single activity, not an entire task. It can also cause any activity to go -away, including the root activity. When it's set to {@code "true"}, the -activity remains part of the task only for the current session. If the user -leaves and then returns to the task, it is no longer present.</dd> -</dl> - - - - -<h3 id="Starting">Starting a task</h3> - -<p>You can set up an activity as the entry point for a task by giving it an intent filter with -{@code "android.intent.action.MAIN"} as the specified action and {@code -"android.intent.category.LAUNCHER"} as the specified category. For example:</p> - -<pre> -<activity ... > - <intent-filter ... > - <action android:name="android.intent.action.MAIN" /> - <category android:name="android.intent.category.LAUNCHER" /> - </intent-filter> - ... -</activity> -</pre> - -<p>An intent filter of this kind causes an icon and label for the -activity to be displayed in the application launcher, giving users a way to launch the activity and -to return to the task that it creates any time after it has been launched. -</p> - -<p>This second ability is important: Users must be able to leave a task and then come back to it -later using this activity launcher. For this reason, the two <a href="#LaunchModes">launch -modes</a> that mark activities as always initiating a task, {@code "singleTask"} and "{@code -"singleInstance"}, should be used only when the activity has an {@link -android.content.Intent#ACTION_MAIN} -and a {@link android.content.Intent#CATEGORY_LAUNCHER} -filter. Imagine, for example, what could happen if the filter is missing: An intent launches a -{@code "singleTask"} activity, initiating a new task, and the user spends some time working in -that task. The user then presses the <em>Home</em> button. The task is now sent to the background -and is -not visible. Now the user has no way to return to the task, because it is not represented in the -application launcher. -</p> - -<p>For those cases where you don't want the user to be able to return to an activity, set the - <code><a -href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element's -<a href="{@docRoot}guide/topics/manifest/activity-element.html#finish">{@code -finishOnTaskLaunch}</a> to {@code "true"} (see <a -href="#Clearing">Clearing the stack</a>).</p> - - - -<!-- -<h2>Beginner's Path</h2> - -<p>For more information about how to use intents to -activate other application components and publish the intents to which your components -respond, continue with the <b><a -href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent -Filters</a></b> document.</p> ---> diff --git a/docs/html/guide/topics/graphics/2d-graphics.jd b/docs/html/guide/topics/graphics/2d-graphics.jd index 5cf1a59..d842cb9 100644 --- a/docs/html/guide/topics/graphics/2d-graphics.jd +++ b/docs/html/guide/topics/graphics/2d-graphics.jd @@ -476,7 +476,7 @@ allowed. do. </p> -<p>The <a href="{@docRoot}guide/developing/tools/draw9patch.html">Draw 9-patch</a> tool offers +<p>The <a href="{@docRoot}tools/help/draw9patch.html">Draw 9-patch</a> tool offers an extremely handy way to create your NinePatch images, using a WYSIWYG graphics editor. It even raises warnings if the region you've defined for the stretchable area is at risk of producing drawing artifacts as a result of the pixel replication. diff --git a/docs/html/guide/topics/graphics/animation.jd b/docs/html/guide/topics/graphics/animation.jd deleted file mode 100644 index 561369d..0000000 --- a/docs/html/guide/topics/graphics/animation.jd +++ /dev/null @@ -1,64 +0,0 @@ -page.title=Animation -@jd:body - - <div id="qv-wrapper"> - <div id="qv"> - - <h2>See also</h2> - <ol> - <li><a href="{@docRoot}guide/topics/graphics/prop-animation.html">Property -Animation</a></li> - <li><a href="{@docRoot}guide/topics/graphics/view-animation.html">View Animation</a></li> - <li><a href="{@docRoot}guide/topics/graphics/drawable-animation.html">Drawable Animation</a></li> - <ol> - </div> - </div> - - <p>The Android framework provides two animation systems: property animation - (introduced in Android 3.0) and view animation. Both animation systems are viable options, - but the property animation system, in general, is the preferred method to use, because it - is more flexible and offers more features. In addition to these two systems, you can utilize Drawable -animation, which allows you to load drawable resources and display them one frame after -another.</p> - - <p>The view animation system provides the capability to only animate {@link android.view.View} -objects, so if you wanted to animate non-{@link android.view.View} objects, you have to implement -your own code to do so. The view animation system is also constrained in the fact that it only -exposes a few aspects of a {@link android.view.View} object to animate, such as the scaling and -rotation of a View but not the background color, for instance.</p> - - <p>Another disadvantage of the view animation system is that it only modified where the - View was drawn, and not the actual View itself. For instance, if you animated a button to move - across the screen, the button draws correctly, but the actual location where you can click the - button does not change, so you have to implement your own logic to handle this.</p> - - <p>With the property animation system, these constraints are completely removed, and you can animate - any property of any object (Views and non-Views) and the object itself is actually modified. - The property animation system is also more robust in the way it carries out animation. At - a high level, you assign animators to the properties that you want to animate, such as color, - position, or size and can define aspects of the animation such as interpolation and - synchronization of multiple animators.</p> - - <p>The view animation system, however, takes less time to setup and requires less code to write. - If view animation accomplishes everything that you need to do, or if your existing code already - works the way you want, there is no need to use the property animation system. It also might - make sense to use both animation systems for different situations if the use case arises.</p> - -<dl> -<dt><strong><a href="{@docRoot}guide/topics/graphics/prop-animation.html">Property -Animation</a></strong></dt> -<dd>Introduced in Android 3.0 (API level 11), the property animation system lets you -animate properties of any object, including ones that are not rendered to the screen. The system is -extensible and lets you animate properties of custom types as well.</dd> - -<dt><strong><a href="{@docRoot}guide/topics/graphics/view-animation.html">View -Animation</a></strong></dt> -<dd>View Animation is the older system and can only be used for Views. It is relatively easy to -setup and offers enough capabilities to meet many application's needs.</dd> -</dl> - -<dt><strong><a href="{@docRoot}guide/topics/graphics/drawable-animation.html">Drawable -Animation</a></strong></dt> -<dd>Drawable animation involves displaying {@link android.graphics.drawable.Drawable} resources one -after another, like a roll of film. This method of animation is useful if you want to animate -things that are easier to represent with Drawable resources, such as a progression of bitmaps.</dd> diff --git a/docs/html/guide/topics/graphics/index.jd b/docs/html/guide/topics/graphics/index.jd index ab623c2..17f6309 100644 --- a/docs/html/guide/topics/graphics/index.jd +++ b/docs/html/guide/topics/graphics/index.jd @@ -1,51 +1,49 @@ -page.title=Graphics -@jd:body - -<div id="qv-wrapper"> - <div id="qv"> - <h2>Topics</h2> - <ol> - <li><a href="{@docRoot}guide/topics/graphics/2d-graphics.html">Canvas and Drawables</a></li> - <li><a href="{@docRoot}guide/topics/graphics/hardware-accel.html">Hardware Acceleration</a></li> - <li><a href="{@docRoot}guide/topics/graphics/opengl.html">OpenGL</a></li> - </ol> - </div> -</div> - -<p>When writing an application, it's important to consider exactly what your graphical demands will be. -Varying graphical tasks are best accomplished with varying techniques. For example, graphics and animations -for a rather static application should be implemented much differently than graphics and animations -for an interactive game. Here, we'll discuss a few of the options you have for drawing graphics -on Android and which tasks they're best suited for. -</p> +page.title=Animation and Graphics +page.landing=true +page.landing.intro=Make your apps look and perform their best using Android's powerful graphics features such as OpenGL, hardware acceleration, and built-in UI animations. +page.landing.image= -<dl> -<dt><strong><a href="{@docRoot}guide/topics/graphics/2d-graphics.html">Canvas and -Drawables</a></strong></dt> -<dd>Android provides a set of {@link android.view.View} widgets that provide general functionality -for a wide array of user interfaces. You can also extend these widgets to modify the way they -look or behave. In addition, you can do your own custom 2D rendering using the various drawing -methods contained in the {@link android.graphics.Canvas} class or create {@link -android.graphics.drawable.Drawable} objects for things such as textured buttons or frame-by-frame -animations.</dd> +@jd:body -<dt><strong><a href="{@docRoot}guide/topics/graphics/hardware-accel.html">Hardware -Acceleration</a></strong></dt> -<dd>Beginning in Android 3.0, you can hardware accelerate the majority of -the drawing done by the Canvas APIs to further increase their performance.</dd> +<div class="landing-docs"> -<dt><strong><a href="{@docRoot}guide/topics/graphics/opengl.html">OpenGL</a></strong></dt> -<dd>Android supports OpenGL ES 1.0 and 2.0, with Android framework APIs as well as natively -with the Native Development Kit (NDK). Using the framework APIs is desireable when you want to add a -few graphical enhancements to your application that are not supported with the Canvas APIs, or if -you desire platform independence and don't demand high performance. There is a performance hit in -using the framework APIs compared to the NDK, so for many graphic intensive applications such as -games, using the NDK is beneficial (It is important to note though that you can still get adequate -performance using the framework APIs. For example, the Google Body app is developed entirely -using the framework APIs). OpenGL with the NDK is also useful if you have a lot of native -code that you want to port over to Android. For more information about using the NDK, read the -docs in the <code>docs/</code> directory of the <a href="{@docRoot}sdk/ndk/index.html">NDK -download.</a></dd> -</dl> + <div class="col-6"> + <h3>Blog Articles</h3> + <a +href="http://android-developers.blogspot.com/2011/11/android-40-graphics-and-animations.html"> + <h4>Android 4.0 Graphics and Animations</h4> + <p>Earlier this year, Android 3.0 launched with a new 2D rendering pipeline designed to +support hardware acceleration on tablets. With this new pipeline, all drawing operations performed +by the UI toolkit are carried out using the GPU. You’ll be happy to hear that Android 4.0, Ice Cream +Sandwich, brings an improved version of the hardware-accelerated 2D rendering pipeline.</p> + </a> + + <a +href="http://android-developers.blogspot.com/2011/05/introducing-viewpropertyanimator.html"> + <h4>Introducing ViewPropertyAnimator</h4> + <p>This new animation system makes it easy to animate any kind of property on any object, +including the new properties added to the View class in 3.0. In the 3.1 release, we added a small +utility class that makes animating these properties even easier.</p> + </a> + + <a +href="http://android-developers.blogspot.com/2011/03/android-30-hardware-acceleration.html"> + <h4>Android 3.0 Hardware Acceleration</h4> + <p>Hardware accelerated graphics is nothing new to the Android platform, it has always been +used for windows composition or OpenGL games for instance, but with this new rendering pipeline +applications can benefit from an extra boost in performance.</p> + </a> + </div> + <div class="col-6"> + <h3>Training</h3> + <a href="{@docRoot}training/displaying-bitmaps/index.html"> + <h4>Displaying Bitmaps Efficiently</h4> + <p>This class covers some common techniques for processing and loading Bitmap objects in a way +that keeps your user interface (UI) components responsive and avoids exceeding your application +memory limit.</p> + </a> + + </div> +</div>
\ No newline at end of file diff --git a/docs/html/guide/topics/graphics/opengl.jd b/docs/html/guide/topics/graphics/opengl.jd index a786d42..a9fedb7 100644 --- a/docs/html/guide/topics/graphics/opengl.jd +++ b/docs/html/guide/topics/graphics/opengl.jd @@ -20,6 +20,7 @@ parent.link=index.html <li><a href="#proj-es1">Projection and camera in ES 2.0</a></li> </ol> </li> + <li><a href="#faces-winding">Shape Faces and Winding</li> <li><a href="#compatibility">OpenGL Versions and Device Compatibility</a> <ol> <li><a href="#textures">Texture compression support</a></li> @@ -33,11 +34,6 @@ parent.link=index.html <li>{@link android.opengl.GLSurfaceView}</li> <li>{@link android.opengl.GLSurfaceView.Renderer}</li> </ol> - <h2>Related tutorials</h2> - <ol> - <li><a href="{@docRoot}resources/tutorials/opengl/opengl-es10.html">OpenGL ES 1.0</a></li> - <li><a href="{@docRoot}resources/tutorials/opengl/opengl-es20.html">OpenGL ES 2.0</a></li> - </ol> <h2>Related samples</h2> <ol> <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/GLSurfaceViewActivity.html">GLSurfaceViewActivity</a></li> @@ -48,8 +44,8 @@ href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics </ol> <h2>See also</h2> <ol> - <li><a href="{@docRoot}resources/articles/glsurfaceview.html">Introducing -GLSurfaceView</a></li> + <li><a href="{@docRoot}training/graphics/opengl/index.html"> + Displaying Graphics with OpenGL ES</a></li> <li><a href="http://www.khronos.org/opengles/">OpenGL ES</a></li> <li><a href="http://www.khronos.org/opengles/1_X/">OpenGL ES 1.x Specification</a></li> <li><a href="http://www.khronos.org/opengles/2_X/">OpenGL ES 2.x specification</a></li> @@ -73,7 +69,7 @@ OpenGL ES 2.0 API specification.</p> <p>Android supports OpenGL both through its framework API and the Native Development Kit (NDK). This topic focuses on the Android framework interfaces. For more information about the -NDK, see the <a href="{@docRoot}sdk/ndk/index.html">Android NDK</a>. +NDK, see the <a href="{@docRoot}tools/sdk/ndk/index.html">Android NDK</a>. <p>There are two foundational classes in the Android framework that let you create and manipulate graphics with the OpenGL ES API: {@link android.opengl.GLSurfaceView} and {@link @@ -389,6 +385,43 @@ objects to be rendered by OpenGL. href="{@docRoot}resources/tutorials/opengl/opengl-es20.html#projection-and-views">OpenGL ES 2.0 tutorial</a>.</p> +<h2 id="faces-winding">Shape Faces and Winding</h2> + +<p>In OpenGL, the face of a shape is a surface defined by three or more points in three-dimensional +space. A set of three or more three-dimensional points (called vertices in OpenGL) have a front face +and a back face. How do you know which face is front and which is the back? Good question. The +answer has to do with winding, or, the direction in which you define the points of a shape.</p> + +<img src="{@docRoot}images/opengl/ccw-winding.png"> +<p class="img-caption"> + <strong>Figure 1.</strong> Illustration of a coordinate list which translates into a +counterclockwise drawing order.</p> + +<p>In this example, the points of the triangle are defined in an order such that they are drawn in a +counterclockwise direction. The order in which these coordinates are drawn defines the winding +direction for the shape. By default, in OpenGL, the face which is drawn counterclockwise is the +front face. The triangle shown in Figure 1 is defined so that you are looking at the front face of +the shape (as interpreted by OpenGL) and the other side is the back face.</p> + +<p>Why is it important to know which face of a shape is the front face? The answer has to do with a +commonly used feature of OpenGL, called face culling. Face culling is an option for the OpenGL +environment which allows the rendering pipeline to ignore (not calculate or draw) the back face of a +shape, saving time, memory and processing cycles:</p> + +<pre> +// enable face culling feature +gl.glEnable(GL10.GL_CULL_FACE); +// specify which faces to not draw +gl.glCullFace(GL10.GL_BACK); +</pre> + +<p>If you try to use the face culling feature without knowing which sides of your shapes are the +front and back, your OpenGL graphics are going to look a bit thin, or possibly not show up at all. +So, always define the coordinates of your OpenGL shapes in a counterclockwise drawing order.</p> + +<p class="note"><strong>Note:</strong> It is possible to set an OpenGL environment to treat the +clockwise face as the front face, but doing so requires more code and is likely to confuse +experienced OpenGL developers when you ask them for help. So don’t do that.</p> <h2 id="compatibility">OpenGL Versions and Device Compatibility</h2> @@ -410,7 +443,8 @@ texture compression, see the <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/CompressedTextureActivity.html" >CompressedTextureActivity</a> code sample.</p> -<p>To check if the ETC1 format is supported on a device, call the {@link +<p>The ETC format is supported by most Android devices, but it not guarranteed to be available. To +check if the ETC1 format is supported on a device, call the {@link android.opengl.ETC1Util#isETC1Supported() ETC1Util.isETC1Supported()} method.</p> <p class="note"><b>Note:</b> The ETC1 texture compression format does not support textures with an diff --git a/docs/html/guide/topics/graphics/overview.jd b/docs/html/guide/topics/graphics/overview.jd new file mode 100644 index 0000000..a53cd3f --- /dev/null +++ b/docs/html/guide/topics/graphics/overview.jd @@ -0,0 +1,73 @@ +page.title=Animation and Graphics Overview +@jd:body + + <p>Android provides a variety of powerful APIs for applying animation to UI elements and drawing custom + 2D and 3D graphics. The sections below provide an overview of the APIs and system capabilities available + and help you decide with approach is best for your needs.</p> + + <h3 id="animation">Animation</h3> + + <p>The Android framework provides two animation systems: property animation + (introduced in Android 3.0) and view animation. Both animation systems are viable options, + but the property animation system, in general, is the preferred method to use, because it + is more flexible and offers more features. In addition to these two systems, you can utilize Drawable + animation, which allows you to load drawable resources and display them one frame after + another.</p> + +<dl> +<dt><strong><a href="{@docRoot}guide/topics/graphics/prop-animation.html">Property +Animation</a></strong></dt> +<dd>Introduced in Android 3.0 (API level 11), the property animation system lets you +animate properties of any object, including ones that are not rendered to the screen. The system is +extensible and lets you animate properties of custom types as well.</dd> + +<dt><strong><a href="{@docRoot}guide/topics/graphics/view-animation.html">View +Animation</a></strong></dt> +<dd>View Animation is the older system and can only be used for Views. It is relatively easy to +setup and offers enough capabilities to meet many application's needs.</dd> +</dl> + +<dt><strong><a href="{@docRoot}guide/topics/graphics/drawable-animation.html">Drawable +Animation</a></strong></dt> +<dd>Drawable animation involves displaying {@link android.graphics.drawable.Drawable} resources one +after another, like a roll of film. This method of animation is useful if you want to animate +things that are easier to represent with Drawable resources, such as a progression of bitmaps.</dd> + +<h3 id="graphics">2D and 3D Graphics</h3> + +<p>When writing an application, it's important to consider exactly what your graphical demands will be. +Varying graphical tasks are best accomplished with varying techniques. For example, graphics and animations +for a rather static application should be implemented much differently than graphics and animations +for an interactive game. Here, we'll discuss a few of the options you have for drawing graphics +on Android and which tasks they're best suited for. +</p> + +<dl> +<dt><strong><a href="{@docRoot}guide/topics/graphics/2d-graphics.html">Canvas and +Drawables</a></strong></dt> +<dd>Android provides a set of {@link android.view.View} widgets that provide general functionality +for a wide array of user interfaces. You can also extend these widgets to modify the way they +look or behave. In addition, you can do your own custom 2D rendering using the various drawing +methods contained in the {@link android.graphics.Canvas} class or create {@link +android.graphics.drawable.Drawable} objects for things such as textured buttons or frame-by-frame +animations.</dd> + +<dt><strong><a href="{@docRoot}guide/topics/graphics/hardware-accel.html">Hardware +Acceleration</a></strong></dt> +<dd>Beginning in Android 3.0, you can hardware accelerate the majority of +the drawing done by the Canvas APIs to further increase their performance.</dd> + +<dt><strong><a href="{@docRoot}guide/topics/graphics/opengl.html">OpenGL</a></strong></dt> +<dd>Android supports OpenGL ES 1.0 and 2.0, with Android framework APIs as well as natively +with the Native Development Kit (NDK). Using the framework APIs is desireable when you want to add a +few graphical enhancements to your application that are not supported with the Canvas APIs, or if +you desire platform independence and don't demand high performance. There is a performance hit in +using the framework APIs compared to the NDK, so for many graphic intensive applications such as +games, using the NDK is beneficial (It is important to note though that you can still get adequate +performance using the framework APIs. For example, the Google Body app is developed entirely +using the framework APIs). OpenGL with the NDK is also useful if you have a lot of native +code that you want to port over to Android. For more information about using the NDK, read the +docs in the <code>docs/</code> directory of the <a href="{@docRoot}tools/sdk/ndk/index.html">NDK +download.</a></dd> +</dl> + diff --git a/docs/html/guide/topics/graphics/prop-animation.jd b/docs/html/guide/topics/graphics/prop-animation.jd index be24788..b733624 100644 --- a/docs/html/guide/topics/graphics/prop-animation.jd +++ b/docs/html/guide/topics/graphics/prop-animation.jd @@ -166,6 +166,31 @@ parent.link=animation.html "{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html">API Demos</a> sample project provides many examples on how to use the property animation system.</p> + + <h2 id="property-vs-view">How Property Animation Differs from View Animation</h2> + + <p>The view animation system provides the capability to only animate {@link android.view.View} + objects, so if you wanted to animate non-{@link android.view.View} objects, you have to implement + your own code to do so. The view animation system is also constrained in the fact that it only + exposes a few aspects of a {@link android.view.View} object to animate, such as the scaling and + rotation of a View but not the background color, for instance.</p> + + <p>Another disadvantage of the view animation system is that it only modified where the + View was drawn, and not the actual View itself. For instance, if you animated a button to move + across the screen, the button draws correctly, but the actual location where you can click the + button does not change, so you have to implement your own logic to handle this.</p> + + <p>With the property animation system, these constraints are completely removed, and you can animate + any property of any object (Views and non-Views) and the object itself is actually modified. + The property animation system is also more robust in the way it carries out animation. At + a high level, you assign animators to the properties that you want to animate, such as color, + position, or size and can define aspects of the animation such as interpolation and + synchronization of multiple animators.</p> + + <p>The view animation system, however, takes less time to setup and requires less code to write. + If view animation accomplishes everything that you need to do, or if your existing code already + works the way you want, there is no need to use the property animation system. It also might + make sense to use both animation systems for different situations if the use case arises.</p> <h2>API Overview</h2> diff --git a/docs/html/guide/topics/renderscript/compute.jd b/docs/html/guide/topics/graphics/renderscript/compute.jd index e827f00..e827f00 100644 --- a/docs/html/guide/topics/renderscript/compute.jd +++ b/docs/html/guide/topics/graphics/renderscript/compute.jd diff --git a/docs/html/guide/topics/renderscript/graphics.jd b/docs/html/guide/topics/graphics/renderscript/graphics.jd index 462a990..58676ea 100644 --- a/docs/html/guide/topics/renderscript/graphics.jd +++ b/docs/html/guide/topics/graphics/renderscript/graphics.jd @@ -46,7 +46,8 @@ parent.link=index.html <li><a href="{@docRoot}resources/samples/RenderScript/FountainFbo/index.html">FountainFbo</a></li> - <li><a href="{@docRoot}resources/samples/RenderScript/HelloWorld/index.html">Hello World</a></li> + <li><a href="{@docRoot}resources/samples/RenderScript/HelloWorld/index.html">Hello +World</a></li> <li><a href="{@docRoot}resources/samples/RenderScript/MiscSamples/index.html">Misc Samples</a></li> diff --git a/docs/html/guide/topics/renderscript/index.jd b/docs/html/guide/topics/graphics/renderscript/index.jd index b2d9f84..b2d9f84 100644 --- a/docs/html/guide/topics/renderscript/index.jd +++ b/docs/html/guide/topics/graphics/renderscript/index.jd diff --git a/docs/html/guide/topics/renderscript/reference.jd b/docs/html/guide/topics/graphics/renderscript/reference.jd index a0a9df2..a0a9df2 100644 --- a/docs/html/guide/topics/renderscript/reference.jd +++ b/docs/html/guide/topics/graphics/renderscript/reference.jd diff --git a/docs/html/guide/topics/intents/index.html b/docs/html/guide/topics/intents/index.html deleted file mode 100644 index b831246..0000000 --- a/docs/html/guide/topics/intents/index.html +++ /dev/null @@ -1,9 +0,0 @@ -<html> -<head> -<meta http-equiv="refresh" content="0;url=intents-filters.html"> -<title>Redirecting...</title> -</head> -<body> -<a href="intents-filters.html">click here</a> if you are not redirected. -</body> -</html>
\ No newline at end of file diff --git a/docs/html/guide/topics/intents/intents-filters.jd b/docs/html/guide/topics/intents/intents-filters.jd deleted file mode 100644 index 3ad3c93..0000000 --- a/docs/html/guide/topics/intents/intents-filters.jd +++ /dev/null @@ -1,1055 +0,0 @@ -page.title=Intents and Intent Filters -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - -<h2>In this document</h2> -<ol> -<li><a href="#iobjs">Intent Objects</a></li> -<li><a href="#ires">Intent Resolution</a></li> -<li style="margin-left: 2em"><a href="#ifs">Intent filters</a></li> -<li style="margin-left: 2em"><a href="#ccases">Common cases</a></li> -<li style="margin-left: 2em"><a href="#imatch">Using intent matching</a></li> -<li><a href="#npex">Note Pad Example</a></li> -</ol> - -<h2>Key classes</h2> -<ol> -<li>{@link android.content.Intent}</li> -<li>{@link android.content.IntentFilter}</li> -<li>{@link android.content.BroadcastReceiver}</li> -<li>{@link android.content.pm.PackageManager}</li> -</ol> - -</div> -</div> - - -<p> -Three of the core components of an application — activities, services, and -broadcast receivers — are activated through messages, called <i>intents</i>. -Intent messaging is a facility for late run-time binding between components in the same -or different applications. The intent itself, an {@link android.content.Intent} -object, is a passive data structure holding an abstract description of an operation -to be performed — or, often in the case of broadcasts, a description of something -that has happened and is being announced. There are separate mechanisms for -delivering intents to each type of component: -</p> - -<ul> -<li>An Intent object is passed to <code>{@link android.content.Context#startActivity -Context.startActivity()}</code> or <code>{@link android.app.Activity#startActivityForResult -Activity.startActivityForResult()}</code> to launch an activity or get an existing -activity to do something new. (It can also be passed to -<code>{@link android.app.Activity#setResult(int, Intent) Activity.setResult()}</code> -to return information to the activity that called {@code startActivityForResult()}.)</li> - -<li><p>An Intent object is passed to <code>{@link android.content.Context#startService -Context.startService()}</code> to initiate a service or deliver new instructions to an -ongoing service. Similarly, an intent can be passed to <code>{@link -android.content.Context#bindService Context.bindService()}</code> to establish a -connection between the calling component and a target service. It can optionally -initiate the service if it's not already running.</p></li> - -<li><p>Intent objects passed to any of the broadcast methods (such as <code>{@link -android.content.Context#sendBroadcast(Intent) Context.sendBroadcast()}</code>, -<code>{@link android.content.Context#sendOrderedBroadcast(Intent, String) -Context.sendOrderedBroadcast()}</code>, or <code>{@link -android.content.Context#sendStickyBroadcast Context.sendStickyBroadcast()}</code>) -are delivered to all interested broadcast receivers. Many kinds of broadcasts -originate in system code.</p></li> -</ul> - -<p> -In each case, the Android system finds the appropriate activity, service, or set -of broadcast receivers to respond to the intent, instantiating them if necessary. -There is no overlap within these messaging systems: Broadcast intents are delivered -only to broadcast receivers, never to activities or services. An intent passed to -{@code startActivity()} is delivered only to an activity, never to a service or -broadcast receiver, and so on. -</p> - -<p> -This document begins with a description of Intent objects. It then describes the -rules Android uses to map intents to components — how it resolves which -component should receive an intent message. For intents that don't explicitly -name a target component, this process involves testing the Intent object against -<i>intent filters</i> associated with potential targets. -</p> - - -<h2><a name="iobjs"></a>Intent Objects</h2> - -<p> -An {@link android.content.Intent} object is a bundle of information. It -contains information of interest to the component that receives the intent -(such as the action to be taken and the data to act on) plus information -of interest to the Android system (such as the category of component that -should handle the intent and instructions on how to launch a target activity). -Principally, it can contain the following: -</p> - -<dl> - -<dt><b>Component name</b><a name="cname"></a></dt> -<dd>The name of the component that should handle the intent. This field is -a {@link android.content.ComponentName} object — a combination of the -fully qualified class name of the target component (for example "{@code -com.example.project.app.FreneticActivity}") and the package name set -in the manifest file of the application where the component resides (for -example, "{@code com.example.project}"). The package part of the component -name and the package name set in the manifest do not necessarily have to match. - -<p> -The component name is optional. If it is set, the Intent object is -delivered to an instance of the designated class. If it is not set, -Android uses other information in the Intent object to locate a suitable -target — see <a href="#ires">Intent Resolution</a>, later in this -document. -</p> - -<p> -The component name is set by <code>{@link android.content.Intent#setComponent -setComponent()}</code>, <code>{@link android.content.Intent#setClass -setClass()}</code>, or <code>{@link android.content.Intent#setClassName(String, String) -setClassName()}</code> and read by <code>{@link android.content.Intent#getComponent -getComponent()}</code>. -</p> -</dd> - -<p><dt><b>Action</b></dt> -<dd>A string naming the action to be performed — or, in the case of broadcast -intents, the action that took place and is being reported. The Intent class defines -a number of action constants, including these: -</p> - -<table> -<tr> - <th>Constant</th> - <th>Target component</th> - <th>Action</th> -</tr><tr> - <td>{@code ACTION_CALL} - <td>activity - <td>Initiate a phone call. -</tr><tr> - <td>{@code ACTION_EDIT} - <td>activity - <td>Display data for the user to edit. -</tr><tr> - <td>{@code ACTION_MAIN} - <td>activity - <td>Start up as the initial activity of a task, with no data input and no returned output. -</tr><tr> - <td>{@code ACTION_SYNC} - <td>activity - <td>Synchronize data on a server with data on the mobile device. -</tr><tr> - <td>{@code ACTION_BATTERY_LOW} - <td>broadcast receiver - <td>A warning that the battery is low. -</tr><tr> - <td>{@code ACTION_HEADSET_PLUG} - <td>broadcast receiver - <td>A headset has been plugged into the device, or unplugged from it. -</tr><tr> - <td>{@code ACTION_SCREEN_ON} - <td>broadcast receiver - <td>The screen has been turned on. -</tr><tr> - <td>{@code ACTION_TIMEZONE_CHANGED} - <td>broadcast receiver - <td>The setting for the time zone has changed. -</tr> -</table> - -<p> -See the {@link android.content.Intent} class description for a list of -pre-defined constants for generic actions. Other actions are defined -elsewhere in the Android API. -You can also define your own action strings for activating the components -in your application. Those you invent should include the application -package as a prefix — for example: -"<code>com.example.project.SHOW_COLOR</code>". -</p> - -<p> -The action largely determines how the rest of the intent is structured -— particularly the <a href="#data">data</a> and -<a href="#extras">extras</a> fields — -much as a method name determines a set of arguments and a return value. -For this reason, it's a good idea to use action names that are -as specific as possible, and to couple them tightly to the other fields of -the intent. In other words, instead of defining an action in isolation, -define an entire protocol for the Intent objects your components can handle. -</p> - -<p> -The action in an Intent object is set by the -<code>{@link android.content.Intent#setAction setAction()}</code> -method and read by -<code>{@link android.content.Intent#getAction getAction()}</code>. -</p> -</dd> - -<p><dt><b>Data</b><a name="data"></a></dt> -<dd>The URI of the data to be acted on and the MIME type of that data. Different -actions are paired with different kinds of data specifications. For example, if -the action field is {@code ACTION_EDIT}, -the data field would contain the URI of the document to be displayed for editing. -If the action is {@code ACTION_CALL}, the data field would be a {@code tel:} URI -with the number to call. Similarly, if the action is {@code ACTION_VIEW} and the -data field is an {@code http:} URI, the receiving activity would be called upon -to download and display whatever data the URI refers to. - -<p> -When matching an intent to a component that is capable of handling the data, -it's often important to know the type of data (its MIME type) in addition to its URI. -For example, a component able to display image data should not be called -upon to play an audio file. -</p> - -<p> -In many cases, the data type can be inferred from the URI — particularly -{@code content:} URIs, which indicate that the data is located on the device and -controlled by a content provider (see the -<a href="{@docRoot}guide/topics/providers/content-providers.html">separate -discussion on content providers</a>). But the type can also be explicitly set -in the Intent object. -The <code>{@link android.content.Intent#setData setData()}</code> method specifies -data only as a URI, <code>{@link android.content.Intent#setType setType()}</code> -specifies it only as a MIME type, and <code>{@link -android.content.Intent#setDataAndType setDataAndType()}</code> specifies it as both -a URI and a MIME type. The URI is read by <code>{@link -android.content.Intent#getData getData()}</code> and the type by <code>{@link -android.content.Intent#getType getType()}</code>. -</p> -</dd> - -<p><dt><b>Category</b></dt> -<dd>A string containing additional information about the kind of component -that should handle the intent. Any number of category descriptions can be -placed in an Intent object. As it does for actions, the Intent class defines -several category constants, including these: - -<table> -<tr> - <th>Constant</th> - <th>Meaning</th> -</tr><tr> - <td>{@code CATEGORY_BROWSABLE} - <td>The target activity can be safely invoked by the browser to display data - referenced by a link — for example, an image or an e-mail message. -</tr><tr> - <td>{@code CATEGORY_GADGET} - <td>The activity can be embedded inside of another activity that hosts gadgets. -</tr><tr> - <td>{@code CATEGORY_HOME} - <td>The activity displays the home screen, the first screen the user sees when - the device is turned on or when the <em>Home</em> button is pressed. -</tr><tr> - <td>{@code CATEGORY_LAUNCHER} - <td>The activity can be the initial activity of a task and is listed in - the top-level application launcher. -</tr><tr> - <td>{@code CATEGORY_PREFERENCE} - <td>The target activity is a preference panel. -</tr> -</table> - -<p> -See the {@link android.content.Intent} class description for the full list of -categories. -</p> - -<p> -The <code>{@link android.content.Intent#addCategory addCategory()}</code> method -places a category in an Intent object, <code>{@link android.content.Intent#removeCategory -removeCategory()}</code> deletes a category previously added, and <code>{@link android.content.Intent#getCategories getCategories()}</code> gets the set of all -categories currently in the object. -</p> -</dd> - -<p><dt><b>Extras</b><a name="extras"></a></dt> -<dd>Key-value pairs for additional information that should be delivered to the -component handling the intent. Just as some actions are paired with particular -kinds of data URIs, some are paired with particular extras. For example, an -{@code ACTION_TIMEZONE_CHANGED} intent has a "{@code time-zone}" extra that -identifies the new time zone, and {@code ACTION_HEADSET_PLUG} has a -"{@code state}" extra indicating whether the headset is now plugged in or -unplugged, as well as a "{@code name}" extra for the type of headset. -If you were to invent a {@code SHOW_COLOR} action, the color value would -be set in an extra key-value pair. - -<p> -The Intent object has a series of {@code put...()} methods for inserting various -types of extra data and a similar set of {@code get...()} methods for reading -the data. These methods parallel those for {@link android.os.Bundle} objects. -In fact, the extras can be installed and read as a Bundle using the <code>{@link -android.content.Intent#putExtras putExtras()}</code> and <code>{@link -android.content.Intent#getExtras getExtras()}</code> methods. -</p> -</dd> - -<p><dt><b>Flags</b></dt> -<dd>Flags of various sorts. Many instruct the Android system how to launch an -activity (for example, which task the activity should belong to) and how to treat -it after it's launched (for example, whether it belongs in the list of recent -activities). All these flags are defined in the Intent class. -</dd> - -</dl> - -<p> -The Android system and the applications that come with the platform employ -Intent objects both to send out system-originated broadcasts and to activate -system-defined components. To see how to structure an intent to activate a -system component, consult the -<a href="{@docRoot}guide/appendix/g-app-intents.html">list of intents</a> -in the reference. -</p> - - -<h2><a name="ires"></a>Intent Resolution</h2> - -<p> -Intents can be divided into two groups: -</p> - -<ul> -<li><i>Explicit intents</i> designate the target component by its -name (the <a href="#cname">component name field</a>, mentioned earlier, -has a value set). Since component names would generally not be known to -developers of other applications, explicit intents are typically used -for application-internal messages — such as an activity starting -a subordinate service or launching a sister activity.</li> - -<li><p><i>Implicit intents</i> do not name a target (the field for -the component name is blank). Implicit intents are often used to -activate components in other applications.</p></li> -</ul> - -<p> -Android delivers an explicit intent to an instance of the designated -target class. Nothing in the Intent object other than the component -name matters for determining which component should get the intent. -</p> - -<p> -A different strategy is needed for implicit intents. In the absence of a -designated target, the Android system must find the best component (or -components) to handle the intent — a single activity or service to -perform the requested action or the set of broadcast receivers to respond -to the broadcast announcement. It does so by comparing the contents of -the Intent object to <i>intent filters</i>, structures associated with -components that can potentially receive intents. Filters advertise the -capabilities of a component and delimit the intents it can handle. They -open the component to the possibility of receiving implicit intents of -the advertised type. If a component does not have any intent filters, -it can receive only explicit intents. A component with filters can -receive both explicit and implicit intents. -</p> - -<p> -Only three aspects of an Intent object are consulted when the object -is tested against an intent filter: -</p> - -<p style="margin-left: 2em">action -<br/>data (both URI and data type) -<br/>category</p> - -<p> -The extras and flags play no part in resolving which component receives -an intent. -</p> - - -<h3><a name="ifs"></a>Intent filters</h3> - -<p> -To inform the system which implicit intents they can handle, activities, -services, and broadcast receivers can have one or more intent filters. -Each filter describes a capability of the component, a set of intents that -the component is willing to receive. It, in effect, filters in -intents of a desired type, while filtering out unwanted -intents — but only unwanted implicit intents (those that don't name -a target class). An explicit intent is always delivered to its target, -no matter what it contains; the filter is not consulted. But an implicit -intent is delivered to a component only if it can pass through one of the -component's filters. -</p> - -<p> -A component has separate filters for each job it can do, each face it can -present to the user. For example, the NoteEditor activity of the sample -Note Pad application has two filters — one for starting up with a -specific note that the user can view or edit, and another for starting -with a new, blank note that the user can fill in and save. (All of Note -Pad's filters are described in the <a href="#npex">Note Pad Example</a> -section, later.) -</p> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Filters and security</h2> -<p>An intent filter cannot be relied on for security. While it opens a -component to receiving only certain kinds of implicit intents, it does -nothing to prevent explicit intents from targeting the component. Even -though a filter restricts the intents a component will be asked to handle -to certain actions and data sources, someone could always put -together an explicit intent with a different action and data source, and -name the component as the target. -</p> -</div> -</div> - -<p> -An intent filter is an instance of the {@link android.content.IntentFilter} class. -However, since the Android system must know about the capabilities of a component -before it can launch that component, intent filters are generally not set up in -Java code, but in the application's manifest file (AndroidManifest.xml) as -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> -elements. (The one exception would be filters for -broadcast receivers that are registered dynamically by calling <code>{@link android.content.Context#registerReceiver(BroadcastReceiver, IntentFilter, String, -Handler) Context.registerReceiver()}</code>; they are directly created as -IntentFilter objects.) -</p> - -<p> -A filter has fields that parallel the action, data, and category fields of an -Intent object. An implicit intent is tested against the filter in all three areas. -To be delivered to the component that owns the filter, it must pass all three tests. -If it fails even one of them, the Android system won't deliver it to the -component — at least not on the basis of that filter. However, since a -component can have multiple intent filters, an intent that does not pass -through one of a component's filters might make it through on another. -</p> - -<p> -Each of the three tests is described in detail below: -</p> - -<dl> - -<dt><b>Action test</b></dt> -<dd>An -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> -element in the manifest file lists actions as -<code><a href="{@docRoot}guide/topics/manifest/action-element.html"><action></a></code> -subelements. For example: - -<pre><intent-filter . . . > - <action android:name="com.example.project.SHOW_CURRENT" /> - <action android:name="com.example.project.SHOW_RECENT" /> - <action android:name="com.example.project.SHOW_PENDING" /> - . . . -</intent-filter></pre> - -<p> -As the example shows, while an Intent object names just a single action, -a filter may list more than one. The list cannot be empty; a filter must -contain at least one {@code <action>} element, or it -will block all intents. -</p> - -<p> -To pass this test, the action specified in the Intent object must match -one of the actions listed in the filter. If the object or the filter -does not specify an action, the results are as follows: -</p> - -<ul> -<li>If the filter fails to list any actions, there is nothing for an -intent to match, so all intents fail the test. No intents can get -through the filter.</li> - -<li><p>On the other hand, an Intent object that doesn't specify an -action automatically passes the test — as long as the filter -contains at least one action.</p></li> -</ul -</dd> - -<dt><b>Category test</b></dt> -<dd>An -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> -element also lists categories as subelements. For example: - -<pre><intent-filter . . . > - <category android:name="android.intent.category.DEFAULT" /> - <category android:name="android.intent.category.BROWSABLE" /> - . . . -</intent-filter></pre> - -<p> -Note that the constants described earlier for actions and categories are not -used in the manifest file. The full string values are used instead. For -instance, the "{@code android.intent.category.BROWSABLE}" string in the example -above corresponds to the {@code CATEGORY_BROWSABLE} constant mentioned earlier -in this document. Similarly, the string "{@code android.intent.action.EDIT}" -corresponds to the {@code ACTION_EDIT} constant. -</p> - -<p> -For an intent to pass the category test, every category in the Intent object -must match a category in the filter. The filter can list additional categories, -but it cannot omit any that are in the intent. -</p> - -<p> -In principle, therefore, an Intent object with no categories should always pass -this test, regardless of what's in the filter. That's mostly true. However, -with one exception, Android treats all implicit intents passed to {@link -android.content.Context#startActivity startActivity()} as if they contained -at least one category: "{@code android.intent.category.DEFAULT}" (the -{@code CATEGORY_DEFAULT} constant). -Therefore, activities that are willing to receive implicit intents must -include "{@code android.intent.category.DEFAULT}" in their intent filters. -(Filters with "{@code android.intent.action.MAIN}" and -"{@code android.intent.category.LAUNCHER}" settings are the exception. -They mark activities that begin new tasks and that are represented on the -launcher screen. They can include "{@code android.intent.category.DEFAULT}" -in the list of categories, but don't need to.) See <a href="#imatch">Using -intent matching</a>, later, for more on these filters.) -</p> -<dd> - -<dt><b>Data test</b></dt> -<dd>Like the action and categories, the data specification for an intent filter -is contained in a subelement. And, as in those cases, the subelement can appear -multiple times, or not at all. For example: - -<pre><intent-filter . . . > - <data android:mimeType="video/mpeg" android:scheme="http" . . . /> - <data android:mimeType="audio/mpeg" android:scheme="http" . . . /> - . . . -</intent-filter></pre> - -<p> -Each -<code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code> -element can specify a URI and a data type (MIME media type). There are separate -attributes — {@code scheme}, {@code host}, {@code port}, -and {@code path} — for each part of the URI: -</p> - -<p style="margin-left: 2em">{@code scheme://host:port/path}</p> - -<p> -For example, in the following URI, -</p> - -<p style="margin-left: 2em">{@code content://com.example.project:200/folder/subfolder/etc}</p> - -<p> the scheme is "{@code content}", the host is "{@code com.example.project}", -the port is "{@code 200}", and the path is "{@code folder/subfolder/etc}". -The host and port together constitute the URI <i>authority</i>; if a host is -not specified, the port is ignored. -</p> - -<p> -Each of these attributes is optional, but they are not independent of each other: -For an authority to be meaningful, a scheme must also be specified. -For a path to be meaningful, both a scheme and an authority must be specified. -</p> - -<p> -When the URI in an Intent object is compared to a URI specification in a filter, -it's compared only to the parts of the URI actually mentioned in the filter. -For example, if a filter specifies only a scheme, all URIs with that scheme match -the filter. If a filter specifies a scheme and an authority but no path, all URIs -with the same scheme and authority match, regardless of their paths. If a filter -specifies a scheme, an authority, and a path, only URIs with the same scheme, -authority, and path match. However, a path specification in the filter can -contain wildcards to require only a partial match of the path. -</p> - -<p> -The {@code type} attribute of a {@code <data>} element specifies the MIME type -of the data. It's more common in filters than a URI. Both the Intent object and -the filter can use a "*" wildcard for the subtype field — for example, -"{@code text/*}" or "{@code audio/*}" — indicating any subtype matches. -</p> - -<p> -The data test compares both the URI and the data type in the Intent object to a URI -and data type specified in the filter. The rules are as follows: -</p> - -<ol type="a"> -<li>An Intent object that contains neither a URI nor a data type passes the -test only if the filter likewise does not specify any URIs or data types.</li> - -<li><p>An Intent object that contains a URI but no data type (and a type cannot -be inferred from the URI) passes the test only if its URI matches a URI in the -filter and the filter likewise does not specify a type. This will be the case -only for URIs like {@code mailto:} and {@code tel:} that do not refer to actual data.</p></li> - -<li><p>An Intent object that contains a data type but not a URI passes the test -only if the filter lists the same data type and similarly does not specify a URI.</p></li> - -<li><p>An Intent object that contains both a URI and a data type (or a data type -can be inferred from the URI) passes the data type part of the test only if its -type matches a type listed in the filter. It passes the URI part of the test -either if its URI matches a URI in the filter or if it has a {@code content:} -or {@code file:} URI and the filter does not specify a URI. In other words, -a component is presumed to support {@code content:} and {@code file:} data if -its filter lists only a data type.</p></li> -</ol> -</dl> - -<p> -If an intent can pass through the filters of more than one activity or service, -the user may be asked which component to activate. An exception is raised if -no target can be found. -</p> - - -<h3><a name="ccases"></a>Common cases</h3> - -<p> -The last rule shown above for the data test, rule (d), reflects the expectation -that components are able to get local data from a file or content provider. -Therefore, their filters can list just a data type and do not need to explicitly -name the {@code content:} and {@code file:} schemes. -This is a typical case. A {@code <data>} element like the following, -for example, tells Android that the component can get image data from a content -provider and display it: -</p> - -<pre><data android:mimeType="image/*" /></pre> - -<p> -Since most available data is dispensed by content providers, filters that -specify a data type but not a URI are perhaps the most common. -</p> - -<p> -Another common configuration is filters with a scheme and a data type. For -example, a {@code <data>} element like the following tells Android that -the component can get video data from the network and display it: -</p> - -<pre><data android:scheme="http" android:type="video/*" /></pre> - -<p> -Consider, for example, what the browser application does when -the user follows a link on a web page. It first tries to display the data -(as it could if the link was to an HTML page). If it can't display the data, -it puts together an implicit intent with the scheme and data type and tries -to start an activity that can do the job. If there are no takers, it asks the -download manager to download the data. That puts it under the control -of a content provider, so a potentially larger pool of activities -(those with filters that just name a data type) can respond. -</p> - -<p> -Most applications also have a way to start fresh, without a reference -to any particular data. Activities that can initiate applications -have filters with "{@code android.intent.action.MAIN}" specified as -the action. If they are to be represented in the application launcher, -they also specify the "{@code android.intent.category.LAUNCHER}" -category: -</p> - -<pre><intent-filter . . . > - <action android:name="code android.intent.action.MAIN" /> - <category android:name="code android.intent.category.LAUNCHER" /> -</intent-filter></pre> - - -<h3><a name="imatch"></a>Using intent matching</h3> - -<p> -Intents are matched against intent filters not only to discover a target -component to activate, but also to discover something about the set of -components on the device. For example, the Android system populates the -application launcher, the top-level screen that shows the applications -that are available for the user to launch, by finding all the activities - with intent filters that specify the "{@code android.intent.action.MAIN}" -action and "{@code android.intent.category.LAUNCHER}" category -(as illustrated in the previous section). It then displays the icons and -labels of those activities in the launcher. Similarly, it discovers the -home screen by looking for the activity with -"{@code android.intent.category.HOME}" in its filter. -</p> - -<p> -Your application can use intent matching is a similar way. -The {@link android.content.pm.PackageManager} has a set of {@code query...()} -methods that return all components that can accept a particular intent, and -a similar series of {@code resolve...()} methods that determine the best -component to respond to an intent. For example, -{@link android.content.pm.PackageManager#queryIntentActivities -queryIntentActivities()} returns a list of all activities that can perform -the intent passed as an argument, and {@link -android.content.pm.PackageManager#queryIntentServices -queryIntentServices()} returns a similar list of services. -Neither method activates the components; they just list the ones that -can respond. There's a similar method, -{@link android.content.pm.PackageManager#queryBroadcastReceivers -queryBroadcastReceivers()}, for broadcast receivers. -</p> - -<h2 id="npex">Note Pad Example</h2> - -<p> -The Note Pad sample application enables users to browse through a list -of notes, view details about individual items in the list, edit the items, -and add a new item to the list. This section looks at the intent filters -declared in its manifest file. (If you're working offline in the SDK, you -can find all the source files for this sample application, including its -manifest file, at {@code <sdk>/samples/NotePad/index.html}. -If you're viewing the documentation online, the source files are in the -<a href="{@docRoot}resources/samples/index.html">Tutorials and Sample Code</a> -section <a href="{@docRoot}resources/samples/NotePad/index.html">here</a>.) -</p> - -<p> -In its manifest file, the Note Pad application declares three activities, -each with at least one intent filter. It also declares a content provider -that manages the note data. Here is the manifest file in its entirety: -</p> - -<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android" - package="com.example.android.notepad"> - <application android:icon="@drawable/app_notes" - android:label="@string/app_name" > - - <provider android:name="NotePadProvider" - android:authorities="com.google.provider.NotePad" /> - - <activity android:name="NotesList" android:label="@string/title_notes_list"> - <intent-filter> - <action android:name="android.intent.action.MAIN" /> - <category android:name="android.intent.category.LAUNCHER" /> - </intent-filter> - <intent-filter> - <action android:name="android.intent.action.VIEW" /> - <action android:name="android.intent.action.EDIT" /> - <action android:name="android.intent.action.PICK" /> - <category android:name="android.intent.category.DEFAULT" /> - <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" /> - </intent-filter> - <intent-filter> - <action android:name="android.intent.action.GET_CONTENT" /> - <category android:name="android.intent.category.DEFAULT" /> - <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> - </intent-filter> - </activity> - - <activity android:name="NoteEditor" - android:theme="@android:style/Theme.Light" - android:label="@string/title_note" > - <intent-filter android:label="@string/resolve_edit"> - <action android:name="android.intent.action.VIEW" /> - <action android:name="android.intent.action.EDIT" /> - <action android:name="com.android.notepad.action.EDIT_NOTE" /> - <category android:name="android.intent.category.DEFAULT" /> - <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> - </intent-filter> - <intent-filter> - <action android:name="android.intent.action.INSERT" /> - <category android:name="android.intent.category.DEFAULT" /> - <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" /> - </intent-filter> - </activity> - - <activity android:name="TitleEditor" - android:label="@string/title_edit_title" - android:theme="@android:style/Theme.Dialog"> - <intent-filter android:label="@string/resolve_title"> - <action android:name="com.android.notepad.action.EDIT_TITLE" /> - <category android:name="android.intent.category.DEFAULT" /> - <category android:name="android.intent.category.ALTERNATIVE" /> - <category android:name="android.intent.category.SELECTED_ALTERNATIVE" /> - <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> - </intent-filter> - </activity> - - </application> -</manifest></pre> - -<p> -The first activity, NotesList, is -distinguished from the other activities by the fact that it operates -on a directory of notes (the note list) rather than on a single note. -It would generally serve as the initial user interface into the -application. It can do three things as described by its three intent -filters: -</p> - -<ol> -<li><pre><intent-filter> - <action android:name="android.intent.action.MAIN" /> - <category android:name="android.intent.category.LAUNCHER" /> -</intent-filter></pre> - -<p> -This filter declares the main entry point into the Note Pad application. -The standard {@code MAIN} action is an entry point that does not require -any other information in the Intent (no data specification, for example), -and the {@code LAUNCHER} category says that this entry point should be -listed in the application launcher. -</p></li> - -<li><pre><intent-filter> - <action android:name="android.intent.action.VIEW" /> - <action android:name="android.intent.action.EDIT" /> - <action android:name="android.intent.action.PICK" /> - <category android:name="android.intent.category.DEFAULT" /> - <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" /> -</intent-filter></pre> - -<p> -This filter declares the things that the activity can do on a directory -of notes. It can allow the user to view or edit the directory (via -the {@code VIEW} and {@code EDIT} actions), or to pick a particular note -from the directory (via the {@code PICK} action). -</p> - -<p> -The {@code mimeType} attribute of the -<code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code> -element specifies the kind of data that these actions operate on. It -indicates that the activity can get a Cursor over zero or more items -({@code vnd.android.cursor.dir}) from a content provider that holds -Note Pad data ({@code vnd.google.note}). The Intent object that launches -the activity would include a {@code content:} URI specifying the exact -data of this type that the activity should open. -</p> - -<p> -Note also the {@code DEFAULT} category supplied in this filter. It's -there because the <code>{@link android.content.Context#startActivity -Context.startActivity()}</code> and -<code>{@link android.app.Activity#startActivityForResult -Activity.startActivityForResult()}</code> methods treat all intents -as if they contained the {@code DEFAULT} category — with just -two exceptions: -</p> - -<ul> -<li>Intents that explicitly name the target activity</li> -<li>Intents consisting of the {@code MAIN} action and {@code LAUNCHER} -category</li> -</ul> - -<p> -Therefore, the {@code DEFAULT} category is <em>required</em> for all -filters — except for those with the {@code MAIN} action and -{@code LAUNCHER} category. (Intent filters are not consulted for -explicit intents.) -</p></li> - -<li><pre><intent-filter> - <action android:name="android.intent.action.GET_CONTENT" /> - <category android:name="android.intent.category.DEFAULT" /> - <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> -</intent-filter></pre> - -<p> -This filter describes the activity's ability to return a note selected by -the user without requiring any specification of the directory the user should -choose from. The {@code GET_CONTENT} action is similar to the {@code PICK} -action. In both cases, the activity returns the URI for a note selected by -the user. (In each case, it's returned to the activity that called -<code>{@link android.app.Activity#startActivityForResult -startActivityForResult()}</code> to start the NoteList activity.) Here, -however, the caller specifies the type of data desired instead of the -directory of data the user will be picking from. -</p> - -<p> -The data type, <code>vnd.android.cursor.item/vnd.google.note</code>, -indicates the type of data the activity can return — a URI for -a single note. From the returned URI, the caller can get a Cursor for -exactly one item ({@code vnd.android.cursor.item}) from the content -provider that holds Note Pad data ({@code vnd.google.note}). -</p> - -<p> -In other words, for the {@code PICK} action in the previous filter, -the data type indicates the type of data the activity could display to the -user. For the {@code GET_CONTENT} filter, it indicates the type of data -the activity can return to the caller. -</p></li> -</ol> - -<p> -Given these capabilities, the following intents will resolve to the -NotesList activity: -</p> - -<dl style="margin-left: 2em"> -<dt>action: <code>android.intent.action.MAIN</code></dt> -<dd>Launches the activity with no data specified.</dd> - -<dt>action: <code>android.intent.action.MAIN</code> -<br/>category: <code>android.intent.category.LAUNCHER</code></dt> -<dd> Launches the activity with no data selected specified. -This is the actual intent used by the Launcher to populate its top-level -list. All activities with filters that match this action and category -are added to the list.</dd> - -<dt>action: <code>android.intent.action.VIEW</code> -<br/>data: <code>content://com.google.provider.NotePad/notes</code></dt> -<dd>Asks the activity to display a list of all the notes under -<code>content://com.google.provider.NotePad/notes</code>. The user can then -browse through the list and get information about the items in it.</dd> - -<dt>action: <code>android.intent.action.PICK</code> -<br/>data: <code>content://com.google.provider.NotePad/notes</code></dt> -<dd>Asks the activity to display a list of the notes under -<code>content://com.google.provider.NotePad/notes</code>. -The user can then pick a note from the list, and the activity will return -the URI for that item back to the activity that started the NoteList activity.</dd> - -<dt>action: <code>android.intent.action.GET_CONTENT</code> -<br/>data type: <code>vnd.android.cursor.item/vnd.google.note</code></dt> -<dd>Asks the activity to supply a single item of Note Pad data.</dd> -</dl> - -<p> -The second activity, NoteEditor, shows -users a single note entry and allows them to edit it. It can do two things -as described by its two intent filters: - -<ol> -<li><pre><intent-filter android:label="@string/resolve_edit"> - <action android:name="android.intent.action.VIEW" /> - <action android:name="android.intent.action.EDIT" /> - <action android:name="com.android.notepad.action.EDIT_NOTE" /> - <category android:name="android.intent.category.DEFAULT" /> - <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> -</intent-filter></pre> - -<p> -The first, primary, purpose of this activity is to enable the user to -interact with a single note — to either {@code VIEW} the note or -{@code EDIT} it. (The {@code EDIT_NOTE} category is a synonym for -{@code EDIT}.) The intent would contain the URI for data matching the -MIME type <code>vnd.android.cursor.item/vnd.google.note</code> — -that is, the URI for a single, specific note. It would typically be a -URI that was returned by the {@code PICK} or {@code GET_CONTENT} -actions of the NoteList activity. -</p> - -<p> -As before, this filter lists the {@code DEFAULT} category so that the -activity can be launched by intents that don't explicitly specify the -NoteEditor class. -</p></li> - -<li><pre><intent-filter> - <action android:name="android.intent.action.INSERT" /> - <category android:name="android.intent.category.DEFAULT" /> - <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" /> -</intent-filter></pre> - -<p> -The secondary purpose of this activity is to enable the user to create a new -note, which it will {@code INSERT} into an existing directory of notes. The -intent would contain the URI for data matching the MIME type -<code>vnd.android.cursor.dir/vnd.google.note</code> — that -is, the URI for the directory where the note should be placed. -</p></li> -</ol> - -<p> -Given these capabilities, the following intents will resolve to the -NoteEditor activity: -</p> - -<dl style:"margin-left: 2em"> -<dt>action: <code>android.intent.action.VIEW</code> -<br/>data: <code>content://com.google.provider.NotePad/notes/<var>ID</var></code></dt> -<dd>Asks the activity to display the content of the note identified -by {@code <var>ID</var>}. (For details on how {@code content:} URIs -specify individual members of a group, see -<a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>.) - -<dt>action: <code>android.intent.action.EDIT</code> -<br/>data: <code>content://com.google.provider.NotePad/notes/<var>ID</var></code></dt> -<dd>Asks the activity to display the content of the note identified -by {@code <var>ID</var>}, and to let the user edit it. If the user -saves the changes, the activity updates the data for the note in the -content provider.</dd> - -<dt>action: <code>android.intent.action.INSERT</code> -<br/>data: <code>content://com.google.provider.NotePad/notes</code></dt> -<dd>Asks the activity to create a new, empty note in the notes list at -<code>content://com.google.provider.NotePad/notes</code> -and allow the user to edit it. If the user saves the note, its URI -is returned to the caller. -</dd> -</dl> - -<p>The last activity, TitleEditor, -enables the user to edit the title of a note. This could be implemented -by directly invoking the activity (by explicitly setting its component -name in the Intent), without using an intent filter. But here we take -the opportunity to show how to publish alternative operations on existing -data: -</p> - -<pre><intent-filter android:label="@string/resolve_title"> - <action android:name="com.android.notepad.action.EDIT_TITLE" /> - <category android:name="android.intent.category.DEFAULT" /> - <category android:name="android.intent.category.ALTERNATIVE" /> - <category android:name="android.intent.category.SELECTED_ALTERNATIVE" /> - <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> -</intent-filter></pre> - -<p> -The single intent filter for this activity uses a custom action called -"<code>com.android.notepad.action.EDIT_TITLE</code>". It must be invoked on -a specific note (data type <code>vnd.android.cursor.item/vnd.google.note</code>), -like the previous {@code VIEW} and {@code EDIT} actions. However, here the -activity displays the title contained in the note data, not the content of -the note itself. -</p> - -<p> -In addition to supporting the usual {@code DEFAULT} category, the title -editor also supports two other standard categories: -<code>{@link android.content.Intent#CATEGORY_ALTERNATIVE ALTERNATIVE}</code> -and <code>{@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE -SELECTED_ALTERNATIVE}</code>. -These categories identify activities that can be presented to users in -a menu of options (much as the {@code LAUNCHER} category identifies -activities that should be presented to user in the application launcher). -Note that the filter also supplies an explicit label (via -<code>android:label="@string/resolve_title"</code>) to better control -what users see when presented with this activity as an alternative -action to the data they are currently viewing. (For more information -on these categories and building options menus, see the -<code>{@link android.content.pm.PackageManager#queryIntentActivityOptions -PackageManager.queryIntentActivityOptions()}</code> and -<code>{@link android.view.Menu#addIntentOptions Menu.addIntentOptions()}</code> -methods.) -</p> - -<p> -Given these capabilities, the following intent will resolve to the -TitleEditor activity: -</p> - -<dl style="margin-left: 2em"> -<dt>action: <code>com.android.notepad.action.EDIT_TITLE</code> -<br/>data: <code>content://com.google.provider.NotePad/notes/<var>ID</var></code></dt> -<dd>Asks the activity to display the title associated with note <var>ID</var>, and -allow the user to edit the title.</dd> -</dl> - - - - - - - - - - - diff --git a/docs/html/guide/topics/location/index.jd b/docs/html/guide/topics/location/index.jd index 8a2e9cd..54c034d 100644 --- a/docs/html/guide/topics/location/index.jd +++ b/docs/html/guide/topics/location/index.jd @@ -13,8 +13,7 @@ device's location and bearing and register for updates</li> <h2>Topics</h2> <ol> - <li><a href="{@docRoot}guide/topics/location/obtaining-user-location.html">Obtaining User -Location</a></li> + <li><a href="{@docRoot}guide/topics/location/strategies.html">Location Strategies</a></li> </ol> <h2>See Also</h2> @@ -58,8 +57,7 @@ comes within a given proximity (specified by radius in meters) of a given lat/lo </ul> <p>For more information, read the guide to <a -href="{@docRoot}guide/topics/location/obtaining-user-location.html">Obtaining User -Location</a>.</p> +href="{@docRoot}guide/topics/location/strategies.html">Location Strategies</a>.</p> <h2 id="maps">Google Maps External Library</h2> @@ -98,8 +96,8 @@ Google APIs add-on, visit</p> href="http://code.google.com/android/add-ons/google-apis">http://code.google.com/android/add-ons/google-apis</a></p> <p>For your convenience, the Google APIs add-on is also available as a downloadable component from -the Android SDK Manager (see <a href="{@docRoot}sdk/adding-components.html">Adding SDK -Components</a>).</p> +the Android SDK Manager (see <a href="{@docRoot}sdk/exploring.html">Exploring the +SDK</a>).</p> <p class="note"><strong>Note:</strong> In order to display Google Maps data in a MapView, you must register with the Google Maps service and obtain a Maps API diff --git a/docs/html/guide/topics/location/obtaining-user-location.jd b/docs/html/guide/topics/location/strategies.jd index 3b450f0..f790953 100644 --- a/docs/html/guide/topics/location/obtaining-user-location.jd +++ b/docs/html/guide/topics/location/strategies.jd @@ -1,4 +1,4 @@ -page.title=Obtaining User Location +page.title=Location Strategies parent.title=Location and Maps parent.link=index.html @jd:body @@ -422,7 +422,7 @@ lat/long coordinates, with a GPX file for route playback, or a KML file for mult </ul> <p>For more information on using DDMS to spoof location data, see -<a href="{@docRoot}guide/developing/debugging/ddms.html">Using DDMS</a>. +<a href="{@docRoot}tools/debugging/ddms.html">Using DDMS</a>. <h3 id="MockGeo">Using the "geo" command in the emulator console</h3> @@ -451,4 +451,4 @@ lat/long coordinates, with a GPX file for route playback, or a KML file for mult </ol> <p>For information about how to connect to the emulator console, see -<a href="{@docRoot}guide/developing/devices/emulator.html#console">Using the Emulator Console</a>.</p> +<a href="{@docRoot}tools/devices/emulator.html#console">Using the Emulator Console</a>.</p> diff --git a/docs/html/guide/topics/manifest/action-element.jd b/docs/html/guide/topics/manifest/action-element.jd index 8ad94cd..037d0dc 100644 --- a/docs/html/guide/topics/manifest/action-element.jd +++ b/docs/html/guide/topics/manifest/action-element.jd @@ -16,7 +16,7 @@ parent.link=manifest-intro.html An <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element must contain one or more {@code <action>} elements. If it doesn't contain any, no Intent objects will get through the filter. See -<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and +<a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a> for details on intent filters and the role of action specifications within a filter. </dd> diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd index 9dc124b..88f226c 100644 --- a/docs/html/guide/topics/manifest/activity-element.jd +++ b/docs/html/guide/topics/manifest/activity-element.jd @@ -508,7 +508,7 @@ other activities and tasks using the <em>Back</em> button. </p> <p>For more information on launch modes and their interaction with Intent flags, see the -<a href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back Stack</a> +<a href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back Stack</a> document. </p> </dd> diff --git a/docs/html/guide/topics/manifest/category-element.jd b/docs/html/guide/topics/manifest/category-element.jd index f392c0a..41a2cfd 100644 --- a/docs/html/guide/topics/manifest/category-element.jd +++ b/docs/html/guide/topics/manifest/category-element.jd @@ -12,7 +12,7 @@ parent.link=manifest-intro.html <dt>description:</dt> <dd>Adds a category name to an intent filter. See -<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and +<a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a> for details on intent filters and the role of category specifications within a filter.</dd> diff --git a/docs/html/guide/topics/manifest/compatible-screens-element.jd b/docs/html/guide/topics/manifest/compatible-screens-element.jd index a27c316..bb004fb 100644 --- a/docs/html/guide/topics/manifest/compatible-screens-element.jd +++ b/docs/html/guide/topics/manifest/compatible-screens-element.jd @@ -54,7 +54,7 @@ href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code <supports-screens>}</a> element to declare whether the system should resize your application for different screen sizes.</p> - <p>Also see the <a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a> + <p>Also see the <a href="{@docRoot}guide/google/play/filters.html">Filters on Google Play</a> document for more information about how Google Play filters applications using this and other manifest elements.</p> @@ -138,5 +138,5 @@ entry looks like if your application is compatible with only small and normal sc <dt>see also:</dt> <dd><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></dd> -<dd><a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a></dd> +<dd><a href="{@docRoot}guide/google/play/filters.html">Filters on Google Play</a></dd> </dl> diff --git a/docs/html/guide/topics/manifest/data-element.jd b/docs/html/guide/topics/manifest/data-element.jd index 9b0d0df..8fd91de 100644 --- a/docs/html/guide/topics/manifest/data-element.jd +++ b/docs/html/guide/topics/manifest/data-element.jd @@ -62,7 +62,7 @@ options. None of its attributes have default values. <p> Information on how intent filters work, including the rules for how Intent objects are matched against filters, can be found in another document, -<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and +<a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>. See also the <a href="{@docRoot}guide/topics/manifest/manifest-intro.html#ifs">Intent Filters</a> section in the introduction. diff --git a/docs/html/guide/topics/manifest/intent-filter-element.jd b/docs/html/guide/topics/manifest/intent-filter-element.jd index d293400..f90541c 100644 --- a/docs/html/guide/topics/manifest/intent-filter-element.jd +++ b/docs/html/guide/topics/manifest/intent-filter-element.jd @@ -41,7 +41,7 @@ Most of the contents of the filter are described by its <p> For a more detailed discussion of filters, see the separate -<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents +<a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a> document, as well as the <a href="{@docRoot}guide/topics/manifest/manifest-intro.html#ifs">Intents Filters</a> section in the introduction. diff --git a/docs/html/guide/topics/manifest/manifest-element.jd b/docs/html/guide/topics/manifest/manifest-element.jd index 98968d7..a3d4a95 100644 --- a/docs/html/guide/topics/manifest/manifest-element.jd +++ b/docs/html/guide/topics/manifest/manifest-element.jd @@ -152,7 +152,7 @@ either internal or external storage through the system settings.</td> <p class="caution"><strong>Caution:</strong> If your application uses Google Play's Copy Protection feature, it cannot be installed to a device's SD card. However, if you use Google - Play's <a href="{@docRoot}guide/market/licensing.html">Application Licensing</a> instead, + Play's <a href="{@docRoot}guide/google/play/licensing.html">Application Licensing</a> instead, your application <em>can</em> be installed to internal or external storage, including SD cards.</p> <p class="note"><strong>Note:</strong> By default, your application will be installed on the diff --git a/docs/html/guide/topics/manifest/manifest-intro.jd b/docs/html/guide/topics/manifest/manifest-intro.jd index 0f20305..a130f7d 100644 --- a/docs/html/guide/topics/manifest/manifest-intro.jd +++ b/docs/html/guide/topics/manifest/manifest-intro.jd @@ -345,7 +345,7 @@ filters. <p> For information on how Intent objects are tested against intent filters, see a separate document, -<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents +<a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>. </p> diff --git a/docs/html/guide/topics/manifest/supports-gl-texture-element.jd b/docs/html/guide/topics/manifest/supports-gl-texture-element.jd index ebdd0b1..6dfc59e 100644 --- a/docs/html/guide/topics/manifest/supports-gl-texture-element.jd +++ b/docs/html/guide/topics/manifest/supports-gl-texture-element.jd @@ -141,7 +141,7 @@ and others.</td> <dt>see also:</dt> <dd> <ul> - <li><a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a></li> + <li><a href="{@docRoot}guide/google/play/filters.html">Filters on Google Play</a></li> </ul> </dd> diff --git a/docs/html/guide/topics/manifest/uses-feature-element.jd b/docs/html/guide/topics/manifest/uses-feature-element.jd index 5f0a501..f605295 100644 --- a/docs/html/guide/topics/manifest/uses-feature-element.jd +++ b/docs/html/guide/topics/manifest/uses-feature-element.jd @@ -207,7 +207,7 @@ can check at run-time whether a higher level of OpenGL ES is available.)</p> <li>{@link android.content.pm.FeatureInfo}</li> <li>{@link android.content.pm.ConfigurationInfo}</li> <li><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><code><uses-permission></code></a></li> - <li><a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a></li> + <li><a href="{@docRoot}guide/google/play/filters.html">Filters on Google Play</a></li> </ul> </dd> @@ -501,7 +501,7 @@ If you are using SDK Tools r8 or higher, you can find <code>aapt</code> in the <p class="note"><strong>Note:</strong> You must use the version of <code>aapt</code> that is provided for the latest Platform-Tools component available. If you do not have the latest Platform-Tools component, download it using the <a -href="{@docRoot}sdk/adding-components.html">Android SDK Manager</a>. +href="{@docRoot}sdk/exploring.html">Android SDK Manager</a>. </p></li> <li>Run <code>aapt</code> using this syntax: </li> </ol> diff --git a/docs/html/guide/topics/manifest/uses-library-element.jd b/docs/html/guide/topics/manifest/uses-library-element.jd index 2f8eb50..3ad8ddb 100644 --- a/docs/html/guide/topics/manifest/uses-library-element.jd +++ b/docs/html/guide/topics/manifest/uses-library-element.jd @@ -46,7 +46,7 @@ parent.link=manifest-intro.html <dd> Google Play filters applications based on the libraries installed on the user's device. For more information about filtering, see the topic - <a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a>. + <a href="{@docRoot}guide/google/play/filters.html">Filters on Google Play</a>. </dd> </dl> <p> diff --git a/docs/html/guide/topics/manifest/uses-sdk-element.jd b/docs/html/guide/topics/manifest/uses-sdk-element.jd index 8fa39d1..29dcb56 100644 --- a/docs/html/guide/topics/manifest/uses-sdk-element.jd +++ b/docs/html/guide/topics/manifest/uses-sdk-element.jd @@ -3,6 +3,29 @@ parent.title=The AndroidManifest.xml File parent.link=manifest-intro.html @jd:body + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>In this document</h2> +<ol> + <li><a href="#ApiLevels">What is API Level?</a></li> + <li><a href="#uses">Uses of API Level in Android</a></li> + <li><a href="#considerations">Development Considerations</a> + <ol> + <li><a href="#fc">Application forward compatibility</a></li> + <li><a href="#bc">Application backward compatibility</a></li> + <li><a href="#platform">Selecting a platform version and API Level</a></li> + <li><a href="#apilevel">Declaring a minimum API Level</a></li> + <li><a href="#testing">Testing against higher API Levels</a></li> + </ol> + </li> + <li><a href="#provisional">Using a Provisional API Level</a></li> + <li><a href="#filtering">Filtering the Reference Documentation by API Level</a></li> +</ol> +</div> +</div> + <dl class="xml"> <dt>syntax:</dt> <dd><pre> @@ -25,9 +48,8 @@ The API Level is always a single integer. You cannot derive the API Level from its associated Android version number (for example, it is not the same as the major version or the sum of the major and minor versions).</p> -<p>For more information, read about -<a href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a> and -<a href="{@docRoot}guide/publishing/versioning.html">Versioning Your Applications</a>. +<p>Also read the document about +<a href="{@docRoot}tools/publishing/versioning.html">Versioning Your Applications</a>. </p></dd> <div class="sidebox-wrapper" xstyle="margin-bottom:2em;margin-top:.5em;width:90%;"> @@ -42,7 +64,7 @@ version-compatibility. To do this, Google Play checks the <code><uses-sdk> attributes in each application's manifest to establish its version-compatibility range, then shows or hides the application based on a comparison with the API Level of the user's Android system version. For more information, see <a -href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a>.</p> +href="{@docRoot}guide/google/play/filters.html">Filters on Google Play</a>.</p> </div> </div> @@ -156,3 +178,403 @@ download. </div> <dd>API Level 1</dd> </dl> + + + + + +<!--- CONTENT FROM OLD API LEVEL DOC ----> + + + + +<h2 id="ApiLevels">What is API Level?</h2> + +<p>API Level is an integer value that uniquely identifies the framework API +revision offered by a version of the Android platform.</p> + +<p>The Android platform provides a framework API that applications can use to +interact with the underlying Android system. The framework API consists of:</p> + +<ul> +<li>A core set of packages and classes</li> +<li>A set of XML elements and attributes for declaring a manifest file</li> +<li>A set of XML elements and attributes for declaring and accessing resources</li> +<li>A set of Intents</li> +<li>A set of permissions that applications can request, as well as permission +enforcements included in the system</li> +</ul> + +<p>Each successive version of the Android platform can include updates to the +Android application framework API that it delivers. </p> + +<p>Updates to the framework API are designed so that the new API remains +compatible with earlier versions of the API. That is, most changes in the API +are additive and introduce new or replacement functionality. As parts of the API +are upgraded, the older replaced parts are deprecated but are not removed, so +that existing applications can still use them. In a very small number of cases, +parts of the API may be modified or removed, although typically such changes are +only needed to ensure API robustness and application or system security. All +other API parts from earlier revisions are carried forward without +modification.</p> + +<p>The framework API that an Android platform delivers is specified using an +integer identifier called "API Level". Each Android platform version supports +exactly one API Level, although support is implicit for all earlier API Levels +(down to API Level 1). The initial release of the Android platform provided +API Level 1 and subsequent releases have incremented the API Level.</p> + +<p>The following table specifies the API Level supported by each version of the +Android platform.</p> + +<table> + <tr><th>Platform Version</th><th>API Level</th><th>VERSION_CODE</th><th>Notes</th></tr> + + <tr><td><a href="{@docRoot}about/versions/android-4.0.3.html">Android 4.0.3</a></td> + <td><a href="{@docRoot}sdk/api_diff/15/changes.html" title="Diff Report">15</a></td> + <td>{@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH_MR1}</td> + <td rowspan="2"><a href="{@docRoot}about/versions/android-4.0-highlights.html">Platform +Highlights</a></td></tr> + + <tr><td><a href="{@docRoot}about/versions/android-4.0.html">Android 4.0, 4.0.1, 4.0.2</a></td> + <td><a href="{@docRoot}sdk/api_diff/14/changes.html" title="Diff Report">14</a></td> + <td>{@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH}</td> + </tr> + + <tr><td><a href="{@docRoot}about/versions/android-3.2.html">Android 3.2</a></td> + <td><a href="{@docRoot}sdk/api_diff/13/changes.html" title="Diff Report">13</a></td> + <td>{@link android.os.Build.VERSION_CODES#HONEYCOMB_MR2}</td> + <td><!-- <a href="{@docRoot}about/versions/android-3.2-highlights.html">Platform +Highlights</a>--></td></tr> + + <tr><td><a href="{@docRoot}about/versions/android-3.1.html">Android 3.1.x</a></td> + <td><a href="{@docRoot}sdk/api_diff/12/changes.html" title="Diff Report">12</a></td> + <td>{@link android.os.Build.VERSION_CODES#HONEYCOMB_MR1}</td> + <td><a href="{@docRoot}about/versions/android-3.1-highlights.html">Platform Highlights</a></td></tr> + + <tr><td><a href="{@docRoot}about/versions/android-3.0.html">Android 3.0.x</td> + <td><a href="{@docRoot}sdk/api_diff/11/changes.html" title="Diff Report">11</a></td> + <td>{@link android.os.Build.VERSION_CODES#HONEYCOMB}</td> + <td><a href="{@docRoot}about/versions/android-3.0-highlights.html">Platform Highlights</a></td></tr> + + <tr><td><a href="{@docRoot}about/versions/android-2.3.3.html">Android 2.3.4<br>Android 2.3.3</td> + <td><a href="{@docRoot}sdk/api_diff/10/changes.html" title="Diff Report">10</a></td> + <td>{@link android.os.Build.VERSION_CODES#GINGERBREAD_MR1}</td> + <td rowspan="2"><a href="{@docRoot}about/versions/android-2.3-highlights.html">Platform +Highlights</a></td></tr> + + <tr><td><a href="{@docRoot}about/versions/android-2.3.html">Android 2.3.2<br>Android 2.3.1<br>Android +2.3</td> + <td><a href="{@docRoot}sdk/api_diff/9/changes.html" title="Diff Report">9</a></td> + <td>{@link android.os.Build.VERSION_CODES#GINGERBREAD}</td> + </tr> + + <tr><td><a href="{@docRoot}about/versions/android-2.2.html">Android 2.2.x</td> + <td ><a href="{@docRoot}sdk/api_diff/8/changes.html" title="Diff Report">8</a></td> + <td>{@link android.os.Build.VERSION_CODES#FROYO}</td> + <td><a href="{@docRoot}about/versions/android-2.2-highlights.html">Platform Highlights</a></td></tr> + + <tr><td><a href="{@docRoot}about/versions/android-2.1.html">Android 2.1.x</td> + <td><a href="{@docRoot}sdk/api_diff/7/changes.html" title="Diff Report">7</a></td> + <td>{@link android.os.Build.VERSION_CODES#ECLAIR_MR1}</td> + <td rowspan="3" ><a href="{@docRoot}about/versions/android-2.0-highlights.html">Platform +Highlights</a></td></tr> + + <tr><td><a href="{@docRoot}about/versions/android-2.0.1.html">Android 2.0.1</td> + <td><a href="{@docRoot}sdk/api_diff/6/changes.html" title="Diff Report">6</a></td> + <td>{@link android.os.Build.VERSION_CODES#ECLAIR_0_1}</td> + </tr> + + <tr><td><a href="{@docRoot}about/versions/android-2.0.html">Android 2.0</td> + <td><a href="{@docRoot}sdk/api_diff/5/changes.html" title="Diff Report">5</a></td> + <td>{@link android.os.Build.VERSION_CODES#ECLAIR}</td> + </tr> + + <tr><td><a href="{@docRoot}about/versions/android-1.6.html">Android 1.6</td> + <td><a href="{@docRoot}sdk/api_diff/4/changes.html" title="Diff Report">4</a></td> + <td>{@link android.os.Build.VERSION_CODES#DONUT}</td> + <td><a href="{@docRoot}about/versions/android-1.6-highlights.html">Platform Highlights</a></td></tr> + + <tr><td><a href="{@docRoot}about/versions/android-1.5.html">Android 1.5</td> + <td><a href="{@docRoot}sdk/api_diff/3/changes.html" title="Diff Report">3</a></td> + <td>{@link android.os.Build.VERSION_CODES#CUPCAKE}</td> + <td><a href="{@docRoot}about/versions/android-1.5-highlights.html">Platform Highlights</a></td></tr> + + <tr><td><a href="{@docRoot}about/versions/android-1.1.html">Android 1.1</td> + <td>2</td> + <td>{@link android.os.Build.VERSION_CODES#BASE_1_1}</td><td></td></tr> + + <tr><td>Android 1.0</td> + <td>1</td> + <td>{@link android.os.Build.VERSION_CODES#BASE}</td> + <td></td></tr> +</table> + + +<h2 id="uses">Uses of API Level in Android</h2> + +<p>The API Level identifier serves a key role in ensuring the best possible +experience for users and application developers: + +<ul> +<li>It lets the Android platform describe the maximum framework API revision +that it supports</li> +<li>It lets applications describe the framework API revision that they +require</li> +<li>It lets the system negotiate the installation of applications on the user's +device, such that version-incompatible applications are not installed.</li> +</ul> + +<p>Each Android platform version stores its API Level identifier internally, in +the Android system itself. </p> + +<p>Applications can use a manifest element provided by the framework API — +<code><uses-sdk></code> — to describe the minimum and maximum API +Levels under which they are able to run, as well as the preferred API Level that +they are designed to support. The element offers three key attributes:</p> + +<ul> +<li><code>android:minSdkVersion</code> — Specifies the minimum API Level +on which the application is able to run. The default value is "1".</li> +<li><code>android:targetSdkVersion</code> — Specifies the API Level +on which the application is designed to run. In some cases, this allows the +application to use manifest elements or behaviors defined in the target +API Level, rather than being restricted to using only those defined +for the minimum API Level.</li> +<li><code>android:maxSdkVersion</code> — Specifies the maximum API Level +on which the application is able to run. <strong>Important:</strong> Please read the <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> +documentation before using this attribute. </li> +</ul> + +<p>For example, to specify the minimum system API Level that an application +requires in order to run, the application would include in its manifest a +<code><uses-sdk></code> element with a <code>android:minSdkVersion</code> +attribute. The value of <code>android:minSdkVersion</code> would be the integer +corresponding to the API Level of the earliest version of the Android platform +under which the application can run. </p> + +<p>When the user attempts to install an application, or when revalidating an +appplication after a system update, the Android system first checks the +<code><uses-sdk></code> attributes in the application's manifest and +compares the values against its own internal API Level. The system allows the +installation to begin only if these conditions are met:</p> + +<ul> +<li>If a <code>android:minSdkVersion</code> attribute is declared, its value +must be less than or equal to the system's API Level integer. If not declared, +the system assumes that the application requires API Level 1. </li> +<li>If a <code>android:maxSdkVersion</code> attribute is declared, its value +must be equal to or greater than the system's API Level integer. +If not declared, the system assumes that the application +has no maximum API Level. Please read the <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> +documentation for more information about how the system handles this attribute.</li> +</ul> + +<p>When declared in an application's manifest, a <code><uses-sdk></code> +element might look like this: </p> + +<pre><manifest> + <uses-sdk android:minSdkVersion="5" /> + ... +</manifest></pre> + +<p>The principal reason that an application would declare an API Level in +<code>android:minSdkVersion</code> is to tell the Android system that it is +using APIs that were <em>introduced</em> in the API Level specified. If the +application were to be somehow installed on a platform with a lower API Level, +then it would crash at run-time when it tried to access APIs that don't exist. +The system prevents such an outcome by not allowing the application to be +installed if the lowest API Level it requires is higher than that of the +platform version on the target device.</p> + +<p>For example, the {@link android.appwidget} package was introduced with API +Level 3. If an application uses that API, it must declare a +<code>android:minSdkVersion</code> attribute with a value of "3". The +application will then be installable on platforms such as Android 1.5 (API Level +3) and Android 1.6 (API Level 4), but not on the Android 1.1 (API Level 2) and +Android 1.0 platforms (API Level 1).</p> + +<p>For more information about how to specify an application's API Level +requirements, see the <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> + section of the manifest file documentation.</p> + + +<h2 id="considerations">Development Considerations</h2> + +<p>The sections below provide information related to API level that you should +consider when developing your application.</p> + +<h3 id="fc">Application forward compatibility</h3> + +<p>Android applications are generally forward-compatible with new versions of +the Android platform.</p> + +<p>Because almost all changes to the framework API are additive, an Android +application developed using any given version of the API (as specified by its +API Level) is forward-compatible with later versions of the Android platform and +higher API levels. The application should be able to run on all later versions +of the Android platform, except in isolated cases where the application uses a +part of the API that is later removed for some reason. </p> + +<p>Forward compatibility is important because many Android-powered devices +receive over-the-air (OTA) system updates. The user may install your +application and use it successfully, then later receive an OTA update to a new +version of the Android platform. Once the update is installed, your application +will run in a new run-time version of the environment, but one that has the API +and system capabilities that your application depends on. </p> + +<p>In some cases, changes <em>below</em> the API, such those in the underlying +system itself, may affect your application when it is run in the new +environment. For that reason it's important for you, as the application +developer, to understand how the application will look and behave in each system +environment. To help you test your application on various versions of the Android +platform, the Android SDK includes multiple platforms that you can download. +Each platform includes a compatible system image that you can run in an AVD, to +test your application. </p> + +<h3 id="bc">Application backward compatibility</h3> + +<p>Android applications are not necessarily backward compatible with versions of +the Android platform older than the version against which they were compiled. +</p> + +<p>Each new version of the Android platform can include new framework APIs, such +as those that give applications access to new platform capabilities or replace +existing API parts. The new APIs are accessible to applications when running on +the new platform and, as mentioned above, also when running on later versions of +the platform, as specified by API Level. Conversely, because earlier versions of +the platform do not include the new APIs, applications that use the new APIs are +unable to run on those platforms.</p> + +<p>Although it's unlikely that an Android-powered device would be downgraded to +a previous version of the platform, it's important to realize that there are +likely to be many devices in the field that run earlier versions of the +platform. Even among devices that receive OTA updates, some might lag and +might not receive an update for a significant amount of time. </p> + +<h3 id="platform">Selecting a platform version and API Level</h3> + +<p>When you are developing your application, you will need to choose +the platform version against which you will compile the application. In +general, you should compile your application against the lowest possible +version of the platform that your application can support. + +<p>You can determine the lowest possible platform version by compiling the +application against successively lower build targets. After you determine the +lowest version, you should create an AVD using the corresponding platform +version (and API Level) and fully test your application. Make sure to declare a +<code>android:minSdkVersion</code> attribute in the application's manifest and +set its value to the API Level of the platform version. </p> + +<h3 id="apilevel">Declaring a minimum API Level</h3> + +<p>If you build an application that uses APIs or system features introduced in +the latest platform version, you should set the +<code>android:minSdkVersion</code> attribute to the API Level of the latest +platform version. This ensures that users will only be able to install your +application if their devices are running a compatible version of the Android +platform. In turn, this ensures that your application can function properly on +their devices. </p> + +<p>If your application uses APIs introduced in the latest platform version but +does <em>not</em> declare a <code>android:minSdkVersion</code> attribute, then +it will run properly on devices running the latest version of the platform, but +<em>not</em> on devices running earlier versions of the platform. In the latter +case, the application will crash at runtime when it tries to use APIs that don't +exist on the earlier versions.</p> + +<h3 id="testing">Testing against higher API Levels</h3> + +<p>After compiling your application, you should make sure to test it on the +platform specified in the application's <code>android:minSdkVersion</code> +attribute. To do so, create an AVD that uses the platform version required by +your application. Additionally, to ensure forward-compatibility, you should run +and test the application on all platforms that use a higher API Level than that +used by your application. </p> + +<p>The Android SDK includes multiple platform versions that you can use, +including the latest version, and provides an updater tool that you can use to +download other platform versions as necessary. </p> + +<p>To access the updater, use the <code>android</code> command-line tool, +located in the <sdk>/tools directory. You can launch the SDK updater by +executing <code>android sdk</code>. You can +also simply double-click the android.bat (Windows) or android (OS X/Linux) file. +In ADT, you can also access the updater by selecting +<strong>Window</strong> > <strong>Android SDK +Manager</strong>.</p> + +<p>To run your application against different platform versions in the emulator, +create an AVD for each platform version that you want to test. For more +information about AVDs, see <a +href="{@docRoot}tools/devices/index.html">Creating and Managing Virtual Devices</a>. If +you are using a physical device for testing, ensure that you know the API Level +of the Android platform it runs. See the table at the top of this document for +a list of platform versions and their API Levels. </p> + +<h2 id="provisional">Using a Provisional API Level</h2> + +<p>In some cases, an "Early Look" Android SDK platform may be available. To let +you begin developing on the platform although the APIs may not be final, the +platform's API Level integer will not be specified. You must instead use the +platform's <em>provisional API Level</em> in your application manifest, in order +to build applications against the platform. A provisional API Level is not an +integer, but a string matching the codename of the unreleased platform version. +The provisional API Level will be specified in the release notes for the Early +Look SDK release notes and is case-sensitive.</p> + +<p>The use of a provisional API Level is designed to protect developers and +device users from inadvertently publishing or installing applications based on +the Early Look framework API, which may not run properly on actual devices +running the final system image.</p> + +<p>The provisional API Level will only be valid while using the Early Look SDK +and can only be used to run applications in the emulator. An application using +the provisional API Level can never be installed on an Android device. At the +final release of the platform, you must replace any instances of the provisional +API Level in your application manifest with the final platform's actual API +Level integer.</p> + + +<h2 id="filtering">Filtering the Reference Documentation by API Level</h2> + +<p>Reference documentation pages on the Android Developers site offer a "Filter +by API Level" control in the top-right area of each page. You can use the +control to show documentation only for parts of the API that are actually +accessible to your application, based on the API Level that it specifies in +the <code>android:minSdkVersion</code> attribute of its manifest file. </p> + +<p>To use filtering, select the checkbox to enable filtering, just below the +page search box. Then set the "Filter by API Level" control to the same API +Level as specified by your application. Notice that APIs introduced in a later +API Level are then grayed out and their content is masked, since they would not +be accessible to your application. </p> + +<p>Filtering by API Level in the documentation does not provide a view +of what is new or introduced in each API Level — it simply provides a way +to view the entire API associated with a given API Level, while excluding API +elements introduced in later API Levels.</p> + +<p>If you decide that you don't want to filter the API documentation, just +disable the feature using the checkbox. By default, API Level filtering is +disabled, so that you can view the full framework API, regardless of API Level. +</p> + +<p>Also note that the reference documentation for individual API elements +specifies the API Level at which each element was introduced. The API Level +for packages and classes is specified as "Since <api level>" at the +top-right corner of the content area on each documentation page. The API Level +for class members is specified in their detailed description headers, +at the right margin. </p> + + + + + + + + + diff --git a/docs/html/guide/topics/media/camera.jd b/docs/html/guide/topics/media/camera.jd index 7d72491..a63270a 100644 --- a/docs/html/guide/topics/media/camera.jd +++ b/docs/html/guide/topics/media/camera.jd @@ -162,8 +162,7 @@ information, you must request location permission: <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> </pre> <p>For more information about getting user location, see -<a href="{@docRoot}guide/topics/location/obtaining-user-location.html">Obtaining User -Location</a>.</p> +<a href="{@docRoot}guide/topics/location/strategies.html">Location Strategies</a>.</p> </li> </ul> diff --git a/docs/html/guide/topics/media/index.jd b/docs/html/guide/topics/media/index.jd index 0e0412a..a750c9a 100644 --- a/docs/html/guide/topics/media/index.jd +++ b/docs/html/guide/topics/media/index.jd @@ -1,63 +1,56 @@ -page.title=Multimedia and Camera +page.title=Media and Camera +page.landing=true +page.landing.intro=Add video, audio, and photo capabilities to your app with Android's robust APIs for playing and recording media. +page.landing.image= + @jd:body - <div id="qv-wrapper"> - <div id="qv"> - -<h2>Topics</h2> -<ol> -<li><a href="{@docRoot}guide/topics/media/mediaplayer.html">Media Playback</a></li> -<li><a href="{@docRoot}guide/topics/media/jetplayer.html">JetPlayer</a></li> -<li><a href="{@docRoot}guide/topics/media/camera.html">Camera</a></li> -<li><a href="{@docRoot}guide/topics/media/audio-capture.html">Audio Capture</a></li> -</ol> - -<h2>Key classes</h2> -<ol> -<li>{@link android.media.MediaPlayer}</li> -<li>{@link android.media.JetPlayer}</li> -<li>{@link android.hardware.Camera}</li> -<li>{@link android.media.MediaRecorder}</li> -<li>{@link android.media.AudioManager}</li> -<li>{@link android.media.SoundPool}</li> -</ol> - -<h2>See also</h2> -<ol> -<li></li> -<li><a href="{@docRoot}guide/appendix/media-formats.html">Android Supported Media Formats</a></li> -<li><a href="{@docRoot}guide/topics/media/jet/jetcreator_manual.html">JetCreator User -Manual</a></li> -</ol> - -</div> -</div> - -<p>The Android multimedia framework includes support for capturing and playing audio, video and -images in a variety of common media types, so that you can easily integrate them into your -applications. You can play audio or video from media files stored in your application's resources, -from standalone files in the file system, or from a data stream arriving over a -network connection, all using the {@link android.media.MediaPlayer} or {@link -android.media.JetPlayer} APIs. You can also record audio, video and take pictures using the {@link -android.media.MediaRecorder} and {@link android.hardware.Camera} APIs if supported by the device -hardware.</p> - -<p>The following topics show you how to use the Android framework to implement multimedia capture -and playback.</p> - -<dl> - <dt><strong><a href="{@docRoot}guide/topics/media/mediaplayer.html">Media Playback</a></strong> - </dt> - <dd>How to play audio and video in your application.</dd> - - <dt><strong><a href="{@docRoot}guide/topics/media/jetplayer.html">JetPlayer</a></strong></dt> - <dd>How to play interactive audio and video in your application using content created with -JetCreator.</dd> - - <dt><strong><a href="{@docRoot}guide/topics/media/camera.html">Camera</a></strong></dt> - <dd>How to use a device camera to take pictures or video in your application.</dd> - - <dt><strong><a href="{@docRoot}guide/topics/media/audio-capture.html">Audio -Capture</a></strong></dt> - <dd>How to record sound in your application.</dd> -</dl>
\ No newline at end of file +<div class="landing-docs"> + + <div class="col-6"> + <h3>Blog Articles</h3> + <a +href="http://android-developers.blogspot.com/2010/06/allowing-applications-to-play-nicer.html"> + <h4>Allowing applications to play nice(r) with each other: Handling remote control +buttons</h4> + <p>If your media playback application creates a media playback service, just like Music, that +responds to the media button events, how will the user know where those events are going to? Music, +or your new application?</p> + </a> + + <a +href="http://android-developers.blogspot.com/2011/11/making-android-games-that-play-nice.html"> + <h4>Making Android Games that Play Nice</h4> + <p>Making a game on Android is easy. Making a great game for a mobile, multitasking, often +multi-core, multi-purpose system like Android is trickier. Even the best developers frequently make +mistakes in the way they interact with the Android system and with other applications</p> + </a> + + <a href="http://android-developers.blogspot.com/2011/12/more-android-games-that-play-nice.html"> + <h4>More Android Games that Play Nice</h4> + <p>Android users get used to using the back key. We expect the volume keys to work in some +intuitive fashion. We expect that the home key behaves in a manner consistent with the Android +navigation paradigm.</p> + </a> + </div> + + <div class="col-6"> + <h3>Training</h3> + + <a href="http://developer.android.com/training/camera/index.html"> + <h4>Capturing Photos</h4> + <p>This class gets you clicking fast with some super-easy ways of leveraging existing camera +applications. In later lessons, you dive deeper and learn how to control the camera hardware +directly.</p> + </a> + + <a href="http://developer.android.com/training/managing-audio/index.html"> + <h4>Managing Audio Playback</h4> + <p>After this class, you will be able to build apps that respond to hardware audio key +presses, which request audio focus when playing audio, and which respond appropriately to changes in +audio focus caused by the system or other applications.</p> + </a> + + </div> + +</div>
\ No newline at end of file diff --git a/docs/html/guide/topics/media/mediaplayer.jd b/docs/html/guide/topics/media/mediaplayer.jd index 002d113..45a58a7 100644 --- a/docs/html/guide/topics/media/mediaplayer.jd +++ b/docs/html/guide/topics/media/mediaplayer.jd @@ -457,7 +457,7 @@ stopForeground(true); </pre> <p>For more information, see the documentation about <a -href="{@docRoot}guide/topics/fundamentals/services.html#Foreground">Services</a> and +href="{@docRoot}guide/components/services.html#Foreground">Services</a> and <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Status Bar Notifications</a>.</p> diff --git a/docs/html/guide/topics/providers/calendar-provider.jd b/docs/html/guide/topics/providers/calendar-provider.jd index d30dda4..f53b062 100644 --- a/docs/html/guide/topics/providers/calendar-provider.jd +++ b/docs/html/guide/topics/providers/calendar-provider.jd @@ -250,27 +250,30 @@ and store its events on the device.</td> <h3 id="query">Querying a calendar</h3> -<p>Here is an example that shows how to get all the calendars for a particular +<p>Here is an example that shows how to get the calendars that are owned by a particular user. For simplicity's sake, in this example the query operation is shown in the user interface thread ("main thread"). In practice, this should be done in an asynchronous thread instead of on the main thread. For more discussion, see -<a href="{@docRoot}guide/topics/fundamentals/loaders.html">Loaders</a>. If you are not just reading data but modifying it, see {@link android.content.AsyncQueryHandler}. +<a href="{@docRoot}guide/components/loaders.html">Loaders</a>. If you are not just +reading data but modifying it, see {@link android.content.AsyncQueryHandler}. </p> <pre> - // Projection array. Creating indices for this array instead of doing - // dynamic lookups improves performance. - public static final String[] EVENT_PROJECTION = new String[] { +// Projection array. Creating indices for this array instead of doing +// dynamic lookups improves performance. +public static final String[] EVENT_PROJECTION = new String[] { Calendars._ID, // 0 Calendars.ACCOUNT_NAME, // 1 - Calendars.CALENDAR_DISPLAY_NAME // 2 - }; + Calendars.CALENDAR_DISPLAY_NAME, // 2 + Calendars.OWNER_ACCOUNT // 3 +}; - // The indices for the projection array above. - private static final int PROJECTION_ID_INDEX = 0; - private static final int PROJECTION_ACCOUNT_NAME_INDEX = 1; - private static final int PROJECTION_DISPLAY_NAME_INDEX = 2;</pre> +// The indices for the projection array above. +private static final int PROJECTION_ID_INDEX = 0; +private static final int PROJECTION_ACCOUNT_NAME_INDEX = 1; +private static final int PROJECTION_DISPLAY_NAME_INDEX = 2; +private static final int PROJECTION_OWNER_ACCOUNT_INDEX = 3;</pre> <div class="sidebox-wrapper"> <div class="sidebox"> <h3>Why must you include @@ -291,11 +294,15 @@ synced.</p> </div> </div> <p> In the next part of the example, you construct your query. The selection specifies the criteria for the query. In this example the query is looking for -all calendars that have the <code>ACCOUNT_NAME</code> -"sampleuser@google.com" and the <code>ACCOUNT_TYPE</code> -"com.google". The query returns a {@link android.database.Cursor} +calendars that have the <code>ACCOUNT_NAME</code> +"sampleuser@google.com", the <code>ACCOUNT_TYPE</code> +"com.google", and the <code>OWNER_ACCOUNT</code> +"sampleuser@google.com". If you want to see all calendars that a user +has viewed, not just calendars the user owns, omit the <code>OWNER_ACCOUNT</code>. +The query returns a {@link android.database.Cursor} object that you can use to traverse the result set returned by the database -query. For more discussion of using queries in content providers, see <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>.</p> +query. For more discussion of using queries in content providers, +see <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>.</p> <pre>// Run query @@ -303,8 +310,10 @@ Cursor cur = null; ContentResolver cr = getContentResolver(); Uri uri = Calendars.CONTENT_URI; String selection = "((" + Calendars.ACCOUNT_NAME + " = ?) AND (" - + Calendars.ACCOUNT_TYPE + " = ?))"; -String[] selectionArgs = new String[] {"sampleuser@gmail.com", "com.google"}; + + Calendars.ACCOUNT_TYPE + " = ?) AND (" + + Calendars.OWNER_ACCOUNT + " = ?))"; +String[] selectionArgs = new String[] {"sampleuser@gmail.com", "com.google", + "sampleuser@gmail.com"}; // Submit the query and get a Cursor object back. cur = cr.query(uri, EVENT_PROJECTION, selection, selectionArgs, null);</pre> @@ -316,12 +325,14 @@ for each field.</p> while (cur.moveToNext()) { long calID = 0; String displayName = null; - String accountName = null; + String accountName = null; + String ownerName = null; // Get the field values calID = cur.getLong(PROJECTION_ID_INDEX); displayName = cur.getString(PROJECTION_DISPLAY_NAME_INDEX); accountName = cur.getString(PROJECTION_ACCOUNT_NAME_INDEX); + ownerName = cur.getString(PROJECTION_OWNER_ACCOUNT_INDEX); // Do something with the values... @@ -1179,5 +1190,3 @@ However, a sync adapter is restricted to the <code>ACCOUNT_NAME</code> and </pre> <p>For a sample implementation of a sync adapter (not specifically related to Calendar), see <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">SampleSyncAdapter</a>. -</body> -</html> diff --git a/docs/html/guide/topics/providers/contacts-provider.jd b/docs/html/guide/topics/providers/contacts-provider.jd new file mode 100644 index 0000000..e3b998a --- /dev/null +++ b/docs/html/guide/topics/providers/contacts-provider.jd @@ -0,0 +1,2361 @@ +page.title=Contacts Provider +@jd:body +<div id="qv-wrapper"> +<div id="qv"> +<h2>Quickview</h2> +<ul> + <li>Android's repository of information about people.</li> + <li> + Syncs with the web. + </li> + <li> + Integrates social stream data. + </li> +</ul> +<h2>In this document</h2> +<ol> + <li> + <a href="#InformationTypes">Contacts Provider Organization</a> + </li> + <li> + <a href="#RawContactBasics">Raw contacts</a> + </li> + <li> + <a href="#DataBasics">Data</a> + </li> + <li> + <a href="#ContactBasics">Contacts</a> + </li> + <li> + <a href="#Sources">Data From Sync Adapters</a> + </li> + <li> + <a href="#Permissions">Required Permissions</a> + </li> + <li> + <a href="#UserProfile">The User Profile</a> + </li> + <li> + <a href="#ContactsProviderMetadata">Contacts Provider Metadata</a> + </li> + <li> + <a href="#Access">Contacts Provider Access</a> + <li> + </li> + <li> + <a href="#SyncAdapters">Contacts Provider Sync Adapters</a> + </li> + <li> + <a href="#SocialStream">Social Stream Data</a> + </li> + <li> + <a href="#AdditionalFeatures">Additional Contacts Provider Features</a> + </li> +</ol> +<h2>Key classes</h2> +<ol> + <li>{@link android.provider.ContactsContract.Contacts}</li> + <li>{@link android.provider.ContactsContract.RawContacts}</li> + <li>{@link android.provider.ContactsContract.Data}</li> + <li>{@link android.provider.ContactsContract.StreamItems}</li> +</ol> +<h2>Related Samples</h2> +<ol> + <li> + <a href="{@docRoot}resources/samples/ContactManager/index.html"> + Contact Manager + </a> + </li> + <li> + <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> + Sample Sync Adapter</a> + </li> +</ol> +<h2>See Also</h2> +<ol> + <li> + <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Content Provider Basics + </a> + </li> +</ol> +</div> +</div> +<p> + The Contacts Provider is a powerful and flexible Android component that manages the + device's central repository of data about people. The Contacts Provider is the source of data + you see in the device's contacts application, and you can also access its data in your own + application and transfer data between the device and online services. The provider accommodates + a wide range of data sources and tries to manage as much data as possible for each person, with + the result that its organization is complex. Because of this, the provider's API includes an + extensive set of contract classes and interfaces that facilitate both data retrieval and + modification. +</p> +<p> + This guide describes the following: +</p> + <ul> + <li> + The basic provider structure. + </li> + <li> + How to retrieve data from the provider. + </li> + <li> + How to modify data in the provider. + </li> + <li> + How to write a sync adapter for synchronizing data from your server to the + Contacts Provider. + </li> + </ul> +<p> + This guide assumes that you know the basics of Android content providers. To learn more + about Android content providers, read the + <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Content Provider Basics</a> guide. The + <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">Sample Sync Adapter</a> + sample app is an example of using a sync adapter to transfer data between the Contacts + Provider and a sample application hosted by Google Web Services. +</p> +<h2 id="InformationTypes">Contacts Provider Organization</h2> +<p> + The Contacts Provider is an Android content provider component. It maintains three types of + data about a person, each of which corresponds to a table offered by the provider, as + illustrated in figure 1: +</p> +<img src="{@docRoot}images/providers/contacts_structure.png" alt="" + height="364" id="figure1" /> +<p class="img-caption"> + <strong>Figure 1.</strong> Contacts Provider table structure. +</p> +<p> + The three tables are commonly referred to by the names of their contract classes. The classes + define constants for content URIs, column names, and column values used by the tables: +</p> +<dl> + <dt> + {@link android.provider.ContactsContract.Contacts} table + </dt> + <dd> + Rows representing different people, based on aggregations of raw contact rows. + </dd> + <dt> + {@link android.provider.ContactsContract.RawContacts} table + </dt> + <dd> + Rows containing a summary of a person's data, specific to a user account and type. + </dd> + <dt> + {@link android.provider.ContactsContract.Data} table + </dt> + <dd> + Rows containing the details for raw contact, such as email addresses or phone numbers. + </dd> +</dl> +<p> + The other tables represented by contract classes in {@link android.provider.ContactsContract} + are auxiliary tables that the Contacts Provider uses to manage its operations or support + specific functions in the device's contacts or telephony applications. +</p> +<h2 id="RawContactBasics">Raw contacts</h2> +<p> + A raw contact represents a person's data coming from a single account type and account + name. Because the Contacts Provider allows more than one online service as the source of + data for a person, the Contacts Provider allows multiple raw contacts for the same person. + Multiple raw contacts also allow a user to combine a person's data from more than one account + from the same account type. +</p> +<p> + Most of the data for a raw contact isn't stored in the + {@link android.provider.ContactsContract.RawContacts} table. Instead, it's stored in one or more + rows in the {@link android.provider.ContactsContract.Data} table. Each data row has a column + {@link android.provider.ContactsContract.DataColumns#RAW_CONTACT_ID Data.RAW_CONTACT_ID} that + contains the {@link android.provider.BaseColumns#_ID RawContacts._ID} value of its + parent {@link android.provider.ContactsContract.RawContacts} row. +</p> +<h3 id="RawContactsColumns">Important raw contact columns</h3> +<p> + The important columns in the {@link android.provider.ContactsContract.RawContacts} table are + listed in table 1. Please read the notes that follow after the table: +</p> +<p class="table-caption" id="table1"> + <strong>Table 1.</strong> Important raw contact columns. +</p> +<table> + <tr> + <th scope="col">Column name</th> + <th scope="col">Use</th> + <th scope="col">Notes</th> + </tr> + <tr> + <td> + {@link android.provider.ContactsContract.SyncColumns#ACCOUNT_NAME} + </td> + <td> + The account name for the account type that's the source of this raw contact. + For example, the account name of a Google account is one of the device owner's Gmail + addresses. See the next entry for + {@link android.provider.ContactsContract.SyncColumns#ACCOUNT_TYPE} for more + information. + </td> + <td> + The format of this name is specific to its account type. It is not + necessarily an email address. + </td> + </tr> + <tr> + <td> + {@link android.provider.ContactsContract.SyncColumns#ACCOUNT_TYPE} + </td> + <td> + The account type that's the source of this raw contact. For example, the account + type of a Google account is <code>com.google</code>. Always qualify your account type + with a domain identifier for a domain you own or control. This will ensure that your + account type is unique. + </td> + <td> + An account type that offers contacts data usually has an associated sync adapter that + synchronizes with the Contacts Provider. + </tr> + <tr> + <td> + {@link android.provider.ContactsContract.RawContactsColumns#DELETED} + </td> + <td> + The "deleted" flag for a raw contact. + </td> + <td> + This flag allows the Contacts Provider to maintain the row internally until sync + adapters are able to delete the row from their servers and then finally delete the row + from the repository. + </td> + </tr> +</table> +<h4>Notes</h4> +<p> + The following are important notes about the + {@link android.provider.ContactsContract.RawContacts} table: +</p> +<ul> + <li> + A raw contact's name is not stored in its row in + {@link android.provider.ContactsContract.RawContacts}. Instead, it's stored in + the {@link android.provider.ContactsContract.Data} table, in a + {@link android.provider.ContactsContract.CommonDataKinds.StructuredName} row. A raw contact + has only one row of this type in the {@link android.provider.ContactsContract.Data} table. + </li> + <li> + <strong>Caution:</strong> To use your own account data in a raw contact row, it must + first be registered with the {@link android.accounts.AccountManager}. To do this, prompt + users to add the account type and their account name to the list of accounts. If you don't + do this, the Contacts Provider will automatically delete your raw contact row. + <p> + For example, if you want your app to maintain contacts data for your web-based service + with the domain {@code com.example.dataservice}, and the user's account for your service + is {@code becky.sharp@dataservice.example.com}, the user must first add the account + "type" ({@code com.example.dataservice}) and account "name" + ({@code becky.smart@dataservice.example.com}) before your app can add raw contact rows. + You can explain this requirement to the user in documentation, or you can prompt the + user to add the type and name, or both. Account types and account names + are described in more detail in the next section. + </li> +</ul> +<h3 id="RawContactsExample">Sources of raw contacts data</h3> +<p> + To understand how raw contacts work, consider the user "Emily Dickinson" who has the following + three user accounts defined on her device: +</p> +<ul> + <li><code>emily.dickinson@gmail.com</code></li> + <li><code>emilyd@gmail.com</code></li> + <li>Twitter account "belle_of_amherst"</li> +</ul> +<p> + This user has enabled <em>Sync Contacts</em> for all three of these accounts in the + <em>Accounts</em> settings. +</p> +<p> + Suppose Emily Dickinson opens a browser window, logs into Gmail as + <code>emily.dickinson@gmail.com</code>, opens + Contacts, and adds "Thomas Higginson". Later on, she logs into Gmail as + <code>emilyd@gmail.com</code> and sends an email to "Thomas Higginson", which automatically + adds him as a contact. She also follows "colonel_tom" (Thomas Higginson's Twitter ID) on + Twitter. +</p> +<p> + The Contacts Provider creates three raw contacts as a result of this work: +</p> +<ol> + <li> + A raw contact for "Thomas Higginson" associated with <code>emily.dickinson@gmail.com</code>. + The user account type is Google. + </li> + <li> + A second raw contact for "Thomas Higginson" associated with <code>emilyd@gmail.com</code>. + The user account type is also Google. There is a second raw contact even + though the name is identical to a previous name, because the person was added for a + different user account. + </li> + <li> + A third raw contact for "Thomas Higginson" associated with "belle_of_amherst". The user + account type is Twitter. + </li> +</ol> +<h2 id="DataBasics">Data</h2> +<p> + As noted previously, the data for a raw contact is stored in a + {@link android.provider.ContactsContract.Data} row that is linked to the raw contact's + <code>_ID</code> value. This allows a single raw contact to have multiple instances of the same + type of data such as email addresses or phone numbers. For example, if + "Thomas Higginson" for {@code emilyd@gmail.com} (the raw contact row for Thomas Higginson + associated with the Google account <code>emilyd@gmail.com</code>) has a home email address of + <code>thigg@gmail.com</code> and a work email address of + <code>thomas.higginson@gmail.com</code>, the Contacts Provider stores the two email address + rows and links them both to the raw contact. +</p> +<p> + Notice that different types of data are stored in this single table. Display name, + phone number, email, postal address, photo, and website detail rows are all found in the + {@link android.provider.ContactsContract.Data} table. To help manage this, the + {@link android.provider.ContactsContract.Data} table has some columns with descriptive names, + and others with generic names. The contents of a descriptive-name column have the same meaning + regardless of the type of data in the row, while the contents of a generic-name column have + different meanings depending on the type of data. +</p> +<h3 id="DescriptiveColumns">Descriptive column names</h3> +<p> + Some examples of descriptive column names are: +</p> +<dl> + <dt> + {@link android.provider.ContactsContract.Data#RAW_CONTACT_ID} + </dt> + <dd> + The value of the <code>_ID</code> column of the raw contact for this data. + </dd> + <dt> + {@link android.provider.ContactsContract.Data#MIMETYPE} + </dt> + <dd> + The type of data stored in this row, expressed as a custom MIME type. The Contacts Provider + uses the MIME types defined in the subclasses of + {@link android.provider.ContactsContract.CommonDataKinds}. These MIME types are open source, + and can be used by any application or sync adapter that works with the Contacts Provider. + </dd> + <dt> + {@link android.provider.ContactsContract.DataColumns#IS_PRIMARY} + </dt> + <dd> + If this type of data row can occur more than once for a raw contact, the + {@link android.provider.ContactsContract.DataColumns#IS_PRIMARY} column flags + the data row that contains the primary data for the type. For example, if + the user long-presses a phone number for a contact and selects <strong>Set default</strong>, + then the {@link android.provider.ContactsContract.Data} row containing that number + has its {@link android.provider.ContactsContract.DataColumns#IS_PRIMARY} column set to a + non-zero value. + </dd> +</dl> +<h3 id="GenericColumns">Generic column names</h3> +<p> + There are 15 generic columns named <code>DATA1</code> through + <code>DATA15</code> that are generally available and an additional four generic + columns <code>SYNC1</code> through <code>SYNC4</code> that should only be used by sync + adapters. The generic column name constants always work, regardless of the type of + data the row contains. +</p> +<p> + The <code>DATA1</code> column is indexed. The Contacts Provider always uses this column for + the data that the provider expects will be the most frequent target of a query. For example, + in an email row, this column contains the actual email address. +</p> +<p> + By convention, the column <code>DATA15</code> is reserved for storing Binary Large Object + (BLOB) data such as photo thumbnails. +</p> +<h3 id="TypeSpecificNames">Type-specific column names</h3> +<p> + To facilitate working with the columns for a particular type of row, the Contacts Provider + also provides type-specific column name constants, defined in subclasses of + {@link android.provider.ContactsContract.CommonDataKinds}. The constants simply give a + different constant name to the same column name, which helps you access data in a row of a + particular type. +</p> +<p> + For example, the {@link android.provider.ContactsContract.CommonDataKinds.Email} class defines + type-specific column name constants for a {@link android.provider.ContactsContract.Data} row + that has the MIME type + {@link android.provider.ContactsContract.CommonDataKinds.Email#CONTENT_ITEM_TYPE + Email.CONTENT_ITEM_TYPE}. The class contains the constant + {@link android.provider.ContactsContract.CommonDataKinds.Email#ADDRESS} for the email address + column. The actual value of + {@link android.provider.ContactsContract.CommonDataKinds.Email#ADDRESS} is "data1", which is + the same as the column's generic name. +</p> +<p class="caution"> + <strong>Caution:</strong> Don't add your own custom data to the + {@link android.provider.ContactsContract.Data} table using a row that has one of the + provider's pre-defined MIME types. If you do, you may lose the data or cause the provider to + malfunction. For example, you should not add a row with the MIME type + {@link android.provider.ContactsContract.CommonDataKinds.Email#CONTENT_ITEM_TYPE + Email.CONTENT_ITEM_TYPE} that contains a user name instead of an email address in the + column <code>DATA1</code>. If you use your own custom MIME type for the row, then you are free + to define your own type-specific column names and use the columns however you wish. +</p> +<p> + Figure 2 shows how descriptive columns and data columns appear in a + {@link android.provider.ContactsContract.Data} row, and how type-specific column names "overlay" + the generic column names +</p> +<img src="{@docRoot}images/providers/data_columns.png" + alt="How type-specific column names map to generic column names" + height="311" id="figure2" /> +<p class="img-caption"> + <strong>Figure 2.</strong> Type-specific column names and generic column names. +</p> +<h3 id="ColumnMaps">Type-specific column name classes</h3> +<p> + Table 2 lists the most commonly-used type-specific column name classes: +</p> +<p class="table-caption" id="table2"> + <strong>Table 2.</strong> Type-specific column name classes</p> +<table> + <tr> + <th scope="col">Mapping class</th> + <th scope="col">Type of data</th> + <th scope="col">Notes</th> + </tr> + <tr> + <td>{@link android.provider.ContactsContract.CommonDataKinds.StructuredName}</td> + <td>The name data for the raw contact associated with this data row.</td> + <td>A raw contact has only one of these rows.</td> + </tr> + <tr> + <td>{@link android.provider.ContactsContract.CommonDataKinds.Photo}</td> + <td>The main photo for the raw contact associated with this data row.</td> + <td>A raw contact has only one of these rows.</td> + </tr> + <tr> + <td>{@link android.provider.ContactsContract.CommonDataKinds.Email}</td> + <td>An email address for the raw contact associated with this data row.</td> + <td>A raw contact can have multiple email addresses.</td> + </tr> + <tr> + <td>{@link android.provider.ContactsContract.CommonDataKinds.StructuredPostal}</td> + <td>A postal address for the raw contact associated with this data row.</td> + <td>A raw contact can have multiple postal addresses.</td> + </tr> + <tr> + <td>{@link android.provider.ContactsContract.CommonDataKinds.GroupMembership}</td> + <td>An identifier that links the raw contact to one of the groups in the Contacts Provider.</td> + <td> + Groups are an optional feature of an account type and account name. They're described in + more detail in the section <a href="#Groups">Contact groups</a>. + </td> + </tr> +</table> +<h3 id="ContactBasics">Contacts</h3> +<p> + The Contacts Provider combines the raw contact rows across all account types and account names + to form a <strong>contact</strong>. This facilitates displaying and modifying all the data a + user has collected for a person. The Contacts Provider manages the creation of new contact + rows, and the aggregation of raw contacts with an existing contact row. Neither applications nor + sync adapters are allowed to add contacts, and some columns in a contact row are read-only. +</p> +<p class="note"> + <strong>Note:</strong> If you try to add a contact to the Contacts Provider with an + {@link android.content.ContentResolver#insert(Uri,ContentValues) insert()}, you'll get + an {@link java.lang.UnsupportedOperationException} exception. If you try to update a column + that's listed as "read-only," the update is ignored. +</p> +<p> + The Contacts Provider creates a new contact in response to the addition of a new raw contact + that doesn't match any existing contacts. The provider also does this if an existing raw + contact's data changes in such a way that it no longer matches the contact to which it was + previously attached. If an application or sync adapter creates a new raw contact that + <em>does</em> match an existing contact, the new raw contact is aggregated to the existing + contact. +</p> +<p> + The Contacts Provider links a contact row to its raw contact rows with the contact row's + <code>_ID</code> column in the {@link android.provider.ContactsContract.Contacts Contacts} + table. The <code>CONTACT_ID</code> column of the raw contacts table + {@link android.provider.ContactsContract.RawContacts} contains <code>_ID</code> values for + the contacts row associated with each raw contacts row. +</p> +<p> + The {@link android.provider.ContactsContract.Contacts} table also has the column + {@link android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY} that is a + "permanent" link to the contact row. Because the Contacts Provider maintains contacts + automatically, it may change a contact row's {@link android.provider.BaseColumns#_ID} value + in response to an aggregation or sync. Even If this happens, the content URI + {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI} combined with + contact's {@link android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY} will still + point to the contact row, so you can use + {@link android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY} + to maintain links to "favorite" contacts, and so forth. This column has its own format that is + unrelated to the format of the {@link android.provider.BaseColumns#_ID} column. +</p> +<p> + Figure 3 shows how the three main tables relate to each other. +</p> +<img src="{@docRoot}images/providers/contacts_tables.png" alt="Contacts provider main tables" + height="514" id="figure4" /> +<p class="img-caption"> + <strong>Figure 3.</strong> Contacts, Raw Contacts, and Details table relationships. +</p> +<h2 id="Sources">Data From Sync Adapters</h2> +<p> + Users enter contacts data directly into the device, but data also flows into the Contacts + Provider from web services via <strong>sync adapters</strong>, which automate + the transfer of data between the device and services. Sync adapters run in the background + under the control of the system, and they call {@link android.content.ContentResolver} methods + to manage data. +</p> +<p> + In Android, the web service that a sync adapter works with is identified by an account type. + Each sync adapter works with one account type, but it can support multiple account names for + that type. Account types and account names are described briefly in the section + <a href="#RawContactsExample">Sources of raw contacts data</a>. The following definitions offer + more detail, and describe how account type and name relate to sync adapters and services. +</p> +<dl> + <dt> + Account type + </dt> + <dd> + Identifies a service in which the user has stored data. Most of the time, the user has to + authenticate with the service. For example, Google Contacts is an account type, identified + by the code <code>google.com</code>. This value corresponds to the account type used by + {@link android.accounts.AccountManager}. + </dd> + <dt> + Account name + </dt> + <dd> + Identifies a particular account or login for an account type. Google Contacts accounts + are the same as Google accounts, which have an email address as an account name. + Other services may use a single-word username or numeric id. + </dd> +</dl> +<p> + Account types don't have to be unique. A user can configure multiple Google Contacts accounts + and download their data to the Contacts Provider; this may happen if the user has one set of + personal contacts for a personal account name, and another set for work. Account names are + usually unique. Together, they identify a specific data flow between the Contacts Provider and + an external service. +</p> +<p> + If you want to transfer your service's data to the Contacts Provider, you need to write your + own sync adapter. This is described in more detail in the section + <a href="#SyncAdapters">Contacts Provider Sync Adapters</a>. +</p> +<p> + Figure 4 shows how the Contacts Provider fits into the flow of data + about people. In the box marked "sync adapters," each adapter is labeled by its account type. +</p> +<img src="{@docRoot}images/providers/ContactsDataFlow.png" alt="Flow of data about people" + height="252" id="figure5" /> +<p class="img-caption"> + <strong>Figure 4.</strong> The Contacts Provider flow of data. +</p> +<h2 id="Permissions">Required Permissions</h2> +<p> + Applications that want to access the Contacts Provider must request the following + permissions: +</p> +<dl> + <dt>Read access to one or more tables</dt> + <dd> + {@link android.Manifest.permission#READ_CONTACTS}, specified in + <code>AndroidManifest.xml</code> with the + <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"> + <uses-permission></a></code> element as + <code><uses-permission android:name="android.permission.READ_CONTACTS"></code>. + </dd> + <dt>Write access to one or more tables</dt> + <dd> + {@link android.Manifest.permission#WRITE_CONTACTS}, specified in + <code>AndroidManifest.xml</code> with the + <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"> + <uses-permission></a></code> element as + <code><uses-permission android:name="android.permission.WRITE_CONTACTS"></code>. + </dd> +</dl> +<p> + These permissions do not extend to the user profile data. The user profile and its + required permissions are discussed in the following section, + <a href="#UserProfile">The User Profile</a>. +</p> +<p> + Remember that the user's contacts data is personal and sensitive. Users are concerned about + their privacy, so they don't want applications collecting data about them or their contacts. + If it's not obvious why you need permission to access their contacts data, they may give + your application low ratings or simply refuse to install it. +</p> +<h2 id="UserProfile">The User Profile</h2> +<p> + The {@link android.provider.ContactsContract.Contacts} table has a single row containing + profile data for the device's user. This data describes the device's <code>user</code> rather + than one of the user's contacts. The profile contacts row is linked to a raw + contacts row for each system that uses a profile. + Each profile raw contact row can have multiple data rows. Constants for accessing the user + profile are available in the {@link android.provider.ContactsContract.Profile} class. +</p> +<p> + Access to the user profile requires special permissions. In addition to the + {@link android.Manifest.permission#READ_CONTACTS} and + {@link android.Manifest.permission#WRITE_CONTACTS} permissions needed to read and write, access + to the user profile requires the {@link android.Manifest.permission#READ_PROFILE} and + {@link android.Manifest.permission#WRITE_PROFILE} permissions for read and write access, + respectively. +</p> +<p> + Remember that you should consider a user's profile to be sensitive. The permission + {@link android.Manifest.permission#READ_PROFILE} allows you to access the device user's + personally-identifying data. Make sure to tell the user why + you need user profile access permissions in the description of your application. +</p> +<p> + To retrieve the contact row that contains the user's profile, + call {@link android.content.ContentResolver#query(Uri,String[], String, String[], String) + ContentResolver.query()}. Set the content URI to + {@link android.provider.ContactsContract.Profile#CONTENT_URI} and don't provide any + selection criteria. You can also use this content URI as the base URI for retrieving raw + contacts or data for the profile. For example, this snippet retrieves data for the profile: +</p> +<pre> +// Sets the columns to retrieve for the user profile +mProjection = new String[] + { + Profile._ID, + Profile.DISPLAY_NAME_PRIMARY, + Profile.LOOKUP_KEY, + Profile.PHOTO_THUMBNAIL_URI + }; + +// Retrieves the profile from the Contacts Provider +mProfileCursor = + getContentResolver().query( + Profile.CONTENT_URI, + mProjection , + null, + null, + null); +</pre> +<p class="note"> + <strong>Note:</strong> If you retrieve multiple contact rows, and you want to determine if one of them + is the user profile, test the row's + {@link android.provider.ContactsContract.ContactsColumns#IS_USER_PROFILE} column. This column + is set to "1" if the contact is the user profile. +</p> +<h2 id="ContactsProviderMetadata">Contacts Provider Metadata</h2> +<p> + The Contacts Provider manages data that keeps track of the state of contacts data in the + repository. This metadata about the repository is stored in various places, including the + Raw Contacts, Data, and Contacts table rows, the + {@link android.provider.ContactsContract.Settings} table, and the + {@link android.provider.ContactsContract.SyncState} table. The following table shows the + effect of each of these pieces of metadata: +</p> +<p class="table-caption" id="table3"> + <strong>Table 3.</strong> Metadata in the Contacts Provider</p> +<table> + <tr> + <th scope="col">Table</th> + <th scope="col">Column</th> + <th scope="col">Values</th> + <th scope="col">Meaning</th> + </tr> + <tr> + <td rowspan="2">{@link android.provider.ContactsContract.RawContacts}</td> + <td rowspan="2">{@link android.provider.ContactsContract.SyncColumns#DIRTY}</td> + <td>"0" - not changed since the last sync.</td> + <td rowspan="2"> + Marks raw contacts that were changed on the device and have to be synced back to the + server. The value is set automatically by the Contacts Provider when Android + applications update a row. + <p> + Sync adapters that modify the raw contact or data tables should always append the + string {@link android.provider.ContactsContract#CALLER_IS_SYNCADAPTER} to the + content URI they use. This prevents the provider from marking rows as dirty. + Otherwise, sync adapter modifications appear to be local modifications and are + sent to the server, even though the server was the source of the modification. + </p> + </td> + </tr> + <tr> + <td>"1" - changed since last sync, needs to be synced back to the server.</td> + </tr> + <tr> + <td>{@link android.provider.ContactsContract.RawContacts}</td> + <td>{@link android.provider.ContactsContract.SyncColumns#VERSION}</td> + <td>The version number of this row.</td> + <td> + The Contacts Provider automatically increments this value whenever the row or + its related data changes. + </td> + </tr> + <tr> + <td>{@link android.provider.ContactsContract.Data}</td> + <td>{@link android.provider.ContactsContract.DataColumns#DATA_VERSION}</td> + <td>The version number of this row.</td> + <td> + The Contacts Provider automatically increments this value whenever the data row + is changed. + </td> + </tr> + <tr> + <td>{@link android.provider.ContactsContract.RawContacts}</td> + <td>{@link android.provider.ContactsContract.SyncColumns#SOURCE_ID}</td> + <td> + A string value that uniquely identifies this raw contact to the account in + which it was created. + </td> + <td> + When a sync adapter creates a new raw contact, this column should be set to the + server's unique ID for the raw contact. When an Android application creates a new + raw contact, the application should leave this column empty. This signals the sync + adapter that it should create a new raw contact on the server, and get a + value for the {@link android.provider.ContactsContract.SyncColumns#SOURCE_ID}. + <p> + In particular, the source id must be <strong>unique</strong> for each account + type and should be stable across syncs: + </p> + <ul> + <li> + Unique: Each raw contact for an account must have its own source id. If you + don't enforce this, you'll cause problems in the contacts application. + Notice that two raw contacts for the same account <em>type</em> may have + the same source id. For example, the raw contact "Thomas Higginson" for the + account {@code emily.dickinson@gmail.com} is allowed to have the same source + id as the raw contact "Thomas Higginson" for the account + {@code emilyd@gmail.com}. + </li> + <li> + Stable: Source ids are a permanent part of the online service's data for + the raw contact. For example, if the user clears Contacts Storage from the + Apps settings and re-syncs, the restored raw contacts should have the same + source ids as before. If you don't enforce this, shortcuts will stop + working. + </li> + </ul> + </td> + </tr> + <tr> + <td rowspan="2">{@link android.provider.ContactsContract.Groups}</td> + <td rowspan="2">{@link android.provider.ContactsContract.GroupsColumns#GROUP_VISIBLE}</td> + <td>"0" - Contacts in this group should not be visible in Android application UIs.</td> + <td> + This column is for compatibility with servers that allow a user to hide contacts in + certain groups. + </td> + </tr> + <tr> + <td>"1" - Contacts in this group are allowed to be visible in application UIs.</td> + </tr> + <tr> + <td rowspan="2">{@link android.provider.ContactsContract.Settings}</td> + <td rowspan="2"> + {@link android.provider.ContactsContract.SettingsColumns#UNGROUPED_VISIBLE}</td> + <td> + "0" - For this account and account type, contacts that don't belong to a group are + invisible to Android application UIs. + </td> + <td rowspan="2"> + By default, contacts are invisible if none of their raw contacts belongs to a group + (Group membership for a raw contact is indicated by one or more + {@link android.provider.ContactsContract.CommonDataKinds.GroupMembership} rows + in the {@link android.provider.ContactsContract.Data} table). + By setting this flag in the {@link android.provider.ContactsContract.Settings} table row + for an account type and account, you can force contacts without groups to be visible. + One use of this flag is to show contacts from servers that don't use groups. + </td> + </tr> + <tr> + <td> + "1" - For this account and account type, contacts that don't belong to a group are + visible to application UIs. + </td> + + </tr> + <tr> + <td>{@link android.provider.ContactsContract.SyncState}</td> + <td>(all)</td> + <td> + Use this table to store metadata for your sync adapter. + </td> + <td> + With this table you can store sync state and other sync-related data persistently on + the device. + </td> + </tr> +</table> +<h2 id="Access">Contacts Provider Access</h2> +<p> + This section describes guidelines for accessing data from the Contacts Provider, focusing on + the following: +</p> +<ul> + <li> + Entity queries. + </li> + <li> + Batch modification. + </li> + <li> + Retrieval and modification with intents. + </li> + <li> + Data integrity. + </li> +</ul> +<p> + Making modifications from a sync adapter is also covered in more detail in the section + <a href="#SyncAdapters">Contacts Provider Sync Adapters</a>. +</p> +<h3 id="Entities">Querying entities</h3> +<p> + Because the Contacts Provider tables are organized in a hierarchy, it's often useful to + retrieve a row and all of the "child" rows that are linked to it. For example, to display + all the information for a person, you may want to retrieve all the + {@link android.provider.ContactsContract.RawContacts} rows for a single + {@link android.provider.ContactsContract.Contacts} row, or all the + {@link android.provider.ContactsContract.CommonDataKinds.Email} rows for a single + {@link android.provider.ContactsContract.RawContacts} row. To facilitate this, the Contacts + Provider offers <strong>entity</strong> constructs, which act like database joins between + tables. +</p> +<p> + An entity is like a table composed of selected columns from a parent table and its child table. + When you query an entity, you supply a projection and search criteria based on the columns + available from the entity. The result is a {@link android.database.Cursor} that contains + contains one row for each child table row that was retrieved. For example, if you query + {@link android.provider.ContactsContract.Contacts.Entity} for a contact name + and all the {@link android.provider.ContactsContract.CommonDataKinds.Email} rows for all the + raw contacts for that name, you get back a {@link android.database.Cursor} containing one row + for each {@link android.provider.ContactsContract.CommonDataKinds.Email} row. +</p> +<p> + Entities simplify queries. Using an entity, you can retrieve all of the contacts data for a + contact or raw contact at once, instead of having to query the parent table first to get an + ID, and then having to query the child table with that ID. Also, the Contacts Provider processes + a query against an entity in a single transaction, which ensures that the retrieved data is + internally consistent. +</p> +<p class="note"> + <strong>Note:</strong> An entity usually doesn't contain all the columns of the parent and + child table. If you attempt to work with a column name that isn't in the list of column name + constants for the entity, you'll get an {@link java.lang.Exception}. +</p> +<p> + The following snippet shows how to retrieve all the raw contact rows for a contact. The snippet + is part of a larger application that has two activities, "main" and "detail". The main activity + shows a list of contact rows; when the user select one, the activity sends its ID to the detail + activity. The detail activity uses the {@link android.provider.ContactsContract.Contacts.Entity} + to display all of the data rows from all of the raw contacts associated with the selected + contact. +</p> +<p> + This snippet is taken from the "detail" activity: +</p> +<pre> +... + /* + * Appends the entity path to the URI. In the case of the Contacts Provider, the + * expected URI is content://com.google.contacts/#/entity (# is the ID value). + */ + mContactUri = Uri.withAppendedPath( + mContactUri, + ContactsContract.Contacts.Entity.CONTENT_DIRECTORY); + + // Initializes the loader identified by LOADER_ID. + getLoaderManager().initLoader( + LOADER_ID, // The identifier of the loader to initialize + null, // Arguments for the loader (in this case, none) + this); // The context of the activity + + // Creates a new cursor adapter to attach to the list view + mCursorAdapter = new SimpleCursorAdapter( + this, // the context of the activity + R.layout.detail_list_item, // the view item containing the detail widgets + mCursor, // the backing cursor + mFromColumns, // the columns in the cursor that provide the data + mToViews, // the views in the view item that display the data + 0); // flags + + // Sets the ListView's backing adapter. + mRawContactList.setAdapter(mCursorAdapter); +... +@Override +public Loader<Cursor> onCreateLoader(int id, Bundle args) { + + /* + * Sets the columns to retrieve. + * RAW_CONTACT_ID is included to identify the raw contact associated with the data row. + * DATA1 contains the first column in the data row (usually the most important one). + * MIMETYPE indicates the type of data in the data row. + */ + String[] projection = + { + ContactsContract.Contacts.Entity.RAW_CONTACT_ID, + ContactsContract.Contacts.Entity.DATA1, + ContactsContract.Contacts.Entity.MIMETYPE + }; + + /* + * Sorts the retrieved cursor by raw contact id, to keep all data rows for a single raw + * contact collated together. + */ + String sortOrder = + ContactsContract.Contacts.Entity.RAW_CONTACT_ID + + " ASC"; + + /* + * Returns a new CursorLoader. The arguments are similar to + * ContentResolver.query(), except for the Context argument, which supplies the location of + * the ContentResolver to use. + */ + return new CursorLoader( + getApplicationContext(), // The activity's context + mContactUri, // The entity content URI for a single contact + projection, // The columns to retrieve + null, // Retrieve all the raw contacts and their data rows. + null, // + sortOrder); // Sort by the raw contact ID. +} +</pre> +<p> + When the load is finished, {@link android.app.LoaderManager} invokes a callback to + {@link android.app.LoaderManager.LoaderCallbacks#onLoadFinished(Loader, D) + onLoadFinished()}. One of the incoming arguments to this method is a + {@link android.database.Cursor} with the results of the query. In your own app, you can get the + data from this {@link android.database.Cursor} to display it or work with it further. +</p> +<h3 id="Transactions">Batch modification</h3> +<p> + Whenever possible, you should insert, update, and delete data in the Contacts Provider in + "batch mode", by creating an {@link java.util.ArrayList} of + {@link android.content.ContentProviderOperation} objects and calling + {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}. Because + the Contacts Provider performs all of the operations in an + {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()} in a single + transaction, your modifications will never leave the contacts repository in an inconsistent + state. A batch modification also facilitates inserting a raw contact and its detail data at + the same time. +</p> +<p class="note"> + <strong>Note:</strong> To modify a <em>single</em> raw contact, consider sending an intent to + the device's contacts application rather than handling the modification in your app. + Doing this is described in more detail in the section + <a href="#Intents">Retrieval and modification with intents</a>. +</p> +<h4>Yield points</h4> +<p> + A batch modification containing a large number of operations can block other processes, + resulting in a bad overall user experience. To organize all the modifications you want to + perform in as few separate lists as possible, and at the same time prevent them from + blocking the system, you should set <strong>yield points</strong> for one or more operations. + A yield point is a {@link android.content.ContentProviderOperation} object that has its + {@link android.content.ContentProviderOperation#isYieldAllowed()} value set to + <code>true</code>. When the Contacts Provider encounters a yield point, it pauses its work to + let other processes run and closes the current transaction. When the provider starts again, it + continues with the next operation in the {@link java.util.ArrayList} and starts a new + transaction. +</p> +<p> + Yield points do result in more than one transaction per call to + {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}. Because of + this, you should set a yield point for the last operation for a set of related rows. + For example, you should set a yield point for the last operation in a set that adds a + raw contact rows and its associated data rows, or the last operation for a set of rows related + to a single contact. +</p> +<p> + Yield points are also a unit of atomic operation. All accesses between two yield points will + either succeed or fail as a single unit. If you don't set any yield points, the smallest + atomic operation is the entire batch of operations. If you do use yield points, you prevent + operations from degrading system performance, while at the same time ensuring that a subset of + operations is atomic. +</p> +<h4>Modification back references</h4> +<p> + When you're inserting a new raw contact row and its associated data rows as a set of + {@link android.content.ContentProviderOperation} objects, you have to link the data rows to + the raw contact row by inserting the raw contact's + {@link android.provider.BaseColumns#_ID} value as the + {@link android.provider.ContactsContract.DataColumns#RAW_CONTACT_ID} value. However, this + value isn't available when you're creating the {@link android.content.ContentProviderOperation} + for the data row, because you haven't yet applied the + {@link android.content.ContentProviderOperation} for the raw contact row. To work around this, + the {@link android.content.ContentProviderOperation.Builder} class has the method + {@link android.content.ContentProviderOperation.Builder#withValueBackReference(String, int) withValueBackReference()}. + This method allows you to insert or modify a column with the + result of a previous operation. +</p> +<p> + The {@link android.content.ContentProviderOperation.Builder#withValueBackReference(String, int) withValueBackReference()} + method has two arguments: +</p> + <dl> + <dt> + <code>key</code> + </dt> + <dd> + The key of a key-value pair. The value of this argument should be the name of a column + in the table that you're modifying. + </dd> + <dt> + <code>previousResult</code> + </dt> + <dd> + The 0-based index of a value in the array of + {@link android.content.ContentProviderResult} objects from + {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}. As + the batch operations are applied, the result of each operation is stored in an + intermediate array of results. The <code>previousResult</code> value is the index + of one of these results, which is retrieved and stored with the <code>key</code> + value. This allows you to insert a new raw contact record and get back its + {@link android.provider.BaseColumns#_ID} value, then make a "back reference" to the + value when you add a {@link android.provider.ContactsContract.Data} row. + <p> + The entire result array is created when you first call + {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}, + with a size equal to the size of the {@link java.util.ArrayList} of + {@link android.content.ContentProviderOperation} objects you provide. However, all + the elements in the result array are set to <code>null</code>, and if you try + to do a back reference to a result for an operation that hasn't yet been applied, +{@link android.content.ContentProviderOperation.Builder#withValueBackReference(String, int) withValueBackReference()} + throws an {@link java.lang.Exception}. + + </p> + </dd> + </dl> +<p> + The following snippets show how to insert a new raw contact and data in batch. They + includes code that establishes a yield point and uses a back reference. The snippets are an + expanded version of the <code>createContacEntry()</code> method, which is part of the + <code>ContactAdder</code> class in the + <code><a href="{@docRoot}resources/samples/ContactManager/index.html"> + Contact Manager</a></code> sample application. +</p> +<p> + The first snippet retrieves contact data from the UI. At this point, the user has already + selected the account for which the new raw contact should be added. +</p> +<pre> +// Creates a contact entry from the current UI values, using the currently-selected account. +protected void createContactEntry() { + /* + * Gets values from the UI + */ + String name = mContactNameEditText.getText().toString(); + String phone = mContactPhoneEditText.getText().toString(); + String email = mContactEmailEditText.getText().toString(); + + int phoneType = mContactPhoneTypes.get( + mContactPhoneTypeSpinner.getSelectedItemPosition()); + + int emailType = mContactEmailTypes.get( + mContactEmailTypeSpinner.getSelectedItemPosition()); +</pre> +<p> + The next snippet creates an operation to insert the raw contact row into the + {@link android.provider.ContactsContract.RawContacts} table: +</p> +<pre> + /* + * Prepares the batch operation for inserting a new raw contact and its data. Even if + * the Contacts Provider does not have any data for this person, you can't add a Contact, + * only a raw contact. The Contacts Provider will then add a Contact automatically. + */ + + // Creates a new array of ContentProviderOperation objects. + ArrayList<ContentProviderOperation> ops = + new ArrayList<ContentProviderOperation>(); + + /* + * Creates a new raw contact with its account type (server type) and account name + * (user's account). Remember that the display name is not stored in this row, but in a + * StructuredName data row. No other data is required. + */ + ContentProviderOperation.Builder op = + ContentProviderOperation.newInsert(ContactsContract.RawContacts.CONTENT_URI) + .withValue(ContactsContract.RawContacts.ACCOUNT_TYPE, mSelectedAccount.getType()) + .withValue(ContactsContract.RawContacts.ACCOUNT_NAME, mSelectedAccount.getName()); + + // Builds the operation and adds it to the array of operations + ops.add(op.build()); +</pre> +<p> + Next, the code creates data rows for the display name, phone, and email rows. +</p> +<p> + Each operation builder object uses + {@link android.content.ContentProviderOperation.Builder#withValueBackReference(String, int) withValueBackReference()} + to get the + {@link android.provider.ContactsContract.DataColumns#RAW_CONTACT_ID}. The reference points + back to the {@link android.content.ContentProviderResult} object from the first operation, + which adds the raw contact row and returns its new {@link android.provider.BaseColumns#_ID} + value. As a result, each data row is automatically linked by its + {@link android.provider.ContactsContract.DataColumns#RAW_CONTACT_ID} + to the new {@link android.provider.ContactsContract.RawContacts} row to which it belongs. +</p> +<p> + The {@link android.content.ContentProviderOperation.Builder} object that adds the email row is + flagged with {@link android.content.ContentProviderOperation.Builder#withYieldAllowed(boolean) + withYieldAllowed()}, which sets a yield point: +</p> +<pre> + // Creates the display name for the new raw contact, as a StructuredName data row. + op = + ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) + /* + * withValueBackReference sets the value of the first argument to the value of + * the ContentProviderResult indexed by the second argument. In this particular + * call, the raw contact ID column of the StructuredName data row is set to the + * value of the result returned by the first operation, which is the one that + * actually adds the raw contact row. + */ + .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) + + // Sets the data row's MIME type to StructuredName + .withValue(ContactsContract.Data.MIMETYPE, + ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE) + + // Sets the data row's display name to the name in the UI. + .withValue(ContactsContract.CommonDataKinds.StructuredName.DISPLAY_NAME, name); + + // Builds the operation and adds it to the array of operations + ops.add(op.build()); + + // Inserts the specified phone number and type as a Phone data row + op = + ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) + /* + * Sets the value of the raw contact id column to the new raw contact ID returned + * by the first operation in the batch. + */ + .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) + + // Sets the data row's MIME type to Phone + .withValue(ContactsContract.Data.MIMETYPE, + ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE) + + // Sets the phone number and type + .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER, phone) + .withValue(ContactsContract.CommonDataKinds.Phone.TYPE, phoneType); + + // Builds the operation and adds it to the array of operations + ops.add(op.build()); + + // Inserts the specified email and type as a Phone data row + op = + ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) + /* + * Sets the value of the raw contact id column to the new raw contact ID returned + * by the first operation in the batch. + */ + .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) + + // Sets the data row's MIME type to Email + .withValue(ContactsContract.Data.MIMETYPE, + ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE) + + // Sets the email address and type + .withValue(ContactsContract.CommonDataKinds.Email.ADDRESS, email) + .withValue(ContactsContract.CommonDataKinds.Email.TYPE, emailType); + + /* + * Demonstrates a yield point. At the end of this insert, the batch operation's thread + * will yield priority to other threads. Use after every set of operations that affect a + * single contact, to avoid degrading performance. + */ + op.withYieldAllowed(true); + + // Builds the operation and adds it to the array of operations + ops.add(op.build()); +</pre> +<p> + The last snippet shows the call to + {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()} that + inserts the new raw contact and data rows. +</p> +<pre> + // Ask the Contacts Provider to create a new contact + Log.d(TAG,"Selected account: " + mSelectedAccount.getName() + " (" + + mSelectedAccount.getType() + ")"); + Log.d(TAG,"Creating contact: " + name); + + /* + * Applies the array of ContentProviderOperation objects in batch. The results are + * discarded. + */ + try { + + getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops); + } catch (Exception e) { + + // Display a warning + Context ctx = getApplicationContext(); + + CharSequence txt = getString(R.string.contactCreationFailure); + int duration = Toast.LENGTH_SHORT; + Toast toast = Toast.makeText(ctx, txt, duration); + toast.show(); + + // Log exception + Log.e(TAG, "Exception encountered while inserting contact: " + e); + } +} +</pre> +<p> + Batch operations also allow you to implement <strong>optimistic concurrency control</strong>, + a method of applying modification transactions without having to lock the underlying repository. + To use this method, you apply the transaction and then check for other modifications that + may have been made at the same time. If you find an inconsistent modification has occurred, you + roll back your transaction and retry it. +</p> +<p> + Optimistic concurrency control is useful for a mobile device, where there's only one user at + a time, and simultaneous accesses to a data repository are rare. Because locking isn't used, + no time is wasted on setting locks or waiting for other transactions to release their locks. +</p> +<p> + To use optimistic concurrency control while updating a single + {@link android.provider.ContactsContract.RawContacts} row, follow these steps: +</p> +<ol> + <li> + Retrieve the raw contact's {@link android.provider.ContactsContract.SyncColumns#VERSION} + column along with the other data you retrieve. + </li> + <li> + Create a {@link android.content.ContentProviderOperation.Builder} object suitable for + enforcing a constraint, using the method + {@link android.content.ContentProviderOperation#newAssertQuery(Uri)}. For the content URI, + use {@link android.provider.ContactsContract.RawContacts#CONTENT_URI + RawContacts.CONTENT_URI} + with the raw contact's {@link android.provider.BaseColumns#_ID} appended to it. + </li> + <li> + For the {@link android.content.ContentProviderOperation.Builder} object, call + {@link android.content.ContentProviderOperation.Builder#withValue(String, Object) + withValue()} to compare the {@link android.provider.ContactsContract.SyncColumns#VERSION} + column to the version number you just retrieved. + </li> + <li> + For the same {@link android.content.ContentProviderOperation.Builder}, call + {@link android.content.ContentProviderOperation.Builder#withExpectedCount(int) + withExpectedCount()} to ensure that only one row is tested by this assertion. + </li> + <li> + Call {@link android.content.ContentProviderOperation.Builder#build()} to create the + {@link android.content.ContentProviderOperation} object, then add this object as the + first object in the {@link java.util.ArrayList} that you pass to + {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}. + </li> + <li> + Apply the batch transaction. + </li> +</ol> +<p> + If the raw contact row is updated by another operation between the time you read the row and + the time you attempt to modify it, the "assert" {@link android.content.ContentProviderOperation} + will fail, and the entire batch of operations will be backed out. You can then choose to retry + the batch or take some other action. +</p> +<p> + The following snippet demonstrates how to create an "assert" + {@link android.content.ContentProviderOperation} after querying for a single raw contact using + a {@link android.content.CursorLoader}: +</p> +<pre> +/* + * The application uses CursorLoader to query the raw contacts table. The system calls this method + * when the load is finished. + */ +public void onLoadFinished(Loader<Cursor> loader, Cursor cursor) { + + // Gets the raw contact's _ID and VERSION values + mRawContactID = cursor.getLong(cursor.getColumnIndex(BaseColumns._ID)); + mVersion = cursor.getInt(cursor.getColumnIndex(SyncColumns.VERSION)); +} + +... + +// Sets up a Uri for the assert operation +Uri rawContactUri = ContentUris.withAppendedId(RawContacts.CONTENT_URI, mRawContactID); + +// Creates a builder for the assert operation +ContentProviderOperation.Builder assertOp = ContentProviderOperation.netAssertQuery(rawContactUri); + +// Adds the assertions to the assert operation: checks the version and count of rows tested +assertOp.withValue(SyncColumns.VERSION, mVersion); +assertOp.withExpectedCount(1); + +// Creates an ArrayList to hold the ContentProviderOperation objects +ArrayList ops = new ArrayList<ContentProviderOperationg>; + +ops.add(assertOp.build()); + +// You would add the rest of your batch operations to "ops" here + +... + +// Applies the batch. If the assert fails, an Exception is thrown +try + { + ContentProviderResult[] results = + getContentResolver().applyBatch(AUTHORITY, ops); + + } catch (OperationApplicationException e) { + + // Actions you want to take if the assert operation fails go here + } +</pre> +<h3 id="Intents">Retrieval and modification with intents</h3> +<p> + Sending an intent to the device's contacts application allows you to access the Contacts + Provider indirectly. The intent starts the device's contacts application UI, in which users can + do contacts-related work. With this type of access, users can: + <ul> + <li>Pick a contact from a list and have it returned to your app for further work.</li> + <li>Edit an existing contact's data.</li> + <li>Insert a new raw contact for any of their accounts.</li> + <li>Delete a contact or contacts data.</li> + </ul> +<p> + If the user is inserting or updating data, you can collect the data first and send it as + part of the intent. +</p> +<p> + When you use intents to access the Contacts Provider via the device's contacts application, you + don't have to write your own UI or code for accessing the provider. You also don't have to + request permission to read or write to the provider. The device's contacts application can + delegate read permission for a contact to you, and because you're making modifications to the + provider through another application, you don't have to have write permissions. +</p> +<p> + The general process of sending an intent to access a provider is described in detail in the + <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Content Provider Basics</a> guide in the section "Data access via intents." The action, + MIME type, and data values you use for the available tasks are summarized in Table 4, while the + extras values you can use with + {@link android.content.Intent#putExtra(String, String) putExtra()} are listed in the + reference documentation for {@link android.provider.ContactsContract.Intents.Insert}: +</p> +<p class="table-caption" id="table4"> + <strong>Table 4.</strong> Contacts Provider Intents. +</p> +<table style="width:75%"> + <tr> + <th scope="col" style="width:10%">Task</th> + <th scope="col" style="width:5%">Action</th> + <th scope="col" style="width:10%">Data</th> + <th scope="col" style="width:10%">MIME type</th> + <th scope="col" style="width:25%">Notes</th> + </tr> + <tr> + <td><strong>Pick a contact from a list</strong></td> + <td>{@link android.content.Intent#ACTION_PICK}</td> + <td> + One of: + <ul> + <li> +{@link android.provider.ContactsContract.Contacts#CONTENT_URI Contacts.CONTENT_URI}, + which displays a list of contacts. + </li> + <li> +{@link android.provider.ContactsContract.CommonDataKinds.Phone#CONTENT_URI Phone.CONTENT_URI}, + which displays a list of phone numbers for a raw contact. + </li> + <li> +{@link android.provider.ContactsContract.CommonDataKinds.StructuredPostal#CONTENT_URI +StructuredPostal.CONTENT_URI}, + which displays a list of postal addresses for a raw contact. + </li> + <li> +{@link android.provider.ContactsContract.CommonDataKinds.Email#CONTENT_URI Email.CONTENT_URI}, + which displays a list of email addresses for a raw contact. + </li> + </ul> + </td> + <td> + Not used + </td> + <td> + Displays a list of raw contacts or a list of data from a raw contact, depending on the + content URI type you supply. + <p> + Call + {@link android.app.Activity#startActivityForResult(Intent, int) startActivityForResult()}, + which returns the content URI of the selected row. The form of the URI is the + table's content URI with the row's <code>LOOKUP_ID</code> appended to it. + The device's contacts app delegates read and write permissions to this content URI + for the life of your activity. See the + <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Content Provider Basics</a> guide for more details. + </p> + </td> + </tr> + <tr> + <td><strong>Insert a new raw contact</strong></td> + <td>{@link android.provider.ContactsContract.Intents.Insert#ACTION Insert.ACTION}</td> + <td>N/A</td> + <td> + {@link android.provider.ContactsContract.RawContacts#CONTENT_TYPE + RawContacts.CONTENT_TYPE}, MIME type for a set of raw contacts. + </td> + <td> + Displays the device's contacts application's <strong>Add Contact</strong> screen. The + extras values you add to the intent are displayed. If sent with + {@link android.app.Activity#startActivityForResult(Intent, int) startActivityForResult()}, + the content URI of the newly-added raw contact is passed back to your activity's + {@link android.app.Activity#onActivityResult(int, int, Intent) onActivityResult()} + callback method in the {@link android.content.Intent} argument, in the + "data" field. To get the value, call {@link android.content.Intent#getData()}. + </td> + </tr> + <tr> + <td><strong>Edit a contact</strong></td> + <td>{@link android.content.Intent#ACTION_EDIT}</td> + <td> + {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI} for + the contact. The editor activity will allow the user to edit any of the data associated + with this contact. + </td> + <td> + {@link android.provider.ContactsContract.Contacts#CONTENT_ITEM_TYPE + Contacts.CONTENT_ITEM_TYPE}, a single contact.</td> + <td> + Displays the Edit Contact screen in the contacts application. The extras values you add + to the intent are displayed. When the user clicks <strong>Done</strong> to save the + edits, your activity returns to the foreground. + </td> + </tr> + <tr> + <td><strong>Display a picker that can also add data.</strong></td> + <td>{@link android.content.Intent#ACTION_INSERT_OR_EDIT}</td> + <td> + N/A + </td> + <td> + {@link android.provider.ContactsContract.Contacts#CONTENT_ITEM_TYPE} + </td> + <td> + This intent always displays the contacts app's picker screen. The user can either + pick a contact to edit, or add a new contact. Either the edit or the add screen + appears, depending on the user's choice, and the extras data you pass in the intent + is displayed. If your app displays contact data such as an email or phone number, use + this intent to allow the user to add the data to an existing contact. + contact, + <p class="note"> + <strong>Note:</strong> There's no need to send a name value in this intent's extras, + because the user always picks an existing name or adds a new one. Moreover, + if you send a name, and the user chooses to do an edit, the contacts app will + display the name you send, overwriting the previous value. If the user doesn't + notice this and saves the edit, the old value is lost. + </p> + </td> + </tr> +</table> +<p> + The device's contacts app doesn't allow you to delete a raw contact or any of its data with an + intent. Instead, to delete a raw contact, use + {@link android.content.ContentResolver#delete(Uri, String, String[]) ContentResolver.delete()} + or {@link android.content.ContentProviderOperation#newDelete(Uri) + ContentProviderOperation.newDelete()}. +</p> +<p> + The following snippet shows how to construct and send an intent that inserts a new raw + contact and data: +</p> +<pre> +// Gets values from the UI +String name = mContactNameEditText.getText().toString(); +String phone = mContactPhoneEditText.getText().toString(); +String email = mContactEmailEditText.getText().toString(); + +String company = mCompanyName.getText().toString(); +String jobtitle = mJobTitle.getText().toString(); + +// Creates a new intent for sending to the device's contacts application +Intent insertIntent = new Intent(ContactsContract.Intents.Insert.ACTION); + +// Sets the MIME type to the one expected by the insertion activity +insertIntent.setType(ContactsContract.RawContacts.CONTENT_TYPE); + +// Sets the new contact name +insertIntent.putExtra(ContactsContract.Intents.Insert.NAME, name); + +// Sets the new company and job title +insertIntent.putExtra(ContactsContract.Intents.Insert.COMPANY, company); +insertIntent.putExtra(ContactsContract.Intents.Insert.JOB_TITLE, jobtitle); + +/* + * Demonstrates adding data rows as an array list associated with the DATA key + */ + +// Defines an array list to contain the ContentValues objects for each row +ArrayList<ContentValues> contactData = new ArrayList<ContentValues>(); + + +/* + * Defines the raw contact row + */ + +// Sets up the row as a ContentValues object +ContentValues rawContactRow = new ContentValues(); + +// Adds the account type and name to the row +rawContactRow.put(ContactsContract.RawContacts.ACCOUNT_TYPE, mSelectedAccount.getType()); +rawContactRow.put(ContactsContract.RawContacts.ACCOUNT_NAME, mSelectedAccount.getName()); + +// Adds the row to the array +contactData.add(rawContactRow); + +/* + * Sets up the phone number data row + */ + +// Sets up the row as a ContentValues object +ContentValues phoneRow = new ContentValues(); + +// Specifies the MIME type for this data row (all data rows must be marked by their type) +phoneRow.put( + ContactsContract.Data.MIMETYPE, + ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE +); + +// Adds the phone number and its type to the row +phoneRow.put(ContactsContract.CommonDataKinds.Phone.NUMBER, phone); + +// Adds the row to the array +contactData.add(phoneRow); + +/* + * Sets up the email data row + */ + +// Sets up the row as a ContentValues object +ContentValues emailRow = new ContentValues(); + +// Specifies the MIME type for this data row (all data rows must be marked by their type) +emailRow.put( + ContactsContract.Data.MIMETYPE, + ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE +); + +// Adds the email address and its type to the row +emailRow.put(ContactsContract.CommonDataKinds.Email.ADDRESS, email); + +// Adds the row to the array +contactData.add(emailRow); + +/* + * Adds the array to the intent's extras. It must be a parcelable object in order to + * travel between processes. The device's contacts app expects its key to be + * Intents.Insert.DATA + */ +insertIntent.putParcelableArrayListExtra(ContactsContract.Intents.Insert.DATA, contactData); + +// Send out the intent to start the device's contacts app in its add contact activity. +startActivity(insertIntent); +</pre> +<h3 id="DataIntegrity">Data integrity</h3> +<p> + Because the contacts repository contains important and sensitive data that users expect to be + correct and up-to-date, the Contacts Provider has well-defined rules for data integrity. It's + your responsibility to conform to these rules when you modify contacts data. The important + rules are listed here: +</p> +<dl> + <dt> + Always add a {@link android.provider.ContactsContract.CommonDataKinds.StructuredName} row + for every {@link android.provider.ContactsContract.RawContacts} row you add. + </dt> + <dd> + A {@link android.provider.ContactsContract.RawContacts} row without a + {@link android.provider.ContactsContract.CommonDataKinds.StructuredName} row in the + {@link android.provider.ContactsContract.Data} table may cause problems during + aggregation. + </dd> + <dt> + Always link new {@link android.provider.ContactsContract.Data} rows to their parent + {@link android.provider.ContactsContract.RawContacts} row. + </dt> + <dd> + A {@link android.provider.ContactsContract.Data} row that isn't linked to a + {@link android.provider.ContactsContract.RawContacts} won't be visible in the device's + contacts application, and it might cause problems with sync adapters. + </dd> + <dt> + Change data only for those raw contacts that you own. + </dt> + <dd> + Remember that the Contacts Provider is usually managing data from several different + account types/online services. You need to ensure that your application only modifies + or deletes data for rows that belong to you, and that it only inserts data with an + account type and name that you control. + </dd> + <dt> + Always use the constants defined in {@link android.provider.ContactsContract} and its + subclasses for authorities, content URIs, URI paths, column names, MIME types, and + {@link android.provider.ContactsContract.CommonDataKinds.CommonColumns#TYPE} values. + </dt> + <dd> + Using these constants helps you to avoid errors. You'll also be notified with compiler + warnings if any of the constants is deprecated. + </dd> +</dl> +<h3 id="CustomData">Custom data rows</h3> +<p> + By creating and using your own custom MIME types, you can insert, edit, delete, and retrieve + your own data rows in the {@link android.provider.ContactsContract.Data} table. Your rows + are limited to using the column defined in + {@link android.provider.ContactsContract.DataColumns}, although you can map your own + type-specific column names to the default column names. In the device's contacts application, + the data for your rows is displayed but can't be edited or deleted, and users can't add + additional data. To allow users to modify your custom data rows, you must provide an editor + activity in your own application. +</p> +<p> + To display your custom data, provide a <code>contacts.xml</code> file containing a + <code><ContactsAccountType></code> element and one or more of its + <code><ContactsDataKind></code> child elements. This is described in more detail in the + section <a href="#SocialStreamDataKind"><code><ContactsDataKind> element</code></a>. +</p> +<p> + To learn more about custom MIME types, read the + <a href="{@docRoot}guide/topics/providers/content-provider-creating.html"> + Creating a Content Provider</a> guide. +</p> +<h2 id="SyncAdapters">Contacts Provider Sync Adapters</h2> +<p> + The Contacts Provider is specifically designed for handling <strong>synchronization</strong> + of contacts data between a device and an online service. This allows users to download + existing data to a new device and upload existing data to a new account. + Synchronization also ensures that users have the latest data at hand, regardless + of the source of additions and changes. Another advantage of synchronization is that it makes + contacts data available even when the device is not connected to the network. +</p> +<p> + Although you can implement synchronization in a variety of ways, the Android system provides + a plug-in synchronization framework that automates the following tasks: + <ul> + + <li> + Checking network availability. + </li> + <li> + Scheduling and executing synchronization, based on user preferences. + </li> + <li> + Restarting synchronizations that have stopped. + </li> + </ul> +<p> + To use this framework, you supply a sync adapter plug-in. Each sync adapter is unique to a + service and content provider, but can handle multiple account names for the same service. The + framework also allows multiple sync adapters for the same service and provider. +</p> +<h3 id="SyncClassesFiles">Sync adapter classes and files</h3> +<p> + You implement a sync adapter as a subclass of + {@link android.content.AbstractThreadedSyncAdapter} and install it as part of an Android + application. The system learns about the sync adapter from elements in your application + manifest, and from a special XML file pointed to by the manifest. The XML file defines the + account type for the online service and the authority for the content provider, which together + uniquely identify the adapter. The sync adapter does not become active until the user adds an + account for the sync adapter's account type and enables synchronization for the content + provider the sync adapter syncs with. At that point, the system starts managing the adapter, + calling it as necessary to synchronize between the content provider and the server. +</p> +<p class="note"> + <strong>Note:</strong> Using an account type as part of the sync adapter's identification allows + the system to detect and group together sync adapters that access different services from the + same organization. For example, sync adapters for Google online services all have the same + account type <code>com.google</code>. When users add a Google account to their devices, all + of the installed sync adapters for Google services are listed together; each sync adapter + listed syncs with a different content provider on the device. +</p> +<p> + Because most services require users to verify their identity before accessing + data, the Android system offers an authentication framework that is similar to, and often + used in conjunction with, the sync adapter framework. The authentication framework uses + plug-in authenticators that are subclasses of + {@link android.accounts.AbstractAccountAuthenticator}. An authenticator verifies + the user's identity in the following steps: + <ol> + <li> + Collects the user's name, password or similar information (the user's + <strong>credentials</strong>). + </li> + <li> + Sends the credentials to the service + </li> + <li> + Examines the service's reply. + </li> + </ol> +<p> + If the service accepts the credentials, the authenticator can + store the credentials for later use. Because of the plug-in authenticator framework, the + {@link android.accounts.AccountManager} can provide access to any authtokens an authenticator + supports and chooses to expose, such as OAuth2 authtokens. +</p> +<p> + Although authentication is not required, most contacts services use it. + However, you're not required to use the Android authentication framework to do authentication. +</p> +<h3 id="SyncAdapterImplementing">Sync adapter implementation</h3> +<p> + To implement a sync adapter for the Contacts Provider, you start by creating an + Android application that contains the following: +</p> + <dl> + <dt> + A {@link android.app.Service} component that responds to requests from the system to + bind to the sync adapter. + </dt> + <dd> + When the system wants to run a synchronization, it calls the service's + {@link android.app.Service#onBind(Intent) onBind()} method to get an + {@link android.os.IBinder} for the sync adapter. This allows the system to do + cross-process calls to the adapter's methods. + <p> + In the <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> + Sample Sync Adapter</a> sample app, the class name of this service is + <code>com.example.android.samplesync.syncadapter.SyncService</code>. + </p> + </dd> + <dt> + The actual sync adapter, implemented as a concrete subclass of + {@link android.content.AbstractThreadedSyncAdapter}. + </dt> + <dd> + This class does the work of downloading data from the server, uploading data from the + device, and resolving conflicts. The main work of the adapter is + done in the method {@link android.content.AbstractThreadedSyncAdapter#onPerformSync( + Account, Bundle, String, ContentProviderClient, SyncResult) + onPerformSync()}. This class must be instantiated as a singleton. + <p> + In the <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> + Sample Sync Adapter</a> sample app, the sync adapter is defined in the class + <code>com.example.android.samplesync.syncadapter.SyncAdapter</code>. + </p> + </dd> + <dt> + A subclass of {@link android.app.Application}. + </dt> + <dd> + This class acts as a factory for the sync adapter singleton. Use the + {@link android.app.Application#onCreate()} method to instantiate the sync adapter, and + provide a static "getter" method to return the singleton to the + {@link android.app.Service#onBind(Intent) onBind()} method of the sync adapter's + service. + </dd> + <dt> + <strong>Optional:</strong> A {@link android.app.Service} component that responds to + requests from the system for user authentication. + </dt> + <dd> + {@link android.accounts.AccountManager} starts this service to begin the authentication + process. The service's {@link android.app.Service#onCreate()} method instantiates an + authenticator object. When the system wants to authenticate a user account for the + application's sync adapter, it calls the service's + {@link android.app.Service#onBind(Intent) onBind()} method to get an + {@link android.os.IBinder} for the authenticator. This allows the system to do + cross-process calls to the authenticator's methods.. + <p> + In the <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> + Sample Sync Adapter</a> sample app, the class name of this service is + <code>com.example.android.samplesync.authenticator.AuthenticationService</code>. + </p> + </dd> + <dt> + <strong>Optional:</strong> A concrete subclass of + {@link android.accounts.AbstractAccountAuthenticator} that handles requests for + authentication. + </dt> + <dd> + This class provides methods that the {@link android.accounts.AccountManager} invokes + to authenticate the user's credentials with the server. The details of the + authentication process vary widely, based on the server technology in use. You should + refer to the documentation for your server software to learn more about authentication. + <p> + In the <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> + Sample Sync Adapter</a> sample app, the authenticator is defined in the class + <code>com.example.android.samplesync.authenticator.Authenticator</code>. + </p> + </dd> + <dt> + XML files that define the sync adapter and authenticator to the system. + </dt> + <dd> + The sync adapter and authenticator service components described previously are + defined in +<code><<a href="{@docRoot}guide/topics/manifest/service-element.html">service</a>></code> + elements in the application manifest. These elements + contain +<code><<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">meta-data</a>></code> +child elements that provide specific data to the + system: + <ul> + <li> + The +<code><<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">meta-data</a>></code> + element for the sync adapter service points to the + XML file <code>res/xml/syncadapter.xml</code>. In turn, this file specifies + a URI for the web service that will be synchronized with the Contacts Provider, + and an account type for the web service. + </li> + <li> + <strong>Optional:</strong> The +<code><<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">meta-data</a>></code> + element for the authenticator points to the XML file + <code>res/xml/authenticator.xml</code>. In turn, this file specifies the + account type that this authenticator supports, as well as UI resources that + appear during the authentication process. The account type specified in this + element must be the same as the account type specified for the sync + adapter. + </li> + </ul> + </dd> + </dl> +<h2 id="SocialStream">Social Stream Data</h2> +<p> + The {@link android.provider.ContactsContract.StreamItems} and + {@link android.provider.ContactsContract.StreamItemPhotos} tables + manage incoming data from social networks. You can write a sync adapter that adds stream data + from your own network to these tables, or you can read stream data from these tables and + display it in your own application, or both. With these features, your social networking + services and applications can be integrated into Android's social networking experience. +</p> +<h3 id="StreamText">Social stream text</h3> +<p> + Stream items are always associated with a raw contact. The + {@link android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID} links to the + <code>_ID</code> value for the raw contact. The account type and account name of the raw + contact are also stored in the stream item row. +</p> +<p> + Store the data from your stream in the following columns: +</p> +<dl> + <dt> + {@link android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_TYPE} + </dt> + <dd> + <strong>Required.</strong> The user's account type for the raw contact associated with this + stream item. Remember to set this value when you insert a stream item. + </dd> + <dt> + {@link android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_NAME} + </dt> + <dd> + <strong>Required.</strong> The user's account name for the raw contact associated with this + stream item. Remember to set this value when you insert a stream item. + </dd> + <dt> + Identifier columns + </dt> + <dd> + <strong>Required.</strong> You must insert the following identifier columns when you + insert a stream item: + <ul> + <li> + {@link android.provider.ContactsContract.StreamItemsColumns#CONTACT_ID}: The + {@link android.provider.BaseColumns#_ID} value of the contact that this stream + item is associated with. + </li> + <li> + {@link android.provider.ContactsContract.StreamItemsColumns#CONTACT_LOOKUP_KEY}: The + {@link android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY} value of the + contact this stream item is associated with. + </li> + <li> + {@link android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID}: The + {@link android.provider.BaseColumns#_ID} value of the raw contact that this stream + item is associated with. + </li> + </ul> + </dd> + <dt> + {@link android.provider.ContactsContract.StreamItemsColumns#COMMENTS} + </dt> + <dd> + Optional. Stores summary information that you can display at the beginning of a stream item. + </dd> + <dt> + {@link android.provider.ContactsContract.StreamItemsColumns#TEXT} + </dt> + <dd> + The text of the stream item, either the content that was posted by the source of the item, + or a description of some action that generated the stream item. This column can contain + any formatting and embedded resource images that can be rendered by + {@link android.text.Html#fromHtml(String) fromHtml()}. The provider may truncate or + ellipsize long content, but it will try to avoid breaking tags. + </dd> + <dt> + {@link android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP} + </dt> + <dd> + A text string containing the time the stream item was inserted or updated, in the form + of <em>milliseconds</em> since epoch. Applications that insert or update stream items are + responsible for maintaining this column; it is not automatically maintained by the + Contacts Provider. + </dd> +</dl> +<p> + To display identifying information for your stream items, use the + {@link android.provider.ContactsContract.StreamItemsColumns#RES_ICON}, + {@link android.provider.ContactsContract.StreamItemsColumns#RES_LABEL}, and + {@link android.provider.ContactsContract.StreamItemsColumns#RES_PACKAGE} to link to resources + in your application. +</p> +<p> + The {@link android.provider.ContactsContract.StreamItems} table also contains the columns + {@link android.provider.ContactsContract.StreamItemsColumns#SYNC1} through + {@link android.provider.ContactsContract.StreamItemsColumns#SYNC4} for the exclusive use of + sync adapters. +</p> +<h3 id="StreamPhotos">Social stream photos</h3> +<p> + The {@link android.provider.ContactsContract.StreamItemPhotos} table stores photos associated + with a stream item. The table's + {@link android.provider.ContactsContract.StreamItemPhotosColumns#STREAM_ITEM_ID} column + links to values in the {@link android.provider.BaseColumns#_ID} column of + {@link android.provider.ContactsContract.StreamItems} table. Photo references are stored in the + table in these columns: +</p> +<dl> + <dt> + {@link android.provider.ContactsContract.StreamItemPhotos#PHOTO} column (a BLOB). + </dt> + <dd> + A binary representation of the photo, resized by the provider for storage and display. + This column is available for backwards compatibility with previous versions of the Contacts + Provider that used it for storing photos. However, in the current version + you should not use this column to store photos. Instead, use + either {@link android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID} or + {@link android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI} (both of + which are described in the following points) to store photos in a file. This column now + contains a thumbnail of the photo, which is available for reading. + </dd> + <dt> + {@link android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID} + </dt> + <dd> + A numeric identifier of a photo for a raw contact. Append this value to the constant + {@link android.provider.ContactsContract.DisplayPhoto#CONTENT_URI DisplayPhoto.CONTENT_URI} + to get a content URI pointing to a single photo file, and then call + {@link android.content.ContentResolver#openAssetFileDescriptor(Uri, String) + openAssetFileDescriptor()} to get a handle to the photo file. + </dd> + <dt> + {@link android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI} + </dt> + <dd> + A content URI pointing directly to the photo file for the photo represented by this row. + Call {@link android.content.ContentResolver#openAssetFileDescriptor(Uri, String) + openAssetFileDescriptor()} with this URI to get a handle to the photo file. + </dd> +</dl> +<h3 id="SocialStreamTables">Using the social stream tables</h3> +<p> + These tables work the same as the other main tables in the Contacts Provider, except that: +</p> + <ul> + <li> + These tables require additional access permissions. To read from them, your application + must have the permission {@link android.Manifest.permission#READ_SOCIAL_STREAM}. To + modify them, your application must have the permission + {@link android.Manifest.permission#WRITE_SOCIAL_STREAM}. + </li> + <li> + For the {@link android.provider.ContactsContract.StreamItems} table, the number of rows + stored for each raw contact is limited. Once this limit is reached, + the Contacts Provider makes space for new stream item rows by automatically deleting + the rows having the oldest + {@link android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP}. To get the + limit, issue a query to the content URI + {@link android.provider.ContactsContract.StreamItems#CONTENT_LIMIT_URI}. You can leave + all the arguments other than the content URI set to <code>null</code>. The query + returns a Cursor containing a single row, with the single column + {@link android.provider.ContactsContract.StreamItems#MAX_ITEMS}. + </li> + </ul> + +<p> + The class {@link android.provider.ContactsContract.StreamItems.StreamItemPhotos} defines a + sub-table of {@link android.provider.ContactsContract.StreamItemPhotos} containing the photo + rows for a single stream item. +</p> +<h3 id="SocialStreamInteraction">Social stream interactions</h3> +<p> + The social stream data managed by the Contacts Provider, in conjunction with the + device's contacts application, offers a powerful way to connect your social networking system + with existing contacts. The following features are available: +</p> + <ul> + <li> + By syncing your social networking service to the Contacts Provider with a sync + adapter, you can retrieve recent activity for a user's contacts and store it in + the {@link android.provider.ContactsContract.StreamItems} and + {@link android.provider.ContactsContract.StreamItemPhotos} tables for later use. + </li> + <li> + Besides regular synchronization, you can trigger your sync adapter to retrieve + additional data when the user selects a contact to view. This allows your sync adapter + to retrieve high-resolution photos and the most recent stream items for the contact. + </li> + <li> + By registering a notification with the device's contacts application and the Contacts + Provider, you can <em>receive</em> an intent when a contact is viewed, and at that point + update the contact's status from your service. This approach may be faster and use less + bandwidth than doing a full sync with a sync adapter. + </li> + <li> + Users can add a contact to your social networking service while looking at the contact + in the device's contacts application. You enable this with the "invite contact" feature, + which you enable with a combination of an activity that adds an existing contact to your + network, and an XML file that provides the device's contacts application and the + Contacts Provider with the details of your application. + </li> + </ul> +<p> + Regular synchronization of stream items with the Contacts Provider is the same as + other synchronizations. To learn more about synchronization, see the section + <a href="#SyncAdapters">Contacts Provider Sync Adapters</a>. Registering notifications and + inviting contacts are covered in the next two sections. +</p> +<h4>Registering to handle social networking views</h4> +<p> + To register your sync adapter to receive notifications when the user views a contact that's + managed by your sync adapter: +</p> +<ol> + <li> + Create a file named <code>contacts.xml</code> in your project's <code>res/xml/</code> + directory. If you already have this file, you can skip this step. + </li> + <li> + In this file, add the element +<code><ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"></code>. + If this element already exists, you can skip this step. + </li> + <li> + To register a service that is notified when the user opens a contact's detail page in + the device's contacts application, add the attribute + <code>viewContactNotifyService="<em>serviceclass</em>"</code> to the element, where + <code><em>serviceclass</em></code> is the fully-qualified classname of the service + that should receive the intent from the device's contacts application. For the notifier + service, use a class that extends {@link android.app.IntentService}, to allow the service to + receive intents. The data in the incoming intent contains the content URI of the raw + contact the user clicked. From the notifier service, you can bind to and then call your + sync adapter to update the data for the raw contact. + </li> +</ol> +<p> + To register an activity to be called when the user clicks on a stream item or photo or both: +</p> +<ol> + <li> + Create a file named <code>contacts.xml</code> in your project's <code>res/xml/</code> + directory. If you already have this file, you can skip this step. + </li> + <li> + In this file, add the element +<code><ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"></code>. + If this element already exists, you can skip this step. + </li> + <li> + To register one of your activities to handle the user clicking on a stream item in the + device's contacts application, add the attribute + <code>viewStreamItemActivity="<em>activityclass</em>"</code> to the element, where + <code><em>activityclass</em></code> is the fully-qualified classname of the activity + that should receive the intent from the device's contacts application. + </li> + <li> + To register one of your activities to handle the user clicking on a stream photo in the + device's contacts application, add the attribute + <code>viewStreamItemPhotoActivity="<em>activityclass</em>"</code> to the element, where + <code><em>activityclass</em></code> is the fully-qualified classname of the activity + that should receive the intent from the device's contacts application. + </li> +</ol> +<p> + The <code><ContactsAccountType></code> element is described in more detail in the + section <a href="#SocialStreamAcctType"><ContactsAccountType> element</a>. +</p> +<p> + The incoming intent contains the content URI of the item or photo that the user clicked. + To have separate activities for text items and for photos, use both attributes in the same file. +</p> +<h4>Interacting with your social networking service</h4> +<p> + Users don't have to leave the device's contacts application to invite a contact to your social + networking site. Instead, you can have the device's contacts app send an intent for inviting the + contact to one of your activities. To set this up: +</p> +<ol> + <li> + Create a file named <code>contacts.xml</code> in your project's <code>res/xml/</code> + directory. If you already have this file, you can skip this step. + </li> + <li> + In this file, add the element +<code><ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"></code>. + If this element already exists, you can skip this step. + </li> + <li> + Add the following attributes: + <ul> + <li><code>inviteContactActivity="<em>activityclass</em>"</code></li> + <li> + <code>inviteContactActionLabel="@string/<em>invite_action_label</em>"</code> + </li> + </ul> + The <code><em>activityclass</em></code> value is the fully-qualified classname of the + activity that should receive the intent. The <code><em>invite_action_label</em></code> + value is a text string that's displayed in the <strong>Add Connection</strong> menu in the + device's contacts application. + </li> +</ol> +<p class="note"> + <strong>Note:</strong> <code>ContactsSource</code> is a deprecated tag name for + <code>ContactsAccountType</code>. +</p> +<h3 id="ContactsFile">contacts.xml reference</h3> +<p> + The file <code>contacts.xml</code> contains XML elements that control the interaction of your + sync adapter and application with the contacts application and the Contacts Provider. These + elements are described in the following sections. +</p> +<h4 id="SocialStreamAcctType"><ContactsAccountType> element</h4> +<p> + The <code><ContactsAccountType></code> element controls the interaction of your + application with the contacts application. It has the following syntax: +</p> +<pre> +<ContactsAccountType + xmlns:android="http://schemas.android.com/apk/res/android" + inviteContactActivity="<em>activity_name</em>" + inviteContactActionLabel="<em>invite_command_text</em>" + viewContactNotifyService="<em>view_notify_service</em>" + viewGroupActivity="<em>group_view_activity</em>" + viewGroupActionLabel="<em>group_action_text</em>" + viewStreamItemActivity="<em>viewstream_activity_name</em>" + viewStreamItemPhotoActivity="<em>viewphotostream_activity_name</em>"> +</pre> +<p> + <strong>contained in:</strong> +</p> +<p> + <code>res/xml/contacts.xml</code> +</p> +<p> + <strong>can contain:</strong> +</p> +<p> + <strong><code><ContactsDataKind></code></strong> +</p> +<p> + <strong>Description:</strong> +</p> +<p> + Declares Android components and UI labels that allow users to invite one of their contacts to + a social network, notify users when one of their social networking streams is updated, and + so forth. +</p> +<p> + Notice that the attribute prefix <code>android:</code> is not necessary for the attributes + of <code><ContactsAccountType></code>. +</p> +<p> + <strong>Attributes:</strong> +</p> +<dl> + <dt>{@code inviteContactActivity}</dt> + <dd> + The fully-qualified class name of the activity in your application that you want to + activate when the user selects <strong>Add connection</strong> from the device's + contacts application. + </dd> + <dt>{@code inviteContactActionLabel}</dt> + <dd> + A text string that is displayed for the activity specified in + {@code inviteContactActivity}, in the <strong>Add connection</strong> menu. + For example, you can use the string "Follow in my network". You can use a string resource + identifier for this label. + </dd> + <dt>{@code viewContactNotifyService}</dt> + <dd> + The fully-qualified class name of a service in your application that should receive + notifications when the user views a contact. This notification is sent by the device's + contacts application; it allows your application to postpone data-intensive operations + until they're needed. For example, your application can respond to this notification + by reading in and displaying the contact's high-resolution photo and most recent + social stream items. This feature is described in more detail in the section + <a href="#SocialStreamInteraction">Social stream interactions</a>. You can see an + example of the notification service in the <code>NotifierService.java</code> file in the + <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">SampleSyncAdapter</a> + sample app. + </dd> + <dt>{@code viewGroupActivity}</dt> + <dd> + The fully-qualified class name of an activity in your application that can display + group information. When the user clicks the group label in the device's contacts + application, the UI for this activity is displayed. + </dd> + <dt>{@code viewGroupActionLabel}</dt> + <dd> + The label that the contacts application displays for a UI control that allows + the user to look at groups in your application. + <p> + For example, if you install the Google+ application on your device and you sync + Google+ with the contacts application, you'll see Google+ circles listed as groups + in your contacts application's <strong>Groups</strong> tab. If you click on a + Google+ circle, you'll see people in that circle listed as a "group". At the top of + the display, you'll see a Google+ icon; if you click it, control switches to the + Google+ app. The contacts application does this with the + {@code viewGroupActivity}, using the Google+ icon as the value of + {@code viewGroupActionLabel}. + </p> + <p> + A string resource identifier is allowed for this attribute. + </p> + </dd> + <dt>{@code viewStreamItemActivity}</dt> + <dd> + The fully-qualified class name of an activity in your application that the device's + contacts application launches when the user clicks a stream item for a raw contact. + </dd> + <dt>{@code viewStreamItemPhotoActivity}</dt> + <dd> + The fully-qualified class name of an activity in your application that the device's + contacts application launches when the user clicks a photo in the stream item + for a raw contact. + </dd> +</dl> +<h4 id="SocialStreamDataKind"><ContactsDataKind> element</h4> +<p> + The <code><ContactsDataKind></code> element controls the display of your application's + custom data rows in the contacts application's UI. It has the following syntax: +</p> +<pre> +<ContactsDataKind + android:mimeType="<em>MIMEtype</em>" + android:icon="<em>icon_resources</em>" + android:summaryColumn="<em>column_name</em>" + android:detailColumn="<em>column_name</em>"> +</pre> +<p> + <strong>contained in:</strong> +</p> +<code><ContactsAccountType></code> +<p> + <strong>Description:</strong> +</p> +<p> + Use this element to have the contacts application display the contents of a custom data row as + part of the details of a raw contact. Each <code><ContactsDataKind></code> child element + of <code><ContactsAccountType></code> represents a type of custom data row that your sync + adapter adds to the {@link android.provider.ContactsContract.Data} table. Add one + <code><ContactsDataKind></code> element for each custom MIME type you use. You don't have + to add the element if you have a custom data row for which you don't want to display data. +</p> +<p> + <strong>Attributes:</strong> +</p> +<dl> + <dt>{@code android:mimeType}</dt> + <dd> + The custom MIME type you've defined for one of your custom data row types in the + {@link android.provider.ContactsContract.Data} table. For example, the value + <code>vnd.android.cursor.item/vnd.example.locationstatus</code> could be a custom + MIME type for a data row that records a contact's last known location. + </dd> + <dt>{@code android:icon}</dt> + <dd> + An Android + <a href="{@docRoot}guide/topics/resources/drawable-resource.html">drawable resource</a> + that the contacts application displays next to your data. Use this to indicate to the + user that the data comes from your service. + </dd> + <dt>{@code android:summaryColumn}</dt> + <dd> + The column name for the first of two values retrieved from the data row. The + value is displayed as the first line of the entry for this data row. The first line is + intended to be used as a summary of the data, but that is optional. See also + <a href="#detailColumn">android:detailColumn</a>. + </dd> + <dt>{@code android:detailColumn}</dt> + <dd> + The column name for the second of two values retrieved from the data row. The value is + displayed as the second line of the entry for this data row. See also + {@code android:summaryColumn}. + </dd> +</dl> +<h2 id="AdditionalFeatures">Additional Contacts Provider Features</h2> +<p> + Besides the main features described in previous sections, the Contacts Provider offers + these useful features for working with contacts data: +</p> + <ul> + <li>Contact groups</li> + <li>Photo features</li> + </ul> +<h3 id="Groups">Contact groups</h3> +<p> + The Contacts Provider can optionally label collections of related contacts with + <strong>group</strong> data. If the server associated with a user account + wants to maintain groups, the sync adapter for the account's account type should transfer + groups data between the Contacts Provider and the server. When users add a new contact to the + server and then put this contact in a new group, the sync adapter must add the new group + to the {@link android.provider.ContactsContract.Groups} table. The group or groups a raw + contact belongs to are stored in the {@link android.provider.ContactsContract.Data} table, using + the {@link android.provider.ContactsContract.CommonDataKinds.GroupMembership} MIME type. +</p> +<p> + If you're designing a sync adapter that will add raw contact data from + server to the Contacts Provider, and you aren't using groups, then you need to tell the + Provider to make your data visible. In the code that is executed when a user adds an account + to the device, update the {@link android.provider.ContactsContract.Settings} + row that the Contacts Provider adds for the account. In this row, set the value of the + {@link android.provider.ContactsContract.SettingsColumns#UNGROUPED_VISIBLE + Settings.UNGROUPED_VISIBLE} column to 1. When you do this, the Contacts Provider will always + make your contacts data visible, even if you don't use groups. +</p> +<h3 id="Photos">Contact photos</h3> +<p> + The {@link android.provider.ContactsContract.Data} table stores photos as rows with MIME type + {@link android.provider.ContactsContract.CommonDataKinds.Photo#CONTENT_ITEM_TYPE + Photo.CONTENT_ITEM_TYPE}. The row's + {@link android.provider.ContactsContract.RawContactsColumns#CONTACT_ID} column is linked to the + {@link android.provider.BaseColumns#_ID} column of the raw contact to which it belongs. + The class {@link android.provider.ContactsContract.Contacts.Photo} defines a sub-table of + {@link android.provider.ContactsContract.Contacts} containing photo information for a contact's + primary photo, which is the primary photo of the contact's primary raw contact. Similarly, + the class {@link android.provider.ContactsContract.RawContacts.DisplayPhoto} defines a sub-table + of {@link android.provider.ContactsContract.RawContacts} containing photo information for a + raw contact's primary photo. +</p> +<p> + The reference documentation for {@link android.provider.ContactsContract.Contacts.Photo} and + {@link android.provider.ContactsContract.RawContacts.DisplayPhoto} contain examples of + retrieving photo information. There is no convenience class for retrieving the primary + thumbnail for a raw contact, but you can send a query to the + {@link android.provider.ContactsContract.Data} table, selecting on the raw contact's + {@link android.provider.BaseColumns#_ID}, the + {@link android.provider.ContactsContract.CommonDataKinds.Photo#CONTENT_ITEM_TYPE + Photo.CONTENT_ITEM_TYPE}, and the {@link android.provider.ContactsContract.Data#IS_PRIMARY} + column to find the raw contact's primary photo row. +</p> +<p> + Social stream data for a person may also include photos. These are stored in the + {@link android.provider.ContactsContract.StreamItemPhotos} table, which is described in more + detail in the section <a href="#StreamPhotos">Social stream photos</a>. +</p> diff --git a/docs/html/guide/topics/providers/content-provider-basics.jd b/docs/html/guide/topics/providers/content-provider-basics.jd index de89568..b1d6827 100644 --- a/docs/html/guide/topics/providers/content-provider-basics.jd +++ b/docs/html/guide/topics/providers/content-provider-basics.jd @@ -371,7 +371,7 @@ Uri singleUri = ContentUri.withAppendedId(UserDictionary.Words.CONTENT_URI,4); ContentResolver.query()} on the "UI thread"". In actual code, however, you should do queries asynchronously on a separate thread. One way to do this is to use the {@link android.content.CursorLoader} class, which is described - in more detail in the <a href="{@docRoot}guide/topics/fundamentals/loaders.html"> + in more detail in the <a href="{@docRoot}guide/components/loaders.html"> Loaders</a> guide. Also, the lines of code are snippets only; they don't show a complete application. </p> @@ -941,7 +941,7 @@ mRowsDeleted = getContentResolver().delete( <li> Asynchronous queries: You should do queries in a separate thread. One way to do this is to use a {@link android.content.CursorLoader} object. The examples in the - <a href="{@docRoot}guide/topics/fundamentals/loaders.html">Loaders</a> guide demonstrate + <a href="{@docRoot}guide/components/loaders.html">Loaders</a> guide demonstrate how to do this. </li> <li> diff --git a/docs/html/guide/topics/providers/content-provider-creating.jd b/docs/html/guide/topics/providers/content-provider-creating.jd index 4ebdb50..bad5390 100644 --- a/docs/html/guide/topics/providers/content-provider-creating.jd +++ b/docs/html/guide/topics/providers/content-provider-creating.jd @@ -551,7 +551,7 @@ public class ExampleProvider extends ContentProvider { All of these methods except {@link android.content.ContentProvider#onCreate() onCreate()} can be called by multiple threads at once, so they must be thread-safe. To learn more about multiple threads, see the topic - <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html"> + <a href="{@docRoot}guide/components/processes-and-threads.html"> Processes and Threads</a>. </li> <li> @@ -1211,5 +1211,5 @@ vnd.android.cursor.<strong>item</strong>/vnd.com.example.provider.table1 <p> Handling an incoming intent that wishes to modify your provider's data is no different from handling other intents. You can learn more about using intents by reading the topic - <a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Filters</a>. + <a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>. </p> diff --git a/docs/html/guide/topics/providers/content-providers.jd b/docs/html/guide/topics/providers/content-providers.jd index 1707f03..751fc95 100644 --- a/docs/html/guide/topics/providers/content-providers.jd +++ b/docs/html/guide/topics/providers/content-providers.jd @@ -18,6 +18,9 @@ page.title=Content Providers <li> <a href="{@docRoot}guide/topics/providers/calendar-provider.html">Calendar Provider</a> </li> + <li> + <a href="{@docRoot}guide/topics/providers/contacts-provider.html">Contacts Provider</a> + </li> </ol> <!-- Related Samples --> @@ -38,6 +41,10 @@ page.title=Content Providers href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List7.html"> "Cursor (Phones)"</a> </li> + <li> + <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> + Sample Sync Adapter</a> + </li> </ol> </div> </div> @@ -93,4 +100,11 @@ page.title=Content Providers <dd> How to access the Calendar Provider that is part of the Android platform. </dd> + <dt> + <strong><a href="{@docRoot}guide/topics/providers/contacts-provider.html"> + Contacts Provider</a></strong> + </dt> + <dd> + How to access the Contacts Provider that is part of the Android platform. + </dd> </dl> diff --git a/docs/html/guide/topics/resources/animation-resource.jd b/docs/html/guide/topics/resources/animation-resource.jd index 6473155..3af52aa 100644 --- a/docs/html/guide/topics/resources/animation-resource.jd +++ b/docs/html/guide/topics/resources/animation-resource.jd @@ -18,7 +18,7 @@ parent.link=available-resources.html <h2>See also</h2> <ol> <li><a href="{@docRoot}guide/topics/graphics/view-animation.html">View Animation</a></li> - <li><a href="{@docRoot}guide/topics/graphics/animation.html">Property Animation</a></li> + <li><a href="{@docRoot}guide/topics/graphics/prop-animation.html">Property Animation</a></li> </ol> </div> </div> @@ -334,7 +334,7 @@ set.start(); <dt>see also:</dt> <dd> <ul> - <li><a href="{@docRoot}guide/topics/graphics/animation.html">Property Animation</a></li> + <li><a href="{@docRoot}guide/topics/graphics/prop-animation.html">Property Animation</a></li> <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html">API Demos</a> for examples on how to use the property animation system.</li> </ul> diff --git a/docs/html/guide/topics/resources/index.jd b/docs/html/guide/topics/resources/index.jd index 3f0f1ee..386abf5 100644 --- a/docs/html/guide/topics/resources/index.jd +++ b/docs/html/guide/topics/resources/index.jd @@ -1,103 +1,55 @@ -page.title=Application Resources -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - <h2>Topics</h2> - <ol> - <li><a href="providing-resources.html">Providing Resources</a></li> - <li><a href="accessing-resources.html">Accessing Resources</a></li> - <li><a href="runtime-changes.html">Handling Runtime Changes</a></li> - <li><a href="localization.html">Localization</a></li> - </ol> - - <h2>Reference</h2> - <ol> - <li><a href="available-resources.html">Resource Types</a></li> - </ol> -</div> -</div> - - -<p>You should always externalize resources such as images and strings from your application -code, so that you can maintain them independently. Externalizing your -resources also allows you to provide alternative resources that support specific device -configurations such as different languages or screen sizes, which becomes increasingly -important as more Android-powered devices become available with different configurations. In order -to provide compatibility with different configurations, you must organize resources in your -project's {@code res/} directory, using various sub-directories that group resources by type and -configuration.</p> - -<div class="figure" style="width:429px"> -<img src="{@docRoot}images/resources/resource_devices_diagram1.png" height="167" alt="" /> -<p class="img-caption"> -<strong>Figure 1.</strong> Two different devices, each using the default layout -(the app provides no alternative layouts).</p> -</div> - -<div class="figure" style="width:429px"> -<img src="{@docRoot}images/resources/resource_devices_diagram2.png" height="167" alt="" /> -<p class="img-caption"> -<strong>Figure 2.</strong> Two different devices, each using a different layout provided -for different screen sizes.</p> -</div> +page.title=App Resources +page.landing=true +page.landing.intro=It takes more than just code to build a great app. Resources are the additional files and static content that your code uses, such as bitmaps, layout definitions, user interface strings, animation instructions, and more. +page.landing.image=images/develop/resources.png -<p>For any type of resource, you can specify <em>default</em> and multiple -<em>alternative</em> resources for your application:</p> -<ul> - <li>Default resources are those that should be used regardless of -the device configuration or when there are no alternative resources that match the current -configuration.</li> - <li>Alternative resources are those that you've designed for use with a specific -configuration. To specify that a group of resources are for a specific configuration, -append an appropriate configuration qualifier to the directory name.</li> -</ul> - -<p>For example, while your default UI -layout is saved in the {@code res/layout/} directory, you might specify a different layout to -be used when the screen is in landscape orientation, by saving it in the {@code res/layout-land/} -directory. Android automatically applies the appropriate resources by matching the -device's current configuration to your resource directory names.</p> - -<p>Figure 1 illustrates how the system applies the same layout for -two different devices when there are no alternative resources available. Figure 2 shows -the same application when it adds an alternative layout resource for larger screens.</p> - -<p>The following documents provide a complete guide to how you can organize your application resources, -specify alternative resources, access them in your application, and more:</p> - -<dl> - <dt><strong><a href="providing-resources.html">Providing Resources</a></strong></dt> - <dd>What kinds of resources you can provide in your app, where to save them, and how to create -alternative resources for specific device configurations.</dd> - <dt><strong><a href="accessing-resources.html">Accessing Resources</a></strong></dt> - <dd>How to use the resources you've provided, either by referencing them from your application -code or from other XML resources.</dd> - <dt><strong><a href="runtime-changes.html">Handling Runtime Changes</a></strong></dt> - <dd>How to manage configuration changes that occur while your Activity is running.</dd> - <dt><strong><a href="localization.html">Localization</a></strong></dt> - <dd>A bottom-up guide to localizing your application using alternative resources. While this is -just one specific use of alternative resources, it is very important in order to reach more -users.</dd> - <dt><strong><a href="available-resources.html">Resource Types</a></strong></dt> - <dd>A reference of various resource types you can provide, describing their XML elements, -attributes, and syntax. For example, this reference shows you how to create a resource for -application menus, drawables, animations, and more.</dd> -</dl> - -<!-- -<h2>Raw Assets</h2> +@jd:body -<p>An alternative to saving files in {@code res/} is to save files in the {@code -assets/} directory. This should only be necessary if you need direct access to original files and -directories by name. Files saved in the {@code assets/} directory will not be given a resource -ID, so you can't reference them through the {@code R} class or from XML resources. Instead, you can -query data in the {@code assets/} directory like an ordinary file system, search through the -directory and -read raw data using {@link android.content.res.AssetManager}. For example, this can be more useful -when dealing with textures for a game. However, if you only need to read raw data from a file -(such as a video or audio file), then you should save files into the {@code res/raw/} directory and -then read a stream of bytes using {@link android.content.res.Resources#openRawResource(int)}. This -is uncommon, but if you need direct access to original files in {@code assets/}, refer to the {@link -android.content.res.AssetManager} documentation.</p> ---> +<div class="landing-docs"> + + <div class="col-6"> + <h3>Blog Articles</h3> + + <a +href="http://android-developers.blogspot.com/2011/07/new-tools-for-managing-screen-sizes.html"> + <h4>New Tools For Managing Screen Sizes</h4> + <p>Android 3.2 includes new tools for supporting devices with a wide range of screen sizes. +One important result is better support for a new size of screen; what is typically called a ?7-inch? +tablet. This release also offers several new APIs to simplify developers? work in adjusting to +different screen sizes.</p> + </a> + + <a href="http://android-developers.blogspot.com/2012/01/holo-everywhere.html"> + <h4>Holo Everywhere</h4> + <p>Before Android 4.0 the variance in system themes from device to device could make it +difficult to design an app with a single predictable look and feel. We set out to improve this +situation for the developer community in Ice Cream Sandwich and beyond.</p> + </a> + + <a +href="http://android-developers.blogspot.com/2011/07/new-mode-for-apps-on-large-screens.html"> + <h4>New Mode for Apps on Large Screens</h4> + <p>Android tablets are becoming more popular, and we're pleased to note that the vast majority +of apps resize to the larger screens just fine. To keep the few apps that don't resize well from +frustrating users with awkward-looking apps on their tablets, Android 3.2 introduces a screen +compatibility mode that makes these apps more usable on tablets.</p> + </a> + </div> + + <div class="col-6"> + <h3>Training</h3> + + <a href="http://developer.android.com/training/basics/supporting-devices/index.html"> + <h4>Supporting Different Devices</h4> + <p>This class teaches you how to use basic platform features that leverage alternative +resources and other features so your app can provide an optimized user experience on a variety of +Android-compatible devices, using a single application package (APK).</p> + </a> + + <a href="http://developer.android.com/training/multiscreen/index.html"> + <h4>Designing for Multiple Screens</h4> + <p>This class shows you how to implement a user interface that's optimized for several screen +configurations.</p> + </a> + </div> +</div><!-- end landing-docs --> diff --git a/docs/html/guide/topics/resources/layout-resource.jd b/docs/html/guide/topics/resources/layout-resource.jd index 286e3d1..5643075 100644 --- a/docs/html/guide/topics/resources/layout-resource.jd +++ b/docs/html/guide/topics/resources/layout-resource.jd @@ -7,7 +7,7 @@ parent.link=available-resources.html <div id="qv"> <h2>See also</h2> <ol> - <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">XML Layouts</a></li> + <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Layouts</a></li> </ol> </div> </div> @@ -128,7 +128,7 @@ or {@code "wrap_content"}). See the <a href="#layoutvalues">valid values</a> bel <p>More attributes are supported by the {@link android.view.View} base class, and many more are supported by each implementation of {@link android.view.View}. Read <a -href="{@docRoot}guide/topics/ui/declaring-layout.html">XML Layouts</a> for more information. For +href="{@docRoot}guide/topics/ui/declaring-layout.html">Layouts</a> for more information. For a reference of all available attributes, see the corresponding reference documentation (for example, the <a href="{@docRoot}reference/android/widget/TextView.html#lattrs">TextView XML attributes</a>).</p> @@ -275,7 +275,7 @@ public void onCreate(Bundle savedInstanceState) { <dt>see also:</dt> <dd> <ul> - <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">XML Layouts</a></li> + <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Layouts</a></li> <li>{@link android.view.View}</li> <li>{@link android.view.ViewGroup}</li> </ul> diff --git a/docs/html/guide/topics/resources/localization.jd b/docs/html/guide/topics/resources/localization.jd index c2b668d..41961a3 100755 --- a/docs/html/guide/topics/resources/localization.jd +++ b/docs/html/guide/topics/resources/localization.jd @@ -38,7 +38,6 @@ defaults.</li> <li><a href="#emulator">Testing on an Emulator</a></li>
<li><a href="#test-for-default">Testing for Default Resources</a></li>
</ol>
-<li><a href="#publishing">Publishing</a></li>
<li><a href="#checklist">Localization Checklists</a></li>
<ol>
<li><a href="#planning-checklist">Planning and Design Checklist</a></li>
@@ -52,7 +51,7 @@ defaults.</li> <li><a
href="{@docRoot}resources/tutorials/localization/index.html">Hello, L10N Tutorial</a></li>
<li><a href="{@docRoot}guide/topics/resources/providing-resources.html">Providing Resources</a></li>
- <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">XML Layouts</a></li>
+ <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Layouts</a></li>
<li><a href="{@docRoot}reference/android/app/Activity.html#ActivityLifecycle">Activity Lifecycle</a></li>
</ol>
</div>
@@ -430,7 +429,7 @@ Menu > Settings > Locale & text > Select locale). </p> <h3 id="emulator">Testing on an Emulator</h3>
<p>For details about using the emulator, see See <a
-href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a>.</p>
+href="{@docRoot}tools/help/emulator.html">Android Emulator</a>.</p>
<h4>Creating and using a custom locale</h4>
<p>A "custom" locale is a language/region combination that the Android
@@ -505,26 +504,6 @@ the new locale. </p> <code>res/layout-port/main.xml</code>, then set the emulator or device to
portrait orientation and see if the application will run.
-<h2 id="publishing">Publishing Localized Applications</h2>
-
-<p>The Google Play is
- the main application distribution system for Android devices. To publish a
- localized application, you need to sign your application, version it, and go
-through all the other steps described in <a
-href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish</a>. </p>
-
-<p>If you split your application in several .apk files, each targeted to a
-different locale, follow these guidelines:</p>
-
-<ul>
- <li>Sign each .apk file with the same certificate. For more about this, see <a
-href="{@docRoot}guide/publishing/app-signing.html#strategies">Signing
-Strategies</a>. </li>
- <li>Give each .apk file a different application name. Currently it is
-impossible to publish two applications on Google Play that have exactly the
-same name.</li>
-<li>Include a complete set of default resources in each .apk file.</li>
-</ul>
<h2 id="checklist">Localization Checklists</h2>
@@ -640,8 +619,6 @@ border="0"></td> border="0"></td>
<td>Upload your .apk file or files to Google Play, selecting the appropriate
languages as
- you upload. (For more details, see <a
-href="{@docRoot}guide/publishing/publishing.html">Publishing Your
-Applications</a>.)</td>
+ you upload.</td>
</tr>
</table>
\ No newline at end of file diff --git a/docs/html/guide/topics/resources/menu-resource.jd b/docs/html/guide/topics/resources/menu-resource.jd index fb7612e..b2d6eb3 100644 --- a/docs/html/guide/topics/resources/menu-resource.jd +++ b/docs/html/guide/topics/resources/menu-resource.jd @@ -111,7 +111,7 @@ only parameter, which indicates the item clicked. This method takes precedence o callback to {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()}. See the example at the bottom. <p class="warning"><strong>Warning:</strong> If you obfuscate your code using <a -href="{@docRoot}guide/developing/tools/proguard.html">ProGuard</a> (or a similar tool), +href="{@docRoot}tools/help/proguard.html">ProGuard</a> (or a similar tool), be sure to exclude the method you specify in this attribute from renaming, because it can break the functionality.</p> <p>Introduced in API Level 11.</p></dd> @@ -133,7 +133,8 @@ Avoid using this unless it's critical that the item always appear in the action bar. Setting multiple items to always appear as action items can result in them overlapping with other UI in the action bar.</td></tr> <tr><td><code>collapseActionView</code></td><td>The action view associated -with this action item (as declared by <code>android:actionViewLayout</code>) is +with this action item (as declared by <code>android:actionLayout</code> or +<code>android:actionViewClass</code>) is collapsible.<br/>Introduced in API Level 14.</td></tr> </table> <p>See the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer @@ -141,7 +142,7 @@ guide for more information.</p> <p>Introduced in API Level 11.</p> </dd> - <dt><code>android:actionViewLayout</code></dt> + <dt><code>android:actionLayout</code></dt> <dd><em>Layout resource</em>. A layout to use as the action view. <p>See the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guide for more information.</p> @@ -154,7 +155,7 @@ to use as the action view. For example, <p>See the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guide for more information.</p> <p class="warning"><strong>Warning:</strong> If you obfuscate your code using <a -href="{@docRoot}guide/developing/tools/proguard.html">ProGuard</a> (or a similar tool), +href="{@docRoot}tools/help/proguard.html">ProGuard</a> (or a similar tool), be sure to exclude the class you specify in this attribute from renaming, because it can break the functionality.</p> <p>Introduced in API Level 11.</p></dd> @@ -166,7 +167,7 @@ android.view.ActionProvider} to use in place of the action item. For example, <p>See the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guide for more information.</p> <p class="warning"><strong>Warning:</strong> If you obfuscate your code using <a -href="{@docRoot}guide/developing/tools/proguard.html">ProGuard</a> (or a similar tool), +href="{@docRoot}tools/help/proguard.html">ProGuard</a> (or a similar tool), be sure to exclude the class you specify in this attribute from renaming, because it can break the functionality.</p> <p>Introduced in API Level 14.</p></dd> diff --git a/docs/html/guide/topics/resources/overview.jd b/docs/html/guide/topics/resources/overview.jd new file mode 100644 index 0000000..c3bd0bf --- /dev/null +++ b/docs/html/guide/topics/resources/overview.jd @@ -0,0 +1,103 @@ +page.title=Resources Overview +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>Topics</h2> + <ol> + <li><a href="providing-resources.html">Providing Resources</a></li> + <li><a href="accessing-resources.html">Accessing Resources</a></li> + <li><a href="runtime-changes.html">Handling Runtime Changes</a></li> + <li><a href="localization.html">Localization</a></li> + </ol> + + <h2>Reference</h2> + <ol> + <li><a href="available-resources.html">Resource Types</a></li> + </ol> +</div> +</div> + + +<p>You should always externalize resources such as images and strings from your application +code, so that you can maintain them independently. Externalizing your +resources also allows you to provide alternative resources that support specific device +configurations such as different languages or screen sizes, which becomes increasingly +important as more Android-powered devices become available with different configurations. In order +to provide compatibility with different configurations, you must organize resources in your +project's {@code res/} directory, using various sub-directories that group resources by type and +configuration.</p> + +<div class="figure" style="width:429px"> +<img src="{@docRoot}images/resources/resource_devices_diagram1.png" height="167" alt="" /> +<p class="img-caption"> +<strong>Figure 1.</strong> Two different devices, each using the default layout +(the app provides no alternative layouts).</p> +</div> + +<div class="figure" style="width:429px"> +<img src="{@docRoot}images/resources/resource_devices_diagram2.png" height="167" alt="" /> +<p class="img-caption"> +<strong>Figure 2.</strong> Two different devices, each using a different layout provided +for different screen sizes.</p> +</div> + +<p>For any type of resource, you can specify <em>default</em> and multiple +<em>alternative</em> resources for your application:</p> +<ul> + <li>Default resources are those that should be used regardless of +the device configuration or when there are no alternative resources that match the current +configuration.</li> + <li>Alternative resources are those that you've designed for use with a specific +configuration. To specify that a group of resources are for a specific configuration, +append an appropriate configuration qualifier to the directory name.</li> +</ul> + +<p>For example, while your default UI +layout is saved in the {@code res/layout/} directory, you might specify a different layout to +be used when the screen is in landscape orientation, by saving it in the {@code res/layout-land/} +directory. Android automatically applies the appropriate resources by matching the +device's current configuration to your resource directory names.</p> + +<p>Figure 1 illustrates how the system applies the same layout for +two different devices when there are no alternative resources available. Figure 2 shows +the same application when it adds an alternative layout resource for larger screens.</p> + +<p>The following documents provide a complete guide to how you can organize your application resources, +specify alternative resources, access them in your application, and more:</p> + +<dl> + <dt><strong><a href="providing-resources.html">Providing Resources</a></strong></dt> + <dd>What kinds of resources you can provide in your app, where to save them, and how to create +alternative resources for specific device configurations.</dd> + <dt><strong><a href="accessing-resources.html">Accessing Resources</a></strong></dt> + <dd>How to use the resources you've provided, either by referencing them from your application +code or from other XML resources.</dd> + <dt><strong><a href="runtime-changes.html">Handling Runtime Changes</a></strong></dt> + <dd>How to manage configuration changes that occur while your Activity is running.</dd> + <dt><strong><a href="localization.html">Localization</a></strong></dt> + <dd>A bottom-up guide to localizing your application using alternative resources. While this is +just one specific use of alternative resources, it is very important in order to reach more +users.</dd> + <dt><strong><a href="available-resources.html">Resource Types</a></strong></dt> + <dd>A reference of various resource types you can provide, describing their XML elements, +attributes, and syntax. For example, this reference shows you how to create a resource for +application menus, drawables, animations, and more.</dd> +</dl> + +<!-- +<h2>Raw Assets</h2> + +<p>An alternative to saving files in {@code res/} is to save files in the {@code +assets/} directory. This should only be necessary if you need direct access to original files and +directories by name. Files saved in the {@code assets/} directory will not be given a resource +ID, so you can't reference them through the {@code R} class or from XML resources. Instead, you can +query data in the {@code assets/} directory like an ordinary file system, search through the +directory and +read raw data using {@link android.content.res.AssetManager}. For example, this can be more useful +when dealing with textures for a game. However, if you only need to read raw data from a file +(such as a video or audio file), then you should save files into the {@code res/raw/} directory and +then read a stream of bytes using {@link android.content.res.Resources#openRawResource(int)}. This +is uncommon, but if you need direct access to original files in {@code assets/}, refer to the {@link +android.content.res.AssetManager} documentation.</p> +--> diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd index 82b5e29..b0d5d6f 100644 --- a/docs/html/guide/topics/resources/providing-resources.jd +++ b/docs/html/guide/topics/resources/providing-resources.jd @@ -44,7 +44,7 @@ Screens</a></li> <p>You should always externalize application resources such as images and strings from your code, so that you can maintain them independently. You should also provide alternative resources for specific device configurations, by grouping them in specially-named resource directories. At -runtime, Android uses uses the appropriate resource based on the current configuration. For +runtime, Android uses the appropriate resource based on the current configuration. For example, you might want to provide a different UI layout depending on the screen size or different strings depending on the language setting.</p> @@ -89,7 +89,7 @@ supported inside project {@code res/} directory.</p> <tr> <td><code>animator/</code></td> - <td>XML files that define <a href="{@docRoot}guide/topics/graphics/animation.html">property + <td>XML files that define <a href="{@docRoot}guide/topics/graphics/prop-animation.html">property animations</a>.</td> </tr> @@ -744,7 +744,7 @@ orientation" described above.</p> <p>The API level supported by the device. For example, <code>v1</code> for API level 1 (devices with Android 1.0 or higher) and <code>v4</code> for API level 4 (devices with Android 1.6 or higher). See the <a -href="{@docRoot}guide/appendix/api-levels.html">Android API levels</a> document for more information +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">Android API levels</a> document for more information about these values.</p> <p class="caution"><strong>Caution:</strong> Android 1.5 and 1.6 only match resources with this qualifier when it exactly matches the platform version. See the section below about <a @@ -976,7 +976,7 @@ put {@code normal} size resources in the corresponding default resource director notlong} resources in the corresponding default resource directory.</p> </li> - <li>Ensure that your <a href="{@docRoot}sdk/tools-notes.html">SDK Tools</a> version + <li>Ensure that your <a href="{@docRoot}tools/sdk/tools-notes.html">SDK Tools</a> version is r6 or greater. <p>You need SDK Tools, Revision 6 (or greater), because it includes a new packaging tool that diff --git a/docs/html/guide/topics/resources/runtime-changes.jd b/docs/html/guide/topics/resources/runtime-changes.jd index 871b063..f5475b4 100644 --- a/docs/html/guide/topics/resources/runtime-changes.jd +++ b/docs/html/guide/topics/resources/runtime-changes.jd @@ -32,7 +32,7 @@ alternative resources that match the new device configuration.</p> <p>To properly handle a restart, it is important that your activity restores its previous state through the normal <a -href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">Activity +href="{@docRoot}guide/components/activities.html#Lifecycle">Activity lifecycle</a>, in which Android calls {@link android.app.Activity#onSaveInstanceState(Bundle) onSaveInstanceState()} before it destroys your activity so that you can save data about the application state. You can then restore the state @@ -45,7 +45,7 @@ tasks in your application. Your application should be able to restart at any tim user data or state in order to handle events such as configuration changes or when the user receives an incoming phone call and then returns to your application much later after your application process may have been destroyed. To learn how you can restore your activity state, read about the <a -href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">Activity lifecycle</a>.</p> +href="{@docRoot}guide/components/activities.html#Lifecycle">Activity lifecycle</a>.</p> <p>However, you might encounter a situation in which restarting your application and restoring significant amounts of data can be costly and create a poor user experience. In such a diff --git a/docs/html/guide/topics/search/index.jd b/docs/html/guide/topics/search/index.jd index 218511b..2ee624b 100644 --- a/docs/html/guide/topics/search/index.jd +++ b/docs/html/guide/topics/search/index.jd @@ -1,4 +1,4 @@ -page.title=Search +page.title=Search Overview @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/search/search-dialog.jd b/docs/html/guide/topics/search/search-dialog.jd index 8b8e75b..49451ac 100644 --- a/docs/html/guide/topics/search/search-dialog.jd +++ b/docs/html/guide/topics/search/search-dialog.jd @@ -561,7 +561,7 @@ case, the search dialog naturally disappears).</p> events are triggered once the user executes a search (the current activity receives {@link android.app.Activity#onPause()} and so forth, as described in the <a -href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">Activities</a> +href="{@docRoot}guide/components/activities.html#Lifecycle">Activities</a> document). If, however, the current activity is the searchable activity, then one of two things happens:</p> diff --git a/docs/html/guide/topics/security/index.jd b/docs/html/guide/topics/security/index.jd new file mode 100644 index 0000000..775fc03 --- /dev/null +++ b/docs/html/guide/topics/security/index.jd @@ -0,0 +1,65 @@ +page.title=Security and Permissions +page.landing=true +page.landing.intro=Android's security architecture gives the user full control over what resources are accessible to each app, protecting the system itself and all apps in it. Learn how to use system permissions to request access to the resources your app needs and design your app for optimal security. +page.landing.image= + +@jd:body + +<div style="width=100%;padding-left:1em;"> + + <div style="float:left;clear:both;padding-top:20px;"> + <p style="text-transform:uppercase;"><b style="color:#666;font-size:14px;">Blog Articles</b></p> + + <div class="" style="border-top:2px solid #DDD;margin:1em 0;background-color:#F7F7F7;width:336px"> + + <div style="float:left;padding:8px;padding-right:16px;"> + <img src="/assets/images/resource-article.png"> + </div> + + <div class="caption"> + <p style="margin:0;padding:0;font-weight:bold;"><a href="">Accessibility: Are You Serving All Your Users?</a></p> + <p style="margin:0;padding:0">In the upcoming weeks, some of the older Client Login authentication keys will expire. + If you generated the token you’re currently using to authenticate with the C2DM servers before October 2011, it will stop working.</p> + + <p style="margin:0;padding:0;font-weight:bold;"><a href="">Android C2DM — Client Login key expiration</a></p> + <p style="margin:0;padding:0">Accessibility is about making sure that Android users who have limited vision or other physical impairments can use your application just as well</p> + + <p style="margin:0;padding:0;font-weight:bold;"><a href="">A Faster Emulator with Better Hardware Support</a></p> + <p style="margin:0;padding:0">The Android emulator is a key tool for Android developers in building and testing their apps. + As the power and diversity of Android devices has grown quickly, it’s been hard for the emulator keep pace. </p> + + <a href="">More »</a> + </div> + </div> + </div> + + <div style="float:right;padding-top:20px;"> + <p style="text-transform:uppercase;"><b style="color:#666;font-size:14px;">Training</b></p> + + <div class="" style="border-top:2px solid #DDD;bordddser-top:2px solid #FF8800;margin:1em 0;background-color:#F7F7F7;width:336px"> + + <div style="float:left;padding:8px;padding-right:16px;"> + <img src="/assets/images/resource-tutorial.png"> + </div> + + <div class="caption"> + <p style="margin:0;padding:0;font-weight:bold;"><a href="">Managing the Activity Lifecycle</a></p> + <p style="margin:0;padding:0">This class explains important lifecycle callback methods that each Activity + instance receives and how you can use them so your activity does what the user expects and does not consume system + resources when your activity doesn't need them.</p> + + <p style="margin:0;padding:0;font-weight:bold;"><a href="">Supporting Different Devices</a></p> + <p style="margin:0;padding:0">This class teaches you how to use basic platform features that leverage alternative + resources and other features so your app can provide an optimized user experience on a variety of Android-compatible devices, + using a single application package (APK).</p> + + <p style="margin:0;padding:0;font-weight:bold;"><a href="">Sharing Content</a></p> + <p style="margin:0;padding:0">This class covers some common ways you can send and receive content between + applications using Intent APIs and the ActionProvider object.</p> + + <a href="">More »</a> + </div> + </div> +</div> + +</div>
\ No newline at end of file diff --git a/docs/html/guide/topics/security/permissions.jd b/docs/html/guide/topics/security/permissions.jd new file mode 100644 index 0000000..3013e38 --- /dev/null +++ b/docs/html/guide/topics/security/permissions.jd @@ -0,0 +1,407 @@ +page.title=Permissions +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>In this document</h2> +<ol> +<li><a href="#arch">Security Architecture</a></li> +<li><a href="#signing">Application Signing</a></li> +<li><a href="#userid">User IDs and File Access</a></li> +<li><a href="#permissions">Using Permissions</a></li> +<li><a href="#declaring">Declaring and Enforcing Permissions</a> + <ol> + <li><a href="#manifest">...in AndroidManifest.xml</a></li> + <li><a href="#broadcasts">...when Sending Broadcasts</a></li> + <li><a href="#enforcement">Other Permission Enforcement</a></li> + </ol></li> +<li><a href="#uri">URI Permissions</a></li> +</ol> +</div> +</div> +<p>This document describes how application developers can use the +security features provided by Android. A more general <a +href="http://source.android.com/tech/security/index.html"> Android Security +Overview</a> is provided in the Android Open Source Project.</p> + +<p>Android is a privilege-separated operating system, in which each +application runs with a distinct system identity (Linux user ID and group +ID). Parts of the system are also separated into distinct identities. +Linux thereby isolates applications from each other and from the system.</p> + +<p>Additional finer-grained security features are provided through a +"permission" mechanism that enforces restrictions on the specific operations +that a particular process can perform, and per-URI permissions for granting +ad-hoc access to specific pieces of data.</p> + +<a name="arch"></a> +<h2>Security Architecture</h2> + +<p>A central design point of the Android security architecture is that no +application, by default, has permission to perform any operations that would +adversely impact other applications, the operating system, or the user. This +includes reading or writing the user's private data (such as contacts or +e-mails), reading or writing another application's files, performing +network access, keeping the device awake, etc.</p> + +<p>Because Android sandboxes applications from each other, applications +must explicitly share resources and data. They do this by declaring the +<em>permissions</em> they need for additional capabilities not provided by +the basic sandbox. Applications statically declare the permissions they +require, and the Android system prompts the user for consent at the time the +application is installed. Android has no mechanism for granting permissions +dynamically (at run-time) because it complicates the user experience to the +detriment of security.</p> + +<p>The application sandbox does not depend on the technology used to build +an application. In particular the Dalvik VM is not a security boundary, and +any app can run native code (see <a href="/sdk/ndk/index.html">the Android +NDK</a>). All types of applications — Java, native, and hybrid — +are sandboxed in the same way and have the same degree of security from each +other.</p> + +<a name="signing"></a> +<h2>Application Signing</h2> + +<p>All Android applications (.apk files) must be signed with a certificate +whose private key is held by their developer. This certificate identifies +the author of the application. The certificate does <em>not</em> need to be +signed by a certificate authority: it is perfectly allowable, and typical, +for Android applications to use self-signed certificates. The purpose of +certificates in Android is to distinguish application authors. This allows +the system to grant or deny applications access to <a +href="/guide/topics/manifest/permission-element.html#plevel">signature-level +permissions</a> and to grant or deny an application's <a +href="/guide/topics/manifest/manifest-element.html#uid">request to be given +the same Linux identity</a> as another application.</p> + +<a name="userid"></a> +<h2>User IDs and File Access</h2> + +<p>At install time, Android gives each package a distinct Linux user ID. The +identity remains constant for the duration of the package's life on that +device. On a different device, the same package may have a different UID; +what matters is that each package has a distinct UID on a given device.</p> + +<p>Because security enforcement happens at the +process level, the code of any two packages can not normally +run in the same process, since they need to run as different Linux users. +You can use the {@link android.R.attr#sharedUserId} attribute in the +<code>AndroidManifest.xml</code>'s +{@link android.R.styleable#AndroidManifest manifest} tag of each package to +have them assigned the same user ID. By doing this, for purposes of security +the two packages are then treated as being the same application, with the same +user ID and file permissions. Note that in order to retain security, only two applications +signed with the same signature (and requesting the same sharedUserId) will +be given the same user ID.</p> + +<p>Any data stored by an application will be assigned that application's user +ID, and not normally accessible to other packages. When creating a new file +with {@link android.content.Context#getSharedPreferences}, +{@link android.content.Context#openFileOutput}, or +{@link android.content.Context#openOrCreateDatabase}, +you can use the +{@link android.content.Context#MODE_WORLD_READABLE} and/or +{@link android.content.Context#MODE_WORLD_WRITEABLE} flags to allow any other +package to read/write the file. When setting these flags, the file is still +owned by your application, but its global read and/or write permissions have +been set appropriately so any other application can see it.</p> + + +<a name="permissions"></a> +<h2>Using Permissions</h2> + +<p>A basic Android application has no permissions associated with it, +meaning it can not do anything that would adversely impact the user experience +or any data on the device. To make use of protected features of the device, +you must include in your <code>AndroidManifest.xml</code> one or more +<code>{@link android.R.styleable#AndroidManifestUsesPermission <uses-permission>}</code> +tags declaring the permissions that your application needs.</p> + +<p>For example, an application that needs to monitor incoming SMS messages would +specify:</p> + +<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.android.app.myapp" > + <uses-permission android:name="android.permission.RECEIVE_SMS" /> + ... +</manifest></pre> + +<p>At application install time, permissions requested by the application are +granted to it by the package installer, based on checks against the +signatures of the applications declaring those permissions and/or interaction +with the user. <em>No</em> checks with the user +are done while an application is running: it either was granted a particular +permission when installed, and can use that feature as desired, or the +permission was not granted and any attempt to use the feature will fail +without prompting the user.</p> + +<p>Often times a permission failure will result in a {@link +java.lang.SecurityException} being thrown back to the application. However, +this is not guaranteed to occur everywhere. For example, the {@link +android.content.Context#sendBroadcast} method checks permissions as data is +being delivered to each receiver, after the method call has returned, so you +will not receive an exception if there are permission failures. In almost all +cases, however, a permission failure will be printed to the system log.</p> + +<p>The permissions provided by the Android system can be found at {@link +android.Manifest.permission}. Any application may also define and enforce its +own permissions, so this is not a comprehensive list of all possible +permissions.</p> + +<p>A particular permission may be enforced at a number of places during your +program's operation:</p> + +<ul> +<li>At the time of a call into the system, to prevent an application from +executing certain functions.</li> +<li>When starting an activity, to prevent applications from launching +activities of other applications.</li> +<li>Both sending and receiving broadcasts, to control who can receive +your broadcast or who can send a broadcast to you.</li> +<li>When accessing and operating on a content provider.</li> +<li>Binding to or starting a service.</li> +</ul> + + +<a name="declaring"></a> +<h2>Declaring and Enforcing Permissions</h2> + +<p>To enforce your own permissions, you must first declare them in your +<code>AndroidManifest.xml</code> using one or more +<code>{@link android.R.styleable#AndroidManifestPermission <permission>}</code> +tags.</p> + +<p>For example, an application that wants to control who can start one +of its activities could declare a permission for this operation as follows:</p> + +<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.me.app.myapp" > + <permission android:name="com.me.app.myapp.permission.DEADLY_ACTIVITY" + android:label="@string/permlab_deadlyActivity" + android:description="@string/permdesc_deadlyActivity" + android:permissionGroup="android.permission-group.COST_MONEY" + android:protectionLevel="dangerous" /> + ... +</manifest></pre> + +<p>The {@link android.R.styleable#AndroidManifestPermission_protectionLevel +<protectionLevel>} attribute is required, telling the system how the +user is to be informed of applications requiring the permission, or who is +allowed to hold that permission, as described in the linked documentation.</p> + +<p>The {@link android.R.styleable#AndroidManifestPermission_permissionGroup +<permissionGroup>} attribute is optional, and only used to help the system display +permissions to the user. You will usually want to set this to either a standard +system group (listed in {@link android.Manifest.permission_group +android.Manifest.permission_group}) or in more rare cases to one defined by +yourself. It is preferred to use an existing group, as this simplifies the +permission UI shown to the user.</p> + +<p>Note that both a label and description should be supplied for the +permission. These are string resources that can be displayed to the user when +they are viewing a list of permissions +(<code>{@link android.R.styleable#AndroidManifestPermission_label android:label}</code>) +or details on a single permission ( +<code>{@link android.R.styleable#AndroidManifestPermission_description android:description}</code>). +The label should be short, a few words +describing the key piece of functionality the permission is protecting. The +description should be a couple sentences describing what the permission allows +a holder to do. Our convention for the description is two sentences, the first +describing the permission, the second warning the user of what bad things +can happen if an application is granted the permission.</p> + +<p>Here is an example of a label and description for the CALL_PHONE +permission:</p> + +<pre> + <string name="permlab_callPhone">directly call phone numbers</string> + <string name="permdesc_callPhone">Allows the application to call + phone numbers without your intervention. Malicious applications may + cause unexpected calls on your phone bill. Note that this does not + allow the application to call emergency numbers.</string> +</pre> + +<p>You can look at the permissions currently defined in the system with the +Settings app and the shell command <code>adb shell pm list permissions</code>. +To use the Settings app, go to Settings > Applications. Pick an app and +scroll down to see the permissions that the app uses. For developers, the adb '-s' +option displays the permissions in a form similar to how the user will see them:</p> + +<pre> +$ adb shell pm list permissions -s +All Permissions: + +Network communication: view Wi-Fi state, create Bluetooth connections, full +Internet access, view network state + +Your location: access extra location provider commands, fine (GPS) location, +mock location sources for testing, coarse (network-based) location + +Services that cost you money: send SMS messages, directly call phone numbers + +...</pre> + +<a name="manifest"></a> +<h3>Enforcing Permissions in AndroidManifest.xml</h3> + +<p>High-level permissions restricting access to entire components of the +system or application can be applied through your +<code>AndroidManifest.xml</code>. All that this requires is including an {@link +android.R.attr#permission android:permission} attribute on the desired +component, naming the permission that will be used to control access to +it.</p> + +<p><strong>{@link android.app.Activity}</strong> permissions +(applied to the +{@link android.R.styleable#AndroidManifestActivity <activity>} tag) +restrict who can start the associated +activity. The permission is checked during +{@link android.content.Context#startActivity Context.startActivity()} and +{@link android.app.Activity#startActivityForResult Activity.startActivityForResult()}; +if the caller does not have +the required permission then {@link java.lang.SecurityException} is thrown +from the call.</p> + +<p><strong>{@link android.app.Service}</strong> permissions +(applied to the +{@link android.R.styleable#AndroidManifestService <service>} tag) +restrict who can start or bind to the +associated service. The permission is checked during +{@link android.content.Context#startService Context.startService()}, +{@link android.content.Context#stopService Context.stopService()} and +{@link android.content.Context#bindService Context.bindService()}; +if the caller does not have +the required permission then {@link java.lang.SecurityException} is thrown +from the call.</p> + +<p><strong>{@link android.content.BroadcastReceiver}</strong> permissions +(applied to the +{@link android.R.styleable#AndroidManifestReceiver <receiver>} tag) +restrict who can send broadcasts to the associated receiver. +The permission is checked <em>after</em> +{@link android.content.Context#sendBroadcast Context.sendBroadcast()} returns, +as the system tries +to deliver the submitted broadcast to the given receiver. As a result, a +permission failure will not result in an exception being thrown back to the +caller; it will just not deliver the intent. In the same way, a permission +can be supplied to +{@link android.content.Context#registerReceiver(android.content.BroadcastReceiver, android.content.IntentFilter, String, android.os.Handler) +Context.registerReceiver()} +to control who can broadcast to a programmatically registered receiver. +Going the other way, a permission can be supplied when calling +{@link android.content.Context#sendBroadcast(Intent, String) Context.sendBroadcast()} +to restrict which BroadcastReceiver objects are allowed to receive the broadcast (see +below).</p> + +<p><strong>{@link android.content.ContentProvider}</strong> permissions +(applied to the +{@link android.R.styleable#AndroidManifestProvider <provider>} tag) +restrict who can access the data in +a {@link android.content.ContentProvider}. (Content providers have an important +additional security facility available to them called +<a href="#uri">URI permissions</a> which is described later.) +Unlike the other components, +there are two separate permission attributes you can set: +{@link android.R.attr#readPermission android:readPermission} restricts who +can read from the provider, and +{@link android.R.attr#writePermission android:writePermission} restricts +who can write to it. Note that if a provider is protected with both a read +and write permission, holding only the write permission does not mean +you can read from a provider. The permissions are checked when you first +retrieve a provider (if you don't have either permission, a SecurityException +will be thrown), and as you perform operations on the provider. Using +{@link android.content.ContentResolver#query ContentResolver.query()} requires +holding the read permission; using +{@link android.content.ContentResolver#insert ContentResolver.insert()}, +{@link android.content.ContentResolver#update ContentResolver.update()}, +{@link android.content.ContentResolver#delete ContentResolver.delete()} +requires the write permission. +In all of these cases, not holding the required permission results in a +{@link java.lang.SecurityException} being thrown from the call.</p> + + +<a name="broadcasts"></a> +<h3>Enforcing Permissions when Sending Broadcasts</h3> + +<p>In addition to the permission enforcing who can send Intents to a +registered {@link android.content.BroadcastReceiver} (as described above), you +can also specify a required permission when sending a broadcast. By calling {@link +android.content.Context#sendBroadcast(android.content.Intent,String) +Context.sendBroadcast()} with a +permission string, you require that a receiver's application must hold that +permission in order to receive your broadcast.</p> + +<p>Note that both a receiver and a broadcaster can require a permission. When +this happens, both permission checks must pass for the Intent to be delivered +to the associated target.</p> + + +<a name="enforcement"></a> +<h3>Other Permission Enforcement</h3> + +<p>Arbitrarily fine-grained permissions can be enforced at any call into a +service. This is accomplished with the {@link +android.content.Context#checkCallingPermission Context.checkCallingPermission()} +method. Call with a desired +permission string and it will return an integer indicating whether that +permission has been granted to the current calling process. Note that this can +only be used when you are executing a call coming in from another process, +usually through an IDL interface published from a service or in some other way +given to another process.</p> + +<p>There are a number of other useful ways to check permissions. If you have +the pid of another process, you can use the Context method {@link +android.content.Context#checkPermission(String, int, int) Context.checkPermission(String, int, int)} +to check a permission against that pid. If you have the package name of another +application, you can use the direct PackageManager method {@link +android.content.pm.PackageManager#checkPermission(String, String) +PackageManager.checkPermission(String, String)} +to find out whether that particular package has been granted a specific permission.</p> + + +<a name="uri"></a> +<h2>URI Permissions</h2> + +<p>The standard permission system described so far is often not sufficient +when used with content providers. A content provider may want to +protect itself with read and write permissions, while its direct clients +also need to hand specific URIs to other applications for them to operate on. +A typical example is attachments in a mail application. Access to the mail +should be protected by permissions, since this is sensitive user data. However, +if a URI to an image attachment is given to an image viewer, that image viewer +will not have permission to open the attachment since it has no reason to hold +a permission to access all e-mail.</p> + +<p>The solution to this problem is per-URI permissions: when starting an +activity or returning a result to an activity, the caller can set +{@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION +Intent.FLAG_GRANT_READ_URI_PERMISSION} and/or +{@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION +Intent.FLAG_GRANT_WRITE_URI_PERMISSION}. This grants the receiving activity +permission access the specific data URI in the Intent, regardless of whether +it has any permission to access data in the content provider corresponding +to the Intent.</p> + +<p>This mechanism allows a common capability-style model where user interaction +(opening an attachment, selecting a contact from a list, etc) drives ad-hoc +granting of fine-grained permission. This can be a key facility for reducing +the permissions needed by applications to only those directly related to their +behavior.</p> + +<p>The granting of fine-grained URI permissions does, however, require some +cooperation with the content provider holding those URIs. It is strongly +recommended that content providers implement this facility, and declare that +they support it through the +{@link android.R.styleable#AndroidManifestProvider_grantUriPermissions +android:grantUriPermissions} attribute or +{@link android.R.styleable#AndroidManifestGrantUriPermission +<grant-uri-permissions>} tag.</p> + +<p>More information can be found in the +{@link android.content.Context#grantUriPermission Context.grantUriPermission()}, +{@link android.content.Context#revokeUriPermission Context.revokeUriPermission()}, and +{@link android.content.Context#checkUriPermission Context.checkUriPermission()} +methods.</p> + diff --git a/docs/html/guide/topics/security/security.jd b/docs/html/guide/topics/security/security.jd index 1fd9ba0..eeaac44 100644 --- a/docs/html/guide/topics/security/security.jd +++ b/docs/html/guide/topics/security/security.jd @@ -1,407 +1,770 @@ -page.title=Security and Permissions +page.title=Designing for Security @jd:body <div id="qv-wrapper"> <div id="qv"> - <h2>In this document</h2> <ol> -<li><a href="#arch">Security Architecture</a></li> -<li><a href="#signing">Application Signing</a></li> -<li><a href="#userid">User IDs and File Access</a></li> -<li><a href="#permissions">Using Permissions</a></li> -<li><a href="#declaring">Declaring and Enforcing Permissions</a> - <ol> - <li><a href="#manifest">...in AndroidManifest.xml</a></li> - <li><a href="#broadcasts">...when Sending Broadcasts</a></li> - <li><a href="#enforcement">Other Permission Enforcement</a></li> - </ol></li> -<li><a href="#uri">URI Permissions</a></li> +<li><a href="#Dalvik">Using Davlik Code</a></li> +<li><a href="#Native">Using Native Code</a></li> +<li><a href="#Data">Storing Data</a></li> +<li><a href="#IPC">Using IPC</a></li> +<li><a href="#Permissions">Using Permissions</a></li> +<li><a href="#Networking">Using Networking</a></li> +<li><a href="#DynamicCode">Dynamically Loading Code</a></li> +<li><a href="#Input">Performing Input Validation</a></li> +<li><a href="#UserData">Handling User Data</a></li> +<li><a href="#Crypto">Using Cryptography</a></li> </ol> -</div> -</div> -<p>This document describes how application developers can use the -security features provided by Android. A more general <a -href="http://source.android.com/tech/security/index.html"> Android Security -Overview</a> is provided in the Android Open Source Project.</p> - -<p>Android is a privilege-separated operating system, in which each -application runs with a distinct system identity (Linux user ID and group -ID). Parts of the system are also separated into distinct identities. -Linux thereby isolates applications from each other and from the system.</p> - -<p>Additional finer-grained security features are provided through a -"permission" mechanism that enforces restrictions on the specific operations -that a particular process can perform, and per-URI permissions for granting -ad-hoc access to specific pieces of data.</p> - -<a name="arch"></a> -<h2>Security Architecture</h2> - -<p>A central design point of the Android security architecture is that no -application, by default, has permission to perform any operations that would -adversely impact other applications, the operating system, or the user. This -includes reading or writing the user's private data (such as contacts or -e-mails), reading or writing another application's files, performing -network access, keeping the device awake, etc.</p> - -<p>Because Android sandboxes applications from each other, applications -must explicitly share resources and data. They do this by declaring the -<em>permissions</em> they need for additional capabilities not provided by -the basic sandbox. Applications statically declare the permissions they -require, and the Android system prompts the user for consent at the time the -application is installed. Android has no mechanism for granting permissions -dynamically (at run-time) because it complicates the user experience to the -detriment of security.</p> - -<p>The application sandbox does not depend on the technology used to build -an application. In particular the Dalvik VM is not a security boundary, and -any app can run native code (see <a href="/sdk/ndk/index.html">the Android -NDK</a>). All types of applications — Java, native, and hybrid — -are sandboxed in the same way and have the same degree of security from each -other.</p> - -<a name="signing"></a> -<h2>Application Signing</h2> - -<p>All Android applications (.apk files) must be signed with a certificate -whose private key is held by their developer. This certificate identifies -the author of the application. The certificate does <em>not</em> need to be -signed by a certificate authority: it is perfectly allowable, and typical, -for Android applications to use self-signed certificates. The purpose of -certificates in Android is to distinguish application authors. This allows -the system to grant or deny applications access to <a -href="/guide/topics/manifest/permission-element.html#plevel">signature-level -permissions</a> and to grant or deny an application's <a -href="/guide/topics/manifest/manifest-element.html#uid">request to be given -the same Linux identity</a> as another application.</p> - -<a name="userid"></a> -<h2>User IDs and File Access</h2> - -<p>At install time, Android gives each package a distinct Linux user ID. The -identity remains constant for the duration of the package's life on that -device. On a different device, the same package may have a different UID; -what matters is that each package has a distinct UID on a given device.</p> - -<p>Because security enforcement happens at the -process level, the code of any two packages can not normally -run in the same process, since they need to run as different Linux users. -You can use the {@link android.R.attr#sharedUserId} attribute in the -<code>AndroidManifest.xml</code>'s -{@link android.R.styleable#AndroidManifest manifest} tag of each package to -have them assigned the same user ID. By doing this, for purposes of security -the two packages are then treated as being the same application, with the same -user ID and file permissions. Note that in order to retain security, only two applications -signed with the same signature (and requesting the same sharedUserId) will -be given the same user ID.</p> - -<p>Any data stored by an application will be assigned that application's user -ID, and not normally accessible to other packages. When creating a new file -with {@link android.content.Context#getSharedPreferences}, -{@link android.content.Context#openFileOutput}, or -{@link android.content.Context#openOrCreateDatabase}, -you can use the -{@link android.content.Context#MODE_WORLD_READABLE} and/or -{@link android.content.Context#MODE_WORLD_WRITEABLE} flags to allow any other -package to read/write the file. When setting these flags, the file is still -owned by your application, but its global read and/or write permissions have -been set appropriately so any other application can see it.</p> - - -<a name="permissions"></a> -<h2>Using Permissions</h2> - -<p>A basic Android application has no permissions associated with it, -meaning it can not do anything that would adversely impact the user experience -or any data on the device. To make use of protected features of the device, -you must include in your <code>AndroidManifest.xml</code> one or more -<code>{@link android.R.styleable#AndroidManifestUsesPermission <uses-permission>}</code> -tags declaring the permissions that your application needs.</p> - -<p>For example, an application that needs to monitor incoming SMS messages would -specify:</p> - -<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android" - package="com.android.app.myapp" > - <uses-permission android:name="android.permission.RECEIVE_SMS" /> - ... -</manifest></pre> - -<p>At application install time, permissions requested by the application are -granted to it by the package installer, based on checks against the -signatures of the applications declaring those permissions and/or interaction -with the user. <em>No</em> checks with the user -are done while an application is running: it either was granted a particular -permission when installed, and can use that feature as desired, or the -permission was not granted and any attempt to use the feature will fail -without prompting the user.</p> - -<p>Often times a permission failure will result in a {@link -java.lang.SecurityException} being thrown back to the application. However, -this is not guaranteed to occur everywhere. For example, the {@link -android.content.Context#sendBroadcast} method checks permissions as data is -being delivered to each receiver, after the method call has returned, so you -will not receive an exception if there are permission failures. In almost all -cases, however, a permission failure will be printed to the system log.</p> - -<p>The permissions provided by the Android system can be found at {@link -android.Manifest.permission}. Any application may also define and enforce its -own permissions, so this is not a comprehensive list of all possible +<h2>See also</h2> +<ol> +<li><a href="http://source.android.com/tech/security/index.html">Android +Security Overview</a></li> +<li><a href="{@docRoot}guide/topics/security/security.html">Android Security +And Permissions</a></li> +</ol> +</div></div> +<p>Android was designed so that most developers will be able to build +applications using the default settings and not be confronted with difficult +decisions about security. Android also has a number of security features built +into the operating system that significantly reduce the frequency and impact of +application security issues.</p> + +<p>Some of the security features that help developers build secure applications +include: +<ul> +<li>The Android Application Sandbox that isolates data and code execution on a +per-application basis.</li> +<li>Android application framework with robust implementations of common +security functionality such as cryptography, permissions, and secure IPC.</li> +<li>Technologies like ASLR, NX, ProPolice, safe_iop, OpenBSD dlmalloc, OpenBSD +calloc, and Linux mmap_min_addr to mitigate risks associated with common memory +management errors</li> +<li>An encrypted filesystem that can be enabled to protect data on lost or +stolen devices.</li> +</ul></p> + +<p>Nevertheless, it is important for developers to be familiar with Android +security best practices to make sure they take advantage of these capabilities +and to reduce the likelihood of inadvertently introducing security issues that +can affect their applications.</p> + +<p>This document is organized around common APIs and development techniques +that can have security implications for your application and its users. As +these best practices are constantly evolving, we recommend you check back +occasionally throughout your application development process.</p> + +<a name="Dalvik"></a> +<h2>Using Dalvik Code</h2> +<p>Writing secure code that runs in virtual machines is a well-studied topic +and many of the issues are not specific to Android. Rather than attempting to +rehash these topics, we’d recommend that you familiarize yourself with the +existing literature. Two of the more popular resources are: +<ul> +<li><a href="http://www.securingjava.com/toc.html"> +http://www.securingjava.com/toc.html</a></li> +<li><a +href="https://www.owasp.org/index.php/Java_Security_Resources"> +https://www.owasp.org/index.php/Java_Security_Resources</a></li> +</ul></p> + +<p>This document is focused on the areas which are Android specific and/or +different from other environments. For developers experienced with VM +programming in other environments, there are two broad issues that may be +different about writing apps for Android: +<ul> +<li>Some virtual machines, such as the JVM or .net runtime, act as a security +boundary, isolating code from the underlying operating system capabilities. On +Android, the Dalvik VM is not a security boundary -- the application sandbox is +implemented at the OS level, so Dalvik can interoperate with native code in the +same application without any security constraints.</li> +<li>Given the limited storage on mobile devices, it’s common for developers +to want to build modular applications and use dynamic class loading. When +doing this consider both the source where you retrieve your application logic +and where you store it locally. Do not use dynamic class loading from sources +that are not verified, such as unsecured network sources or external storage, +since that code can be modified to include malicious behavior.</li> +</ul></p> + +<a name="Native"></a> +<h2>Using Native Code</h2> + +<p>In general, we encourage developers to use the Android SDK for most +application development, rather than using native code. Applications built +with native code are more complex, less portable, and more like to include +common memory corruption errors such as buffer overflows.</p> + +<p>Android is built using the Linux kernel and being familiar with Linux +development security best practices is especially useful if you are going to +use native code. This document is too short to discuss all of those best +practices, but one of the most popular resources is “Secure Programming for +Linux and Unix HOWTO”, available at <a +href="http://www.dwheeler.com/secure-programs"> +http://www.dwheeler.com/secure-programs</a>.</p> + +<p>An important difference between Android and most Linux environments is the +Application Sandbox. On Android, all applications run in the Application +Sandbox, including those written with native code. At the most basic level, a +good way to think about it for developers familiar with Linux is to know that +every application is given a unique UID with very limited permissions. This is +discussed in more detail in the <a +href="http://source.android.com/tech/security/index.html">Android Security +Overview</a> and you should be familiar with application permissions even if +you are using native code.</p> + +<a name="Data"></a> +<h2>Storing Data</h2> + +<h3>Using internal files</h3> + +<p>By default, files created on <a +href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal +storage</a> are only accessible to the application that created the file. This +protection is implemented by Android and is sufficient for most +applications.</p> + +<p>Use of <a +href="{@docRoot}reference/android/content/Context.html#MODE_WORLD_WRITEABLE"> +world writable</a> or <a +href="{@docRoot}reference/android/content/Context.html#MODE_WORLD_READABLE">world +readable</a> files for IPC is discouraged because it does not provide +the ability to limit data access to particular applications, nor does it +provide any control on data format. As an alternative, you might consider using +a ContentProvider which provides read and write permissions, and can make +dynamic permission grants on a case-by-case basis.</p> + +<p>To provide additional protection for sensitive data, some applications +choose to encrypt local files using a key that is not accessible to the +application. (For example, a key can be placed in a <code><a +href={@docRoot}reference/java/security/KeyStore.html">KeyStore</a></code> and +protected with a user password that is not stored on the device). While this +does not protect data from a root compromise that can monitor the user +inputting the password, it can provide protection for a lost device without <a +href="http://source.android.com/tech/encryption/index.html">file system +encryption</a>.</p> + +<h3>Using external storage</h3> + +<p>Files created on <a +href="{@docRoot}guide/topics/data/data-storage.html#filesExternal">external +storage</a>, such as SD Cards, are globally readable and writable. Since +external storage can be removed by the user and also modified by any +application, applications should not store sensitive information using +external storage.</p> + +<p>As with data from any untrusted source, applications should perform input +validation when handling data from external storage (see Input Validation +section). We strongly recommend that applications not store executables or +class files on external storage prior to dynamic loading. If an application +does retrieve executable files from external storage they should be signed and +cryptographically verified prior to dynamic loading.</p> + +<h3>Using content providers</h3> + +<p>ContentProviders provide a structured storage mechanism that can be limited +to your own application, or exported to allow access by other applications. By +default, a <code> +<a href="{@docRoot}reference/android/content/ContentProvider.html"> +ContentProvider</a></code> is +<a href="{@docRoot}guide/topics/manifest/provider-element.html#exported">exported +</a> for use by other applications. If you do not intend to provide other +applications with access to your<code> +<a href="{@docRoot}reference/android/content/ContentProvider.html"> +ContentProvider</a></code>, mark them as <code><a +href="{@docRoot}guide/topics/manifest/provider-element.html#exported"> +android:exported=false</a></code> in the application manifest.</p> + +<p>When creating a <code> +<a href="{@docRoot}reference/android/content/ContentProvider.html">ContentProvider +</a></code> that will be exported for use by other applications, you can specify +a single +<a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">permission +</a> for reading and writing, or distinct permissions for reading and writing +within the manifest. We recommend that you limit your permissions to those +required to accomplish the task at hand. Keep in mind that it’s usually +easier to add permissions later to expose new functionality than it is to take +them away and break existing users.</p> + +<p>If you are using a <code> +<a href="{@docRoot}reference/android/content/ContentProvider.html"> +ContentProvider</a></code> for sharing data between applications built by the +same developer, it is preferable to use +<a href="{@docRoot}guide/topics/manifest/permission-element.html#plevel">signature +level permissions</a>. Signature permissions do not require user confirmation, +so they provide a better user experience and more controlled access to the +<code> +<a href="{@docRoot}reference/android/content/ContentProvider.html"> +ContentProvider</a></code>.</p> + +<p>ContentProviders can also provide more granular access by declaring the <a +href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn"> +grantUriPermissions</a> element and using the <code><a +href="{@docRoot}reference/android/content/Intent.html#FLAG_GRANT_READ_URI_PERMISSION">FLAG_GRANT_READ_URI_PERMISSION</a></code> +and <code><a +href="{@docRoot}reference/android/content/Intent.html#FLAG_GRANT_WRITE_URI_PERMISSION">FLAG_GRANT_WRITE_URI_PERMISSION</a></code> +flags in the Intent object +that activates the component. The scope of these permissions can be further +limited by the <code><a +href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"> +grant-uri-permission element</a></code>.</p> + +<p>When accessing a <code> +<a href="{@docRoot}reference/android/content/ContentProvider.html"> +ContentProvider</a></code>, use parameterized query methods such as <code> +<a href="{@docRoot}reference/android/content/ContentProvider.html#query(android.net.Uri,%20java.lang.String[],%20java.lang.String,%20java.lang.String[],%20java.lang.String)">query()</a></code>, <code><a +href="{@docRoot}reference/android/content/ContentProvider.html#update(android.net.Uri,%20android.content.ContentValues,%20java.lang.String,%20java.lang.String[])">update()</a></code>, and <code><a +href="{@docRoot}reference/android/content/ContentProvider.html#delete(android.net.Uri,%20java.lang.String,%20java.lang.String[])">delete()</a></code> to avoid +potential <a href="http://en.wikipedia.org/wiki/SQL_injection">SQL +Injection</a> from untrusted data. Note that using parameterized methods is not +sufficient if the <code>selection</code> is built by concatenating user data +prior to submitting it to the method.</p> + +<p>Do not have a false sense of security about the write permission. Consider +that the write permission allows SQL statements which make it possible for some +data to be confirmed using creative <code>WHERE</code> clauses and parsing the +results. For example, an attacker might probe for presence of a specific phone +number in a call-log by modifying a row only if that phone number already +exists. If the content provider data has predictable structure, the write +permission may be equivalent to providing both reading and writing.</p> + +<a name="IPC"></a> +<h2>Using Interprocess Communication (IPC)</h2> + +<p>Some Android applications attempt to implement IPC using traditional Linux +techniques such as network sockets and shared files. We strongly encourage the +use of Android system functionality for IPC such as Intents, Binders, Services, +and Receivers. The Android IPC mechanisms allow you to verify the identity of +the application connecting to your IPC and set security policy for each IPC +mechanism.</p> + +<p>Many of the security elements are shared across IPC mechanisms. <a +href="{@docRoot}reference/android/content/BroadcastReceiver.html"> +Broadcast Receivers</a>, <a +href="{@docRoot}reference/android/R.styleable.html#AndroidManifestActivity"> +Activities</a>, and <a +href="{@docRoot}reference/android/R.styleable.html#AndroidManifestService"> +Services</a> are all declared in the application manifest. If your IPC mechanism is +not intended for use by other applications, set the <a +href="{@docRoot}guide/topics/manifest/service-element.html#exported">{@code android:exported}</a> +property to false. This is useful for applications that consist of multiple processes +within the same UID, or if you decide late in development that you do not +actually want to expose functionality as IPC but you don’t want to rewrite +the code.</p> + +<p>If your IPC is intended to be accessible to other applications, you can +apply a security policy by using the <a +href="{@docRoot}reference/android/R.styleable.html#AndroidManifestPermission"> +Permission</a> tag. If IPC is between applications built by the same developer, +it is preferable to use <a +href="{@docRoot}guide/topics/manifest/permission-element.html#plevel">signature +level permissions</a>. Signature permissions do not require user confirmation, +so they provide a better user experience and more controlled access to the IPC +mechanism.</p> + +<p>One area that can introduce confusion is the use of intent filters. Note +that Intent filters should not be considered a security feature -- components +can be invoked directly and may not have data that would conform to the intent +filter. You should perform input validation within your intent receiver to +confirm that it is properly formatted for the invoked receiver, service, or +activity.</p> + +<h3>Using intents</h3> + +<p>Intents are the preferred mechanism for asynchronous IPC in Android. +Depending on your application requirements, you might use <code><a +href="{@docRoot}reference/android/content/Context.html#sendBroadcast(android.content.Intent)">sendBroadcast()</a></code>, +<code><a +href="{@docRoot}reference/android/content/Context.html#sendOrderedBroadcast(android.content.Intent,%20java.lang.String)">sendOrderedBroadcast()</a></code>, +or direct an intent to a specific application component.</p> + +<p>Note that ordered broadcasts can be “consumed” by a recipient, so they +may not be delivered to all applications. If you are sending an Intent where +delivery to a specific receiver is required, the intent must be delivered +directly to the receiver.</p> + +<p>Senders of an intent can verify that the recipient has a permission +specifying a non-Null Permission upon sending. Only applications with that +Permission will receive the intent. If data within a broadcast intent may be +sensitive, you should consider applying a permission to make sure that +malicious applications cannot register to receive those messages without +appropriate permissions. In those circumstances, you may also consider +invoking the receiver directly, rather than raising a broadcast.</p> + +<h3>Using binder and AIDL interfaces</h3> + +<p><a href="{@docRoot}reference/android/os/Binder.html">Binders</a> are the +preferred mechanism for RPC-style IPC in Android. They provide a well-defined +interface that enables mutual authentication of the endpoints, if required.</p> + +<p>We strongly encourage designing interfaces in a manner that does not require +interface specific permission checks. Binders are not declared within the +application manifest, and therefore you cannot apply declarative permissions +directly to a Binder. Binders generally inherit permissions declared in the +application manifest for the Service or Activity within which they are +implemented. If you are creating an interface that requires authentication +and/or access controls on a specific binder interface, those controls must be +explicitly added as code in the interface.</p> + +<p>If providing an interface that does require access controls, use <code><a +href="{@docRoot}reference/android/content/Context.html#checkCallingPermission(java.lang.String)">checkCallingPermission()</a></code> +to verify whether the +caller of the Binder has a required permission. This is especially important +before accessing a Service on behalf of the caller, as the identify of your +application is passed to other interfaces. If invoking an interface provided +by a Service, the <code><a +href="{@docRoot}reference/android/content/Context.html#bindService(android.content.Intent,%20android.content.ServiceConnection,%20int)">bindService()</a></code> + invocation may fail if you do not have permission to access the given Service. + If calling an interface provided locally by your own application, it may be +useful to use the <code><a +href="{@docRoot}reference/android/os/Binder.html#clearCallingIdentity()"> +clearCallingIdentity()</a></code> to satisfy internal security checks.</p> + +<h3>Using broadcast receivers</h3> + +<p>Broadcast receivers are used to handle asynchronous requests initiated via +an intent.</p> + +<p>By default, receivers are exported and can be invoked by any other +application. If your <code><a +href="{@docRoot}reference/android/content/BroadcastReceiver.html"> +BroadcastReceivers</a></code> is intended for use by other applications, you +may want to apply security permissions to receivers using the <code><a +href="{@docRoot}guide/topics/manifest/receiver-element.html"> +<receiver></a></code> element within the application manifest. This will +prevent applications without appropriate permissions from sending an intent to +the <code><a +href="{@docRoot}reference/android/content/BroadcastReceiver.html"> +BroadcastReceivers</a></code>.</p> + +<h3>Using Services</h3> + +<p>Services are often used to supply functionality for other applications to +use. Each service class must have a corresponding <service> declaration in its +package's AndroidManifest.xml.</p> + +<p>By default, Services are exported and can be invoked by any other +application. Services can be protected using the <a +href="{@docRoot}guide/topics/manifest/service-element.html#prmsn">{@code android:permission}</a> +attribute +within the manifest’s <code><a +href="{@docRoot}guide/topics/manifest/service-element.html"> +<service></a></code> tag. By doing so, other applications will need to declare +a corresponding <code><a +href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a> +</code> element in their own manifest to be +able to start, stop, or bind to the service.</p> + +<p>A Service can protect individual IPC calls into it with permissions, by +calling <code><a +href="{@docRoot}reference/android/content/Context.html#checkCallingPermission(java.lang.String)">checkCallingPermission()</a></code> +before executing +the implementation of that call. We generally recommend using the +declarative permissions in the manifest, since those are less prone to +oversight.</p> + +<h3>Using Activities</h3> + +<p>Activities are most often used for providing the core user-facing +functionality of an application. By default, Activities are exported and +invokable by other applications only if they have an intent filter or binder +declared. In general, we recommend that you specifically declare a Receiver or +Service to handle IPC, since this modular approach reduces the risk of exposing +functionality that is not intended for use by other applications.</p> + +<p>If you do expose an Activity for purposes of IPC, the <code><a +href="{@docRoot}guide/topics/manifest/activity-element.html#prmsn">android:permission</a></code> +attribute in the <code><a +href="{@docRoot}guide/topics/manifest/activity-element.html"> +<activity></a></code> declaration in the application manifest can be used to +restrict access to only those applications which have the stated permissions.</p> -<p>A particular permission may be enforced at a number of places during your -program's operation:</p> +<a name="Permissions"></a> +<h2>Using Permissions</h2> +<h3>Requesting Permissions</h3> + +<p>We recommend minimizing the number of permissions requested by an +application. Not having access to sensitive permissions reduces the risk of +inadvertently misusing those permissions, can improve user adoption, and makes +applications less attractive targets for attackers.</p> + +<p>If it is possible to design your application in a way that does not require +a permission, that is preferable. For example, rather than requesting access +to device information to create an identifier, create a <a +href="{@docRoot}reference/java/util/UUID.html">GUID</a> for your application. +(This specific example is also discussed in Handling User Data) Or, rather than +using external storage, store data in your application directory.</p> + +<p>If a permission is not required, do not request it. This sounds simple, but +there has been quite a bit of research into the frequency of over-requesting +permissions. If you’re interested in the subject you might start with this +research paper published by U.C. Berkeley: <a +href="http://www.eecs.berkeley.edu/Pubs/TechRpts/2011/EECS-2011-48.pdf"> +http://www.eecs.berkeley.edu/Pubs/TechRpts/2011/EECS-2011-48.pdf</a></p> + +<p>In addition to requesting permissions, your application can use <a +href="{@docRoot}guide/topics/manifest/permission-element.html">permissions</a> +to protect IPC that is security sensitive and will be exposed to other +applications -- such as a <code><a +href="{@docRoot}reference/android/content/ContentProvider.html"> +ContentProvider</a></code>. In general, we recommend using access controls +other than user confirmed permissions where possible since permissions can +be confusing for users. For example, consider using the <a +href="{@docRoot}guide/topics/manifest/permission-element.html#plevel">signature +protection level</a> on permissions for IPC communication between applications +provided by a single developer.</p> + +<p>Do not cause permission re-delegation. This occurs when an app exposes data +over IPC that is only available because it has a specific permission, but does +not require that permission of any clients of it’s IPC interface. More +details on the potential impacts, and frequency of this type of problem is +provided in this research paper published at USENIX: <a +href="http://www.cs.berkeley.edu/~afelt/felt_usenixsec2011.pdf">http://www.cs.be +rkeley.edu/~afelt/felt_usenixsec2011.pdf</a></p> + +<h3>Creating Permissions</h3> + +<p>Generally, you should strive to create as few permissions as possible while +satisfying your security requirements. Creating a new permission is relatively +uncommon for most applications, since <a +href="{@docRoot}reference/android/Manifest.permission.html">system-defined +permissions</a> cover many situations. Where appropriate, +perform access checks using existing permissions.</p> + +<p>If you must create a new permission, consider whether you can accomplish +your task with a Signature permission. Signature permissions are transparent +to the user and only allow access by applications signed by the same developer +as application performing the permission check. If you create a Dangerous +permission, then the user needs to decide whether to install the application. +This can be confusing for other developers, as well as for users.</p> + +<p>If you create a Dangerous permission, there are a number of complexities +that you need to consider. <ul> -<li>At the time of a call into the system, to prevent an application from -executing certain functions.</li> -<li>When starting an activity, to prevent applications from launching -activities of other applications.</li> -<li>Both sending and receiving broadcasts, to control who can receive -your broadcast or who can send a broadcast to you.</li> -<li>When accessing and operating on a content provider.</li> -<li>Binding to or starting a service.</li> -</ul> - - -<a name="declaring"></a> -<h2>Declaring and Enforcing Permissions</h2> - -<p>To enforce your own permissions, you must first declare them in your -<code>AndroidManifest.xml</code> using one or more -<code>{@link android.R.styleable#AndroidManifestPermission <permission>}</code> -tags.</p> - -<p>For example, an application that wants to control who can start one -of its activities could declare a permission for this operation as follows:</p> - -<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android" - package="com.me.app.myapp" > - <permission android:name="com.me.app.myapp.permission.DEADLY_ACTIVITY" - android:label="@string/permlab_deadlyActivity" - android:description="@string/permdesc_deadlyActivity" - android:permissionGroup="android.permission-group.COST_MONEY" - android:protectionLevel="dangerous" /> - ... -</manifest></pre> - -<p>The {@link android.R.styleable#AndroidManifestPermission_protectionLevel -<protectionLevel>} attribute is required, telling the system how the -user is to be informed of applications requiring the permission, or who is -allowed to hold that permission, as described in the linked documentation.</p> - -<p>The {@link android.R.styleable#AndroidManifestPermission_permissionGroup -<permissionGroup>} attribute is optional, and only used to help the system display -permissions to the user. You will usually want to set this to either a standard -system group (listed in {@link android.Manifest.permission_group -android.Manifest.permission_group}) or in more rare cases to one defined by -yourself. It is preferred to use an existing group, as this simplifies the -permission UI shown to the user.</p> - -<p>Note that both a label and description should be supplied for the -permission. These are string resources that can be displayed to the user when -they are viewing a list of permissions -(<code>{@link android.R.styleable#AndroidManifestPermission_label android:label}</code>) -or details on a single permission ( -<code>{@link android.R.styleable#AndroidManifestPermission_description android:description}</code>). -The label should be short, a few words -describing the key piece of functionality the permission is protecting. The -description should be a couple sentences describing what the permission allows -a holder to do. Our convention for the description is two sentences, the first -describing the permission, the second warning the user of what bad things -can happen if an application is granted the permission.</p> - -<p>Here is an example of a label and description for the CALL_PHONE -permission:</p> - -<pre> - <string name="permlab_callPhone">directly call phone numbers</string> - <string name="permdesc_callPhone">Allows the application to call - phone numbers without your intervention. Malicious applications may - cause unexpected calls on your phone bill. Note that this does not - allow the application to call emergency numbers.</string> -</pre> - -<p>You can look at the permissions currently defined in the system with the -Settings app and the shell command <code>adb shell pm list permissions</code>. -To use the Settings app, go to Settings > Applications. Pick an app and -scroll down to see the permissions that the app uses. For developers, the adb '-s' -option displays the permissions in a form similar to how the user will see them:</p> - -<pre> -$ adb shell pm list permissions -s -All Permissions: - -Network communication: view Wi-Fi state, create Bluetooth connections, full -Internet access, view network state - -Your location: access extra location provider commands, fine (GPS) location, -mock location sources for testing, coarse (network-based) location - -Services that cost you money: send SMS messages, directly call phone numbers - -...</pre> - -<a name="manifest"></a> -<h3>Enforcing Permissions in AndroidManifest.xml</h3> - -<p>High-level permissions restricting access to entire components of the -system or application can be applied through your -<code>AndroidManifest.xml</code>. All that this requires is including an {@link -android.R.attr#permission android:permission} attribute on the desired -component, naming the permission that will be used to control access to -it.</p> - -<p><strong>{@link android.app.Activity}</strong> permissions -(applied to the -{@link android.R.styleable#AndroidManifestActivity <activity>} tag) -restrict who can start the associated -activity. The permission is checked during -{@link android.content.Context#startActivity Context.startActivity()} and -{@link android.app.Activity#startActivityForResult Activity.startActivityForResult()}; -if the caller does not have -the required permission then {@link java.lang.SecurityException} is thrown -from the call.</p> - -<p><strong>{@link android.app.Service}</strong> permissions -(applied to the -{@link android.R.styleable#AndroidManifestService <service>} tag) -restrict who can start or bind to the -associated service. The permission is checked during -{@link android.content.Context#startService Context.startService()}, -{@link android.content.Context#stopService Context.stopService()} and -{@link android.content.Context#bindService Context.bindService()}; -if the caller does not have -the required permission then {@link java.lang.SecurityException} is thrown -from the call.</p> - -<p><strong>{@link android.content.BroadcastReceiver}</strong> permissions -(applied to the -{@link android.R.styleable#AndroidManifestReceiver <receiver>} tag) -restrict who can send broadcasts to the associated receiver. -The permission is checked <em>after</em> -{@link android.content.Context#sendBroadcast Context.sendBroadcast()} returns, -as the system tries -to deliver the submitted broadcast to the given receiver. As a result, a -permission failure will not result in an exception being thrown back to the -caller; it will just not deliver the intent. In the same way, a permission -can be supplied to -{@link android.content.Context#registerReceiver(android.content.BroadcastReceiver, android.content.IntentFilter, String, android.os.Handler) -Context.registerReceiver()} -to control who can broadcast to a programmatically registered receiver. -Going the other way, a permission can be supplied when calling -{@link android.content.Context#sendBroadcast(Intent, String) Context.sendBroadcast()} -to restrict which BroadcastReceiver objects are allowed to receive the broadcast (see -below).</p> - -<p><strong>{@link android.content.ContentProvider}</strong> permissions -(applied to the -{@link android.R.styleable#AndroidManifestProvider <provider>} tag) -restrict who can access the data in -a {@link android.content.ContentProvider}. (Content providers have an important -additional security facility available to them called -<a href="#uri">URI permissions</a> which is described later.) -Unlike the other components, -there are two separate permission attributes you can set: -{@link android.R.attr#readPermission android:readPermission} restricts who -can read from the provider, and -{@link android.R.attr#writePermission android:writePermission} restricts -who can write to it. Note that if a provider is protected with both a read -and write permission, holding only the write permission does not mean -you can read from a provider. The permissions are checked when you first -retrieve a provider (if you don't have either permission, a SecurityException -will be thrown), and as you perform operations on the provider. Using -{@link android.content.ContentResolver#query ContentResolver.query()} requires -holding the read permission; using -{@link android.content.ContentResolver#insert ContentResolver.insert()}, -{@link android.content.ContentResolver#update ContentResolver.update()}, -{@link android.content.ContentResolver#delete ContentResolver.delete()} -requires the write permission. -In all of these cases, not holding the required permission results in a -{@link java.lang.SecurityException} being thrown from the call.</p> - - -<a name="broadcasts"></a> -<h3>Enforcing Permissions when Sending Broadcasts</h3> - -<p>In addition to the permission enforcing who can send Intents to a -registered {@link android.content.BroadcastReceiver} (as described above), you -can also specify a required permission when sending a broadcast. By calling {@link -android.content.Context#sendBroadcast(android.content.Intent,String) -Context.sendBroadcast()} with a -permission string, you require that a receiver's application must hold that -permission in order to receive your broadcast.</p> - -<p>Note that both a receiver and a broadcaster can require a permission. When -this happens, both permission checks must pass for the Intent to be delivered -to the associated target.</p> - - -<a name="enforcement"></a> -<h3>Other Permission Enforcement</h3> - -<p>Arbitrarily fine-grained permissions can be enforced at any call into a -service. This is accomplished with the {@link -android.content.Context#checkCallingPermission Context.checkCallingPermission()} -method. Call with a desired -permission string and it will return an integer indicating whether that -permission has been granted to the current calling process. Note that this can -only be used when you are executing a call coming in from another process, -usually through an IDL interface published from a service or in some other way -given to another process.</p> - -<p>There are a number of other useful ways to check permissions. If you have -the pid of another process, you can use the Context method {@link -android.content.Context#checkPermission(String, int, int) Context.checkPermission(String, int, int)} -to check a permission against that pid. If you have the package name of another -application, you can use the direct PackageManager method {@link -android.content.pm.PackageManager#checkPermission(String, String) -PackageManager.checkPermission(String, String)} -to find out whether that particular package has been granted a specific permission.</p> - - -<a name="uri"></a> -<h2>URI Permissions</h2> - -<p>The standard permission system described so far is often not sufficient -when used with content providers. A content provider may want to -protect itself with read and write permissions, while its direct clients -also need to hand specific URIs to other applications for them to operate on. -A typical example is attachments in a mail application. Access to the mail -should be protected by permissions, since this is sensitive user data. However, -if a URI to an image attachment is given to an image viewer, that image viewer -will not have permission to open the attachment since it has no reason to hold -a permission to access all e-mail.</p> - -<p>The solution to this problem is per-URI permissions: when starting an -activity or returning a result to an activity, the caller can set -{@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION -Intent.FLAG_GRANT_READ_URI_PERMISSION} and/or -{@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION -Intent.FLAG_GRANT_WRITE_URI_PERMISSION}. This grants the receiving activity -permission access the specific data URI in the Intent, regardless of whether -it has any permission to access data in the content provider corresponding -to the Intent.</p> - -<p>This mechanism allows a common capability-style model where user interaction -(opening an attachment, selecting a contact from a list, etc) drives ad-hoc -granting of fine-grained permission. This can be a key facility for reducing -the permissions needed by applications to only those directly related to their -behavior.</p> - -<p>The granting of fine-grained URI permissions does, however, require some -cooperation with the content provider holding those URIs. It is strongly -recommended that content providers implement this facility, and declare that -they support it through the -{@link android.R.styleable#AndroidManifestProvider_grantUriPermissions -android:grantUriPermissions} attribute or -{@link android.R.styleable#AndroidManifestGrantUriPermission -<grant-uri-permissions>} tag.</p> - -<p>More information can be found in the -{@link android.content.Context#grantUriPermission Context.grantUriPermission()}, -{@link android.content.Context#revokeUriPermission Context.revokeUriPermission()}, and -{@link android.content.Context#checkUriPermission Context.checkUriPermission()} -methods.</p> - +<li>The permission must have a string that concisely expresses to a user the +security decision they will be required to make.</li> +<li>The permission string must be localized to many different languages.</li> +<li>Uses may choose not to install an application because a permission is +confusing or perceived as risky.</li> +<li>Applications may request the permission when the creator of the permission +has not been installed.</li> +</ul></p> + +<p>Each of these poses a significant non-technical challenge for an application +developer, which is why we discourage the use of Dangerous permission.</p> + +<a name="Networking"></a> +<h2>Using Networking</h2> + +<h3>Using IP Networking</h3> + +<p>Networking on Android is not significantly different from Linux +environments. The key consideration is making sure that appropriate protocols +are used for sensitive data, such as <a +href="{@docRoot}reference/javax/net/ssl/HttpsURLConnection.html">HTTPS</a> for +web traffic. We prefer use of HTTPS over HTTP anywhere that HTTPS is +supported on the server, since mobile devices frequently connect on networks +that are not secured, such as public WiFi hotspots.</p> + +<p>Authenticated, encrypted socket-level communication can be easily +implemented using the <code><a +href="{@docRoot}reference/javax/net/ssl/SSLSocket.html">SSLSocket</a></code> +class. Given the frequency with which Android devices connect to unsecured +wireless networks using WiFi, the use of secure networking is strongly +encouraged for all applications.</p> + +<p>We have seen some applications use <a +href="http://en.wikipedia.org/wiki/Localhost">localhost</a> network ports for +handling sensitive IPC. We discourage this approach since these interfaces are +accessible by other applications on the device. Instead, use an Android IPC +mechanism where authentication is possible such as a Service and Binder. (Even +worse than using loopback is to bind to INADDR_ANY since then your application +may receive requests from anywhere. We’ve seen that, too.)</p> + +<p>Also, one common issue that warrants repeating is to make sure that you do +not trust data downloaded from HTTP or other insecure protocols. This includes +validation of input in <code><a +href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code> and +any responses to intents issued against HTTP.</p> + +<h3>Using Telephony Networking</h3> + +<p>SMS is the telephony protocol most frequently used by Android developers. +Developers should keep in mind that this protocol was primarily designed for +user-to-user communication and is not well-suited for some application +purposes. Due to the limitations of SMS, we strongly recommend the use of <a +href="http://code.google.com/android/c2dm/">C2DM</a> and IP networking for +sending data messages to devices.</p> + +<p>Many developers do not realize that SMS is not encrypted or strongly +authenticated on the network or on the device. In particular, any SMS receiver +should expect that a malicious user may have sent the SMS to your application +-- do not rely on unauthenticated SMS data to perform sensitive commands. +Also, you should be aware that SMS may be subject to spoofing and/or +interception on the network. On the Android-powered device itself, SMS +messages are transmitted as Broadcast intents, so they may be read or captured +by other applications that have the READ_SMS permission.</p> + +<a name="DynamicCode"></a> +<h2>Dynamically Loading Code</h2> + +<p>We strongly discourage loading code from outside of the application APK. +Doing so significantly increases the likelihood of application compromise due +to code injection or code tampering. It also adds complexity around version +management and application testing. Finally, it can make it impossible to +verify the behavior of an application, so it may be prohibited in some +environments.</p> + +<p>If your application does dynamically load code, the most important thing to +keep in mind about dynamically loaded code is that it runs with the same +security permissions as the application APK. The user made a decision to +install your application based on your identity, and they are expecting that +you provide any code run within the application, including code that is +dynamically loaded.</p> + +<p>The major security risk associated with dynamically loading code is that the +code needs to come from a verifiable source. If the modules are included +directly within your APK, then they cannot be modified by other applications. +This is true whether the code is a native library or a class being loaded using +<a href="{@docRoot}reference/dalvik/system/DexClassLoader.html"> +<code>DexClassLoader</code></a>. We have seen many instances of applications +attempting to load code from insecure locations, such as downloaded from the +network over unencrypted protocols or from world writable locations such as +external storage. These locations could allow someone on the network to modify +the content in transit, or another application on a users device to modify the +content, respectively.</p> + + +<h3>Using WebView</h3> + +<p>Since WebView consumes web content that can include HTML and JavaScript, +improper use can introduce common web security issues such as <a +href="http://en.wikipedia.org/wiki/Cross_site_scripting">cross-site-scripting</a +> (JavaScript injection). Android includes a number of mechanisms to reduce +the scope of these potential issues by limiting the capability of WebView to +the minimum functionality required by your application.</p> + +<p>If your application does not directly use JavaScript within a <code><a +href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code>, do +not call +<a href="{@docRoot}reference/android/webkit/WebSettings.html#setJavaScriptEnabled(boolean)"> +<code>setJavaScriptEnabled()</code></a>. We have seen this method invoked +in sample code that might be repurposed in production application -- so +remove it if necessary. By default, <code><a +href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code> does +not execute JavaScript so cross-site-scripting is not possible.</p> + +<p>Use <code><a +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> with +particular care because it allows JavaScript to invoke operations that are +normally reserved for Android applications. Only expose <code><a +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> to +sources from which all input is trustworthy. If untrusted input is allowed, +untrusted JavaScript may be able to invoke Android methods. In general, we +recommend only exposing <code><a +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> to +JavaScript that is contained within your application APK.</p> + +<p>Do not trust information downloaded over HTTP, use HTTPS instead. Even if +you are connecting only to a single website that you trust or control, HTTP is +subject to <a +href="http://en.wikipedia.org/wiki/Man-in-the-middle_attack">MiTM</a> attacks +and interception of data. Sensitive capabilities using <code><a +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> should +not ever be exposed to unverified script downloaded over HTTP. Note that even +with the use of HTTPS, +<code><a +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> +increases the attack surface of your application to include the server +infrastructure and all CAs trusted by the Android-powered device.</p> + +<p>If your application accesses sensitive data with a <code><a +href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code>, you +may want to use the <code><a +href="{@docRoot}reference/android/webkit/WebView.html#clearCache(boolean)"> +clearCache()</a></code> method to delete any files stored locally. Server side +headers like no-cache can also be used to indicate that an application should +not cache particular content.</p> + +<a name="Input"></a> +<h2>Performing Input Validation</h2> + +<p>Insufficient input validation is one of the most common security problems +affecting applications, regardless of what platform they run on. Android does +have platform-level countermeasures that reduce the exposure of applications to +input validation issues, you should use those features where possible. Also +note that selection of type-safe languages tends to reduce the likelihood of +input validation issues. We strongly recommend building your applications with +the Android SDK.</p> + +<p>If you are using native code, then any data read from files, received over +the network, or received from an IPC has the potential to introduce a security +issue. The most common problems are <a +href="http://en.wikipedia.org/wiki/Buffer_overflow">buffer overflows</a>, <a +href="http://en.wikipedia.org/wiki/Double_free#Use_after_free">use after +free</a>, and <a +href="http://en.wikipedia.org/wiki/Off-by-one_error">off-by-one errors</a>. +Android provides a number of technologies like ASLR and DEP that reduce the +exploitability of these errors, but they do not solve the underlying problem. +These can be prevented by careful handling of pointers and managing of +buffers.</p> + +<p>Dynamic, string based languages such as JavaScript and SQL are also subject +to input validation problems due to escape characters and <a +href="http://en.wikipedia.org/wiki/Code_injection">script injection</a>.</p> + +<p>If you are using data within queries that are submitted to SQL Database or a +Content Provider, SQL Injection may be an issue. The best defense is to use +parameterized queries, as is discussed in the ContentProviders section. +Limiting permissions to read-only or write-only can also reduce the potential +for harm related to SQL Injection.</p> + +<p>If you are using <code><a +href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code>, then +you must consider the possibility of XSS. If your application does not +directly use JavaScript within a <code><a +href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code>, do +not call setJavaScriptEnabled() and XSS is no longer possible. If you must +enable JavaScript then the WebView section provides other security best +practices.</p> + +<p>If you cannot use the security features above, we strongly recommend the use +of well-structured data formats and verifying that the data conforms to the +expected format. While blacklisting of characters or character-replacement can +be an effective strategy, these techniques are error-prone in practice and +should be avoided when possible.</p> + +<a name="UserData"></a> +<h2>Handling User Data</h2> + +<p>In general, the best approach is to minimize use of APIs that access +sensitive or personal user data. If you have access to data and can avoid +storing or transmitting the information, do not store or transmit the data. +Finally, consider if there is a way that your application logic can be +implemented using a hash or non-reversible form of the data. For example, your +application might use the hash of an an email address as a primary key, to +avoid transmitting or storing the email address. This reduces the chances of +inadvertently exposing data, and it also reduces the chance of attackers +attempting to exploit your application.</p> + +<p>If your application accesses personal information such as passwords or +usernames, keep in mind that some jurisdictions may require you to provide a +privacy policy explaining your use and storage of that data. So following the +security best practice of minimizing access to user data may also simplify +compliance.</p> + +<p>You should also consider whether your application might be inadvertently +exposing personal information to other parties such as third-party components +for advertising or third-party services used by your application. If you don't +know why a component or service requires a personal information, don’t +provide it. In general, reducing the access to personal information by your +application will reduce the potential for problems in this area.</p> + +<p>If access to sensitive data is required, evaluate whether that information +must be transmitted to a server, or whether the operation can be performed on +the client. Consider running any code using sensitive data on the client to +avoid transmitting user data.</p> + +<p>Also, make sure that you do not inadvertently expose user data to other +application on the device through overly permissive IPC, world writable files, +or network sockets. This is a special case of permission redelegation, +discussed in the Requesting Permissions section.</p> + +<p>If a GUID is required, create a large, unique number and store it. Do not +use phone identifiers such as the phone number or IMEI which may be associated +with personal information. This topic is discussed in more detail in the <a +href="http://android-developers.blogspot.com/2011/03/identifying-app-installations.html">Android Developer Blog</a>.</p> + +<p>Application developers should be careful writing to on-device logs. +In Android, logs are a shared resource, and are available +to an application with the +<a href="{@docRoot}reference/android/Manifest.permission.html#READ_LOGS"> +<code>READ_LOGS</code></a> permission. Even though the phone log data +is temporary and erased on reboot, inappropriate logging of user information +could inadvertently leak user data to other applications.</p> + + +<h3>Handling Credentials</h3> + +<p>In general, we recommend minimizing the frequency of asking for user +credentials -- to make phishing attacks more conspicuous, and less likely to be +successful. Instead use an authorization token and refresh it.</p> + +<p>Where possible, username and password should not be stored on the device. +Instead, perform initial authentication using the username and password +supplied by the user, and then use a short-lived, service-specific +authorization token.</p> + +<p>Services that will be accessible to multiple applications should be accessed +using <code> +<a href="{@docRoot}reference/android/accounts/AccountManager.html"> +AccountManager</a></code>. If possible, use the <code><a +href="{@docRoot}reference/android/accounts/AccountManager.html"> +AccountManager</a></code> class to invoke a cloud-based service and do not store +passwords on the device.</p> + +<p>After using <code><a +href="{@docRoot}reference/android/accounts/AccountManager.html"> +AccountManager</a></code> to retrieve an Account, check the <code><a +href="{@docRoot}reference/android/accounts/Account.html#CREATOR">CREATOR</a> +</code> before passing in any credentials, so that you do not inadvertently pass +credentials to the wrong application.</p> + +<p>If credentials are to be used only by applications that you create, then you +can verify the application which accesses the <code><a +href="{@docRoot}reference/android/accounts/AccountManager.html"> +AccountManager</a></code> using <code><a +href="{@docRoot}reference/android/content/pm/PackageManager.html#checkSignatures(java.lang.String,%20java.lang.String)">checkSignature()</a></code>. +Alternatively, if only one application will use the credential, you might use a +<code><a +href={@docRoot}reference/java/security/KeyStore.html">KeyStore</a></code> for +storage.</p> + +<a name="Crypto"></a> +<h2>Using Cryptography</h2> + +<p>In addition to providing data isolation, supporting full-filesystem +encryption, and providing secure communications channels Android provides a +wide array of algorithms for protecting data using cryptography.</p> + +<p>In general, try to use the highest level of pre-existing framework +implementation that can support your use case. If you need to securely +retrieve a file from a known location, a simple HTTPS URI may be adequate and +require no knowledge of cryptography on your part. If you need a secure +tunnel, consider using +<a href="{@docRoot}reference/javax/net/ssl/HttpsURLConnection.html"> +<code>HttpsURLConnection</code></a> or <code><a +href="{@docRoot}reference/javax/net/ssl/SSLSocket.html">SSLSocket</a></code>, +rather than writing your own protocol.</p> + +<p>If you do find yourself needing to implement your own protocol, we strongly +recommend that you not implement your own cryptographic algorithms. Use +existing cryptographic algorithms such as those in the implementation of AES or +RSA provided in the <code><a +href="{@docRoot}reference/javax/crypto/Cipher.html">Cipher</a></code> class.</p> + +<p>Use a secure random number generator ( +<a href="{@docRoot}reference/java/security/SecureRandom.html"> +<code>SecureRandom</code></a>) to initialize any cryptographic keys (<a +href="{@docRoot}reference/javax/crypto/KeyGenerator.html"> +<code>KeyGenerator</code></a>). Use of a key that is not generated with a secure random +number generator significantly weakens the strength of the algorithm, and may +allow offline attacks.</p> + +<p>If you need to store a key for repeated use, use a mechanism like <code><a +href="{@docRoot}reference/java/security/KeyStore.html">KeyStore</a></code> that +provides a mechanism for long term storage and retrieval of cryptographic +keys.</p> + +<h2>Conclusion</h2> + +<p>Android provides developers with the ability to design applications with a +broad range of security requirements. These best practices will help you make +sure that your application takes advantage of the security benefits provided by +the platform.</p> + +<p>You can receive more information on these topics and discuss security best +practices with other developers in the <a +href="http://groups.google.com/group/android-security-discuss">Android Security +Discuss</a> Google Group</p> diff --git a/docs/html/guide/topics/sensors/index.jd b/docs/html/guide/topics/sensors/index.jd index 43903dc..a045899 100644 --- a/docs/html/guide/topics/sensors/index.jd +++ b/docs/html/guide/topics/sensors/index.jd @@ -1,88 +1,40 @@ -page.title=Sensors -@jd:body - -<div id="qv-wrapper"> - <div id="qv"> - <h2>Topics</h2> - <ol> - <li><a href="{@docRoot}guide/topics/sensors/sensors_overview.html">Sensors Overview</a></li> - <li><a href="{@docRoot}guide/topics/sensors/sensors_motion.html">Motion Sensors</a></li> - <li><a href="{@docRoot}guide/topics/sensors/sensors_position.html">Position - Sensors</a></li> - <li><a href="{@docRoot}guide/topics/sensors/sensors_environment.html">Environment - Sensors</a></li> - </ol> - <h2>Key classes and interfaces</h2> - <ol> - <li>{@link android.hardware.Sensor}</li> - <li>{@link android.hardware.SensorEvent}</li> - <li>{@link android.hardware.SensorManager}</li> - <li>{@link android.hardware.SensorEventListener}</li> - </ol> - <h2>Related samples</h2> - <ol> - <li><a href="{@docRoot}resources/samples/AccelerometerPlay/index.html">Accelerometer - Play</a></li> - <li><a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/os/RotationVectorDemo.html"> -API Demos (OS - RotationVectorDemo)</a></li> - <li><a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/os/Sensors.html">API Demos -(OS - Sensors)</a></li> - </ol> - </div> -</div> +page.title=Location and Sensors +page.landing=true +page.landing.intro=Use sensors on the device to add rich location and motion capabilities to your app, from GPS or network location to accelerometer, gyroscope, temperature, barometer, and more. +page.landing.image= -<p>Most Android-powered devices have built-in sensors that measure motion, orientation, -and various environmental conditions. These sensors are capable of providing raw data with high -precision and accuracy, and are useful if you want to monitor three-dimensional device movement or -positioning, or you want to monitor changes in the ambient environment near a device. For example, a -game might track readings from a device's gravity sensor to infer complex user gestures -and motions, such as tilt, shake, rotation, or swing. Likewise, a weather application might use a -device's temperature sensor and humidity sensor to calculate and report the dewpoint, or a travel -application might use the geomagnetic field sensor and accelerometer to report a compass -bearing.</p> +@jd:body -<p>The Android platform supports three broad categories of sensors:</p> +<div class="landing-docs"> -<ul> - <li>Motion sensors - <p>These sensors measure acceleration forces and rotational forces along three axes. This - category includes accelerometers, gravity sensors, gyroscopes, and rotational vector - sensors.</p> - </li> - <li>Environmental sensors - <p>These sensors measure various environmental parameters, such as ambient air temperature - and pressure, illumination, and humidity. This category includes barometers, photometers, and - thermometers.</p> - </li> - <li>Position sensors - <p>These sensors measure the physical position of a device. This category includes - orientation sensors and magnetometers.</p> - </li> -</ul> + <div class="col-6"> + <h3>Blog Articles</h3> + + <a href="http://android-developers.blogspot.com/2010/09/one-screen-turn-deserves-another.html"> + <h4>One Screen Turn Deserves Another</h4> + <p>However, there’s a new wrinkle: recently, a few devices have shipped (see here and here) +that run Android on screens that are naturally landscape in their orientation. That is, when held in +the default position, the screens are wider than they are tall. This introduces a few fairly subtle +issues that we’ve noticed causing problems in some apps.</p> + </a> + + <a href="android-developers.blogspot.com/2011/06/deep-dive-into-location.html"> + <h4>A Deep Dive Into Location</h4> + <p>I’ve written an open-source reference app that incorporates all of the tips, tricks, and +cheats I know to reduce the time between opening an app and seeing an up-to-date list of nearby +venues - as well as providing a reasonable level of offline support</p> + </a> + </div> -<p>To access these sensors, you can use the Android sensor framework. The sensor framework provides -several classes and interfaces that help you perform a wide variety of sensor-related tasks. To -learn more about the framework and the sensors that are supported on the Android system, read the -following documents:</p> + <div class="col-6"> + <h3>Training</h3> + + <a href="http://developer.android.com/training/basics/location/index.html"> + <h4>Making Your App Location Aware</h4> + <p>This class teaches you how to incorporate location based services in your Android +application. You'll learn a number of methods to receive location updates and related best +practices.</p> + </a> + </div> -<dl> - <dt><strong><a href="{@docRoot}guide/topics/sensors/sensors_overview.html">Sensors - Overview</a></strong></dt> - <dd>Learn how to list the sensors that are on a device, set up sensor event listeners, and - acquire sensor data. Also learn best practices for accessing and using sensors.</dd> - <dt><strong><a href="{@docRoot}guide/topics/sensors/sensors_motion.html">Motion - Sensors</a></strong></dt> - <dd>Learn how to use the sensors that provide acceleration data, such as the accelerometer, - gravity sensor, and linear acceleration sensor. Also learn how to use the sensors that - provide rotational data, such as gyroscopes and rotational vector sensors.</dd> - <dt><strong><a href="{@docRoot}guide/topics/sensors/sensors_position.html">Position - Sensors</a></strong></dt> - <dd>Learn how to use the sensors that provide orientation and compass data, such as the - orientation sensor and the geomagnetic field sensor.</dd> - <dt><strong><a href="{@docRoot}guide/topics/sensors/sensors_environment.html">Environment - Sensors</a></strong></dt> - <dd>Learn how to use the sensors that provide environmental data, such as the light, - humidity, pressure, temperature, and proximity sensors.</dd> -</dl> +</div>
\ No newline at end of file diff --git a/docs/html/guide/topics/sensors/sensors_overview.jd b/docs/html/guide/topics/sensors/sensors_overview.jd index 543872c..e38a843 100644 --- a/docs/html/guide/topics/sensors/sensors_overview.jd +++ b/docs/html/guide/topics/sensors/sensors_overview.jd @@ -50,13 +50,39 @@ href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/os/Senso </div> </div> -<p>Most Android-powered devices have sensors that let you monitor changes in device -position and motion. Many devices also have sensors that let you determine ambient environmental -conditions, such as temperature, pressure, humidity, and lighting. You can access these -sensors and acquire raw sensor data by using the Android sensor framework.</p> +<p>Most Android-powered devices have built-in sensors that measure motion, orientation, +and various environmental conditions. These sensors are capable of providing raw data with high +precision and accuracy, and are useful if you want to monitor three-dimensional device movement or +positioning, or you want to monitor changes in the ambient environment near a device. For example, a +game might track readings from a device's gravity sensor to infer complex user gestures +and motions, such as tilt, shake, rotation, or swing. Likewise, a weather application might use a +device's temperature sensor and humidity sensor to calculate and report the dewpoint, or a travel +application might use the geomagnetic field sensor and accelerometer to report a compass +bearing.</p> + +<p>The Android platform supports three broad categories of sensors:</p> -<p>The sensor framework provides several classes and interfaces that help you perform a wide variety -of sensor-related tasks. For example, you can use the sensor framework to do the following:</p> +<ul> + <li>Motion sensors + <p>These sensors measure acceleration forces and rotational forces along three axes. This + category includes accelerometers, gravity sensors, gyroscopes, and rotational vector + sensors.</p> + </li> + <li>Environmental sensors + <p>These sensors measure various environmental parameters, such as ambient air temperature + and pressure, illumination, and humidity. This category includes barometers, photometers, and + thermometers.</p> + </li> + <li>Position sensors + <p>These sensors measure the physical position of a device. This category includes + orientation sensors and magnetometers.</p> + </li> +</ul> + + +<p>You can access sensors available on the device and acquire raw sensor data by using the Android +sensor framework. The sensor framework provides several classes and interfaces that help you perform a wide +variety of sensor-related tasks. For example, you can use the sensor framework to do the following:</p> <ul> <li>Determine which sensors are available on a device.</li> diff --git a/docs/html/guide/topics/testing/activity_testing.jd b/docs/html/guide/topics/testing/activity_testing.jd deleted file mode 100644 index 51121f4..0000000 --- a/docs/html/guide/topics/testing/activity_testing.jd +++ /dev/null @@ -1,394 +0,0 @@ -page.title=Activity Testing -parent.title=Testing -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - <ol> - <li> - <a href="#ActivityTestAPI">The Activity Testing API</a> - <ol> - <li> - <a href="#ActivityInstrumentationTestCase2">ActivityInstrumentationTestCase2</a> - </li> - <li> - <a href="#ActivityUnitTestCase">ActivityUnitTestCase</a> - </li> - <li> - <a href="#SingleLaunchActivityTestCase">SingleLaunchActivityTestCase</a> - </li> - <li> - <a href="#MockObjectNotes">Mock objects and activity testing</a> - </li> - <li> - <a href="#AssertionNotes">Assertions for activity testing</a> - </li> - </ol> - </li> - <li> - <a href="#WhatToTest">What to Test</a> - </li> - <li> - <a href="#NextSteps">Next Steps</a> - </li> - <li> - <a href="#UITesting">Appendix: UI Testing Notes</a> - <ol> - <li> - <a href="#RunOnUIThread">Testing on the UI thread</a> - </li> - <li> - <a href="#NotouchMode">Turning off touch mode</a> - </li> - <li> - <a href="#UnlockDevice">Unlocking the Emulator or Device</a> - </li> - <li> - <a href="#UITestTroubleshooting">Troubleshooting UI tests</a> - </li> - </ol> - </li> - </ol> -<h2>Key Classes</h2> - <ol> - <li>{@link android.test.InstrumentationTestRunner}</li> - <li>{@link android.test.ActivityInstrumentationTestCase2}</li> - <li>{@link android.test.ActivityUnitTestCase}</li> - </ol> -<h2>Related Tutorials</h2> - <ol> - <li> - <a href="{@docRoot}resources/tutorials/testing/helloandroid_test.html"> - Hello, Testing</a> - </li> - <li> - <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> - </li> - </ol> -<h2>See Also</h2> - <ol> - <li> - <a href="{@docRoot}guide/developing/testing/testing_eclipse.html"> - Testing in Eclipse, with ADT</a> - </li> - <li> - <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> - Testing in Other IDEs</a> - </li> - </ol> - </div> -</div> -<p> - Activity testing is particularly dependent on the the Android instrumentation framework. - Unlike other components, activities have a complex lifecycle based on callback methods; these - can't be invoked directly except by instrumentation. Also, the only way to send events to the - user interface from a program is through instrumentation. -</p> -<p> - This document describes how to test activities using instrumentation and other test - facilities. The document assumes you have already read - <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>, - the introduction to the Android testing and instrumentation framework. -</p> -<h2 id="ActivityTestAPI">The Activity Testing API</h2> -<p> - The activity testing API base class is {@link android.test.InstrumentationTestCase}, - which provides instrumentation to the test case subclasses you use for Activities. -</p> -<p> - For activity testing, this base class provides these functions: -</p> -<ul> - <li> - Lifecycle control: With instrumentation, you can start the activity under test, pause it, - and destroy it, using methods provided by the test case classes. - </li> - <li> - Dependency injection: Instrumentation allows you to create mock system objects such as - Contexts or Applications and use them to run the activity under test. This - helps you control the test environment and isolate it from production systems. You can - also set up customized Intents and start an activity with them. - </li> - <li> - User interface interaction: You use instrumentation to send keystrokes or touch events - directly to the UI of the activity under test. - </li> -</ul> -<p> - The activity testing classes also provide the JUnit framework by extending - {@link junit.framework.TestCase} and {@link junit.framework.Assert}. -</p> -<p> - The two main testing subclasses are {@link android.test.ActivityInstrumentationTestCase2} and - {@link android.test.ActivityUnitTestCase}. To test an Activity that is launched in a mode - other than <code>standard</code>, you use {@link android.test.SingleLaunchActivityTestCase}. -</p> -<h3 id="ActivityInstrumentationTestCase2">ActivityInstrumentationTestCase2</h3> -<p> - The {@link android.test.ActivityInstrumentationTestCase2} test case class is designed to do - functional testing of one or more Activities in an application, using a normal system - infrastructure. It runs the Activities in a normal instance of the application under test, - using a standard system Context. It allows you to send mock Intents to the activity under - test, so you can use it to test an activity that responds to multiple types of intents, or - an activity that expects a certain type of data in the intent, or both. Notice, though, that it - does not allow mock Contexts or Applications, so you can not isolate the test from the rest of - a production system. -</p> -<h3 id="ActivityUnitTestCase">ActivityUnitTestCase</h3> -<p> - The {@link android.test.ActivityUnitTestCase} test case class tests a single activity in - isolation. Before you start the activity, you can inject a mock Context or Application, or both. - You use it to run activity tests in isolation, and to do unit testing of methods - that do not interact with Android. You can not send mock Intents to the activity under test, - although you can call - {@link android.app.Activity#startActivity(Intent) Activity.startActivity(Intent)} and then - look at arguments that were received. -</p> -<h3 id="SingleLaunchActivityTestCase">SingleLaunchActivityTestCase</h3> -<p> - The {@link android.test.SingleLaunchActivityTestCase} class is a convenience class for - testing a single activity in an environment that doesn't change from test to test. - It invokes {@link junit.framework.TestCase#setUp() setUp()} and - {@link junit.framework.TestCase#tearDown() tearDown()} only once, instead of once per - method call. It does not allow you to inject any mock objects. -</p> -<p> - This test case is useful for testing an activity that runs in a mode other than - <code>standard</code>. It ensures that the test fixture is not reset between tests. You - can then test that the activity handles multiple calls correctly. -</p> -<h3 id="MockObjectNotes">Mock objects and activity testing</h3> -<p> - This section contains notes about the use of the mock objects defined in - {@link android.test.mock} with activity tests. -</p> -<p> - The mock object {@link android.test.mock.MockApplication} is only available for activity - testing if you use the {@link android.test.ActivityUnitTestCase} test case class. - By default, <code>ActivityUnitTestCase</code>, creates a hidden <code>MockApplication</code> - object that is used as the application under test. You can inject your own object using - {@link android.test.ActivityUnitTestCase#setApplication(Application) setApplication()}. -</p> -<h3 id="AssertionNotes">Assertions for activity testing</h3> -<p> - {@link android.test.ViewAsserts} defines assertions for Views. You use it to verify the - alignment and position of View objects, and to look at the state of ViewGroup objects. -</p> -<h2 id="WhatToTest">What To Test</h2> -<ul> - <li> - Input validation: Test that an activity responds correctly to input values in an - EditText View. Set up a keystroke sequence, send it to the activity, and then - use {@link android.view.View#findViewById(int)} to examine the state of the View. You can - verify that a valid keystroke sequence enables an OK button, while an invalid one leaves the - button disabled. You can also verify that the Activity responds to invalid input by - setting error messages in the View. - </li> - <li> - Lifecycle events: Test that each of your application's activities handles lifecycle events - correctly. In general, lifecycle events are actions, either from the system or from the - user, that trigger a callback method such as <code>onCreate()</code> or - <code>onClick()</code>. For example, an activity should respond to pause or destroy events - by saving its state. Remember that even a change in screen orientation causes the current - activity to be destroyed, so you should test that accidental device movements don't - accidentally lose the application state. - </li> - <li> - Intents: Test that each activity correctly handles the intents listed in the intent - filter specified in its manifest. You can use - {@link android.test.ActivityInstrumentationTestCase2} to send mock Intents to the - activity under test. - </li> - <li> - Runtime configuration changes: Test that each activity responds correctly to the - possible changes in the device's configuration while your application is running. These - include a change to the device's orientation, a change to the current language, and so - forth. Handling these changes is described in detail in the topic - <a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime - Changes</a>. - </li> - <li> - Screen sizes and resolutions: Before you publish your application, make sure to test it on - all of the screen sizes and densities on which you want it to run. You can test the - application on multiple sizes and densities using AVDs, or you can test your application - directly on the devices that you are targeting. For more information, see the topic - <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>. - </li> -</ul> -<h2 id="NextSteps">Next Steps</h2> -<p> - To learn how to set up and run tests in Eclipse, please refer to <a - href="{@docRoot}guide/developing/testing/testing_eclipse.html">Testing in - Eclipse, with ADT</a>. If you're not working in Eclipse, refer to <a - href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other - IDEs</a>. -</p> -<p> - If you want a step-by-step introduction to testing activities, try one of the - testing tutorials: -</p> -<ul> - <li> - The <a - href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello, - Testing</a> tutorial introduces basic testing concepts and procedures in the - context of the Hello, World application. - </li> - <li> - The <a - href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity - Testing</a> tutorial is an excellent follow-up to the Hello, Testing tutorial. - It guides you through a more complex testing scenario that you develop against a - more realistic activity-oriented application. - </li> -</ul> -<h2 id="UITesting">Appendix: UI Testing Notes</h2> -<p> - The following sections have tips for testing the UI of your Android application, specifically - to help you handle actions that run in the UI thread, touch screen and keyboard events, and home - screen unlock during testing. -</p> -<h3 id="RunOnUIThread">Testing on the UI thread</h3> -<p> - An application's activities run on the application's <strong>UI thread</strong>. Once the - UI is instantiated, for example in the activity's <code>onCreate()</code> method, then all - interactions with the UI must run in the UI thread. When you run the application normally, it - has access to the thread and does not have to do anything special. -</p> -<p> - This changes when you run tests against the application. With instrumentation-based classes, - you can invoke methods against the UI of the application under test. The other test classes - don't allow this. To run an entire test method on the UI thread, you can annotate the thread - with <code>@UIThreadTest</code>. Notice that this will run <em>all</em> of the method statements - on the UI thread. Methods that do not interact with the UI are not allowed; for example, you - can't invoke <code>Instrumentation.waitForIdleSync()</code>. -</p> -<p> - To run a subset of a test method on the UI thread, create an anonymous class of type - <code>Runnable</code>, put the statements you want in the <code>run()</code> method, and - instantiate a new instance of the class as a parameter to the method - <code><em>appActivity</em>.runOnUiThread()</code>, where <code><em>appActivity</em></code> is - the instance of the application you are testing. -</p> -<p> - For example, this code instantiates an activity to test, requests focus (a UI action) for the - Spinner displayed by the activity, and then sends a key to it. Notice that the calls to - <code>waitForIdleSync</code> and <code>sendKeys</code> aren't allowed to run on the UI thread: -</p> -<pre> - private MyActivity mActivity; // MyActivity is the class name of the app under test - private Spinner mSpinner; - - ... - - protected void setUp() throws Exception { - super.setUp(); - mInstrumentation = getInstrumentation(); - - mActivity = getActivity(); // get a references to the app under test - - /* - * Get a reference to the main widget of the app under test, a Spinner - */ - mSpinner = (Spinner) mActivity.findViewById(com.android.demo.myactivity.R.id.Spinner01); - - ... - - public void aTest() { - /* - * request focus for the Spinner, so that the test can send key events to it - * This request must be run on the UI thread. To do this, use the runOnUiThread method - * and pass it a Runnable that contains a call to requestFocus on the Spinner. - */ - mActivity.runOnUiThread(new Runnable() { - public void run() { - mSpinner.requestFocus(); - } - }); - - mInstrumentation.waitForIdleSync(); - - this.sendKeys(KeyEvent.KEYCODE_DPAD_CENTER); -</pre> - -<h3 id="NotouchMode">Turning off touch mode</h3> -<p> - To control the emulator or a device with key events you send from your tests, you must turn off - touch mode. If you do not do this, the key events are ignored. -</p> -<p> - To turn off touch mode, you invoke - <code>ActivityInstrumentationTestCase2.setActivityTouchMode(false)</code> - <em>before</em> you call <code>getActivity()</code> to start the activity. You must invoke the - method in a test method that is <em>not</em> running on the UI thread. For this reason, you - can't invoke the touch mode method from a test method that is annotated with - <code>@UIThread</code>. Instead, invoke the touch mode method from <code>setUp()</code>. -</p> -<h3 id="UnlockDevice">Unlocking the emulator or device</h3> -<p> - You may find that UI tests don't work if the emulator's or device's home screen is disabled with - the keyguard pattern. This is because the application under test can't receive key events sent - by <code>sendKeys()</code>. The best way to avoid this is to start your emulator or device - first and then disable the keyguard for the home screen. -</p> -<p> - You can also explicitly disable the keyguard. To do this, - you need to add a permission in the manifest file (<code>AndroidManifest.xml</code>) and - then disable the keyguard in your application under test. Note, though, that you either have to - remove this before you publish your application, or you have to disable it with code in - the published application. -</p> -<p> - To add the the permission, add the element - <code><uses-permission android:name="android.permission.DISABLE_KEYGUARD"/></code> - as a child of the <code><manifest></code> element. To disable the KeyGuard, add the - following code to the <code>onCreate()</code> method of activities you intend to test: -</p> -<pre> - mKeyGuardManager = (KeyguardManager) getSystemService(KEYGUARD_SERVICE); - mLock = mKeyGuardManager.newKeyguardLock("<em>activity_classname</em>"); - mLock.disableKeyguard(); -</pre> -<p>where <code><em>activity_classname</em></code> is the class name of the activity.</p> -<h3 id="UITestTroubleshooting">Troubleshooting UI tests</h3> -<p> - This section lists some of the common test failures you may encounter in UI testing, and their - causes: -</p> -<dl> - <dt><code>WrongThreadException</code></dt> - <dd> - <p><strong>Problem:</strong></p> - For a failed test, the Failure Trace contains the following error message: - <code> - android.view.ViewRoot$CalledFromWrongThreadException: Only the original thread that created - a view hierarchy can touch its views. - </code> - <p><strong>Probable Cause:</strong></p> - This error is common if you tried to send UI events to the UI thread from outside the UI - thread. This commonly happens if you send UI events from the test application, but you don't - use the <code>@UIThread</code> annotation or the <code>runOnUiThread()</code> method. The - test method tried to interact with the UI outside the UI thread. - <p><strong>Suggested Resolution:</strong></p> - Run the interaction on the UI thread. Use a test class that provides instrumentation. See - the previous section <a href="#RunOnUIThread">Testing on the UI Thread</a> - for more details. - </dd> - <dt><code>java.lang.RuntimeException</code></dt> - <dd> - <p><strong>Problem:</strong></p> - For a failed test, the Failure Trace contains the following error message: - <code> - java.lang.RuntimeException: This method can not be called from the main application thread - </code> - <p><strong>Probable Cause:</strong></p> - This error is common if your test method is annotated with <code>@UiThreadTest</code> but - then tries to do something outside the UI thread or tries to invoke - <code>runOnUiThread()</code>. - <p><strong>Suggested Resolution:</strong></p> - Remove the <code>@UiThreadTest</code> annotation, remove the <code>runOnUiThread()</code> - call, or re-factor your tests. - </dd> -</dl> diff --git a/docs/html/guide/topics/testing/contentprovider_testing.jd b/docs/html/guide/topics/testing/contentprovider_testing.jd deleted file mode 100644 index edaae8c..0000000 --- a/docs/html/guide/topics/testing/contentprovider_testing.jd +++ /dev/null @@ -1,225 +0,0 @@ -page.title=Content Provider Testing -parent.title=Testing -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - <ol> - <li> - <a href="#DesignAndTest">Content Provider Design and Testing</a> - </li> - <li> - <a href="#ContentProviderTestAPI">The Content Provider Testing API</a> - <ol> - <li> - <a href="#ProviderTestCase2">ProviderTestCase2 </a> - </li> - <li> - <a href="#MockObjects">Mock object classes</a> - </li> - </ol> - </li> - <li> - <a href="#WhatToTest">What To Test</a> - </li> - <li> - <a href="#NextSteps">Next Steps</a> - </li> - </ol> - <h2>Key Classes</h2> - <ol> - <li>{@link android.test.InstrumentationTestRunner}</li> - <li>{@link android.test.ProviderTestCase2}</li> - <li>{@link android.test.IsolatedContext}</li> - <li>{@link android.test.mock.MockContentResolver}</li> - </ol> - <h2>See Also</h2> - <ol> - <li> - <a - href="{@docRoot}guide/topics/testing/testing_android.html"> - Testing Fundamentals</a> - </li> - <li> - <a href="{@docRoot}guide/developing/testing/testing_eclipse.html"> - Testing in Eclipse, with ADT</a> - </li> - <li> - <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> - Testing in Other IDEs</a> - </li> - </ol> - </div> -</div> -<p> - Content providers, which store and retrieve data and make it accessible across applications, - are a key part of the Android API. As an application developer you're allowed to provide your - own public providers for use by other applications. If you do, then you should test them - using the API you publish. -</p> -<p> - This document describes how to test public content providers, although the information is - also applicable to providers that you keep private to your own application. If you aren't - familiar with content providers or the Android testing framework, please read - <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>, - the guide to developing content providers, and - <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>, - the introduction to the Android testing and instrumentation framework. -</p> -<h2 id="DesignAndTest">Content Provider Design and Testing</h2> -<p> - In Android, content providers are viewed externally as data APIs that provide - tables of data, with their internals hidden from view. A content provider may have many - public constants, but it usually has few if any public methods and no public variables. - This suggests that you should write your tests based only on the provider's public members. - A content provider that is designed like this is offering a contract between itself and its - users. -</p> -<p> - The base test case class for content providers, - {@link android.test.ProviderTestCase2}, allows you to test your content provider in an - isolated environment. Android mock objects such as {@link android.test.IsolatedContext} and - {@link android.test.mock.MockContentResolver} also help provide an isolated test environment. -</p> -<p> - As with other Android tests, provider test packages are run under the control of the test - runner {@link android.test.InstrumentationTestRunner}. The section - <a href="{@docRoot}guide/topics/testing/testing_android.html#InstrumentationTestRunner"> - Running Tests With InstrumentationTestRunner</a> describes the test runner in - more detail. The topic <a href="{@docRoot}guide/developing/testing/testing_eclipse.html"> - Testing in Eclipse, with ADT</a> shows you how to run a test package in Eclipse, and the - topic <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> - Testing in Other IDEs</a> - shows you how to run a test package from the command line. -</p> -<h2 id="ContentProviderTestAPI">Content Provider Testing API</h2> -<p> - The main focus of the provider testing API is to provide an isolated testing environment. This - ensures that tests always run against data dependencies set explicitly in the test case. It - also prevents tests from modifying actual user data. For example, you want to avoid writing - a test that fails because there was data left over from a previous test, and you want to - avoid adding or deleting contact information in a actual provider. -</p> -<p> - The test case class and mock object classes for provider testing set up this isolated testing - environment for you. -</p> -<h3 id="ProviderTestCase2">ProviderTestCase2</h3> -<p> - You test a provider with a subclass of {@link android.test.ProviderTestCase2}. This base class - extends {@link android.test.AndroidTestCase}, so it provides the JUnit testing framework as well - as Android-specific methods for testing application permissions. The most important - feature of this class is its initialization, which creates the isolated test environment. -</p> -<p> - The initialization is done in the constructor for {@link android.test.ProviderTestCase2}, which - subclasses call in their own constructors. The {@link android.test.ProviderTestCase2} - constructor creates an {@link android.test.IsolatedContext} object that allows file and - database operations but stubs out other interactions with the Android system. - The file and database operations themselves take place in a directory that is local to the - device or emulator and has a special prefix. -</p> -<p> - The constructor then creates a {@link android.test.mock.MockContentResolver} to use as the - resolver for the test. The {@link android.test.mock.MockContentResolver} class is described in - detail in the section - <a href="{@docRoot}guide/topics/testing/testing_android.html#MockObjectClasses">Mock object -classes</a>. -</p> -<p> - Lastly, the constructor creates an instance of the provider under test. This is a normal - {@link android.content.ContentProvider} object, but it takes all of its environment information - from the {@link android.test.IsolatedContext}, so it is restricted to - working in the isolated test environment. All of the tests done in the test case class run - against this isolated object. -</p> -<h3 id="MockObjects">Mock object classes</h3> -<p> - {@link android.test.ProviderTestCase2} uses {@link android.test.IsolatedContext} and - {@link android.test.mock.MockContentResolver}, which are standard mock object classes. To - learn more about them, please read - <a href="{@docRoot}guide/topics/testing/testing_android.html#MockObjectClasses"> - Testing Fundamentals</a>. -</p> -<h2 id="WhatToTest">What To Test</h2> -<p> - The topic <a href="{@docRoot}guide/topics/testing/what_to_test.html">What To Test</a> - lists general considerations for testing Android components. - Here are some specific guidelines for testing content providers. -</p> -<ul> - <li> - Test with resolver methods: Even though you can instantiate a provider object in - {@link android.test.ProviderTestCase2}, you should always test with a resolver object - using the appropriate URI. This ensures that you are testing the provider using the same - interaction that a regular application would use. - </li> - <li> - Test a public provider as a contract: If you intent your provider to be public and - available to other applications, you should test it as a contract. This includes - the following ideas: - <ul> - <li> - Test with constants that your provider publicly exposes. For - example, look for constants that refer to column names in one of the provider's - data tables. These should always be constants publicly defined by the provider. - </li> - <li> - Test all the URIs offered by your provider. Your provider may offer several URIs, - each one referring to a different aspect of the data. The - <a href="{@docRoot}resources/samples/NotePad/index.html">Note Pad</a> sample, - for example, features a provider that offers one URI for retrieving a list of notes, - another for retrieving an individual note by it's database ID, and a third for - displaying notes in a live folder. - </li> - <li> - Test invalid URIs: Your unit tests should deliberately call the provider with an - invalid URI, and look for errors. Good provider design is to throw an - IllegalArgumentException for invalid URIs. - - </li> - </ul> - </li> - <li> - Test the standard provider interactions: Most providers offer six access methods: - query, insert, delete, update, getType, and onCreate(). Your tests should verify that all - of these methods work. These are described in more detail in the topic - <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>. - </li> - <li> - Test business logic: Don't forget to test the business logic that your provider should - enforce. Business logic includes handling of invalid values, financial or arithmetic - calculations, elimination or combining of duplicates, and so forth. A content provider - does not have to have business logic, because it may be implemented by activities that - modify the data. If the provider does implement business logic, you should test it. - </li> -</ul> -<h2 id="NextSteps">Next Steps</h2> -<p> - To learn how to set up and run tests in Eclipse, please refer to <a - href="{@docRoot}guide/developing/testing/testing_eclipse.html">Testing in - Eclipse, with ADT</a>. If you're not working in Eclipse, refer to <a - href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other - IDEs</a>. -</p> -<p> - If you want a step-by-step introduction to testing activities, try one of the - testing tutorials: -</p> -<ul> - <li> - The <a - href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello, - Testing</a> tutorial introduces basic testing concepts and procedures in the - context of the Hello, World application. - </li> - <li> - The <a - href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity - Testing</a> tutorial is an excellent follow-up to the Hello, Testing tutorial. - It guides you through a more complex testing scenario that you develop against a - more realistic activity-oriented application. - </li> -</ul> diff --git a/docs/html/guide/topics/testing/index.jd b/docs/html/guide/topics/testing/index.jd deleted file mode 100644 index cf87187..0000000 --- a/docs/html/guide/topics/testing/index.jd +++ /dev/null @@ -1,86 +0,0 @@ -page.title=Testing -@jd:body -<p> - The Android development environment includes an integrated testing framework that helps you - test all aspects of your application. -</p> -<h4>Fundamentals</h4> -<p> - To start learning how to use the framework to create tests for your applications, please - read the topic <a href="{@docRoot}guide/topics/testing/testing_android.html"> - Testing Fundamentals</a>. -</p> -<h4>Concepts</h4> -<ul> - <li> - <a href="{@docRoot}guide/topics/testing/activity_testing.html"> - Activity Testing</a> focuses on testing activities. It describes how instrumentation allows - you to control activities outside the normal application lifecycle. It also lists - activity-specific features you should test, and it provides tips for testing Android - user interfaces. - </li> - <li> - <a href="{@docRoot}guide/topics/testing/contentprovider_testing.html"> - Content Provider Testing</a> focuses on testing content providers. It describes the - mock system objects you can use, provides tips for designing providers so that they - can be tested, and lists provider-specific features you should test. - </li> - <li> - <a href="{@docRoot}guide/topics/testing/service_testing.html"> - Service Testing</a> focuses on testing services. It also lists service-specific features - you should test. - </li> - <li> - <a href="{@docRoot}guide/topics/testing/what_to_test.html">What to Test</a> - is an overview of the types of testing you should do. It focuses on testing - system-wide aspects of Android that can affect every component in your application. - </li> -</ul> -<h4>Procedures</h4> -<ul> - <li> - The topic <a href="{@docRoot}guide/developing/testing/testing_eclipse.html"> - Testing in Eclipse, with ADT</a> describes how to create and run tests in Eclipse with ADT. - </li> - <li> - The topic <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> - Testing in other IDEs</a> describes how to create and run tests with command-line tools. - </li> -</ul> -<h4>Tutorials</h4> -<ul> - <li> - The <a href="{@docRoot}resources/tutorials/testing/helloandroid_test.html"> - Hello, Testing</a> tutorial introduces basic testing concepts and procedures. - </li> - <li> - For a more advanced tutorial, try - <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a>, - which guides you through a more complex testing scenario. - </li> -</ul> -<h4>Tools</h4> -<ul> - <li> - The - <a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a>, - usually called Monkey, is a command-line tool that sends pseudo-random - streams of keystrokes, touches, and gestures to a device. - </li> - <li> - The <a href="{@docRoot}guide/developing/tools/monkeyrunner_concepts.html">monkeyrunner</a> tool - is an API and execution environment. You use monkeyrunner with Python programs - to test applications and devices. - </li> -</ul> -<!-- -<h4>Samples</h4> -<ul> - <li> - The <a href="{@docRoot}resources/samples/AlarmServiceTest.html">Alarm Service Test</a> - is a test package for the <a href="{@docRoot}resources/samples/Alarm.html">Alarm</a> - sample application. It provides a simple example of unit - testing a {@link android.app.Service}. - </li> -</ul> ---> diff --git a/docs/html/guide/topics/testing/service_testing.jd b/docs/html/guide/topics/testing/service_testing.jd deleted file mode 100644 index eae8607..0000000 --- a/docs/html/guide/topics/testing/service_testing.jd +++ /dev/null @@ -1,180 +0,0 @@ -page.title=Service Testing -parent.title=Testing -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - <ol> - <li> - <a href="#DesignAndTest">Service Design and Testing</a> - </li> - <li> - <a href="#ServiceTestCase">ServiceTestCase</a> - </li> - <li> - <a href="#MockObjects">Mock object classes</a> - </li> - <li> - <a href="#TestAreas">What to Test</a> - </li> - </ol> - <h2>Key Classes</h2> - <ol> - <li>{@link android.test.InstrumentationTestRunner}</li> - <li>{@link android.test.ServiceTestCase}</li> - <li>{@link android.test.mock.MockApplication}</li> - <li>{@link android.test.RenamingDelegatingContext}</li> - </ol> - <h2>Related Tutorials</h2> - <ol> - <li> - <a href="{@docRoot}resources/tutorials/testing/helloandroid_test.html"> - Hello, Testing</a> - </li> - <li> - <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> - </li> - </ol> - <h2>See Also</h2> - <ol> - <li> - <a href="{@docRoot}guide/developing/testing/testing_eclipse.html"> - Testing in Eclipse, with ADT</a> - </li> - <li> - <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> - Testing in Other IDEs</a> - </li> - </ol> - </div> -</div> -<p> - Android provides a testing framework for Service objects that can run them in - isolation and provides mock objects. The test case class for Service objects is - {@link android.test.ServiceTestCase}. Since the Service class assumes that it is separate - from its clients, you can test a Service object without using instrumentation. -</p> -<p> - This document describes techniques for testing Service objects. If you aren't familiar with the - Service class, please read the <a href="{@docRoot}guide/topics/fundamentals/services.html"> - Services</a> document. If you aren't familiar with Android testing, please read - <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>, - the introduction to the Android testing and instrumentation framework. -</p> -<h2 id="DesignAndTest">Service Design and Testing</h2> -<p> - When you design a Service, you should consider how your tests can examine the various states - of the Service lifecycle. If the lifecycle methods that start up your Service, such as - {@link android.app.Service#onCreate() onCreate()} or - {@link android.app.Service#onStartCommand(Intent, int, int) onStartCommand()} do not normally - set a global variable to indicate that they were successful, you may want to provide such a - variable for testing purposes. -</p> -<p> - Most other testing is facilitated by the methods in the {@link android.test.ServiceTestCase} - test case class. For example, the {@link android.test.ServiceTestCase#getService()} method - returns a handle to the Service under test, which you can test to confirm that the Service is - running even at the end of your tests. -</p> -<h2 id="ServiceTestCase">ServiceTestCase</h2> -<p> - {@link android.test.ServiceTestCase} extends the JUnit {@link junit.framework.TestCase} class - with with methods for testing application permissions and for controlling the application and - Service under test. It also provides mock application and Context objects that isolate your - test from the rest of the system. -</p> -<p> - {@link android.test.ServiceTestCase} defers initialization of the test environment until you - call {@link android.test.ServiceTestCase#startService(Intent) ServiceTestCase.startService()} or - {@link android.test.ServiceTestCase#bindService(Intent) ServiceTestCase.bindService()}. This - allows you to set up your test environment, particularly your mock objects, before the Service - is started. -</p> -<p> - Notice that the parameters to <code>ServiceTestCase.bindService()</code>are different from - those for <code>Service.bindService()</code>. For the <code>ServiceTestCase</code> version, - you only provide an Intent. Instead of returning a boolean, - <code>ServiceTestCase.bindService()</code> returns an object that subclasses - {@link android.os.IBinder}. -</p> -<p> - The {@link android.test.ServiceTestCase#setUp()} method for {@link android.test.ServiceTestCase} - is called before each test. It sets up the test fixture by making a copy of the current system - Context before any test methods touch it. You can retrieve this Context by calling - {@link android.test.ServiceTestCase#getSystemContext()}. If you override this method, you must - call <code>super.setUp()</code> as the first statement in the override. -</p> -<p> - The methods {@link android.test.ServiceTestCase#setApplication(Application) setApplication()} - and {@link android.test.AndroidTestCase#setContext(Context)} setContext()} allow you to set - a mock Context or mock Application (or both) for the Service, before you start it. These mock - objects are described in <a href="#MockObjects">Mock object classes</a>. -</p> -<p> - By default, {@link android.test.ServiceTestCase} runs the test method - {@link android.test.AndroidTestCase#testAndroidTestCaseSetupProperly()}, which asserts that - the base test case class successfully set up a Context before running. -</p> -<h2 id="MockObjects">Mock object classes</h2> -<p> - <code>ServiceTestCase</code> assumes that you will use a mock Context or mock Application - (or both) for the test environment. These objects isolate the test environment from the - rest of the system. If you don't provide your own instances of these objects before you - start the Service, then {@link android.test.ServiceTestCase} will create its own internal - instances and inject them into the Service. You can override this behavior by creating and - injecting your own instances before starting the Service -</p> -<p> - To inject a mock Application object into the Service under test, first create a subclass of - {@link android.test.mock.MockApplication}. <code>MockApplication</code> is a subclass of - {@link android.app.Application} in which all the methods throw an Exception, so to use it - effectively you subclass it and override the methods you need. You then inject it into the - Service with the - {@link android.test.ServiceTestCase#setApplication(Application) setApplication()} method. - This mock object allows you to control the application values that the Service sees, and - isolates it from the real system. In addition, any hidden dependencies your Service has on - its application reveal themselves as exceptions when you run the test. -</p> -<p> - You inject a mock Context into the Service under test with the - {@link android.test.AndroidTestCase#setContext(Context) setContext()} method. The mock - Context classes you can use are described in more detail in - <a href="{@docRoot}guide/topics/testing/testing_android.html#MockObjectClasses"> - Testing Fundamentals</a>. -</p> -<h2 id="TestAreas">What to Test</h2> -<p> - The topic <a href="{@docRoot}guide/topics/testing/what_to_test.html">What To Test</a> - lists general considerations for testing Android components. - Here are some specific guidelines for testing a Service: -</p> -<ul> - <li> - Ensure that the {@link android.app.Service#onCreate()} is called in response to - {@link android.content.Context#startService(Intent) Context.startService()} or - {@link android.content.Context#bindService(Intent,ServiceConnection,int) Context.bindService()}. - Similarly, you should ensure that {@link android.app.Service#onDestroy()} is called in - response to {@link android.content.Context#stopService(Intent) Context.stopService()}, - {@link android.content.Context#unbindService(ServiceConnection) Context.unbindService()}, - {@link android.app.Service#stopSelf()}, or - {@link android.app.Service#stopSelfResult(int) stopSelfResult()}. - </li> - <li> - Test that your Service correctly handles multiple calls from - <code>Context.startService()</code>. Only the first call triggers - <code>Service.onCreate()</code>, but all calls trigger a call to - <code>Service.onStartCommand()</code>. - <p> - In addition, remember that <code>startService()</code> calls don't - nest, so a single call to <code>Context.stopService()</code> or - <code>Service.stopSelf()</code> (but not <code>stopSelf(int)</code>) - will stop the Service. You should test that your Service stops at the correct point. - </p> - </li> - <li> - Test any business logic that your Service implements. Business logic includes checking for - invalid values, financial and arithmetic calculations, and so forth. - </li> -</ul> diff --git a/docs/html/guide/topics/testing/testing_android.jd b/docs/html/guide/topics/testing/testing_android.jd deleted file mode 100755 index adbc59d..0000000 --- a/docs/html/guide/topics/testing/testing_android.jd +++ /dev/null @@ -1,666 +0,0 @@ -page.title=Testing Fundamentals -parent.title=Testing -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - <ol> - <li> - <a href="#TestStructure">Test Structure</a> - </li> - <li> - <a href="#TestProjects">Test Projects</a> - </li> - <li> - <a href="#TestAPI">The Testing API</a> - <ol> - <li> - <a href="#JUnit">JUnit</a> - </li> - <li> - <a href="#Instrumentation">Instrumentation</a> - </li> - <li> - <a href="#TestCaseClasses">Test case classes</a> - </li> - <li> - <a href="#AssertionClasses">Assertion classes</a> - </li> - <li> - <a href="#MockObjectClasses">Mock object classes</a> - </li> - </ol> - </li> - <li> - <a href="#InstrumentationTestRunner">Running Tests</a> - </li> - <li> - <a href="#TestResults">Seeing Test Results</a> - </li> - <li> - <a href="#Monkeys">monkey and monkeyrunner</a> - </li> - <li> - <a href="#PackageNames">Working With Package Names</a> - </li> - <li> - <a href="#WhatToTest">What To Test</a> - </li> - <li> - <a href="#NextSteps">Next Steps</a> - </li> - </ol> - <h2>Key classes</h2> - <ol> - <li>{@link android.test.InstrumentationTestRunner}</li> - <li>{@link android.test}</li> - <li>{@link android.test.mock}</li> - <li>{@link junit.framework}</li> - </ol> - <h2>Related tutorials</h2> - <ol> - <li> - <a href="{@docRoot}resources/tutorials/testing/helloandroid_test.html"> - Hello, Testing</a> - </li> - <li> - <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> - </li> - </ol> - <h2>See also</h2> - <ol> - <li> - <a href="{@docRoot}guide/developing/testing/testing_eclipse.html"> - Testing in Eclipse, with ADT</a> - </li> - <li> - <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> - Testing in Other IDEs</a> - </li> - <li> - <a href="{@docRoot}guide/developing/tools/monkeyrunner_concepts.html"> - monkeyrunner</a> - </li> - <li> - <a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a> - </li> - </ol> - </div> -</div> -<p> - The Android testing framework, an integral part of the development environment, - provides an architecture and powerful tools that help you test every aspect of your application - at every level from unit to framework. -</p> -<p> - The testing framework has these key features: -</p> -<ul> - <li> - Android test suites are based on JUnit. You can use plain JUnit to test a class that doesn't - call the Android API, or Android's JUnit extensions to test Android components. If you're - new to Android testing, you can start with general-purpose test case classes such as {@link - android.test.AndroidTestCase} and then go on to use more sophisticated classes. - </li> - <li> - The Android JUnit extensions provide component-specific test case classes. These classes - provide helper methods for creating mock objects and methods that help you control the - lifecycle of a component. - </li> - <li> - Test suites are contained in test packages that are similar to main application packages, so - you don't need to learn a new set of tools or techniques for designing and building tests. - </li> - <li> - The SDK tools for building and tests are available in Eclipse with ADT, and also in - command-line form for use with other IDES. These tools get information from the project of - the application under test and use this information to automatically create the build files, - manifest file, and directory structure for the test package. - </li> - <li> - The SDK also provides - <a href="{@docRoot}guide/developing/tools/monkeyrunner_concepts.html">monkeyrunner</a>, an API - testing devices with Python programs, and <a - href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a>, - a command-line tool for stress-testing UIs by sending pseudo-random events to a device. - </li> -</ul> -<p> - This document describes the fundamentals of the Android testing framework, including the - structure of tests, the APIs that you use to develop tests, and the tools that you use to run - tests and view results. The document assumes you have a basic knowledge of Android application - programming and JUnit testing methodology. -</p> -<p> - The following diagram summarizes the testing framework: -</p> -<div style="width: 70%; margin-left:auto; margin-right:auto;"> -<a href="{@docRoot}images/testing/test_framework.png"> - <img src="{@docRoot}images/testing/test_framework.png" - alt="The Android testing framework"/> -</a> -</div> -<h2 id="TestStructure">Test Structure</h2> -<p> - Android's build and test tools assume that test projects are organized into a standard - structure of tests, test case classes, test packages, and test projects. -</p> -<p> - Android testing is based on JUnit. In general, a JUnit test is a method whose - statements test a part of the application under test. You organize test methods into classes - called test cases (or test suites). Each test is an isolated test of an individual module in - the application under test. Each class is a container for related test methods, although it - often provides helper methods as well. -</p> -<p> - In JUnit, you build one or more test source files into a class file. Similarly, in Android you - use the SDK's build tools to build one or more test source files into class files in an - Android test package. In JUnit, you use a test runner to execute test classes. In Android, you - use test tools to load the test package and the application under test, and the tools then - execute an Android-specific test runner. -</p> -<h2 id="TestProjects">Test Projects</h2> -<p> - Tests, like Android applications, are organized into projects. -</p> -<p> - A test project is a directory or Eclipse project in which you create the source code, manifest - file, and other files for a test package. The Android SDK contains tools for Eclipse with ADT - and for the command line that create and update test projects for you. The tools create the - directories you use for source code and resources and the manifest file for the test package. - The command-line tools also create the Ant build files you need. -</p> -<p> - You should always use Android tools to create a test project. Among other benefits, - the tools: -</p> - <ul> - <li> - Automatically set up your test package to use - {@link android.test.InstrumentationTestRunner} as the test case runner. You must use - <code>InstrumentationTestRunner</code> (or a subclass) to run JUnit tests. - </li> - <li> - Create an appropriate name for the test package. If the application - under test has a package name of <code>com.mydomain.myapp</code>, then the - Android tools set the test package name to <code>com.mydomain.myapp.test</code>. This - helps you identify their relationship, while preventing conflicts within the system. - </li> - <li> - Automatically create the proper build files, manifest file, and directory - structure for the test project. This helps you to build the test package without - having to modify build files and sets up the linkage between your test package and - the application under test. - The - </li> - </ul> -<p> - You can create a test project anywhere in your file system, but the best approach is to - add the test project so that its root directory <code>tests/</code> is at the same level - as the <code>src/</code> directory of the main application's project. This helps you find the - tests associated with an application. For example, if your application project's root directory - is <code>MyProject</code>, then you should use the following directory structure: -</p> -<pre class="classic no-pretty-print"> - MyProject/ - AndroidManifest.xml - res/ - ... (resources for main application) - src/ - ... (source code for main application) ... - tests/ - AndroidManifest.xml - res/ - ... (resources for tests) - src/ - ... (source code for tests) -</pre> -<h2 id="TestAPI">The Testing API</h2> -<p> - The Android testing API is based on the JUnit API and extended with a instrumentation - framework and Android-specific testing classes. -</p> -<h3 id="JUnit">JUnit</h3> -<p> - You can use the JUnit {@link junit.framework.TestCase TestCase} class to do unit testing on - a plain Java object. <code>TestCase</code> is also the base class for - {@link android.test.AndroidTestCase}, which you can use to test Android-dependent objects. - Besides providing the JUnit framework, AndroidTestCase offers Android-specific setup, - teardown, and helper methods. -</p> -<p> - You use the JUnit {@link junit.framework.Assert} class to display test results. - The assert methods compare values you expect from a test to the actual results and - throw an exception if the comparison fails. Android also provides a class of assertions that - extend the possible types of comparisons, and another class of assertions for testing the UI. - These are described in more detail in the section <a href="#AssertionClasses"> - Assertion classes</a> -</p> -<p> - To learn more about JUnit, you can read the documentation on the - <a href="http://www.junit.org">junit.org</a> home page. - Note that the Android testing API supports JUnit 3 code style, but not JUnit 4. Also, you must - use Android's instrumented test runner {@link android.test.InstrumentationTestRunner} to run - your test case classes. This test runner is described in the - section <a href="#InstrumentationTestRunner">Running Tests</a>. -</p> -<h3 id="Instrumentation">Instrumentation</h3> -<p> - Android instrumentation is a set of control methods or "hooks" in the Android system. These hooks - control an Android component independently of its normal lifecycle. They also control how - Android loads applications. -</p> -<p> - Normally, an Android component runs in a lifecycle determined by the system. For example, an - Activity object's lifecycle starts when the Activity is activated by an Intent. The object's - <code>onCreate()</code> method is called, followed by <code>onResume()</code>. When the user - starts another application, the <code>onPause()</code> method is called. If the Activity - code calls the <code>finish()</code> method, the <code>onDestroy()</code> method is called. - The Android framework API does not provide a way for your code to invoke these callback - methods directly, but you can do so using instrumentation. -</p> -<p> - Also, the system runs all the components of an application into the same - process. You can allow some components, such as content providers, to run in a separate process, - but you can't force an application to run in the same process as another application that is - already running. -</p> -<p> - With Android instrumentation, though, you can invoke callback methods in your test code. - This allows you to run through the lifecycle of a component step by step, as if you were - debugging the component. The following test code snippet demonstrates how to use this to - test that an Activity saves and restores its state: -</p> -<a name="ActivitySnippet"></a> -<pre> - // Start the main activity of the application under test - mActivity = getActivity(); - - // Get a handle to the Activity object's main UI widget, a Spinner - mSpinner = (Spinner)mActivity.findViewById(com.android.example.spinner.R.id.Spinner01); - - // Set the Spinner to a known position - mActivity.setSpinnerPosition(TEST_STATE_DESTROY_POSITION); - - // Stop the activity - The onDestroy() method should save the state of the Spinner - mActivity.finish(); - - // Re-start the Activity - the onResume() method should restore the state of the Spinner - mActivity = getActivity(); - - // Get the Spinner's current position - int currentPosition = mActivity.getSpinnerPosition(); - - // Assert that the current position is the same as the starting position - assertEquals(TEST_STATE_DESTROY_POSITION, currentPosition); -</pre> -<p> - The key method used here is - {@link android.test.ActivityInstrumentationTestCase2#getActivity()}, which is a - part of the instrumentation API. The Activity under test is not started until you call this - method. You can set up the test fixture in advance, and then call this method to start the - Activity. -</p> -<p> - Also, instrumentation can load both a test package and the application under test into the - same process. Since the application components and their tests are in the same process, the - tests can invoke methods in the components, and modify and examine fields in the components. -</p> -<h3 id="TestCaseClasses">Test case classes</h3> -<p> - Android provides several test case classes that extend {@link junit.framework.TestCase} and - {@link junit.framework.Assert} with Android-specific setup, teardown, and helper methods. -</p> -<h4 id="AndroidTestCase">AndroidTestCase</h4> -<p> - A useful general test case class, especially if you are - just starting out with Android testing, is {@link android.test.AndroidTestCase}. It extends - both {@link junit.framework.TestCase} and {@link junit.framework.Assert}. It provides the - JUnit-standard <code>setUp()</code> and <code>tearDown()</code> methods, as well as - all of JUnit's Assert methods. In addition, it provides methods for testing permissions, and a - method that guards against memory leaks by clearing out certain class references. -</p> -<h4 id="ComponentTestCase">Component-specific test cases</h4> -<p> - A key feature of the Android testing framework is its component-specific test case classes. - These address specific component testing needs with methods for fixture setup and - teardown and component lifecycle control. They also provide methods for setting up mock objects. - These classes are described in the component-specific testing topics: -</p> -<ul> - <li> - <a href="{@docRoot}guide/topics/testing/activity_testing.html">Activity Testing</a> - </li> - <li> - <a href="{@docRoot}guide/topics/testing/contentprovider_testing.html"> - Content Provider Testing</a> - </li> - <li> - <a href="{@docRoot}guide/topics/testing/service_testing.html">Service Testing</a> - </li> -</ul> -<p> - Android does not provide a separate test case class for BroadcastReceiver. Instead, test a - BroadcastReceiver by testing the component that sends it Intent objects, to verify that the - BroadcastReceiver responds correctly. -</p> -<h4 id="ApplicationTestCase">ApplicationTestCase</h4> -<p> - You use the {@link android.test.ApplicationTestCase} test case class to test the setup and - teardown of {@link android.app.Application} objects. These objects maintain the global state of - information that applies to all the components in an application package. The test case can - be useful in verifying that the <application> element in the manifest file is correctly - set up. Note, however, that this test case does not allow you to control testing of the - components within your application package. -</p> -<h4 id="InstrumentationTestCase">InstrumentationTestCase</h4> -<p> - If you want to use instrumentation methods in a test case class, you must use - {@link android.test.InstrumentationTestCase} or one of its subclasses. The - {@link android.app.Activity} test cases extend this base class with other functionality that - assists in Activity testing. -</p> - -<h3 id="AssertionClasses">Assertion classes</h3> -<p> - Because Android test case classes extend JUnit, you can use assertion methods to display the - results of tests. An assertion method compares an actual value returned by a test to an - expected value, and throws an AssertionException if the comparison test fails. Using assertions - is more convenient than doing logging, and provides better test performance. -</p> -<p> - Besides the JUnit {@link junit.framework.Assert} class methods, the testing API also provides - the {@link android.test.MoreAsserts} and {@link android.test.ViewAsserts} classes: -</p> -<ul> - <li> - {@link android.test.MoreAsserts} contains more powerful assertions such as - {@link android.test.MoreAsserts#assertContainsRegex}, which does regular expression - matching. - </li> - <li> - {@link android.test.ViewAsserts} contains useful assertions about Views. For example - it contains {@link android.test.ViewAsserts#assertHasScreenCoordinates} that tests if a View - has a particular X and Y position on the visible screen. These asserts simplify testing of - geometry and alignment in the UI. - </li> -</ul> -<h3 id="MockObjectClasses">Mock object classes</h3> -<p> - To facilitate dependency injection in testing, Android provides classes that create mock system - objects such as {@link android.content.Context} objects, - {@link android.content.ContentProvider} objects, {@link android.content.ContentResolver} - objects, and {@link android.app.Service} objects. Some test cases also provide mock - {@link android.content.Intent} objects. You use these mocks both to isolate tests - from the rest of the system and to facilitate dependency injection for testing. These classes - are found in the Java packages {@link android.test} and {@link android.test.mock}. -</p> -<p> - Mock objects isolate tests from a running system by stubbing out or overriding - normal operations. For example, a {@link android.test.mock.MockContentResolver} - replaces the normal resolver framework with its own local framework, which is isolated - from the rest of the system. MockContentResolver also stubs out the - {@link android.content.ContentResolver#notifyChange(Uri, ContentObserver, boolean)} method - so that observer objects outside the test environment are not accidentally triggered. -</p> -<p> - Mock object classes also facilitate dependency injection by providing a subclass of the - normal object that is non-functional except for overrides you define. For example, the - {@link android.test.mock.MockResources} object provides a subclass of - {@link android.content.res.Resources} in which all the methods throw Exceptions when called. - To use it, you override only those methods that must provide information. -</p> -<p> - These are the mock object classes available in Android: -</p> -<h4 id="SimpleMocks">Simple mock object classes</h4> -<p> - {@link android.test.mock.MockApplication}, {@link android.test.mock.MockContext}, - {@link android.test.mock.MockContentProvider}, {@link android.test.mock.MockCursor}, - {@link android.test.mock.MockDialogInterface}, {@link android.test.mock.MockPackageManager}, and - {@link android.test.mock.MockResources} provide a simple and useful mock strategy. They are - stubbed-out versions of the corresponding system object class, and all of their methods throw an - {@link java.lang.UnsupportedOperationException} exception if called. To use them, you override - the methods you need in order to provide mock dependencies. -</p> -<p class="Note"><strong>Note:</strong> - {@link android.test.mock.MockContentProvider} - and {@link android.test.mock.MockCursor} are new as of API level 8. -</p> -<h4 id="ResolverMocks">Resolver mock objects</h4> -<p> - {@link android.test.mock.MockContentResolver} provides isolated testing of content providers by - masking out the normal system resolver framework. Instead of looking in the system to find a - content provider given an authority string, MockContentResolver uses its own internal table. You - must explicitly add providers to this table using - {@link android.test.mock.MockContentResolver#addProvider(String,ContentProvider)}. -</p> -<p> - With this feature, you can associate a mock content provider with an authority. You can create - an instance of a real provider but use test data in it. You can even set the provider for an - authority to <code>null</code>. In effect, a MockContentResolver object isolates your test - from providers that contain real data. You can control the - function of the provider, and you can prevent your test from affecting real data. -</p> -<h3 id="ContextMocks">Contexts for testing</h3> -<p> - Android provides two Context classes that are useful for testing: -</p> -<ul> - <li> - {@link android.test.IsolatedContext} provides an isolated {@link android.content.Context}, - File, directory, and database operations that use this Context take place in a test area. - Though its functionality is limited, this Context has enough stub code to respond to - system calls. - <p> - This class allows you to test an application's data operations without affecting real - data that may be present on the device. - </p> - </li> - <li> - {@link android.test.RenamingDelegatingContext} provides a Context in which - most functions are handled by an existing {@link android.content.Context}, but - file and database operations are handled by a {@link android.test.IsolatedContext}. - The isolated part uses a test directory and creates special file and directory names. - You can control the naming yourself, or let the constructor determine it automatically. - <p> - This object provides a quick way to set up an isolated area for data operations, - while keeping normal functionality for all other Context operations. - </p> - </li> -</ul> -<h2 id="InstrumentationTestRunner">Running Tests</h2> -<p> - Test cases are run by a test runner class that loads the test case class, set ups, - runs, and tears down each test. An Android test runner must also be instrumented, so that - the system utility for starting applications can control how the test package - loads test cases and the application under test. You tell the Android platform - which instrumented test runner to use by setting a value in the test package's manifest file. -</p> -<p> - {@link android.test.InstrumentationTestRunner} is the primary Android test runner class. It - extends the JUnit test runner framework and is also instrumented. It can run any of the test - case classes provided by Android and supports all possible types of testing. -</p> -<p> - You specify <code>InstrumentationTestRunner</code> or a subclass in your test package's - manifest file, in the <a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"> - instrumentation</a> element. Also, <code>InstrumentationTestRunner</code> code resides - in the shared library <code>android.test.runner</code>, which is not normally linked to - Android code. To include it, you must specify it in a - <a href="{@docRoot}guide/topics/manifest/uses-library-element.html">uses-library</a> element. - You do not have to set up these elements yourself. Both Eclipse with ADT and the - <code>android</code> command-line tool construct them automatically and add them to your - test package's manifest file. -</p> -<p class="Note"> - <strong>Note:</strong> If you use a test runner other than - <code>InstrumentationTestRunner</code>, you must change the <instrumentation> - element to point to the class you want to use. -</p> -<p> - To run {@link android.test.InstrumentationTestRunner}, you use internal system classes called by - Android tools. When you run a test in Eclipse with ADT, the classes are called automatically. - When you run a test from the command line, you run these classes with - <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge (adb)</a>. -</p> -<p> - The system classes load and start the test package, kill any processes that - are running an instance of the application under test, and then load a new instance of the - application under test. They then pass control to - {@link android.test.InstrumentationTestRunner}, which runs - each test case class in the test package. You can also control which test cases and - methods are run using settings in Eclipse with ADT, or using flags with the command-line tools. -</p> -<p> - Neither the system classes nor {@link android.test.InstrumentationTestRunner} run - the application under test. Instead, the test case does this directly. It either calls methods - in the application under test, or it calls its own methods that trigger lifecycle events in - the application under test. The application is under the complete control of the test case, - which allows it to set up the test environment (the test fixture) before running a test. This - is demonstrated in the previous <a href="#ActivitySnippet">code snippet</a> that tests an - Activity that displays a Spinner widget. -</p> -<p> - To learn more about running tests, please read the topics - <a href="{@docRoot}guide/developing/testing/testing_eclipse.html""> - Testing in Eclipse, with ADT</a> or - <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> - Testing in Other IDes</a>. -</p> -<h2 id="TestResults">Seeing Test Results</h2> -<p> - The Android testing framework returns test results back to the tool that started the test. - If you run a test in Eclipse with ADT, the results are displayed in a new JUnit view pane. If - you run a test from the command line, the results are displayed in <code>STDOUT</code>. In - both cases, you see a test summary that displays the name of each test case and method that - was run. You also see all the assertion failures that occurred. These include pointers to the - line in the test code where the failure occurred. Assertion failures also list the expected - value and actual value. -</p> -<p> - The test results have a format that is specific to the IDE that you are using. The test - results format for Eclipse with ADT is described in - <a href="{@docRoot}guide/developing/testing/testing_eclipse.html#RunTestEclipse"> - Testing in Eclipse, with ADT</a>. The test results format for tests run from the - command line is described in - <a href="{@docRoot}guide/developing/testing/testing_otheride.html#RunTestsCommand"> - Testing in Other IDEs</a>. -</p> -<h2 id="Monkeys">monkey and monkeyrunner</h2> -<p> - The SDK provides two tools for functional-level application testing: -</p> - <ul> - <li> -The <a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a>, - usually called "monkey", is a command-line tool that sends pseudo-random streams of - keystrokes, touches, and gestures to a device. You run it with the - <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (adb) tool. - You use it to stress-test your application and report back errors that are encountered. - You can repeat a stream of events by running the tool each time with the same random - number seed. - </li> - <li> - The <a href="{@docRoot}guide/developing/tools/monkeyrunner_concepts.html">monkeyrunner</a> tool - is an API and execution environment for test programs written in Python. The API - includes functions for connecting to a device, installing and uninstalling packages, - taking screenshots, comparing two images, and running a test package against an - application. Using the API, you can write a wide range of large, powerful, and complex - tests. You run programs that use the API with the <code>monkeyrunner</code> command-line - tool. - </li> - </ul> -<h2 id="PackageNames">Working With Package names</h2> -<p> - In the test environment, you work with both Android application package names and - Java package identifiers. Both use the same naming format, but they represent substantially - different entities. You need to know the difference to set up your tests correctly. -</p> -<p> - An Android package name is a unique system name for a <code>.apk</code> file, set by the - "android:package" attribute of the <manifest> element in the package's - manifest. The Android package name of your test package must be different from the - Android package name of the application under test. By default, Android tools create the - test package name by appending ".test" to the package name of the application under test. -</p> -<p> - The test package also uses an Android package name to target the application package it - tests. This is set in the "android:targetPackage" attribute of the - <instrumentation> element in the test package's manifest. -</p> -<p> - A Java package identifier applies to a source file. This package name reflects the directory - path of the source file. It also affects the visibility of classes and members to each other. -</p> -<p> - Android tools that create test projects set up an Android test package name for you. - From your input, the tools set up the test package name and the target package name for the - application under test. For these tools to work, the application project must already exist. -</p> -<p> - By default, these tools set the Java package identifier for the test class to be the same - as the Android package identifier. You may want to change this if you want to expose - members in the application under test by giving them package visibility. If you do this, - change only the Java package identifier, not the Android package names, and change only the - test case source files. Do not change the Java package name of the generated - <code>R.java</code> class in your test package, because it will then conflict with the - <code>R.java</code> class in the application under test. Do not change the Android package name - of your test package to be the same as the application it tests, because then their names - will no longer be unique in the system. -</p> -<h2 id="WhatToTest">What to Test</h2> -<p> - The topic <a href="{@docRoot}guide/topics/testing/what_to_test.html">What To Test</a> - describes the key functionality you should test in an Android application, and the key - situations that might affect that functionality. -</p> -<p> - Most unit testing is specific to the Android component you are testing. - The topics <a href="{@docRoot}guide/topics/testing/activity_testing.html">Activity Testing</a>, - <a href="{@docRoot}guide/topics/testing/contentprovider_testing.html"> - Content Provider Testing</a>, and <a href="{@docRoot}guide/topics/testing/service_testing.html"> - Service Testing</a> each have a section entitled "What To Test" that lists possible testing - areas. -</p> -<p> - When possible, you should run these tests on an actual device. If this is not possible, you can - use the <a href="{@docRoot}guide/developing/devices/emulator.html">Android Emulator</a> with - Android Virtual Devices configured for the hardware, screens, and versions you want to test. -</p> -<h2 id="NextSteps">Next Steps</h2> -<p> - To learn how to set up and run tests in Eclipse, please refer to <a - href="{@docRoot}guide/developing/testing/testing_eclipse.html">Testing in - Eclipse, with ADT</a>. If you're not working in Eclipse, refer to <a - href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other - IDEs</a>. -</p> -<p> - If you want a step-by-step introduction to Android testing, try one of the - testing tutorials or sample test packages: -</p> -<ul> - <li> - The <a - href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello, - Testing</a> tutorial introduces basic testing concepts and procedures in the - context of the Hello, World application. - </li> - <li> - The <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity - Testing</a> tutorial is an excellent follow-up to the Hello, Testing tutorial. - It guides you through a more complex testing scenario that you develop against a - more realistic application. - </li> - <!-- sample is not available - <li> - The sample test package <a href="{@docRoot}resources/samples/AlarmServiceTest/index.html"> - Alarm Service Test</a> is an example of testing a {@link android.app.Service}. It contains - a set of unit tests for the Alarm Service sample application's {@link android.app.Service}. - </li> - --> -</ul> - diff --git a/docs/html/guide/topics/testing/what_to_test.jd b/docs/html/guide/topics/testing/what_to_test.jd deleted file mode 100644 index 99061df..0000000 --- a/docs/html/guide/topics/testing/what_to_test.jd +++ /dev/null @@ -1,86 +0,0 @@ -page.title=What To Test -parent.title=Testing -parent.link=index.html -@jd:body -<p> - As you develop Android applications, knowing what to test is as important as knowing how to - test. This document lists some most common Android-related situations that you should consider - when you test, even at the unit test level. This is not an exhaustive list, and you consult the - documentation for the features that you use for more ideas. The - <a href="http://groups.google.com/group/android-developers">android-developers</a> Google Groups - site is another resource for information about testing. -</p> -<h2 id="Tests">Ideas for Testing</h2> -<p> - The following sections are organized by behaviors or situations that you should test. Each - section contains a scenario that further illustrates the situation and the test or tests you - should do. -</p> -<h4>Change in orientation</h4> -<p> - For devices that support multiple orientations, Android detects a change in orientation when - the user turns the device so that the display is "landscape" (long edge is horizontal) instead - of "portrait" (long edge is vertical). -</p> -<p> - When Android detects a change in orientation, its default behavior is to destroy and then - re-start the foreground Activity. You should consider testing the following: -</p> -<ul> - <li> - Is the screen re-drawn correctly? Any custom UI code you have should handle changes in the - orientation. - </li> - <li> - Does the application maintain its state? The Activity should not lose anything that the - user has already entered into the UI. The application should not "forget" its place in the - current transaction. - </li> -</ul> -<h4>Change in configuration</h4> -<p> - A situation that is more general than a change in orientation is a change in the device's - configuration, such as a change in the availability of a keyboard or a change in system - language. -</p> -<p> - A change in configuration also triggers the default behavior of destroying and then restarting - the foreground Activity. Besides testing that the application maintains the UI and its - transaction state, you should also test that the application updates itself to respond - correctly to the new configuration. -</p> -<h4>Battery life</h4> -<p> - Mobile devices primarily run on battery power. A device has finite "battery budget", and when it - is gone, the device is useless until it is recharged. You need to write your application to - minimize battery usage, you need to test its battery performance, and you need to test the - methods that manage battery usage. -</p> -<p> - Techniques for minimizing battery usage were presented at the 2010 Google I/O conference in the - presentation - <a href="http://code.google.com/events/io/2009/sessions/CodingLifeBatteryLife.html"> - Coding for Life -- Battery Life, That Is</a>. This presentation describes the impact on battery - life of various operations, and the ways you can design your application to minimize these - impacts. When you code your application to reduce battery usage, you also write the - appropriate unit tests. -</p> -<h4>Dependence on external resources</h4> -<p> - If your application depends on network access, SMS, Bluetooth, or GPS, then you should - test what happens when the resource or resources are not available. -</p> -<p> - For example, if your application uses the network,it can notify the user if access is - unavailable, or disable network-related features, or do both. For GPS, it can switch to - IP-based location awareness. It can also wait for WiFi access before doing large data transfers, - since WiFi transfers maximize battery usage compared to transfers over 3G or EDGE. -</p> -<p> - You can use the emulator to test network access and bandwidth. To learn more, please see - <a href="{@docRoot}guide/developing/tools/emulator.html#netspeed">Network Speed Emulation</a>. - To test GPS, you can use the emulator console and {@link android.location.LocationManager}. To - learn more about the emulator console, please see - <a href="{@docRoot}guide/developing/tools/emulator.html#console"> - Using the Emulator Console</a>. -</p> diff --git a/docs/html/guide/topics/clipboard/copy-paste.jd b/docs/html/guide/topics/text/copy-paste.jd index 6c86f47..6c86f47 100644 --- a/docs/html/guide/topics/clipboard/copy-paste.jd +++ b/docs/html/guide/topics/text/copy-paste.jd diff --git a/docs/html/guide/topics/text/creating-input-method.jd b/docs/html/guide/topics/text/creating-input-method.jd new file mode 100644 index 0000000..e49610f --- /dev/null +++ b/docs/html/guide/topics/text/creating-input-method.jd @@ -0,0 +1,528 @@ +page.title=Creating an Input Method +parent.title=Articles +parent.link=../browser.html?tag=article +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>See also</h2> +<ol> + <li> + <a href="http://android-developers.blogspot.com/2009/04/updating-applications-for-on-screen.html">Onscreen Input Methods</a> + </li> + <li> + <a href="{@docRoot}resources/samples/SoftKeyboard/index.html">Soft Keyboard sample</a> + </li> +</ol> +</div> +</div> +<p> + An input method editor (IME) is a user control that enables users to enter text. Android + provides an extensible input method framework that allows applications to provide users + alternative input methods, such as on-screen keyboards or even speech input. Once installed, + users can select which IME they want to use from the system settings and use it across the + entire system; only one IME may be enabled at a time. +</p> +<p> + To add an IME to the Android system, you create an Android application + containing a class that extends {@link android.inputmethodservice.InputMethodService}. In + addition, you usually create a "settings" activity that passes options to the IME + service. You can also define a settings UI that's displayed as part of the system settings. +</p> +<p>This article covers the following:</p> +<ul> + <li>The IME lifecycle.</li> + <li>Declaring IME components in the application manifest.</li> + <li>The IME API.</li> + <li>Designing an IME UI.</li> + <li>Sending text from an IME to an application.</li> + <li>Working with IME subtypes.</li> +</ul> +<p> + If you haven't worked with IMEs before, you should read the introductory article + <a href="http://android-developers.blogspot.com/2009/04/updating-applications-for-on-screen.html">Onscreen Input Methods</a> first. + Also, the Soft Keyboard sample app included in the SDK contains sample code that you can modify + to start building your own IME. +</p> +<h2 id="InputMethodLifecycle">The IME Lifecycle</h2> +<p> + The following diagram describes the life cycle of an IME: +</p> +<img src="{@docRoot}resources/articles/images/inputmethod_lifecycle_image.png" alt="" height="845" + id="figure1" /> +<p class="img-caption"> + <strong>Figure 1.</strong> The life cycle of an IME. +</p> +<p> + The following sections describe how to implement the UI and code associated with an IME that + follows this lifecycle. +</p> +<h2 id="DefiningIME">Declaring IME Components in the Manifest</h2> +<p> + In the Android system, an IME is an Android application that contains a special IME service. + The application's manifest file must declare the service, request the necessary permissions, + provide an intent filter that matches the action <code>action.view.InputMethod</code>, and + provide metadata that defines characteristics of the IME. In addition, to provide a settings + interface that allows the user to modify the behavior of the IME, you can define a "settings" + activity that can be launched from System Settings. +</p> +<p> + The following snippet declares IME service. It requests the permission {@link + android.Manifest.permission#BIND_INPUT_METHOD} to allow the service to connect the IME to + the system, sets up an intent filter that matches the action + <code>android.view.InputMethod</code>, and defines metadata for the IME: +</p> +<pre> +<!-- Declares the input method service --> + <service android:name="FastInputIME" + android:label="@string/fast_input_label" + android:permission="android.permission.BIND_INPUT_METHOD"> + <intent-filter> + <action android:name="android.view.InputMethod" /> + </intent-filter> + <meta-data android:name="android.view.im" android:resource="@xml/method" /> + </service> +</pre> +<p> + This next snippet declares the settings activity for the IME. It has an intent filter for + {@link android.content.Intent#ACTION_MAIN} that indicates this activity is the main entry point + for the IME application:</p> +<pre> + <!-- Optional: an activity for controlling the IME settings --> + <activity android:name="FastInputIMESettings" + android:label="@string/fast_input_settings"> + <intent-filter> + <action android:name="android.intent.action.MAIN"/> + </intent-filter> + </activity> +</pre> +<p> + You can also provide access to the IME's settings directly from its UI. +</p> +<h2 id="IMEAPI">The Input Method API</h2> +<p> + Classes specific to IMEs are found in the {@link android.inputmethodservice} and {@link + android.view.inputmethod} packages. The {@link android.view.KeyEvent} class is important for + handling keyboard characters. +</p> +<p> + The central part of an IME is a service component, a class that extends + {@link android.inputmethodservice.InputMethodService}. In addition to implementing the + normal service lifecycle, this class has callbacks for providing your IME's UI, handling user + input, and delivering text to the field that currently has focus. By default, the + {@link android.inputmethodservice.InputMethodService} class provides most of the implementation + for managing the state and visibility of the IME and communicating with the current + input field. +</p> +<p> + The following classes are also important: +</p> +<dl> + <dt>{@link android.view.inputmethod.BaseInputConnection}</dt> + <dd> + Defines the communication channel from an {@link android.view.inputmethod.InputMethod} + back to the application that is receiving its input. You use it to read text around the + cursor, commit text to the text box, and send raw key events to the application. + Applications should extend this class rather than implementing the base interface + {@link android.view.inputmethod.InputConnection}. + </dd> + <dt>{@link android.inputmethodservice.KeyboardView}</dt> + <dd> + An extension of {@link android.view.View} that renders a keyboard and responds to user + input events. The keyboard layout is specified by an instance of + {@link android.inputmethodservice.Keyboard}, which you can define in an XML file. + </dd> +</dl> +<h2 id="IMEUI">Designing the Input Method UI</h2> +<p> + There are two main visual elements for an IME: the <strong>input</strong> view and the + <strong>candidates</strong> view. You only have to implement the elements that are relevant to + the input method you're designing. +</p> +<h3 id="InputView">Input view</h3> +<p> + The input view is the UI where the user inputs text, in the form of keyclicks, handwriting or + gestures. When the iIME is displayed for the first time, the system calls the + {@link android.inputmethodservice.InputMethodService#onCreateInputView()} callback. In your + implementation of this method, you create the layout you want to display in the IME + window and return the layout to the system. This snippet is an example of implementing the + {@link android.inputmethodservice.InputMethodService#onCreateInputView()} method: +<pre> + @Override + public View onCreateInputView() { + MyKeyboardView inputView = + (MyKeyboardView) getLayoutInflater().inflate( R.layout.input, null); + + inputView.setOnKeyboardActionListener(this); inputView.setKeyboard(mLatinKeyboard); + + return mInputView; + } +</pre> +<p> + In this example, {@code MyKeyboardView} is an instance of a custom implementation of + {@link android.inputmethodservice.KeyboardView} that renders a + {@link android.inputmethodservice.Keyboard}. If you’re building a traditional QWERTY keyboard, + see the <a href=”{@docRoot}resources/samples/SoftKeyboard/index.html”>Soft Keyboard</a> sample + app for an example of how to extend the {@link android.inputmethodservice.KeyboardView} class. +</p> +<h3 id="CandidateView">Candidates view</h3> +<p> + The candidates view is the UI where the IME displays potential word corrections or + suggestions for the user to select. In the IME lifecycle, the system calls + {@link android.inputmethodservice.InputMethodService#onCreateCandidatesView()} when it's ready + to display the candidate view. In your implementation of this method, return a layout that shows + word suggestions, or return null if you don’t want to show anything (a null response is the + default behavior, so you don’t have to implement this if you don’t provide suggestions).</p> +<p> + For an example implementation that provides user suggestions, see the + <a href=”{@docRoot}resources/samples/SoftKeyboard/index.html”>Soft Keyboard</a> sample app. +</p> +<h3 id="DesignConsiderations">UI design considerations</h3> +<p> + This section describes some specific UI design considerations for IMEs. +</p> +<h4>Handling multiple screen sizes</h4> +<p> + The UI for your IME must be able to scale for different screen sizes, and it also + must handle both landscape and portrait orientations. In non-fullscreen IME mode, leave + sufficient space for the application to show the text field and any associated context, so that + no more than half the screen is occupied by the IME. In fullscreen IME mode this is not an + issue. +</p> +<h4>Handling different input types</h4> +<p> + Android text fields allow you to set a specific input type, such as free form text, numbers, + URLs, email addresses, and search strings. When you implement a new IME, you need to + detect the input type of each field and provide the appropriate interface for it. However, you + don't have to set up your IME to check that the user entered text that's valid for the + input type; that's the responsibility of the application that owns the text field. +</p> +<p> + For example, here are screenshots of the interfaces that the Latin IME provided with the + Android platform provides for text and phone number inputs: +</p> +<img src="{@docRoot}resources/articles/images/inputmethod_text_type_screenshot.png" alt="" + height="142" id="figure2" /> +<img src="{@docRoot}resources/articles/images/inputmethod_numeric_type_screenshot.png" alt="" + height="120" id="figure2a" /> +<p class="img-caption"> + <strong>Figure 2.</strong> Latin IME input types. +</p> +<p> + When an input field receives focus and your IME starts, the system calls + {@link android.inputmethodservice.InputMethodService#onStartInputView(EditorInfo, boolean) + onStartInputView()}, passing in an {@link android.view.inputmethod.EditorInfo} object that + contains details about the input type and other attributes of the text field. In this object, + the {@link android.view.inputmethod.EditorInfo#inputType} field contains the text field's input + type. +</p> +<p> + The {@link android.view.inputmethod.EditorInfo#inputType} field is an <code>int</code> + that contains bit patterns for various input type settings. To test it for the text field's + input type, mask it with the constant {@link android.text.InputType#TYPE_MASK_CLASS}, like + this: +</p> +<pre> +inputType & InputType.TYPE_MASK_CLASS +</pre> +<p> +The input type bit pattern can have one of several values, including: +</p> +<dl> + <dt>{@link android.text.InputType#TYPE_CLASS_NUMBER}</dt> + <dd> + A text field for entering numbers. As illustrated in the previous screen shot, the + Latin IME displays a number pad for fields of this type. + </dd> + <dt>{@link android.text.InputType#TYPE_CLASS_DATETIME}</dt> + <dd> + A text field for entering a date and time. + </dd> + <dt>{@link android.text.InputType#TYPE_CLASS_PHONE}</dt> + <dd> + A text field for entering telephone numbers. + </dd> + <dt>{@link android.text.InputType#TYPE_CLASS_TEXT}</dt> + <dd> + A text field for entering all supported characters. + </dd> +</dl> +<p> + These constants are described in more detail in the reference documentation for + {@link android.text.InputType}. +</p> +<p> + The {@link android.view.inputmethod.EditorInfo#inputType} field can contain other bits that + indicate a variant of the text field type, such as: +</p> +<dl> + <dt>{@link android.text.InputType#TYPE_TEXT_VARIATION_PASSWORD}</dt> + <dd> + A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for entering passwords. The + input method will display dingbats instead of the actual text. + </dd> + <dt>{@link android.text.InputType#TYPE_TEXT_VARIATION_URI}</dt> + <dd> + A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for entering web URLs and + other Uniform Resource Identifiers (URIs). + </dd> + <dt>{@link android.text.InputType#TYPE_TEXT_FLAG_AUTO_COMPLETE}</dt> + <dd> + A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for entering text that the + application "auto-completes" from a dictionary, search, or other facility. + </dd> +</dl> +<p> + Remember to mask {@link android.view.inputmethod.EditorInfo#inputType} with the appropriate + constant when you test for these variants. The available mask constants are listed in the + reference documentation for {@link android.text.InputType}. +</p> +<p class="caution"> + <strong>Caution:</strong> In your own IME, make sure you handle text correctly when you send it + to a password field. Hide the password in your UI both in the input view and in the candidates + view. Also remember that you shouldn't store passwords on a device. To learn more, see the <a + href="{@docRoot}guide/practices/security.html">Designing for Security</a> guide. +</p> +<h2 id="SendText">Sending Text to the Application</h2> +<p> + As the user inputs text with your IME, you can send text to the application by + sending individual key events or by editing the text around the cursor in the application's text + field. In either case, you use an instance of {@link android.view.inputmethod.InputConnection} + to deliver the text. To get this instance, call + {@link android.inputmethodservice.InputMethodService#getCurrentInputConnection + InputMethodService.getCurrentInputConnection()}. +</p> +<h3 id="EditingCursor">Editing the text around the cursor</h3> +<p> + When you're handling the editing of existing text in a text field, some of the more useful + methods in {@link android.view.inputmethod.BaseInputConnection} are: +</p> +<dl> + <dt> + {@link android.view.inputmethod.BaseInputConnection#getTextBeforeCursor(int, int) + getTextBeforeCursor()}</dt> + <dd> + Returns a {@link java.lang.CharSequence} containing the number of requested characters + before the current cursor position. + </dd> + <dt> + {@link android.view.inputmethod.BaseInputConnection#getTextAfterCursor(int, int) + getTextAfterCursor()} + </dt> + <dd> + Returns a {@link java.lang.CharSequence} containing the number of requested characters + following the current cursor position. + </dd> + <dt> + {@link android.view.inputmethod.BaseInputConnection#deleteSurroundingText(int, int) + deleteSurroundingText()} + </dt> + <dd> + Deletes the specified number of characters before and following the current cursor + position. + </dd> + <dt> + {@link android.view.inputmethod.BaseInputConnection#commitText(CharSequence, int) + commitText()} + </dt> + <dd> + Commit a {@link java.lang.CharSequence} to the text field and set a new cursor + position. + </dd> +</dl> +<p> + For example, the following snippet shows how to replace the text "Fell" to the left of the + with the text "Hello!": +</p> +<pre> + InputConnection ic = getCurrentInputConnection(); + + ic.deleteSurroundingText(4, 0); + + ic.commitText("Hello", 1); + + ic.commitText("!", 1); +</pre> +<h3 id="ComposeThenCommit">Composing text before committing</h3> +<p> + If your IME does text prediction or requires multiple steps to compose a glyph or + word, you can show the progress in the text field until the user commits the word, and then you + can replace the partial composition with the completed text. You may give special treatment to + the text by adding a "span" to it when you pass it to InputConnection#setComposingText(). +</p> +<p> + The following snippet shows how to show progress in a text field: +</p> +<pre> + InputConnection ic = getCurrentInputConnection(); + + ic.setComposingText("Composi", 1); +... + + ic.setComposingText("Composin", 1); + +... + + ic.commitText("Composing ", 1); +</pre> +<p> + The following screenshots show how this appears to the user: +</p> +<img src="{@docRoot}resources/articles/images/inputmethod_composing_text_1.png" alt="" height="54" + id="figure3a" /> +<img src="{@docRoot}resources/articles/images/inputmethod_composing_text_2.png" alt="" height="53" + id="figure3b" /> +<img src="{@docRoot}resources/articles/images/inputmethod_composing_text_3.png" alt="" height="31" + id="figure3c" /> +<p class="img-caption"> + <strong>Figure 3.</strong> Composing text before committing. +</p> +<h3 id="HardwareKeyEvents">Intercepting hardware key events</h3> +<p> + Even though the input method window doesn't have explicit focus, it receives hardware key + events first and can choose to consume them or forward them along to the application. For + example, you may want to consume the directional keys to navigate within your UI for candidate + selection during composition. You may also want to trap the back key to dismiss any popups + originating from the input method window.</p> +<p> + To intercept hardware keys, override + {@link android.inputmethodservice.InputMethodService#onKeyDown(int, KeyEvent) onKeyDown()} + and {@link android.inputmethodservice.InputMethodService#onKeyUp(int, KeyEvent) onKeyUp()}. + See the <a href=”{@docRoot}resources/samples/SoftKeyboard/index.html”>Soft Keyboard</a> sample + app for an example. +</p> +<p> + Remember to call the <code>super()</code> method for keys you don't want to handle yourself. +</p> +<h2 id="IMESubTypes">Creating an IME Subtype</h2> +<p> + Subtypes allow the IME to expose multiple input modes and languages supported by an IME. A + subtype can represent: +</p> +<ul> + <li>A locale such as en_US or fr_FR</li> + <li>An input mode such as voice, keyboard, or handwriting</li> + <li> + Other input styles, forms, or properties specific to the IME, such as 10-key or qwerty + keyboard layouts. + </li> +</ul> +<p> + Basically, the mode can be any text such as "keyboard", "voice", and so forth. +</p> +<p>A subtype can also expose a combination of these.</p> +<p> + Subtype information is used for an IME switcher dialog that's available from the notification + bar and also for IME settings. The information also allows the framework to bring up a + specific subtype of an IME directly. When you build an IME, use the subtype facility, because + it helps the user identify and switch between different IME languages and modes. +</p> +<p> + You define subtypes in one of the input method's XML resource files, using the + <code><subtype></code> element. The following snippet defines an IME with two + subtypes: a keyboard subtype for the US English locale, and another keyboard subtype for the + French language locale for France: +</p> +<pre> +<input-method xmlns:android="http://schemas.android.com/apk/res/android" + android:settingsActivity="com.example.softkeyboard.Settings" + android:icon="@drawable/ime_icon" + <subtype android:name="@string/display_name_english_keyboard_ime" + android:icon="@drawable/subtype_icon_english_keyboard_ime" + android:imeSubtypeLanguage="en_US" + android:imeSubtypeMode="keyboard" + android:imeSubtypeExtraValue="somePrivateOption=true" + /> + <subtype android:name="@string/display_name_french_keyboard_ime" + android:icon="@drawable/subtype_icon_french_keyboard_ime" + android:imeSubtypeLanguage="fr_FR" + android:imeSubtypeMode="keyboard" + android:imeSubtypeExtraValue="foobar=30,someInternalOption=false" + /> + <subtype android:name="@string/display_name_german_keyboard_ime" + ... + /> +/> +</pre> +<p> + To ensure that your subtypes are labeled correctly in the UI, use %s to get a subtype label + that is the same as the subtype’s locale label. This is demonstrated in the next two snippets. + The first snippet shows part of the input method's XML file: +</p> +<pre> + <subtype + android:label="@string/label_subtype_generic" + android:imeSubtypeLocale="en_US" + android:icon="@drawable/icon_en_us" + android:imeSubtypeMode="keyboard" /> +</pre> +<p> + The next snippet is part of the IME's <code>strings.xml</code> file. The string + resource <code>label_subtype_generic</code>, which is used by the input method UI definition to + set the subtype's label, is defined as: +</p> +<pre> +<string name="label_subtype_generic">%s</string> +</pre> +<p> + This sets the subtype’s display name to “English (United States)” in any English language + locale, or to the appropriate localization in other locales. +</p> +<h3 id="SubtypeProcessing">Choosing IME subtypes from the notification bar</h3> +<p> + The Android system manages all subtypes exposed by all IMEs. IME subtypes are + treated as modes of the IME they belong to. In the notification bar, a user can select an + available subtype for the currently-set IME, as shown in the following screenshot: +</p> +<img src="{@docRoot}resources/articles/images/inputmethod_subtype_notification.png" alt="" + height="85" id="figure4" /> +<p class="img-caption"> + <strong>Figure 4.</strong> Choosing an IME subtype from the notification bar. +</p> +<img src="{@docRoot}resources/articles/images/inputmethod_subtype_preferences.png" alt="" + height="165" id="figure5" /> +<p class="img-caption"> + <strong>Figure 5.</strong> Setting subtype preferences in System Settings. +</p> +<h3 id="SubtypeSettings">Choosing IME subtypes from System Settings</h3> +<p> + A user can control how subtypes are used in the “Language & input” settings panel in the + System Settings area. In the Soft Keyboard sample, the file + <code>InputMethodSettingsFragment.java</code> contains an implementation that + facilitates a subtype enabler in the IME settings. Please refer to the SoftKeyboard sample in + the Android SDK for more information about how to support Input Method Subtypes in your IME. +</p> +<img src="{@docRoot}resources/articles/images/inputmethod_subtype_settings.png" alt="" + height="210" id="figure6" /> +<p class="img-caption"> + <strong>Figure 6.</strong> Choosing a language for the IME. +</p> +<h2 id="GeneralDesign">General IME Considerations</h2> +<p> + Here are some other things to consider as you're implementing your IME: +</p> +<ul> +<li> + Provide a way for users to set options directly from the IME's UI. +</li> +<li> + Because multiple IMEs may be installed on the device, provide a way for the user to switch to a + different IME directly from the input method UI. +</li> +<li> + Bring up the IME's UI quickly. Preload or load on demand any large resources so that users + see the IME as soon as they tap on a text field. Cache resources and views for subsequent + invocations of the input method. +</li> +<li> + Conversely, you should release large memory allocations soon after the input method window is + hidden, so that applications can have sufficient memory to run. Consider using a delayed message + to release resources if the IME is in a hidden state for a few seconds. +</li> +<li> + Make sure that users can enter as many characters as possible for the language or locale + associated with the IME. Remember that users may use punctuation in passwords or user + names, so your IME has to provide many different characters to allow users to enter a + password and get access to the device. +</li> +</ul> diff --git a/docs/html/guide/topics/text/index.jd b/docs/html/guide/topics/text/index.jd new file mode 100644 index 0000000..3865f25 --- /dev/null +++ b/docs/html/guide/topics/text/index.jd @@ -0,0 +1,40 @@ +page.title=Text and Input +page.landing=true +page.landing.intro=Use text services to add conventient features such as copy/paste and spell checking to your app. You can also develop your own text services to offer custom IMEs, dictionaries, and spelling checkers that you can distribute to users as applications. +page.landing.image= + +@jd:body + +<div class="landing-docs"> + + <div class="col-12"> + <h3>Blog Articles</h3> + + <a href="http://android-developers.blogspot.com/2011/12/add-voice-typing-to-your-ime.html"> + <h4>Add Voice Typing To Your IME</h4> + <p>A new feature available in Android 4.0 is voice typing: the difference for users is that +the recognition results appear in the text box while they are still speaking. If you are an IME +developer, you can easily integrate with voice typing.</p> + </a> + + <a href="http://android-developers.blogspot.com/2010/03/speech-input-api-for-android.html"> + <h4>Speech Input API for Android</h4> + <p>We believe speech can fundamentally change the mobile experience. We would like to invite +every Android application developer to consider integrating speech input capabilities via the +Android SDK.</p> + </a> + + <a href="http://android-developers.blogspot.com/2010/06/making-sense-of-multitouch.html"> + <h4>Making Sense of Multitouch</h4> + <p>The word "multitouch" gets thrown around quite a bit and it’s not always clear what people +are referring to. For some it’s about hardware capability, for others it refers to specific gesture +support in software. Whatever you decide to call it, today we’re going to look at how to make your +apps and views behave nicely with multiple fingers on the screen.</p> + </a> + </div> + + <div class="col-6"> + + </div> + +</div>
\ No newline at end of file diff --git a/docs/html/guide/topics/text/spell-checker-framework.jd b/docs/html/guide/topics/text/spell-checker-framework.jd new file mode 100644 index 0000000..05b6890 --- /dev/null +++ b/docs/html/guide/topics/text/spell-checker-framework.jd @@ -0,0 +1,236 @@ +page.title=Spelling Checker Framework +parent.title=Articles +parent.link=../browser.html?tag=article +@jd:body +<div id="qv-wrapper"> +<div id="qv"> +<h2>In This Document</h2> +<ol> + <li> + <a href="#SpellCheckLifeCycle">Spell Check Lifecycle</a> + </li> + <li> + <a href="#SpellCheckImplementation">Implementing a Spell Checker Service</a> + </li> + <li> + <a href="#SpellCheckClient">Implementing a Spell Checker Client</a> + </li> +</ol> + <h2>See also</h2> + <ol> + <li> + <a href="{@docRoot}resources/samples/SpellChecker/SampleSpellCheckerService/index.html"> + Spell Checker Service</a> sample app + </li> + <li> + <a href="{@docRoot}resources/samples/SpellChecker/HelloSpellChecker/index.html"> + Spell Checker Client</a> sample app + </li> + </ol> +</div> +</div> + +<p> + The Android platform offers a spelling checker framework that lets you implement + and access spell checking in your application. The framework is one of the + Text Service APIs offered by the Android platform. +</p> +<p> + To use the framework in your app, you create a special type of Android service that + generates a spelling checker <strong>session</strong> object. Based on text you provide, + the session object returns spelling suggestions generated by the spelling checker. +</p> +<h2 id="SpellCheckLifeCycle">Spell Checker Lifecycle</h2> +<p> + The following diagram shows the lifecycle of the spelling checker service: +</p> +<img src="{@docRoot}resources/articles/images/spellcheck_lifecycle.png" alt="" height="596" + id="figure1" /> +<p class="img-caption"> + <strong>Figure 1.</strong> The spelling checker service lifecycle. +</p> +<p> + To initiate spell checking, your app starts its implementation of the spelling checker + service. Clients in your app, such as activities or individual UI elements, request a + spelling checker session from the service, then use the session to get suggestions for text. + As a client terminates its operation, it closes its spelling checker session. If necessary, your + app can shut down the spelling checker service at any time. +</p> +<h2 id="SpellCheckImplementation">Implementing a Spell Checker Service</h2> +<p> + To use the spelling checker framework in your app, add a spelling checker service component including + the session object definition. You can also add to your app an optional activity that + controls settings. You must also add an XML metadata file that describes + the spelling checker service, and add the appropriate elements to your manifest file. +</p> +<h3 id="SpellCheckCode">Spell checker classes</h3> +<p> + Define the service and session object with the following classes: +</p> +<dl> + <dt> + A subclass of {@link android.service.textservice.SpellCheckerService} + </dt> + <dd> + The {@link android.service.textservice.SpellCheckerService} implements both the + {@link android.app.Service} class and the spelling checker framework interface. Within your + subclass, you must implement the following method: + <dl> + <dt>{@link android.service.textservice.SpellCheckerService#createSession()}</dt> + <dd> + A factory method that returns a + {@link android.service.textservice.SpellCheckerService.Session} object to a + client that wants to do spell checking. + </dd> + </dl> + <p> + See the + <a href="{@docRoot}resources/samples/SpellChecker/SampleSpellCheckerService/index.html"> + Spell Checker Service</a> sample app to learn more about implementing this class. + </p> + </dd> + <dt> + An implementation of {@link android.service.textservice.SpellCheckerService.Session} + </dt> + <dd> + An object that the spelling checker service provides to clients, to let them pass text to + the spelling checker and receive suggestions. Within this class, you must implement the + following methods: + <dl> + <dt> + {@link android.service.textservice.SpellCheckerService.Session#onCreate()} + </dt> + <dd> + Called by the system in response to + {@link android.service.textservice.SpellCheckerService#createSession()}. In this + method, you can initialize the + {@link android.service.textservice.SpellCheckerService.Session} object based on + the current locale and so forth. + </dd> + <dt> + {@link android.service.textservice.SpellCheckerService.Session#onGetSuggestions(TextInfo, int) + onGetSuggestions()} + </dt> + <dd> + Does the actual spell checking. This method returns an object containing + suggestions for the text passed to it. + </dd> + </dl> + <p> + Optionally, you can implement + {@link android.service.textservice.SpellCheckerService.Session#onCancel()}, which + handles requests to cancel spell checking, or +{@link android.service.textservice.SpellCheckerService.Session#onGetSuggestionsMultiple(TextInfo[], int, boolean) +onGetSuggestionsMultiple()}, which handles batches of suggestion requests, or both. + </p> + <p> + See the + <a href="{@docRoot}resources/samples/SpellChecker/HelloSpellChecker/index.html"> + Spell Checker Client</a> sample app to learn more about implementing this class. + </p> + </dd> +</dl> +<p class="note"> + <strong>Note:</strong> You must implement all aspects of spell checking as asynchronous and + thread-safe. A spelling checker may be called simultaneously by different threads running on + different cores. The {@link android.service.textservice.SpellCheckerService} and + {@link android.service.textservice.SpellCheckerService.Session} take care of this + automatically. +</p> +<h3 id="SpellCheckXML">Spell checker manifest and metadata</h3> +<p> + In addition to code, you need to provide the appropriate manifest file and a metadata file for + the spelling checker. +</p> +<p> + The manifest file defines the application, the service, and the activity for controlling + settings, as shown in the following snippet: +</p> +<pre> +<manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.example.android.samplespellcheckerservice" > + <application + android:label="@string/app_name" > + <service + android:label="@string/app_name" + android:name=".SampleSpellCheckerService" + android:permission="android.permission.BIND_TEXT_SERVICE" > + <intent-filter > + <action android:name="android.service.textservice.SpellCheckerService" /> + </intent-filter> + + <meta-data + android:name="android.view.textservice.scs" + android:resource="@xml/spellchecker" /> + </service> + + <activity + android:label="@string/sample_settings" + android:name="SpellCheckerSettingsActivity" > + <intent-filter > + <action android:name="android.intent.action.MAIN" /> + </intent-filter> + </activity> + </application> +</manifest> +</pre> +<p> + Notice that components that want to use the service must request the permission + {@link android.Manifest.permission#BIND_TEXT_SERVICE} to ensure that only the system binds to + the service. The service's definition also specifies the <code>spellchecker.xml</code> metadata + file, which is described in the next section. +</p> +<p> + The metadata file <code>spellchecker.xml</code> contains the following XML: +</p> +<pre> +<spell-checker xmlns:android="http://schemas.android.com/apk/res/android" + android:label="@string/spellchecker_name" + android:settingsActivity="com.example.SpellCheckerSettingsActivity"> + <subtype + android:label="@string/subtype_generic" + android:subtypeLocale="en” + /> + <subtype + android:label="@string/subtype_generic" + android:subtypeLocale="fr” + /> +</spell-checker> +</pre> +<p> + The metadata specifies the activity that the spelling checker uses for controlling settings. It + also defines subtypes for the spelling checker; in this case, the subtypes define locales that + the spelling checker can handle. +</p> + + +<!-- Accessing the Spell Checker Service from a Client --> +<h2 id="SpellCheckClient">Accessing the Spell Checker Service from a Client</h2> +<p> + Applications that use {@link android.widget.TextView} views automatically benefit from spell + checking, because {@link android.widget.TextView} automatically uses a spelling checker. The + following screenshots show this: +</p> +<img src="{@docRoot}resources/articles/images/textview_spellcheck_screenshot_1.png" alt="" + height="45" id="figure2a" /> +<br> +<img src="{@docRoot}resources/articles/images/textview_spellcheck_screenshot_2.png" alt="" + height="121" id="figure2b" /> +<p class="img-caption"> + <strong>Figure 2.</strong> Spell checking in TextView. +</p> +<p> + However, you may want to interact directly with a spelling checker service in other cases as well. + The following diagram shows the flow of control for interacting with a spelling checker service: +</p> +<img src="{@docRoot}resources/articles/images/spellcheck_client_flow.png" alt="" + height="394" id="figure3" /> +<p class="img-caption"> + <strong>Figure 3.</strong> Interacting with a spelling checker service. +</p> +<p> + The <a href="{@docRoot}resources/samples/SpellChecker/HelloSpellChecker/index.html"> + Spell Checker Client</a> sample app shows how to interact with a spelling checker service. The + LatinIME input method editor in the Android Open Source Project also contains an example of + spell checking. +</p>
\ No newline at end of file diff --git a/docs/html/guide/topics/ui/accessibility/apps.jd b/docs/html/guide/topics/ui/accessibility/apps.jd index dc91638..d23512b 100644 --- a/docs/html/guide/topics/ui/accessibility/apps.jd +++ b/docs/html/guide/topics/ui/accessibility/apps.jd @@ -328,7 +328,7 @@ following approaches:</p> <li>If your application targets Android 4.0 (API level 14) and higher, override and implement the accessibility methods listed above directly in your custom view class.</li> <li>If your custom view is intended to be compatible with Android 1.6 (API Level 4) and above, add -the Android <a href="{@docRoot}sdk/compatibility-library.html">Support Library</a>, revision 5 or +the Android <a href="{@docRoot}tools/extras/support-library.html">Support Library</a>, revision 5 or higher, to your project. Then, within your custom view class, call the {@link android.support.v4.view.ViewCompat#setAccessibilityDelegate ViewCompat.setAccessibilityDelegate()} method to implement the accessibility methods @@ -467,7 +467,7 @@ appropriate feedback to users.</p> <p>The example code below shows how override these three methods by using {@link android.support.v4.view.ViewCompat#setAccessibilityDelegate ViewCompat.setAccessibilityDelegate()}. Note that this sample code requires that the Android -<a href="{@docRoot}sdk/compatibility-library.html">Support Library</a> for API Level 4 (revision 5 +<a href="{@docRoot}tools/extras/support-library.html">Support Library</a> for API Level 4 (revision 5 or higher) is added to your project.</p> <pre> @@ -511,7 +511,7 @@ ViewCompat.setAccessibilityDelegate(new AccessibilityDelegateCompat() { <p>On applications targeting Android 4.0 (API Level 14) and higher, these methods can be implemented directly in your custom view class. For another example of this approach, see the Android -<a href="{@docRoot}sdk/compatibility-library.html">Support Library</a> (revision 5 or higher) sample +<a href="{@docRoot}tools/extras/support-library.html">Support Library</a> (revision 5 or higher) sample {@code AccessibilityDelegateSupportActivity} in ({@code <sdk>/extras/android/support/v4/samples/Support4Demos/}).</p> @@ -567,7 +567,7 @@ option is not available.</p> <p>As part of your accessibility testing, you can test navigation of your application using focus, even if your test devices does not have a directional controller. The <a -href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> provides a +href="{@docRoot}tools/help/emulator.html">Android Emulator</a> provides a simulated directional controller that you can easily use to test navigation. You can also use a software-based directional controller, such as the one provided by the <a href="https://play.google.com/store/apps/details?id=com.googlecode.eyesfree.inputmethod.latin"> diff --git a/docs/html/guide/topics/ui/accessibility/index.jd b/docs/html/guide/topics/ui/accessibility/index.jd index 414d5f3..6fd71e2 100644 --- a/docs/html/guide/topics/ui/accessibility/index.jd +++ b/docs/html/guide/topics/ui/accessibility/index.jd @@ -47,9 +47,9 @@ Accessible</a></strong> <dd>Development practices and API features to ensure your application is accessible to users with disabilities.</dd> - <dt><strong><a href="{@docRoot}guide/topics/ui/accessibility/service.html">Building Accessibility + <dt><strong><a href="{@docRoot}guide/topics/ui/accessibility/services.html">Building Accessibility Services</a></strong> </dt> <dd>How to use API features to build services that make other applications more accessible for users.</dd> -</dl>
\ No newline at end of file +</dl> diff --git a/docs/html/guide/topics/ui/accessibility/services.jd b/docs/html/guide/topics/ui/accessibility/services.jd index 0dad4ec..0c1d065 100644 --- a/docs/html/guide/topics/ui/accessibility/services.jd +++ b/docs/html/guide/topics/ui/accessibility/services.jd @@ -50,7 +50,7 @@ accessibility service.</p> Support Library was also updated with the release of Android 4.0 to provide support for these enhanced accessibility features back to Android 1.6. Developers aiming for widely compatible accessibility services are encouraged to use the -<a href="{@docRoot}sdk/compatibility-library.html">Support Library</a> and develop for the more +<a href="{@docRoot}tools/extras/support-library.html">Support Library</a> and develop for the more advanced accessibility features introduced in Android 4.0.</p> @@ -279,7 +279,7 @@ android.accessibilityservice.AccessibilityService} and can be used as a base for accessibility services that are compatible with Android 1.6 (API Level 4) and higher.</li> <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/accessibility/TaskBackService.html">TaskBackService</a> - This service is based on the enhanced accessibility APIs introduced in Android 4.0 (API Level -14). However, you can use the Android <a href="{@docRoot}sdk/compatibility-library.html">Support +14). However, you can use the Android <a href="{@docRoot}tools/extras/support-library.html">Support Libary</a> to substitute classes introduced in later API levels (e.g., {@link android.view.accessibility.AccessibilityRecord}, {@link android.view.accessibility.AccessibilityNodeInfo} diff --git a/docs/html/guide/topics/ui/actionbar.jd b/docs/html/guide/topics/ui/actionbar.jd index bf7369a..4842000 100644 --- a/docs/html/guide/topics/ui/actionbar.jd +++ b/docs/html/guide/topics/ui/actionbar.jd @@ -6,13 +6,6 @@ parent.link=index.html <div id="qv-wrapper"> <div id="qv"> - <h2>Quickview</h2> - <ul> - <li>A title bar that includes the application icon and activity title</li> - <li>Provides access to menu items and navigation modes such as tabs</li> - <li>Requires API level 11 or greater</li> - </ul> - <h2>In this document</h2> <ol> <li><a href="#Adding">Adding the Action Bar</a> @@ -102,7 +95,7 @@ navigation label, such as the currently selected tab.</p></li> <li>Provide consistent navigation and view refinement across different applications. <p>The action bar provides built-in tab navigation for switching between <a -href="{@docRoot}guide/topics/fundamentals/fragments.html">fragments</a>. It also offers a drop-down +href="{@docRoot}guide/components/fragments.html">fragments</a>. It also offers a drop-down list you can use as an alternative navigation mode or to refine the current view (such as to sort a list by different criteria).</p> </li> @@ -120,7 +113,7 @@ include a <em>Menu</em> button).</p> </li> </ul> -<img src="{@docRoot}images/ui/actionbar.png" alt="" /> +<img src="{@docRoot}images/ui/actionbar.png" alt="" width="440" /> <p class="img-caption"><strong>Figure 1.</strong> Action bar from the <a href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a> app (on a landscape handset), showing the logo on the left, navigation tabs, and an action item on the @@ -510,7 +503,7 @@ intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_NEW_TASK); </pre> <p>For more information about these flags and other back stack behaviors, read the <a -href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back Stack</a> +href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back Stack</a> developer guide.</p> <p class="note"><strong>Note:</strong> If you're using the icon to navigate to the home @@ -955,7 +948,7 @@ when the screen is too narrow, as shown in figures 9 and 10.</p> <p>To switch between fragments using the tabs, you must perform a fragment transaction each time a tab is selected. If you're not familiar with how to change fragments using {@link android.app.FragmentTransaction}, first read the <a -href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a> developer guide.</p> +href="{@docRoot}guide/components/fragments.html">Fragments</a> developer guide.</p> <p>To get started, your layout must include a {@link android.view.ViewGroup} in which you place each {@link android.app.Fragment} associated with a tab. Be sure the {@link android.view.ViewGroup} has a @@ -1092,7 +1085,7 @@ href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/Frag <p>If your activity stops, you should retain the currently selected tab with the <a -href="{@docRoot}guide/topics/fundamentals/activities.html#SavingActivityState">saved instance +href="{@docRoot}guide/components/activities.html#SavingActivityState">saved instance state</a> so you can open the appropriate tab when the user returns. When it's time to save the state, you can query the currently selected tab with {@link android.app.ActionBar#getSelectedNavigationIndex()}. This returns the index position of the selected @@ -1101,7 +1094,7 @@ tab.</p> <p class="caution"><strong>Caution:</strong> It's important that you save the state of each fragment as necessary, so that when users switch fragments with the tabs and then return to a previous fragment, it looks the way it did when they left. For information about saving the state of your -fragment, see the <a href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a> +fragment, see the <a href="{@docRoot}guide/components/fragments.html">Fragments</a> developer guide.</p> diff --git a/docs/html/guide/topics/ui/binding.jd b/docs/html/guide/topics/ui/binding.jd index 26364ee..e8b49d5 100644 --- a/docs/html/guide/topics/ui/binding.jd +++ b/docs/html/guide/topics/ui/binding.jd @@ -1,4 +1,4 @@ -page.title=Binding to Data with AdapterView +page.title=AdapterView parent.title=User Interface parent.link=index.html @jd:body @@ -20,32 +20,7 @@ parent.link=index.html </div> </div> -<p>The {@link android.widget.AdapterView} is a ViewGroup subclass whose child Views are determined by an {@link android.widget.Adapter Adapter} that -binds to data of some type. AdapterView is useful whenever you need to display stored data (as opposed to resource strings or drawables) in your layout.</p> -<p>{@link android.widget.Gallery Gallery}, {@link android.widget.ListView ListView}, and {@link android.widget.Spinner Spinner} are examples of AdapterView subclasses that you can use to bind to a specific type of data and display it in a certain way. </p> - - -<p>AdapterView objects have two main responsibilities: </p> -<ul> - <li>Filling the layout with data - </li> - <li>Handling user selections - </li> -</ul> - - -<h2 id="FillingTheLayout">Filling the Layout with Data</h2> -<p>Inserting data into the layout is typically done by binding the AdapterView class to an {@link -android.widget.Adapter}, which retrieves data from an external source (perhaps a list that -the code supplies or query results from the device's database). </p> -<p>The following code sample does the following:</p> -<ol> - <li>Creates a {@link android.widget.Spinner Spinner} with an existing View and binds it to a new ArrayAdapter -that reads an array of colors from the local resources.</li> - <li>Creates another Spinner object from a View and binds it to a new SimpleCursorAdapter that will read -people's names from the device contacts (see {@link android.provider.Contacts.People}).</li> -</ol> <pre> // Get a Spinner and bind it to an ArrayAdapter that diff --git a/docs/html/guide/topics/ui/controls.jd b/docs/html/guide/topics/ui/controls.jd new file mode 100644 index 0000000..83bb0c8 --- /dev/null +++ b/docs/html/guide/topics/ui/controls.jd @@ -0,0 +1,92 @@ +page.title=Input Controls +parent.title=User Interface +parent.link=index.html +@jd:body + +<div class="figure" style="margin:0"> + <img src="{@docRoot}images/ui/ui-controls.png" alt="" style="margin:0" /> +</div> + +<p>Input controls are the interactive components in your app's user interface. Android provides a +wide variety of controls you can use in your UI, such as buttons, text fields, seek bars, +checkboxes, zoom buttons, toggle buttons, and many more.</p> + +<p>Adding an input control to your UI is as simple as adding an XML element to your <a +href="{@docRoot}guide/topics/ui/declaring-layout.html">XML layout</a>. For example, here's a +layout with a text field and button:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:orientation="horizontal"> + <EditText android:id="@+id/edit_message" + android:layout_weight="1" + android:layout_width="0dp" + android:layout_height="wrap_content" + android:hint="@string/edit_message" /> + <Button android:id="@+id/button_send" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/button_send" + android:onClick="sendMessage" /> +</LinearLayout> +</pre> + +<p>Each input control supports a specific set of input events so you can handle events such as when +the user enters text or touches a button.</p> + + +<h2 id="CommonControls">Common Controls</h2> +<p>Here's a list of some common controls that you can use in your app. Follow the links to learn +more about using each one.</p> + +<p class="note"><strong>Note:</strong> Android provides several more controls than are listed +here. Browse the {@link android.widget} package to discover more. If your app requires a +specific kind of input control, you can build your own <a +href="{@docRoot}guide/topics/ui/custom-components.html">custom components</a>.</p> + +<table> + <tr> + <th scope="col">Control Type</th> + <th scope="col">Description</th> + <th scope="col">Related Classes</th> + </tr> + <tr> + <td><a href="controls/button.html">Button</a></td> + <td>A push-button that can be pressed, or clicked, by the user to perform an action.</td> + <td>{@link android.widget.Button Button} </td> + </tr> + <tr> + <td><a href="controls/text.html">Text field</a></td> + <td>An editable text field. You can use the <code>AutoCompleteTextView</code> widget to create a text entry widget that provides auto-complete suggestions</td> + <td>{@link android.widget.EditText EditText}, {@link android.widget.AutoCompleteTextView}</td> + </tr> + <tr> + <td><a href="controls/checkbox.html">Checkbox</a></td> + <td>An on/off switch that can be toggled by the user. You should use checkboxes when presenting users with a group of selectable options that are not mutually exclusive.</td> + <td>{@link android.widget.CheckBox CheckBox} </td> + </tr> + <tr> + <td><a href="controls/radiobutton.html">Radio button</a></td> + <td>Similar to checkboxes, except that only one option can be selected in the group.</td> + <td>{@link android.widget.RadioGroup RadioGroup} + <br>{@link android.widget.RadioButton RadioButton} </td> + </tr> + <tr> + <td><a href="controls/togglebutton.html" style="white-space:nowrap">Toggle button</a></td> + <td>An on/off button with a light indicator.</td> + <td>{@link android.widget.ToggleButton ToggleButton} </td> + </tr> + <tr> + <td><a href="controls/spinner.html">Spinner</a></td> + <td>A drop-down list that allows users to select one value from a set.</td> + <td>{@link android.widget.Spinner Spinner} </td> + </tr> + <tr> + <td><a href="controls/pickers.html">Pickers</a></td> + <td>A dialog for users to select a single value for a set by using up/down buttons or via a swipe gesture. Use a <code>DatePicker</code>code> widget to enter the values for the date (month, day, year) or a <code>TimePicker</code> widget to enter the values for a time (hour, minute, AM/PM), which will be formatted automatically for the user's locale.</td> + <td>{@link android.widget.DatePicker}, {@link android.widget.TimePicker}</td> + </tr> +</table> diff --git a/docs/html/guide/topics/ui/controls/button.jd b/docs/html/guide/topics/ui/controls/button.jd new file mode 100644 index 0000000..8d48e9c --- /dev/null +++ b/docs/html/guide/topics/ui/controls/button.jd @@ -0,0 +1,245 @@ +page.title=Buttons +parent.title=Input Controls +parent.link=../controls.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> +<ol> + <li><a href="#HandlingEvents">Responding to Click Events</a> + <ol> + <li><a href="#ClickListener">Using an OnClickListener</a></li> + </ol> + </li> + <li><a href="#Style">Styling Your Button</a> + <ol> + <li><a href="#Borderless">Borderless button</a></li> + <li><a href="#CustomBackground">Custom background</a></li> + </ol> + </li> +</ol> + <h2>Key classes</h2> + <ol> + <li>{@link android.widget.Button}</li> + <li>{@link android.widget.ImageButton}</li> + </ol> +</div> +</div> + + +<p>A button consists of text or an icon (or both text and an icon) that communicates what action +occurs when the user touches it.</p> + +<img src="{@docRoot}images/ui/button-types.png" alt="" /> + +<p>Depending on whether you want a button with text, an icon, or both, you can create the +button in your layout in three ways:</p> +<ul> + <li>With text, using the {@link android.widget.Button} class: +<pre> +<Button + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/button_text" + ... /> +</pre> + </li> + <li>With an icon, using the {@link android.widget.ImageButton} class: +<pre> +<ImageButton + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:src="@drawable/button_icon" + ... /> +</pre> + </li> + <li>With text and an icon, using the {@link android.widget.Button} class with the <a +href="{@docRoot}reference/android/widget/TextView.html#attr_android:drawableLeft">{@code +android:drawableLeft}</a> attribute: +<pre> +<Button + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/button_text" + android:drawableLeft="@drawable/button_icon" + ... /> +</pre> +</li> +</ul> + +<h2 id="HandlingEvents">Responding to Click Events</h2> + +<p>When the user clicks a button, the {@link android.widget.Button} object receives +an on-click event.</p> + +<p>To define the click event handler for a button, add the {@link +android.R.attr#onClick android:onClick} attribute to the {@code <Button>} element in your XML +layout. The value for this attribute must be the name of the method you want to call in response +to a click event. The {@link android.app.Activity} hosting the layout must then implement the +corresponding method.</p> + +<p>For example, here's a layout with a button using {@link +android.R.attr#onClick android:onClick}:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<Button xmlns:android="http://schemas.android.com/apk/res/android" + android:id="@+id/button_send" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/button_send" + android:onClick="sendMessage" /> +</pre> + +<p>Within the {@link android.app.Activity} that hosts this layout, the following method handles +the click event:</p> + +<pre> +/** Called when the user touches the button */ +public void sendMessage(View view) { + // Do something in response to button click +} +</pre> + +<p>The method you declare in the {@link android.R.attr#onClick android:onClick} attribute must have +a signature exactly as shown above. Specifically, the method must:</p> +<ul> + <li>Be public</li> + <li>Return void</li> + <li>Define a {@link android.view.View} as its only parameter (this will be the {@link +android.view.View} that was clicked)</li> +</ul> + + +<h3 id="ClickListener">Using an OnClickListener</h3> + +<p>You can also declare the click event handler pragmatically rather than in an XML layout. This +might be necessary if you instantiate the {@link android.widget.Button} at runtime or you need to +declare the click behavior in a {@link android.app.Fragment} subclass.</p> + +<p>To declare the event handler programmatically, create an {@link +android.view.View.OnClickListener} object and assign it to the button by calling {@link +android.view.View#setOnClickListener}. For example:</p> + +<pre> +Button button = (Button) findViewById(R.id.button_send); +button.setOnClickListener(new View.OnClickListener() { + public void onClick(View v) { + // Do something in response to button click + } +}); +</pre> + + +<h2 id="Style">Styling Your Button</h2> + +<p>The appearance of your button (background image and font) may vary from one device to +another, because devices by different manufacturers often have different default styles for +input controls.</p> + +<p>You can control exactly how your controls are styled using a theme that you apply to your +entire application. For instance, to ensure that all devices running Android 4.0 and higher use +the Holo theme in your app, declare {@code android:theme="@android:style/Theme.Holo"} in your +manifest's {@code <application>} element. Also read the blog post, <a +href="http://android-developers.blogspot.com/2012/01/holo-everywhere.html">Holo Everywhere</a> +for information about using the Holo theme while supporting older devices.</p> + +<p>To customize individual buttons with a different background, specify the {@link +android.R.attr#background android:background} attribute with a drawable or color resource. +Alternatively, you can apply a <em>style</em> for the button, which works in a manner similar to +HTML styles to define multiple style properties such as the background, font, size, and others. +For more information about applying styles, see <a +href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a>.</p> + + +<h3 id="Borderless">Borderless button</h3> + +<p>One design that can be useful is a "borderless" button. Borderless buttons resemble +basic buttons except that they have no borders or background but still change appearance during +different states, such as when clicked.</p> + +<p>To create a borderless button, apply the {@link android.R.attr#borderlessButtonStyle} +style to the button. For example:</p> + +<pre> +<Button + android:id="@+id/button_send" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/button_send" + android:onClick="sendMessage" + style="?android:attr/borderlessButtonStyle" /> +</pre> + + + +<h3 id="CustomBackground">Custom background</h3> + +<p>If you want to truly redefine the appearance of your button, you can specify a custom +background. Instead of supplying a simple bitmap or color, however, your background should be a +state list resource that changes appearance depending on the button's current state.</p> + +<p>You can define the state list in an XML file that defines three different images or colors to use +for the different button states.</p> + +<p>To create a state list drawable for your button background:</p> + +<ol> + <li>Create three bitmaps for the button background that represent the default, pressed, and +focused button states. + <p>To ensure that your images fit buttons of various sizes, create the bitmaps as <a +href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">Nine-patch</a> bitmaps.</p> + </li> + <li>Place the bitmaps into the <code>res/drawable/</code> directory of +your project. Be sure each bitmap is named properly to reflect the button state that they each +represent, such as {@code button_default.9.png}, {@code button_pressed.9.png}, and {@code +button_focused.9.png}.</li> + <li>Create a new XML file in the <code>res/drawable/</code> directory (name it something like +<code>button_custom.xml</code>). Insert the following XML: +<pre> +<?xml version="1.0" encoding="utf-8"?> +<selector xmlns:android="http://schemas.android.com/apk/res/android"> + <item android:drawable="@drawable/button_pressed" + android:state_pressed="true" /> + <item android:drawable="@drawable/button_focused" + android:state_focused="true" /> + <item android:drawable="@drawable/button_default" /> +</selector> +</pre> + <p>This defines a single drawable resource, which will change its image based on the current +state of the button.</p> +<ul> + <li>The first <code><item></code> defines the bitmap to use when the button is +pressed (activated).</li> + <li>The second <code><item></code> defines the bitmap to use when the button is +focused (when the button is highlighted using the trackball or directional +pad).</li> + <li>The third <code><item></code> defines the bitmap to use when the button is in the +default state (it's neither pressed nor focused).</li> +</ul> + <p class="note"><strong>Note:</strong> The order of the <code><item></code> elements is +important. When this drawable is referenced, the <code><item></code> elements are traversed +in-order to determine which one is appropriate for the current button state. Because the default +bitmap is last, it is only applied when the conditions <code>android:state_pressed</code> and +<code>android:state_focused</code> have both evaluated as false.</p> + <p>This XML file now represents a single +drawable resource and when referenced by a {@link android.widget.Button} for its background, +the image displayed will change based on these three states.</p> +</li> + <li>Then simply apply the drawable XML file as the button background: +<pre> +<Button + android:id="@+id/button_send" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/button_send" + android:onClick="sendMessage" + android:background="@drawable/button_custom" /> +</pre> +</ol> + + <p>For more information about this XML syntax, including how to define a disabled, hovered, or +other button states, read about <a +href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">State List +Drawable</a>.</p>
\ No newline at end of file diff --git a/docs/html/guide/topics/ui/controls/checkbox.jd b/docs/html/guide/topics/ui/controls/checkbox.jd new file mode 100644 index 0000000..35b8f56 --- /dev/null +++ b/docs/html/guide/topics/ui/controls/checkbox.jd @@ -0,0 +1,101 @@ +page.title=Checkboxes +parent.title=Input Controls +parent.link=../controls.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> +<ol> + <li><a href="#HandlingEvents">Responding to Click Events</a></li> +</ol> + +<h2>Key classes</h2> +<ol> + <li>{@link android.widget.CheckBox}</li> +</ol> +</div> +</div> + +<p>Checkboxes allow the user to select one or more options from a set. Typically, you should +present each checkbox option in a vertical list.</p> + +<img src="{@docRoot}images/ui/checkboxes.png" alt="" /> + +<p>To create each checkbox option, create a {@link android.widget.CheckBox} in your layout. Because +a set of checkbox options allows the user to select multiple items, each checkbox is managed +separately and you must register a click listener for each one.</p> + +<h2 id="HandlingEvents">Responding to Click Events</h2> + +<p>When the user selects a checkbox, the {@link android.widget.CheckBox} object receives an +on-click event.</p> + +<p>To define the click event handler for a checkbox, add the <code><a +href="/reference/android/R.attr.html#onClick">android:onClick</a></code> attribute to the +<code><CheckBox></code> element in your XML +layout. The value for this attribute must be the name of the method you want to call in response +to a click event. The {@link android.app.Activity} hosting the layout must then implement the +corresponding method.</p> + +<p>For example, here are a couple {@link android.widget.CheckBox} objects in a list:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:orientation="vertical" + android:layout_width="fill_parent" + android:layout_height="fill_parent"> + <CheckBox android:id="@+id/checkbox_meat" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/meat" + android:onClick="onCheckboxClicked"/> + <CheckBox android:id="@+id/checkbox_cheese" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/cheese" + android:onClick="onCheckboxClicked"/> +</LinearLayout> +</pre> + +<p>Within the {@link android.app.Activity} that hosts this layout, the following method handles the +click event for both checkboxes:</p> + +<pre> +public void onCheckboxClicked(View view) { + // Is the view now checked? + boolean checked = (CheckBox) view).isChecked(); + + // Check which checkbox was clicked + switch(view.getId()) { + case R.id.checkbox_meat: + if (checked) + // Put some meat on the sandwich + else + // Remove the meat + break; + case R.id.checkbox_cheese: + if (checked) + // Cheese me + else + // I'm lactose intolerant + break; + // TODO: Veggie sandwich + } +} +</pre> + +<p>The method you declare in the {@link android.R.attr#onClick android:onClick} attribute +must have a signature exactly as shown above. Specifically, the method must:</p> +<ul> + <li>Be public</li> + <li>Return void</li> + <li>Define a {@link android.view.View} as its only parameter (this will be the {@link +android.view.View} that was clicked)</li> +</ul> + +<p class="note"><strong>Tip:</strong> If you need to change the radio button state +yourself (such as when loading a saved {@link android.preference.CheckBoxPreference}), +use the {@link android.widget.CompoundButton#setChecked(boolean)} or {@link +android.widget.CompoundButton#toggle()} method.</p>
\ No newline at end of file diff --git a/docs/html/guide/topics/ui/controls/pickers.jd b/docs/html/guide/topics/ui/controls/pickers.jd new file mode 100644 index 0000000..cf90f1d --- /dev/null +++ b/docs/html/guide/topics/ui/controls/pickers.jd @@ -0,0 +1,259 @@ +page.title= Pickers +parent.title=Form Controls +parent.link=controls-form.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> +<ol> + <li><a href="#TimePicker">Creating a Time Picker</a> + <ol> + <li><a href="#TimePickerFragment">Extending DialogFragment for a time picker</a></li> + <li><a href="#ShowingTheTimePicker">Showing the time picker</a></li> + </ol> + </li> + <li><a href="#DatePicker">Creating a Date Picker</a> + <ol> + <li><a href="#DatePickerFragment">Extending DialogFragment for a date picker</a></li> + <li><a href="#ShowingTheDatePicker">Showing the date picker</a></li> + </ol> + </li> +</ol> + <h2>Key classes</h2> + <ol> + <li>{@link android.app.DatePickerDialog}</li> + <li>{@link android.app.TimePickerDialog}</li> + <li>{@link android.support.v4.app.DialogFragment}</li> + </ol> + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}guide/components/fragments.html">Fragments</a></li> + </ol> +</div> +</div> + +<p>Android provides controls for the user to pick a time or pick a date as ready-to-use dialogs. +Each picker provides controls for selecting each part of the time (hour, minute, AM/PM) or date +(month, day, year). Using these pickers helps ensure that your users can pick a time or date that +is valid, formatted correctly, and adjusted to the user's locale.</p> + +<img src="{@docRoot}images/ui/pickers.png" alt="" /> + +<p>We recommend that you use {@link android.support.v4.app.DialogFragment} to host each time or date +picker. The {@link android.support.v4.app.DialogFragment} manages the dialog lifecycle for you and +allows you to display the pickers in different layout configurations, +such as in a basic dialog on handsets or as an embedded part of the layout on large screens.</p> + +<p>Although {@link android.app.DialogFragment} was first added to the platform in Android 3.0 (API +level 11), if your app supports versions of Android older than 3.0—even as low as Android +1.6—you can use the {@link android.support.v4.app.DialogFragment} class that's available in +the <a href="{@docRoot}tools/extras/support-library.html">support library</a> for backward +compatibility.</p> + +<p class="note"><strong>Note:</strong> The code samples below show how to create dialogs for a time +picker and date picker using the <a href="{@docRoot}tools/extras/support-library.html">support +library</a> APIs for {@link android.support.v4.app.DialogFragment}. If your app's <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> is 11 or +higher, you can instead use the platform version of {@link android.app.DialogFragment}.</p> + + + +<h2 id="TimePicker">Creating a Time Picker</h2> + +<p>To display a {@link android.app.TimePickerDialog} using {@link +android.support.v4.app.DialogFragment}, you need to define a fragment class that extends {@link +android.support.v4.app.DialogFragment} and return a {@link android.app.TimePickerDialog} from the +fragment's {@link android.support.v4.app.DialogFragment#onCreateDialog onCreateDialog()} method.</p> + +<p class="note"><strong>Note:</strong> If your app supports versions of Android older than 3.0, +be sure you've set up your Android project with the support library as described in <a +href="{@docRoot}tools/extras/support-library.html#SettingUp">Setting Up a Project to Use a +Library</a>.</p> + +<h3 id="TimePickerFragment">Extending DialogFragment for a time picker</h3> + +<p>To define a {@link +android.support.v4.app.DialogFragment} for a {@link android.app.TimePickerDialog}, you +must:</p> +<ul> + <li>Define the {@link android.support.v4.app.DialogFragment#onCreateDialog onCreateDialog()} +method to return an instance of {@link android.app.TimePickerDialog}</li> + <li>Implement the +{@link android.app.TimePickerDialog.OnTimeSetListener} interface to receive a callback when the user +sets the time.</li> +</ul> + +<p>Here's an example:</p> + +<pre> +public static class TimePickerFragment extends DialogFragment + implements TimePickerDialog.OnTimeSetListener { + + @Override + public Dialog onCreateDialog(Bundle savedInstanceState) { + // Use the current time as the default values for the picker + final Calendar c = Calendar.getInstance(); + int hour = c.get(Calendar.HOUR_OF_DAY); + int minute = c.get(Calendar.MINUTE); + + // Create a new instance of TimePickerDialog and return it + return new TimePickerDialog(getActivity(), this, hour, minute, + DateFormat.is24HourFormat(getActivity())); + } + + public void onTimeSet(TimePicker view, int hourOfDay, int minute) { + // Do something with the time chosen by the user + } +} +</pre> + +<p>See the {@link android.app.TimePickerDialog} class for information about the constructor +arguments.</p> + +<p>Now all you need is an event that adds an instance of this fragment to your activity.</p> + + +<h3 id="ShowingTheTimePicker">Showing the time picker</h3> + +<p>Once you've defined a {@link android.support.v4.app.DialogFragment} like the one shown above, +you can display the time picker by creating an instance of the {@link +android.support.v4.app.DialogFragment} and calling {@link +android.support.v4.app.DialogFragment#show show()}.</p> + +<p>For example, here's a button that, when clicked, calls a method to show the dialog:</p> + +<pre> +<Button + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/pick_time" + android:onClick="showTimePickerDialog" /> +</pre> + +<p>When the user clicks this button, the system calls the following method:</p> + +<pre> +public void showTimePickerDialog(View v) { + DialogFragment newFragment = new TimePickerFragment(); + newFragment.show(getSupportFragmentManager(), "timePicker"); +} +</pre> + +<p>This method calls {@link +android.support.v4.app.DialogFragment#show show()} on a new instance of the {@link +android.support.v4.app.DialogFragment} defined above. The {@link +android.support.v4.app.DialogFragment#show show()} method requires an instance of {@link +android.support.v4.app.FragmentManager} and a unique tag name for the fragment.</p> + +<p class="caution"><strong>Caution:</strong> If your app supports versions of Android lower than +3.0, be sure that you call {@link +android.support.v4.app.FragmentActivity#getSupportFragmentManager()} to acquire an instance of +{@link android.support.v4.app.FragmentManager}. Also make sure that your activity that displays the +time picker extends {@link android.support.v4.app.FragmentActivity} instead of the standard {@link +android.app.Activity} class.</p> + + + + + + + + + +<h2 id="DatePicker">Creating a Date Picker</h2> + +<p>Creating a {@link android.app.DatePickerDialog} is just like creating a {@link +android.app.TimePickerDialog}. The only difference is the dialog you create for the fragment.</p> + +<p>To display a {@link android.app.DatePickerDialog} using {@link +android.support.v4.app.DialogFragment}, you need to define a fragment class that extends {@link +android.support.v4.app.DialogFragment} and return a {@link android.app.DatePickerDialog} from the +fragment's {@link android.support.v4.app.DialogFragment#onCreateDialog onCreateDialog()} method.</p> + +<p class="note"><strong>Note:</strong> If your app supports versions of Android older than 3.0, +be sure you've set up your Android project with the support library as described in <a +href="{@docRoot}tools/extras/support-library.html#SettingUp">Setting Up a Project to Use a +Library</a>.</p> + +<h3 id="DatePickerFragment">Extending DialogFragment for a date picker</h3> + +<p>To define a {@link +android.support.v4.app.DialogFragment} for a {@link android.app.DatePickerDialog}, you +must:</p> +<ul> + <li>Define the {@link android.support.v4.app.DialogFragment#onCreateDialog onCreateDialog()} +method to return an instance of {@link android.app.DatePickerDialog}</li> + <li>Implement the +{@link android.app.DatePickerDialog.OnDateSetListener} interface to receive a callback when the user +sets the date.</li> +</ul> + +<p>Here's an example:</p> + +<pre> +public static class DatePickerFragment extends DialogFragment + implements DatePickerDialog.OnDateSetListener { + + @Override + public Dialog onCreateDialog(Bundle savedInstanceState) { + // Use the current date as the default date in the picker + final Calendar c = Calendar.getInstance(); + int year = c.get(Calendar.YEAR); + int month = c.get(Calendar.MONTH); + int day = c.get(Calendar.DAY_OF_MONTH); + + // Create a new instance of DatePickerDialog and return it + return new DatePickerDialog(getActivity(), this, year, month, day); + } + + public void onDateSet(DatePicker view, int year, int month, int day) { + // Do something with the date chosen by the user + } +} +</pre> + +<p>See the {@link android.app.DatePickerDialog} class for information about the constructor +arguments.</p> + +<p>Now all you need is an event that adds an instance of this fragment to your activity.</p> + + +<h3 id="ShowingTheDatePicker">Showing the date picker</h3> + +<p>Once you've defined a {@link android.support.v4.app.DialogFragment} like the one shown above, +you can display the date picker by creating an instance of the {@link +android.support.v4.app.DialogFragment} and calling {@link +android.support.v4.app.DialogFragment#show show()}.</p> + +<p>For example, here's a button that, when clicked, calls a method to show the dialog:</p> + +<pre> +<Button + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/pick_date" + android:onClick="showDatePickerDialog" /> +</pre> + +<p>When the user clicks this button, the system calls the following method:</p> + +<pre> +public void showDatePickerDialog(View v) { + DialogFragment newFragment = new DatePickerFragment(); + newFragment.show(getSupportFragmentManager(), "datePicker"); +} +</pre> + +<p>This method calls {@link +android.support.v4.app.DialogFragment#show show()} on a new instance of the {@link +android.support.v4.app.DialogFragment} defined above. The {@link +android.support.v4.app.DialogFragment#show show()} method requires an instance of {@link +android.support.v4.app.FragmentManager} and a unique tag name for the fragment.</p> + +<p class="caution"><strong>Caution:</strong> If your app supports versions of Android lower than +3.0, be sure that you call {@link +android.support.v4.app.FragmentActivity#getSupportFragmentManager()} to acquire an instance of +{@link android.support.v4.app.FragmentManager}. Also make sure that your activity that displays the +time picker extends {@link android.support.v4.app.FragmentActivity} instead of the standard {@link +android.app.Activity} class.</p> diff --git a/docs/html/guide/topics/ui/controls/radiobutton.jd b/docs/html/guide/topics/ui/controls/radiobutton.jd new file mode 100644 index 0000000..f6f6d49 --- /dev/null +++ b/docs/html/guide/topics/ui/controls/radiobutton.jd @@ -0,0 +1,103 @@ +page.title=Radio Buttons +parent.title=Input Controls +parent.link=../controls.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> +<ol> + <li><a href="#HandlingEvents">Responding to Click Events</a></li> +</ol> + +<h2>Key classes</h2> +<ol> + <li>{@link android.widget.RadioButton}</li> + <li>{@link android.widget.RadioGroup}</li> +</ol> +</div> +</div> + +<p>Radio buttons allow the user to select one option from a set. You should use radio buttons for +optional sets that are mutually exclusive if you think that the user needs to see all available +options side-by-side. If it's not necessary to show all options side-by-side, use a <a +href="{@docRoot}guide/topics/ui/controls/spinner.html">spinner</a> instead.</p> + +<img src="{@docRoot}images/ui/radiobuttons.png" alt="" /> + +<p>To create each radio button option, create a {@link android.widget.RadioButton} in your layout. +However, because radio buttons are mutually exclusive, you must group them together inside a +{@link android.widget.RadioGroup}. By grouping them together, the system ensures that only one +radio button can be selected at a time.</p> + +<h2 id="HandlingEvents">Responding to Click Events</h2> + +<p>When the user selects one of the radio buttons, the corresponding {@link +android.widget.RadioButton} object receives an on-click event.</p> + +<p>To define the click event handler for a button, add the <code><a +href="/reference/android/R.attr.html#onClick">android:onClick</a></code> attribute to the +<code><RadioButton></code> element in your XML +layout. The value for this attribute must be the name of the method you want to call in response +to a click event. The {@link android.app.Activity} hosting the layout must then implement the +corresponding method.</p> + +<p>For example, here are a couple {@link android.widget.RadioButton} objects:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<RadioGroup xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:orientation="vertical"> + <RadioButton android:id="@+id/radio_pirates" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/pirates" + android:onClick="onRadioButtonClicked"/> + <RadioButton android:id="@+id/radio_ninjas" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/ninjas" + android:onClick="onRadioButtonClicked"/> +</RadioGroup> +</pre> + +<p class="note"><strong>Note:</strong> The {@link android.widget.RadioGroup} is a subclass of +{@link android.widget.LinearLayout} that has a vertical orientation by default.</p> + +<p>Within the {@link android.app.Activity} that hosts this layout, the following method handles the +click event for both radio buttons:</p> + +<pre> +public void onRadioButtonClicked(View view) { + // Is the button now checked? + boolean checked = (RadioButton) view).isChecked(); + + // Check which radio button was clicked + switch(view.getId()) { + case R.id.radio_pirates: + if (checked) + // Pirates are the best + break; + case R.id.radio_ninjas: + if (checked) + // Ninjas rule + break; + } +} +</pre> + +<p>The method you declare in the {@link android.R.attr#onClick android:onClick} attribute +must have a signature exactly as shown above. Specifically, the method must:</p> +<ul> + <li>Be public</li> + <li>Return void</li> + <li>Define a {@link android.view.View} as its only parameter (this will be the {@link +android.view.View} that was clicked)</li> +</ul> + +<p class="note"><strong>Tip:</strong> If you need to change the radio button state +yourself (such as when loading a saved {@link android.preference.CheckBoxPreference}), +use the {@link android.widget.CompoundButton#setChecked(boolean)} or {@link +android.widget.CompoundButton#toggle()} method.</p> diff --git a/docs/html/guide/topics/ui/controls/spinner.jd b/docs/html/guide/topics/ui/controls/spinner.jd new file mode 100644 index 0000000..deba3e6 --- /dev/null +++ b/docs/html/guide/topics/ui/controls/spinner.jd @@ -0,0 +1,147 @@ +page.title= Spinners +parent.title=Input Controls +parent.link=../controls.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>In this document</h2> +<ol> + <li><a href="#Populate">Populate the Spinner with User Choices</a></li> + <li><a href="#SelectListener">Responding to User Selections</a></li> +</ol> +<h2>Key classes</h2> +<ol> + <li>{@link android.widget.Spinner}</li> + <li>{@link android.widget.SpinnerAdapter}</li> + <li>{@link android.widget.AdapterView.OnItemSelectedListener}</li> +</ol> + +</div> +</div> + +<p>Spinners provide a quick way to select one value from a set. In the default state, a spinner +shows its currently selected value. Touching the spinner displays a dropdown menu with all other +available values, from which the user can select a new one.</p> + +<img src="{@docRoot}images/ui/spinner.png" alt="" /> + +<p>You can add a spinner to your layout with the {@link android.widget.Spinner} object. You +should usually do so in your XML layout with a {@code <Spinner>} element. For example:</p> + +<pre> +<Spinner + android:id="@+id/planets_spinner" + android:layout_width="fill_parent" + android:layout_height="wrap_content" /> +</pre> + +<p>To populate the spinner with a list of choices, you then need to specify a {@link +android.widget.SpinnerAdapter} in your {@link android.app.Activity} or {@link android.app.Fragment} +source code.</p> + +<h2 id="Populate">Populate the Spinner with User Choices</h2> + +<p>The choices you provide for the spinner can come from any source, but must be provided through +an {@link android.widget.SpinnerAdapter}, such as an {@link android.widget.ArrayAdapter} if the +choices are available in an array or a {@link android.widget.CursorAdapter} if the choices are +available from a database query.</p> + +<p>For instance, if the available choices for your spinner are pre-determined, you can provide +them with a string array defined in a <a +href="{@docRoot}guide/topics/resources/string-resource.html">string +resource file</a>:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <string-array name="planets_array"> + <item>Mercury</item> + <item>Venus</item> + <item>Earth</item> + <item>Mars</item> + <item>Jupiter</item> + <item>Saturn</item> + <item>Uranus</item> + <item>Neptune</item> + </string-array> +</resources> +</pre> + + <p>With an array such as this one, you can use the following code in your {@link +android.app.Activity} or {@link android.app.Fragment} to supply the spinner with the array using +an instance of {@link android.widget.ArrayAdapter}: + +<pre> +Spinner spinner = (Spinner) findViewById(R.id.spinner); +// Create an ArrayAdapter using the string array and a default spinner layout +ArrayAdapter<CharSequence> adapter = ArrayAdapter.createFromResource(this, + R.array.planets_array, android.R.layout.simple_spinner_item); +// Specify the layout to use when the list of choices appears +adapter.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item); +// Apply the adapter to the spinner +spinner.setAdapter(adapter); +</pre> + +<p>The {@link +android.widget.ArrayAdapter#createFromResource(Context,int,int) createFromResource()} method allows +you to create an {@link android.widget.ArrayAdapter} from the string array. The third argument for +this method is a layout resource that defines how the selected choice appears in the +spinner control. The {@link android.R.layout#simple_spinner_item} layout is provided by the +platform and is the default layout you should use unless you'd like to define your own layout +for the spinner's appearance.</p> + +<p>You should then call {@link android.widget.ArrayAdapter#setDropDownViewResource(int)} to specify +the layout the adapter should use to display the list of spinner choices ({@link +android.R.layout#simple_spinner_dropdown_item} is another standard layout defined by the +platform).</p> + +<p>Call {@link android.widget.AdapterView#setAdapter setAdapter()} to apply the adapter to your +{@link android.widget.Spinner}.</p> + + +<h2 id="SelectListener">Responding to User Selections</h2> + +<p>When the user selects an item from the drop-down, the {@link android.widget.Spinner} object +receives an on-item-selected event.</p> + +<p>To define the selection event handler for a spinner, implement the {@link +android.widget.AdapterView.OnItemSelectedListener} interface and the corresponding {@link +android.widget.AdapterView.OnItemSelectedListener#onItemSelected onItemSelected()} callback method. +For example, here's an implementation of the interface in an {@link android.app.Activity}:</p> + +<pre> +public class SpinnerActivity extends Activity implements OnItemSelectedListener { + ... + + public void onItemSelected(AdapterView<?> parent, View view, + int pos, long id) { + // An item was selected. You can retrieve the selected item using + // parent.getItemAtPosition(pos) + } + + public void onNothingSelected(AdapterView<?> parent) { + // Another interface callback + } +} +</pre> + +<p>The {@link android.widget.AdapterView.OnItemSelectedListener} requires the {@link +android.widget.AdapterView.OnItemSelectedListener#onItemSelected(AdapterView,View,int,long) +onItemSelected()} and {@link +android.widget.AdapterView.OnItemSelectedListener#onNothingSelected(AdapterView) +onNothingSelected()} callback methods.</p> + +<p>Then you need to specify the interface implementation by calling {@link +android.widget.AdapterView#setOnItemSelectedListener setOnItemSelectedListener()}:</p> + +<pre> +Spinner spinner = (Spinner) findViewById(R.id.spinner); +spinner.setOnItemSelectedListener(this); +</pre> + +<p>If you implement the {@link +android.widget.AdapterView.OnItemSelectedListener} interface with your {@link +android.app.Activity} or {@link android.app.Fragment} (such as in the example above), you can pass +<code>this</code> as the interface instance.</p>
\ No newline at end of file diff --git a/docs/html/guide/topics/ui/controls/text.jd b/docs/html/guide/topics/ui/controls/text.jd new file mode 100644 index 0000000..2d9d215 --- /dev/null +++ b/docs/html/guide/topics/ui/controls/text.jd @@ -0,0 +1,306 @@ +page.title=Text Fields +parent.title=Input Controls +parent.link=../controls.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>In this document</h2> +<ol> + <li><a href="#Keyboard">Specifying the Keyboard Type</a> + <ol> + <li><a href="#Behaviors">Controlling other behaviors</a></li> + </ol> + </li> + <li><a href="#Actions">Specifying Keyboard Actions</a> + <ol> + <li><a href="#ActionEvent">Responding to action button events</a></li> + <li><a href="#ActionLabel">Setting a custom action button label</a></li> + </ol> + </li> + <li><a href="#Flags">Adding Other Keyboard Flags</a></li> + <li><a href="#AutoComplete">Providing Auto-complete Suggestions</a></li> +</ol> +<h2>Key classes</h2> +<ol> + <li>{@link android.widget.EditText}</li> + <li>{@link android.widget.AutoCompleteTextView}</li> +</ol> + +</div> +</div> + +<p>A text field allows the user to type text into your app. It can be either single line or +multi-line. Touching a text field places the cursor and automatically displays the keyboard. In +addition to typing, text fields allow for a variety of other activities, such as text selection +(cut, copy, paste) and data look-up via auto-completion.</p> + +<p>You can add a text field to you layout with the {@link android.widget.EditText} object. You +should usually do so in your XML layout with a {@code <EditText>} element.</p> + +<img src="{@docRoot}images/ui/edittext-noextract.png" alt="" /> + + + +<h2 id="Keyboard">Specifying the Keyboard Type</h2> + +<div class="figure" style="width:300px;margin-top:0"> +<img src="{@docRoot}images/ui/edittext-text.png" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> The default {@code text} input type.</p> +</div> + +<div class="figure" style="width:300px"> +<img src="{@docRoot}images/ui/edittext-email.png" alt="" /> +<p class="img-caption"><strong>Figure 2.</strong> The {@code textEmailAddress} input type.</p> +</div> + +<div class="figure" style="width:300px"> +<img src="{@docRoot}images/ui/edittext-phone.png" alt="" /> +<p class="img-caption"><strong>Figure 3.</strong> The {@code phone} input type.</p> +</div> + +<p>Text fields can have different input types, such as number, date, password, or email address. The +type determines what kind of characters are allowed inside the field, and may prompt the virtual +keyboard to optimize its layout for frequently used characters.</p> + +<p>You can specify the type of keyboard you want for your {@link android.widget.EditText} object +with the <a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code +android:inputType}</a> attribute. For example, if you want the user to input an email address, you +should use the {@code textEmailAddress} input type:</p> + +<pre> +<EditText + android:id="@+id/email_address" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:hint="@string/email_hint" + android:inputType="textEmailAddress" /> +</pre> + + +<p>There are several different input types available for different situations. You can find +them all listed with the documentation for <a +href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code +android:inputType}</a>.</p> + +<p class="note"><strong>Tip:</strong> To allow users to input long strings of text with line +breaks, use the {@code "textMultiLine"} input type. By default, an {@link android.widget.EditText} +object is restricted to one line of text and scrolls horizontally when the text exceeds the +available width.</p> + + +<h3 id="Behaviors">Controlling other behaviors</h3> + +<p>The <a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code +android:inputType}</a> also allows you to specify certain keyboard behaviors, such as whether to +capitalize all new words or use features like auto-complete and spelling suggestions.</p> + +<p>The <a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code +android:inputType}</a> attribute allows bitwise combinations so you can specify both a keyboard +layout and one or more behaviors at once. For example, here's how you can collect a postal +address, capitalize each word, and disable text suggestions:</p> + +<pre> +<EditText + android:id="@+id/postal_address" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:hint="@string/postal_address_hint" + android:inputType="textPostalAddress| + textCapWords| + textNoSuggestions" /> +</pre> + +<p>All behaviors are also listed with the <a +href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code +android:inputType}</a> documentation.</p> + + +<h2 id="Actions">Specifying Keyboard Actions</h2> + +<div class="figure" style="width:300px"> +<img src="{@docRoot}images/ui/edittext-actionsend.png" alt="" /> +<p class="img-caption"><strong>Figure 4.</strong> If you declare {@code +android:imeOptions="actionSend"}, the keyboard includes the Send action.</p> +</div> + +<p>In addition to changing the keyboard's input type, Android allows you to specify an action to be +made when users have completed their input. The action specifies the button that appears in place of +the carriage return key and the action to be made, such as "Search" or "Send."</p> + +<p>You can specify the action by setting the <a +href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeOptions">{@code +android:imeOptions}</a> attribute. For example, here's how you can specify the Send action:</p> + +<pre> +<EditText + android:id="@+id/search" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:hint="@string/search_hint" + android:inputType="text" + android:imeOptions="actionSend" /> +</pre> + +<p>If you do not explicitly specify an input action then the system attempts to determine if there +are any subsequent <a +href="{@docRoot}reference/android/view/View.html#attr_android:focusable">{@code +android:focusable}</a> fields. If any focusable fields are found following this one, the system +applies the (@code actionNext} action to the current {@link android.widget.EditText} so the user can +select Next to move to the next field. If there's no subsequent focusable field, the system applies +the {@code "actionDone"} action. You can override this by setting the <a +href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeOptions">{@code +android:imeOptions}</a> attribute to any other value such as {@code "actionSend"} or {@code +"actionSearch"} or suppress the default behavior by using the {@code "actionNone"} action.</p> + + +<h3 id="ActionEvent">Responding to action button events</h3> + +<p>If you have specified a keyboard action for the input method using <a +href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeOptions">{@code +android:imeOptions}</a> attribute (such as {@code "actionSend"}), you can listen for the specific +action event using an {@link android.widget.TextView.OnEditorActionListener}. The {@link +android.widget.TextView.OnEditorActionListener} interface provides a callback method called {@link +android.widget.TextView.OnEditorActionListener#onEditorAction onEditorAction()} that indicates the +action type invoked with an action ID such as {@link +android.view.inputmethod.EditorInfo#IME_ACTION_SEND} or {@link +android.view.inputmethod.EditorInfo#IME_ACTION_SEARCH}.</p> + +<p>For example, here's how you can listen for when the user clicks the Send button on the +keyboard:</p> + +<pre> +EditText editText = (EditText) findViewById(R.id.search); +editText.setOnEditorActionListener(new OnEditorActionListener() { + @Override + public boolean onEditorAction(TextView v, int actionId, KeyEvent event) { + boolean handled = false; + if (actionId == EditorInfo.IME_ACTION_SEND) { + // Send the user message + handled = true; + } + return handled; + } +}); +</pre> + + +<h3 id="ActionLabel">Setting a custom action button label</h3> + +<p>If the keyboard is too large to reasonably share space with the underlying application (such as +when a handset device is in landscape orientation) then fullscreen ("extract mode") is triggered. In +this mode, a labeled action button is displayed next to the input. You can customize the text of +this button by setting the <a +href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeActionLabel">{@code +android:imeActionLabel}</a> attribute:</p> + +<pre> +<EditText + android:id="@+id/launch_codes" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:hint="@string/enter_launch_codes" + android:inputType="number" + android:imeActionLabel="@string/launch" /> +</pre> + +<img src="{@docRoot}images/ui/edittext-actionlabel.png" alt="" /> +<p class="img-caption"><strong>Figure 5.</strong> A custom action label with <a +href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeActionLabel">{@code +android:imeActionLabel}</a>.</p> + + + +<h2 id="Flags">Adding Other Keyboard Flags</h2> + +<p>In addition to the actions you can specify with the <a +href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeOptions">{@code +android:imeOptions}</a> attribute, you can add additional flags to specify other keyboard +behaviors. All available flags are listed along with the actions in the <a +href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeOptions">{@code +android:imeOptions}</a> documentation.</p> + +<p>For example, figure 5 shows how the system enables a fullscreen text field when a handset device +is in landscape orientation (or the screen space is otherwise constrained for space). You can +disable the fullscreen input mode with {@code flagNoExtractUi} in the <a +href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeOptions">{@code +android:imeOptions}</a> attribute, as shown in figure 6.</p> + +<img src="{@docRoot}images/ui/edittext-noextract.png" alt="" /> +<p class="img-caption"><strong>Figure 6.</strong> The fullscreen text field ("extract mode") is +disabled with {@code android:imeOptions="flagNoExtractUi"}.</p> + + + + +<h2 id="AutoComplete">Providing Auto-complete Suggestions</h2> + +<p>If you want to provide suggestions to users as they type, you can use a subclass of {@link +android.widget.EditText} called {@link android.widget.AutoCompleteTextView}. To implement +auto-complete, you must specify an (@link android.widget.Adapter) that provides the text +suggestions. There are several kinds of adapters available, depending on where the data is coming +from, such as from a database or an array.</p> + +<img src="{@docRoot}images/ui/edittext-autocomplete.png" alt="" /> +<p class="img-caption"><strong>Figure 7.</strong> Example of {@link +android.widget.AutoCompleteTextView} with text suggestions.</p> + +<p>The following procedure describes how to set up an {@link android.widget.AutoCompleteTextView} +that provides suggestions from an array, using {@link android.widget.ArrayAdapter}: + +<ol> + <li>Add the {@link android.widget.AutoCompleteTextView} to your layout. Here's a +layout with only the text field: +<pre> +<?xml version="1.0" encoding="utf-8"?> +<AutoCompleteTextView xmlns:android="http://schemas.android.com/apk/res/android" + android:id="@+id/autocomplete_country" + android:layout_width="fill_parent" + android:layout_height="wrap_content" /> +</pre> +</li> + +<li>Define the array that contains all text suggestions. For example, here's an array of country +names that's defined in an XML resource file ({@code res/values/strings.xml}): +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <string-array name="countries_array"> + <item>Afghanistan</item> + <item>Albania</item> + <item>Algeria</item> + <item>American Samoa</item> + <item>Andorra</item> + <item>Angola</item> + <item>Anguilla</item> + <item>Antarctica</item> + ... + </string-array> +</resources> +</pre> +</li> + +<li>In your {@link android.app.Activity} or {@link android.app.Fragment}, use the following +code to specify the adapter that supplies the suggestions: +<pre> +// Get a reference to the AutoCompleteTextView in the layout +AutoCompleteTextView textView = (AutoCompleteTextView) findViewById(R.id.autocomplete_country); +// Get the string array +String[] countries = getResources().getStringArray(R.array.countries_array); +// Create the adapter and set it to the AutoCompleteTextView +ArrayAdapter<String> adapter = + new ArrayAdapter<String>(this, android.R.layout.simple_list_item_1, countries); +textView.setAdapter(adapter); +</pre> + +<p>Here, a new {@link +android.widget.ArrayAdapter} is initialized to bind each item in the <code>COUNTRIES</code> +string array to a {@link android.widget.TextView} that exists in the {@code simple_list_item_1} +layout (this is a layout provided by Android that provides a standard appearance for text in a +list).</p> +<p>Then assign the adapter to the {@link android.widget.AutoCompleteTextView} by +calling {@link android.widget.AutoCompleteTextView#setAdapter setAdapter()}.</p> +</li> +</ol> + diff --git a/docs/html/guide/topics/ui/controls/togglebutton.jd b/docs/html/guide/topics/ui/controls/togglebutton.jd new file mode 100644 index 0000000..dd7634b --- /dev/null +++ b/docs/html/guide/topics/ui/controls/togglebutton.jd @@ -0,0 +1,124 @@ +page.title=Toggle Buttons +parent.title=Input Controls +parent.link=../controls.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> +<ol> + <li><a href="#HandlingEvents">Responding to Click Events</a> + <ol> + <li><a href="#ClickListener">Using an OnCheckedChangeListener</a></li> + </ol> + </li> +</ol> + <h2>Key classes</h2> + <ol> + <li>{@link android.widget.ToggleButton}</li> + <li>{@link android.widget.Switch}</li> + </ol> +</div> +</div> + +<p>A toggle button allows the user to change a setting between two states.</p> + +<p>You can add a basic toggle button to your layout with the {@link android.widget.ToggleButton} +object. Android 4.0 (API level 14) introduces another kind of toggle button called a switch that +provides a slider control, which you can add with a {@link android.widget.Switch} object.</p> + +<div style="float:left;width:200px"> +<img src="{@docRoot}images/ui/togglebutton.png" alt="" /> +<p class="img-caption"><em>Toggle buttons</em></p> +</div> + +<div style="float:left;width:200px;margin-top:24px"> +<img src="{@docRoot}images/ui/switch.png" alt="" /> +<p class="img-caption"><em>Switches (in Android 4.0+)</em></p> +</div> + +<p style="clear:left">The {@link android.widget.ToggleButton} and {@link android.widget.Switch} +controls are subclasses of {@link android.widget.CompoundButton} and function in the same manner, so +you can implement their behavior the same way.</p> + +<h2 id="HandlingEvents">Responding to Click Events</h2> + +<p>When the user selects a {@link android.widget.ToggleButton} and {@link android.widget.Switch}, +the object receives an on-click event.</p> + +<p>To define the click event handler, add the <code><a +href="/reference/android/R.attr.html#onClick">android:onClick</a></code> attribute to the +<code><ToggleButton></code> or <code><Switch></code> element in your XML +layout. The value for this attribute must be the name of the method you want to call in response +to a click event. The {@link android.app.Activity} hosting the layout must then implement the +corresponding method.</p> + +<p>For example, here's a {@link android.widget.ToggleButton} with the <code><a +href="/reference/android/R.attr.html#onClick">android:onClick</a></code> attribute:</p> + +<pre> +<ToggleButton + android:id="@+id/togglebutton" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:textOn="Vibrate on" + android:textOff="Vibrate off" + android:onClick="onToggleClicked"/> +</pre> + +<p>Within the {@link android.app.Activity} that hosts this layout, the following method handles the +click event:</p> + +<pre> +public void onToggleClicked(View view) { + // Is the toggle on? + boolean on = ((ToggleButton) view).isChecked(); + + if (on) { + // Enable vibrate + } else { + // Disable vibrate + } +} +</pre> + +<p>The method you declare in the {@link android.R.attr#onClick android:onClick} attribute +must have a signature exactly as shown above. Specifically, the method must:</p> +<ul> + <li>Be public</li> + <li>Return void</li> + <li>Define a {@link android.view.View} as its only parameter (this will be the {@link +android.view.View} that was clicked)</li> +</ul> + +<p class="note"><strong>Tip:</strong> If you need to change the state +yourself, +use the {@link android.widget.CompoundButton#setChecked(boolean)} or {@link +android.widget.CompoundButton#toggle()} method to change the state.</p> + + + +<h3 id="ClickListener">Using an OnCheckedChangeListener</h3> + +<p>You can also declare a click event handler pragmatically rather than in an XML layout. This +might be necessary if you instantiate the {@link android.widget.ToggleButton} or {@link +android.widget.Switch} at runtime or you need to +declare the click behavior in a {@link android.app.Fragment} subclass.</p> + +<p>To declare the event handler programmatically, create an {@link +android.widget.CompoundButton.OnCheckedChangeListener} object and assign it to the button by calling +{@link +android.widget.CompoundButton#setOnCheckedChangeListener}. For example:</p> + +<pre> +ToggleButton toggle = (ToggleButton) findViewById(R.id.togglebutton); +toggle.setOnCheckedChangeListener(new CompoundButton.OnCheckedChangeListener() { + public void onCheckedChanged(CompoundButton buttonView, boolean isChecked) { + if (isChecked) { + // The toggle is enabled + } else { + // The toggle is disabled + } + } +}); +</pre> diff --git a/docs/html/guide/topics/ui/declaring-layout.jd b/docs/html/guide/topics/ui/declaring-layout.jd index 8af4a1c..3c9faa8 100644 --- a/docs/html/guide/topics/ui/declaring-layout.jd +++ b/docs/html/guide/topics/ui/declaring-layout.jd @@ -1,4 +1,4 @@ -page.title=XML Layouts +page.title=Layouts parent.title=User Interface parent.link=index.html @jd:body @@ -6,18 +6,25 @@ parent.link=index.html <div id="qv-wrapper"> <div id="qv"> <h2>In this document</h2> - <ol> - <li><a href="#write">Write the XML</a></li> - <li><a href="#load">Load the XML Resource</a></li> - <li><a href="#attributes">Attributes</a> - <ol> - <li><a href="#id">ID</a></li> - <li><a href="#layout-params">Layout Parameters</a></li> - </ol> - </li> - <li><a href="#Position">Position</a></li> - <li><a href="#SizePaddingMargins">Size, Padding and Margins</a></li> - </ol> +<ol> + <li><a href="#write">Write the XML</a></li> + <li><a href="#load">Load the XML Resource</a></li> + <li><a href="#attributes">Attributes</a> + <ol> + <li><a href="#id">ID</a></li> + <li><a href="#layout-params">Layout Parameters</a></li> + </ol> + </li> + <li><a href="#Position">Layout Position</a></li> + <li><a href="#SizePaddingMargins">Size, Padding and Margins</a></li> + <li><a href="#CommonLayouts">Common Layouts</a></li> + <li><a href="#AdapterViews">Building Layouts with an Adapter</a> + <ol> + <li><a href="#FillingTheLayout">Filling an adapter view with data</a></li> + <li><a href="#HandlingUserSelections">Handling click events</a></li> + </ol> + </li> +</ol> <h2>Key classes</h2> <ol> @@ -43,15 +50,15 @@ application can create View and ViewGroup objects (and manipulate their properti <div class="sidebox-wrapper"> <div class="sidebox"> <ul> - <li>The <a href="{@docRoot}sdk/eclipse-adt.html">ADT + <li>The <a href="{@docRoot}tools/sdk/eclipse-adt.html">ADT Plugin for Eclipse</a> offers a layout preview of your XML — with the XML file opened, select the <strong>Layout</strong> tab.</li> <li>You should also try the - <a href="{@docRoot}guide/developing/debugging/debugging-ui.html#hierarchyViewer">Hierarchy Viewer</a> tool, + <a href="{@docRoot}tools/debugging/debugging-ui.html#hierarchyViewer">Hierarchy Viewer</a> tool, for debugging layouts — it reveals layout property values, draws wireframes with padding/margin indicators, and full rendered views while you debug on the emulator or device.</li> - <li>The <a href="{@docRoot}guide/developing/debugging/debugging-ui.html#layoutopt">layoutopt</a> tool lets + <li>The <a href="{@docRoot}tools/debugging/debugging-ui.html#layoutopt">layoutopt</a> tool lets you quickly analyze your layouts and hierarchies for inefficiencies or other problems.</li> </div> </div> @@ -125,7 +132,7 @@ public void onCreate(Bundle savedInstanceState) { <p>The <code>onCreate()</code> callback method in your Activity is called by the Android framework when your Activity is launched (see the discussion about lifecycles, in the -<a href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">Activities</a> +<a href="{@docRoot}guide/components/activities.html#Lifecycle">Activities</a> document).</p> @@ -300,5 +307,213 @@ Available Resources</a> document.</p> </p> + + + + +<style type="text/css"> +div.layout { + float:left; + width:200px; + margin:0 0 20px 20px; +} +div.layout.first { + margin-left:0; + clear:left; +} +</style> + + + + +<h2 id="CommonLayouts">Common Layouts</h2> + +<p>Each subclass of the {@link android.view.ViewGroup} class provides a unique way to display +the views you nest within it. Below are some of the more common layout types that are built +into the Android platform.</p> + +<p class="note"><strong>Note:</strong> Although you can nest one or more layouts within another +layout to acheive your UI design, you should strive to keep your layout hierarchy as shallow as +possible. Your layout draws faster if it has fewer nested layouts (a wide view hierarchy is +better than a deep view hierarchy).</p> + +<!-- +<h2 id="framelayout">FrameLayout</h2> +<p>{@link android.widget.FrameLayout FrameLayout} is the simplest type of layout +object. It's basically a blank space on your screen that you can +later fill with a single object — for example, a picture that you'll swap in and out. +All child elements of the FrameLayout are pinned to the top left corner of the screen; you cannot +specify a different location for a child view. Subsequent child views will simply be drawn over +previous ones, +partially or totally obscuring them (unless the newer object is transparent). +</p> +--> + + +<div class="layout first"> + <h4><a href="layout/linear.html">Linear Layout</a></h4> + <a href="layout/linear.html"><img src="{@docRoot}images/ui/linearlayout-small.png" alt="" /></a> + <p>A layout that organizes its children into a single horizontal or vertical row. It + creates a scrollbar if the length of the window exceeds the length of the screen.</p> +</div> + +<div class="layout"> + <h4><a href="layout/relative.html">Relative Layout</a></h4> + <a href="layout/relative.html"><img src="{@docRoot}images/ui/relativelayout-small.png" alt="" +/></a> + <p>Enables you to specify the location of child objects relative to each other (child A to +the left of child B) or to the parent (aligned to the top of the parent).</p> +</div> + +<!-- +<div class="layout"> + <h4><a href="layout/tabs.html">Tabs</a></h4> + <a href="layout/tabs.html"><img src="{@docRoot}images/ui/tabs-small.png" alt="" /></a> + <p>Provides a tab selection list that monitors clicks and enables the application to change +the screen whenever a tab is clicked.</p> +</div> + +<div class="layout first"> + <h4><a href="layout/grid.html">Table Layout</a></h4> + <a href="layout/table.html"><img src="{@docRoot}images/ui/gridlayout-small.png" alt="" /></a> + <p>A tabular layout with an arbitrary number of rows and columns, each cell holding the +widget of your choice. The rows resize to fit the largest column. The cell borders are not +visible.</p> +</div> +--> + +<div class="layout"> + <h4><a href="{@docRoot}guide/webapps/webview.html">Web View</a></h4> + <a href="{@docRoot}guide/webapps/webview.html"><img src="{@docRoot}images/ui/webview-small.png" +alt="" /></a> + <p>Displays web pages.</p> +</div> + + + + +<h2 id="AdapterViews" style="clear:left">Building Layouts with an Adapter</h2> + +<p>When the content for your layout is dynamic or not pre-determined, you can use a layout that +subclasses {@link android.widget.AdapterView} to populate the layout with views at runtime. A +subclass of the {@link android.widget.AdapterView} class uses an {@link android.widget.Adapter} to +bind data to its layout. The {@link android.widget.Adapter} behaves as a middle-man between the data +source and the {@link android.widget.AdapterView} layout—the {@link android.widget.Adapter} +retreives the data (from a source such as an array or a database query) and converts each entry +into a view that can be added into the {@link android.widget.AdapterView} layout.</p> + +<p>Common layouts backed by an adapter include:</p> + +<div class="layout first"> + <h4><a href="layout/listview.html">List View</a></h4> + <a href="layout/list.html"><img src="{@docRoot}images/ui/listview-small.png" alt="" /></a> + <p>Displays a scrolling single column list.</p> +</div> + +<div class="layout"> + <h4><a href="layout/gridview.html">Grid View</a></h4> + <a href="layout/grid.html"><img src="{@docRoot}images/ui/gridview-small.png" alt="" /></a> + <p>Displays a scrolling grid of columns and rows.</p> +</div> + + + +<h3 id="FillingTheLayout" style="clear:left">Filling an adapter view with data</h3> + +<p>You can populate an {@link android.widget.AdapterView} such as {@link android.widget.ListView} or +{@link android.widget.GridView} by binding the {@link android.widget.AdapterView} instance to an +{@link android.widget.Adapter}, which retrieves data from an external source and creates a {@link +android.view.View} that represents each data entry.</p> + +<p>Android provides several subclasses of {@link android.widget.Adapter} that are useful for +retrieving different kinds of data and building views for an {@link android.widget.AdapterView}. The +two most common adapters are:</p> + +<dl> + <dt>{@link android.widget.ArrayAdapter}</dt> + <dd>Use this adapter when your data source is an array. By default, {@link +android.widget.ArrayAdapter} creates a view for each array item by calling {@link +java.lang.Object#toString()} on each item and placing the contents in a {@link +android.widget.TextView}. + <p>For example, if you have an array of strings you want to display in a {@link +android.widget.ListView}, initialize a new {@link android.widget.ArrayAdapter} using a +constructor to specify the layout for each string and the string array:</p> +<pre> +ArrayAdapter adapter = new ArrayAdapter<String>(this, + android.R.layout.simple_list_item_1, myStringArray); +</pre> +<p>The arguments for this constructor are:</p> +<ul> + <li>Your app {@link android.content.Context}</li> + <li>The layout that contains a {@link android.widget.TextView} for each string in the array</li> + <li>The string array</li> +</ul> +<p>Then simply call +{@link android.widget.ListView#setAdapter setAdapter()} on your {@link android.widget.ListView}:</p> +<pre> +ListView listView = (ListView) findViewById(R.id.listview); +listView.setAdapter(adapter); +</pre> + + <p>To customize the appearance of each item you can override the {@link +java.lang.Object#toString()} method for the objects in your array. Or, to create a view for each +item that's something other than a {@link android.widget.TextView} (for example, if you want an +{@link android.widget.ImageView} for each array item), extend the {@link +android.widget.ArrayAdapter} class and override {@link android.widget.ArrayAdapter#getView +getView()} to return the type of view you want for each item.</p> + +</dd> + + <dt>{@link android.widget.SimpleCursorAdapter}</dt> + <dd>Use this adapter when your data comes from a {@link android.database.Cursor}. When +using {@link android.widget.SimpleCursorAdapter}, you must specify a layout to use for each +row in the {@link android.database.Cursor} and which columns in the {@link android.database.Cursor} +should be inserted into which views of the layout. For example, if you want to create a list of +people's names and phone numbers, you can perform a query that returns a {@link +android.database.Cursor} containing a row for each person and columns for the names and +numbers. You then create a string array specifying which columns from the {@link +android.database.Cursor} you want in the layout for each result and an integer array specifying the +corresponding views that each column should be placed:</p> +<pre> +String[] fromColumns = {ContactsContract.Data.DISPLAY_NAME, + ContactsContract.CommonDataKinds.Phone.NUMBER}; +int[] toViews = {R.id.display_name, R.id.phone_number}; +</pre> +<p>When you instantiate the {@link android.widget.SimpleCursorAdapter}, pass the layout to use for +each result, the {@link android.database.Cursor} containing the results, and these two arrays:</p> +<pre> +SimpleCursorAdapter adapter = new SimpleCursorAdapter(this, + R.layout.person_name_and_number, cursor, fromColumns, toViews, 0); +ListView listView = getListView(); +listView.setAdapter(adapter); +</pre> +<p>The {@link android.widget.SimpleCursorAdapter} then creates a view for each row in the +{@link android.database.Cursor} using the provided layout by inserting each {@code +fromColumns} item into the corresponding {@code toViews} view.</p>.</dd> +</dl> + + +<p>If, during the course of your application's life, you change the underlying data that is read by +your adapter, you should call {@link android.widget.ArrayAdapter#notifyDataSetChanged()}. This will +notify the attached view that the data has been changed and it should refresh itself.</p> + + + +<h3 id="HandlingUserSelections">Handling click events</h3> + +<p>You can respond to click events on each item in an {@link android.widget.AdapterView} by +implementing the {@link android.widget.AdapterView.OnItemClickListener} interface. For example:</p> + +<pre> +// Create a message handling object as an anonymous class. +private OnItemClickListener mMessageClickedHandler = new OnItemClickListener() { + public void onItemClick(AdapterView parent, View v, int position, long id) { + // Do something in response to the click + } +}; + +listView.setOnItemClickListener(mMessageClickedHandler); +</pre> + diff --git a/docs/html/guide/topics/ui/dialogs.jd b/docs/html/guide/topics/ui/dialogs.jd index 82cbfd1..9c28058 100644 --- a/docs/html/guide/topics/ui/dialogs.jd +++ b/docs/html/guide/topics/ui/dialogs.jd @@ -313,7 +313,7 @@ Activity, the selection is lost. <p class="note"><strong>Note:</strong> To save the selection when the user leaves or pauses the Activity, you must properly save and restore the setting throughout -the <a href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">activity lifecycle</a>. +the <a href="{@docRoot}guide/components/activities.html#Lifecycle">activity lifecycle</a>. To permanently save the selections, even when the Activity process is completely shutdown, you need to save the settings with one of the <a href="{@docRoot}guide/topics/data/data-storage.html">Data diff --git a/docs/html/guide/topics/ui/images/android_focused.png b/docs/html/guide/topics/ui/images/android_focused.png Binary files differnew file mode 100644 index 0000000..f84d0fe --- /dev/null +++ b/docs/html/guide/topics/ui/images/android_focused.png diff --git a/docs/html/guide/topics/ui/images/android_normal.png b/docs/html/guide/topics/ui/images/android_normal.png Binary files differnew file mode 100644 index 0000000..94a7084 --- /dev/null +++ b/docs/html/guide/topics/ui/images/android_normal.png diff --git a/docs/html/guide/topics/ui/images/android_pressed.png b/docs/html/guide/topics/ui/images/android_pressed.png Binary files differnew file mode 100644 index 0000000..fe81ff9 --- /dev/null +++ b/docs/html/guide/topics/ui/images/android_pressed.png diff --git a/docs/html/guide/topics/ui/images/hello-gallery.png b/docs/html/guide/topics/ui/images/hello-gallery.png Binary files differnew file mode 100755 index 0000000..22d1eaf --- /dev/null +++ b/docs/html/guide/topics/ui/images/hello-gallery.png diff --git a/docs/html/guide/topics/ui/images/hello-gridview.png b/docs/html/guide/topics/ui/images/hello-gridview.png Binary files differnew file mode 100755 index 0000000..2def0df --- /dev/null +++ b/docs/html/guide/topics/ui/images/hello-gridview.png diff --git a/docs/html/guide/topics/ui/images/hello-linearlayout.png b/docs/html/guide/topics/ui/images/hello-linearlayout.png Binary files differnew file mode 100755 index 0000000..dfef819 --- /dev/null +++ b/docs/html/guide/topics/ui/images/hello-linearlayout.png diff --git a/docs/html/guide/topics/ui/images/hello-listview.png b/docs/html/guide/topics/ui/images/hello-listview.png Binary files differnew file mode 100644 index 0000000..165b1ac --- /dev/null +++ b/docs/html/guide/topics/ui/images/hello-listview.png diff --git a/docs/html/guide/topics/ui/images/hello-mapview.png b/docs/html/guide/topics/ui/images/hello-mapview.png Binary files differnew file mode 100644 index 0000000..6bd9740 --- /dev/null +++ b/docs/html/guide/topics/ui/images/hello-mapview.png diff --git a/docs/html/guide/topics/ui/images/hello-relativelayout.png b/docs/html/guide/topics/ui/images/hello-relativelayout.png Binary files differnew file mode 100755 index 0000000..ec4d9d4 --- /dev/null +++ b/docs/html/guide/topics/ui/images/hello-relativelayout.png diff --git a/docs/html/guide/topics/ui/images/hello-tablelayout.png b/docs/html/guide/topics/ui/images/hello-tablelayout.png Binary files differnew file mode 100755 index 0000000..3d80e7f --- /dev/null +++ b/docs/html/guide/topics/ui/images/hello-tablelayout.png diff --git a/docs/html/guide/topics/ui/images/hello-tabwidget.png b/docs/html/guide/topics/ui/images/hello-tabwidget.png Binary files differnew file mode 100644 index 0000000..6580c5b --- /dev/null +++ b/docs/html/guide/topics/ui/images/hello-tabwidget.png diff --git a/docs/html/guide/topics/ui/images/hello-webview.png b/docs/html/guide/topics/ui/images/hello-webview.png Binary files differnew file mode 100644 index 0000000..248c6d4 --- /dev/null +++ b/docs/html/guide/topics/ui/images/hello-webview.png diff --git a/docs/html/guide/topics/ui/images/ic_tab_artists_grey.png b/docs/html/guide/topics/ui/images/ic_tab_artists_grey.png Binary files differnew file mode 100644 index 0000000..9baa30e --- /dev/null +++ b/docs/html/guide/topics/ui/images/ic_tab_artists_grey.png diff --git a/docs/html/guide/topics/ui/images/ic_tab_artists_white.png b/docs/html/guide/topics/ui/images/ic_tab_artists_white.png Binary files differnew file mode 100644 index 0000000..3b010d5 --- /dev/null +++ b/docs/html/guide/topics/ui/images/ic_tab_artists_white.png diff --git a/docs/html/guide/topics/ui/index.jd b/docs/html/guide/topics/ui/index.jd index be07249..f342b06 100644 --- a/docs/html/guide/topics/ui/index.jd +++ b/docs/html/guide/topics/ui/index.jd @@ -1,236 +1,61 @@ page.title=User Interface -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>In this document</h2> - <ol> - <li><a href="#ViewHierarchy">View Hierarchy</a></li> - <li><a href="#Layout">Layout</a></li> - <li><a href="#Widgets">Widgets</a></li> - <li><a href="#Events">Input Events</a></li> - <li><a href="#Menus">Menus</a></li> - <li><a href="#Advanced">Advanced Topics</a> - <ol> - <li><a href="#Adapters">Adapters</a></li> - <li><a href="#StylesAndThemes">Styles and Themes</a></li> - </ol> - </li> - </ol> - - <h2>Key classes</h2> - <ol> - <li>{@link android.view.View}</li> - <li>{@link android.view.ViewGroup}</li> - <li>{@link android.widget Widget classes}</li> - </ol> -</div> -</div> - -<p>In an Android application, the user interface is built using {@link android.view.View} and -{@link android.view.ViewGroup} objects. There are many types of views and view groups, each of which -is a descendant of the {@link android.view.View} class.</p> - -<p>View objects are the basic units of user interface expression on the Android platform. -The View class serves as the base for subclasses called "widgets," which offer fully implemented -UI objects, like text fields and buttons. The ViewGroup class serves as the base for subclasses called "layouts," -which offer different kinds of layout architecture, like linear, tabular and relative.</p> - -<p>A View object is a data structure whose properties store the layout parameters and content for a specific -rectangular area of the screen. A View object handles its own measurement, layout, drawing, focus change, -scrolling, and key/gesture interactions for the rectangular area of the screen in which it resides. As an -object in the user interface, a View is also a point of interaction for the user and the receiver -of the interaction events.</p> - - -<h2 id="ViewHierarchy">View Hierarchy</h2> - -<p>On the Android platform, you define an Activity's UI using a hierarchy of View and ViewGroup nodes, -as shown in the diagram below. This hierarchy tree can be as simple or complex as you need it to be, and you -can build it up using Android's set of predefined widgets and layouts, or with custom Views that you -create yourself.</p> +page.landing=true +page.landing.intro=Your app's user interface is everything that the user can see and interact with. Android provides a variety of pre-build UI components such as structured layout objects and UI controls that allow you to build the graphical user interface for your app. Android also provides other UI modules for special interfaces such as dialogs, notifications, and menus. +page.landing.image=images/ui/ui_index.png +page.landing.next=overview.html -<img src="{@docRoot}images/viewgroup.png" alt="" /> - -<p> -In order to attach the view hierarchy tree to the screen for rendering, your Activity must call the -<code>{@link android.app.Activity#setContentView(int) setContentView()}</code> -method and pass a reference to the root node object. The Android system -receives this reference and uses it to invalidate, measure, and draw the tree. The root node of the hierarchy requests -that its child nodes draw themselves — in turn, each view group node is responsible for calling -upon each of its own child views to draw themselves. -The children may request a size and location within the parent, but the parent object has the final -decision on where how big each child can be. Android parses -the elements of your layout in-order (from the top of the hierarchy tree), instantiating the Views and -adding them to their parent(s). Because these are drawn in-order, if there are elements that -overlap positions, the last one to be drawn will lie on top of others previously drawn to that space.</p> - -<p>For a more detailed discussion on how view hierarchies are measured -and drawn, read <a href="how-android-draws.html">How Android Draws Views</a>.</p> - - -<h2 id="Layout">Layout</h2> - -<p>The most common way to define your layout and express the view hierarchy is with an XML layout file. -XML offers a human-readable structure for the layout, much like HTML. Each element in XML is -either a View or ViewGroup object (or descendant thereof). View objects are leaves in the tree, -ViewGroup objects are branches in the tree (see the View Hierarchy figure above).</p> -<p>The name of an XML element -is respective to the Java class that it represents. So a <code><TextView></code> element creates -a {@link android.widget.TextView} in your UI, and a <code><LinearLayout></code> element creates -a {@link android.widget.LinearLayout} view group. When you load a layout resource, -the Android system initializes these run-time objects, corresponding to the elements in your layout.</p> - -<p>For example, a simple vertical layout with a text view and a button looks like this:</p> -<pre> -<?xml version="1.0" encoding="utf-8"?> -<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" - android:layout_width="fill_parent" - android:layout_height="fill_parent" - android:orientation="vertical" > - <TextView android:id="@+id/text" - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:text="Hello, I am a TextView" /> - <Button android:id="@+id/button" - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:text="Hello, I am a Button" /> -</LinearLayout> -</pre> - -<p>Notice that the LinearLayout element contains both the TextView and the Button. You can nest -another LinearLayout (or other type of view group) inside here, to lengthen the view hierarchy and create a more -complex layout.</p> +@jd:body -<p>For more on building a UI layout, read <a href="declaring-layout.html">XML Layouts</a>. +<div class="landing-docs"> + + <div class="col-6"> + <h3>Blog Articles</h3> + + <a href="http://android-developers.blogspot.com/2012/01/say-goodbye-to-menu-button.html"> + <h4>Say Goodbye to the Menu Button</h4> + <p>As Ice Cream Sandwich rolls out to more devices, it’s important that you begin to migrate +your designs to the action bar in order to promote a consistent Android user experience.</p> </a> + + <a href="http://android-developers.blogspot.com/2011/11/new-layout-widgets-space-and-gridlayout.html"> + <h4>New Layout Widgets: Space and GridLayout</h4> + <p>Ice Cream Sandwich (ICS) sports two new widgets that have been designed to support the +richer user interfaces made possible by larger displays: Space and GridLayout.</p> </a> + + <a href="http://android-developers.blogspot.com/2011/04/customizing-action-bar.html"> + <h4>Customizing the Action Bar</h4> + <p>By using the Action Bar in your Honeycomb-targeted apps, you'll give your users a familiar +way to interact with your application.</p> </a> + + <a href="http://android-developers.blogspot.com/2011/08/horizontal-view-swiping-with-viewpager.html"> + <h4>Horizontal View Swiping with ViewPager</h4> + <p>Whether you have just started out in Android app development or are a veteran of the craft, +it probably won’t be too long before you’ll need to implement horizontally scrolling sets of views. +</p> </a> + </div> + + <div class="col-6"> + <h3>Training</h3> + + <a href="http://developer.android.com/training/implementing-navigation/index.html"> + <h4>Implementing Effective Navigation</h4> + <p>This class shows you how to plan out the high-level screen hierarchy for your application +and then choose appropriate forms of navigation to allow users to effectively and intuitively +traverse your content.</p> </a> + + <a href="http://developer.android.com/training/multiscreen/index.html"> + <h4>Designing for Multiple Screens</h4> + <p>Android powers hundreds of device types with several different screen sizes, ranging from +small phones to large TV sets. This class shows you how to implement a user interface that's +optimized for several screen configurations.</p> + </a> + + <a href="http://developer.android.com/training/improving-layouts/index.html"> + <h4>Improving Layout Performance</h4> + <p>Layouts are a key part of Android applications that directly affect the user experience. If +implemented poorly, your layout can lead to a memory hungry application with slow UIs. This +class shows you how to avoid such problems.</p> + </a> + </div> -<div class="sidebox-wrapper"> -<div class="sidebox"> - <p><b>Tip:</b> You can also draw View and ViewGroups objects in Java code, - using the <code>{@link android.view.ViewGroup#addView(View)}</code> methods - to dynamically insert new View and ViewGroup objects.</p> -</div> </div> -<p>There are a variety of ways in which you can layout your views. Using more and different kinds of view groups, -you can structure child views and view groups in an infinite number of ways. -Some pre-defined view groups offered by Android (called layouts) include LinearLayout, RelativeLayout, -TableLayout, GridLayout and others. Each offers a unique set of layout parameters that are used to define the -positions of child views and layout structure.</p> -<p>To learn about some of the different kinds of view groups used for a layout, -read <a href="layout-objects.html">Common Layout Objects</a>.</p> - - -<h2 id="Widgets">Widgets</h2> - -<p>A widget is a View object that serves as an interface for interaction with the user. -Android provides a set of fully implemented -widgets, like buttons, checkboxes, and text-entry fields, so you can quickly build your UI. -Some widgets provided by Android are more complex, like a date picker, a clock, and zoom controls. -But you're not limited to the kinds of widgets provided by the Android platform. If you'd -like to do something more customized and create your own actionable elements, you can, by defining your own -View object or by extending and combining existing widgets.</p> -<p>Read more in the <a href="custom-components.html">Custom Components</a> developer guide.</p> - -<p>For a list of the widgets provided by Android, see the {@link android.widget} package.</p> - - -<h2 id="Events">Input Events</h2> - -<p>Once you've added some Views/widgets to the UI, you probably want to know about the -user's interaction with them, so you can perform actions. To be informed of user input events, you -need to do one of two things:</p> -<ul> - <li><strong>Define an event listener and register it with the View.</strong> More often than not, -this is how you'll listen for events. The View class contains a collection of nested interfaces named -On<em><something></em>Listener, each with a callback method called <code>On<em><something></em>()</code>. -For example, {@link android.view.View.OnClickListener} (for handling "clicks" on a View), -{@link android.view.View.OnTouchListener} (for handling touch screen events in a View), and -{@link android.view.View.OnKeyListener} if you want to handle hardware key presses within a View. So if you want your View -to be notified when it is "clicked" (such as when a button is selected), implement OnClickListener and define -its <code>onClick()</code> callback method (where you perform the action upon click), and register it -to the View with <code>{@link android.view.View#setOnClickListener(View.OnClickListener) setOnClickListener()}</code>. -</li> - <li><strong>Override an existing callback method for the View.</strong> This is -what you should do when you've implemented your own View class and want to listen for specific events -that occur within it. Example events you can handle include when the -screen is touched (<code>{@link android.view.View#onTouchEvent(MotionEvent) onTouchEvent()}</code>), when -the trackball is moved (<code>{@link android.view.View#onTrackballEvent(MotionEvent) onTrackballEvent()}</code>), -or when a <em>hardware</em> key on the device is pressed (<code>{@link android.view.View#onKeyDown(int, KeyEvent) -onKeyDown()}</code>). This allows you to define the default behavior for each event inside your custom View and determine -whether the event should be passed on to some other child View. Again, these are callbacks to the View class, -so your only chance to define them is when you -<a href="{@docRoot}guide/topics/ui/custom-components.html">build a custom component</a>. -</li> -</ul> - -<p>Continue reading about handling user interaction with Views in the <a -href="ui-events.html">Input Events</a> document.</p> - - -<h2 id="Menus">Menus</h2> - -<p>Application menus are another important part of an application's UI. Menus offers a reliable interface that reveals -application functions and settings. The most common application menu is revealed by pressing -the <em>Menu</em> button on the device. However, you can also add Context Menus, which may be -revealed when the user presses -and holds down on an item.</p> - -<p>Menus are also structured using a View hierarchy, but you don't define this structure yourself. Instead, -you define the <code>{@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()}</code> or -<code>{@link android.app.Activity#onCreateContextMenu(ContextMenu,View,ContextMenu.ContextMenuInfo) onCreateContextMenu()}</code> -callback methods for your Activity and declare the items that you want to include in your menu. -At the appropriate time, Android will automatically create the necessary View hierarchy for the menu and -draw each of your menu items in it.</p> - -<p>Menus also handle their own events, so there's no need to register event listeners on the items in your menu. -When an item in your menu is selected, the <code>{@link android.app.Activity#onOptionsItemSelected(MenuItem) -onOptionsItemSelected()}</code> or -<code>{@link android.app.Activity#onContextItemSelected(MenuItem) onContextItemSelected()}</code> -method will be called by the framework.</p> - -<p>And just like your application layout, you have the option to declare the items for you menu in an XML file.</p> - -<p>Read <a href="{@docRoot}guide/topics/ui/menus.html">Menus</a> to learn more.</p> - - -<h2 id="Advanced">Advanced Topics</h2> - -<p>Once you've grappled the fundamentals of creating a user interface, you can explore -some advanced features for creating a more complex application interface.</p> - -<h3 id="Adapters">Adapters</h3> - -<p>Sometimes you'll want to populate a view group with some information that can't be hard-coded, instead, -you want to bind your view to an external source of data. To do this, you use an AdapterView as -your view group and each child View is initialized and populated with data from the Adapter.</p> -<p>The AdapterView object is an implementation of ViewGroup that determines its child views -based on a given Adapter object. The Adapter acts like a courier between your data source (perhaps an -array of external strings) and the AdapterView, which displays it. There are several implementations -of the Adapter class, for specific tasks, such as the CursorAdapter for reading database data from a Cursor, -or an ArrayAdapter for reading from an arbitrary array.</p> -<p>To learn more about using an Adapter to populate your views, read -<a href="binding.html">Binding to Data with AdapterView</a>.</p> - - -<h3 id="StylesAndThemes">Styles and Themes</h3> - -<p>Perhaps you're not satisfied with the look of the standard widgets. To revise them, you can create some -of your own styles and themes.</p> - -<ul> - <li>A style is a set of one or more formatting attributes that you can apply as a unit to individual elements -in your layout. For example, you could define a style that specifies a certain text size and color, then -apply it to only specific View elements.</li> - <li>A theme is a set of one or more formatting attributes that you can apply as a unit to all activities in -an application, or just a single activity. For example, you could define a theme that sets specific colors for -the window frame and the panel background, and sets text sizes and colors for menus. This theme can then be -applied to specific activities or the entire application.</li> -</ul> - -<p>Styles and themes are resources. Android provides some default style and theme resources that you can use, -or you can declare your own custom style and theme resources.</p> -<p>Learn more about using styles and themes in the -<a href="themes.html">Styles and Themes</a> document.</p> diff --git a/docs/html/guide/topics/ui/layout-objects.jd b/docs/html/guide/topics/ui/layout-objects.jd index e251fe9..1d15ad6 100644 --- a/docs/html/guide/topics/ui/layout-objects.jd +++ b/docs/html/guide/topics/ui/layout-objects.jd @@ -1,291 +1,6 @@ -page.title=Common Layout Objects +page.title=Layouts parent.title=User Interface parent.link=index.html @jd:body -<div id="qv-wrapper"> -<div id="qv"> - <h2>In this document</h2> - <ol> - <li><a href="#framelayout">FrameLayout</a></li> - <li><a href="#linearlayout">LinearLayout</a></li> - <li><a href="#tablelayout">TableLayout</a></li> - <li><a href="#relativelayout">RelativeLayout</a></li> - <li><a href="#viewgroupsummary">Summary of Important View Groups</a></li> - </ol> -</div> -</div> - -<p>This section describes some of the more common types of layout objects -to use in your applications. Like all layouts, they are subclasses of {@link android.view.ViewGroup ViewGroup}.</p> - -<p>Also see the <a href="{@docRoot}resources/tutorials/views/index.html">Hello Views</a> tutorials for -some guidance on using more Android View layouts.</p> - -<h2 id="framelayout">FrameLayout</h2> -<p>{@link android.widget.FrameLayout FrameLayout} is the simplest type of layout -object. It's basically a blank space on your screen that you can -later fill with a single object — for example, a picture that you'll swap in and out. -All child elements of the FrameLayout are pinned to the top left corner of the screen; you cannot -specify a different location for a child view. Subsequent child views will simply be drawn over previous ones, -partially or totally obscuring them (unless the newer object is transparent). -</p> - - -<h2 id="linearlayout">LinearLayout</h2> -<p>{@link android.widget.LinearLayout LinearLayout} aligns all children in a -single direction — vertically or horizontally, depending on how you -define the <code>orientation</code> attribute. All children are -stacked one after the other, so a vertical list will only have one child per -row, no matter how wide they are, and a horizontal list will only be one row -high (the height of the tallest child, plus padding). A {@link -android.widget.LinearLayout LinearLayout} respects <em>margin</em>s between children -and the <em>gravity</em> (right, center, or left alignment) of each child. </p> - -<p>{@link android.widget.LinearLayout LinearLayout} also supports assigning a -<em>weight</em> to individual children. This attribute assigns an "importance" value to a view, -and allows it to expand to fill any remaining space in the parent view. -Child views can specify an integer weight value, and then any remaining space in the view group is -assigned to children in the proportion of their declared weight. Default -weight is zero. For example, if there are three text boxes and two of -them declare a weight of 1, while the other is given no weight (0), the third text box without weight -will not grow and will only occupy the area required by its content. -The other two will expand equally to fill the space remaining after all three boxes are measured. -If the third box is then given a weight of 2 (instead of 0), then it is now declared -"more important" than both the others, so it gets half the total remaining space, while the first two -share the rest equally.</p> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<p><strong>Tip</strong>: To create a proportionate size -layout on the screen, create a container view group object with the -<code>layout_width</code> and <code>layout_height</code> attributes set to <var>fill_parent</var>; assign -the children <code>height</code> or <code>width</code> to <code>0</code> (zero); then assign relative -<code>weight</code> values -to each child, depending on what proportion of the screen each should -have.</p> -</div> -</div> - -<p>The following two forms represent a {@link android.widget.LinearLayout LinearLayout} with a set of elements: a -button, some labels and text boxes. The text boxes have their width set to <var>fill_parent</var>; other -elements are set to <var>wrap_content</var>. The gravity, by default, is left. -The difference between the two versions of the form is that the form -on the left has weight values unset (0 by default), while the form on the right has -the comments text box weight set to 1. If the Name textbox had also been set -to 1, the Name and Comments text boxes would be the same height. </p> - -<img src="{@docRoot}images/linearlayout.png" alt="" /> - -<p>Within a horizontal {@link android.widget.LinearLayout LinearLayout}, items are aligned by the position of -their text base line (the first line of the first list element — topmost or -leftmost — is considered the reference line). This is so that people scanning -elements in a form shouldn't have to jump up and down to read element text in -neighboring elements. This can be turned off by setting -<code>android:baselineAligned="false"</code> in the layout XML. </p> - -<p>To view other sample code, see the -<a href="{@docRoot}resources/tutorials/views/hello-linearlayout.html">Hello LinearLayout</a> tutorial.</p> - - -<h2 id="tablelayout">TableLayout</h2> -<p>{@link android.widget.TableLayout} positions its children into rows - and columns. TableLayout containers do not display border lines for their rows, columns, - or cells. The table will have as many columns as the row with the most cells. A table can leave -cells empty, but cells cannot span columns, as they can in HTML.</p> -<p>{@link android.widget.TableRow} objects are the child views of a TableLayout -(each TableRow defines a single row in the table). -Each row has zero or more cells, each of which is defined by any kind of other View. So, the cells of a row may be -composed of a variety of View objects, like ImageView or TextView objects. -A cell may also be a ViewGroup object (for example, you can nest another TableLayout as a cell).</p> -<p>The following sample layout has two rows and two cells in each. The accompanying screenshot shows the -result, with cell borders displayed as dotted lines (added for visual effect). </p> - -<table class="columns"> - <tr> - <td> - <pre> -<?xml version="1.0" encoding="utf-8"?> -<TableLayout xmlns:android="http://schemas.android.com/apk/res/android" - android:layout_width="fill_parent" - android:layout_height="fill_parent" - android:stretchColumns="1"> - <TableRow> - <TextView - android:text="@string/table_layout_4_open" - android:padding="3dip" /> - <TextView - android:text="@string/table_layout_4_open_shortcut" - android:gravity="right" - android:padding="3dip" /> - </TableRow> - - <TableRow> - <TextView - android:text="@string/table_layout_4_save" - android:padding="3dip" /> - <TextView - android:text="@string/table_layout_4_save_shortcut" - android:gravity="right" - android:padding="3dip" /> - </TableRow> -</TableLayout> -</pre></td> - <td><img src="{@docRoot}images/table_layout.png" alt="" style="margin:0" /></td> - </tr> -</table> - -<p>Columns can be hidden, marked to stretch and fill the available screen space, - or can be marked as shrinkable to force the column to shrink until the table - fits the screen. See the {@link android.widget.TableLayout TableLayout reference} -documentation for more details. </p> - -<p>To view sample code, see the <a href="{@docRoot}resources/tutorials/views/hello-tablelayout.html">Hello -TableLayout</a> tutorial.</p> - - -<h2 id="relativelayout">RelativeLayout</h2> -<p>{@link android.widget.RelativeLayout} lets child views specify their - position relative to the parent view or to each other (specified by ID). So you can - align two elements by right border, or make one below another, centered in - the screen, centered left, and so on. Elements are rendered in the order given, so if the first element - is centered in the screen, other elements aligning themselves to that element - will be aligned relative to screen center. Also, because of this ordering, if using XML to specify this layout, - the element that you will reference (in order to position other view objects) must be listed in the XML -file before you refer to it from the other views via its reference ID. </p> -<p>The example below shows an XML file and the resulting screen in the UI. -Note that the attributes that refer to relative elements (e.g., <var>layout_toLeft</var>) -refer to the ID using the syntax of a relative resource -(<var>@id/<em>id</em></var>). </p> - -<table class="columns"> - <tr> - <td> - <pre> -<?xml version="1.0" encoding="utf-8"?> -<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" - android:layout_width="fill_parent" - android:layout_height="wrap_content" - android:background="@drawable/blue" - android:padding="10px" > - - <TextView android:id="@+id/label" - android:layout_width="fill_parent" - android:layout_height="wrap_content" - android:text="Type here:" /> - - <EditText android:id="@+id/entry" - android:layout_width="fill_parent" - android:layout_height="wrap_content" - android:background="@android:drawable/editbox_background" - android:layout_below="@id/label" /> - - <Button android:id="@+id/ok" - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:layout_below="@id/entry" - android:layout_alignParentRight="true" - android:layout_marginLeft="10px" - android:text="OK" /> - - <Button android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:layout_toLeftOf="@id/ok" - android:layout_alignTop="@id/ok" - android:text="Cancel" /> -</RelativeLayout> -</pre></td> - <td><img src="{@docRoot}images/designing_ui_layout_example.png" alt="" style="margin:0" /></td> - </tr> -</table> - - -<p>Some of these properties are supported directly by - the element, and some are supported by its LayoutParams member (subclass RelativeLayout - for all the elements in this screen, because all elements are children of a RelativeLayout - parent object). The defined RelativeLayout parameters are: <code>width</code>, <code>height</code>, - <code>below</code>, <code>alignTop</code>, <code>toLeft</code>, <code>padding[Bottom|Left|Right|Top]</code>, - and <code>margin[Bottom|Left|Right|Top]</code>. Note that some of these parameters specifically support - relative layout positions — their values must be the ID of the element to which you'd like this view laid relative. - For example, assigning the parameter <code>toLeft="my_button"</code> to a TextView would place the TextView to - the left of the View with the ID <var>my_button</var> (which must be written in the XML <em>before</em> the TextView). </p> - -<p>To view this sample code, see the <a href="{@docRoot}resources/tutorials/views/hello-relativelayout.html">Hello -RelativeLayout</a> tutorial.</p> - - -<h2 id="viewgroupsummary">Summary of Important View Groups</h2> -<p>These objects all hold child UI elements. Some provide their own form of a visible UI, while others - are invisible structures that only manage the layout of their child views. </p> -<table width="100%" border="1"> - <tr> - <th scope="col">Class</th> - <th scope="col">Description</th> - </tr> - <tr> - <td>{@link android.widget.FrameLayout FrameLayout}</td> - <td>Layout that acts as a view frame to display - a single object. </td> - </tr> - <tr> - <td>{@link android.widget.Gallery Gallery} </td> - <td>A horizontal scrolling display of images, from a bound list. </td> - </tr> - <tr> - <td>{@link android.widget.GridView GridView} </td> - <td>Displays a scrolling grid of m columns and n rows.</td> - </tr> - <tr> - <td>{@link android.widget.LinearLayout LinearLayout} </td> - <td>A layout that organizes its children into a single horizontal or vertical - row. It creates a scrollbar if the length of the window exceeds the length - of the screen. </td> - </tr> - <tr> - <td>{@link android.widget.ListView ListView} </td> - <td>Displays a scrolling single column list. </td> - </tr> - <tr> - <td>{@link android.widget.RelativeLayout RelativeLayout} </td> - <td>Enables you to specify the location of child objects relative to each - other (child A to the left of child B) or to the parent (aligned to the - top of the parent). </td> - </tr> - <tr> - <td>{@link android.widget.ScrollView ScrollView} </td> - <td>A vertically scrolling column of elements. </td> - </tr> - <tr> - <td>{@link android.widget.Spinner Spinner} </td> - <td>Displays a single item at a time from a bound list, inside a one-row - textbox. Rather like a one-row listbox that can scroll either horizontally - or vertically. </td> - </tr> - <tr> - <td>{@link android.view.SurfaceView SurfaceView} </td> - <td>Provides direct access to a dedicated drawing surface. It can hold child - views layered on top of the surface, but is intended for applications - that need to draw pixels, rather than using widgets. </td> - </tr> - <tr> - <td>{@link android.widget.TabHost TabHost} </td> - <td>Provides a tab selection list that monitors clicks and enables the application - to change the screen whenever a tab is clicked. </td> - </tr> - <tr> - <td>{@link android.widget.TableLayout TableLayout} </td> - <td>A tabular layout with an arbitrary number of rows and columns, each cell - holding the widget of your choice. The rows resize to fit the largest - column. The cell borders are not - visible. </td> - </tr> - <tr> - <td>{@link android.widget.ViewFlipper ViewFlipper} </td> - <td>A list that displays one item at a time, inside a one-row textbox. It - can be set to swap items at timed intervals, like a slide show. </td> - </tr> - <tr> - <td>{@link android.widget.ViewSwitcher ViewSwitcher} </td> - <td>Same as ViewFlipper. </td> - </tr> -</table> +<p>You should have been redirected to <a href="declaring-layout.html">Layouts</a>.</p>
\ No newline at end of file diff --git a/docs/html/guide/topics/ui/layout/grid.jd b/docs/html/guide/topics/ui/layout/grid.jd new file mode 100644 index 0000000..52f453b --- /dev/null +++ b/docs/html/guide/topics/ui/layout/grid.jd @@ -0,0 +1,187 @@ +page.title=Table +parent.title=Layouts +parent.link=layout-objects.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> + <ol> + <li><a href="#example">Example</a></li> + </ol> + <h2>Key classes</h2> + <ol> + <li>{@link android.widget.TableLayout}</li> + <li>{@link android.widget.TableRow}</li> + <li>{@link android.widget.TextView}</li> + </ol> +</div> +</div> +<p>{@link android.widget.TableLayout} is a {@link android.view.ViewGroup} that +displays child {@link android.view.View} elements in rows and columns.</p> + + +<img src="{@docRoot}images/ui/gridlayout.png" alt="" /> + +<p>{@link android.widget.TableLayout} positions its children into rows + and columns. TableLayout containers do not display border lines for their rows, columns, + or cells. The table will have as many columns as the row with the most cells. A table can leave +cells empty, but cells cannot span columns, as they can in HTML.</p> +<p>{@link android.widget.TableRow} objects are the child views of a TableLayout +(each TableRow defines a single row in the table). +Each row has zero or more cells, each of which is defined by any kind of other View. So, the cells of a row may be +composed of a variety of View objects, like ImageView or TextView objects. +A cell may also be a ViewGroup object (for example, you can nest another TableLayout as a cell).</p> +<p>The following sample layout has two rows and two cells in each. The accompanying screenshot shows the +result, with cell borders displayed as dotted lines (added for visual effect). </p> + +<table class="columns"> + <tr> + <td> + <pre> +<?xml version="1.0" encoding="utf-8"?> +<TableLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:stretchColumns="1"> + <TableRow> + <TextView + android:text="@string/table_layout_4_open" + android:padding="3dip" /> + <TextView + android:text="@string/table_layout_4_open_shortcut" + android:gravity="right" + android:padding="3dip" /> + </TableRow> + + <TableRow> + <TextView + android:text="@string/table_layout_4_save" + android:padding="3dip" /> + <TextView + android:text="@string/table_layout_4_save_shortcut" + android:gravity="right" + android:padding="3dip" /> + </TableRow> +</TableLayout> +</pre></td> + <td><img src="{@docRoot}images/table_layout.png" alt="" style="margin:0" /></td> + </tr> +</table> + +<p>Columns can be hidden, marked to stretch and fill the available screen space, + or can be marked as shrinkable to force the column to shrink until the table + fits the screen. See the {@link android.widget.TableLayout TableLayout reference} +documentation for more details. </p> + + +<h2 id="example">Example</h2> +<ol> + <li>Start a new project named <em>HelloTableLayout</em>.</li> + <li>Open the <code>res/layout/main.xml</code> file and insert the following: +<pre> +<?xml version="1.0" encoding="utf-8"?> +<TableLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:stretchColumns="1"> + + <TableRow> + <TextView + android:layout_column="1" + android:text="Open..." + android:padding="3dip" /> + <TextView + android:text="Ctrl-O" + android:gravity="right" + android:padding="3dip" /> + </TableRow> + + <TableRow> + <TextView + android:layout_column="1" + android:text="Save..." + android:padding="3dip" /> + <TextView + android:text="Ctrl-S" + android:gravity="right" + android:padding="3dip" /> + </TableRow> + + <TableRow> + <TextView + android:layout_column="1" + android:text="Save As..." + android:padding="3dip" /> + <TextView + android:text="Ctrl-Shift-S" + android:gravity="right" + android:padding="3dip" /> + </TableRow> + + <View + android:layout_height="2dip" + android:background="#FF909090" /> + + <TableRow> + <TextView + android:text="X" + android:padding="3dip" /> + <TextView + android:text="Import..." + android:padding="3dip" /> + </TableRow> + + <TableRow> + <TextView + android:text="X" + android:padding="3dip" /> + <TextView + android:text="Export..." + android:padding="3dip" /> + <TextView + android:text="Ctrl-E" + android:gravity="right" + android:padding="3dip" /> + </TableRow> + + <View + android:layout_height="2dip" + android:background="#FF909090" /> + + <TableRow> + <TextView + android:layout_column="1" + android:text="Quit" + android:padding="3dip" /> + </TableRow> +</TableLayout> +</pre> +<p>Notice how this resembles the structure of an HTML table. The {@link android.widget.TableLayout} +element is like the HTML <code><table></code> element; {@link android.widget.TableRow} is like +a <code>><tr>></code> element; +but for the cells, you can use any kind of {@link android.view.View} element. In this example, a +{@link android.widget.TextView} is used for each cell. In between some of the rows, there is also a +basic {@link android.view.View}, which is used to draw a horizontal line.</p> + +</li> +<li>Make sure your <em>HelloTableLayout</em> Activity loads this layout in the +{@link android.app.Activity#onCreate(Bundle) onCreate()} method: +<pre> +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); +} +</pre> +<p>The {@link android.app.Activity#setContentView(int)} method loads the +layout file for the {@link android.app.Activity}, specified by the resource +ID — <code>R.layout.main</code> refers to the <code>res/layout/main.xml</code> layout +file.</p> +</li> +<li>Run the application.</li> +</ol> +<p>You should see the following:</p> +<img src="images/hello-tablelayout.png" width="150px" /> + + + diff --git a/docs/html/guide/topics/ui/layout/gridview.jd b/docs/html/guide/topics/ui/layout/gridview.jd new file mode 100644 index 0000000..284a25a --- /dev/null +++ b/docs/html/guide/topics/ui/layout/gridview.jd @@ -0,0 +1,191 @@ +page.title=Grid +parent.title=Layouts +parent.link=layout-objects.html +@jd:body +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> + <ol> + <li><a href="#example">Example</a></li> + </ol> + <h2>Key classes</h2> + <ol> + <li>{@link android.widget.GridView}</li> + <li>{@link android.widget.ImageView}</li> + <li>{@link android.widget.BaseAdapter}</li> + <li>{@link android.widget.AdapterView.OnItemClickListener}</li> + </ol> +</div> +</div> +<p>{@link android.widget.GridView} is a {@link android.view.ViewGroup} that displays items in a +two-dimensional, +scrollable grid. The grid items are automatically inserted to the layout using a {@link +android.widget.ListAdapter}.</p> + +<img src="{@docRoot}images/ui/gridview.png" alt="" /> + + +<h2 id="example">Example</h2> +<p>In this tutorial, you'll create a grid of image thumbnails. When an item is selected, a +toast message will display the position of the image.</p> + + +<ol> + <li>Start a new project named <em>HelloGridView</em>.</li> + <li>Find some photos you'd like to use, or <a +href="{@docRoot}shareables/sample_images.zip">download these sample images</a>. Save the image files +into the project's +<code>res/drawable/</code> directory.</li> + <li>Open the <code>res/layout/main.xml</code> file and insert the following: +<pre> +<?xml version="1.0" encoding="utf-8"?> +<GridView xmlns:android="http://schemas.android.com/apk/res/android" + android:id="@+id/gridview" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:columnWidth="90dp" + android:numColumns="auto_fit" + android:verticalSpacing="10dp" + android:horizontalSpacing="10dp" + android:stretchMode="columnWidth" + android:gravity="center" +/> +</pre> + <p>This {@link android.widget.GridView} will fill the entire screen. The attributes are rather +self explanatory. For more information about valid attributes, see the {@link +android.widget.GridView} reference.</p> +</li> + <li>Open <code>HelloGridView.java</code> and insert the following code for the +{@link android.app.Activity#onCreate(Bundle) onCreate()} method: +<pre> +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + + GridView gridview = (GridView) findViewById(R.id.gridview); + gridview.setAdapter(new ImageAdapter(this)); + + gridview.setOnItemClickListener(new OnItemClickListener() { + public void onItemClick(AdapterView<?> parent, View v, int position, long id) { + Toast.makeText(HelloGridView.this, "" + position, Toast.LENGTH_SHORT).show(); + } + }); +} +</pre> + <p>After the {@code main.xml} layout is set for the content view, the +{@link android.widget.GridView} is captured from the layout with {@link +android.app.Activity#findViewById(int)}. The {@link +android.widget.GridView#setAdapter(T) setAdapter()} method then sets a custom adapter ({@code +ImageAdapter}) as the source for all items to be displayed in the grid. The {@code ImageAdapter} is +created in the next step.</p> +<p>To do something when an item in the grid is clicked, the {@link +android.widget.AdapterView#setOnItemClickListener(OnItemClickListener) setOnItemClickListener()} +method is passed a new {@link android.widget.AdapterView.OnItemClickListener}. This anonymous +instance defines the {@link +android.widget.AdapterView.OnItemClickListener#onItemClick(AdapterView,View,int,long) +onItemClick()} callback method to show a {@link android.widget.Toast} that displays the index +position (zero-based) of the selected item (in a real world scenario, the position could be used to +get the full sized +image for some other task).</p> + +</li> +<li>Create a new class called <code>ImageAdapter</code> that extends {@link +android.widget.BaseAdapter}: +<pre> +public class ImageAdapter extends BaseAdapter { + private Context mContext; + + public ImageAdapter(Context c) { + mContext = c; + } + + public int getCount() { + return mThumbIds.length; + } + + public Object getItem(int position) { + return null; + } + + public long getItemId(int position) { + return 0; + } + + // create a new ImageView for each item referenced by the Adapter + public View getView(int position, View convertView, ViewGroup parent) { + ImageView imageView; + if (convertView == null) { // if it's not recycled, initialize some attributes + imageView = new ImageView(mContext); + imageView.setLayoutParams(new GridView.LayoutParams(85, 85)); + imageView.setScaleType(ImageView.ScaleType.CENTER_CROP); + imageView.setPadding(8, 8, 8, 8); + } else { + imageView = (ImageView) convertView; + } + + imageView.setImageResource(mThumbIds[position]); + return imageView; + } + + // references to our images + private Integer[] mThumbIds = { + R.drawable.sample_2, R.drawable.sample_3, + R.drawable.sample_4, R.drawable.sample_5, + R.drawable.sample_6, R.drawable.sample_7, + R.drawable.sample_0, R.drawable.sample_1, + R.drawable.sample_2, R.drawable.sample_3, + R.drawable.sample_4, R.drawable.sample_5, + R.drawable.sample_6, R.drawable.sample_7, + R.drawable.sample_0, R.drawable.sample_1, + R.drawable.sample_2, R.drawable.sample_3, + R.drawable.sample_4, R.drawable.sample_5, + R.drawable.sample_6, R.drawable.sample_7 + }; +} +</pre> +<p>First, this implements some required methods inherited from {@link +android.widget.BaseAdapter}. The constructor and {@link +android.widget.Adapter#getCount()} are self-explanatory. Normally, {@link +android.widget.Adapter#getItem(int)} should return the actual object at the specified position in +the adapter, but it's ignored for this example. Likewise, {@link +android.widget.Adapter#getItemId(int)} should return the row id of the item, but it's not +needed here.</p> + +<p>The first method necessary is {@link android.widget.Adapter#getView(int,View,ViewGroup) +getView()}. This method creates a new {@link android.view.View} for each image added to the {@code +ImageAdapter}. When this is called, a {@link android.view.View} is passed in, which is normally a +recycled object (at least after this has been called once), so there's a check to see if the +object is null. If it <em>is</em> null, an {@link android.widget.ImageView} is instantiated and +configured with desired properties for the image presentation:</p> +<ul> + <li>{@link android.view.View#setLayoutParams(ViewGroup.LayoutParams)} sets +the height and width for the View—this ensures that, no matter the size of the drawable, each +image is resized and cropped to fit in these dimensions, as appropriate.</li> + <li>{@link android.widget.ImageView#setScaleType(ImageView.ScaleType)} declares that images should +be cropped toward the center (if necessary).</li> + <li>{@link android.widget.ImageView#setPadding(int,int,int,int)} defines the padding for all +sides. (Note that, if the images have different aspect-ratios, then less +padding will cause for more cropping of the image if it does not match +the dimensions given to the ImageView.)</li> +</ul> + +<p>If the {@link android.view.View} passed to {@link +android.widget.Adapter#getView(int,View,ViewGroup) getView()} is <em>not</em> null, then the local +{@link android.widget.ImageView} is initialized with the recycled {@link android.view.View} +object.</p> + +<p>At the end of the {@link android.widget.Adapter#getView(int,View,ViewGroup) getView()} method, +the {@code +position} integer passed into the method is used to select an image from the {@code mThumbIds} +array, which is set as the image resource for the {@link android.widget.ImageView}.</p> +<p>All that's left is to define the {@code mThumbIds} array of drawable resources.</p> +</li> +<li>Run the application.</li> +</ol> + +<p>Try experimenting with the behaviors of the {@link android.widget.GridView} and {@link +android.widget.ImageView} elements by adjusting their properties. For example, instead of using +{@link android.view.View#setLayoutParams(ViewGroup.LayoutParams)}, try using +{@link android.widget.ImageView#setAdjustViewBounds(boolean)}. </p> + + diff --git a/docs/html/guide/topics/ui/layout/linear.jd b/docs/html/guide/topics/ui/layout/linear.jd new file mode 100644 index 0000000..8e33706 --- /dev/null +++ b/docs/html/guide/topics/ui/layout/linear.jd @@ -0,0 +1,116 @@ +page.title=Linear Layout +parent.title=Layouts +parent.link=layout-objects.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> +<ol> + <li><a href="#Weight">Layout Weight</a></li> + <li><a href="#Example">Example</a></li> +</ol> + +<h2>Key classes</h2> +<ol> + <li>{@link android.widget.LinearLayout}</li> + <li>{@link android.widget.LinearLayout.LayoutParams}</li> +</ol> +</div> +</div> + +<p>{@link android.widget.LinearLayout} is a view group that aligns all children in a single +direction, vertically or horizontally. You can specify the layout direction with the +<a href="{@docRoot}reference/android/widget/LinearLayout.html#attr_android:orientation">{@code +android:orientation}</a> attribute.</p> + +<img src="{@docRoot}images/ui/linearlayout.png" alt="" /> + +<p>All children of a {@link android.widget.LinearLayout} are +stacked one after the other, so a vertical list will only have one child per +row, no matter how wide they are, and a horizontal list will only be one row +high (the height of the tallest child, plus padding). A {@link +android.widget.LinearLayout LinearLayout} respects <em>margin</em>s between children +and the <em>gravity</em> (right, center, or left alignment) of each child. </p> + + +<h2 id="Weight">Layout Weight</h2> + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h3>Equally weighted children</h3> +<p>To create a linear layout in which each child uses the same amount of +space on the screen, set the <a +href="{@docRoot}reference/android/view/ViewGroup.LayoutParams.html#attr_android:layout_height" +>{@code android:layout_height}</a> of each view to {@code "0dp"} (for a +vertical layout) or the <a +href="{@docRoot}reference/android/view/ViewGroup.LayoutParams.html#attr_android:layout_width" +>{@code android:layout_width}</a> of each view to {@code "0dp"} (for a +horizontal +layout). Then set the <a +href="{@docRoot}reference/android/widget/LinearLayout.LayoutParams.html#attr_android:layout_weight" +>{@code android:layout_weight}</a> of each view to {@code "1"}.</p> +</div> +</div> + + +<p>{@link android.widget.LinearLayout} also supports assigning a +<em>weight</em> to individual children with the <a +href="{@docRoot}reference/android/widget/LinearLayout.LayoutParams.html#attr_android:layout_weight" +>{@code android:layout_weight}</a> attribute. +This attribute assigns an "importance" value to a view in +terms of how much space is should occupy on the screen. A larger weight value allows it to expand +to fill any remaining space in the parent view. +Child views can specify a weight value, and then any remaining space in the view group is +assigned to children in the proportion of their declared weight. Default +weight is zero.</p> + +<p>For example, if there are three text fields and two of them declare a weight of 1, while the +other is given no weight, the third text field without weight will not grow and will only occupy the +area required by its content. The other two will expand equally to fill the space remaining after +all three fields are measured. If the third field is then given a weight of 2 (instead of 0), then +it is now declared more important than both the others, so it gets half the total remaining space, +while the first two +share the rest equally.</p> + + +<h2 id="Example">Example</h2> + +<div class="figure" style="width:220px;margin-top:0"> +<img src="{@docRoot}images/ui/sample-linearlayout.png" alt="" /> +</div> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:paddingLeft="16dp" + android:paddingRight="16dp" + android:orientation="vertical" > + <EditText + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:hint="@string/to" /> + <EditText + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:hint="@string/subject" /> + <EditText + android:layout_width="fill_parent" + android:layout_height="0dp" + android:layout_weight="1" + android:gravity="top" + android:hint="@string/message" /> + <Button + android:layout_width="100dp" + android:layout_height="wrap_content" + android:layout_gravity="right" + android:text="@string/send" /> +</LinearLayout> +</pre> + +<p>For details about the attributes available to each child view of a {@link +android.widget.LinearLayout}, see {@link android.widget.LinearLayout.LayoutParams}.</p> + + diff --git a/docs/html/guide/topics/ui/layout/listview.jd b/docs/html/guide/topics/ui/layout/listview.jd new file mode 100644 index 0000000..26a7597 --- /dev/null +++ b/docs/html/guide/topics/ui/layout/listview.jd @@ -0,0 +1,151 @@ +page.title=List View +parent.title=Layouts +parent.link=declaring-layout.html +@jd:body +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> + <ol> + <li><a href="#Loader">Using a Loader</a></li> + <li><a href="#Example">Example</a></li> + </ol> + <h2>Key classes</h2> + <ol> + <li>{@link android.widget.ListView}</li> + <li>{@link android.widget.Adapter}</li> + <li>{@link android.support.v4.content.CursorLoader}</li> + </ol> + <h2>See also</h2> + <ol> + <li><a +href="{@docRoot}guide/components/loaders.html">Loaders</a></li> + </ol> +</div> +</div> + +<p>{@link android.widget.ListView} is a view group that displays a list of +scrollable items. The list items are automatically inserted to the list using an {@link +android.widget.Adapter} that pulls content from a source such as an array or database query and +converts each item result into a view that's placed into the list.</p> + +<img src="{@docRoot}images/ui/listview.png" alt="" /> + +<h2 id="Loader">Using a Loader</h2> + +<p>Using a {@link +android.support.v4.content.CursorLoader} is the standard way to query a {@link +android.database.Cursor} as an asynchronous task in order to avoid blocking your app's main thread +with the query. When the {@link android.support.v4.content.CursorLoader} receives the {@link +android.database.Cursor} result, the {@link android.support.v4.app.LoaderManager.LoaderCallbacks +LoaderCallbacks} receives a callback to {@link +android.support.v4.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()}, which is +where you update your {@link +android.widget.Adapter} with the new {@link android.database.Cursor} and the list view then +displays the results.</p> + +<p>Although the {@link android.support.v4.content.CursorLoader} APIs were first introduced in +Android 3.0 (API level 11), they are also available in the <a +href="{@docRoot}tools/extras/support-library.html">Support Library</a> so that your app may use them +while supporting devices running Android 1.6 or higher.</p> + +<p>For more information about using a {@link +android.support.v4.content.Loader} to asynchronously load data, see the <a +href="{@docRoot}guide/components/loaders.html">Loaders</a> guide.</p> + + +<h2 id="Example">Example</h2> + +<p>The following example uses {@link android.app.ListActivity}, which is an activity that includes +a {@link android.widget.ListView} as its only layout element by default. It performs a query to +the <a +href="{@docRoot}guide/topics/providers/contacts-provider.html">Contacts +Provider</a> for a list of names and phone numbers.</p> + +<p>The activity implements the {@link android.support.v4.app.LoaderManager.LoaderCallbacks +LoaderCallbacks} interface in order to use a {@link android.support.v4.content.CursorLoader} that +dynamically loads the data for the list view.</p> + +<pre> +public class ListViewLoader extends ListActivity + implements LoaderManager.LoaderCallbacks<Cursor> { + + // This is the Adapter being used to display the list's data + SimpleCursorAdapter mAdapter; + + // These are the Contacts rows that we will retrieve + static final String[] PROJECTION = new String[] {ContactsContract.Data._ID, + ContactsContract.Data.DISPLAY_NAME}; + + // This is the select criteria + static final String SELECTION = "((" + + ContactsContract.Data.DISPLAY_NAME + " NOTNULL) AND (" + + ContactsContract.Data.DISPLAY_NAME + " != '' ))"; + + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + + // Create a progress bar to display while the list loads + ProgressBar progressBar = new ProgressBar(this); + progressBar.setLayoutParams(new LayoutParams(LayoutParams.WRAP_CONTENT, + LayoutParams.WRAP_CONTENT, Gravity.CENTER)); + progressBar.setIndeterminate(true); + getListView().setEmptyView(progressBar); + + // Must add the progress bar to the root of the layout + ViewGroup root = (ViewGroup) findViewById(android.R.id.content); + root.addView(progressBar); + + // For the cursor adapter, specify which columns go into which views + String[] fromColumns = {ContactsContract.Data.DISPLAY_NAME}; + int[] toViews = {android.R.id.text1}; // The TextView in simple_list_item_1 + + // Create an empty adapter we will use to display the loaded data. + // We pass null for the cursor, then update it in onLoadFinished() + mAdapter = new SimpleCursorAdapter(this, + android.R.layout.simple_list_item_1, null, + fromColumns, toViews, 0); + setListAdapter(mAdapter); + + // Prepare the loader. Either re-connect with an existing one, + // or start a new one. + getLoaderManager().initLoader(0, null, this); + } + + // Called when a new Loader needs to be created + public Loader<Cursor> onCreateLoader(int id, Bundle args) { + // Now create and return a CursorLoader that will take care of + // creating a Cursor for the data being displayed. + return new CursorLoader(this, ContactsContract.Data.CONTENT_URI, + PROJECTION, SELECTION, null, null); + } + + // Called when a previously created loader has finished loading + public void onLoadFinished(Loader<Cursor> loader, Cursor data) { + // Swap the new cursor in. (The framework will take care of closing the + // old cursor once we return.) + mAdapter.swapCursor(data); + } + + // Called when a previously created loader is reset, making the data unavailable + public void onLoaderReset(Loader<Cursor> loader) { + // This is called when the last Cursor provided to onLoadFinished() + // above is about to be closed. We need to make sure we are no + // longer using it. + mAdapter.swapCursor(null); + } + + @Override + public void onListItemClick(ListView l, View v, int position, long id) { + // Do something when a list item is clicked + } +} +</pre> + +<p class="note"><strong>Note:</strong> Because this sample performs a query on the <a +href="{@docRoot}guide/topics/providers/contacts-provider.html">Contacts +Provider</a>, if you want to +try this code, your app must request the {@link android.Manifest.permission#READ_CONTACTS} +permission in the manifest file:<br/> +<code><uses-permission android:name="android.permission.READ_CONTACTS" /></p> + diff --git a/docs/html/guide/topics/ui/layout/relative.jd b/docs/html/guide/topics/ui/layout/relative.jd new file mode 100644 index 0000000..ee6cf02 --- /dev/null +++ b/docs/html/guide/topics/ui/layout/relative.jd @@ -0,0 +1,118 @@ +page.title=Relative Layout +parent.title=Layouts +parent.link=layout-objects.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> + <ol> + <li><a href="#Position">Positioning Views</a></li> + <li><a href="#Example">Example</a></li> + </ol> + <h2>Key classes</h2> + <ol> + <li>{@link android.widget.RelativeLayout}</li> + <li>{@link android.widget.RelativeLayout.LayoutParams}</li> + </ol> +</div> +</div> + +<p>{@link android.widget.RelativeLayout} is a view group that displays child views in relative +positions. The position of each view can be specified as relative to sibling elements (such as to +the left-of or below another view) or in positions relative to the parent {@link +android.widget.RelativeLayout} area (such as aligned to the bottom, left of center).</p> + +<img src="{@docRoot}images/ui/relativelayout.png" alt="" /> + +<p>A {@link android.widget.RelativeLayout} is a very powerful utility for designing a user interface +because it can eliminate nested view groups and keep your layout hierarchy flat, which improves +performance. If you find yourself using several nested {@link android.widget.LinearLayout} groups, +you may be able to replace them with a single {@link android.widget.RelativeLayout}.</p> + + +<h2 id="Position">Positioning Views</h2> + +<p>{@link android.widget.RelativeLayout} lets child views specify their position relative to the +parent view or to each other (specified by ID). So you can align two elements by right border, or +make one below another, centered in the screen, centered left, and so on. By default, all child +views are drawn at the top-left of the layout, so you must define the position of each view +using the various layout properties available from {@link +android.widget.RelativeLayout.LayoutParams}.</p> + +<p>Some of the many layout properties available to views in a {@link android.widget.RelativeLayout} +include:</p> +<dl> + <dt><a +href="{docRoot}reference/android/widget/RelativeLayout.LayoutParams.html#attr_android:layout_alignParentTop" +>{@code android:layout_alignParentTop}</a></dt> + <dd>If {@code "true"}, makes the top edge of this view match the top edge of the parent. </dd> + <dt><a +href="{docRoot}reference/android/widget/RelativeLayout.LayoutParams.html#attr_android:layout_centerVertical" +>{@code android:layout_centerVertical}</a></dt> + <dd>If {@code "true"}, centers this child vertically within its parent.</dd> + <dt><a +href="{docRoot}reference/android/widget/RelativeLayout.LayoutParams.html#attr_android:layout_below" +>{@code android:layout_below}</a></dt> + <dd>Positions the top edge of this view below the view specified with a resource ID.</dd> + <dt><a +href="{docRoot}reference/android/widget/RelativeLayout.LayoutParams.html#attr_android:layout_toRightOf" +>{@code android:layout_toRightOf}</a></dt> + <dd>Positions the left edge of this view to the right of the view specified with a resource ID.</dd> +</dl> + +<p>These are just a few examples. All layout attributes are documented at {@link +android.widget.RelativeLayout.LayoutParams}.</p> + +<p>The value for each layout property is either a boolean to +enable a layout position relative to the parent {@link android.widget.RelativeLayout} or an ID that +references another view in the layout against which the view should be positioned.</p> + +<p>In your XML layout, dependencies against other views in the layout can be declared in any order. +For example, you can declare that "view1" be positioned below "view2" even if "view2" is the last +view declared in the hierarchy. The example below demonstrates such a scenario.</p> + + +<h2 id="Example">Example</h2> + +<p>Each of the attributes that control the relative position of each view are emphasized.</p> +<div class="figure" style="width:220px;margin-top:0"> +<img src="{@docRoot}images/ui/sample-relativelayout.png" alt="" /> +</div> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:paddingLeft="16dp" + android:paddingRight="16dp" > + <EditText + android:id="@+id/name" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:hint="@string/reminder" /> + <Spinner + android:id="@+id/dates" + android:layout_width="0dp" + android:layout_height="wrap_content" + <strong>android:layout_below="@id/name"</strong> + <strong>android:layout_alignParentLeft="true"</strong> + <strong>android:layout_toLeftOf="@+id/times"</strong> /> + <Spinner + android:id="@id/times" + android:layout_width="96dp" + android:layout_height="wrap_content" + <strong>android:layout_below="@id/name"</strong> + <strong>android:layout_alignParentRight="true"</strong> /> + <Button + android:layout_width="96dp" + android:layout_height="wrap_content" + <strong>android:layout_below="@id/times"</strong> + <strong>android:layout_alignParentRight="true"</strong> + android:text="@string/done" /> +</RelativeLayout> +</pre> + +<p>For details about all the layout attributes available to each child view of a {@link +android.widget.RelativeLayout}, see {@link android.widget.RelativeLayout.LayoutParams}.</p>
\ No newline at end of file diff --git a/docs/html/guide/topics/ui/layout/tabs.jd b/docs/html/guide/topics/ui/layout/tabs.jd new file mode 100644 index 0000000..62663de --- /dev/null +++ b/docs/html/guide/topics/ui/layout/tabs.jd @@ -0,0 +1,219 @@ +page.title=Tabbed +parent.title=Layouts +parent.link=layout-objects.html +@jd:body +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> + <ol> + <li><a href="#example">Example</a></li> + </ol> + <h2>Key classes</h2> + <ol> +<li>{@link android.widget.TabWidget}</li> +<li>{@link android.widget.TabHost}</li> +<li>{@link android.widget.TabHost.TabSpec}</li> +<li>{@link android.widget.FrameLayout}</li> + </ol> +</div> +</div> +<p>To create a tabbed UI, you need to use a {@link android.widget.TabHost} and a {@link +android.widget.TabWidget}. The {@link android.widget.TabHost} must be the root node for the layout, +which contains both the {@link android.widget.TabWidget} for displaying the tabs and a {@link +android.widget.FrameLayout} for displaying the tab content.</p> + +<img src="{@docRoot}images/ui/tabs.png" alt="" /> + +<p>You can implement your tab content in one of two ways: use the tabs to swap +{@link android.view.View}s within the same {@link android.app.Activity}, or use the tabs to change +between entirely separate activities. Which method you want for your application will depend on your +demands, but if each tab provides a distinct user activity, then it probably makes sense to use +a separate {@link android.app.Activity} for each tab, so that you can better manage the application +in discrete groups, rather than one massive application and layout.</p> +<h2 id="example">Example</h2> +<p>In this tutorial, you'll create a tabbed UI that uses a separate {@link +android.app.Activity} for each tab.</p> + +<ol> + <li>Start a new project named <em>HelloTabWidget</em>.</li> + <li>First, create three separate {@link android.app.Activity} classes in your project: +<code>ArtistsActivity</code>, <code>AlbumsActivity</code>, and <code>SongsActivity</code>. These +will each represent a separate tab. For now, make each one display a simple message using a {@link +android.widget.TextView}. For example: +<pre> +public class ArtistsActivity extends Activity { + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + + TextView textview = new TextView(this); + textview.setText("This is the Artists tab"); + setContentView(textview); + } +} +</pre> + <p>Notice that this doesn't use a layout file. Just create a {@link +android.widget.TextView}, give it some text and set that as the content. Duplicate this for +each of the three activities, and add the corresponding <code><activity/></code> tags to the Android Manifest file.</p> + + <li>You need an icon for each of your tabs. For each icon, you should create two versions: one +for when the tab is selected and one for when it is unselected. The +general design recommendation is for the selected icon to be a dark color (grey), and the +unselected icon to be a light color (white). (See the <a +href="{@docRoot}guide/practices/ui_guidelines/icon_design.html#tabstructure">Icon Design +Guidelines</a>.) For example: + <p> + <img src="images/ic_tab_artists_white.png" title="unselected tab icon" alt="" /> + <img src="images/ic_tab_artists_grey.png" title="selected tab icon" alt="" /> + </p> + <p>For this tutorial, you can copy these images and use them for all three tabs. (When you +create tabs in your own application, you should create customized tab icons.)</p> + <p>Now create a <a +href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">state-list drawable</a> +that specifies which image to use for each tab state:</p> + <ol> + <li>Save the icon images in your project <code>res/drawable/</code> directory.</li> + <li>Create a new XML file in <code>res/drawable/</code> +named <code>ic_tab_artists.xml</code> and insert the following: +<pre> +<?xml version="1.0" encoding="utf-8"?> +<selector xmlns:android="http://schemas.android.com/apk/res/android"> + <!-- When selected, use grey --> + <item android:drawable="@drawable/ic_tab_artists_grey" + android:state_selected="true" /> + <!-- When not selected, use white--> + <item android:drawable="@drawable/ic_tab_artists_white" /> +</selector> +</pre> + <p>This is a <a +href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">state-list drawable</a>, +which you will apply as the tab image. When the tab state changes, the tab icon will +automatically switch between the images defined here.</p> + </li> + </ol> + </li> + + <li>Open the <code>res/layout/main.xml</code> file and insert the following: + <pre> +<?xml version="1.0" encoding="utf-8"?> +<TabHost xmlns:android="http://schemas.android.com/apk/res/android" + android:id="@android:id/tabhost" + android:layout_width="fill_parent" + android:layout_height="fill_parent"> + <LinearLayout + android:orientation="vertical" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:padding="5dp"> + <TabWidget + android:id="@android:id/tabs" + android:layout_width="fill_parent" + android:layout_height="wrap_content" /> + <FrameLayout + android:id="@android:id/tabcontent" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:padding="5dp" /> + </LinearLayout> +</TabHost> +</pre> + <p>This is the layout that will display the tabs and provide navigation between each {@link + android.app.Activity} created above.</p> + <p>The {@link android.widget.TabHost} requires that a {@link android.widget.TabWidget} and a +{@link android.widget.FrameLayout} both live somewhere within it. To position the {@link +android.widget.TabWidget} and {@link android.widget.FrameLayout} vertically, a {@link +android.widget.LinearLayout} is used. The {@link android.widget.FrameLayout} is where the content +for each tab goes, which is empty now because the {@link android.widget.TabHost} will automatically +embed each {@link android.app.Activity} within it.</p> + <p>Notice that the {@link android.widget.TabWidget} and the {@link android.widget.FrameLayout} + elements have the IDs {@code tabs} and {@code tabcontent}, respectively. These names + must be used so that the {@link android.widget.TabHost} can retrieve references to each of + them. It expects exactly these names.</p> + </li> + + <li>Now open <code>HelloTabWidget.java</code> and make it extend {@link + android.app.TabActivity}:</p> +<pre> +public class HelloTabWidget extends TabActivity { +</pre> + </li> + <li>Use the following code for the {@link android.app.Activity#onCreate(Bundle) onCreate()} + method: +<pre> +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + + Resources res = getResources(); // Resource object to get Drawables + TabHost tabHost = getTabHost(); // The activity TabHost + TabHost.TabSpec spec; // Resusable TabSpec for each tab + Intent intent; // Reusable Intent for each tab + + // Create an Intent to launch an Activity for the tab (to be reused) + intent = new Intent().setClass(this, ArtistsActivity.class); + + // Initialize a TabSpec for each tab and add it to the TabHost + spec = tabHost.newTabSpec("artists").setIndicator("Artists", + res.getDrawable(R.drawable.ic_tab_artists)) + .setContent(intent); + tabHost.addTab(spec); + + // Do the same for the other tabs + intent = new Intent().setClass(this, AlbumsActivity.class); + spec = tabHost.newTabSpec("albums").setIndicator("Albums", + res.getDrawable(R.drawable.ic_tab_albums)) + .setContent(intent); + tabHost.addTab(spec); + + intent = new Intent().setClass(this, SongsActivity.class); + spec = tabHost.newTabSpec("songs").setIndicator("Songs", + res.getDrawable(R.drawable.ic_tab_songs)) + .setContent(intent); + tabHost.addTab(spec); + + tabHost.setCurrentTab(2); +} +</pre> + <p>This sets up each tab with their text and icon, and assigns each one an {@link +android.app.Activity}.</p> + <p>A reference to the {@link android.widget.TabHost} is first captured with {@link +android.app.TabActivity#getTabHost()}. Then, for +each tab, a {@link android.widget.TabHost.TabSpec} is created to define the tab properties. The +{@link android.widget.TabHost#newTabSpec(String)} method creates a new {@link +android.widget.TabHost.TabSpec} identified by the given string tag. For each +{@link android.widget.TabHost.TabSpec}, {@link +android.widget.TabHost.TabSpec#setIndicator(CharSequence,Drawable)} is called to set the text and +icon for the tab, and {@link android.widget.TabHost.TabSpec#setContent(Intent)} is called to specify +the {@link android.content.Intent} to open the appropriate {@link android.app.Activity}. Each +{@link android.widget.TabHost.TabSpec} is then added to the {@link android.widget.TabHost} by +calling {@link android.widget.TabHost#addTab(TabHost.TabSpec)}.</p> + + <p>At the very end, {@link + android.widget.TabHost#setCurrentTab(int)} opens the tab to be displayed by default, specified + by the index position of the tab.</p> + + <p>Notice that not once was the {@link android.widget.TabWidget} object referenced. This is + because a {@link android.widget.TabWidget} must always be a child of a {@link + android.widget.TabHost}, which is what you use for almost all interaction with the tabs. So when + a tab is added to the {@link android.widget.TabHost}, it's automatically added to the child + {@link android.widget.TabWidget}.</p> + </li> + + <li>Now open the Android Manifest file and add the <code>NoTitleBar</code> theme to the +<em>HelloTabWidget</em>'s + <code><activity></code> tag. This will remove the default application title from the top + of the layout, leaving more space for the tabs, which effectively operate as their own titles. + The <code><activity></code> tag should look like this: +<pre> +<activity android:name=".HelloTabWidget" android:label="@string/app_name" + android:theme="@android:style/Theme.NoTitleBar"> +</pre> + </li> + + <li>Run the application.</li> +</ol> + + +<p>Your application should look like this (though your icons may be different):</p> +<img src="images/hello-tabwidget.png" width="150px" /> + + diff --git a/docs/html/guide/topics/ui/menus.jd b/docs/html/guide/topics/ui/menus.jd index d51a378..01d373e 100644 --- a/docs/html/guide/topics/ui/menus.jd +++ b/docs/html/guide/topics/ui/menus.jd @@ -1040,7 +1040,7 @@ category. For example:</p> </pre> <p>Read more about writing intent filters in the -<a href="/guide/topics/intents/intents-filters.html">Intents and Intent Filters</a> document.</p> +<a href="/guide/components/intents-filters.html">Intents and Intent Filters</a> document.</p> <p>For a sample application using this technique, see the <a href="{@docRoot}resources/samples/NotePad/src/com/example/android/notepad/NoteEditor.html">Note diff --git a/docs/html/guide/topics/ui/notifiers/index.jd b/docs/html/guide/topics/ui/notifiers/index.jd index c61d4f0..caf0df7 100644 --- a/docs/html/guide/topics/ui/notifiers/index.jd +++ b/docs/html/guide/topics/ui/notifiers/index.jd @@ -21,7 +21,7 @@ the application should show a hovering progress wheel or bar.</li> <ul> <li>A <a href="#Toast">Toast Notification</a>, for brief messages that come from the background.</li> - <li>A <a href="#StatusBar">Status Bar Notification</a>, for persistent reminders + <li>A <a href="#StatusBar">Status Notification</a>, for persistent reminders that come from the background and request the user's response.</li> <li>A <a href="#Dialog">Dialog Notification</a>, for Activity-related notifications.</li> </ul> @@ -44,16 +44,16 @@ out, and does not accept interaction events. Because a toast can be created from when you're fairly certain the user is paying attention to the screen. A toast can not accept user interaction events; if you'd like the user to respond and take action, consider using a -<a href="#StatusBar">Status Bar Notification</a> instead.</p> +<a href="#StatusBar">Status Notification</a> instead.</p> <p>For more information, refer to <a href="toasts.html">Toast Notifications</a>.</p> -<h2 id="StatusBar">Status Bar Notification</h2> +<h2 id="StatusBar">Status Notification</h2> <img src="{@docRoot}images/notifications_window.png" alt="" style="float:right; clear:right;" /> -<p>A status bar notification adds an icon to the system's status bar +<p>A status notification adds an icon to the system's status bar (with an optional ticker-text message) and an expanded message in the "Notifications" window. When the user selects the expanded message, Android fires an {@link android.content.Intent} that is defined by the notification (usually to launch an @@ -68,7 +68,7 @@ while your Activity is still in focus, consider using a <a href="#Dialog">Dialog Notification</a> instead.</p> <p>For more information, refer to -<a href="notifications.html">Status Bar Notifications</a>.</p> +<a href="notifications.html">Status Notifications</a>.</p> <h2 id="Dialog">Dialog Notification</h2> diff --git a/docs/html/guide/topics/ui/notifiers/notifications.jd b/docs/html/guide/topics/ui/notifiers/notifications.jd index d104b4b..52092f9 100644 --- a/docs/html/guide/topics/ui/notifiers/notifications.jd +++ b/docs/html/guide/topics/ui/notifiers/notifications.jd @@ -1,4 +1,4 @@ -page.title=Status Bar Notifications +page.title=Status Notifications parent.title=Notifications parent.link=index.html @jd:body @@ -7,7 +7,7 @@ parent.link=index.html <div id="qv"> <h2>Quickview</h2> <ul> - <li>A status bar notification allows your application to notify the user of an event + <li>A status notification allows your application to notify the user of an event without interupting their current activity</li> <li>You can attach an intent to your notification that the system will initiate when the user clicks it</li> @@ -43,7 +43,7 @@ Design: Notifications</a></li> </div> </div> -<p>A status bar notification adds an icon to the system's status bar +<p>A status notification adds an icon to the system's status bar (with an optional ticker-text message) and a notification message in the notifications window. When the user selects the notification, Android fires an {@link android.content.Intent} that is defined by the {@link android.app.Notification} (usually to @@ -51,11 +51,11 @@ launch an {@link android.app.Activity}). You can also configure the notification to alert the user with a sound, a vibration, and flashing lights on the device.</p> -<p>A status bar notification should be used for any case in +<p>A status notification should be used for any case in which a background service needs to alert the user about an event that requires a response. A background service <strong>should never</strong> launch an activity on its own in order to receive user interaction. -The service should instead create a status bar notification that will launch the activity +The service should instead create a status notification that will launch the activity when selected by the user.</p> <p>Figure 1 shows the status bar with a notification icon on the left side.</p> @@ -78,9 +78,9 @@ href="{@docRoot}design/patterns/notifications.html">Notifications</a> guide.</p> <h2 id="Basics">The Basics</h2> -<p>An {@link android.app.Activity} or {@link android.app.Service} can initiate a status bar +<p>An {@link android.app.Activity} or {@link android.app.Service} can initiate a status notification. Because an activity can perform actions only while it is -running in the foreground and its window has focus, you will usually create status bar notifications +running in the foreground and its window has focus, you will usually create status notifications from a service. This way, the notification can be created from the background, while the user is using another application or @@ -88,9 +88,9 @@ while the device is asleep. To create a notification, you must use two classes: {@link android.app.Notification} and {@link android.app.NotificationManager}.</p> <p>Use an instance of the {@link android.app.Notification} class to define the properties of your -status bar notification, such as the status bar icon, the notification message, and extra settings +status notification, such as the status icon, the notification message, and extra settings such as a sound to play. The {@link android.app.NotificationManager} is an Android system service -that executes and manages all status bar notifications. You do not instantiate the +that executes and manages all status notifications. You do not instantiate the {@link android.app.NotificationManager} directly. In order to give it your {@link android.app.Notification}, you must retrieve a reference to the {@link android.app.NotificationManager} with @@ -98,7 +98,7 @@ to give it your {@link android.app.Notification}, you must retrieve a reference then, when you want to notify the user, pass it your {@link android.app.Notification} with {@link android.app.NotificationManager#notify(int,Notification) notify()}. </p> -<p>To create a status bar notification:</p> +<p>To create a status notification:</p> <ol> <li>Get a reference to the {@link android.app.NotificationManager}: <pre> @@ -277,7 +277,7 @@ String ns = Context.NOTIFICATION_SERVICE; NotificationManager mNotificationManager = (NotificationManager) getSystemService(ns); </pre> -<p>When you want to deliver your status bar notification, pass the {@link android.app.Notification} +<p>When you want to deliver your status notification, pass the {@link android.app.Notification} to the {@link android.app.NotificationManager} with {@link android.app.NotificationManager#notify(int,Notification)}. The first parameter is the unique ID for the notification and the second is the {@link @@ -287,7 +287,7 @@ application. The ID is necessary if you need to update the notification or (if your application manages different kinds of notifications) select the appropriate action when the user returns to your application via the intent defined in the notification.</p> -<p>To clear the status bar notification when the user selects it from the notifications +<p>To clear the status notification when the user selects it from the notifications window, add the "FLAG_AUTO_CANCEL" flag to your {@link android.app.Notification}. You can also clear it manually with {@link android.app.NotificationManager#cancel(int)}, passing it the notification ID, or clear all your notifications with {@link @@ -300,14 +300,14 @@ android.app.NotificationManager#cancelAll()}.</p> message that is displayed in the status bar and notifications window, and any other alert settings, such as sounds and blinking lights.</p> -<p>A status bar notification <em>requires</em> all of the following:</p> +<p>A status notification <em>requires</em> all of the following:</p> <ul> <li>An icon for the status bar</li> <li>A title and message, unless you define a <a href="#CustomExpandedView">custom notification layout</a></li> <li>A {@link android.app.PendingIntent}, to be fired when the notification is selected</li> </ul> -<p>Optional settings for the status bar notification include:</p> +<p>Optional settings for the status notification include:</p> <ul> <li>A ticker-text message for the status bar</li> <li>An alert sound</li> @@ -339,7 +339,7 @@ notification.setLatestEventInfo(context, contentTitle, contentText, contentInten <h3 id="Updating">Updating the notification</h3> -<p>You can update the information in your status bar notification as events +<p>You can update the information in your status notification as events continue to occur in your application. For example, when a new SMS text message arrives before previous messages have been read, the Messaging application updates the existing notification to display the total number of new messages received. @@ -484,7 +484,7 @@ following:</p> your notification is on-going.</dd> <dt>{@link android.app.Notification#number} field</dt> <dd>This value indicates the current number of events represented by the notification. - The appropriate number is overlaid on top of the status bar icon. + The appropriate number is overlaid on top of the status icon. If you intend to use this field, then you must start with "1" when the Notification is first created. (If you change the value from zero to anything greater during an update, the number is not shown.)</dd> diff --git a/docs/html/guide/topics/ui/overview.jd b/docs/html/guide/topics/ui/overview.jd new file mode 100644 index 0000000..41f7cc7 --- /dev/null +++ b/docs/html/guide/topics/ui/overview.jd @@ -0,0 +1,74 @@ +page.title=UI Overview +@jd:body + + +<p>All user interface elements in an Android app are built using {@link android.view.View} and +{@link android.view.ViewGroup} objects. A {@link android.view.View} is an object that draws +something on the screen that the user can interact with. A {@link android.view.ViewGroup} is an +object that holds other {@link android.view.View} (and {@link android.view.ViewGroup}) objects in +order to define the layout of the interface.</p> + +<p>Android provides a collection of both {@link android.view.View} and {@link +android.view.ViewGroup} subclasses that offer you common input controls (such as buttons and text +fields) and various layout models (such as a linear or relative layout).</p> + + +<h2 id="Layout">User Interface Layout</h2> + +<p>The user interface for each component of your app is defined using a hierarchy of {@link +android.view.View} and {@link android.view.ViewGroup} objects, as shown in figure 1. Each view group +is an invisible container that organizes child views, while the child views may be input +controls or other widgets that +draw some part of the UI. This hierarchy tree can be as simple or complex as you need +it to be (but simplicity is best for performance).</p> + +<img src="{@docRoot}images/viewgroup.png" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> Illustration of a view hierarchy, which defines a +UI layout.</p> + +<p>To declare your layout, you can instantiate {@link android.view.View} objects in code and start +building a tree, but the easiest and most effective way to define your layout is with an XML file. +XML offers a human-readable structure for the layout, similar to HTML.</p> + +<p>The name of an XML element for a view is respective to the Android class it represents. So a +<code><TextView></code> element creates a {@link android.widget.TextView} widget in your UI, +and a <code><LinearLayout></code> element creates a {@link android.widget.LinearLayout} view +group. </p> + +<p>For example, a simple vertical layout with a text view and a button looks like this:</p> +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:orientation="vertical" > + <TextView android:id="@+id/text" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="I am a TextView" /> + <Button android:id="@+id/button" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="I am a Button" /> +</LinearLayout> +</pre> + +<p>When you load a layout resource in your app, Android initializes each node of the layout into a +runtime object you can use to define additional behaviors, query the object state, or modify the +layout.</p> + +<p>For a complete guide to creating a UI layout, see <a href="declaring-layout.html">XML +Layouts</a>. + + +<h2 id="UIComponents">User Interface Components</h2> + +<p>You don't have to build all of your UI using {@link android.view.View} and {@link +android.view.ViewGroup} objects. Android provides several app components that offer +a standard UI layout for which you simply need to define the content. These UI components each +have a unique set of APIs that are described in their respective documents, such as <a +href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>, <a +href="{@docRoot}guide/topics/ui/dialogs.html">Dialogs</a>, and <a +href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Status Notifications</a>.</p> + + diff --git a/docs/html/guide/topics/ui/sharables/sample_images.zip b/docs/html/guide/topics/ui/sharables/sample_images.zip Binary files differnew file mode 100644 index 0000000..007a68a --- /dev/null +++ b/docs/html/guide/topics/ui/sharables/sample_images.zip diff --git a/docs/html/guide/topics/views/custom-views.jd b/docs/html/guide/topics/views/custom-views.jd deleted file mode 100644 index 8589b1a..0000000 --- a/docs/html/guide/topics/views/custom-views.jd +++ /dev/null @@ -1,544 +0,0 @@ -page.title=Building Custom Views -parent.title=Views and Layout -parent.link=index.html -@jd:body - -<p>Android offers a sophisticated and powerful componentized model for building your UI, based on the fundamental building block classes {@link android.view.View} and {@link android.view.ViewGroup}. To start with, the platform includes a variety of prebuilt View and ViewGroup subclasses — called widgets and layouts, respectively — that you can use to construct your UI. The widgets and layouts are fully implemented and handle all of their own measuring and drawing, so you can use them right away. You can make new types of UI elements simply by nesting and grouping the widgets and layouts. Using widgets and layouts is the recommended approach to building a UI for your applications.</p> - -<p>A partial list of available widgets includes {@link android.widget.Button Button}, -{@link android.widget.TextView TextView}, -{@link android.widget.EditText EditText}, -{@link android.widget.ListView ListView}, -{@link android.widget.CheckBox CheckBox}, -{@link android.widget.RadioButton RadioButton}, -{@link android.widget.Gallery Gallery}, -{@link android.widget.Spinner Spinner}, and the more special-purpose -{@link android.widget.AutoCompleteTextView AutoCompleteTextView}, -{@link android.widget.ImageSwitcher ImageSwitcher}, and -{@link android.widget.TextSwitcher TextSwitcher}. </p> - -<p>Among the layouts available are {@link android.widget.LinearLayout LinearLayout}, -{@link android.widget.FrameLayout FrameLayout}, {@link android.widget.AbsoluteLayout AbsoluteLayout}, and others. For more examples, see <a href="layout">Common Layout Objects</a>.</p> - -<p>If none of the prebuilt widgets or layouts meets your needs, you can also create your own View subclass, such as a layout group or compound control. If you only need to make small adjustments to an existing widget or layout, you can simply subclass the widget or layout and override its methods. -</p> - -<p>Creating your own View subclasses gives you precise control over the appearance and function of a screen element. To give an idea of the control you get with custom views, here are some examples of what you could do with them:</p> - -<ul> - <li> - You could create a completely custom-rendered View type, for example a "volume - control" knob rendered using 2D graphics, and which resembles an - analog electronic control. - </li> - <li> - You could combine a group of View components into a new single component, perhaps - to make something like a ComboBox (a combination of popup list and free - entry text field), a dual-pane selector control (a left and right pane - with a list in each where you can re-assign which item is in which - list), and so on. - </li> - <li> - You could override the way that an EditText component is rendered on the screen - (the <a href="{@docRoot}resources/samples/NotePad/">Notepad sample</a> uses this to good effect, - to create a lined-notepad page). - </li> - <li> - You could capture other events like key presses and handle them in some custom - way (such as for a game). - </li> -</ul> -<p> -The sections below explain how to create custom Views and use them in your application. -For detailed reference information, see the {@link android.view.View} class. </p> - -<p>This document covers the following:</p> -<ol class="toc"> - <li><a href="#basic">The Basic Approach</a></li> - <li><a href="#custom">Fully Customized Views</a></li> - <li><a href="#customexample">Customized View Example</a></li> - <li><a href="#compound">Compound Controls</a></li> - <li><a href="#tweaking">Modifying an Existing Component Type</a></li> -</ol> - -<a name="basic"></a> -<h2>The Basic Approach -</h2> -<p> -These steps provide a high level overview of -what you need to know to get started in creating your own -View components:</p> - -<ol> - <li> - Extend an existing {@link android.view.View View} class or subclass - with your own class. - </li> - <li> - Override some of the methods from the superclass: the superclass methods - to override start with '<code>on</code>', for - example, {@link android.view.View#onDraw onDraw()}, - {@link android.view.View#onMeasure onMeasure()}, and - {@link android.view.View#onKeyDown onKeyDown()}. - <ul> - <li> - This is similar to the <code>on...</code> events in {@link android.app.Activity - Activity} or {@link android.app.ListActivity ListActivity} - that you override for life cycle and other functionality hooks. - </li> - </ul> - <li> - Use your new extension class: once completed, your new extension class - can be used in place of the view upon which it was based, but now with the new - functionality. - </li> -</ol> -<p class="note"><strong>Tip:</strong> - Extension classes can be defined as inner classes inside the activities - that use them. This is useful because it controls access to them but - isn't necessary (perhaps you want to create a new public View for - wider use in your application). -</p> - -<a name="custom"></a> -<h2>Fully Customized Components</h2> -<p> -Fully customized components can be used to create graphical components that -appear however you wish. Perhaps a graphical VU -meter that looks like an old analog gauge, or a sing-a-long text view where -a bouncing ball moves along the words so you can sing along with a karaoke -machine. Either way, you want something that the built-in components just -won't do, no matter how you combine them.</p> -<p>Fortunately, you can easily create components that look and behave in any -way you like, limited perhaps only by your imagination, the size of the -screen, and the available processing power (remember that ultimately your -application might have to run on something with significantly less power -than your desktop workstation).</p> -<p>To create a fully customized component:</p> -<ol> - <li> - The most generic view you can extend is, unsurprisingly, {@link - android.view.View View}, so you will usually start by extending this to - create your new super component. - </li> - <li> - You can supply a constructor which can - take attributes and parameters from the XML, and you can also consume - your own such attributes and parameters (perhaps the color and range of - the VU meter, or the width and damping of the needle, etc.) - </li> - <li> - You will probably want to create your own event listeners, - property accessors and modifiers, and possibly more sophisticated - behavior in your component class as well. - </li> - <li> - You will almost certainly want to override <code>onMeasure()</code> and - are also likely to need to override <code>onDraw()</code> if you want - the component to show something. While both have default behavior, - the default <code>onDraw()</code> will do nothing, and the default - <code>onMeasure()</code> will always set a size of 100x100 — which is - probably not what you want. - </li> - <li> - Other <code>on...</code> methods may also be overridden as required. - </li> -</ol> -<h4><code>onDraw()</code> and <code>onMeasure()</code></h4> -<p><code>onDraw()</code> delivers you a {@link android.graphics.Canvas Canvas} -upon which you can implement anything you want: 2D graphics, other standard or -custom components, styled text, or anything else you can think of.</p> -<p><em>Note:</em> -Except for 3D graphics. If you want to -use 3D graphics, you must extend {@link android.view.SurfaceView SurfaceView} -instead of View, and draw from a separate thread. See the -GLSurfaceViewActivity sample -for details.</p> -<p><code>onMeasure()</code> is a little more involved. <code>onMeasure()</code> -is a critical piece of the rendering contract between your component and its -container. <code>onMeasure()</code> should be overridden to efficiently and -accurately report the measurements of its contained parts. This is made -slightly more complex by the requirements of limits from the parent -(which are passed in to the <code>onMeasure()</code> method) and by the -requirement to call the <code>setMeasuredDimension()</code> method with the -measured width and height once they have been calculated. If you fail to -call this method from an overridden <code>onMeasure()</code> method, the -result will be an exception at measurement time.</p> -<p>At a high level, implementing <code>onMeasure()</code> looks something - like this:</p> - -<ol> - <li> - The overridden <code>onMeasure()</code> method is called with width and - height measure specifications (<code>widthMeasureSpec</code> and - <code>heightMeasureSpec</code> parameters, both are integer codes - representing dimensions) which should be treated as requirements for - the restrictions on the width and height measurements you should produce. A - full reference to the kind of restrictions these specifications can require - can be found in the reference documentation under {@link - android.view.View#onMeasure View.onMeasure(int, int)} (this reference - documentation does a pretty good job of explaining the whole measurement - operation as well). - </li> - <li> - Your component's <code>onMeasure()</code> method should calculate a - measurement width and height which will be required to render the - component. It should try to stay within the specifications passed in, - although it can choose to exceed them (in this case, the parent can - choose what to do, including clipping, scrolling, throwing an exception, - or asking the <code>onMeasure()</code> to try again, perhaps with - different measurement specifications). - </li> - <li> - Once the width and height are calculated, the <code>setMeasuredDimension(int - width, int height)</code> method must be called with the calculated - measurements. Failure to do this will result in an exception being - thrown. - </li> -</ol> - -<p> -Here's a summary of some of the other standard methods that the framework calls on views: -</p> -<table border="2" width="85%" align="center" cellpadding="5"> - <thead> - <tr><th>Category</th> <th>Methods</th> <th>Description</th></tr> - </thead> - - <tbody> - <tr> - <td rowspan="2">Creation</td> - <td>Constructors</td> - <td>There is a form of the constructor that are called when the view - is created from code and a form that is called when the view is - inflated from a layout file. The second form should parse and apply - any attributes defined in the layout file. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onFinishInflate()}</code></td> - <td>Called after a view and all of its children has been inflated - from XML.</td> - </tr> - - <tr> - <td rowspan="3">Layout</td> - <td><code>{@link android.view.View#onMeasure}</code></td> - <td>Called to determine the size requirements for this view and all - of its children. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onLayout}</code></td> - <td>Called when this view should assign a size and position to all - of its children. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onSizeChanged}</code></td> - <td>Called when the size of this view has changed. - </td> - </tr> - - <tr> - <td>Drawing</td> - <td><code>{@link android.view.View#onDraw}</code></td> - <td>Called when the view should render its content. - </td> - </tr> - - <tr> - <td rowspan="4">Event processing</td> - <td><code>{@link android.view.View#onKeyDown}</code></td> - <td>Called when a new key event occurs. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onKeyUp}</code></td> - <td>Called when a key up event occurs. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onTrackballEvent}</code></td> - <td>Called when a trackball motion event occurs. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onTouchEvent}</code></td> - <td>Called when a touch screen motion event occurs. - </td> - </tr> - - <tr> - <td rowspan="2">Focus</td> - <td><code>{@link android.view.View#onFocusChanged}</code></td> - <td>Called when the view gains or loses focus. - </td> - </tr> - - <tr> - <td><code>{@link android.view.View#onWindowFocusChanged}</code></td> - <td>Called when the window containing the view gains or loses focus. - </td> - </tr> - - <tr> - <td rowspan="3">Attaching</td> - <td><code>{@link android.view.View#onAttachedToWindow()}</code></td> - <td>Called when the view is attached to a window. - </td> - </tr> - - <tr> - <td><code>{@link android.view.View#onDetachedFromWindow}</code></td> - <td>Called when the view is detached from its window. - </td> - </tr> - - <tr> - <td><code>{@link android.view.View#onWindowVisibilityChanged}</code></td> - <td>Called when the visibility of the window containing the view - has changed. - </td> - </tr> - </tbody> - - </table> - - -<a name="customexample"></a> -<h3>A Custom View Example</h3> -<p>The CustomView sample in the -<a href="{@docRoot}samples/ApiDemos/index.html">API Demos</a> provides an example -of a customized View. The custom View is defined in the -<a href="{@docRoot}samples/ApiDemos/src/com/example/android/apis/view/LabelView.html">LabelView</a> -class.</p> -<p>The LabelView sample demonstrates a number of different aspects of custom components:</p> -<ul> - <li>Extending the View class for a completely custom component.</li> - <li>Parameterized constructor that takes the view inflation parameters - (parameters defined in the XML). Some of these are passed through to the - View superclass, but more importantly, there are some custom attributes defined - and used for LabelView.</li> - <li>Standard public methods of the type you would expect to see for a label - component, for example <code>setText()</code>, <code>setTextSize()</code>, - <code>setTextColor()</code> and so on.</li> - <li>An overridden <code>onMeasure</code> method to determine and set the - rendering size of the component. (Note that in LabelView, the real work is done - by a private <code>measureWidth()</code> method.)</li> - <li>An overridden <code>onDraw()</code> method to draw the label onto the - provided canvas.</li> -</ul> -<p>You can see some sample usages of the LabelView custom View in -<a href="{@docRoot}samples/ApiDemos/res/layout/custom_view_1.html">custom_view_1.xml</a> -from the samples. In particular, you can see a mix of both <code>android:</code> -namespace parameters and custom <code>app:</code> namespace parameters. These -<code>app:</code> parameters are the custom ones that the LabelView recognizes -and works with, and are defined in a styleable inner class inside of the -samples R resources definition class.</p> - -<a name="compound"></a> -<h2>Compound Controls -</h2> -<p>If you don't want to create a completely customized component, but instead -are looking to put together a reusable component that consists of a group of -existing controls, then creating a Compound Component (or Compound Control) might -fit the bill. In a nutshell, this brings together a number of more atomic -controls (or views) into a logical group of items that can be treated as a -single thing. For example, a Combo Box can be thought of as a -combination of a single line EditText field and an adjacent button with an attached - PopupList. If you press the button and select -something from the list, it populates the EditText field, but the user can -also type something directly into the EditText if they prefer.</p> -<p>In Android, there are actually two other Views readily available to do -this: {@link android.widget.Spinner Spinner} and -{@link android.widget.AutoCompleteTextView AutoCompleteTextView}, but -regardless, the concept of a Combo Box makes an easy-to-understand -example.</p> -<p>To create a compound component:</p> -<ol> - <li> - The usual starting point is a Layout of some kind, so create a class - that extends a Layout. Perhaps in the case of a Combo box we might use - a LinearLayout with horizontal orientation. Remember that other layouts - can be nested inside, so the compound component can be arbitrarily - complex and structured. Note that just like with an Activity, you can - use either the declarative (XML-based) approach to creating the - contained components, or you can nest them programmatically from your - code. - </li> - <li> - In the constructor for the new class, take whatever parameters the - superclass expects, and pass them through to the superclass constructor - first. Then you can set up the other views to use within your new - component; this is where you would create the EditText field and the - PopupList. Note that you also might introduce your own attributes and - parameters into the XML that can be pulled out and used by your - constructor. - </li> - <li> - You can also create listeners for events that your contained views might - generate, for example, a listener method for the List Item Click Listener - to update the contents of the EditText if a list selection is made. - </li> - <li> - You might also create your own properties with accessors and modifiers, - for example, allow the EditText value to be set initially in the - component and query for its contents when needed. - </li> - <li> - In the case of extending a Layout, you don't need to override the - <code>onDraw()</code> and <code>onMeasure()</code> methods since the - layout will have default behavior that will likely work just fine. However, - you can still override them if you need to. - </li> - <li> - You might override other <code>on...</code> methods, like - <code>onKeyDown()</code>, to perhaps choose certain default values from - the popup list of a combo box when a certain key is pressed. - </li> -</ol> -<p> - To summarize, the use of a Layout as the basis for a Custom Control has a -number of advantages, including:</p> - -<ul> - <li> - You can specify the layout using the declarative XML files just like - with an activity screen, or you can create views programmatically and - nest them into the layout from your code. - </li> - <li> - The <code>onDraw()</code> and <code>onMeasure()</code> methods (plus - most of the other <code>on...</code> methods) will likely have suitable behavior so - you don't have to override them. - </li> - <li> - In the end, you can very quickly construct arbitrarily complex compound - views and re-use them as if they were a single component. - </li> -</ul> -<h4>Examples of Compound Controls</h4> -<p>In the API Demos project - that comes with the SDK, there are two List - examples — Example 4 and Example 6 under Views/Lists demonstrate a - SpeechView which extends LinearLayout to make a component for displaying - Speech quotes. The corresponding classes in the sample code are - <code>List4.java</code> and <code>List6.java</code>.</p> - -<a name="tweaking"></a> -<h2>Modifying an Existing View Type -</h2> -<p>There is an even easier option for creating a custom View which is -useful in certain circumstances. If there is a component that is already very -similar to what you want, you can simply extend that component and just -override the behavior that you want to change. You can do all of the things -you would do with a fully customized component, but by starting with a more -specialized class in the View hierarchy, you can also get a lot of behavior for -free that probably does exactly what you want.</p> -<p>For example, the SDK includes a <a -href="{@docRoot}samples/NotePad/index.html">NotePad application</a> in the -samples. This demonstrates many aspects of using the Android platform, among -them is extending an EditText View to make a lined notepad. This is not a -perfect example, and the APIs for doing this might change from this early -preview, but it does demonstrate the principles.</p> -<p>If you haven't done so already, import the -NotePad sample into Eclipse (or -just look at the source using the link provided). In particular look at the definition of -<code>MyEditText</code> in the <a -href="{@docRoot}samples/NotePad/src/com/example/android/notepad/NoteEditor.html">NoteEditor.java</a> -file.</p> -<p>Some points to note here</p> -<ol> - <li> - <strong>The Definition</strong> - <p>The class is defined with the following line:</p> - <code>public static class MyEditText extends EditText</code><br><br> - - <ul> - <li> - It is defined as an inner class within the <code>NoteEditor</code> - activity, but it is public so that it could be accessed as - <code>NoteEditor.MyEditText</code> from outside of the <code>NoteEditor</code> - class if desired. - </li> - <li> - It is <code>static</code>, meaning it does not generate the so-called - "synthetic methods" that allow it to access data from the parent - class, which in turn means that it really behaves as a separate - class rather than something strongly related to <code>NoteEditor</code>. - This is a cleaner way to create inner classes if they do not need - access to state from the outer class, keeps the generated class - small, and allows it to be used easily from other classes. - </li> - <li> - It extends <code>EditText</code>, which is the View we have chosen to - customize in this case. When we are finished, the new class will be - able to substitute for a normal <code>EditText</code> view.<br> - <br> - </li> - </ul> - </li> - <li> - <strong>Class Initialization</strong> - <p>As always, the super is called first. Furthermore, - this is not a default constructor, but a parameterized one. The - EditText is created with these parameters when it is inflated from an - XML layout file, thus, our constructor needs to both take them and pass them - to the superclass constructor as well.</p> - </li> - <li> - <strong>Overridden Methods</strong> - <p>In this example, there is only one method to be overridden: - <code>onDraw()</code> — but there could easily be others needed when you - create your own custom components.</p> - <p>For the NotePad sample, overriding the <code>onDraw()</code> method allows - us to paint the blue lines on the <code>EditText</code> view canvas (the - canvas is passed into the overridden <code>onDraw()</code> method). The - super.onDraw() method is called before the method ends. The - superclass method should be invoked, but in this case, we do it at the - end after we have painted the lines we want to include.</p> - <li> - <strong>Use the Custom Component</strong> - <p>We now have our custom component, but how can we use it? In the - NotePad example, the custom component is used directly from the - declarative layout, so take a look at <code>note_editor.xml</code> in the - <code>res/layout</code> folder.</p> - <pre> -<view xmlns:android="http://schemas.android.com/apk/res/android" - class="com.android.notepad.NoteEditor$MyEditText" - id="@+id/note" - android:layout_width="fill_parent" - android:layout_height="fill_parent" - android:background="@android:drawable/empty" - android:padding="10dip" - android:scrollbars="vertical" - android:fadingEdge="vertical" /> </pre> - - <ul> - <li> - The custom component is created as a generic view in the XML, and - the class is specified using the full package. Note also that the - inner class we defined is referenced using the - <code>NoteEditor$MyEditText</code> notation which is a standard way to - refer to inner classes in the Java programming language. - </li> - <li> - The other attributes and parameters in the definition are the ones - passed into the custom component constructor, and then passed - through to the EditText constructor, so they are the same - parameters that you would use for an EditText view. Note that it is - possible to add your own parameters as well, and we will touch on - this again below. - </li> - </ul> - </li> -</ol> -<p>And that's all there is to it. Admittedly this is a simple case, but -that's the point — creating custom components is only as complicated as you -need it to be.</p> -<p>A more sophisticated component may override even more <code>on...</code> methods and -introduce some of its own helper methods, substantially customizing its properties and -behavior. The only limit is your imagination and what you need the component to -do.</p> - diff --git a/docs/html/guide/topics/views/intro.jd b/docs/html/guide/topics/views/intro.jd deleted file mode 100644 index f49f547..0000000 --- a/docs/html/guide/topics/views/intro.jd +++ /dev/null @@ -1,49 +0,0 @@ -page.title=Introduction to Views -parent.title=Views and Layout -parent.link=index.html -@jd:body - -<p>The basic functional unit of an Android application is the <em>activity</em> — an object of the class {@link android.app.Activity android.app.Activity}. An activity can do many things, but by itself it does not have a presence on the screen. To give your activity a screen presence and design its UI, you work with <em>views</em> and <em>viewgroups</em> -- basic units of user interface expression on the Android platform.</p> - -<h2>Views</h2> -<p>A view is an object of base class {@link android.view.View android.view.View}. It's a data structure whose properties store the layout and content for a specific rectangular area of the screen. A View object handles measuring and layout, drawing, focus change, scrolling, and key/gestures for the screen area it represents. </p> -<p>The View class serves as a base class for <em>widgets </em> — a set of fully implemented subclasses that draw interactive screen elements. Widgets handle their own measuring and drawing, so you can use them to build your UI more quickly. The list of widgets available includes Text, EditText, InputMethod, MovementMethod, Button, RadioButton, Checkbox, and ScrollView.</p> - -<h2>Viewgroups </h2> - -<p>A viewgroup is an object of class {@link android.view.ViewGroup android.view.Viewgroup}. As its name indicates, a viewgroup is a special type of view object whose function is to contain and manage a subordinate set of views and other viewgroups, Viewgroups let you add structure to your UI and build up complex screen elements that can be addressed as a single entity. </p> - -<p>The Viewgroup class serves as a base class for <em>layouts</em> — a set of fully implemented subclasses that provide common types of screen layout. The layouts give you a way to build a structure for a set of views. </p> - -<h2>A Tree-Structured UI</h2> - -<p>On the Android platform, you define an Activity's UI using a tree of view and viewgroup nodes, as shown in the diagram below. The tree can be as simple or complex as you need to make it, and you can build it up using Android's set of predefined widgets and layouts or custom view types that you create yourself. </p> - -<img src={@docRoot}images/viewgroup.png alt="An example of a tree of views and viewgroups" width="312" height="211" align="center"/> - -<p>To attach the tree to the screen for rendering, your Activity calls its setContentView() method and passes a reference to the root node object. Once the Android system has the reference to the root node object, it can work directly with the node to invalidate, measure, and draw the tree. When your Activity becomes active and receives focus, the system notifies your activity and requests the root node to measure and draw the tree. The root node then requests that its child nodes draw themselves — in turn, each viewgroup node in the tree is responsible for drawing its direct children. </p> - -<p>As mentioned previously, each view group has the responsibility of - measuring its available space, laying out its children, and calling Draw() on - each child to let it render itself. The children may request a size and location - in the parent, but the parent object has the final decision on where how big - each child can be.</p> - -<h2>LayoutParams: How a Child Specifies Its Position and Size</h2> - -<p>Every viewgroup class uses a nested class that extends {@link -android.view.ViewGroup.LayoutParams ViewGroup.LayoutParams}. This subclass - contains property types that define a child's size and position, in properties - appropriate for that view group class. </p> - -<img src={@docRoot}images/layoutparams.png alt="An example of layoutparams" width="632" height="369" align="center"/> - -<p>Note that every LayoutParams subclass has its own syntax for setting -values. Each child element must define LayoutParams that are appropriate for its parent, although it may define different LayoutParams for its children. </p> - -<p>All viewgroups include width and height. Many also include margins and -borders. You can specify width and height exactly, though you probably won't want -to do this often. More often you will tell your view to size itself either to -the dimensions of its content, or to become as big as its containing object -will allow.</p> - diff --git a/docs/html/guide/topics/views/ui-xml.jd b/docs/html/guide/topics/views/ui-xml.jd deleted file mode 100644 index bcfa562..0000000 --- a/docs/html/guide/topics/views/ui-xml.jd +++ /dev/null @@ -1,138 +0,0 @@ -page.title=Declaring a UI in XML -parent.title=Views and Layout -parent.link=index.html -@jd:body - -<p>You can create your application's user interface in two ways: -<ul> -<li>You can declare UI elements statically, in XML. Android provides a straightforward XML vocabulary that corresponds to the View classes and subclasses, such as those for widgets and layouts. </li> -<li>You can instantiate screen elements dynamically, at runtime, through code in your application. Your application can refer to or create View or other class objects and manipulate their properties programmatically. </li> -</ul> - -<p>One advantage of declaring your UI in XML is that it enables you to better separate the presentation of your application from the code that controls it's behavior. Your UI description is external to your application code, which means that you can modify or adapt it without having to modify your source code and recompile. For example, you can create XML layouts for different screen orientations and for a variety of device screen sizes or languages. Additionally, declaring in XML makes it easier to see the elements and structure of your UI, so it's easier to debug problems. </p> - -<p>The Android framework gives you the flexibility to use either or both of these ways of declaring and managing your application's UI. For example, you could declare your application's default layouts in XML, including the screen elements that will appear in them and their properties. You could then add code in your application that would modify the state of the screen objects, including those declared in XML, at run time. </p> - -<p>You build your application's UI in approximately the same way, whether you are declaring it in XML or programmatically. In both cases, your UI will be a tree structure that may include multiple View or Viewgroup subclasses. <p> - -<p>In general, the XML vocabulary for declaring UI elements closely follows the structure and naming of the framework's UI-related classes and methods, where element names correspond to class names and attribute names correspond to methods. In fact, the correspondence is often so direct that you can guess what XML attribute corresponds to a class method, or guess what class corresponds to a given xml element. </p> - -<p>However, note that the XML vocabulary for defining UI is not entirely identical to the framework's classes and methods. In some cases, there are slight naming differences. For -example, the EditText element has a <code>text</code> attribute that corresponds to -EditText.setText. </p> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<p>For your convenience, the API reference documentation for UI related classes -lists the available XML attributes that correspond to the class methods, including inherited -attributes.</p> - -<p>To learn more about the available XML elements and attributes, as well as the format of the XML file, see <a -href="{@docRoot}reference/available-resources.html#layoutresources">Layout Resources</a>.</p> -</div> -</div> - -<p>Using Android's XML vocabulary, you can quickly design UI layouts and the screen elements they contain, in the same way you create HTML files — as a series of nested tags. </p> - -<p>Each layout file must contain exactly one root element, and the root element must be a View or ViewGroup object. Once you've defined the root element, you can add additional layout objects or controls as child elements of the root element, if needed. In the example below, the tree of XML elements evaluates to the outermost LinearLayout object. - -<p>After you've declared your layout in XML, you must save the file, with the <code>.xml</code> extension, in the proper location, so that it will be compiled correctly. The proper location for storing layout files is in your application's <code>res/layout/</code> directory. </p> - -<p>When you compile your application, each XML layout file is compiled into an -android.view.View resource. You can then load the layout resource from your application code, by calling <code>setContentView(R.layout.<em>layout_file_name</em>)</code> in your {@link android.app.Activity#onCreate(android.os.Bundle) Activity.onCreate()} -implementation.</p> - -<p>When you load a layout resource, the Android system initializes run-time objects corresponding to the elements in your layout. It parses the elements of your layout in-order (depth-first), instantiating the Views and adding them to their parent(s). </p> - -<p>Attributes named <code>layout_<em>something</em></code> apply to that -object's LayoutParams member. <a href="{@docRoot}reference/available-resources.html#layoutresources">Layout -Resources</a> also describes how to learn the syntax for specifying -LayoutParams properties. </p> - -<p>Also note that Android draws elements in the order in which they -appear in the XML. Therefore, if elements overlap, the last one in the XML -file will probably be drawn on top of any previously listed elements in that -same space.</p> - -<p>The following values are supported for dimensions (described in {@link -android.util.TypedValue TypedValue}):</p> - -<ul> - <li>px (pixels) </li> - <li>dip (device independent pixels) </li> - <li>sp (scaled pixels — best for text size) </li> - <li>pt (points) </li> - <li>in (inches) </li> - <li>mm (millimeters) </li> -</ul> - -<p>Example: <code>android:layout_width="25px"</code> </p> - -<p>For more information about these dimensions, see <a href="{@docRoot}reference/available-resources.html#dimension">Dimension Values</a>.</p> - -<p>The example below shows an XML file and the resulting screen in the UI. Note that the text on the -top of the screen was set by calling {@link -android.app.Activity#setTitle(java.lang.CharSequence) Activity.setTitle}. Note -that the attributes that refer to relative elements (i.e., layout_toLeft) -refer to the ID using the syntax of a relative resource -(@id/<em>id_number</em>). </p> - -<table border="1"> - <tr> - <td> - <pre><?xml version="1.0" encoding="utf-8"?> -<!-- Demonstrates using a relative layout to create a form --> -<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android - android:layout_width="fill_parent" - android:layout_height="wrap_content" - android:background="@drawable/blue" - android:padding="10px"> - - <TextView id="@+id/label" - android:layout_width="fill_parent" - android:layout_height="wrap_content" - android:text="Type here:"/> - - <EditText id="@+id/entry" - android:layout_width="fill_parent" - android:layout_height="wrap_content" - android:background="@android:drawable/editbox_background" - android:layout_below="@id/label"/> - - <Button id="@+id/ok" - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:layout_below="@id/entry" - android:layout_alignParentRight="true" - android:layout_marginLeft="10px" - android:text="OK" /> - - <Button android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:layout_toLeftOf="@id/ok" - android:layout_alignTop="@id/ok" - android:text="Cancel" /> -</RelativeLayout></pre></td> - <td><img src="{@docRoot}images/designing_ui_layout_example.png" alt="Screen shot showing how this layout XML file is rendered." /></td> - </tr> -</table> - -<h3>Loading the XML Resource </h3> - -<p>Loading the compiled layout resource is very easy, and done with a single -call in the activity's onCreate() method, as shown here:</p> - -<pre> -protected void onCreate(Bundle savedValues) -{ - // Be sure to call the super class. - super.onCreate(savedValues); - - // Load the compiled layout resource into the window's - // default ViewGroup. - // The source file is res/layout/hello_activity.xml - setContentView(R.layout.hello_activity); - - // Retrieve any important stored values. - restoreValues(savedValues); -} </pre> diff --git a/docs/html/guide/topics/wireless/index.jd b/docs/html/guide/topics/wireless/index.jd deleted file mode 100644 index 23d2f0f..0000000 --- a/docs/html/guide/topics/wireless/index.jd +++ /dev/null @@ -1,23 +0,0 @@ -page.title=Wireless Controls -@jd:body - -Go away. - -<!-- -<h2>Wi-Fi</h2> -<p>The Wi-Fi APIs provide a means by which application can communicate with the lower-level -wireless stack that provides Wi-Fi network access. Almost all information from the device supplicant -is available, including the connected network's link speed, IP address, negotiation state, and more. -It also provides information about all non-connected available networks. Some of the available network -interactions include the ability to scan, add, dave, terminate and initiate connections.</p> - - -<h2>Bluetooth</h2> -<p>The Android platform includes support for the Bluetooth network stack, which allows a device to -wirelessly exchange data with other Bluetooth devices. The application framework provides access to -the Bluetooth functionality through the Android Bluetooth APIs. These APIs let applications -wirelessly connect to other Bluetooth devices, enabling point-to-point and multipoint wireless -features.</p> ---> - - diff --git a/docs/html/guide/topics/wireless/wifi.jd b/docs/html/guide/topics/wireless/wifi.jd deleted file mode 100644 index 761e463..0000000 --- a/docs/html/guide/topics/wireless/wifi.jd +++ /dev/null @@ -1,18 +0,0 @@ -page.title=Wi-Fi -parent.title=Wireless Controls -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>In this document</h2> - <ol> - - </ol> - -</div> -</div> - - -Go away.
\ No newline at end of file |
