1 page.title=Android 4.0 APIs 2 sdk.platform.version=4.0 3 sdk.platform.apiLevel=14 4 @jd:body 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 9 <h2>In this document</h2> 10 <ol> 11 <li><a href="#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 19 href="{@docRoot}sdk/api_diff/14/changes.html">API 20 Differences 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 30 developers. Besides all the new features and APIs discussed below, Android 4.0 is an important 31 platform release because it brings the extensive set of APIs and Holographic themes from Android 3.x 32 to smaller screens. As an app developer, you now have a single platform and unified API framework 33 that enables you to develop and publish your application with a single APK that provides an 34 optimized user experience for handsets, tablets, and more, when running the same version of 35 Android—Android 4.0 (API level 14) or greater.</p> 36 37 <p>For developers, the Android {@sdkPlatformVersion} platform is available as a 38 downloadable component for the Android SDK. The downloadable platform includes 39 an Android library and system image, as well as a set of emulator skins and 40 more. To get started developing or testing against Android {@sdkPlatformVersion}, 41 use 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" 51 class="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 92 extended to support new social-oriented features such as a personal profile for the device owner and 93 the ability for users to invite individual contacts to social networks that are installed on the 94 device.</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 101 can contribute to the user's profile data by creating a new {@link 102 android.provider.ContactsContract.RawContacts} entry within the {@link 103 android.provider.ContactsContract.Profile}. That is, raw contacts that represent the device user do 104 not belong in the traditional raw contacts table defined by the {@link 105 android.provider.ContactsContract.RawContacts} Uri; instead, you must add a profile raw contact in 106 the table at {@link android.provider.ContactsContract.Profile#CONTENT_RAW_CONTACTS_URI}. Raw 107 contacts 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 110 android.Manifest.permission#WRITE_PROFILE} permission. Likewise, in order to read from the profile 111 table, you must request the {@link android.Manifest.permission#READ_PROFILE} permission. However, 112 most apps should not need to read the user profile, even when contributing data to the 113 profile. Reading the user profile is a sensitive permission and you should expect users to be 114 skeptical 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 120 to invoke an action that indicates the user wants to add a contact to a social network. The app 121 receiving the app uses it to invite the specified contact to that 122 social network. Most apps will be on the receiving-end of this operation. For example, the 123 built-in People app invokes the invite intent when the user selects "Add connection" for a specific 124 social 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 127 sync contact information from your social network. You must then indicate to the system that your 128 app responds to the {@link android.provider.ContactsContract.Intents#INVITE_CONTACT} intent by 129 adding the {@code inviteContactActivity} attribute to your apps sync configuration file, with a 130 fully-qualified name of the activity that the system should start when sending the invite intent. 131 The activity that starts can then retrieve the URI for the contact in question from the intents 132 data and perform the necessary work to invite that contact to the network or add the person to the 133 users connections.</p> 134 135 <p>See the <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">Sample Sync 136 Adapter</a> app for an example (specifically, see the <a 137 href="{@docRoot}resources/samples/SampleSyncAdapter/res/xml-v14/contacts.html">contacts.xml</a> 138 file).</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 144 contact record, the system processes it into both a 96x96 thumbnail (as it has previously) and a 145 256x256 "display photo" that's stored in a new file-based photo store (the exact dimensions that the 146 system chooses may vary in the future). You can add a large photo to a contact by putting a large 147 photo in the usual {@link android.provider.ContactsContract.CommonDataKinds.Photo#PHOTO} column of a 148 data row, which the system will then process into the appropriate thumbnail and display photo 149 records.</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 155 how often the user uses particular methods of contacting people, such as how often the user uses 156 each phone number or e-mail address. This information helps improve the ranking for each contact 157 method 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, 166 reminders 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, 169 some of the most compelling use cases are sync adapters that synchronize the user's calendar from 170 other calendar services with the Calendar Provider, in order to offer a unified location for all the 171 user's events. Google Calendar events, for example, are synchronized with the Calendar Provider by 172 the Google Calendar Sync Adapter, allowing these events to be viewed with Android's built-in 173 Calendar app.</p> 174 175 <p>The data model for calendars and event-related information in the Calendar Provider is 176 defined by {@link android.provider.CalendarContract}. All the users calendar data is stored in a 177 number 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 181 information. Each row in this table contains the details for a single calendar, such as the name, 182 color, sync information, and so on.</li> 183 184 <li>The {@link android.provider.CalendarContract.Events} table holds event-specific information. 185 Each row in this table contains the information for a single event, such as the 186 event title, location, start time, end time, and so on. The event can occur one time or recur 187 multiple times. Attendees, reminders, and extended properties are stored in separate tables and 188 use the events {@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 191 occurrences of an event. Each row in this table represents a single occurrence. For one-time events 192 there is a one-to-one mapping of instances to events. For recurring events, multiple rows are 193 automatically 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 196 information. Each row represents a single guest of an event. It specifies the type of guest the 197 person is and the persons response for the event.</li> 198 199 <li>The {@link android.provider.CalendarContract.Reminders} table holds the alert/notification data. 200 Each row represents a single alert for an event. An event can have multiple reminders. The number of 201 reminders per event is specified in {@code MAX_REMINDERS}, which is set by the sync adapter that 202 owns the given calendar. Reminders are specified in number-of-minutes before the event is 203 scheduled and specify an alarm method such as to use an alert, email, or SMS to remind 204 the user.</li> 205 206 <li>The {@link android.provider.CalendarContract.ExtendedProperties} table hold opaque data fields 207 used by the sync adapter. The provider takes no action with items in this table except to delete 208 them when their related events are deleted.</li> 209 </ul> 210 211 <p>To access a users calendar data with the Calendar Provider, your application must request 212 the {@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 users calendar, you can use an {@link 219 android.content.Intent#ACTION_INSERT} intent with the data defined by {@link 220 android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI} in order to start an 221 activity in the Calendar app that creates new events. Using the intent does not require any 222 permission 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 226 event</li> 227 <li>{@link 228 android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_BEGIN_TIME}: 229 Event begin time in milliseconds from the 230 epoch</li> 231 <li>{@link 232 android.provider.CalendarContract#EXTRA_EVENT_END_TIME CalendarContract.EXTRA_EVENT_END_TIME}: Event 233 end time in milliseconds from the epoch</li> 234 <li>{@link android.provider.CalendarContract.EventsColumns#EVENT_LOCATION Events.EVENT_LOCATION}: 235 Location of the event</li> 236 <li>{@link android.provider.CalendarContract.EventsColumns#DESCRIPTION Events.DESCRIPTION}: Event 237 description</li> 238 <li>{@link android.content.Intent#EXTRA_EMAIL Intent.EXTRA_EMAIL}: Email addresses of those to 239 invite</li> 240 <li>{@link android.provider.CalendarContract.EventsColumns#RRULE Events.RRULE}: The recurrence 241 rule for the event</li> 242 <li>{@link android.provider.CalendarContract.EventsColumns#ACCESS_LEVEL Events.ACCESS_LEVEL}: 243 Whether the event is private or public</li> 244 <li>{@link android.provider.CalendarContract.EventsColumns#AVAILABILITY Events.AVAILABILITY}: 245 Whether 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 254 device, in order to present all the user's voicemails in a single visual presentation. For instance, 255 its possible that a user has multiple voicemail sources, such as 256 one from the phones service provider and others from VoIP or other alternative voice 257 services. These apps can use the Voicemail Provider APIs to add their voicemails to the device. The 258 built-in Phone application then presents all voicemails to the user in a unified presentation. 259 Although the systems Phone application is the only application that can read all the voicemails, 260 each application that provides voicemails can read those that it has added to the system (but cannot 261 read 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 264 system, the only third-party apps that should use the voicemail APIs are those that have voicemail 265 to deliver to the user.</p> 266 267 <p>The {@link android.provider.VoicemailContract} class defines the content provider for the 268 Voicemail Provder. The subclasses {@link android.provider.VoicemailContract.Voicemails} and {@link 269 android.provider.VoicemailContract.Status} provide tables in which apps can 270 insert 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 272 Demo</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, 281 videos, 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 287 videos. For example, image effects allow you to easily fix red-eye, convert an image to grayscale, 288 adjust brightness, adjust saturation, rotate an image, apply a fisheye effect, and much more. The 289 system 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 292 must have a valid OpenGL context before it can use the effects APIs. The textures to which you apply 293 effects may be from bitmaps, videos or even the camera. However, there are certain restrictions that 294 textures 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 301 an 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 305 EffectContext.createWithCurrentGlContext()} from your OpenGL ES 2.0 context.</li> 306 <li>Use the returned {@link android.media.effect.EffectContext} to call {@link 307 android.media.effect.EffectContext#getFactory EffectContext.getFactory()}, which returns an instance 308 of {@link android.media.effect.EffectFactory}.</li> 309 <li>Call {@link android.media.effect.EffectFactory#createEffect createEffect()}, passing it an 310 effect name from @link android.media.effect.EffectFactory}, such as {@link 311 android.media.effect.EffectFactory#EFFECT_FISHEYE} or {@link 312 android.media.effect.EffectFactory#EFFECT_VIGNETTE}.</li> 313 </ol> 314 315 <p>You can adjust an effects parameters by calling {@link android.media.effect.Effect#setParameter 316 setParameter()} and passing a parameter name and parameter value. Each type of effect accepts 317 different parameters, which are documented with the effect name. For example, {@link 318 android.media.effect.EffectFactory#EFFECT_FISHEYE} has one parameter for the {@code scale} of the 319 distortion.</p> 320 321 <p>To apply an effect on a texture, call {@link android.media.effect.Effect#apply apply()} on the 322 {@link 323 android.media.effect.Effect} and pass in the input texture, its width and height, and the output 324 texture. The input texture must be bound to a {@link android.opengl.GLES20#GL_TEXTURE_2D} texture 325 image (usually done by calling the {@link android.opengl.GLES20#glTexImage2D glTexImage2D()} 326 function). You may provide multiple mipmap levels. If the output texture has not been bound to a 327 texture image, it will be automatically bound by the effect as a {@link 328 android.opengl.GLES20#GL_TEXTURE_2D} and with one mipmap level (0), which will have the same 329 size as the input.</p> 330 331 <p>All effects listed in {@link android.media.effect.EffectFactory} are guaranteed to be supported. 332 However, some additional effects available from external libraries are not supported by all devices, 333 so 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 340 controls from remote control clients such as the device lock screen. Media players can also expose 341 information about the media currently playing for display on the remote control, such as track 342 information and album art.</p> 343 344 <p>To enable remote control clients for your media player, instantiate a {@link 345 android.media.RemoteControlClient} with its constructor, passing it a {@link 346 android.app.PendingIntent} that broadcasts {@link 347 android.content.Intent#ACTION_MEDIA_BUTTON}. The intent must also declare the explicit {@link 348 android.content.BroadcastReceiver} component in your app that handles the {@link 349 android.content.Intent#ACTION_MEDIA_BUTTON} event.</p> 350 351 <p>To declare which media control inputs your player can handle, you must call {@link 352 android.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 355 android.media.RemoteControlClient#FLAG_KEY_MEDIA_NEXT}.</p> 356 357 <p>You must then register your {@link android.media.RemoteControlClient} by passing it to {@link 358 android.media.AudioManager#registerRemoteControlClient MediaManager.registerRemoteControlClient()}. 359 Once registered, the broadcast receiver you declared when you instantiated the {@link 360 android.media.RemoteControlClient} will receive {@link android.content.Intent#ACTION_MEDIA_BUTTON} 361 events when a button is pressed from a remote control. The intent you receive includes the {@link 362 android.view.KeyEvent} for the media key pressed, which you can retrieve from the intent with {@link 363 android.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 366 android.media.RemoteControlClient#editMetadata editMetaData()} and add metadata to the returned 367 {@link android.media.RemoteControlClient.MetadataEditor}. You can supply a bitmap for media artwork, 368 numerical information such as elapsed time, and text information such as the track title. For 369 information on available keys see the {@code METADATA_KEY_*} flags in {@link 370 android.media.MediaMetadataRetriever}.</p> 371 372 <p>For a sample implementation, see the <a 373 href="{@docRoot}resources/samples/RandomMusicPlayer/index.html">Random Music Player</a>, which 374 provides compatibility logic such that it enables the remote control client on Android 4.0 375 devices 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 382 android.Manifest.permission#INTERNET} permission. If you use {@link android.media.MediaPlayer} to 383 play content from the Internet, be sure to add the {@link android.Manifest.permission#INTERNET} 384 permission to your manifest or else your media playback will not work beginning with Android 385 4.0.</li> 386 387 <li>{@link android.media.MediaPlayer#setSurface(Surface) setSurface()} allows you define a {@link 388 android.view.Surface} to behave as the video sink.</li> 389 390 <li>{@link android.media.MediaPlayer#setDataSource(Context,Uri,Map) setDataSource()} allows you to 391 send 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 407 Formats</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 416 focus and metering areas.</p> 417 418 419 <h4>Face detection</h4> 420 421 <p>Camera apps can now enhance their abilities with Androids face detection APIs, which not 422 only 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 426 android.hardware.Camera.FaceDetectionListener} by calling {@link 427 android.hardware.Camera#setFaceDetectionListener setFaceDetectionListener()}. You can then start 428 your camera surface and start detecting faces by calling {@link 429 android.hardware.Camera#startFaceDetection}.</p> 430 431 <p>When the system detects one or more faces in the camera scene, it calls the {@link 432 android.hardware.Camera.FaceDetectionListener#onFaceDetection onFaceDetection()} callback in your 433 implementation 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 437 the 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 440 current field of view</li> 441 <li>An integer betwen 1 and 100 that indicates how confident the system is that the object is a 442 human 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 445 located</li> 446 </ul> 447 448 <p class="note"><strong>Note:</strong> Face detection may not be supported on some 449 devices, so you should check by calling {@link 450 android.hardware.Camera.Parameters#getMaxNumDetectedFaces()} and ensure the return 451 value is greater than zero. Also, some devices may not support identification of eyes and mouth, 452 in 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 458 balance 459 and auto-exposure. Both features use the new {@link android.hardware.Camera.Area} class to specify 460 the region of the cameras current view that should be focused or metered. An instance of the {@link 461 android.hardware.Camera.Area} class defines the bounds of the area with a {@link 462 android.graphics.Rect} and the area's weight—representing the level of importance of that 463 area, 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 466 android.hardware.Camera.Parameters#getMaxNumFocusAreas} or {@link 467 android.hardware.Camera.Parameters#getMaxNumMeteringAreas}, respectively. If these return zero, then 468 the device does not support the corresponding feature.</p> 469 470 <p>To specify the focus or metering areas to use, simply call {@link 471 android.hardware.Camera.Parameters#setFocusAreas setFocusAreas()} or {@link 472 android.hardware.Camera.Parameters#setMeteringAreas setMeteringAreas()}. Each take a {@link 473 java.util.List} of {@link android.hardware.Camera.Area} objects that indicate the areas to consider 474 for focus or metering. For example, you might implement a feature that allows the user to set the 475 focus area by touching an area of the preview, which you then translate to an {@link 476 android.hardware.Camera.Area} object and request that the camera focus on that area of the scene. 477 The 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 483 camera app, pass {@link android.hardware.Camera.Parameters#FOCUS_MODE_CONTINUOUS_PICTURE} 484 to {@link android.hardware.Camera.Parameters#setFocusMode setFocusMode()}. When ready to capture 485 a photo, call {@link android.hardware.Camera#autoFocus autoFocus()}. Your {@link 486 android.hardware.Camera.AutoFocusCallback} immediately receives a callback to indicate whether 487 focus was achieved. To resume CAF after receiving the callback, you must call {@link 488 android.hardware.Camera#cancelAutoFocus()}.</p> 489 490 <p class="note"><strong>Note:</strong> Continuous auto focus is also supported when capturing 491 video, using {@link android.hardware.Camera.Parameters#FOCUS_MODE_CONTINUOUS_VIDEO}, which was 492 added 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 499 takePicture()} to save a photo without interrupting the video session. Before doing so, you should 500 call {@link android.hardware.Camera.Parameters#isVideoSnapshotSupported} to be sure the hardware 501 supports it.</li> 502 503 <li>You can now lock auto exposure and white balance with {@link 504 android.hardware.Camera.Parameters#setAutoExposureLock setAutoExposureLock()} and {@link 505 android.hardware.Camera.Parameters#setAutoWhiteBalanceLock setAutoWhiteBalanceLock()} to prevent 506 these properties from changing.</li> 507 508 <li>You can now call {@link android.hardware.Camera#setDisplayOrientation 509 setDisplayOrientation()} while the camera preview is running. Previously, you could call this 510 only 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}: 518 This indicates that the user has captured a new photo. The built-in Camera app invokes this 519 broadcast after a photo is captured and third-party camera apps should also broadcast this intent 520 after capturing a photo.</li> 521 <li>{@link android.hardware.Camera#ACTION_NEW_VIDEO Camera.ACTION_NEW_VIDEO}: 522 This indicates that the user has captured a new video. The built-in Camera app invokes this 523 broadcast after a video is recorded and third-party camera apps should also broadcast this intent 524 after 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 534 another (a process also known as NDEF Push"). The data transfer is initiated when two 535 Android-powered devices that support Android Beam are in close proximity (about 4 cm), usually with 536 their backs touching. The data inside the NDEF message can contain any data that you wish to share 537 between devices. For example, the People app shares contacts, YouTube shares videos, and Browser 538 shares URLs using Android Beam.</p> 539 540 <p>To transmit data between devices using Android Beam, you need to create an {@link 541 android.nfc.NdefMessage} that contains the information you want to share while your activity is in 542 the foreground. You must then pass the {@link android.nfc.NdefMessage} to the system in one of two 543 ways:</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 548 the message you want to send. For instance, you might call this method and pass it your {@link 549 android.nfc.NdefMessage} during your activitys {@link android.app.Activity#onCreate onCreate()} 550 method. Then, whenever Android Beam is activated with another device while the activity is in the 551 foreground, 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 555 implementation of the {@link 556 android.nfc.NfcAdapter.CreateNdefMessageCallback#createNdefMessage createNdefMessage()} 557 method returns the {@link android.nfc.NdefMessage} you want to send. Then pass the {@link 558 android.nfc.NfcAdapter.CreateNdefMessageCallback} implementation to {@link 559 android.nfc.NfcAdapter#setNdefPushMessageCallback setNdefPushMessageCallback()}.</p> 560 <p>In this case, when Android Beam is activated with another device while your activity is in the 561 foreground, the system calls {@link 562 android.nfc.NfcAdapter.CreateNdefMessageCallback#createNdefMessage createNdefMessage()} to retrieve 563 the {@link android.nfc.NdefMessage} you want to send. This allows you to define the {@link 564 android.nfc.NdefMessage} to deliver only once Android Beam is initiated, in case the contents 565 of 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 569 message to the other device, you can implement {@link 570 android.nfc.NfcAdapter.OnNdefPushCompleteCallback} and set it with {@link 571 android.nfc.NfcAdapter#setOnNdefPushCompleteCallback setNdefPushCompleteCallback()}. The system will 572 then call {@link android.nfc.NfcAdapter.OnNdefPushCompleteCallback#onNdefPushComplete 573 onNdefPushComplete()} 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 576 tags. The system invokes an intent with the {@link android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} 577 action to start an activity, with either a URL or a MIME type set according to the first {@link 578 android.nfc.NdefRecord} in the {@link android.nfc.NdefMessage}. For the activity you want to 579 respond, you can declare intent filters for the URLs or MIME types your app cares about. For more 580 information about Tag Dispatch see the <a 581 href="{@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 584 method {@link android.nfc.NdefRecord#createUri createUri} to construct a new {@link 585 android.nfc.NdefRecord} based on either a string or a {@link android.net.Uri} object. If the URI is 586 a special format that you want your application to also receive during an Android Beam event, you 587 should create an intent filter for your activity using the same URI scheme in order to receive the 588 incoming NDEF message.</p> 589 590 <p>You should also pass an Android application record" with your {@link android.nfc.NdefMessage} in 591 order to guarantee that your application handles the incoming NDEF message, even if other 592 applications filter for the same intent action. You can create an Android application record by 593 calling {@link android.nfc.NdefRecord#createApplicationRecord createApplicationRecord()}, passing it 594 your applications package name. When the other device receives the NDEF message with the 595 application record and multiple applications contain activities that handle the specified intent, 596 the system always delivers the message to the activity in your application (based on the matching 597 application record). If the target device does not currently have your application installed, the 598 system uses the Android application record to launch Google Play and take the user to the 599 application in order to install it.</p> 600 601 <p>If your application doesnt use NFC APIs to perform NDEF Push messaging, then Android provides a 602 default behavior: When your application is in the foreground on one device and Android Beam is 603 invoked with another Android-powered device, then the other device receives an NDEF message with an 604 Android application record that identifies your application. If the receiving device has the 605 application installed, the system launches it; if its not installed, Google Play opens and takes 606 the 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 609 href="{@docRoot}guide/topics/connectivity/nfc/nfc.html">NFC Basics</a> developer guide. For some example code 610 using Android Beam, see the <a 611 href="{@docRoot}resources/samples/AndroidBeamDemo/src/com/example/android/beam/Beam.html">Android 612 Beam 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 621 devices and other device types without a hotspot or Internet connection. The Android framework 622 provides a set of Wi-Fi P2P APIs that allow you to discover and connect to other devices when each 623 device supports Wi-Fi Direct, then communicate over a speedy connection across distances much longer 624 than a Bluetooth connection.</p> 625 626 <p>A new package, {@link android.net.wifi.p2p}, contains all the APIs for performing peer-to-peer 627 connections with Wi-Fi. The primary class you need to work with is {@link 628 android.net.wifi.p2p.WifiP2pManager}, which you can acquire by calling {@link 629 android.app.Activity#getSystemService getSystemService(WIFI_P2P_SERVICE)}. The {@link 630 android.net.wifi.p2p.WifiP2pManager} includes APIs that allow you to:</p> 631 <ul> 632 <li>Initialize your application for P2P connections by calling {@link 633 android.net.wifi.p2p.WifiP2pManager#initialize initialize()}</li> 634 635 <li>Discover nearby devices by calling {@link android.net.wifi.p2p.WifiP2pManager#discoverPeers 636 discoverPeers()}</li> 637 638 <li>Start a P2P connection by calling {@link android.net.wifi.p2p.WifiP2pManager#connect 639 connect()}</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 646 callbacks 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 649 information about discovered peers. The callback provides a {@link 650 android.net.wifi.p2p.WifiP2pDeviceList}, from which you can retrieve a {@link 651 android.net.wifi.p2p.WifiP2pDevice} object for each device within range and get information such as 652 the 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 655 receive information about a P2P group. The callback provides a {@link 656 android.net.wifi.p2p.WifiP2pGroup} object, which provides group information such as the owner, the 657 network name, and passphrase.</li> 658 659 <li>{@link android.net.wifi.p2p.WifiP2pManager.ConnectionInfoListener} interface allows you to 660 receive information about the current connection. The callback provides a {@link 661 android.net.wifi.p2p.WifiP2pInfo} object, which has information such as whether a group has been 662 formed 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 doesnt technically connect 670 to the Internet, communicating to Wi-Fi Direct peers with standard java sockets requires Internet 671 permission).</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 677 connection state has changed. This carries {@link 678 android.net.wifi.p2p.WifiP2pManager#EXTRA_WIFI_P2P_INFO} with a {@link 679 android.net.wifi.p2p.WifiP2pInfo} object and {@link 680 android.net.wifi.p2p.WifiP2pManager#EXTRA_NETWORK_INFO} with a {@link android.net.NetworkInfo} 681 object.</li> 682 683 <li>{@link android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_STATE_CHANGED_ACTION}: The P2P state has 684 changed between enabled and disabled. It carries {@link 685 android.net.wifi.p2p.WifiP2pManager#EXTRA_WIFI_STATE} with either {@link 686 android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_STATE_DISABLED} or {@link 687 android.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 690 devices has changed.</li> 691 692 <li>{@link android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_THIS_DEVICE_CHANGED_ACTION}: The details for 693 this device have changed.</li> 694 </ul> 695 696 <p>See the {@link android.net.wifi.p2p.WifiP2pManager} documentation for more information. Also 697 look at the <a href="{@docRoot}resources/samples/WiFiDirectDemo/index.html">Wi-Fi Direct Demo</a> 698 sample 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 707 Bluetooth to communicate with health devices that support Bluetooth, such as heart-rate monitors, 708 blood meters, thermometers, and scales.</p> 709 710 <p>Similar to regular headset and A2DP profile devices, you must call {@link 711 android.bluetooth.BluetoothAdapter#getProfileProxy getProfileProxy()} with a {@link 712 android.bluetooth.BluetoothProfile.ServiceListener} and the {@link 713 android.bluetooth.BluetoothProfile#HEALTH} profile type to establish a connection with the profile 714 proxy object.</p> 715 716 <p>Once youve acquired the Health Profile proxy (the {@link android.bluetooth.BluetoothHealth} 717 object), connecting to and communicating with paired health devices involves the following new 718 Bluetooth classes:</p> 719 <ul> 720 <li>{@link android.bluetooth.BluetoothHealthCallback}: You must extend this class and implement the 721 callback methods to receive updates about changes in the applications registration state and 722 Bluetooth channel state.</li> 723 <li>{@link android.bluetooth.BluetoothHealthAppConfiguration}: During callbacks to your {@link 724 android.bluetooth.BluetoothHealthCallback}, youll receive an instance of this object, which 725 provides configuration information about the available Bluetooth health device, which you must use 726 to perform various operations such as initiate and terminate connections with the {@link 727 android.bluetooth.BluetoothHealth} APIs.</li> 728 </ul> 729 730 <p>For more information about using the Bluetooth Health Profile, see the documentation for {@link 731 android.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 740 and extended APIs that allow you to provide more information about view content or 741 develop 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 747 screen to hear voice descriptions of the content. Because the explore-by-touch mode works like a 748 virtual cursor, it allows screen readers to identify the descriptive text the same way that screen 749 readers can when the user navigates with a d-pad or trackball—by reading information provided 750 by {@link android.R.attr#contentDescription android:contentDescription} and {@link 751 android.view.View#setContentDescription setContentDescription()} upon a simulated "hover" event. So, 752 consider this is a reminder that you should provide descriptive text for the views in your 753 application, especially for {@link android.widget.ImageButton}, {@link android.widget.EditText}, 754 {@link android.widget.ImageView} and other widgets that might not naturally contain descriptive 755 text.</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 761 implement new callback methods for accessibility events in your custom {@link 762 android.view.View} components.</p> 763 764 <p>It's important to first note that the behavior of the {@link 765 android.view.View#sendAccessibilityEvent sendAccessibilityEvent()} method has changed in Android 766 4.0. As with previous version of Android, when the user enables accessibility services on the device 767 and 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 769 implementation of {@link android.view.View#sendAccessibilityEvent sendAccessibilityEvent()} would 770 initialize an {@link android.view.accessibility.AccessibilityEvent} and send it to {@link 771 android.view.accessibility.AccessibilityManager}. The new behavior involves some additional callback 772 methods that allow the view and its parents to add more contextual information to the event: 773 <ol> 774 <li>When invoked, the {@link 775 android.view.View#sendAccessibilityEvent sendAccessibilityEvent()} and {@link 776 android.view.View#sendAccessibilityEventUnchecked sendAccessibilityEventUnchecked()} methods defer 777 to {@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()}. 778 <p>Custom implementations of {@link android.view.View} might want to implement {@link 779 android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()} to 780 attach additional accessibility information to the {@link 781 android.view.accessibility.AccessibilityEvent}, but should also call the super implementation to 782 provide default information such as the standard content description, item index, and more. 783 However, you should not add additional text content in this callback—that happens 784 next.</p></li> 785 <li>Once initialized, if the event is one of several types that should be populated with text 786 information, the view then receives a call to {@link 787 android.view.View#dispatchPopulateAccessibilityEvent dispatchPopulateAccessibilityEvent()}, which 788 defers to the {@link android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} 789 callback. 790 <p>Custom implementations of {@link android.view.View} should usually implement {@link 791 android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} to add additional 792 text content to the {@link android.view.accessibility.AccessibilityEvent} if the {@link 793 android.R.attr#contentDescription android:contentDescription} text is missing or 794 insufficient. To add more text description to the 795 {@link android.view.accessibility.AccessibilityEvent}, call {@link 796 android.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 800 parent view. Each parent view then has the chance to augment the accessibility information by 801 adding an {@link android.view.accessibility.AccessibilityRecord}, until it 802 ultimately reaches the root view, which sends the event to the {@link 803 android.view.accessibility.AccessibilityManager} with {@link 804 android.view.accessibility.AccessibilityManager#sendAccessibilityEvent 805 sendAccessibilityEvent()}.</li> 806 </ol> 807 808 <p>In addition to the new methods above, which are useful when extending the {@link 809 android.view.View} class, you can also intercept these event callbacks on any {@link 810 android.view.View} by extending {@link 811 android.view.View.AccessibilityDelegate AccessibilityDelegate} and setting it on the view with 812 {@link android.view.View#setAccessibilityDelegate setAccessibilityDelegate()}. 813 When you do, each accessibility method in the view defers the call to the corresponding method in 814 the delegate. For example, when the view receives a call to {@link 815 android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()}, it passes it to the 816 same method in the {@link android.view.View.AccessibilityDelegate}. Any methods not handled by 817 the delegate are given right back to the view for default behavior. This allows you to override only 818 the 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 822 the new the accessibility APIs, you can do so with the latest version of the <em>v4 support 823 library</em> (in <a href="{@docRoot}tools/extras/support-library.html">Compatibility Package, r4</a>) 824 using a set of utility classes that provide the new accessibility APIs in a backward-compatible 825 design.</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 833 has been significantly expanded to enable more advanced accessibility feedback for users. In 834 particular, events are generated based on view composition, providing better context information and 835 allowing accessibility services to traverse view hierarchies to get additional view information and 836 deal with special cases.</p> 837 838 <p>If you're developing an accessibility service (such as a screen reader), you can access 839 additional 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, 842 call the {@link android.view.accessibility.AccessibilityEvent#getRecord(int) 843 AccessibilityEvent.getRecord()} to retrieve a specific {@link 844 android.view.accessibility.AccessibilityRecord} (there may be several records attached to the 845 event).</li> 846 847 <li>From either {@link android.view.accessibility.AccessibilityEvent} or an individual {@link 848 android.view.accessibility.AccessibilityRecord}, you can call {@link 849 android.view.accessibility.AccessibilityRecord#getSource() getSource()} to retrieve a {@link 850 android.view.accessibility.AccessibilityNodeInfo} object. 851 <p>An {@link android.view.accessibility.AccessibilityNodeInfo} represents a single node 852 of the window content in a format that allows you to query accessibility information about that 853 node. The {@link android.view.accessibility.AccessibilityNodeInfo} object returned from {@link 854 android.view.accessibility.AccessibilityEvent} describes the event source, whereas the source from 855 an {@link android.view.accessibility.AccessibilityRecord} describes the predecessor of the event 856 source.</p></li> 857 858 <li>With the {@link android.view.accessibility.AccessibilityNodeInfo}, you can query information 859 about it, call {@link 860 android.view.accessibility.AccessibilityNodeInfo#getParent getParent()} or {@link 861 android.view.accessibility.AccessibilityNodeInfo#getChild getChild()} to traverse the view 862 hierarchy, 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 866 must declare an XML configuration file that corresponds to {@link 867 android.accessibilityservice.AccessibilityServiceInfo}. For more information about creating an 868 accessibility service, see {@link 869 android.accessibilityservice.AccessibilityService} and {@link 870 android.accessibilityservice.AccessibilityService#SERVICE_META_DATA 871 SERVICE_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 877 android.view.accessibility.AccessibilityManager} has some new APIs such as:</p> 878 <ul> 879 <li>{@link android.view.accessibility.AccessibilityManager.AccessibilityStateChangeListener} 880 is an interface that allows you to receive a callback whenever accessibility is enabled or 881 disabled.</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 897 input method framework (for IMEs). To create a new spell checker, you must implement a service that 898 extends 899 {@link android.service.textservice.SpellCheckerService} and extend the {@link 900 android.service.textservice.SpellCheckerService.Session} class to provide spelling suggestions based 901 on text provided by the interface's callback methods. In the {@link 902 android.service.textservice.SpellCheckerService.Session} callback methods, you must return the 903 spelling suggestions as {@link android.view.textservice.SuggestionsInfo} objects. </p> 904 905 <p>Applications with a spell checker service must declare the {@link 906 android.Manifest.permission#BIND_TEXT_SERVICE} permission as required by the service. 907 The service must also declare an intent filter with {@code <action 908 android:name="android.service.textservice.SpellCheckerService" />} as the intents action and should 909 include a {@code <meta-data>} element that declares configuration information for the spell 910 checker. </p> 911 912 <p>See the sample <a href="{@docRoot}resources/samples/SpellChecker/SampleSpellCheckerService/index.html"> 913 Spell Checker Service</a> app and 914 sample <a href="{@docRoot}resources/samples/SpellChecker/HelloSpellChecker/index.html"> 915 Spell Checker Client</a> app for example code.</p> 916 917 918 919 920 <h3 id="TTS">Text-to-speech Engines</h3> 921 922 <p>Androids text-to-speech (TTS) APIs have been significantly extended to allow applications to 923 more easily implement custom TTS engines, while applications that want to use a TTS engine have a 924 couple 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 930 to perform text-to-speech (TTS) operations using the TTS engine provided by the system or set a 931 custom engine using {@link android.speech.tts.TextToSpeech#setEngineByPackageName 932 setEngineByPackageName()}. In Android 4.0, the {@link 933 android.speech.tts.TextToSpeech#setEngineByPackageName setEngineByPackageName()} method has been 934 deprecated and you can now specify the engine to use with a new {@link 935 android.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 938 android.speech.tts.TextToSpeech#getEngines()}. This method returns a list of {@link 939 android.speech.tts.TextToSpeech.EngineInfo} objects, which include meta data such as the engines 940 icon, 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 946 file. 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 949 responds to the {@link android.speech.tts.TextToSpeech.Engine#INTENT_ACTION_TTS_SERVICE} intent. The 950 primary work for a TTS engine happens during the {@link 951 android.speech.tts.TextToSpeechService#onSynthesizeText onSynthesizeText()} callback in a service 952 that extends {@link android.speech.tts.TextToSpeechService}. The system delivers this method two 953 objects:</p> 954 <ul> 955 <li>{@link android.speech.tts.SynthesisRequest}: This contains various data including the text to 956 synthesize, 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 958 delivers the resulting speech data as streaming audio. First the engine must call {@link 959 android.speech.tts.SynthesisCallback#start start()} to indicate that the engine is ready to deliver 960 the audio, then call {@link android.speech.tts.SynthesisCallback#audioAvailable audioAvailable()}, 961 passing it the audio data in a byte buffer. Once your engine has passed all audio through the 962 buffer, 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 966 implementation has been removed. Look for a blog post about a compatibility layer 967 that 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 970 href="{@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. 980 The Settings app provides controls that allow users to manage set limits for network data usage and 981 even disable the use of background data for individual apps. In order to avoid users disabling your 982 apps access to data from the background, you should develop strategies to use the data 983 connection 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 986 allow users to control your apps data habits, such as how often your app syncs data, whether to 987 perform uploads/downloads only when on Wi-Fi, whether to use data while roaming, etc. With these 988 controls available to them, users are much less likely to disable your apps access to data when 989 they approach their limits, because they can instead precisely control how much data your app uses. 990 If you provide a preference activity with these settings, you should include in its manifest 991 declaration an intent filter for the {@link android.content.Intent#ACTION_MANAGE_NETWORK_USAGE} 992 action. 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 1004 applications data usage. Thus, when the user inspects how much data your app is using from the 1005 Settings app, a View application settings" button is available that launches your 1006 preference 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 1009 deprecated and always returns true—use {@link 1010 android.net.ConnectivityManager#getActiveNetworkInfo()} instead. Before you attempt any network 1011 transactions, you should always call {@link android.net.ConnectivityManager#getActiveNetworkInfo()} 1012 to get the {@link android.net.NetworkInfo} that represents the current network and query {@link 1013 android.net.NetworkInfo#isConnected()} to check whether the device has a 1014 connection. You can then check other connection properties, such as whether the device is 1015 roaming 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 1035 android.renderscript.Allocation#USAGE_GRAPHICS_RENDER_TARGET} memory space, which allows you to 1036 render things directly into the {@link android.renderscript.Allocation} and use it as a framebuffer 1037 object.</p> 1038 1039 <p>{@link android.renderscript.RSTextureView} provides a means to display RenderScript graphics 1040 inside of a {@link android.view.View}, unlike {@link android.renderscript.RSSurfaceView}, which 1041 creates a separate window. This key difference allows you to do things such as move, transform, or 1042 animate an {@link android.renderscript.RSTextureView} as well as draw RenderScript graphics inside 1043 a view that lies within an activity layout.</p> 1044 1045 <p>The {@link android.renderscript.Script#forEach Script.forEach()} method allows you to call 1046 RenderScript compute scripts from the VM level and have them automatically delegated to available 1047 cores on the device. You do not use this method directly, but any compute RenderScript that you 1048 write will have a {@link android.renderscript.Script#forEach forEach()} method that you can call in 1049 the reflected RenderScript class. You can call the reflected {@link 1050 android.renderscript.Script#forEach forEach()} method by passing in an input {@link 1051 android.renderscript.Allocation} to process, an output {@link android.renderscript.Allocation} to 1052 write the result to, and a {@link android.renderscript.FieldPacker} data structure in case the 1053 RenderScript needs more information. Only one of the {@link android.renderscript.Allocation}s is 1054 necessary 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 1071 Private Network), running as a {@link android.app.Service}. A VPN service creates an interface for a 1072 virtual network with its own address and routing rules and performs all reading and writing with a 1073 file descriptor.</p> 1074 1075 <p>To create a VPN service, use {@link android.net.VpnService.Builder}, which allows you to specify 1076 the network address, DNS server, network route, and more. When complete, you can establish the 1077 interface by calling {@link android.net.VpnService.Builder#establish()}, which returns a {@link 1078 android.os.ParcelFileDescriptor}. </p> 1079 1080 <p>Because a VPN service can intercept packets, there are security implications. As such, if you 1081 implement {@link android.net.VpnService}, then your service must require the {@link 1082 android.Manifest.permission#BIND_VPN_SERVICE} to ensure that only the system can bind to it (only 1083 the system is granted this permission—apps cannot request it). To then use your VPN service, 1084 users 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 1090 android.app.admin.DevicePolicyManager#setCameraDisabled setCameraDisabled()} and the {@link 1091 android.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 1098 certificates in the system key store. Certificates streamline the installation of both client 1099 certificates (to validate the identity of the user) and certificate authority certificates (to 1100 verify server identity). Applications such as web browsers or email clients can access the installed 1101 certificates to authenticate users to servers. See the {@link android.security.KeyChain} 1102 documentation 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 1116 the ambient (room) temperature in degrees Celsius.</li> 1117 <li>{@link android.hardware.Sensor#TYPE_RELATIVE_HUMIDITY}: A humidity sensor that provides the 1118 relative 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 1122 android.hardware.Sensor#TYPE_RELATIVE_HUMIDITY} sensors, you can use them to calculate the dew point 1123 and the absolute humidity.</p> 1124 1125 <p>The previous temperature sensor, {@link android.hardware.Sensor#TYPE_TEMPERATURE}, has been 1126 deprecated. You should use the {@link android.hardware.Sensor#TYPE_AMBIENT_TEMPERATURE} sensor 1127 instead.</p> 1128 1129 <p>Additionally, Androids three synthetic sensors have been greatly improved so they now have lower 1130 latency and smoother output. These sensors include the gravity sensor ({@link 1131 android.hardware.Sensor#TYPE_GRAVITY}), rotation vector sensor ({@link 1132 android.hardware.Sensor#TYPE_ROTATION_VECTOR}), and linear acceleration sensor ({@link 1133 android.hardware.Sensor#TYPE_LINEAR_ACCELERATION}). The improved sensors rely on the gyroscope 1134 sensor 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 1143 importantly, the system gracefully manages the action bars size and configuration when running on 1144 smaller screens in order to provide an optimal user experience on all screen sizes. For example, 1145 when the screen is narrow (such as when a handset is in portrait orientation), the action bars 1146 navigation tabs appear in a stacked bar," which appears directly below the main action bar. You can 1147 also opt-in to a split action bar," which places all action items in a separate bar at the bottom 1148 of 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 1154 a narrow screen, so the system will place more of them into the overflow menu. However, Android 4.0 1155 allows you to enable split action bar" so that more action items can appear on the screen in a 1156 separate bar at the bottom of the screen. To enable split action bar, add {@link 1157 android.R.attr#uiOptions android:uiOptions} with {@code "splitActionBarWhenNarrow"} to either your 1158 <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> 1159 tag or 1160 individual <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code 1161 <activity>}</a> tags 1162 in your manifest file. When enabled, the system will add an additional bar at the bottom of the 1163 screen for all action items when the screen is narrow (no action items will appear in the primary 1164 action bar).</p> 1165 1166 <p>If you want to use the navigation tabs provided by the {@link android.app.ActionBar.Tab} APIs, 1167 but dont need the main action bar on top (you want only the tabs to appear at the top), then enable 1168 the split action bar as described above and also call {@link 1169 android.app.ActionBar#setDisplayShowHomeEnabled setDisplayShowHomeEnabled(false)} to disable the 1170 application icon in the action bar. With nothing left in the main action bar, it 1171 disappears—all thats left are the navigation tabs at the top and the action items at the 1172 bottom 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 1178 android.R.attr#backgroundStacked} and {@link android.R.attr#backgroundSplit} to apply a background 1179 drawable or color to the stacked bar and split bar, respectively. You can also set these styles at 1180 runtime with {@link android.app.ActionBar#setStackedBackgroundDrawable 1181 setStackedBackgroundDrawable()} and {@link android.app.ActionBar#setSplitBackgroundDrawable 1182 setSplitBackgroundDrawable()}.</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 1188 action items. An action provider can define an action view, a default action behavior, and a submenu 1189 for each action item to which it is associated. When you want to create an action item that has 1190 dynamic behaviors (such as a variable action view, default action, or submenu), extending {@link 1191 android.view.ActionProvider} is a good solution in order to create a reusable component, rather than 1192 handling 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 1195 android.view.ActionProvider} that facilitates a share" action from the action bar. Instead of using 1196 traditional action item that invokes the {@link android.content.Intent#ACTION_SEND} intent, you can 1197 use this action provider to present an action view with a drop-down list of applications that handle 1198 the {@link android.content.Intent#ACTION_SEND} intent. When the user selects an application to use 1199 for the action, {@link android.widget.ShareActionProvider} remembers that selection and provides it 1200 in 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} 1203 attribute in the <a href="{@docRoot}guide/topics/resources/menu-resource.html#item-element">{@code 1204 <item>}</a> element for your activitys options menu, with the class name of the action 1205 provider 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 activitys {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} 1215 callback method, retrieve an instance of the action provider from the menu item and set the 1216 intent:</p> 1217 1218 <pre> 1219 public 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 1231 href="{@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 1238 traditional action item state. Previously only the {@link android.widget.SearchView} supported 1239 collapsing when used as an action view, but now you can add an action view for any action item and 1240 switch between the expanded state (action view is visible) and collapsed state (action item is 1241 visible).</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 1245 href="{@docRoot}guide/topics/resources/menu-resource.html#item-element">{@code 1246 <item>}</a> element in the menus XML file.</p> 1247 1248 <p>To receive callbacks when an action view switches between expanded and collapsed, register an 1249 instance of {@link android.view.MenuItem.OnActionExpandListener} with the respective {@link 1250 android.view.MenuItem} by calling {@link android.view.MenuItem#setOnActionExpandListener 1251 setOnActionExpandListener()}. Typically, you should do so during the {@link 1252 android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} callback.</p> 1253 1254 <p>To control a collapsible action view, you can call {@link 1255 android.view.MenuItem#collapseActionView()} and {@link android.view.MenuItem#expandActionView()} on 1256 the respective {@link android.view.MenuItem}.</p> 1257 1258 <p>When creating a custom action view, you can also implement the new {@link 1259 android.view.CollapsibleActionView} interface to receive callbacks when the view is expanded and 1260 collapsed.</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 1266 whether the icon/logo behaves as a button to navigate home or up" (pass true" to make it behave as 1267 a button).</li> 1268 1269 <li>{@link android.app.ActionBar#setIcon setIcon()} and {@link android.app.ActionBar#setLogo 1270 setLogo()} 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 1273 or disable the visibility of the options menu items declared by the fragment. This is useful if the 1274 fragment has been added to the activity, but is not visible, so the menu items should be 1275 hidden.</li> 1276 1277 <li>{@link android.app.FragmentManager#invalidateOptionsMenu 1278 FragmentManager.invalidateOptionsMenu()} 1279 allows you to invalidate the activity options menu during various states of the fragment lifecycle 1280 in 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 1298 grid. Unlike {@link android.widget.TableLayout}, {@link android.widget.GridLayout} relies on a flat 1299 hierarchy and does not make use of intermediate views such as table rows for providing structure. 1300 Instead, children specify which row(s) and column(s) they should occupy (cells can span multiple 1301 rows and/or columns), and by default are laid out sequentially across the grids rows and columns. 1302 The {@link android.widget.GridLayout} orientation determines whether sequential children are by 1303 default laid out horizontally or vertically. Space between children may be specified either by using 1304 instances of the new {@link android.widget.Space} view or by setting the relevant margin parameters 1305 on children.</p> 1306 1307 <p>See <a 1308 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/index.html">ApiDemos</a 1309 > 1310 for 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 1317 as a video or an OpenGL scene. Although similar to {@link android.view.SurfaceView}, {@link 1318 android.view.TextureView} is unique in that it behaves like a regular view, rather than creating a 1319 separate window, so you can treat it like any other {@link android.view.View} object. For example, 1320 you can apply transforms, animate it using {@link android.view.ViewPropertyAnimator}, or 1321 adjust 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 1331 side 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 1334 to appear on the switch when in the on and off setting. The {@code android:text} attribute also 1335 allows you to place a label alongside the switch.</p> 1336 1337 <p>For a sample using switches, see the <a 1338 href="{@docRoot}resources/samples/ApiDemos/res/layout/switches.html">switches.xml</a> layout file 1339 and respective <a 1340 href="{@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 1347 up at an anchor point you specify (usually at the point of the item selected). Android 4.0 extends 1348 the {@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 1351 href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a> with {@link 1352 android.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 1354 callback 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 1361 preferences that provide a two-state selection option. The new {@link 1362 android.preference.SwitchPreference} is an extension of {@link 1363 android.preference.TwoStatePreference} that provides a {@link android.widget.Switch} widget in the 1364 preference view to allow users to toggle a setting on or off without the need to open an additional 1365 preference screen or dialog. For example, the Settings application uses a {@link 1366 android.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 1373 href="{@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 1377 the 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 1380 from one device to another when running the same version of Android. If you explicitly 1381 apply any of the {@link android.R.style#Theme_Holo Theme.Holo} themes to your activities, you can 1382 rest assured that these themes will not change character on different devices within the same 1383 platform version.</p> 1384 1385 <p>If you wish for your app to blend in with the overall device theme (such as when different OEMs 1386 provide different default themes for the system), you should explicitly apply themes from the {@link 1387 android.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. 1393 However, there's no need for you to worry about this if your existing application provides an <a 1394 href="{@docRoot}guide/topics/ui/menus.html#options-menu">options menu</a> and expects there to be a 1395 Menu button. To ensure that existing apps continue to work as they expect, the system provides an 1396 on-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 1399 android.app.ActionBar} to provide access to menu items and set <a 1400 href="{@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 id="SystemUI">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 1408 bar</em>, which resides at the top of handset devices to deliver information such as the carrier 1409 signal, time, notifications, and so on. Android 3.0 added the <em>system bar</em> for tablet 1410 devices, which resides at the bottom of the screen to provide system navigation controls (Home, 1411 Back, and so forth) and also an interface for elements traditionally provided by the status bar. In 1412 Android 4.0, the system provides a new type of system UI called the <em>navigation bar</em>. You 1413 might consider the navigation bar a re-tuned version of the system bar designed for 1414 handsets—it provides navigation controls 1415 for devices that dont have hardware counterparts for navigating the system, but it leaves out the 1416 system bar's notification UI and setting controls. As such, a device that provides the navigation 1417 bar 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 1420 android.view.WindowManager.LayoutParams#FLAG_FULLSCREEN} flag. In Android 4.0, the APIs that control 1421 the system bars visibility have been updated to better reflect the behavior of both the system bar 1422 and navigation bar:</p> 1423 <ul> 1424 <li>The {@link android.view.View#SYSTEM_UI_FLAG_LOW_PROFILE} flag replaces the {@code 1425 STATUS_BAR_HIDDEN} flag. When set, this flag enables low profile" mode for the system bar or 1426 navigation bar. Navigation buttons dim and other elements in the system bar also hide. Enabling 1427 this is useful for creating more immersive games without distraction for the system navigation 1428 buttons.</li> 1429 1430 <li>The {@link android.view.View#SYSTEM_UI_FLAG_VISIBLE} flag replaces the {@code 1431 STATUS_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 1434 the navigation bar hide completely. Be aware that this works only for the <em>navigation bar</em> 1435 used by some handsets (it does <strong>not</strong> hide the system bar on tablets). The navigation 1436 bar returns to view as soon as the system receives user input. As such, this mode is useful 1437 primarily for video playback or other cases in which the whole screen is needed but user input is 1438 not required.</li> 1439 </ul> 1440 1441 <p>You can set each of these flags for the system bar and navigation bar by calling {@link 1442 android.view.View#setSystemUiVisibility setSystemUiVisibility()} on any view in your activity. The 1443 window manager combines (OR-together) all flags from all views in your window and 1444 apply them to the system UI as long as your window has input focus. When your window loses input 1445 focus (the user navigates away from your app, or a dialog appears), your flags cease to have effect. 1446 Similarly, 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 1449 example, 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 1451 of the system bar or navigation bar changes.</p> 1452 1453 <p>See the <a 1454 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/OverscanActivity.html"> 1455 OverscanActivity</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 1468 through the use of pointer devices (such as a mouse or other devices that drive an on-screen 1469 cursor).</p> 1470 1471 <p>To receive hover events on a view, implement the {@link android.view.View.OnHoverListener} and 1472 register it with {@link android.view.View#setOnHoverListener setOnHoverListener()}. When a hover 1473 event occurs on the view, your listener receives a call to {@link 1474 android.view.View.OnHoverListener#onHover onHover()}, providing the {@link android.view.View} that 1475 received the event and a {@link android.view.MotionEvent} that describes the type of hover event 1476 that 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 1484 android.view.View.OnHoverListener#onHover onHover()} if it handles the hover event. If your 1485 listener 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 1488 current state, you can now use the {@code android:state_hovered} attribute in a <a 1489 href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">state list drawable</a> to 1490 provide 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 1493 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/Hover.html">Hover</a> class in 1494 ApiDemos.</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 1500 tablet 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 1503 with the digitizer, applications receive touch events just like they would when a finger is used to 1504 touch the display. When the stylus is hovering above the digitizer, applications receive hover 1505 events just like they would when a mouse pointer was being moved across the display when no buttons 1506 are 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 1510 android.view.MotionEvent#getToolType getToolType()}. The currently defined tool types are: {@link 1511 android.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}, 1513 and {@link android.view.MotionEvent#TOOL_TYPE_ERASER}. By querying the tool type, your application 1514 can 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 1517 state" of a {@link android.view.MotionEvent} using {@link android.view.MotionEvent#getButtonState 1518 getButtonState()}. The currently defined button states are: {@link 1519 android.view.MotionEvent#BUTTON_PRIMARY}, {@link android.view.MotionEvent#BUTTON_SECONDARY}, {@link 1520 android.view.MotionEvent#BUTTON_TERTIARY}, {@link android.view.MotionEvent#BUTTON_BACK}, and {@link 1521 android.view.MotionEvent#BUTTON_FORWARD}. For convenience, the back and forward mouse buttons are 1522 automatically mapped to the {@link android.view.KeyEvent#KEYCODE_BACK} and {@link 1523 android.view.KeyEvent#KEYCODE_FORWARD} keys. Your application can handle these keys to support 1524 mouse 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 1527 devices also report the distance between the stylus tip and the digitizer, the stylus tilt angle, 1528 and the stylus orientation angle. Your application can query this information using {@link 1529 android.view.MotionEvent#getAxisValue getAxisValue()} with the axis codes {@link 1530 android.view.MotionEvent#AXIS_DISTANCE}, {@link android.view.MotionEvent#AXIS_TILT}, and {@link 1531 android.view.MotionEvent#AXIS_ORIENTATION}.</p> 1532 1533 <p>For a demonstration of tool types, button states and the new axis codes, see the <a 1534 href="{@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 1545 property on any object that allows callers to generically set/get values on target objects. It also 1546 allows the functionality of passing around field/method references and allows code to set/get values 1547 of 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 1550 previously do this:</p> 1551 <pre> 1552 foo.bar = value; 1553 </pre> 1554 1555 <p>If you want to call the setter for an underlying private field {@code bar}, you would previously 1556 do this:</p> 1557 <pre> 1558 foo.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} 1565 object {@code BAR} on class {@code Foo} so that you can set the field on instance {@code foo} of 1566 class {@code Foo} like this:</p> 1567 <pre> 1568 BAR.set(foo, value); 1569 </pre> 1570 1571 <p>The {@link android.view.View} class now leverages the {@link android.util.Property} class to 1572 allow you to set various fields, such as transform properties that were added in Android 3.0 ({@link 1573 android.view.View#ROTATION}, {@link android.view.View#ROTATION_X}, {@link 1574 android.view.View#TRANSLATION_X}, etc.).</p> 1575 1576 <p>The {@link android.animation.ObjectAnimator} class also uses the {@link android.util.Property} 1577 class, so you can create an {@link android.animation.ObjectAnimator} with a {@link 1578 android.util.Property}, which is faster, more efficient, and more type-safe than the string-based 1579 approach.</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 1589 application has set either <a 1590 href="{@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 1593 scrolling, and overall better performance and response to user interaction.</p> 1594 1595 <p>If necessary, you can manually disable hardware acceleration with the <a 1596 href="{@docRoot}guide/topics/manifest/activity-element.html#hwaccel">{@code hardwareAccelerated}</a> 1597 attribute for individual <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code 1598 <activity>}</a> elements or the <a 1599 href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> 1600 element. You can alternatively disable hardware acceleration for individual views by calling {@link 1601 android.view.View#setLayerType setLayerType(LAYER_TYPE_SOFTWARE)}.</p> 1602 1603 <p>For more information about hardware acceleration, including a list of unsupported drawing 1604 operations, see the <a href="{@docRoot}guide/topics/graphics/hardware-accel.html">Hardware 1605 Acceleration</a> document.</p> 1606 1607 1608 1609 <h3 id="Jni">JNI Changes</h3> 1610 1611 <p>In previous versions of Android, JNI local references werent indirect handles; Android used 1612 direct pointers. This wasn't a problem as long as the garbage collector didn't move objects, but it 1613 seemed to work because it made it possible to write buggy code. In Android 4.0, the system now uses 1614 indirect 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 1617 href="{@docRoot}guide/practices/jni.html">JNI Tips</a>. In Android 4.0, <a 1618 href="http://android-developers.blogspot.com/2011/07/debugging-android-jni-with-checkjni.html"> 1619 CheckJNI</a> has been enhanced to detect these errors. Watch the <a 1620 href="http://android-developers.blogspot.com/">Android Developers Blog</a> for an upcoming post 1621 about 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 1624 the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code 1625 targetSdkVersion}</a> or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code 1626 minSdkVersion}</a> to {@code 14"} or higher. If youve set these attributes to any lower value, 1627 then 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 1637 needed 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 1639 built-in Browser</li> 1640 <li>Support for <a 1641 href="http://google-opensource.blogspot.com/2009/05/introducing-webdriver.html">WebDriver</a> makes 1642 it 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 1652 href="{@docRoot}about/versions/android-3.0.html">Android 1653 3.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 1658 events</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 1671 messages to the device.</li> 1672 <li>{@link android.Manifest.permission#BIND_TEXT_SERVICE}: A service that implements {@link 1673 android.service.textservice.SpellCheckerService} must require this permission for itself.</li> 1674 <li>{@link android.Manifest.permission#BIND_VPN_SERVICE}: A service that implements {@link 1675 android.net.VpnService} must require this permission for itself.</li> 1676 <li>{@link android.Manifest.permission#READ_PROFILE}: Provides read access to the {@link 1677 android.provider.ContactsContract.Profile} provider.</li> 1678 <li>{@link android.Manifest.permission#WRITE_PROFILE}: Provides write access to the {@link 1679 android.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 1689 uses 1690 Wi-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 1697 href="{@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. 1704 Because the Android 3.x platform is available only for large-screen devices, if you've 1705 been developing primarily for handsets, then you might not be aware of all the APIs added to Android 1706 in 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 1709 on 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 1716 elements 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 1719 the activity window. It includes the application logo in the left corner and provides a new 1720 interface 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 1723 loading of data in combination with UI components to dynamically load data without blocking the 1724 main 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 1727 the 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 1730 operations. 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 1733 object (View, Drawable, Fragment, Object, or anything else) and define animation aspects such 1734 as duration, interpolation, repeat and more. The new framework makes Animations in Android 1735 simpler than ever. See the 1736 <a href="{@docRoot}guide/topics/graphics/prop-animation.html">Property Animation</a> developer 1737 guide.</li> 1738 <li>RenderScript graphics and compute engine: RenderScript offers a high performance 3D 1739 graphics rendering and compute API at the native level, which you write in the C (C99 standard), 1740 providing the type of performance you expect from a native environment while remaining portable 1741 across various CPUs and GPUs. See the 1742 <a href="{@docRoot}guide/topics/renderscript/index.html">RenderScript</a> developer 1743 guide.</li> 1744 <li>Hardware accelerated 2D graphics: You can now enable the OpenGL renderer for your 1745 application by setting {android:hardwareAccelerated="true"} in your manifest element's <a 1746 href="{@docRoot}guide/topics/manifest/application-element.html"><code><application></code></a> 1747 element or for individual <a 1748 href="{@docRoot}guide/topics/manifest/activity-element.html"><code><activity></code></a> 1749 elements. This results 1750 in smoother animations, smoother scrolling, and overall better performance and response to user 1751 interaction. 1752 <p class="note"><strong>Note:</strong> If you set your application's <a 1753 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a 1754 href="{@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> 1757 notes 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 1765 Android applications. The APIs are based on a USB stack and services that are 1766 built into the platform, including support for both USB host and device interactions. See the <a 1767 href="{@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 1769 devices to receive notifications when devices are attached and removed, manage files and storage on 1770 those 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, 1774 which applications can use to manage on-demand or interactive data streaming. In particular, apps 1775 that provide VOIP, push-to-talk, conferencing, and audio streaming can use the API to initiate 1776 sessions and transmit or receive data streams over any available network. See the {@link 1777 android.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> 1780 notes 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 1788 displayed across different screen sizes. The API extends the existing screen support model with the 1789 ability to precisely target specific screen size ranges by dimensions, measured in 1790 density-independent pixel units (such as 600dp or 720dp wide), rather than by their generalized 1791 screen sizes (such as large or xlarge). For example, this is important in order to help you 1792 distinguish between a 5" device and a 7" device, which would both traditionally be bucketed as 1793 "large" screens. See the blog post, <a 1794 href="http://android-developers.blogspot.com/2011/07/new-tools-for-managing-screen-sizes.html"> 1795 New Tools for Managing Screen Sizes</a>.</li> 1796 <li>New constants for <a 1797 href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> to 1798 declare landscape or portrait screen orientation requirements.</li> 1799 <li>The device "screen size" configuration now changes during a screen orientation 1800 change. If your app targets API level 13 or higher, you must handle the {@code "screenSize"} 1801 configuration 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 1803 android:configChanges}</a> for more information.</li> 1804 <li>See the <a href="android-3.2.html">Android 3.2 Platform</a> 1805 notes 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 1817 identifier—<strong>{@sdkPlatformApiLevel}</strong>—that is stored in the system itself. 1818 This identifier, called the "API level", allows the system to correctly determine whether an 1819 application 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 1822 application against an Android platform that supports API level {@sdkPlatformApiLevel} or 1823 higher. 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> 1826 element.</p> 1827 1828 <p>For more information, read <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">What is API 1829 Level?</a></p> 1830
