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