1 page.title=Android 4.0 Platform 2 sdk.platform.version=4.0 3 sdk.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 23 href="{@docRoot}sdk/api_diff/14/changes.html">API 24 Differences 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 34 developers. Besides all the new features and APIs discussed below, Android 4.0 is an important 35 platform release because it brings the extensive set of APIs and Holographic themes from Android 3.x 36 to smaller screens. As an app developer, you now have a single platform and unified API framework 37 that enables you to develop and publish your application with a single APK that provides an 38 optimized user experience for handsets, tablets, and more, when running the same version of 39 Android—Android 4.0 (API level 14) or greater. </p> 40 41 <p>The Android {@sdkPlatformVersion} platform is available as a 42 downloadable component for the Android SDK so you can begin developing and testing your 43 applications on Android 4.0 with the Android emulator. The downloadable platform includes 44 an Android library and system image, as well as a set of emulator skins and 45 more. The downloadable platform does not include any external libraries.</p> 46 47 <p>To start developing or testing against Android {@sdkPlatformVersion}, 48 use the Android SDK Manager to download the platform into your SDK. For more 49 information, see <a href="{@docRoot}sdk/adding-components.html">Adding SDK 50 Components</a>. If you are new to Android, <a 51 href="{@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 54 Android application, please test your application on Android {@sdkPlatformVersion} as 55 soon as possible to be sure your application provides the best 56 experience 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 66 have 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" 73 class="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" 100 class="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 141 extended to support new social-oriented features such as a personal profile for the device owner and 142 the ability for users to invite individual contacts to social networks that are installed on the 143 device.</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 150 can contribute to the user's profile data by creating a new {@link 151 android.provider.ContactsContract.RawContacts} entry within the {@link 152 android.provider.ContactsContract.Profile}. That is, raw contacts that represent the device user do 153 not belong in the traditional raw contacts table defined by the {@link 154 android.provider.ContactsContract.RawContacts} Uri; instead, you must add a profile raw contact in 155 the table at {@link android.provider.ContactsContract.Profile#CONTENT_RAW_CONTACTS_URI}. Raw 156 contacts 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 159 android.Manifest.permission#WRITE_PROFILE} permission. Likewise, in order to read from the profile 160 table, you must request the {@link android.Manifest.permission#READ_PROFILE} permission. However, 161 most apps should not need to read the user profile, even when contributing data to the 162 profile. Reading the user profile is a sensitive permission and you should expect users to be 163 skeptical 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 169 to invoke an action that indicates the user wants to add a contact to a social network. The app 170 receiving the app uses it to invite the specified contact to that 171 social network. Most apps will be on the receiving-end of this operation. For example, the 172 built-in People app invokes the invite intent when the user selects "Add connection" for a specific 173 social 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 176 sync contact information from your social network. You must then indicate to the system that your 177 app responds to the {@link android.provider.ContactsContract.Intents#INVITE_CONTACT} intent by 178 adding the {@code inviteContactActivity} attribute to your apps sync configuration file, with a 179 fully-qualified name of the activity that the system should start when sending the invite intent. 180 The activity that starts can then retrieve the URI for the contact in question from the intents 181 data and perform the necessary work to invite that contact to the network or add the person to the 182 users connections.</p> 183 184 <p>See the <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">Sample Sync 185 Adapter</a> app for an example (specifically, see the <a 186 href="{@docRoot}resources/samples/SampleSyncAdapter/res/xml-v14/contacts.html">contacts.xml</a> 187 file).</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 193 contact record, the system processes it into both a 96x96 thumbnail (as it has previously) and a 194 256x256 "display photo" that's stored in a new file-based photo store (the exact dimensions that the 195 system chooses may vary in the future). You can add a large photo to a contact by putting a large 196 photo in the usual {@link android.provider.ContactsContract.CommonDataKinds.Photo#PHOTO} column of a 197 data row, which the system will then process into the appropriate thumbnail and display photo 198 records.</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 204 how often the user uses particular methods of contacting people, such as how often the user uses 205 each phone number or e-mail address. This information helps improve the ranking for each contact 206 method 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, 215 reminders 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, 218 some of the most compelling use cases are sync adapters that synchronize the user's calendar from 219 other calendar services with the Calendar Provider, in order to offer a unified location for all the 220 user's events. Google Calendar events, for example, are synchronized with the Calendar Provider by 221 the Google Calendar Sync Adapter, allowing these events to be viewed with Android's built-in 222 Calendar app.</p> 223 224 <p>The data model for calendars and event-related information in the Calendar Provider is 225 defined by {@link android.provider.CalendarContract}. All the users calendar data is stored in a 226 number 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 230 information. Each row in this table contains the details for a single calendar, such as the name, 231 color, sync information, and so on.</li> 232 233 <li>The {@link android.provider.CalendarContract.Events} table holds event-specific information. 234 Each row in this table contains the information for a single event, such as the 235 event title, location, start time, end time, and so on. The event can occur one time or recur 236 multiple times. Attendees, reminders, and extended properties are stored in separate tables and 237 use the events {@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 240 occurrences of an event. Each row in this table represents a single occurrence. For one-time events 241 there is a one-to-one mapping of instances to events. For recurring events, multiple rows are 242 automatically 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 245 information. Each row represents a single guest of an event. It specifies the type of guest the 246 person is and the persons response for the event.</li> 247 248 <li>The {@link android.provider.CalendarContract.Reminders} table holds the alert/notification data. 249 Each row represents a single alert for an event. An event can have multiple reminders. The number of 250 reminders per event is specified in {@code MAX_REMINDERS}, which is set by the sync adapter that 251 owns the given calendar. Reminders are specified in number-of-minutes before the event is 252 scheduled and specify an alarm method such as to use an alert, email, or SMS to remind 253 the user.</li> 254 255 <li>The {@link android.provider.CalendarContract.ExtendedProperties} table hold opaque data fields 256 used by the sync adapter. The provider takes no action with items in this table except to delete 257 them when their related events are deleted.</li> 258 </ul> 259 260 <p>To access a users calendar data with the Calendar Provider, your application must request 261 the {@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 users calendar, you can use an {@link 268 android.content.Intent#ACTION_INSERT} intent with the data defined by {@link 269 android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI} in order to start an 270 activity in the Calendar app that creates new events. Using the intent does not require any 271 permission 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 275 event</li> 276 <li>{@link 277 android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_BEGIN_TIME}: 278 Event begin time in milliseconds from the 279 epoch</li> 280 <li>{@link 281 android.provider.CalendarContract#EXTRA_EVENT_END_TIME CalendarContract.EXTRA_EVENT_END_TIME}: Event 282 end time in milliseconds from the epoch</li> 283 <li>{@link android.provider.CalendarContract.EventsColumns#EVENT_LOCATION Events.EVENT_LOCATION}: 284 Location of the event</li> 285 <li>{@link android.provider.CalendarContract.EventsColumns#DESCRIPTION Events.DESCRIPTION}: Event 286 description</li> 287 <li>{@link android.content.Intent#EXTRA_EMAIL Intent.EXTRA_EMAIL}: Email addresses of those to 288 invite</li> 289 <li>{@link android.provider.CalendarContract.EventsColumns#RRULE Events.RRULE}: The recurrence 290 rule for the event</li> 291 <li>{@link android.provider.CalendarContract.EventsColumns#ACCESS_LEVEL Events.ACCESS_LEVEL}: 292 Whether the event is private or public</li> 293 <li>{@link android.provider.CalendarContract.EventsColumns#AVAILABILITY Events.AVAILABILITY}: 294 Whether 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 303 device, in order to present all the user's voicemails in a single visual presentation. For instance, 304 its possible that a user has multiple voicemail sources, such as 305 one from the phones service provider and others from VoIP or other alternative voice 306 services. These apps can use the Voicemail Provider APIs to add their voicemails to the device. The 307 built-in Phone application then presents all voicemails to the user in a unified presentation. 308 Although the systems Phone application is the only application that can read all the voicemails, 309 each application that provides voicemails can read those that it has added to the system (but cannot 310 read 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 313 system, the only third-party apps that should use the voicemail APIs are those that have voicemail 314 to deliver to the user.</p> 315 316 <p>The {@link android.provider.VoicemailContract} class defines the content provider for the 317 Voicemail Provder. The subclasses {@link android.provider.VoicemailContract.Voicemails} and {@link 318 android.provider.VoicemailContract.Status} provide tables in which apps can 319 insert 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 321 Demo</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, 330 videos, 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 336 videos. For example, image effects allow you to easily fix red-eye, convert an image to grayscale, 337 adjust brightness, adjust saturation, rotate an image, apply a fisheye effect, and much more. The 338 system 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 341 must have a valid OpenGL context before it can use the effects APIs. The textures to which you apply 342 effects may be from bitmaps, videos or even the camera. However, there are certain restrictions that 343 textures 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 350 an 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 354 EffectContext.createWithCurrentGlContext()} from your OpenGL ES 2.0 context.</li> 355 <li>Use the returned {@link android.media.effect.EffectContext} to call {@link 356 android.media.effect.EffectContext#getFactory EffectContext.getFactory()}, which returns an instance 357 of {@link android.media.effect.EffectFactory}.</li> 358 <li>Call {@link android.media.effect.EffectFactory#createEffect createEffect()}, passing it an 359 effect name from @link android.media.effect.EffectFactory}, such as {@link 360 android.media.effect.EffectFactory#EFFECT_FISHEYE} or {@link 361 android.media.effect.EffectFactory#EFFECT_VIGNETTE}.</li> 362 </ol> 363 364 <p>You can adjust an effects parameters by calling {@link android.media.effect.Effect#setParameter 365 setParameter()} and passing a parameter name and parameter value. Each type of effect accepts 366 different parameters, which are documented with the effect name. For example, {@link 367 android.media.effect.EffectFactory#EFFECT_FISHEYE} has one parameter for the {@code scale} of the 368 distortion.</p> 369 370 <p>To apply an effect on a texture, call {@link android.media.effect.Effect#apply apply()} on the 371 {@link 372 android.media.effect.Effect} and pass in the input texture, its width and height, and the output 373 texture. The input texture must be bound to a {@link android.opengl.GLES20#GL_TEXTURE_2D} texture 374 image (usually done by calling the {@link android.opengl.GLES20#glTexImage2D glTexImage2D()} 375 function). You may provide multiple mipmap levels. If the output texture has not been bound to a 376 texture image, it will be automatically bound by the effect as a {@link 377 android.opengl.GLES20#GL_TEXTURE_2D} and with one mipmap level (0), which will have the same 378 size as the input.</p> 379 380 <p>All effects listed in {@link android.media.effect.EffectFactory} are guaranteed to be supported. 381 However, some additional effects available from external libraries are not supported by all devices, 382 so 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 389 controls from remote control clients such as the device lock screen. Media players can also expose 390 information about the media currently playing for display on the remote control, such as track 391 information and album art.</p> 392 393 <p>To enable remote control clients for your media player, instantiate a {@link 394 android.media.RemoteControlClient} with its constructor, passing it a {@link 395 android.app.PendingIntent} that broadcasts {@link 396 android.content.Intent#ACTION_MEDIA_BUTTON}. The intent must also declare the explicit {@link 397 android.content.BroadcastReceiver} component in your app that handles the {@link 398 android.content.Intent#ACTION_MEDIA_BUTTON} event.</p> 399 400 <p>To declare which media control inputs your player can handle, you must call {@link 401 android.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 404 android.media.RemoteControlClient#FLAG_KEY_MEDIA_NEXT}.</p> 405 406 <p>You must then register your {@link android.media.RemoteControlClient} by passing it to {@link 407 android.media.AudioManager#registerRemoteControlClient MediaManager.registerRemoteControlClient()}. 408 Once registered, the broadcast receiver you declared when you instantiated the {@link 409 android.media.RemoteControlClient} will receive {@link android.content.Intent#ACTION_MEDIA_BUTTON} 410 events when a button is pressed from a remote control. The intent you receive includes the {@link 411 android.view.KeyEvent} for the media key pressed, which you can retrieve from the intent with {@link 412 android.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 415 android.media.RemoteControlClient#editMetadata editMetaData()} and add metadata to the returned 416 {@link android.media.RemoteControlClient.MetadataEditor}. You can supply a bitmap for media artwork, 417 numerical information such as elapsed time, and text information such as the track title. For 418 information on available keys see the {@code METADATA_KEY_*} flags in {@link 419 android.media.MediaMetadataRetriever}.</p> 420 421 <p>For a sample implementation, see the <a 422 href="{@docRoot}resources/samples/RandomMusicPlayer/index.html">Random Music Player</a>, which 423 provides compatibility logic such that it enables the remote control client on Android 4.0 424 devices 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 431 android.Manifest.permission#INTERNET} permission. If you use {@link android.media.MediaPlayer} to 432 play content from the Internet, be sure to add the {@link android.Manifest.permission#INTERNET} 433 permission to your manifest or else your media playback will not work beginning with Android 434 4.0.</li> 435 436 <li>{@link android.media.MediaPlayer#setSurface(Surface) setSurface()} allows you define a {@link 437 android.view.Surface} to behave as the video sink.</li> 438 439 <li>{@link android.media.MediaPlayer#setDataSource(Context,Uri,Map) setDataSource()} allows you to 440 send 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 456 Formats</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 465 focus and metering areas.</p> 466 467 468 <h4>Face detection</h4> 469 470 <p>Camera apps can now enhance their abilities with Androids face detection APIs, which not 471 only 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 475 android.hardware.Camera.FaceDetectionListener} by calling {@link 476 android.hardware.Camera#setFaceDetectionListener setFaceDetectionListener()}. You can then start 477 your camera surface and start detecting faces by calling {@link 478 android.hardware.Camera#startFaceDetection}.</p> 479 480 <p>When the system detects one or more faces in the camera scene, it calls the {@link 481 android.hardware.Camera.FaceDetectionListener#onFaceDetection onFaceDetection()} callback in your 482 implementation 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 486 the 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 489 current field of view</li> 490 <li>An integer betwen 1 and 100 that indicates how confident the system is that the object is a 491 human 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 494 located</li> 495 </ul> 496 497 <p class="note"><strong>Note:</strong> Face detection may not be supported on some 498 devices, so you should check by calling {@link 499 android.hardware.Camera.Parameters#getMaxNumDetectedFaces()} and ensure the return 500 value is greater than zero. Also, some devices may not support identification of eyes and mouth, 501 in 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 507 balance 508 and auto-exposure. Both features use the new {@link android.hardware.Camera.Area} class to specify 509 the region of the cameras current view that should be focused or metered. An instance of the {@link 510 android.hardware.Camera.Area} class defines the bounds of the area with a {@link 511 android.graphics.Rect} and the area's weight—representing the level of importance of that 512 area, 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 515 android.hardware.Camera.Parameters#getMaxNumFocusAreas} or {@link 516 android.hardware.Camera.Parameters#getMaxNumMeteringAreas}, respectively. If these return zero, then 517 the device does not support the corresponding feature.</p> 518 519 <p>To specify the focus or metering areas to use, simply call {@link 520 android.hardware.Camera.Parameters#setFocusAreas setFocusAreas()} or {@link 521 android.hardware.Camera.Parameters#setMeteringAreas setMeteringAreas()}. Each take a {@link 522 java.util.List} of {@link android.hardware.Camera.Area} objects that indicate the areas to consider 523 for focus or metering. For example, you might implement a feature that allows the user to set the 524 focus area by touching an area of the preview, which you then translate to an {@link 525 android.hardware.Camera.Area} object and request that the camera focus on that area of the scene. 526 The 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 532 camera app, pass {@link android.hardware.Camera.Parameters#FOCUS_MODE_CONTINUOUS_PICTURE} 533 to {@link android.hardware.Camera.Parameters#setFocusMode setFocusMode()}. When ready to capture 534 a photo, call {@link android.hardware.Camera#autoFocus autoFocus()}. Your {@link 535 android.hardware.Camera.AutoFocusCallback} immediately receives a callback to indicate whether 536 focus was achieved. To resume CAF after receiving the callback, you must call {@link 537 android.hardware.Camera#cancelAutoFocus()}.</p> 538 539 <p class="note"><strong>Note:</strong> Continuous auto focus is also supported when capturing 540 video, using {@link android.hardware.Camera.Parameters#FOCUS_MODE_CONTINUOUS_VIDEO}, which was 541 added 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 548 takePicture()} to save a photo without interrupting the video session. Before doing so, you should 549 call {@link android.hardware.Camera.Parameters#isVideoSnapshotSupported} to be sure the hardware 550 supports it.</li> 551 552 <li>You can now lock auto exposure and white balance with {@link 553 android.hardware.Camera.Parameters#setAutoExposureLock setAutoExposureLock()} and {@link 554 android.hardware.Camera.Parameters#setAutoWhiteBalanceLock setAutoWhiteBalanceLock()} to prevent 555 these properties from changing.</li> 556 557 <li>You can now call {@link android.hardware.Camera#setDisplayOrientation 558 setDisplayOrientation()} while the camera preview is running. Previously, you could call this 559 only 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}: 567 This indicates that the user has captured a new photo. The built-in Camera app invokes this 568 broadcast after a photo is captured and third-party camera apps should also broadcast this intent 569 after capturing a photo.</li> 570 <li>{@link android.hardware.Camera#ACTION_NEW_VIDEO Camera.ACTION_NEW_VIDEO}: 571 This indicates that the user has captured a new video. The built-in Camera app invokes this 572 broadcast after a video is recorded and third-party camera apps should also broadcast this intent 573 after 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 583 another (a process also known as NDEF Push"). The data transfer is initiated when two 584 Android-powered devices that support Android Beam are in close proximity (about 4 cm), usually with 585 their backs touching. The data inside the NDEF message can contain any data that you wish to share 586 between devices. For example, the People app shares contacts, YouTube shares videos, and Browser 587 shares URLs using Android Beam.</p> 588 589 <p>To transmit data between devices using Android Beam, you need to create an {@link 590 android.nfc.NdefMessage} that contains the information you want to share while your activity is in 591 the foreground. You must then pass the {@link android.nfc.NdefMessage} to the system in one of two 592 ways:</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 597 the message you want to send. For instance, you might call this method and pass it your {@link 598 android.nfc.NdefMessage} during your activitys {@link android.app.Activity#onCreate onCreate()} 599 method. Then, whenever Android Beam is activated with another device while the activity is in the 600 foreground, 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 604 implementation of the {@link 605 android.nfc.NfcAdapter.CreateNdefMessageCallback#createNdefMessage createNdefMessage()} 606 method returns the {@link android.nfc.NdefMessage} you want to send. Then pass the {@link 607 android.nfc.NfcAdapter.CreateNdefMessageCallback} implementation to {@link 608 android.nfc.NfcAdapter#setNdefPushMessageCallback setNdefPushMessageCallback()}.</p> 609 <p>In this case, when Android Beam is activated with another device while your activity is in the 610 foreground, the system calls {@link 611 android.nfc.NfcAdapter.CreateNdefMessageCallback#createNdefMessage createNdefMessage()} to retrieve 612 the {@link android.nfc.NdefMessage} you want to send. This allows you to define the {@link 613 android.nfc.NdefMessage} to deliver only once Android Beam is initiated, in case the contents 614 of 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 618 message to the other device, you can implement {@link 619 android.nfc.NfcAdapter.OnNdefPushCompleteCallback} and set it with {@link 620 android.nfc.NfcAdapter#setOnNdefPushCompleteCallback setNdefPushCompleteCallback()}. The system will 621 then call {@link android.nfc.NfcAdapter.OnNdefPushCompleteCallback#onNdefPushComplete 622 onNdefPushComplete()} 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 625 tags. The system invokes an intent with the {@link android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} 626 action to start an activity, with either a URL or a MIME type set according to the first {@link 627 android.nfc.NdefRecord} in the {@link android.nfc.NdefMessage}. For the activity you want to 628 respond, you can declare intent filters for the URLs or MIME types your app cares about. For more 629 information about Tag Dispatch see the <a 630 href="{@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 633 method {@link android.nfc.NdefRecord#createUri createUri} to construct a new {@link 634 android.nfc.NdefRecord} based on either a string or a {@link android.net.Uri} object. If the URI is 635 a special format that you want your application to also receive during an Android Beam event, you 636 should create an intent filter for your activity using the same URI scheme in order to receive the 637 incoming NDEF message.</p> 638 639 <p>You should also pass an Android application record" with your {@link android.nfc.NdefMessage} in 640 order to guarantee that your application handles the incoming NDEF message, even if other 641 applications filter for the same intent action. You can create an Android application record by 642 calling {@link android.nfc.NdefRecord#createApplicationRecord createApplicationRecord()}, passing it 643 your applications package name. When the other device receives the NDEF message with the 644 application record and multiple applications contain activities that handle the specified intent, 645 the system always delivers the message to the activity in your application (based on the matching 646 application record). If the target device does not currently have your application installed, the 647 system uses the Android application record to launch Android Market and take the user to the 648 application in order to install it.</p> 649 650 <p>If your application doesnt use NFC APIs to perform NDEF Push messaging, then Android provides a 651 default behavior: When your application is in the foreground on one device and Android Beam is 652 invoked with another Android-powered device, then the other device receives an NDEF message with an 653 Android application record that identifies your application. If the receiving device has the 654 application installed, the system launches it; if its not installed, Android Market opens and takes 655 the 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 658 href="{@docRoot}guide/topics/nfc/nfc.html">NFC Basics</a> developer guide. For some example code 659 using Android Beam, see the <a 660 href="{@docRoot}resources/samples/AndroidBeamDemo/src/com/example/android/beam/Beam.html">Android 661 Beam 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 670 devices and other device types without a hotspot or Internet connection. The Android framework 671 provides a set of Wi-Fi P2P APIs that allow you to discover and connect to other devices when each 672 device supports Wi-Fi Direct, then communicate over a speedy connection across distances much longer 673 than a Bluetooth connection.</p> 674 675 <p>A new package, {@link android.net.wifi.p2p}, contains all the APIs for performing peer-to-peer 676 connections with Wi-Fi. The primary class you need to work with is {@link 677 android.net.wifi.p2p.WifiP2pManager}, which you can acquire by calling {@link 678 android.app.Activity#getSystemService getSystemService(WIFI_P2P_SERVICE)}. The {@link 679 android.net.wifi.p2p.WifiP2pManager} includes APIs that allow you to:</p> 680 <ul> 681 <li>Initialize your application for P2P connections by calling {@link 682 android.net.wifi.p2p.WifiP2pManager#initialize initialize()}</li> 683 684 <li>Discover nearby devices by calling {@link android.net.wifi.p2p.WifiP2pManager#discoverPeers 685 discoverPeers()}</li> 686 687 <li>Start a P2P connection by calling {@link android.net.wifi.p2p.WifiP2pManager#connect 688 connect()}</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 695 callbacks 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 698 information about discovered peers. The callback provides a {@link 699 android.net.wifi.p2p.WifiP2pDeviceList}, from which you can retrieve a {@link 700 android.net.wifi.p2p.WifiP2pDevice} object for each device within range and get information such as 701 the 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 704 receive information about a P2P group. The callback provides a {@link 705 android.net.wifi.p2p.WifiP2pGroup} object, which provides group information such as the owner, the 706 network name, and passphrase.</li> 707 708 <li>{@link android.net.wifi.p2p.WifiP2pManager.ConnectionInfoListener} interface allows you to 709 receive information about the current connection. The callback provides a {@link 710 android.net.wifi.p2p.WifiP2pInfo} object, which has information such as whether a group has been 711 formed 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 doesnt technically connect 719 to the Internet, communicating to Wi-Fi Direct peers with standard java sockets requires Internet 720 permission).</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 726 connection state has changed. This carries {@link 727 android.net.wifi.p2p.WifiP2pManager#EXTRA_WIFI_P2P_INFO} with a {@link 728 android.net.wifi.p2p.WifiP2pInfo} object and {@link 729 android.net.wifi.p2p.WifiP2pManager#EXTRA_NETWORK_INFO} with a {@link android.net.NetworkInfo} 730 object.</li> 731 732 <li>{@link android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_STATE_CHANGED_ACTION}: The P2P state has 733 changed between enabled and disabled. It carries {@link 734 android.net.wifi.p2p.WifiP2pManager#EXTRA_WIFI_STATE} with either {@link 735 android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_STATE_DISABLED} or {@link 736 android.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 739 devices has changed.</li> 740 741 <li>{@link android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_THIS_DEVICE_CHANGED_ACTION}: The details for 742 this device have changed.</li> 743 </ul> 744 745 <p>See the {@link android.net.wifi.p2p.WifiP2pManager} documentation for more information. Also 746 look at the <a href="{@docRoot}resources/samples/WiFiDirectDemo/index.html">Wi-Fi Direct Demo</a> 747 sample 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 756 Bluetooth to communicate with health devices that support Bluetooth, such as heart-rate monitors, 757 blood meters, thermometers, and scales.</p> 758 759 <p>Similar to regular headset and A2DP profile devices, you must call {@link 760 android.bluetooth.BluetoothAdapter#getProfileProxy getProfileProxy()} with a {@link 761 android.bluetooth.BluetoothProfile.ServiceListener} and the {@link 762 android.bluetooth.BluetoothProfile#HEALTH} profile type to establish a connection with the profile 763 proxy object.</p> 764 765 <p>Once youve acquired the Health Profile proxy (the {@link android.bluetooth.BluetoothHealth} 766 object), connecting to and communicating with paired health devices involves the following new 767 Bluetooth classes:</p> 768 <ul> 769 <li>{@link android.bluetooth.BluetoothHealthCallback}: You must extend this class and implement the 770 callback methods to receive updates about changes in the applications registration state and 771 Bluetooth channel state.</li> 772 <li>{@link android.bluetooth.BluetoothHealthAppConfiguration}: During callbacks to your {@link 773 android.bluetooth.BluetoothHealthCallback}, youll receive an instance of this object, which 774 provides configuration information about the available Bluetooth health device, which you must use 775 to perform various operations such as initiate and terminate connections with the {@link 776 android.bluetooth.BluetoothHealth} APIs.</li> 777 </ul> 778 779 <p>For more information about using the Bluetooth Health Profile, see the documentation for {@link 780 android.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 789 and extended APIs that allow you to provide more information about view content or 790 develop 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 796 screen to hear voice descriptions of the content. Because the explore-by-touch mode works like a 797 virtual cursor, it allows screen readers to identify the descriptive text the same way that screen 798 readers can when the user navigates with a d-pad or trackball—by reading information provided 799 by {@link android.R.attr#contentDescription android:contentDescription} and {@link 800 android.view.View#setContentDescription setContentDescription()} upon a simulated "hover" event. So, 801 consider this is a reminder that you should provide descriptive text for the views in your 802 application, especially for {@link android.widget.ImageButton}, {@link android.widget.EditText}, 803 {@link android.widget.ImageView} and other widgets that might not naturally contain descriptive 804 text.</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 810 implement new callback methods for accessibility events in your custom {@link 811 android.view.View} components.</p> 812 813 <p>It's important to first note that the behavior of the {@link 814 android.view.View#sendAccessibilityEvent sendAccessibilityEvent()} method has changed in Android 815 4.0. As with previous version of Android, when the user enables accessibility services on the device 816 and 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 818 implementation of {@link android.view.View#sendAccessibilityEvent sendAccessibilityEvent()} would 819 initialize an {@link android.view.accessibility.AccessibilityEvent} and send it to {@link 820 android.view.accessibility.AccessibilityManager}. The new behavior involves some additional callback 821 methods that allow the view and its parents to add more contextual information to the event: 822 <ol> 823 <li>When invoked, the {@link 824 android.view.View#sendAccessibilityEvent sendAccessibilityEvent()} and {@link 825 android.view.View#sendAccessibilityEventUnchecked sendAccessibilityEventUnchecked()} methods defer 826 to {@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()}. 827 <p>Custom implementations of {@link android.view.View} might want to implement {@link 828 android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()} to 829 attach additional accessibility information to the {@link 830 android.view.accessibility.AccessibilityEvent}, but should also call the super implementation to 831 provide default information such as the standard content description, item index, and more. 832 However, you should not add additional text content in this callback—that happens 833 next.</p></li> 834 <li>Once initialized, if the event is one of several types that should be populated with text 835 information, the view then receives a call to {@link 836 android.view.View#dispatchPopulateAccessibilityEvent dispatchPopulateAccessibilityEvent()}, which 837 defers to the {@link android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} 838 callback. 839 <p>Custom implementations of {@link android.view.View} should usually implement {@link 840 android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} to add additional 841 text content to the {@link android.view.accessibility.AccessibilityEvent} if the {@link 842 android.R.attr#contentDescription android:contentDescription} text is missing or 843 insufficient. To add more text description to the 844 {@link android.view.accessibility.AccessibilityEvent}, call {@link 845 android.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 849 parent view. Each parent view then has the chance to augment the accessibility information by 850 adding an {@link android.view.accessibility.AccessibilityRecord}, until it 851 ultimately reaches the root view, which sends the event to the {@link 852 android.view.accessibility.AccessibilityManager} with {@link 853 android.view.accessibility.AccessibilityManager#sendAccessibilityEvent 854 sendAccessibilityEvent()}.</li> 855 </ol> 856 857 <p>In addition to the new methods above, which are useful when extending the {@link 858 android.view.View} class, you can also intercept these event callbacks on any {@link 859 android.view.View} by extending {@link 860 android.view.View.AccessibilityDelegate AccessibilityDelegate} and setting it on the view with 861 {@link android.view.View#setAccessibilityDelegate setAccessibilityDelegate()}. 862 When you do, each accessibility method in the view defers the call to the corresponding method in 863 the delegate. For example, when the view receives a call to {@link 864 android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()}, it passes it to the 865 same method in the {@link android.view.View.AccessibilityDelegate}. Any methods not handled by 866 the delegate are given right back to the view for default behavior. This allows you to override only 867 the 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 871 the new the accessibility APIs, you can do so with the latest version of the <em>v4 support 872 library</em> (in <a href="{@docRoot}sdk/compatibility-library.html">Compatibility Package, r4</a>) 873 using a set of utility classes that provide the new accessibility APIs in a backward-compatible 874 design.</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 882 has been significantly expanded to enable more advanced accessibility feedback for users. In 883 particular, events are generated based on view composition, providing better context information and 884 allowing accessibility services to traverse view hierarchies to get additional view information and 885 deal with special cases.</p> 886 887 <p>If you're developing an accessibility service (such as a screen reader), you can access 888 additional 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, 891 call the {@link android.view.accessibility.AccessibilityEvent#getRecord(int) 892 AccessibilityEvent.getRecord()} to retrieve a specific {@link 893 android.view.accessibility.AccessibilityRecord} (there may be several records attached to the 894 event).</li> 895 896 <li>From either {@link android.view.accessibility.AccessibilityEvent} or an individual {@link 897 android.view.accessibility.AccessibilityRecord}, you can call {@link 898 android.view.accessibility.AccessibilityRecord#getSource() getSource()} to retrieve a {@link 899 android.view.accessibility.AccessibilityNodeInfo} object. 900 <p>An {@link android.view.accessibility.AccessibilityNodeInfo} represents a single node 901 of the window content in a format that allows you to query accessibility information about that 902 node. The {@link android.view.accessibility.AccessibilityNodeInfo} object returned from {@link 903 android.view.accessibility.AccessibilityEvent} describes the event source, whereas the source from 904 an {@link android.view.accessibility.AccessibilityRecord} describes the predecessor of the event 905 source.</p></li> 906 907 <li>With the {@link android.view.accessibility.AccessibilityNodeInfo}, you can query information 908 about it, call {@link 909 android.view.accessibility.AccessibilityNodeInfo#getParent getParent()} or {@link 910 android.view.accessibility.AccessibilityNodeInfo#getChild getChild()} to traverse the view 911 hierarchy, 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 915 must declare an XML configuration file that corresponds to {@link 916 android.accessibilityservice.AccessibilityServiceInfo}. For more information about creating an 917 accessibility service, see {@link 918 android.accessibilityservice.AccessibilityService} and {@link 919 android.accessibilityservice.AccessibilityService#SERVICE_META_DATA 920 SERVICE_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 926 android.view.accessibility.AccessibilityManager} has some new APIs such as:</p> 927 <ul> 928 <li>{@link android.view.accessibility.AccessibilityManager.AccessibilityStateChangeListener} 929 is an interface that allows you to receive a callback whenever accessibility is enabled or 930 disabled.</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 946 input method framework (for IMEs). To create a new spell checker, you must implement a service that 947 extends 948 {@link android.service.textservice.SpellCheckerService} and extend the {@link 949 android.service.textservice.SpellCheckerService.Session} class to provide spelling suggestions based 950 on text provided by the interface's callback methods. In the {@link 951 android.service.textservice.SpellCheckerService.Session} callback methods, you must return the 952 spelling suggestions as {@link android.view.textservice.SuggestionsInfo} objects. </p> 953 954 <p>Applications with a spell checker service must declare the {@link 955 android.Manifest.permission#BIND_TEXT_SERVICE} permission as required by the service. 956 The service must also declare an intent filter with {@code <action 957 android:name="android.service.textservice.SpellCheckerService" />} as the intents action and should 958 include a {@code <meta-data>} element that declares configuration information for the spell 959 checker. </p> 960 961 <p>See the sample <a href="{@docRoot}resources/samples/SpellChecker/SampleSpellCheckerService/index.html"> 962 Spell Checker Service</a> app and 963 sample <a href="{@docRoot}resources/samples/SpellChecker/HelloSpellChecker/index.html"> 964 Spell Checker Client</a> app for example code.</p> 965 966 967 968 969 <h3 id="TTS">Text-to-speech Engines</h3> 970 971 <p>Androids text-to-speech (TTS) APIs have been significantly extended to allow applications to 972 more easily implement custom TTS engines, while applications that want to use a TTS engine have a 973 couple 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 979 to perform text-to-speech (TTS) operations using the TTS engine provided by the system or set a 980 custom engine using {@link android.speech.tts.TextToSpeech#setEngineByPackageName 981 setEngineByPackageName()}. In Android 4.0, the {@link 982 android.speech.tts.TextToSpeech#setEngineByPackageName setEngineByPackageName()} method has been 983 deprecated and you can now specify the engine to use with a new {@link 984 android.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 987 android.speech.tts.TextToSpeech#getEngines()}. This method returns a list of {@link 988 android.speech.tts.TextToSpeech.EngineInfo} objects, which include meta data such as the engines 989 icon, 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 995 file. 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 998 responds to the {@link android.speech.tts.TextToSpeech.Engine#INTENT_ACTION_TTS_SERVICE} intent. The 999 primary work for a TTS engine happens during the {@link 1000 android.speech.tts.TextToSpeechService#onSynthesizeText onSynthesizeText()} callback in a service 1001 that extends {@link android.speech.tts.TextToSpeechService}. The system delivers this method two 1002 objects:</p> 1003 <ul> 1004 <li>{@link android.speech.tts.SynthesisRequest}: This contains various data including the text to 1005 synthesize, 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 1007 delivers the resulting speech data as streaming audio. First the engine must call {@link 1008 android.speech.tts.SynthesisCallback#start start()} to indicate that the engine is ready to deliver 1009 the audio, then call {@link android.speech.tts.SynthesisCallback#audioAvailable audioAvailable()}, 1010 passing it the audio data in a byte buffer. Once your engine has passed all audio through the 1011 buffer, 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 1015 implementation has been removed. Look for a blog post about a compatibility layer 1016 that 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 1019 href="{@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. 1029 The Settings app provides controls that allow users to manage set limits for network data usage and 1030 even disable the use of background data for individual apps. In order to avoid users disabling your 1031 apps access to data from the background, you should develop strategies to use the data 1032 connection 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 1035 allow users to control your apps data habits, such as how often your app syncs data, whether to 1036 perform uploads/downloads only when on Wi-Fi, whether to use data while roaming, etc. With these 1037 controls available to them, users are much less likely to disable your apps access to data when 1038 they approach their limits, because they can instead precisely control how much data your app uses. 1039 If you provide a preference activity with these settings, you should include in its manifest 1040 declaration an intent filter for the {@link android.content.Intent#ACTION_MANAGE_NETWORK_USAGE} 1041 action. 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 1053 applications data usage. Thus, when the user inspects how much data your app is using from the 1054 Settings app, a View application settings" button is available that launches your 1055 preference 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 1058 deprecated and always returns true—use {@link 1059 android.net.ConnectivityManager#getActiveNetworkInfo()} instead. Before you attempt any network 1060 transactions, you should always call {@link android.net.ConnectivityManager#getActiveNetworkInfo()} 1061 to get the {@link android.net.NetworkInfo} that represents the current network and query {@link 1062 android.net.NetworkInfo#isConnected()} to check whether the device has a 1063 connection. You can then check other connection properties, such as whether the device is 1064 roaming 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 1084 android.renderscript.Allocation#USAGE_GRAPHICS_RENDER_TARGET} memory space, which allows you to 1085 render things directly into the {@link android.renderscript.Allocation} and use it as a framebuffer 1086 object.</p> 1087 1088 <p>{@link android.renderscript.RSTextureView} provides a means to display RenderScript graphics 1089 inside of a {@link android.view.View}, unlike {@link android.renderscript.RSSurfaceView}, which 1090 creates a separate window. This key difference allows you to do things such as move, transform, or 1091 animate an {@link android.renderscript.RSTextureView} as well as draw RenderScript graphics inside 1092 a view that lies within an activity layout.</p> 1093 1094 <p>The {@link android.renderscript.Script#forEach Script.forEach()} method allows you to call 1095 RenderScript compute scripts from the VM level and have them automatically delegated to available 1096 cores on the device. You do not use this method directly, but any compute RenderScript that you 1097 write will have a {@link android.renderscript.Script#forEach forEach()} method that you can call in 1098 the reflected RenderScript class. You can call the reflected {@link 1099 android.renderscript.Script#forEach forEach()} method by passing in an input {@link 1100 android.renderscript.Allocation} to process, an output {@link android.renderscript.Allocation} to 1101 write the result to, and a {@link android.renderscript.FieldPacker} data structure in case the 1102 RenderScript needs more information. Only one of the {@link android.renderscript.Allocation}s is 1103 necessary 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 1120 Private Network), running as a {@link android.app.Service}. A VPN service creates an interface for a 1121 virtual network with its own address and routing rules and performs all reading and writing with a 1122 file descriptor.</p> 1123 1124 <p>To create a VPN service, use {@link android.net.VpnService.Builder}, which allows you to specify 1125 the network address, DNS server, network route, and more. When complete, you can establish the 1126 interface by calling {@link android.net.VpnService.Builder#establish()}, which returns a {@link 1127 android.os.ParcelFileDescriptor}. </p> 1128 1129 <p>Because a VPN service can intercept packets, there are security implications. As such, if you 1130 implement {@link android.net.VpnService}, then your service must require the {@link 1131 android.Manifest.permission#BIND_VPN_SERVICE} to ensure that only the system can bind to it (only 1132 the system is granted this permission—apps cannot request it). To then use your VPN service, 1133 users 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 1139 android.app.admin.DevicePolicyManager#setCameraDisabled setCameraDisabled()} and the {@link 1140 android.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 1147 certificates in the system key store. Certificates streamline the installation of both client 1148 certificates (to validate the identity of the user) and certificate authority certificates (to 1149 verify server identity). Applications such as web browsers or email clients can access the installed 1150 certificates to authenticate users to servers. See the {@link android.security.KeyChain} 1151 documentation 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 1165 the ambient (room) temperature in degrees Celsius.</li> 1166 <li>{@link android.hardware.Sensor#TYPE_RELATIVE_HUMIDITY}: A humidity sensor that provides the 1167 relative 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 1171 android.hardware.Sensor#TYPE_RELATIVE_HUMIDITY} sensors, you can use them to calculate the dew point 1172 and the absolute humidity.</p> 1173 1174 <p>The previous temperature sensor, {@link android.hardware.Sensor#TYPE_TEMPERATURE}, has been 1175 deprecated. You should use the {@link android.hardware.Sensor#TYPE_AMBIENT_TEMPERATURE} sensor 1176 instead.</p> 1177 1178 <p>Additionally, Androids three synthetic sensors have been greatly improved so they now have lower 1179 latency and smoother output. These sensors include the gravity sensor ({@link 1180 android.hardware.Sensor#TYPE_GRAVITY}), rotation vector sensor ({@link 1181 android.hardware.Sensor#TYPE_ROTATION_VECTOR}), and linear acceleration sensor ({@link 1182 android.hardware.Sensor#TYPE_LINEAR_ACCELERATION}). The improved sensors rely on the gyroscope 1183 sensor 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 1192 importantly, the system gracefully manages the action bars size and configuration when running on 1193 smaller screens in order to provide an optimal user experience on all screen sizes. For example, 1194 when the screen is narrow (such as when a handset is in portrait orientation), the action bars 1195 navigation tabs appear in a stacked bar," which appears directly below the main action bar. You can 1196 also opt-in to a split action bar," which places all action items in a separate bar at the bottom 1197 of 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 1203 a narrow screen, so the system will place more of them into the overflow menu. However, Android 4.0 1204 allows you to enable split action bar" so that more action items can appear on the screen in a 1205 separate bar at the bottom of the screen. To enable split action bar, add {@link 1206 android.R.attr#uiOptions android:uiOptions} with {@code "splitActionBarWhenNarrow"} to either your 1207 <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> 1208 tag or 1209 individual <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code 1210 <activity>}</a> tags 1211 in your manifest file. When enabled, the system will add an additional bar at the bottom of the 1212 screen for all action items when the screen is narrow (no action items will appear in the primary 1213 action bar).</p> 1214 1215 <p>If you want to use the navigation tabs provided by the {@link android.app.ActionBar.Tab} APIs, 1216 but dont need the main action bar on top (you want only the tabs to appear at the top), then enable 1217 the split action bar as described above and also call {@link 1218 android.app.ActionBar#setDisplayShowHomeEnabled setDisplayShowHomeEnabled(false)} to disable the 1219 application icon in the action bar. With nothing left in the main action bar, it 1220 disappears—all thats left are the navigation tabs at the top and the action items at the 1221 bottom 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 1227 android.R.attr#backgroundStacked} and {@link android.R.attr#backgroundSplit} to apply a background 1228 drawable or color to the stacked bar and split bar, respectively. You can also set these styles at 1229 runtime with {@link android.app.ActionBar#setStackedBackgroundDrawable 1230 setStackedBackgroundDrawable()} and {@link android.app.ActionBar#setSplitBackgroundDrawable 1231 setSplitBackgroundDrawable()}.</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 1237 action items. An action provider can define an action view, a default action behavior, and a submenu 1238 for each action item to which it is associated. When you want to create an action item that has 1239 dynamic behaviors (such as a variable action view, default action, or submenu), extending {@link 1240 android.view.ActionProvider} is a good solution in order to create a reusable component, rather than 1241 handling 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 1244 android.view.ActionProvider} that facilitates a share" action from the action bar. Instead of using 1245 traditional action item that invokes the {@link android.content.Intent#ACTION_SEND} intent, you can 1246 use this action provider to present an action view with a drop-down list of applications that handle 1247 the {@link android.content.Intent#ACTION_SEND} intent. When the user selects an application to use 1248 for the action, {@link android.widget.ShareActionProvider} remembers that selection and provides it 1249 in 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} 1252 attribute in the <a href="{@docRoot}guide/topics/resources/menu-resource.html#item-element">{@code 1253 <item>}</a> element for your activitys options menu, with the class name of the action 1254 provider 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 activitys {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} 1264 callback method, retrieve an instance of the action provider from the menu item and set the 1265 intent:</p> 1266 1267 <pre> 1268 public 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 1280 href="{@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 1287 traditional action item state. Previously only the {@link android.widget.SearchView} supported 1288 collapsing when used as an action view, but now you can add an action view for any action item and 1289 switch between the expanded state (action view is visible) and collapsed state (action item is 1290 visible).</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 1294 href="{@docRoot}guide/topics/resources/menu-resource.html#item-element">{@code 1295 <item>}</a> element in the menus XML file.</p> 1296 1297 <p>To receive callbacks when an action view switches between expanded and collapsed, register an 1298 instance of {@link android.view.MenuItem.OnActionExpandListener} with the respective {@link 1299 android.view.MenuItem} by calling {@link android.view.MenuItem#setOnActionExpandListener 1300 setOnActionExpandListener()}. Typically, you should do so during the {@link 1301 android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} callback.</p> 1302 1303 <p>To control a collapsible action view, you can call {@link 1304 android.view.MenuItem#collapseActionView()} and {@link android.view.MenuItem#expandActionView()} on 1305 the respective {@link android.view.MenuItem}.</p> 1306 1307 <p>When creating a custom action view, you can also implement the new {@link 1308 android.view.CollapsibleActionView} interface to receive callbacks when the view is expanded and 1309 collapsed.</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 1315 whether the icon/logo behaves as a button to navigate home or up" (pass true" to make it behave as 1316 a button).</li> 1317 1318 <li>{@link android.app.ActionBar#setIcon setIcon()} and {@link android.app.ActionBar#setLogo 1319 setLogo()} 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 1322 or disable the visibility of the options menu items declared by the fragment. This is useful if the 1323 fragment has been added to the activity, but is not visible, so the menu items should be 1324 hidden.</li> 1325 1326 <li>{@link android.app.FragmentManager#invalidateOptionsMenu 1327 FragmentManager.invalidateOptionsMenu()} 1328 allows you to invalidate the activity options menu during various states of the fragment lifecycle 1329 in 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 1347 grid. Unlike {@link android.widget.TableLayout}, {@link android.widget.GridLayout} relies on a flat 1348 hierarchy and does not make use of intermediate views such as table rows for providing structure. 1349 Instead, children specify which row(s) and column(s) they should occupy (cells can span multiple 1350 rows and/or columns), and by default are laid out sequentially across the grids rows and columns. 1351 The {@link android.widget.GridLayout} orientation determines whether sequential children are by 1352 default laid out horizontally or vertically. Space between children may be specified either by using 1353 instances of the new {@link android.widget.Space} view or by setting the relevant margin parameters 1354 on children.</p> 1355 1356 <p>See <a 1357 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/index.html">ApiDemos</a 1358 > 1359 for 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 1366 as a video or an OpenGL scene. Although similar to {@link android.view.SurfaceView}, {@link 1367 android.view.TextureView} is unique in that it behaves like a regular view, rather than creating a 1368 separate window, so you can treat it like any other {@link android.view.View} object. For example, 1369 you can apply transforms, animate it using {@link android.view.ViewPropertyAnimator}, or 1370 adjust 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 1380 side 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 1383 to appear on the switch when in the on and off setting. The {@code android:text} attribute also 1384 allows you to place a label alongside the switch.</p> 1385 1386 <p>For a sample using switches, see the <a 1387 href="{@docRoot}resources/samples/ApiDemos/res/layout/switches.html">switches.xml</a> layout file 1388 and respective <a 1389 href="{@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 1396 up at an anchor point you specify (usually at the point of the item selected). Android 4.0 extends 1397 the {@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 1400 href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a> with {@link 1401 android.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 1403 callback 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 1410 preferences that provide a two-state selection option. The new {@link 1411 android.preference.SwitchPreference} is an extension of {@link 1412 android.preference.TwoStatePreference} that provides a {@link android.widget.Switch} widget in the 1413 preference view to allow users to toggle a setting on or off without the need to open an additional 1414 preference screen or dialog. For example, the Settings application uses a {@link 1415 android.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 1422 href="{@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 1426 the 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 1429 from one device to another when running the same version of Android. If you explicitly 1430 apply any of the {@link android.R.style#Theme_Holo Theme.Holo} themes to your activities, you can 1431 rest assured that these themes will not change character on different devices within the same 1432 platform version.</p> 1433 1434 <p>If you wish for your app to blend in with the overall device theme (such as when different OEMs 1435 provide different default themes for the system), you should explicitly apply themes from the {@link 1436 android.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. 1442 However, there's no need for you to worry about this if your existing application provides an <a 1443 href="{@docRoot}guide/topics/ui/menus.html#options-menu">options menu</a> and expects there to be a 1444 Menu button. To ensure that existing apps continue to work as they expect, the system provides an 1445 on-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 1448 android.app.ActionBar} to provide access to menu items and set <a 1449 href="{@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 1457 bar</em>, which resides at the top of handset devices to deliver information such as the carrier 1458 signal, time, notifications, and so on. Android 3.0 added the <em>system bar</em> for tablet 1459 devices, which resides at the bottom of the screen to provide system navigation controls (Home, 1460 Back, and so forth) and also an interface for elements traditionally provided by the status bar. In 1461 Android 4.0, the system provides a new type of system UI called the <em>navigation bar</em>. You 1462 might consider the navigation bar a re-tuned version of the system bar designed for 1463 handsets—it provides navigation controls 1464 for devices that dont have hardware counterparts for navigating the system, but it leaves out the 1465 system bar's notification UI and setting controls. As such, a device that provides the navigation 1466 bar 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 1469 android.view.WindowManager.LayoutParams#FLAG_FULLSCREEN} flag. In Android 4.0, the APIs that control 1470 the system bars visibility have been updated to better reflect the behavior of both the system bar 1471 and navigation bar:</p> 1472 <ul> 1473 <li>The {@link android.view.View#SYSTEM_UI_FLAG_LOW_PROFILE} flag replaces the {@code 1474 STATUS_BAR_HIDDEN} flag. When set, this flag enables low profile" mode for the system bar or 1475 navigation bar. Navigation buttons dim and other elements in the system bar also hide. Enabling 1476 this is useful for creating more immersive games without distraction for the system navigation 1477 buttons.</li> 1478 1479 <li>The {@link android.view.View#SYSTEM_UI_FLAG_VISIBLE} flag replaces the {@code 1480 STATUS_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 1483 the navigation bar hide completely. Be aware that this works only for the <em>navigation bar</em> 1484 used by some handsets (it does <strong>not</strong> hide the system bar on tablets). The navigation 1485 bar returns to view as soon as the system receives user input. As such, this mode is useful 1486 primarily for video playback or other cases in which the whole screen is needed but user input is 1487 not required.</li> 1488 </ul> 1489 1490 <p>You can set each of these flags for the system bar and navigation bar by calling {@link 1491 android.view.View#setSystemUiVisibility setSystemUiVisibility()} on any view in your activity. The 1492 window manager combines (OR-together) all flags from all views in your window and 1493 apply them to the system UI as long as your window has input focus. When your window loses input 1494 focus (the user navigates away from your app, or a dialog appears), your flags cease to have effect. 1495 Similarly, 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 1498 example, 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 1500 of the system bar or navigation bar changes.</p> 1501 1502 <p>See the <a 1503 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/OverscanActivity.html"> 1504 OverscanActivity</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 1517 through the use of pointer devices (such as a mouse or other devices that drive an on-screen 1518 cursor).</p> 1519 1520 <p>To receive hover events on a view, implement the {@link android.view.View.OnHoverListener} and 1521 register it with {@link android.view.View#setOnHoverListener setOnHoverListener()}. When a hover 1522 event occurs on the view, your listener receives a call to {@link 1523 android.view.View.OnHoverListener#onHover onHover()}, providing the {@link android.view.View} that 1524 received the event and a {@link android.view.MotionEvent} that describes the type of hover event 1525 that 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 1533 android.view.View.OnHoverListener#onHover onHover()} if it handles the hover event. If your 1534 listener 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 1537 current state, you can now use the {@code android:state_hovered} attribute in a <a 1538 href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">state list drawable</a> to 1539 provide 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 1542 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/Hover.html">Hover</a> class in 1543 ApiDemos.</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 1549 tablet 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 1552 with the digitizer, applications receive touch events just like they would when a finger is used to 1553 touch the display. When the stylus is hovering above the digitizer, applications receive hover 1554 events just like they would when a mouse pointer was being moved across the display when no buttons 1555 are 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 1559 android.view.MotionEvent#getToolType getToolType()}. The currently defined tool types are: {@link 1560 android.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}, 1562 and {@link android.view.MotionEvent#TOOL_TYPE_ERASER}. By querying the tool type, your application 1563 can 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 1566 state" of a {@link android.view.MotionEvent} using {@link android.view.MotionEvent#getButtonState 1567 getButtonState()}. The currently defined button states are: {@link 1568 android.view.MotionEvent#BUTTON_PRIMARY}, {@link android.view.MotionEvent#BUTTON_SECONDARY}, {@link 1569 android.view.MotionEvent#BUTTON_TERTIARY}, {@link android.view.MotionEvent#BUTTON_BACK}, and {@link 1570 android.view.MotionEvent#BUTTON_FORWARD}. For convenience, the back and forward mouse buttons are 1571 automatically mapped to the {@link android.view.KeyEvent#KEYCODE_BACK} and {@link 1572 android.view.KeyEvent#KEYCODE_FORWARD} keys. Your application can handle these keys to support 1573 mouse 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 1576 devices also report the distance between the stylus tip and the digitizer, the stylus tilt angle, 1577 and the stylus orientation angle. Your application can query this information using {@link 1578 android.view.MotionEvent#getAxisValue getAxisValue()} with the axis codes {@link 1579 android.view.MotionEvent#AXIS_DISTANCE}, {@link android.view.MotionEvent#AXIS_TILT}, and {@link 1580 android.view.MotionEvent#AXIS_ORIENTATION}.</p> 1581 1582 <p>For a demonstration of tool types, button states and the new axis codes, see the <a 1583 href="{@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 1594 property on any object that allows callers to generically set/get values on target objects. It also 1595 allows the functionality of passing around field/method references and allows code to set/get values 1596 of 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 1599 previously do this:</p> 1600 <pre> 1601 foo.bar = value; 1602 </pre> 1603 1604 <p>If you want to call the setter for an underlying private field {@code bar}, you would previously 1605 do this:</p> 1606 <pre> 1607 foo.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} 1614 object {@code BAR} on class {@code Foo} so that you can set the field on instance {@code foo} of 1615 class {@code Foo} like this:</p> 1616 <pre> 1617 BAR.set(foo, value); 1618 </pre> 1619 1620 <p>The {@link android.view.View} class now leverages the {@link android.util.Property} class to 1621 allow you to set various fields, such as transform properties that were added in Android 3.0 ({@link 1622 android.view.View#ROTATION}, {@link android.view.View#ROTATION_X}, {@link 1623 android.view.View#TRANSLATION_X}, etc.).</p> 1624 1625 <p>The {@link android.animation.ObjectAnimator} class also uses the {@link android.util.Property} 1626 class, so you can create an {@link android.animation.ObjectAnimator} with a {@link 1627 android.util.Property}, which is faster, more efficient, and more type-safe than the string-based 1628 approach.</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 1638 application has set either <a 1639 href="{@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 1642 scrolling, and overall better performance and response to user interaction.</p> 1643 1644 <p>If necessary, you can manually disable hardware acceleration with the <a 1645 href="{@docRoot}guide/topics/manifest/activity-element.html#hwaccel">{@code hardwareAccelerated}</a> 1646 attribute for individual <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code 1647 <activity>}</a> elements or the <a 1648 href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> 1649 element. You can alternatively disable hardware acceleration for individual views by calling {@link 1650 android.view.View#setLayerType setLayerType(LAYER_TYPE_SOFTWARE)}.</p> 1651 1652 <p>For more information about hardware acceleration, including a list of unsupported drawing 1653 operations, see the <a href="{@docRoot}guide/topics/graphics/hardware-accel.html">Hardware 1654 Acceleration</a> document.</p> 1655 1656 1657 1658 <h3 id="Jni">JNI Changes</h3> 1659 1660 <p>In previous versions of Android, JNI local references werent indirect handles; Android used 1661 direct pointers. This wasn't a problem as long as the garbage collector didn't move objects, but it 1662 seemed to work because it made it possible to write buggy code. In Android 4.0, the system now uses 1663 indirect 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 1666 href="{@docRoot}guide/practices/design/jni.html">JNI Tips</a>. In Android 4.0, <a 1667 href="http://android-developers.blogspot.com/2011/07/debugging-android-jni-with-checkjni.html"> 1668 CheckJNI</a> has been enhanced to detect these errors. Watch the <a 1669 href="http://android-developers.blogspot.com/">Android Developers Blog</a> for an upcoming post 1670 about 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 1673 the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code 1674 targetSdkVersion}</a> or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code 1675 minSdkVersion}</a> to {@code 14"} or higher. If youve set these attributes to any lower value, 1676 then 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 1686 needed 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 1688 built-in Browser</li> 1689 <li>Support for <a 1690 href="http://google-opensource.blogspot.com/2009/05/introducing-webdriver.html">WebDriver</a> makes 1691 it 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 1701 href="{@docRoot}sdk/android-3.0.html">Android 1702 3.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 1707 events</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 1720 messages to the device.</li> 1721 <li>{@link android.Manifest.permission#BIND_TEXT_SERVICE}: A service that implements {@link 1722 android.service.textservice.SpellCheckerService} must require this permission for itself.</li> 1723 <li>{@link android.Manifest.permission#BIND_VPN_SERVICE}: A service that implements {@link 1724 android.net.VpnService} must require this permission for itself.</li> 1725 <li>{@link android.Manifest.permission#READ_PROFILE}: Provides read access to the {@link 1726 android.provider.ContactsContract.Profile} provider.</li> 1727 <li>{@link android.Manifest.permission#WRITE_PROFILE}: Provides write access to the {@link 1728 android.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 1738 uses 1739 Wi-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 1746 href="{@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. 1753 Because the Android 3.x platform is available only for large-screen devices, if you've 1754 been developing primarily for handsets, then you might not be aware of all the APIs added to Android 1755 in 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 1758 on 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 1765 elements 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 1768 the activity window. It includes the application logo in the left corner and provides a new 1769 interface 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 1772 loading of data in combination with UI components to dynamically load data without blocking the 1773 main 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 1776 the 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 1779 operations. 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 1782 object (View, Drawable, Fragment, Object, or anything else) and define animation aspects such 1783 as duration, interpolation, repeat and more. The new framework makes Animations in Android 1784 simpler than ever. See the 1785 <a href="{@docRoot}guide/topics/graphics/prop-animation.html">Property Animation</a> developer 1786 guide.</li> 1787 <li>RenderScript graphics and compute engine: RenderScript offers a high performance 3D 1788 graphics rendering and compute API at the native level, which you write in the C (C99 standard), 1789 providing the type of performance you expect from a native environment while remaining portable 1790 across various CPUs and GPUs. See the 1791 <a href="{@docRoot}guide/topics/renderscript/index.html">RenderScript</a> developer 1792 guide.</li> 1793 <li>Hardware accelerated 2D graphics: You can now enable the OpenGL renderer for your 1794 application by setting {android:hardwareAccelerated="true"} in your manifest element's <a 1795 href="{@docRoot}guide/topics/manifest/application-element.html"><code><application></code></a> 1796 element or for individual <a 1797 href="{@docRoot}guide/topics/manifest/activity-element.html"><code><activity></code></a> 1798 elements. This results 1799 in smoother animations, smoother scrolling, and overall better performance and response to user 1800 interaction. 1801 <p class="note"><strong>Note:</strong> If you set your application's <a 1802 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a 1803 href="{@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> 1806 notes 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 1814 Android applications. The APIs are based on a USB stack and services that are 1815 built into the platform, including support for both USB host and device interactions. See the <a 1816 href="{@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 1818 devices to receive notifications when devices are attached and removed, manage files and storage on 1819 those 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, 1823 which applications can use to manage on-demand or interactive data streaming. In particular, apps 1824 that provide VOIP, push-to-talk, conferencing, and audio streaming can use the API to initiate 1825 sessions and transmit or receive data streams over any available network. See the {@link 1826 android.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> 1829 notes 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 1837 displayed across different screen sizes. The API extends the existing screen support model with the 1838 ability to precisely target specific screen size ranges by dimensions, measured in 1839 density-independent pixel units (such as 600dp or 720dp wide), rather than by their generalized 1840 screen sizes (such as large or xlarge). For example, this is important in order to help you 1841 distinguish between a 5" device and a 7" device, which would both traditionally be bucketed as 1842 "large" screens. See the blog post, <a 1843 href="http://android-developers.blogspot.com/2011/07/new-tools-for-managing-screen-sizes.html"> 1844 New Tools for Managing Screen Sizes</a>.</li> 1845 <li>New constants for <a 1846 href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> to 1847 declare landscape or portrait screen orientation requirements.</li> 1848 <li>The device "screen size" configuration now changes during a screen orientation 1849 change. If your app targets API level 13 or higher, you must handle the {@code "screenSize"} 1850 configuration 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 1852 android:configChanges}</a> for more information.</li> 1853 <li>See the <a href="android-3.2.html">Android 3.2 Platform</a> 1854 notes 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 1866 identifier—<strong>{@sdkPlatformApiLevel}</strong>—that is stored in the system itself. 1867 This identifier, called the "API level", allows the system to correctly determine whether an 1868 application 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 1871 application against an Android platform that supports API level {@sdkPlatformApiLevel} or 1872 higher. 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> 1875 element.</p> 1876 1877 <p>For more information, see the <a href="{@docRoot}guide/appendix/api-levels.html">API Levels</a> 1878 document. </p> 1879 1880 1881 <h2 id="apps">Built-in Applications</h2> 1882 1883 <p>The system image included in the downloadable platform provides these 1884 built-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 1923 locales. In some cases, region-specific strings are available for the locales. In other cases, a 1924 default version of the language is used. The languages that are available in the Android 3.0 system 1925 image 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 bokml, 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 1996 locales than are included in the SDK system image. All of the supported locales 1997 are available in the <a href="http://source.android.com/">Android Open Source 1998 Project</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 2035 an AVD with the new WXGA720 skin (it's an xhdpi, normal screen device). Note that the emulator 2036 currently doesn't support the new on-screen navigation bar for devices without hardware navigation 2037 buttons, 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 2041 the 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
