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