1page.title=Android 4.0 Platform 2sdk.platform.version=4.0 3sdk.platform.apiLevel=14 4@jd:body 5 6<div id="qv-wrapper"> 7<div id="qv"> 8 9<h2>In this document</h2> 10<ol> 11 <li><a href="#relnotes">Revisions</a></li> 12 <li><a href="#api">API Overview</a></li> 13 <li><a href="#Honeycomb">Previous APIs</a></li> 14 <li><a href="#api-level">API Level</a></li> 15 <li><a href="#apps">Built-in Applications</a></li> 16 <li><a href="#locs">Locales</a></li> 17 <li><a href="#skins">Emulator Skins</a></li> 18</ol> 19 20<h2>Reference</h2> 21<ol> 22<li><a 23href="{@docRoot}sdk/api_diff/14/changes.html">API 24Differences Report »</a> </li> 25</ol> 26 27</div> 28</div> 29 30 31<p><em>API Level:</em> <strong>{@sdkPlatformApiLevel}</strong></p> 32 33<p>Android 4.0 is a major platform release that adds a variety of new features for users and app 34developers. Besides all the new features and APIs discussed below, Android 4.0 is an important 35platform release because it brings the extensive set of APIs and Holographic themes from Android 3.x 36to smaller screens. As an app developer, you now have a single platform and unified API framework 37that enables you to develop and publish your application with a single APK that provides an 38optimized user experience for handsets, tablets, and more, when running the same version of 39Android—Android 4.0 (API level 14) or greater. </p> 40 41<p>The Android {@sdkPlatformVersion} platform is available as a 42downloadable component for the Android SDK so you can begin developing and testing your 43applications on Android 4.0 with the Android emulator. The downloadable platform includes 44an Android library and system image, as well as a set of emulator skins and 45more. The downloadable platform does not include any external libraries.</p> 46 47<p>To start developing or testing against Android {@sdkPlatformVersion}, 48use the Android SDK Manager to download the platform into your SDK. For more 49information, see <a href="{@docRoot}sdk/adding-components.html">Adding SDK 50Components</a>. If you are new to Android, <a 51href="{@docRoot}sdk/index.html">download the SDK Starter Package</a> first.</p> 52 53<p class="note"><strong>Reminder:</strong> If you've already published an 54Android application, please test your application on Android {@sdkPlatformVersion} as 55soon as possible to be sure your application provides the best 56experience possible on the latest Android-powered devices.</p> 57 58<p>For a high-level overview of the new user and developer features in Android 4.0, see the 59<a href="http://developer.android.com/sdk/android-4.0-highlights.html">Platform Highlights</a>.</p> 60 61 62 63<h2 id="relnotes">Revisions</h2> 64 65<p>To determine what revision of the Android {@sdkPlatformVersion} platform you 66have installed, refer to the "Installed Packages" listing in the Android SDK Manager.</p> 67 68 69<div class="toggle-content opened" style="padding-left:1em;"> 70 71 <p><a href="#" onclick="return toggleContent(this)"> 72 <img src="{@docRoot}assets/images/triangle-opened.png" 73class="toggle-content-img" alt="" /> 74 Android {@sdkPlatformVersion}, Revision 1</a> <em>(October 2011)</em> 75 </a></p> 76 77 <div class="toggle-content-toggleme" style="padding-left:2em;"> 78 79<dl> 80<dt>Initial release. SDK Tools r14 or higher is required. 81 <p class="caution"><strong>Important:</strong> To download the new Android 82 4.0 system components from the Android SDK Manager, you must first update the 83 SDK tools to revision 14 or later and restart the Android SDK Manager. If you do not, 84 the Android 4.0 system components will not be available for download.</p> 85</dt> 86</dl> 87 88 </div> 89</div> 90 91 92<h2 id="api">API Overview</h2> 93 94<p>The sections below provide a technical overview of new APIs in Android 4.0.</p> 95 96<div class="toggle-content closed" style="padding-left:1em;"> 97 98 <p><a href="#" onclick="return toggleContent(this)"> 99 <img src="{@docRoot}assets/images/triangle-closed.png" 100class="toggle-content-img" alt="" /> 101 <strong>Table of Contents</strong> 102 </a></p> 103 104 <div class="toggle-content-toggleme" style="padding-left:2em;"> 105 <ol class="toc" style="margin-left:-1em"> 106 <li><a href="#Contacts">Social APIs in Contacts Provider</a></li> 107 <li><a href="#Calendar">Calendar Provider</a></li> 108 <li><a href="#Voicemail">Voicemail Provider</a></li> 109 <li><a href="#Multimedia">Multimedia</a></li> 110 <li><a href="#Camera">Camera</a></li> 111 <li><a href="#AndroidBeam">Android Beam (NDEF Push with NFC)</a></li> 112 <li><a href="#WiFiDirect">Wi-Fi Direct</a></li> 113 <li><a href="#Bluetooth">Bluetooth Health Devices</a></li> 114 <li><a href="#A11y">Accessibility</a></li> 115 <li><a href="#SpellChecker">Spell Checker Services</a></li> 116 <li><a href="#TTS">Text-to-speech Engines</a></li> 117 <li><a href="#NetworkUsage">Network Usage</a></li> 118 <li><a href="#RenderScript">RenderScript</a></li> 119 <li><a href="#Enterprise">Enterprise</a></li> 120 <li><a href="#Sensors">Device Sensors</a></li> 121 <li><a href="#ActionBar">Action Bar</a></li> 122 <li><a href="#UI">User Interface and Views</a></li> 123 <li><a href="#Input">Input Framework</a></li> 124 <li><a href="#Properties">Properties</a></li> 125 <li><a href="#HwAccel">Hardware Acceleration</a></li> 126 <li><a href="#Jni">JNI Changes</a></li> 127 <li><a href="#WebKit">WebKit</a></li> 128 <li><a href="#Permissions">Permissions</a></li> 129 <li><a href="#DeviceFeatures">Device Features</a></li> 130 </ol> 131 </div> 132</div> 133 134 135 136 137 138<h3 id="Contacts">Social APIs in Contacts Provider</h3> 139 140<p>The contact APIs defined by the {@link android.provider.ContactsContract} provider have been 141extended to support new social-oriented features such as a personal profile for the device owner and 142the ability for users to invite individual contacts to social networks that are installed on the 143device.</p> 144 145 146<h4>User Profile</h4> 147 148<p>Android now includes a personal profile that represents the device owner, as defined by the 149{@link android.provider.ContactsContract.Profile} table. Social apps that maintain a user identity 150can contribute to the user's profile data by creating a new {@link 151android.provider.ContactsContract.RawContacts} entry within the {@link 152android.provider.ContactsContract.Profile}. That is, raw contacts that represent the device user do 153not belong in the traditional raw contacts table defined by the {@link 154android.provider.ContactsContract.RawContacts} Uri; instead, you must add a profile raw contact in 155the table at {@link android.provider.ContactsContract.Profile#CONTENT_RAW_CONTACTS_URI}. Raw 156contacts in this table are then aggregated into the single user-visible profile labeled "Me".</p> 157 158<p>Adding a new raw contact for the profile requires the {@link 159android.Manifest.permission#WRITE_PROFILE} permission. Likewise, in order to read from the profile 160table, you must request the {@link android.Manifest.permission#READ_PROFILE} permission. However, 161most apps should not need to read the user profile, even when contributing data to the 162profile. Reading the user profile is a sensitive permission and you should expect users to be 163skeptical of apps that request it.</p> 164 165 166<h4>Invite Intent</h4> 167 168<p>The {@link android.provider.ContactsContract.Intents#INVITE_CONTACT} intent action allows an app 169to invoke an action that indicates the user wants to add a contact to a social network. The app 170receiving the app uses it to invite the specified contact to that 171social network. Most apps will be on the receiving-end of this operation. For example, the 172built-in People app invokes the invite intent when the user selects "Add connection" for a specific 173social app that's listed in a person's contact details.</p> 174 175<p>To make your app visible as in the "Add connection" list, your app must provide a sync adapter to 176sync contact information from your social network. You must then indicate to the system that your 177app responds to the {@link android.provider.ContactsContract.Intents#INVITE_CONTACT} intent by 178adding the {@code inviteContactActivity} attribute to your app’s sync configuration file, with a 179fully-qualified name of the activity that the system should start when sending the invite intent. 180The activity that starts can then retrieve the URI for the contact in question from the intent’s 181data and perform the necessary work to invite that contact to the network or add the person to the 182user’s connections.</p> 183 184<p>See the <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">Sample Sync 185Adapter</a> app for an example (specifically, see the <a 186href="{@docRoot}resources/samples/SampleSyncAdapter/res/xml-v14/contacts.html">contacts.xml</a> 187file).</p> 188 189 190<h4>Large photos</h4> 191 192<p>Android now supports high resolution photos for contacts. Now, when you push a photo into a 193contact record, the system processes it into both a 96x96 thumbnail (as it has previously) and a 194256x256 "display photo" that's stored in a new file-based photo store (the exact dimensions that the 195system chooses may vary in the future). You can add a large photo to a contact by putting a large 196photo in the usual {@link android.provider.ContactsContract.CommonDataKinds.Photo#PHOTO} column of a 197data row, which the system will then process into the appropriate thumbnail and display photo 198records.</p> 199 200 201<h4>Contact Usage Feedback</h4> 202 203<p>The new {@link android.provider.ContactsContract.DataUsageFeedback} APIs allow you to help track 204how often the user uses particular methods of contacting people, such as how often the user uses 205each phone number or e-mail address. This information helps improve the ranking for each contact 206method associated with each person and provide better suggestions for contacting each person.</p> 207 208 209 210 211 212<h3 id="Calendar">Calendar Provider</h3> 213 214<p>The new calendar APIs allow you to read, add, modify and delete calendars, events, attendees, 215reminders and alerts, which are stored in the Calendar Provider.</p> 216 217<p>A variety of apps and widgets can use these APIs to read and modify calendar events. However, 218some of the most compelling use cases are sync adapters that synchronize the user's calendar from 219other calendar services with the Calendar Provider, in order to offer a unified location for all the 220user's events. Google Calendar events, for example, are synchronized with the Calendar Provider by 221the Google Calendar Sync Adapter, allowing these events to be viewed with Android's built-in 222Calendar app.</p> 223 224<p>The data model for calendars and event-related information in the Calendar Provider is 225defined by {@link android.provider.CalendarContract}. All the user’s calendar data is stored in a 226number of tables defined by various subclasses of {@link android.provider.CalendarContract}:</p> 227 228<ul> 229<li>The {@link android.provider.CalendarContract.Calendars} table holds the calendar-specific 230information. Each row in this table contains the details for a single calendar, such as the name, 231color, sync information, and so on.</li> 232 233<li>The {@link android.provider.CalendarContract.Events} table holds event-specific information. 234Each row in this table contains the information for a single event, such as the 235event title, location, start time, end time, and so on. The event can occur one time or recur 236multiple times. Attendees, reminders, and extended properties are stored in separate tables and 237use the event’s {@code _ID} to link them with the event.</li> 238 239<li>The {@link android.provider.CalendarContract.Instances} table holds the start and end time for 240occurrences of an event. Each row in this table represents a single occurrence. For one-time events 241there is a one-to-one mapping of instances to events. For recurring events, multiple rows are 242automatically generated to correspond to the multiple occurrences of that event.</li> 243 244<li>The {@link android.provider.CalendarContract.Attendees} table holds the event attendee or guest 245information. Each row represents a single guest of an event. It specifies the type of guest the 246person is and the person’s response for the event.</li> 247 248<li>The {@link android.provider.CalendarContract.Reminders} table holds the alert/notification data. 249Each row represents a single alert for an event. An event can have multiple reminders. The number of 250reminders per event is specified in {@code MAX_REMINDERS}, which is set by the sync adapter that 251owns the given calendar. Reminders are specified in number-of-minutes before the event is 252scheduled and specify an alarm method such as to use an alert, email, or SMS to remind 253the user.</li> 254 255<li>The {@link android.provider.CalendarContract.ExtendedProperties} table hold opaque data fields 256used by the sync adapter. The provider takes no action with items in this table except to delete 257them when their related events are deleted.</li> 258</ul> 259 260<p>To access a user’s calendar data with the Calendar Provider, your application must request 261the {@link android.Manifest.permission#READ_CALENDAR} permission (for read access) and 262{@link android.Manifest.permission#WRITE_CALENDAR} (for write access).</p> 263 264 265<h4>Event intent</h4> 266 267<p>If all you want to do is add an event to the user’s calendar, you can use an {@link 268android.content.Intent#ACTION_INSERT} intent with the data defined by {@link 269android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI} in order to start an 270activity in the Calendar app that creates new events. Using the intent does not require any 271permission and you can specify event details with the following extras:</p> 272 273<ul> 274 <li>{@link android.provider.CalendarContract.EventsColumns#TITLE Events.TITLE}: Name for the 275event</li> 276 <li>{@link 277android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_BEGIN_TIME}: 278Event begin time in milliseconds from the 279epoch</li> 280 <li>{@link 281android.provider.CalendarContract#EXTRA_EVENT_END_TIME CalendarContract.EXTRA_EVENT_END_TIME}: Event 282end time in milliseconds from the epoch</li> 283 <li>{@link android.provider.CalendarContract.EventsColumns#EVENT_LOCATION Events.EVENT_LOCATION}: 284Location of the event</li> 285 <li>{@link android.provider.CalendarContract.EventsColumns#DESCRIPTION Events.DESCRIPTION}: Event 286description</li> 287 <li>{@link android.content.Intent#EXTRA_EMAIL Intent.EXTRA_EMAIL}: Email addresses of those to 288invite</li> 289 <li>{@link android.provider.CalendarContract.EventsColumns#RRULE Events.RRULE}: The recurrence 290rule for the event</li> 291 <li>{@link android.provider.CalendarContract.EventsColumns#ACCESS_LEVEL Events.ACCESS_LEVEL}: 292Whether the event is private or public</li> 293 <li>{@link android.provider.CalendarContract.EventsColumns#AVAILABILITY Events.AVAILABILITY}: 294Whether the time period of this event allows for other events to be scheduled at the same time</li> 295</ul> 296 297 298 299 300<h3 id="Voicemail">Voicemail Provider</h3> 301 302<p>The new Voicemail Provider allows applications to add voicemails to the 303device, in order to present all the user's voicemails in a single visual presentation. For instance, 304it’s possible that a user has multiple voicemail sources, such as 305one from the phone’s service provider and others from VoIP or other alternative voice 306services. These apps can use the Voicemail Provider APIs to add their voicemails to the device. The 307built-in Phone application then presents all voicemails to the user in a unified presentation. 308Although the system’s Phone application is the only application that can read all the voicemails, 309each application that provides voicemails can read those that it has added to the system (but cannot 310read voicemails from other services).</p> 311 312<p>Because the APIs currently do not allow third-party apps to read all the voicemails from the 313system, the only third-party apps that should use the voicemail APIs are those that have voicemail 314to deliver to the user.</p> 315 316<p>The {@link android.provider.VoicemailContract} class defines the content provider for the 317Voicemail Provder. The subclasses {@link android.provider.VoicemailContract.Voicemails} and {@link 318android.provider.VoicemailContract.Status} provide tables in which apps can 319insert voicemail data for storage on the device. For an example of a voicemail provider app, see the 320<a href="{@docRoot}resources/samples/VoicemailProviderDemo/index.html">Voicemail Provider 321Demo</a>.</p> 322 323 324 325 326 327<h3 id="Multimedia">Multimedia</h3> 328 329<p>Android 4.0 adds several new APIs for applications that interact with media such as photos, 330videos, and music.</p> 331 332 333<h4>Media Effects</h4> 334 335<p>A new media effects framework allows you to apply a variety of visual effects to images and 336videos. For example, image effects allow you to easily fix red-eye, convert an image to grayscale, 337adjust brightness, adjust saturation, rotate an image, apply a fisheye effect, and much more. The 338system performs all effects processing on the GPU to obtain maximum performance.</p> 339 340<p>For maximum performance, effects are applied directly to OpenGL textures, so your application 341must have a valid OpenGL context before it can use the effects APIs. The textures to which you apply 342effects may be from bitmaps, videos or even the camera. However, there are certain restrictions that 343textures must meet:</p> 344<ol> 345<li>They must be bound to a {@link android.opengl.GLES20#GL_TEXTURE_2D} texture image</li> 346<li>They must contain at least one mipmap level</li> 347</ol> 348 349<p>An {@link android.media.effect.Effect} object defines a single media effect that you can apply to 350an image frame. The basic workflow to create an {@link android.media.effect.Effect} is:</p> 351 352<ol> 353<li>Call {@link android.media.effect.EffectContext#createWithCurrentGlContext 354EffectContext.createWithCurrentGlContext()} from your OpenGL ES 2.0 context.</li> 355<li>Use the returned {@link android.media.effect.EffectContext} to call {@link 356android.media.effect.EffectContext#getFactory EffectContext.getFactory()}, which returns an instance 357of {@link android.media.effect.EffectFactory}.</li> 358<li>Call {@link android.media.effect.EffectFactory#createEffect createEffect()}, passing it an 359effect name from @link android.media.effect.EffectFactory}, such as {@link 360android.media.effect.EffectFactory#EFFECT_FISHEYE} or {@link 361android.media.effect.EffectFactory#EFFECT_VIGNETTE}.</li> 362</ol> 363 364<p>You can adjust an effect’s parameters by calling {@link android.media.effect.Effect#setParameter 365setParameter()} and passing a parameter name and parameter value. Each type of effect accepts 366different parameters, which are documented with the effect name. For example, {@link 367android.media.effect.EffectFactory#EFFECT_FISHEYE} has one parameter for the {@code scale} of the 368distortion.</p> 369 370<p>To apply an effect on a texture, call {@link android.media.effect.Effect#apply apply()} on the 371{@link 372android.media.effect.Effect} and pass in the input texture, it’s width and height, and the output 373texture. The input texture must be bound to a {@link android.opengl.GLES20#GL_TEXTURE_2D} texture 374image (usually done by calling the {@link android.opengl.GLES20#glTexImage2D glTexImage2D()} 375function). You may provide multiple mipmap levels. If the output texture has not been bound to a 376texture image, it will be automatically bound by the effect as a {@link 377android.opengl.GLES20#GL_TEXTURE_2D} and with one mipmap level (0), which will have the same 378size as the input.</p> 379 380<p>All effects listed in {@link android.media.effect.EffectFactory} are guaranteed to be supported. 381However, some additional effects available from external libraries are not supported by all devices, 382so you must first check if the desired effect from the external library is supported by calling 383{@link android.media.effect.EffectFactory#isEffectSupported isEffectSupported()}.</p> 384 385 386<h4>Remote control client</h4> 387 388<p>The new {@link android.media.RemoteControlClient} allows media players to enable playback 389controls from remote control clients such as the device lock screen. Media players can also expose 390information about the media currently playing for display on the remote control, such as track 391information and album art.</p> 392 393<p>To enable remote control clients for your media player, instantiate a {@link 394android.media.RemoteControlClient} with its constructor, passing it a {@link 395android.app.PendingIntent} that broadcasts {@link 396android.content.Intent#ACTION_MEDIA_BUTTON}. The intent must also declare the explicit {@link 397android.content.BroadcastReceiver} component in your app that handles the {@link 398android.content.Intent#ACTION_MEDIA_BUTTON} event.</p> 399 400<p>To declare which media control inputs your player can handle, you must call {@link 401android.media.RemoteControlClient#setTransportControlFlags setTransportControlFlags()} on your 402{@link android.media.RemoteControlClient}, passing a set of {@code FLAG_KEY_MEDIA_*} flags, such as 403{@link android.media.RemoteControlClient#FLAG_KEY_MEDIA_PREVIOUS} and {@link 404android.media.RemoteControlClient#FLAG_KEY_MEDIA_NEXT}.</p> 405 406<p>You must then register your {@link android.media.RemoteControlClient} by passing it to {@link 407android.media.AudioManager#registerRemoteControlClient MediaManager.registerRemoteControlClient()}. 408Once registered, the broadcast receiver you declared when you instantiated the {@link 409android.media.RemoteControlClient} will receive {@link android.content.Intent#ACTION_MEDIA_BUTTON} 410events when a button is pressed from a remote control. The intent you receive includes the {@link 411android.view.KeyEvent} for the media key pressed, which you can retrieve from the intent with {@link 412android.content.Intent#getParcelableExtra getParcelableExtra(Intent.EXTRA_KEY_EVENT)}.</p> 413 414<p>To display information on the remote control about the media playing, call {@link 415android.media.RemoteControlClient#editMetadata editMetaData()} and add metadata to the returned 416{@link android.media.RemoteControlClient.MetadataEditor}. You can supply a bitmap for media artwork, 417numerical information such as elapsed time, and text information such as the track title. For 418information on available keys see the {@code METADATA_KEY_*} flags in {@link 419android.media.MediaMetadataRetriever}.</p> 420 421<p>For a sample implementation, see the <a 422href="{@docRoot}resources/samples/RandomMusicPlayer/index.html">Random Music Player</a>, which 423provides compatibility logic such that it enables the remote control client on Android 4.0 424devices while continuing to support devices back to Android 2.1.</p> 425 426 427<h4>Media player</h4> 428 429<ul> 430<li>Streaming online media from {@link android.media.MediaPlayer} now requires the {@link 431android.Manifest.permission#INTERNET} permission. If you use {@link android.media.MediaPlayer} to 432play content from the Internet, be sure to add the {@link android.Manifest.permission#INTERNET} 433permission to your manifest or else your media playback will not work beginning with Android 4344.0.</li> 435 436<li>{@link android.media.MediaPlayer#setSurface(Surface) setSurface()} allows you define a {@link 437android.view.Surface} to behave as the video sink.</li> 438 439<li>{@link android.media.MediaPlayer#setDataSource(Context,Uri,Map) setDataSource()} allows you to 440send additional HTTP headers with your request, which can be useful for HTTP(S) live streaming</li> 441 442<li>HTTP(S) live streaming now respects HTTP cookies across requests</li> 443</ul> 444 445 446<h4>Media types</h4> 447 448<p>Android 4.0 adds support for:</p> 449<ul> 450<li>HTTP/HTTPS live streaming protocol version 3 </li> 451<li>ADTS raw AAC audio encoding</li> 452<li>WEBP images</li> 453<li>Matroska video</li> 454</ul> 455<p>For more info, see <a href="{@docRoot}guide/appendix/media-formats.html">Supported Media 456Formats</a>.</p> 457 458 459 460 461 462<h3 id="Camera">Camera</h3> 463 464<p>The {@link android.hardware.Camera} class now includes APIs for detecting faces and controlling 465focus and metering areas.</p> 466 467 468<h4>Face detection</h4> 469 470<p>Camera apps can now enhance their abilities with Android’s face detection APIs, which not 471only detect the face of a subject, but also specific facial features, such as the eyes and mouth. 472</p> 473 474<p>To detect faces in your camera application, you must register a {@link 475android.hardware.Camera.FaceDetectionListener} by calling {@link 476android.hardware.Camera#setFaceDetectionListener setFaceDetectionListener()}. You can then start 477your camera surface and start detecting faces by calling {@link 478android.hardware.Camera#startFaceDetection}.</p> 479 480<p>When the system detects one or more faces in the camera scene, it calls the {@link 481android.hardware.Camera.FaceDetectionListener#onFaceDetection onFaceDetection()} callback in your 482implementation of {@link android.hardware.Camera.FaceDetectionListener}, including an array of 483{@link android.hardware.Camera.Face} objects.</p> 484 485<p>An instance of the {@link android.hardware.Camera.Face} class provides various information about 486the face detected, including:</p> 487<ul> 488<li>A {@link android.graphics.Rect} that specifies the bounds of the face, relative to the camera's 489current field of view</li> 490<li>An integer betwen 1 and 100 that indicates how confident the system is that the object is a 491human face</li> 492<li>A unique ID so you can track multiple faces</li> 493<li>Several {@link android.graphics.Point} objects that indicate where the eyes and mouth are 494located</li> 495</ul> 496 497<p class="note"><strong>Note:</strong> Face detection may not be supported on some 498devices, so you should check by calling {@link 499android.hardware.Camera.Parameters#getMaxNumDetectedFaces()} and ensure the return 500value is greater than zero. Also, some devices may not support identification of eyes and mouth, 501in which case, those fields in the {@link android.hardware.Camera.Face} object will be null.</p> 502 503 504<h4>Focus and metering areas</h4> 505 506<p>Camera apps can now control the areas that the camera uses for focus and for metering white 507balance 508and auto-exposure. Both features use the new {@link android.hardware.Camera.Area} class to specify 509the region of the camera’s current view that should be focused or metered. An instance of the {@link 510android.hardware.Camera.Area} class defines the bounds of the area with a {@link 511android.graphics.Rect} and the area's weight—representing the level of importance of that 512area, relative to other areas in consideration—with an integer.</p> 513 514<p>Before setting either a focus area or metering area, you should first call {@link 515android.hardware.Camera.Parameters#getMaxNumFocusAreas} or {@link 516android.hardware.Camera.Parameters#getMaxNumMeteringAreas}, respectively. If these return zero, then 517the device does not support the corresponding feature.</p> 518 519<p>To specify the focus or metering areas to use, simply call {@link 520android.hardware.Camera.Parameters#setFocusAreas setFocusAreas()} or {@link 521android.hardware.Camera.Parameters#setMeteringAreas setMeteringAreas()}. Each take a {@link 522java.util.List} of {@link android.hardware.Camera.Area} objects that indicate the areas to consider 523for focus or metering. For example, you might implement a feature that allows the user to set the 524focus area by touching an area of the preview, which you then translate to an {@link 525android.hardware.Camera.Area} object and request that the camera focus on that area of the scene. 526The focus or exposure in that area will continually update as the scene in the area changes.</p> 527 528 529<h4>Continuous auto focus for photos</h4> 530 531<p>You can now enable continuous auto focusing (CAF) when taking photos. To enable CAF in your 532camera app, pass {@link android.hardware.Camera.Parameters#FOCUS_MODE_CONTINUOUS_PICTURE} 533to {@link android.hardware.Camera.Parameters#setFocusMode setFocusMode()}. When ready to capture 534a photo, call {@link android.hardware.Camera#autoFocus autoFocus()}. Your {@link 535android.hardware.Camera.AutoFocusCallback} immediately receives a callback to indicate whether 536focus was achieved. To resume CAF after receiving the callback, you must call {@link 537android.hardware.Camera#cancelAutoFocus()}.</p> 538 539<p class="note"><strong>Note:</strong> Continuous auto focus is also supported when capturing 540video, using {@link android.hardware.Camera.Parameters#FOCUS_MODE_CONTINUOUS_VIDEO}, which was 541added in API level 9.</p> 542 543 544<h4>Other camera features</h4> 545 546<ul> 547<li>While recording video, you can now call {@link android.hardware.Camera#takePicture 548takePicture()} to save a photo without interrupting the video session. Before doing so, you should 549call {@link android.hardware.Camera.Parameters#isVideoSnapshotSupported} to be sure the hardware 550supports it.</li> 551 552<li>You can now lock auto exposure and white balance with {@link 553android.hardware.Camera.Parameters#setAutoExposureLock setAutoExposureLock()} and {@link 554android.hardware.Camera.Parameters#setAutoWhiteBalanceLock setAutoWhiteBalanceLock()} to prevent 555these properties from changing.</li> 556 557<li>You can now call {@link android.hardware.Camera#setDisplayOrientation 558setDisplayOrientation()} while the camera preview is running. Previously, you could call this 559only before beginning the preview, but you can now change the orientation at any time.</li> 560</ul> 561 562 563<h4>Camera broadcast intents</h4> 564 565<ul> 566<li>{@link android.hardware.Camera#ACTION_NEW_PICTURE Camera.ACTION_NEW_PICTURE}: 567This indicates that the user has captured a new photo. The built-in Camera app invokes this 568broadcast after a photo is captured and third-party camera apps should also broadcast this intent 569after capturing a photo.</li> 570<li>{@link android.hardware.Camera#ACTION_NEW_VIDEO Camera.ACTION_NEW_VIDEO}: 571This indicates that the user has captured a new video. The built-in Camera app invokes this 572broadcast after a video is recorded and third-party camera apps should also broadcast this intent 573after capturing a video.</li> 574</ul> 575 576 577 578 579 580<h3 id="AndroidBeam">Android Beam (NDEF Push with NFC)</h3> 581 582<p>Android Beam is a new NFC feature that allows you to send NDEF messages from one device to 583another (a process also known as “NDEF Push"). The data transfer is initiated when two 584Android-powered devices that support Android Beam are in close proximity (about 4 cm), usually with 585their backs touching. The data inside the NDEF message can contain any data that you wish to share 586between devices. For example, the People app shares contacts, YouTube shares videos, and Browser 587shares URLs using Android Beam.</p> 588 589<p>To transmit data between devices using Android Beam, you need to create an {@link 590android.nfc.NdefMessage} that contains the information you want to share while your activity is in 591the foreground. You must then pass the {@link android.nfc.NdefMessage} to the system in one of two 592ways:</p> 593 594<ul> 595<li>Define a single {@link android.nfc.NdefMessage} to push while in the activity: 596<p>Call {@link android.nfc.NfcAdapter#setNdefPushMessage setNdefPushMessage()} at any time to set 597the message you want to send. For instance, you might call this method and pass it your {@link 598android.nfc.NdefMessage} during your activity’s {@link android.app.Activity#onCreate onCreate()} 599method. Then, whenever Android Beam is activated with another device while the activity is in the 600foreground, the system sends the {@link android.nfc.NdefMessage} to the other device.</p></li> 601 602<li>Define the {@link android.nfc.NdefMessage} to push at the time that Android Beam is initiated: 603<p>Implement {@link android.nfc.NfcAdapter.CreateNdefMessageCallback}, in which your 604implementation of the {@link 605android.nfc.NfcAdapter.CreateNdefMessageCallback#createNdefMessage createNdefMessage()} 606method returns the {@link android.nfc.NdefMessage} you want to send. Then pass the {@link 607android.nfc.NfcAdapter.CreateNdefMessageCallback} implementation to {@link 608android.nfc.NfcAdapter#setNdefPushMessageCallback setNdefPushMessageCallback()}.</p> 609<p>In this case, when Android Beam is activated with another device while your activity is in the 610foreground, the system calls {@link 611android.nfc.NfcAdapter.CreateNdefMessageCallback#createNdefMessage createNdefMessage()} to retrieve 612the {@link android.nfc.NdefMessage} you want to send. This allows you to define the {@link 613android.nfc.NdefMessage} to deliver only once Android Beam is initiated, in case the contents 614of the message might vary throughout the life of the activity.</p></li> 615</ul> 616 617<p>In case you want to run some specific code once the system has successfully delivered your NDEF 618message to the other device, you can implement {@link 619android.nfc.NfcAdapter.OnNdefPushCompleteCallback} and set it with {@link 620android.nfc.NfcAdapter#setOnNdefPushCompleteCallback setNdefPushCompleteCallback()}. The system will 621then call {@link android.nfc.NfcAdapter.OnNdefPushCompleteCallback#onNdefPushComplete 622onNdefPushComplete()} when the message is delivered.</p> 623 624<p>On the receiving device, the system dispatches NDEF Push messages in a similar way to regular NFC 625tags. The system invokes an intent with the {@link android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} 626action to start an activity, with either a URL or a MIME type set according to the first {@link 627android.nfc.NdefRecord} in the {@link android.nfc.NdefMessage}. For the activity you want to 628respond, you can declare intent filters for the URLs or MIME types your app cares about. For more 629information about Tag Dispatch see the <a 630href="{@docRoot}guide/topics/nfc/index.html#dispatch">NFC</a> developer guide.</p> 631 632<p>If you want your {@link android.nfc.NdefMessage} to carry a URI, you can now use the convenience 633method {@link android.nfc.NdefRecord#createUri createUri} to construct a new {@link 634android.nfc.NdefRecord} based on either a string or a {@link android.net.Uri} object. If the URI is 635a special format that you want your application to also receive during an Android Beam event, you 636should create an intent filter for your activity using the same URI scheme in order to receive the 637incoming NDEF message.</p> 638 639<p>You should also pass an “Android application record" with your {@link android.nfc.NdefMessage} in 640order to guarantee that your application handles the incoming NDEF message, even if other 641applications filter for the same intent action. You can create an Android application record by 642calling {@link android.nfc.NdefRecord#createApplicationRecord createApplicationRecord()}, passing it 643your application’s package name. When the other device receives the NDEF message with the 644application record and multiple applications contain activities that handle the specified intent, 645the system always delivers the message to the activity in your application (based on the matching 646application record). If the target device does not currently have your application installed, the 647system uses the Android application record to launch Android Market and take the user to the 648application in order to install it.</p> 649 650<p>If your application doesn’t use NFC APIs to perform NDEF Push messaging, then Android provides a 651default behavior: When your application is in the foreground on one device and Android Beam is 652invoked with another Android-powered device, then the other device receives an NDEF message with an 653Android application record that identifies your application. If the receiving device has the 654application installed, the system launches it; if it’s not installed, Android Market opens and takes 655the user to your application in order to install it.</p> 656 657<p>You can read more about Android Beam and other NFC features in the <a 658href="{@docRoot}guide/topics/nfc/nfc.html">NFC Basics</a> developer guide. For some example code 659using Android Beam, see the <a 660href="{@docRoot}resources/samples/AndroidBeamDemo/src/com/example/android/beam/Beam.html">Android 661Beam Demo</a>.</p> 662 663 664 665 666 667<h3 id="WiFiDirect">Wi-Fi Direct</h3> 668 669<p>Android now supports Wi-Fi Direct for peer-to-peer (P2P) connections between Android-powered 670devices and other device types without a hotspot or Internet connection. The Android framework 671provides a set of Wi-Fi P2P APIs that allow you to discover and connect to other devices when each 672device supports Wi-Fi Direct, then communicate over a speedy connection across distances much longer 673than a Bluetooth connection.</p> 674 675<p>A new package, {@link android.net.wifi.p2p}, contains all the APIs for performing peer-to-peer 676connections with Wi-Fi. The primary class you need to work with is {@link 677android.net.wifi.p2p.WifiP2pManager}, which you can acquire by calling {@link 678android.app.Activity#getSystemService getSystemService(WIFI_P2P_SERVICE)}. The {@link 679android.net.wifi.p2p.WifiP2pManager} includes APIs that allow you to:</p> 680<ul> 681<li>Initialize your application for P2P connections by calling {@link 682android.net.wifi.p2p.WifiP2pManager#initialize initialize()}</li> 683 684<li>Discover nearby devices by calling {@link android.net.wifi.p2p.WifiP2pManager#discoverPeers 685discoverPeers()}</li> 686 687<li>Start a P2P connection by calling {@link android.net.wifi.p2p.WifiP2pManager#connect 688connect()}</li> 689<li>And more</li> 690</ul> 691 692<p>Several other interfaces and classes are necessary as well, such as:</p> 693<ul> 694<li>The {@link android.net.wifi.p2p.WifiP2pManager.ActionListener} interface allows you to receive 695callbacks when an operation such as discovering peers or connecting to them succeeds or fails.</li> 696 697<li>{@link android.net.wifi.p2p.WifiP2pManager.PeerListListener} interface allows you to receive 698information about discovered peers. The callback provides a {@link 699android.net.wifi.p2p.WifiP2pDeviceList}, from which you can retrieve a {@link 700android.net.wifi.p2p.WifiP2pDevice} object for each device within range and get information such as 701the device name, address, device type, the WPS configurations the device supports, and more.</li> 702 703<li>The {@link android.net.wifi.p2p.WifiP2pManager.GroupInfoListener} interface allows you to 704receive information about a P2P group. The callback provides a {@link 705android.net.wifi.p2p.WifiP2pGroup} object, which provides group information such as the owner, the 706network name, and passphrase.</li> 707 708<li>{@link android.net.wifi.p2p.WifiP2pManager.ConnectionInfoListener} interface allows you to 709receive information about the current connection. The callback provides a {@link 710android.net.wifi.p2p.WifiP2pInfo} object, which has information such as whether a group has been 711formed and who is the group owner.</li> 712</ul> 713 714<p>In order to use the Wi-Fi P2P APIs, your app must request the following user permissions:</p> 715<ul> 716<li>{@link android.Manifest.permission#ACCESS_WIFI_STATE}</li> 717<li>{@link android.Manifest.permission#CHANGE_WIFI_STATE}</li> 718<li>{@link android.Manifest.permission#INTERNET} (although your app doesn’t technically connect 719to the Internet, communicating to Wi-Fi Direct peers with standard java sockets requires Internet 720permission).</li> 721</ul> 722 723<p>The Android system also broadcasts several different actions during certain Wi-Fi P2P events:</p> 724<ul> 725<li>{@link android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_CONNECTION_CHANGED_ACTION}: The P2P 726connection state has changed. This carries {@link 727android.net.wifi.p2p.WifiP2pManager#EXTRA_WIFI_P2P_INFO} with a {@link 728android.net.wifi.p2p.WifiP2pInfo} object and {@link 729android.net.wifi.p2p.WifiP2pManager#EXTRA_NETWORK_INFO} with a {@link android.net.NetworkInfo} 730object.</li> 731 732<li>{@link android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_STATE_CHANGED_ACTION}: The P2P state has 733changed between enabled and disabled. It carries {@link 734android.net.wifi.p2p.WifiP2pManager#EXTRA_WIFI_STATE} with either {@link 735android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_STATE_DISABLED} or {@link 736android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_STATE_ENABLED}</li> 737 738<li>{@link android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_PEERS_CHANGED_ACTION}: The list of peer 739devices has changed.</li> 740 741<li>{@link android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_THIS_DEVICE_CHANGED_ACTION}: The details for 742this device have changed.</li> 743</ul> 744 745<p>See the {@link android.net.wifi.p2p.WifiP2pManager} documentation for more information. Also 746look at the <a href="{@docRoot}resources/samples/WiFiDirectDemo/index.html">Wi-Fi Direct Demo</a> 747sample application.</p> 748 749 750 751 752 753<h3 id="Bluetooth">Bluetooth Health Devices</h3> 754 755<p>Android now supports Bluetooth Health Profile devices, so you can create applications that use 756Bluetooth to communicate with health devices that support Bluetooth, such as heart-rate monitors, 757blood meters, thermometers, and scales.</p> 758 759<p>Similar to regular headset and A2DP profile devices, you must call {@link 760android.bluetooth.BluetoothAdapter#getProfileProxy getProfileProxy()} with a {@link 761android.bluetooth.BluetoothProfile.ServiceListener} and the {@link 762android.bluetooth.BluetoothProfile#HEALTH} profile type to establish a connection with the profile 763proxy object.</p> 764 765<p>Once you’ve acquired the Health Profile proxy (the {@link android.bluetooth.BluetoothHealth} 766object), connecting to and communicating with paired health devices involves the following new 767Bluetooth classes:</p> 768<ul> 769<li>{@link android.bluetooth.BluetoothHealthCallback}: You must extend this class and implement the 770callback methods to receive updates about changes in the application’s registration state and 771Bluetooth channel state.</li> 772<li>{@link android.bluetooth.BluetoothHealthAppConfiguration}: During callbacks to your {@link 773android.bluetooth.BluetoothHealthCallback}, you’ll receive an instance of this object, which 774provides configuration information about the available Bluetooth health device, which you must use 775to perform various operations such as initiate and terminate connections with the {@link 776android.bluetooth.BluetoothHealth} APIs.</li> 777</ul> 778 779<p>For more information about using the Bluetooth Health Profile, see the documentation for {@link 780android.bluetooth.BluetoothHealth}.</p> 781 782 783 784 785 786<h3 id="A11y">Accessibility</h3> 787 788<p>Android 4.0 improves accessibility for sight-impaired users with new explore-by-touch mode 789and extended APIs that allow you to provide more information about view content or 790develop advanced accessibility services.</p> 791 792 793<h4>Explore-by-touch mode</h4> 794 795<p>Users with vision loss can now explore the screen by touching and dragging a finger across the 796screen to hear voice descriptions of the content. Because the explore-by-touch mode works like a 797virtual cursor, it allows screen readers to identify the descriptive text the same way that screen 798readers can when the user navigates with a d-pad or trackball—by reading information provided 799by {@link android.R.attr#contentDescription android:contentDescription} and {@link 800android.view.View#setContentDescription setContentDescription()} upon a simulated "hover" event. So, 801consider this is a reminder that you should provide descriptive text for the views in your 802application, especially for {@link android.widget.ImageButton}, {@link android.widget.EditText}, 803{@link android.widget.ImageView} and other widgets that might not naturally contain descriptive 804text.</p> 805 806 807<h4>Accessibility for views</h4> 808 809<p>To enhance the information available to accessibility services such as screen readers, you can 810implement new callback methods for accessibility events in your custom {@link 811android.view.View} components.</p> 812 813<p>It's important to first note that the behavior of the {@link 814android.view.View#sendAccessibilityEvent sendAccessibilityEvent()} method has changed in Android 8154.0. As with previous version of Android, when the user enables accessibility services on the device 816and an input event such as a click or hover occurs, the respective view is notified with a call to 817{@link android.view.View#sendAccessibilityEvent sendAccessibilityEvent()}. Previously, the 818implementation of {@link android.view.View#sendAccessibilityEvent sendAccessibilityEvent()} would 819initialize an {@link android.view.accessibility.AccessibilityEvent} and send it to {@link 820android.view.accessibility.AccessibilityManager}. The new behavior involves some additional callback 821methods that allow the view and its parents to add more contextual information to the event: 822<ol> 823 <li>When invoked, the {@link 824android.view.View#sendAccessibilityEvent sendAccessibilityEvent()} and {@link 825android.view.View#sendAccessibilityEventUnchecked sendAccessibilityEventUnchecked()} methods defer 826to {@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()}. 827 <p>Custom implementations of {@link android.view.View} might want to implement {@link 828android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()} to 829attach additional accessibility information to the {@link 830android.view.accessibility.AccessibilityEvent}, but should also call the super implementation to 831provide default information such as the standard content description, item index, and more. 832However, you should not add additional text content in this callback—that happens 833next.</p></li> 834 <li>Once initialized, if the event is one of several types that should be populated with text 835information, the view then receives a call to {@link 836android.view.View#dispatchPopulateAccessibilityEvent dispatchPopulateAccessibilityEvent()}, which 837defers to the {@link android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} 838callback. 839 <p>Custom implementations of {@link android.view.View} should usually implement {@link 840android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} to add additional 841text content to the {@link android.view.accessibility.AccessibilityEvent} if the {@link 842android.R.attr#contentDescription android:contentDescription} text is missing or 843insufficient. To add more text description to the 844{@link android.view.accessibility.AccessibilityEvent}, call {@link 845android.view.accessibility.AccessibilityEvent#getText()}.{@link java.util.List#add add()}.</p> 846</li> 847 <li>At this point, the {@link android.view.View} passes the event up the view hierarchy by calling 848{@link android.view.ViewGroup#requestSendAccessibilityEvent requestSendAccessibilityEvent()} on the 849parent view. Each parent view then has the chance to augment the accessibility information by 850adding an {@link android.view.accessibility.AccessibilityRecord}, until it 851ultimately reaches the root view, which sends the event to the {@link 852android.view.accessibility.AccessibilityManager} with {@link 853android.view.accessibility.AccessibilityManager#sendAccessibilityEvent 854sendAccessibilityEvent()}.</li> 855</ol> 856 857<p>In addition to the new methods above, which are useful when extending the {@link 858android.view.View} class, you can also intercept these event callbacks on any {@link 859android.view.View} by extending {@link 860android.view.View.AccessibilityDelegate AccessibilityDelegate} and setting it on the view with 861{@link android.view.View#setAccessibilityDelegate setAccessibilityDelegate()}. 862When you do, each accessibility method in the view defers the call to the corresponding method in 863the delegate. For example, when the view receives a call to {@link 864android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()}, it passes it to the 865same method in the {@link android.view.View.AccessibilityDelegate}. Any methods not handled by 866the delegate are given right back to the view for default behavior. This allows you to override only 867the methods necessary for any given view without extending the {@link android.view.View} class.</p> 868 869 870<p>If you want to maintain compatibility with Android versions prior to 4.0, while also supporting 871the new the accessibility APIs, you can do so with the latest version of the <em>v4 support 872library</em> (in <a href="{@docRoot}sdk/compatibility-library.html">Compatibility Package, r4</a>) 873using a set of utility classes that provide the new accessibility APIs in a backward-compatible 874design.</p> 875 876 877 878 879<h4>Accessibility services</h4> 880 881<p>If you're developing an accessibility service, the information about various accessibility events 882has been significantly expanded to enable more advanced accessibility feedback for users. In 883particular, events are generated based on view composition, providing better context information and 884allowing accessibility services to traverse view hierarchies to get additional view information and 885deal with special cases.</p> 886 887<p>If you're developing an accessibility service (such as a screen reader), you can access 888additional content information and traverse view hierarchies with the following procedure:</p> 889<ol> 890<li>Upon receiving an {@link android.view.accessibility.AccessibilityEvent} from an application, 891call the {@link android.view.accessibility.AccessibilityEvent#getRecord(int) 892AccessibilityEvent.getRecord()} to retrieve a specific {@link 893android.view.accessibility.AccessibilityRecord} (there may be several records attached to the 894event).</li> 895 896<li>From either {@link android.view.accessibility.AccessibilityEvent} or an individual {@link 897android.view.accessibility.AccessibilityRecord}, you can call {@link 898android.view.accessibility.AccessibilityRecord#getSource() getSource()} to retrieve a {@link 899android.view.accessibility.AccessibilityNodeInfo} object. 900 <p>An {@link android.view.accessibility.AccessibilityNodeInfo} represents a single node 901of the window content in a format that allows you to query accessibility information about that 902node. The {@link android.view.accessibility.AccessibilityNodeInfo} object returned from {@link 903android.view.accessibility.AccessibilityEvent} describes the event source, whereas the source from 904an {@link android.view.accessibility.AccessibilityRecord} describes the predecessor of the event 905source.</p></li> 906 907<li>With the {@link android.view.accessibility.AccessibilityNodeInfo}, you can query information 908about it, call {@link 909android.view.accessibility.AccessibilityNodeInfo#getParent getParent()} or {@link 910android.view.accessibility.AccessibilityNodeInfo#getChild getChild()} to traverse the view 911hierarchy, and even add child views to the node.</li> 912</ol> 913 914<p>In order for your application to publish itself to the system as an accessibility service, it 915must declare an XML configuration file that corresponds to {@link 916android.accessibilityservice.AccessibilityServiceInfo}. For more information about creating an 917accessibility service, see {@link 918android.accessibilityservice.AccessibilityService} and {@link 919android.accessibilityservice.AccessibilityService#SERVICE_META_DATA 920SERVICE_META_DATA} for information about the XML configuration.</p> 921 922 923<h4>Other accessibility APIs</h4> 924 925<p>If you're interested in the device's accessibility state, the {@link 926android.view.accessibility.AccessibilityManager} has some new APIs such as:</p> 927<ul> 928 <li>{@link android.view.accessibility.AccessibilityManager.AccessibilityStateChangeListener} 929is an interface that allows you to receive a callback whenever accessibility is enabled or 930disabled.</li> 931 <li>{@link android.view.accessibility.AccessibilityManager#getEnabledAccessibilityServiceList 932 getEnabledAccessibilityServiceList()} provides information about which accessibility services 933 are currently enabled.</li> 934 <li>{@link android.view.accessibility.AccessibilityManager#isTouchExplorationEnabled()} tells 935 you whether the explore-by-touch mode is enabled.</li> 936</ul> 937 938 939 940 941 942 943<h3 id="SpellChecker">Spell Checker Services</h3> 944 945<p>A new spell checker framework allows apps to create spell checkers in a manner similar to the 946input method framework (for IMEs). To create a new spell checker, you must implement a service that 947extends 948{@link android.service.textservice.SpellCheckerService} and extend the {@link 949android.service.textservice.SpellCheckerService.Session} class to provide spelling suggestions based 950on text provided by the interface's callback methods. In the {@link 951android.service.textservice.SpellCheckerService.Session} callback methods, you must return the 952spelling suggestions as {@link android.view.textservice.SuggestionsInfo} objects. </p> 953 954<p>Applications with a spell checker service must declare the {@link 955android.Manifest.permission#BIND_TEXT_SERVICE} permission as required by the service. 956The service must also declare an intent filter with {@code <action 957android:name="android.service.textservice.SpellCheckerService" />} as the intent’s action and should 958include a {@code <meta-data>} element that declares configuration information for the spell 959checker. </p> 960 961<p>See the sample <a href="{@docRoot}resources/samples/SpellChecker/SampleSpellCheckerService/index.html"> 962Spell Checker Service</a> app and 963sample <a href="{@docRoot}resources/samples/SpellChecker/HelloSpellChecker/index.html"> 964Spell Checker Client</a> app for example code.</p> 965 966 967 968 969<h3 id="TTS">Text-to-speech Engines</h3> 970 971<p>Android’s text-to-speech (TTS) APIs have been significantly extended to allow applications to 972more easily implement custom TTS engines, while applications that want to use a TTS engine have a 973couple new APIs for selecting an engine.</p> 974 975 976<h4>Using text-to-speech engines</h4> 977 978<p>In previous versions of Android, you could use the {@link android.speech.tts.TextToSpeech} class 979to perform text-to-speech (TTS) operations using the TTS engine provided by the system or set a 980custom engine using {@link android.speech.tts.TextToSpeech#setEngineByPackageName 981setEngineByPackageName()}. In Android 4.0, the {@link 982android.speech.tts.TextToSpeech#setEngineByPackageName setEngineByPackageName()} method has been 983deprecated and you can now specify the engine to use with a new {@link 984android.speech.tts.TextToSpeech} constructor that accepts the package name of a TTS engine.</p> 985 986<p>You can also query the available TTS engines with {@link 987android.speech.tts.TextToSpeech#getEngines()}. This method returns a list of {@link 988android.speech.tts.TextToSpeech.EngineInfo} objects, which include meta data such as the engine’s 989icon, label, and package name.</p> 990 991 992<h4>Building text-to-speech engines</h4> 993 994<p>Previously, custom engines required that the engine be built using an undocumented native header 995file. In Android 4.0, there is a complete set of framework APIs for building TTS engines. </p> 996 997<p>The basic setup requires an implementation of {@link android.speech.tts.TextToSpeechService} that 998responds to the {@link android.speech.tts.TextToSpeech.Engine#INTENT_ACTION_TTS_SERVICE} intent. The 999primary work for a TTS engine happens during the {@link 1000android.speech.tts.TextToSpeechService#onSynthesizeText onSynthesizeText()} callback in a service 1001that extends {@link android.speech.tts.TextToSpeechService}. The system delivers this method two 1002objects:</p> 1003<ul> 1004<li>{@link android.speech.tts.SynthesisRequest}: This contains various data including the text to 1005synthesize, the locale, the speech rate, and voice pitch.</li> 1006<li>{@link android.speech.tts.SynthesisCallback}: This is the interface by which your TTS engine 1007delivers the resulting speech data as streaming audio. First the engine must call {@link 1008android.speech.tts.SynthesisCallback#start start()} to indicate that the engine is ready to deliver 1009the audio, then call {@link android.speech.tts.SynthesisCallback#audioAvailable audioAvailable()}, 1010passing it the audio data in a byte buffer. Once your engine has passed all audio through the 1011buffer, call {@link android.speech.tts.SynthesisCallback#done()}.</li> 1012</ul> 1013 1014<p>Now that the framework supports a true API for creating TTS engines, support for the native code 1015implementation has been removed. Look for a blog post about a compatibility layer 1016that you can use to convert your old TTS engines to the new framework.</p> 1017 1018<p>For an example TTS engine using the new APIs, see the <a 1019href="{@docRoot}resources/samples/TtsEngine/index.html">Text To Speech Engine</a> sample app.</p> 1020 1021 1022 1023 1024 1025 1026<h3 id="NetworkUsage">Network Usage</h3> 1027 1028<p>Android 4.0 gives users precise visibility of how much network data their applications are using. 1029The Settings app provides controls that allow users to manage set limits for network data usage and 1030even disable the use of background data for individual apps. In order to avoid users disabling your 1031app’s access to data from the background, you should develop strategies to use the data 1032connection efficiently and adjust your usage depending on the type of connection available.</p> 1033 1034<p>If your application performs a lot of network transactions, you should provide user settings that 1035allow users to control your app’s data habits, such as how often your app syncs data, whether to 1036perform uploads/downloads only when on Wi-Fi, whether to use data while roaming, etc. With these 1037controls available to them, users are much less likely to disable your app’s access to data when 1038they approach their limits, because they can instead precisely control how much data your app uses. 1039If you provide a preference activity with these settings, you should include in its manifest 1040declaration an intent filter for the {@link android.content.Intent#ACTION_MANAGE_NETWORK_USAGE} 1041action. For example:</p> 1042 1043<pre> 1044<activity android:name="DataPreferences" android:label="@string/title_preferences"> 1045 <intent-filter> 1046 <action android:name="android.intent.action.MANAGE_NETWORK_USAGE" /> 1047 <category android:name="android.intent.category.DEFAULT" /> 1048 </intent-filter> 1049</activity> 1050</pre> 1051 1052<p>This intent filter indicates to the system that this is the activity that controls your 1053application’s data usage. Thus, when the user inspects how much data your app is using from the 1054Settings app, a “View application settings" button is available that launches your 1055preference activity so the user can refine how much data your app uses.</p> 1056 1057<p>Also beware that {@link android.net.ConnectivityManager#getBackgroundDataSetting()} is now 1058deprecated and always returns true—use {@link 1059android.net.ConnectivityManager#getActiveNetworkInfo()} instead. Before you attempt any network 1060transactions, you should always call {@link android.net.ConnectivityManager#getActiveNetworkInfo()} 1061to get the {@link android.net.NetworkInfo} that represents the current network and query {@link 1062android.net.NetworkInfo#isConnected()} to check whether the device has a 1063connection. You can then check other connection properties, such as whether the device is 1064roaming or connected to Wi-Fi.</p> 1065 1066 1067 1068 1069 1070 1071 1072 1073<h3 id="RenderScript">RenderScript</h3> 1074 1075<p>Three major features have been added to RenderScript:</p> 1076 1077<ul> 1078 <li>Off-screen rendering to a framebuffer object</li> 1079 <li>Rendering inside a view</li> 1080 <li>RS for each from the framework APIs</li> 1081</ul> 1082 1083<p>The {@link android.renderscript.Allocation} class now supports a {@link 1084android.renderscript.Allocation#USAGE_GRAPHICS_RENDER_TARGET} memory space, which allows you to 1085render things directly into the {@link android.renderscript.Allocation} and use it as a framebuffer 1086object.</p> 1087 1088<p>{@link android.renderscript.RSTextureView} provides a means to display RenderScript graphics 1089inside of a {@link android.view.View}, unlike {@link android.renderscript.RSSurfaceView}, which 1090creates a separate window. This key difference allows you to do things such as move, transform, or 1091animate an {@link android.renderscript.RSTextureView} as well as draw RenderScript graphics inside 1092a view that lies within an activity layout.</p> 1093 1094<p>The {@link android.renderscript.Script#forEach Script.forEach()} method allows you to call 1095RenderScript compute scripts from the VM level and have them automatically delegated to available 1096cores on the device. You do not use this method directly, but any compute RenderScript that you 1097write will have a {@link android.renderscript.Script#forEach forEach()} method that you can call in 1098the reflected RenderScript class. You can call the reflected {@link 1099android.renderscript.Script#forEach forEach()} method by passing in an input {@link 1100android.renderscript.Allocation} to process, an output {@link android.renderscript.Allocation} to 1101write the result to, and a {@link android.renderscript.FieldPacker} data structure in case the 1102RenderScript needs more information. Only one of the {@link android.renderscript.Allocation}s is 1103necessary and the data structure is optional.</p> 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113<h3 id="Enterprise">Enterprise</h3> 1114 1115<p>Android 4.0 expands the capabilities for enterprise application with the following features.</p> 1116 1117<h4>VPN services</h4> 1118 1119<p>The new {@link android.net.VpnService} allows applications to build their own VPN (Virtual 1120Private Network), running as a {@link android.app.Service}. A VPN service creates an interface for a 1121virtual network with its own address and routing rules and performs all reading and writing with a 1122file descriptor.</p> 1123 1124<p>To create a VPN service, use {@link android.net.VpnService.Builder}, which allows you to specify 1125the network address, DNS server, network route, and more. When complete, you can establish the 1126interface by calling {@link android.net.VpnService.Builder#establish()}, which returns a {@link 1127android.os.ParcelFileDescriptor}. </p> 1128 1129<p>Because a VPN service can intercept packets, there are security implications. As such, if you 1130implement {@link android.net.VpnService}, then your service must require the {@link 1131android.Manifest.permission#BIND_VPN_SERVICE} to ensure that only the system can bind to it (only 1132the system is granted this permission—apps cannot request it). To then use your VPN service, 1133users must manually enable it in the system settings.</p> 1134 1135 1136<h4>Device policies</h4> 1137 1138<p>Applications that manage the device restrictions can now disable the camera using {@link 1139android.app.admin.DevicePolicyManager#setCameraDisabled setCameraDisabled()} and the {@link 1140android.app.admin.DeviceAdminInfo#USES_POLICY_DISABLE_CAMERA} property (applied with a {@code 1141<disable-camera />} element in the policy configuration file).</p> 1142 1143 1144<h4>Certificate management</h4> 1145 1146<p>The new {@link android.security.KeyChain} class provides APIs that allow you to import and access 1147certificates in the system key store. Certificates streamline the installation of both client 1148certificates (to validate the identity of the user) and certificate authority certificates (to 1149verify server identity). Applications such as web browsers or email clients can access the installed 1150certificates to authenticate users to servers. See the {@link android.security.KeyChain} 1151documentation for more information.</p> 1152 1153 1154 1155 1156 1157 1158 1159<h3 id="Sensors">Device Sensors</h3> 1160 1161<p>Two new sensor types have been added in Android 4.0:</p> 1162 1163<ul> 1164 <li>{@link android.hardware.Sensor#TYPE_AMBIENT_TEMPERATURE}: A temperature sensor that provides 1165the ambient (room) temperature in degrees Celsius.</li> 1166 <li>{@link android.hardware.Sensor#TYPE_RELATIVE_HUMIDITY}: A humidity sensor that provides the 1167relative ambient (room) humidity as a percentage.</li> 1168</ul> 1169 1170<p>If a device has both {@link android.hardware.Sensor#TYPE_AMBIENT_TEMPERATURE} and {@link 1171android.hardware.Sensor#TYPE_RELATIVE_HUMIDITY} sensors, you can use them to calculate the dew point 1172and the absolute humidity.</p> 1173 1174<p>The previous temperature sensor, {@link android.hardware.Sensor#TYPE_TEMPERATURE}, has been 1175deprecated. You should use the {@link android.hardware.Sensor#TYPE_AMBIENT_TEMPERATURE} sensor 1176instead.</p> 1177 1178<p>Additionally, Android’s three synthetic sensors have been greatly improved so they now have lower 1179latency and smoother output. These sensors include the gravity sensor ({@link 1180android.hardware.Sensor#TYPE_GRAVITY}), rotation vector sensor ({@link 1181android.hardware.Sensor#TYPE_ROTATION_VECTOR}), and linear acceleration sensor ({@link 1182android.hardware.Sensor#TYPE_LINEAR_ACCELERATION}). The improved sensors rely on the gyroscope 1183sensor to improve their output, so the sensors appear only on devices that have a gyroscope.</p> 1184 1185 1186 1187 1188 1189<h3 id="ActionBar">Action Bar</h3> 1190 1191<p>The {@link android.app.ActionBar} has been updated to support several new behaviors. Most 1192importantly, the system gracefully manages the action bar’s size and configuration when running on 1193smaller screens in order to provide an optimal user experience on all screen sizes. For example, 1194when the screen is narrow (such as when a handset is in portrait orientation), the action bar’s 1195navigation tabs appear in a “stacked bar," which appears directly below the main action bar. You can 1196also opt-in to a “split action bar," which places all action items in a separate bar at the bottom 1197of the screen when the screen is narrow.</p> 1198 1199 1200<h4>Split action bar</h4> 1201 1202<p>If your action bar includes several action items, not all of them will fit into the action bar on 1203a narrow screen, so the system will place more of them into the overflow menu. However, Android 4.0 1204allows you to enable “split action bar" so that more action items can appear on the screen in a 1205separate bar at the bottom of the screen. To enable split action bar, add {@link 1206android.R.attr#uiOptions android:uiOptions} with {@code "splitActionBarWhenNarrow"} to either your 1207<a href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> 1208tag or 1209individual <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code 1210<activity>}</a> tags 1211in your manifest file. When enabled, the system will add an additional bar at the bottom of the 1212screen for all action items when the screen is narrow (no action items will appear in the primary 1213action bar).</p> 1214 1215<p>If you want to use the navigation tabs provided by the {@link android.app.ActionBar.Tab} APIs, 1216but don’t need the main action bar on top (you want only the tabs to appear at the top), then enable 1217the split action bar as described above and also call {@link 1218android.app.ActionBar#setDisplayShowHomeEnabled setDisplayShowHomeEnabled(false)} to disable the 1219application icon in the action bar. With nothing left in the main action bar, it 1220disappears—all that’s left are the navigation tabs at the top and the action items at the 1221bottom of the screen.</p> 1222 1223 1224<h4>Action bar styles</h4> 1225 1226<p>If you want to apply custom styling to the action bar, you can use new style properties {@link 1227android.R.attr#backgroundStacked} and {@link android.R.attr#backgroundSplit} to apply a background 1228drawable or color to the stacked bar and split bar, respectively. You can also set these styles at 1229runtime with {@link android.app.ActionBar#setStackedBackgroundDrawable 1230setStackedBackgroundDrawable()} and {@link android.app.ActionBar#setSplitBackgroundDrawable 1231setSplitBackgroundDrawable()}.</p> 1232 1233 1234<h4>Action provider</h4> 1235 1236<p>The new {@link android.view.ActionProvider} class allows you to create a specialized handler for 1237action items. An action provider can define an action view, a default action behavior, and a submenu 1238for each action item to which it is associated. When you want to create an action item that has 1239dynamic behaviors (such as a variable action view, default action, or submenu), extending {@link 1240android.view.ActionProvider} is a good solution in order to create a reusable component, rather than 1241handling the various action item transformations in your fragment or activity.</p> 1242 1243<p>For example, the {@link android.widget.ShareActionProvider} is an extension of {@link 1244android.view.ActionProvider} that facilitates a “share" action from the action bar. Instead of using 1245traditional action item that invokes the {@link android.content.Intent#ACTION_SEND} intent, you can 1246use this action provider to present an action view with a drop-down list of applications that handle 1247the {@link android.content.Intent#ACTION_SEND} intent. When the user selects an application to use 1248for the action, {@link android.widget.ShareActionProvider} remembers that selection and provides it 1249in the action view for faster access to sharing with that app.</p> 1250 1251<p>To declare an action provider for an action item, include the {@code android:actionProviderClass} 1252attribute in the <a href="{@docRoot}guide/topics/resources/menu-resource.html#item-element">{@code 1253<item>}</a> element for your activity’s options menu, with the class name of the action 1254provider as the value. For example:</p> 1255 1256<pre> 1257<item android:id="@+id/menu_share" 1258 android:title="Share" 1259 android:showAsAction="ifRoom" 1260 android:actionProviderClass="android.widget.ShareActionProvider" /> 1261</pre> 1262 1263<p>In your activity’s {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} 1264callback method, retrieve an instance of the action provider from the menu item and set the 1265intent:</p> 1266 1267<pre> 1268public boolean onCreateOptionsMenu(Menu menu) { 1269 getMenuInflater().inflate(R.menu.options, menu); 1270 ShareActionProvider shareActionProvider = 1271 (ShareActionProvider) menu.findItem(R.id.menu_share).getActionProvider(); 1272 // Set the share intent of the share action provider. 1273 shareActionProvider.setShareIntent(createShareIntent()); 1274 ... 1275 return super.onCreateOptionsMenu(menu); 1276} 1277</pre> 1278 1279<p>For an example using the {@link android.widget.ShareActionProvider}, see the <a 1280href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ActionBarActionProviderActivity.html" 1281>ActionBarActionProviderActivity</a> class in ApiDemos.</p> 1282 1283 1284<h4>Collapsible action views</h4> 1285 1286<p>Action items that provide an action view can now toggle between their action view state and 1287traditional action item state. Previously only the {@link android.widget.SearchView} supported 1288collapsing when used as an action view, but now you can add an action view for any action item and 1289switch between the expanded state (action view is visible) and collapsed state (action item is 1290visible).</p> 1291 1292<p>To declare that an action item that contains an action view be collapsible, include the {@code 1293“collapseActionView"} flag in the {@code android:showAsAction} attribute for the <a 1294href="{@docRoot}guide/topics/resources/menu-resource.html#item-element">{@code 1295<item>}</a> element in the menu’s XML file.</p> 1296 1297<p>To receive callbacks when an action view switches between expanded and collapsed, register an 1298instance of {@link android.view.MenuItem.OnActionExpandListener} with the respective {@link 1299android.view.MenuItem} by calling {@link android.view.MenuItem#setOnActionExpandListener 1300setOnActionExpandListener()}. Typically, you should do so during the {@link 1301android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} callback.</p> 1302 1303<p>To control a collapsible action view, you can call {@link 1304android.view.MenuItem#collapseActionView()} and {@link android.view.MenuItem#expandActionView()} on 1305the respective {@link android.view.MenuItem}.</p> 1306 1307<p>When creating a custom action view, you can also implement the new {@link 1308android.view.CollapsibleActionView} interface to receive callbacks when the view is expanded and 1309collapsed.</p> 1310 1311 1312<h4>Other APIs for action bar</h4> 1313<ul> 1314<li>{@link android.app.ActionBar#setHomeButtonEnabled setHomeButtonEnabled()} allows you to specify 1315whether the icon/logo behaves as a button to navigate home or “up" (pass “true" to make it behave as 1316a button).</li> 1317 1318<li>{@link android.app.ActionBar#setIcon setIcon()} and {@link android.app.ActionBar#setLogo 1319setLogo()} allow you to define the action bar icon or logo at runtime.</li> 1320 1321<li>{@link android.app.Fragment#setMenuVisibility Fragment.setMenuVisibility()} allows you to enable 1322or disable the visibility of the options menu items declared by the fragment. This is useful if the 1323fragment has been added to the activity, but is not visible, so the menu items should be 1324hidden.</li> 1325 1326<li>{@link android.app.FragmentManager#invalidateOptionsMenu 1327FragmentManager.invalidateOptionsMenu()} 1328allows you to invalidate the activity options menu during various states of the fragment lifecycle 1329in which using the equivalent method from {@link android.app.Activity} might not be available.</li> 1330</ul> 1331 1332 1333 1334 1335 1336 1337 1338 1339<h3 id="UI">User Interface and Views</h3> 1340 1341<p>Android 4.0 introduces a variety of new views and other UI components.</p> 1342 1343 1344<h4>GridLayout</h4> 1345 1346<p>{@link android.widget.GridLayout} is a new view group that places child views in a rectangular 1347grid. Unlike {@link android.widget.TableLayout}, {@link android.widget.GridLayout} relies on a flat 1348hierarchy and does not make use of intermediate views such as table rows for providing structure. 1349Instead, children specify which row(s) and column(s) they should occupy (cells can span multiple 1350rows and/or columns), and by default are laid out sequentially across the grid’s rows and columns. 1351The {@link android.widget.GridLayout} orientation determines whether sequential children are by 1352default laid out horizontally or vertically. Space between children may be specified either by using 1353instances of the new {@link android.widget.Space} view or by setting the relevant margin parameters 1354on children.</p> 1355 1356<p>See <a 1357href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/index.html">ApiDemos</a 1358> 1359for samples using {@link android.widget.GridLayout}.</p> 1360 1361 1362 1363<h4>TextureView</h4> 1364 1365<p>{@link android.view.TextureView} is a new view that allows you to display a content stream, such 1366as a video or an OpenGL scene. Although similar to {@link android.view.SurfaceView}, {@link 1367android.view.TextureView} is unique in that it behaves like a regular view, rather than creating a 1368separate window, so you can treat it like any other {@link android.view.View} object. For example, 1369you can apply transforms, animate it using {@link android.view.ViewPropertyAnimator}, or 1370adjust its opacity with {@link android.view.View#setAlpha setAlpha()}.</p> 1371 1372<p>Beware that {@link android.view.TextureView} works only within a hardware accelerated window.</p> 1373 1374<p>For more information, see the {@link android.view.TextureView} documentation.</p> 1375 1376 1377<h4>Switch widget</h4> 1378 1379<p>The new {@link android.widget.Switch} widget is a two-state toggle that users can drag to one 1380side or the other (or simply tap) to toggle an option between two states.</p> 1381 1382<p>You can use the {@code android:textOn} and {@code android:textOff} attributes to specify the text 1383to appear on the switch when in the on and off setting. The {@code android:text} attribute also 1384allows you to place a label alongside the switch.</p> 1385 1386<p>For a sample using switches, see the <a 1387href="{@docRoot}resources/samples/ApiDemos/res/layout/switches.html">switches.xml</a> layout file 1388and respective <a 1389href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/Switches.html">Switches 1390</a> activity.</p> 1391 1392 1393<h4>Popup menus</h4> 1394 1395<p>Android 3.0 introduced {@link android.widget.PopupMenu} to create short contextual menus that pop 1396up at an anchor point you specify (usually at the point of the item selected). Android 4.0 extends 1397the {@link android.widget.PopupMenu} with a couple useful features:</p> 1398<ul> 1399<li>You can now easily inflate the contents of a popup menu from an XML <a 1400href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a> with {@link 1401android.widget.PopupMenu#inflate inflate()}, passing it the menu resource ID.</li> 1402<li>You can also now create a {@link android.widget.PopupMenu.OnDismissListener} that receives a 1403callback when the menu is dismissed.</li> 1404</ul> 1405 1406 1407<h4>Preferences</h4> 1408 1409<p>A new {@link android.preference.TwoStatePreference} abstract class serves as the basis for 1410preferences that provide a two-state selection option. The new {@link 1411android.preference.SwitchPreference} is an extension of {@link 1412android.preference.TwoStatePreference} that provides a {@link android.widget.Switch} widget in the 1413preference view to allow users to toggle a setting on or off without the need to open an additional 1414preference screen or dialog. For example, the Settings application uses a {@link 1415android.preference.SwitchPreference} for the Wi-Fi and Bluetooth settings.</p> 1416 1417 1418 1419<h4>System themes</h4> 1420 1421<p>The default theme for all applications that target Android 4.0 (by setting either <a 1422href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> or 1423<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> to 1424{@code “14"} or higher) is now the 1425"device default" theme: {@link android.R.style#Theme_DeviceDefault Theme.DeviceDefault}. This may be 1426the dark Holo theme or a different dark theme defined by the specific device.</p> 1427 1428<p>The {@link android.R.style#Theme_Holo Theme.Holo} family of themes are guaranteed to not change 1429from one device to another when running the same version of Android. If you explicitly 1430apply any of the {@link android.R.style#Theme_Holo Theme.Holo} themes to your activities, you can 1431rest assured that these themes will not change character on different devices within the same 1432platform version.</p> 1433 1434<p>If you wish for your app to blend in with the overall device theme (such as when different OEMs 1435provide different default themes for the system), you should explicitly apply themes from the {@link 1436android.R.style#Theme_DeviceDefault Theme.DeviceDefault} family.</p> 1437 1438 1439<h4>Options menu button</h4> 1440 1441<p>Beginning with Android 4.0, you'll notice that handsets no longer require a Menu hardware button. 1442However, there's no need for you to worry about this if your existing application provides an <a 1443href="{@docRoot}guide/topics/ui/menus.html#options-menu">options menu</a> and expects there to be a 1444Menu button. To ensure that existing apps continue to work as they expect, the system provides an 1445on-screen Menu button for apps that were designed for older versions of Android.</p> 1446 1447<p>For the best user experience, new and updated apps should instead use the {@link 1448android.app.ActionBar} to provide access to menu items and set <a 1449href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to 1450{@code "14"} to take advantage of the latest framework default behaviors.</p> 1451 1452 1453 1454<h4>Controls for system UI visibility</h4> 1455 1456<p>Since the early days of Android, the system has managed a UI component known as the <em>status 1457bar</em>, which resides at the top of handset devices to deliver information such as the carrier 1458signal, time, notifications, and so on. Android 3.0 added the <em>system bar</em> for tablet 1459devices, which resides at the bottom of the screen to provide system navigation controls (Home, 1460Back, and so forth) and also an interface for elements traditionally provided by the status bar. In 1461Android 4.0, the system provides a new type of system UI called the <em>navigation bar</em>. You 1462might consider the navigation bar a re-tuned version of the system bar designed for 1463handsets—it provides navigation controls 1464for devices that don’t have hardware counterparts for navigating the system, but it leaves out the 1465system bar's notification UI and setting controls. As such, a device that provides the navigation 1466bar also has the status bar at the top.</p> 1467 1468<p>To this day, you can hide the status bar on handsets using the {@link 1469android.view.WindowManager.LayoutParams#FLAG_FULLSCREEN} flag. In Android 4.0, the APIs that control 1470the system bar’s visibility have been updated to better reflect the behavior of both the system bar 1471and navigation bar:</p> 1472<ul> 1473<li>The {@link android.view.View#SYSTEM_UI_FLAG_LOW_PROFILE} flag replaces the {@code 1474STATUS_BAR_HIDDEN} flag. When set, this flag enables “low profile" mode for the system bar or 1475navigation bar. Navigation buttons dim and other elements in the system bar also hide. Enabling 1476this is useful for creating more immersive games without distraction for the system navigation 1477buttons.</li> 1478 1479<li>The {@link android.view.View#SYSTEM_UI_FLAG_VISIBLE} flag replaces the {@code 1480STATUS_BAR_VISIBLE} flag to request the system bar or navigation bar be visible.</li> 1481 1482<li>The {@link android.view.View#SYSTEM_UI_FLAG_HIDE_NAVIGATION} is a new flag that requests 1483the navigation bar hide completely. Be aware that this works only for the <em>navigation bar</em> 1484used by some handsets (it does <strong>not</strong> hide the system bar on tablets). The navigation 1485bar returns to view as soon as the system receives user input. As such, this mode is useful 1486primarily for video playback or other cases in which the whole screen is needed but user input is 1487not required.</li> 1488</ul> 1489 1490<p>You can set each of these flags for the system bar and navigation bar by calling {@link 1491android.view.View#setSystemUiVisibility setSystemUiVisibility()} on any view in your activity. The 1492window manager combines (OR-together) all flags from all views in your window and 1493apply them to the system UI as long as your window has input focus. When your window loses input 1494focus (the user navigates away from your app, or a dialog appears), your flags cease to have effect. 1495Similarly, if you remove those views from the view hierarchy their flags no longer apply.</p> 1496 1497<p>To synchronize other events in your activity with visibility changes to the system UI (for 1498example, hide the action bar or other UI controls when the system UI hides), you should register a 1499{@link android.view.View.OnSystemUiVisibilityChangeListener} to be notified when the visibility 1500of the system bar or navigation bar changes.</p> 1501 1502<p>See the <a 1503href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/OverscanActivity.html"> 1504OverscanActivity</a> class for a demonstration of different system UI options.</p> 1505 1506 1507 1508 1509 1510<h3 id="Input">Input Framework</h3> 1511 1512<p>Android 4.0 adds support for cursor hover events and new stylus and mouse button events.</p> 1513 1514<h4>Hover events</h4> 1515 1516<p>The {@link android.view.View} class now supports “hover" events to enable richer interactions 1517through the use of pointer devices (such as a mouse or other devices that drive an on-screen 1518cursor).</p> 1519 1520<p>To receive hover events on a view, implement the {@link android.view.View.OnHoverListener} and 1521register it with {@link android.view.View#setOnHoverListener setOnHoverListener()}. When a hover 1522event occurs on the view, your listener receives a call to {@link 1523android.view.View.OnHoverListener#onHover onHover()}, providing the {@link android.view.View} that 1524received the event and a {@link android.view.MotionEvent} that describes the type of hover event 1525that occurred. The hover event can be one of the following:</p> 1526<ul> 1527<li>{@link android.view.MotionEvent#ACTION_HOVER_ENTER}</li> 1528<li>{@link android.view.MotionEvent#ACTION_HOVER_EXIT}</li> 1529<li>{@link android.view.MotionEvent#ACTION_HOVER_MOVE}</li> 1530</ul> 1531 1532<p>Your {@link android.view.View.OnHoverListener} should return true from {@link 1533android.view.View.OnHoverListener#onHover onHover()} if it handles the hover event. If your 1534listener returns false, then the hover event will be dispatched to the parent view as usual.</p> 1535 1536<p>If your application uses buttons or other widgets that change their appearance based on the 1537current state, you can now use the {@code android:state_hovered} attribute in a <a 1538href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">state list drawable</a> to 1539provide a different background drawable when a cursor hovers over the view.</p> 1540 1541<p>For a demonstration of the new hover events, see the <a 1542href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/Hover.html">Hover</a> class in 1543ApiDemos.</p> 1544 1545 1546<h4>Stylus and mouse button events</h4> 1547 1548<p>Android now provides APIs for receiving input from a stylus input device such as a digitizer 1549tablet peripheral or a stylus-enabled touch screen.</p> 1550 1551<p>Stylus input operates in a similar manner to touch or mouse input. When the stylus is in contact 1552with the digitizer, applications receive touch events just like they would when a finger is used to 1553touch the display. When the stylus is hovering above the digitizer, applications receive hover 1554events just like they would when a mouse pointer was being moved across the display when no buttons 1555are pressed.</p> 1556 1557<p>Your application can distinguish between finger, mouse, stylus and eraser input by querying the 1558“tool type" associated with each pointer in a {@link android.view.MotionEvent} using {@link 1559android.view.MotionEvent#getToolType getToolType()}. The currently defined tool types are: {@link 1560android.view.MotionEvent#TOOL_TYPE_UNKNOWN}, {@link android.view.MotionEvent#TOOL_TYPE_FINGER}, 1561{@link android.view.MotionEvent#TOOL_TYPE_MOUSE}, {@link android.view.MotionEvent#TOOL_TYPE_STYLUS}, 1562and {@link android.view.MotionEvent#TOOL_TYPE_ERASER}. By querying the tool type, your application 1563can choose to handle stylus input in different ways from finger or mouse input.</p> 1564 1565<p>Your application can also query which mouse or stylus buttons are pressed by querying the “button 1566state" of a {@link android.view.MotionEvent} using {@link android.view.MotionEvent#getButtonState 1567getButtonState()}. The currently defined button states are: {@link 1568android.view.MotionEvent#BUTTON_PRIMARY}, {@link android.view.MotionEvent#BUTTON_SECONDARY}, {@link 1569android.view.MotionEvent#BUTTON_TERTIARY}, {@link android.view.MotionEvent#BUTTON_BACK}, and {@link 1570android.view.MotionEvent#BUTTON_FORWARD}. For convenience, the back and forward mouse buttons are 1571automatically mapped to the {@link android.view.KeyEvent#KEYCODE_BACK} and {@link 1572android.view.KeyEvent#KEYCODE_FORWARD} keys. Your application can handle these keys to support 1573mouse button based back and forward navigation.</p> 1574 1575<p>In addition to precisely measuring the position and pressure of a contact, some stylus input 1576devices also report the distance between the stylus tip and the digitizer, the stylus tilt angle, 1577and the stylus orientation angle. Your application can query this information using {@link 1578android.view.MotionEvent#getAxisValue getAxisValue()} with the axis codes {@link 1579android.view.MotionEvent#AXIS_DISTANCE}, {@link android.view.MotionEvent#AXIS_TILT}, and {@link 1580android.view.MotionEvent#AXIS_ORIENTATION}.</p> 1581 1582<p>For a demonstration of tool types, button states and the new axis codes, see the <a 1583href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/TouchPaint.html">TouchPaint 1584</a> class in ApiDemos.</p> 1585 1586 1587 1588 1589 1590 1591<h3 id="Properties">Properties</h3> 1592 1593<p>The new {@link android.util.Property} class provides a fast, efficient, and easy way to specify a 1594property on any object that allows callers to generically set/get values on target objects. It also 1595allows the functionality of passing around field/method references and allows code to set/get values 1596of the property without knowing the details of what the fields/methods are.</p> 1597 1598<p>For example, if you want to set the value of field {@code bar} on object {@code foo}, you would 1599previously do this:</p> 1600<pre> 1601foo.bar = value; 1602</pre> 1603 1604<p>If you want to call the setter for an underlying private field {@code bar}, you would previously 1605do this:</p> 1606<pre> 1607foo.setBar(value); 1608</pre> 1609 1610<p>However, if you want to pass around the {@code foo} instance and have some other code set the 1611{@code bar} value, there is really no way to do it prior to Android 4.0.</p> 1612 1613<p>Using the {@link android.util.Property} class, you can declare a {@link android.util.Property} 1614object {@code BAR} on class {@code Foo} so that you can set the field on instance {@code foo} of 1615class {@code Foo} like this:</p> 1616<pre> 1617BAR.set(foo, value); 1618</pre> 1619 1620<p>The {@link android.view.View} class now leverages the {@link android.util.Property} class to 1621allow you to set various fields, such as transform properties that were added in Android 3.0 ({@link 1622android.view.View#ROTATION}, {@link android.view.View#ROTATION_X}, {@link 1623android.view.View#TRANSLATION_X}, etc.).</p> 1624 1625<p>The {@link android.animation.ObjectAnimator} class also uses the {@link android.util.Property} 1626class, so you can create an {@link android.animation.ObjectAnimator} with a {@link 1627android.util.Property}, which is faster, more efficient, and more type-safe than the string-based 1628approach.</p> 1629 1630 1631 1632 1633 1634 1635<h3 id="HwAccel">Hardware Acceleration</h3> 1636 1637<p>Beginning with Android 4.0, hardware acceleration for all windows is enabled by default if your 1638application has set either <a 1639href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> or 1640<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> to 1641{@code “14"} or higher. Hardware acceleration generally results in smoother animations, smoother 1642scrolling, and overall better performance and response to user interaction.</p> 1643 1644<p>If necessary, you can manually disable hardware acceleration with the <a 1645href="{@docRoot}guide/topics/manifest/activity-element.html#hwaccel">{@code hardwareAccelerated}</a> 1646attribute for individual <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code 1647<activity>}</a> elements or the <a 1648href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> 1649element. You can alternatively disable hardware acceleration for individual views by calling {@link 1650android.view.View#setLayerType setLayerType(LAYER_TYPE_SOFTWARE)}.</p> 1651 1652<p>For more information about hardware acceleration, including a list of unsupported drawing 1653operations, see the <a href="{@docRoot}guide/topics/graphics/hardware-accel.html">Hardware 1654Acceleration</a> document.</p> 1655 1656 1657 1658<h3 id="Jni">JNI Changes</h3> 1659 1660<p>In previous versions of Android, JNI local references weren’t indirect handles; Android used 1661direct pointers. This wasn't a problem as long as the garbage collector didn't move objects, but it 1662seemed to work because it made it possible to write buggy code. In Android 4.0, the system now uses 1663indirect references in order to detect these bugs.</p> 1664 1665<p>The ins and outs of JNI local references are described in “Local and Global References" in <a 1666href="{@docRoot}guide/practices/design/jni.html">JNI Tips</a>. In Android 4.0, <a 1667href="http://android-developers.blogspot.com/2011/07/debugging-android-jni-with-checkjni.html"> 1668CheckJNI</a> has been enhanced to detect these errors. Watch the <a 1669href="http://android-developers.blogspot.com/">Android Developers Blog</a> for an upcoming post 1670about common errors with JNI references and how you can fix them.</p> 1671 1672<p>This change in the JNI implementation only affects apps that target Android 4.0 by setting either 1673the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code 1674targetSdkVersion}</a> or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code 1675minSdkVersion}</a> to {@code “14"} or higher. If you’ve set these attributes to any lower value, 1676then JNI local references behave the same as in previous versions.</p> 1677 1678 1679 1680 1681 1682<h3 id="WebKit">WebKit</h3> 1683<ul> 1684<li>WebKit updated to version 534.30</li> 1685<li>Support for Indic fonts (Devanagari, Bengali, and Tamil, including the complex character support 1686needed for combining glyphs) in {@link android.webkit.WebView} and the built-in Browser</li> 1687<li>Support for Ethiopic, Georgian, and Armenian fonts in {@link android.webkit.WebView} and the 1688built-in Browser</li> 1689<li>Support for <a 1690href="http://google-opensource.blogspot.com/2009/05/introducing-webdriver.html">WebDriver</a> makes 1691it easier for you to test apps that use {@link android.webkit.WebView}</li> 1692</ul> 1693 1694 1695<h4>Android Browser</h4> 1696 1697<p>The Browser application adds the following features to support web applications:</p> 1698<ul> 1699<li>Updated V8 JavaScript compiler for faster performance</li> 1700<li>Plus other notable enhancements carried over from <a 1701href="{@docRoot}sdk/android-3.0.html">Android 17023.0</a> are now available for handsets: 1703<ul> 1704<li>Support for fixed position elements on all pages</li> 1705<li><a href="http://dev.w3.org/2009/dap/camera/">HTML media capture</a></li> 1706<li><a href="http://dev.w3.org/geo/api/spec-source-orientation.html">Device orientation 1707events</a></li> 1708<li><a href="http://www.w3.org/TR/css3-3d-transforms/">CSS 3D transformations</a></li> 1709</ul> 1710</li> 1711</ul> 1712 1713 1714 1715<h3 id="Permissions">Permissions</h3> 1716 1717<p>The following are new permissions:</p> 1718<ul> 1719<li>{@link android.Manifest.permission#ADD_VOICEMAIL}: Allows a voicemail service to add voicemail 1720messages to the device.</li> 1721<li>{@link android.Manifest.permission#BIND_TEXT_SERVICE}: A service that implements {@link 1722android.service.textservice.SpellCheckerService} must require this permission for itself.</li> 1723<li>{@link android.Manifest.permission#BIND_VPN_SERVICE}: A service that implements {@link 1724android.net.VpnService} must require this permission for itself.</li> 1725<li>{@link android.Manifest.permission#READ_PROFILE}: Provides read access to the {@link 1726android.provider.ContactsContract.Profile} provider.</li> 1727<li>{@link android.Manifest.permission#WRITE_PROFILE}: Provides write access to the {@link 1728android.provider.ContactsContract.Profile} provider.</li> 1729</ul> 1730 1731 1732 1733<h3 id="DeviceFeatures">Device Features</h3> 1734 1735<p>The following are new device features:</p> 1736<ul> 1737<li>{@link android.content.pm.PackageManager#FEATURE_WIFI_DIRECT}: Declares that the application 1738uses 1739Wi-Fi for peer-to-peer communications.</li> 1740</ul> 1741 1742 1743<div class="special" style="margin-top:3em"> 1744<p>For a detailed view of all API changes in Android {@sdkPlatformVersion} (API Level 1745{@sdkPlatformApiLevel}), see the <a 1746href="{@docRoot}sdk/api_diff/{@sdkPlatformApiLevel}/changes.html">API Differences Report</a>.</p> 1747</div> 1748 1749 1750<h2 id="Honeycomb">Previous APIs</h2> 1751 1752<p>In addition to everything above, Android 4.0 naturally supports all APIs from previous releases. 1753Because the Android 3.x platform is available only for large-screen devices, if you've 1754been developing primarily for handsets, then you might not be aware of all the APIs added to Android 1755in these recent releases.</p> 1756 1757<p>Here's a look at some of the most notable APIs you might have missed that are now available 1758on handsets as well:</p> 1759 1760<dl> 1761 <dt><a href="android-3.0.html">Android 3.0</a></dt> 1762 <dd> 1763 <ul> 1764 <li>{@link android.app.Fragment}: A framework component that allows you to separate distinct 1765elements of an activity into self-contained modules that define their own UI and lifecycle. See the 1766<a href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a> developer guide.</li> 1767 <li>{@link android.app.ActionBar}: A replacement for the traditional title bar at the top of 1768the activity window. It includes the application logo in the left corner and provides a new 1769interface for menu items. See the 1770<a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guide.</li> 1771 <li>{@link android.content.Loader}: A framework component that facilitates asynchronous 1772loading of data in combination with UI components to dynamically load data without blocking the 1773main thread. See the 1774<a href="{@docRoot}guide/topics/fundamentals/loaders.html">Loaders</a> developer guide.</li> 1775 <li>System clipboard: Applications can copy and paste data (beyond mere text) to and from 1776the system-wide clipboard. Clipped data can be plain text, a URI, or an intent. See the 1777<a href="{@docRoot}guide/topics/clipboard/copy-paste.html">Copy and Paste</a> developer guide.</li> 1778 <li>Drag and drop: A set of APIs built into the view framework that facilitates drag and drop 1779operations. See the 1780<a href="{@docRoot}guide/topics/ui/drag-drop.html">Drag and Drop</a> developer guide.</li> 1781 <li>An all new flexible animation framework allows you to animate arbitrary properties of any 1782object (View, Drawable, Fragment, Object, or anything else) and define animation aspects such 1783as duration, interpolation, repeat and more. The new framework makes Animations in Android 1784simpler than ever. See the 1785<a href="{@docRoot}guide/topics/graphics/prop-animation.html">Property Animation</a> developer 1786guide.</li> 1787 <li>RenderScript graphics and compute engine: RenderScript offers a high performance 3D 1788graphics rendering and compute API at the native level, which you write in the C (C99 standard), 1789providing the type of performance you expect from a native environment while remaining portable 1790across various CPUs and GPUs. See the 1791<a href="{@docRoot}guide/topics/renderscript/index.html">RenderScript</a> developer 1792guide.</li> 1793 <li>Hardware accelerated 2D graphics: You can now enable the OpenGL renderer for your 1794application by setting {android:hardwareAccelerated="true"} in your manifest element's <a 1795href="{@docRoot}guide/topics/manifest/application-element.html"><code><application></code></a> 1796element or for individual <a 1797href="{@docRoot}guide/topics/manifest/activity-element.html"><code><activity></code></a> 1798elements. This results 1799in smoother animations, smoother scrolling, and overall better performance and response to user 1800interaction. 1801 <p class="note"><strong>Note:</strong> If you set your application's <a 1802href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a 1803href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to 1804{@code "14"} or higher, hardware acceleration is enabled by default.</p></li> 1805 <li>And much, much more. See the <a href="android-3.0.html">Android 3.0 Platform</a> 1806notes for more information.</li> 1807 </ul> 1808 </dd> 1809 1810 <dt><a href="android-3.1.html">Android 3.1</a></dt> 1811 <dd> 1812 <ul> 1813 <li>USB APIs: Powerful new APIs for integrating connected peripherals with 1814Android applications. The APIs are based on a USB stack and services that are 1815built into the platform, including support for both USB host and device interactions. See the <a 1816href="{@docRoot}guide/topics/usb/index.html">USB Host and Accessory</a> developer guide.</li> 1817 <li>MTP/PTP APIs: Applications can interact directly with connected cameras and other PTP 1818devices to receive notifications when devices are attached and removed, manage files and storage on 1819those devices, and transfer files and metadata to and from them. The MTP API implements the PTP 1820(Picture Transfer Protocol) subset of the MTP (Media Transfer Protocol) specification. See the 1821{@link android.mtp} documentation.</li> 1822 <li>RTP APIs: Android exposes an API to its built-in RTP (Real-time Transport Protocol) stack, 1823which applications can use to manage on-demand or interactive data streaming. In particular, apps 1824that provide VOIP, push-to-talk, conferencing, and audio streaming can use the API to initiate 1825sessions and transmit or receive data streams over any available network. See the {@link 1826android.net.rtp} documentation.</li> 1827 <li>Support for joysticks and other generic motion inputs.</li> 1828 <li>See the <a href="android-3.1.html">Android 3.1 Platform</a> 1829notes for many more new APIs.</li> 1830 </ul> 1831 </dd> 1832 1833 <dt><a href="android-3.2.html">Android 3.2</a></dt> 1834 <dd> 1835 <ul> 1836 <li>New screens support APIs that give you more control over how your applications are 1837displayed across different screen sizes. The API extends the existing screen support model with the 1838ability to precisely target specific screen size ranges by dimensions, measured in 1839density-independent pixel units (such as 600dp or 720dp wide), rather than by their generalized 1840screen sizes (such as large or xlarge). For example, this is important in order to help you 1841distinguish between a 5" device and a 7" device, which would both traditionally be bucketed as 1842"large" screens. See the blog post, <a 1843href="http://android-developers.blogspot.com/2011/07/new-tools-for-managing-screen-sizes.html"> 1844New Tools for Managing Screen Sizes</a>.</li> 1845 <li>New constants for <a 1846href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> to 1847declare landscape or portrait screen orientation requirements.</li> 1848 <li>The device "screen size" configuration now changes during a screen orientation 1849change. If your app targets API level 13 or higher, you must handle the {@code "screenSize"} 1850configuration change if you also want to handle the {@code "orientation"} configuration change. See 1851<a href="{@docRoot}guide/topics/manifest/activity-element.html#config">{@code 1852android:configChanges}</a> for more information.</li> 1853 <li>See the <a href="android-3.2.html">Android 3.2 Platform</a> 1854notes for other new APIs.</li> 1855 </ul> 1856 </dd> 1857 1858</dl> 1859 1860 1861 1862 1863<h2 id="api-level">API Level</h2> 1864 1865<p>The Android {@sdkPlatformVersion} API is assigned an integer 1866identifier—<strong>{@sdkPlatformApiLevel}</strong>—that is stored in the system itself. 1867This identifier, called the "API level", allows the system to correctly determine whether an 1868application is compatible with the system, prior to installing the application. </p> 1869 1870<p>To use APIs introduced in Android {@sdkPlatformVersion} in your application, you need compile the 1871application against an Android platform that supports API level {@sdkPlatformApiLevel} or 1872higher. Depending on your needs, you might also need to add an 1873<code>android:minSdkVersion="{@sdkPlatformApiLevel}"</code> attribute to the 1874<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> 1875element.</p> 1876 1877<p>For more information, see the <a href="{@docRoot}guide/appendix/api-levels.html">API Levels</a> 1878document. </p> 1879 1880 1881<h2 id="apps">Built-in Applications</h2> 1882 1883<p>The system image included in the downloadable platform provides these 1884built-in applications:</p> 1885 1886<table style="border:0;padding-bottom:0;margin-bottom:0;"> 1887<tr> 1888<td style="border:0;padding-bottom:0;margin-bottom:0;"> 1889<ul> 1890<li>API Demos</li> 1891<li>Browser</li> 1892<li>Calculator</li> 1893<li>Calendar</li> 1894<li>Camera</li> 1895<li>Clock</li> 1896<li>Custom Locale</li> 1897<li>Dev Tools</li> 1898<li>Downloads</li> 1899<li>Email</li> 1900<li>Gallery</li> 1901</ul> 1902</td> 1903<td style="border:0;padding-bottom:0;margin-bottom:0;padding-left:5em;"> 1904<ul> 1905<li>Gestures Builder</li> 1906<li>Messaging</li> 1907<li>Music</li> 1908<li>People</li> 1909<li>Phone</li> 1910<li>Search</li> 1911<li>Settings</li> 1912<li>Speech Recorder</li> 1913<li>Widget Preview</li> 1914</ul> 1915</td> 1916</tr> 1917</table> 1918 1919 1920<h2 id="locs" style="margin-top:.75em;">Locales</h2> 1921 1922<p>The system image included in the downloadable SDK platform provides a variety of built-in 1923locales. In some cases, region-specific strings are available for the locales. In other cases, a 1924default version of the language is used. The languages that are available in the Android 3.0 system 1925image are listed below (with <em>language</em>_<em>country/region</em> locale descriptor).</p> 1926 1927<table style="border:0;padding-bottom:0;margin-bottom:0;"> 1928<tr> 1929<td style="border:0;padding-bottom:0;margin-bottom:0;"> 1930<ul> 1931<li>Arabic, Egypt (ar_EG)</li> 1932<li>Arabic, Israel (ar_IL)</li> 1933<li>Bulgarian, Bulgaria (bg_BG)</li> 1934<li>Catalan, Spain (ca_ES)</li> 1935<li>Czech, Czech Republic (cs_CZ)</li> 1936<li>Danish, Denmark(da_DK)</li> 1937<li>German, Austria (de_AT)</li> 1938<li>German, Switzerland (de_CH)</li> 1939<li>German, Germany (de_DE)</li> 1940<li>German, Liechtenstein (de_LI)</li> 1941<li>Greek, Greece (el_GR)</li> 1942<li>English, Australia (en_AU)</li> 1943<li>English, Canada (en_CA)</li> 1944<li>English, Britain (en_GB)</li> 1945<li>English, Ireland (en_IE)</li> 1946<li>English, India (en_IN)</li> 1947<li>English, New Zealand (en_NZ)</li> 1948<li>English, Singapore(en_SG)</li> 1949<li>English, US (en_US)</li> 1950<li>English, Zimbabwe (en_ZA)</li> 1951<li>Spanish (es_ES)</li> 1952<li>Spanish, US (es_US)</li> 1953<li>Finnish, Finland (fi_FI)</li> 1954<li>French, Belgium (fr_BE)</li> 1955<li>French, Canada (fr_CA)</li> 1956<li>French, Switzerland (fr_CH)</li> 1957<li>French, France (fr_FR)</li> 1958<li>Hebrew, Israel (he_IL)</li> 1959<li>Hindi, India (hi_IN)</li> 1960</ul> 1961</td> 1962<td style="border:0;padding-bottom:0;margin-bottom:0;padding-left:5em;"> 1963<li>Croatian, Croatia (hr_HR)</li> 1964<li>Hungarian, Hungary (hu_HU)</li> 1965<li>Indonesian, Indonesia (id_ID)</li> 1966<li>Italian, Switzerland (it_CH)</li> 1967<li>Italian, Italy (it_IT)</li> 1968<li>Japanese (ja_JP)</li> 1969<li>Korean (ko_KR)</li> 1970<li>Lithuanian, Lithuania (lt_LT)</li> 1971<li>Latvian, Latvia (lv_LV)</li> 1972<li>Norwegian bokmål, Norway (nb_NO)</li> 1973<li>Dutch, Belgium (nl_BE)</li> 1974<li>Dutch, Netherlands (nl_NL)</li> 1975<li>Polish (pl_PL)</li> 1976<li>Portuguese, Brazil (pt_BR)</li> 1977<li>Portuguese, Portugal (pt_PT)</li> 1978<li>Romanian, Romania (ro_RO)</li> 1979<li>Russian (ru_RU)</li></li> 1980<li>Slovak, Slovakia (sk_SK)</li> 1981<li>Slovenian, Slovenia (sl_SI)</li> 1982<li>Serbian (sr_RS)</li> 1983<li>Swedish, Sweden (sv_SE)</li> 1984<li>Thai, Thailand (th_TH)</li> 1985<li>Tagalog, Philippines (tl_PH)</li> 1986<li>Turkish, Turkey (tr_TR)</li> 1987<li>Ukrainian, Ukraine (uk_UA)</li> 1988<li>Vietnamese, Vietnam (vi_VN)</li> 1989<li>Chinese, PRC (zh_CN)</li> 1990<li>Chinese, Taiwan (zh_TW)</li> 1991</td> 1992</tr> 1993</table> 1994 1995<p class="note"><strong>Note:</strong> The Android platform may support more 1996locales than are included in the SDK system image. All of the supported locales 1997are available in the <a href="http://source.android.com/">Android Open Source 1998Project</a>.</p> 1999 2000<h2 id="skins">Emulator Skins</h2> 2001 2002<p>The downloadable platform includes the following emulator skins:</p> 2003 2004<ul> 2005 <li> 2006 QVGA (240x320, low density, small screen) 2007 </li> 2008 <li> 2009 WQVGA400 (240x400, low density, normal screen) 2010 </li> 2011 <li> 2012 WQVGA432 (240x432, low density, normal screen) 2013 </li> 2014 <li> 2015 HVGA (320x480, medium density, normal screen) 2016 </li> 2017 <li> 2018 WVGA800 (480x800, high density, normal screen) 2019 </li> 2020 <li> 2021 WVGA854 (480x854 high density, normal screen) 2022 </li> 2023 <li> 2024 WXGA720 (1280x720, extra-high density, normal screen) <span class="new">new</span> 2025 </li> 2026 <li> 2027 WSVGA (1024x600, medium density, large screen) <span class="new">new</span> 2028 </li> 2029 <li> 2030 WXGA (1280x800, medium density, xlarge screen) 2031 </li> 2032</ul> 2033 2034<p>To test your application on an emulator that represents the latest Android device, you can create 2035an AVD with the new WXGA720 skin (it's an xhdpi, normal screen device). Note that the emulator 2036currently doesn't support the new on-screen navigation bar for devices without hardware navigation 2037buttons, so when using this skin, you must use keyboard keys <em>Home</em> for the Home button, 2038<em>ESC</em> for the Back button, and <em>F2</em> or <em>Page-up</em> for the Menu button.</p> 2039 2040<p>However, due to performance issues in the emulator when running high-resolution screens such as 2041the one for the WXGA720 skin, we recommend that you primarily use the traditional WVGA800 skin 2042(hdpi, normal screen) to test your application.</p> 2043 2044
