page.title=Android 4.0 APIs sdk.platform.version=4.0 sdk.platform.apiLevel=14 @jd:body

In this document

  1. API Overview
  2. Previous APIs
  3. API Level

Reference

  1. API Differences Report »

API Level: {@sdkPlatformApiLevel}

Android 4.0 ({@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH}) is a major platform release that adds a variety of new features for users and app developers. Besides all the new features and APIs discussed below, Android 4.0 is an important platform release because it brings the extensive set of APIs and Holographic themes from Android 3.x to smaller screens. As an app developer, you now have a single platform and unified API framework that enables you to develop and publish your application with a single APK that provides an optimized user experience for handsets, tablets, and more, when running the same version of Android—Android 4.0 (API level 14) or greater.

For developers, the Android {@sdkPlatformVersion} platform is available as a downloadable component for the Android SDK. The downloadable platform includes an Android library and system image, as well as a set of emulator skins and more. To get started developing or testing against Android {@sdkPlatformVersion}, use the Android SDK Manager to download the platform into your SDK.

API Overview

The sections below provide a technical overview of new APIs in Android 4.0.

Table of Contents

  1. Social APIs in Contacts Provider
  2. Calendar Provider
  3. Voicemail Provider
  4. Multimedia
  5. Camera
  6. Android Beam (NDEF Push with NFC)
  7. Wi-Fi Direct
  8. Bluetooth Health Devices
  9. Accessibility
  10. Spell Checker Services
  11. Text-to-speech Engines
  12. Network Usage
  13. RenderScript
  14. Enterprise
  15. Device Sensors
  16. Action Bar
  17. User Interface and Views
  18. Input Framework
  19. Properties
  20. Hardware Acceleration
  21. JNI Changes
  22. WebKit
  23. Permissions
  24. Device Features

Social APIs in Contacts Provider

The contact APIs defined by the {@link android.provider.ContactsContract} provider have been extended to support new social-oriented features such as a personal profile for the device owner and the ability for users to invite individual contacts to social networks that are installed on the device.

User Profile

Android now includes a personal profile that represents the device owner, as defined by the {@link android.provider.ContactsContract.Profile} table. Social apps that maintain a user identity can contribute to the user's profile data by creating a new {@link android.provider.ContactsContract.RawContacts} entry within the {@link android.provider.ContactsContract.Profile}. That is, raw contacts that represent the device user do not belong in the traditional raw contacts table defined by the {@link android.provider.ContactsContract.RawContacts} Uri; instead, you must add a profile raw contact in the table at {@link android.provider.ContactsContract.Profile#CONTENT_RAW_CONTACTS_URI}. Raw contacts in this table are then aggregated into the single user-visible profile labeled "Me".

Adding a new raw contact for the profile requires the {@link android.Manifest.permission#WRITE_PROFILE} permission. Likewise, in order to read from the profile table, you must request the {@link android.Manifest.permission#READ_PROFILE} permission. However, most apps should not need to read the user profile, even when contributing data to the profile. Reading the user profile is a sensitive permission and you should expect users to be skeptical of apps that request it.

Invite Intent

The {@link android.provider.ContactsContract.Intents#INVITE_CONTACT} intent action allows an app to invoke an action that indicates the user wants to add a contact to a social network. The app receiving the app uses it to invite the specified contact to that social network. Most apps will be on the receiving-end of this operation. For example, the built-in People app invokes the invite intent when the user selects "Add connection" for a specific social app that's listed in a person's contact details.

To make your app visible as in the "Add connection" list, your app must provide a sync adapter to sync contact information from your social network. You must then indicate to the system that your app responds to the {@link android.provider.ContactsContract.Intents#INVITE_CONTACT} intent by adding the {@code inviteContactActivity} attribute to your app’s sync configuration file, with a fully-qualified name of the activity that the system should start when sending the invite intent. The activity that starts can then retrieve the URI for the contact in question from the intent’s data and perform the necessary work to invite that contact to the network or add the person to the user’s connections.

See the Sample Sync Adapter app for an example (specifically, see the contacts.xml file).

Large photos

Android now supports high resolution photos for contacts. Now, when you push a photo into a contact record, the system processes it into both a 96x96 thumbnail (as it has previously) and a 256x256 "display photo" that's stored in a new file-based photo store (the exact dimensions that the system chooses may vary in the future). You can add a large photo to a contact by putting a large photo in the usual {@link android.provider.ContactsContract.CommonDataKinds.Photo#PHOTO} column of a data row, which the system will then process into the appropriate thumbnail and display photo records.

Contact Usage Feedback

The new {@link android.provider.ContactsContract.DataUsageFeedback} APIs allow you to help track how often the user uses particular methods of contacting people, such as how often the user uses each phone number or e-mail address. This information helps improve the ranking for each contact method associated with each person and provide better suggestions for contacting each person.

Calendar Provider

The new calendar APIs allow you to read, add, modify and delete calendars, events, attendees, reminders and alerts, which are stored in the Calendar Provider.

A variety of apps and widgets can use these APIs to read and modify calendar events. However, some of the most compelling use cases are sync adapters that synchronize the user's calendar from other calendar services with the Calendar Provider, in order to offer a unified location for all the user's events. Google Calendar events, for example, are synchronized with the Calendar Provider by the Google Calendar Sync Adapter, allowing these events to be viewed with Android's built-in Calendar app.

The data model for calendars and event-related information in the Calendar Provider is defined by {@link android.provider.CalendarContract}. All the user’s calendar data is stored in a number of tables defined by various subclasses of {@link android.provider.CalendarContract}:

To access a user’s calendar data with the Calendar Provider, your application must request the {@link android.Manifest.permission#READ_CALENDAR} permission (for read access) and {@link android.Manifest.permission#WRITE_CALENDAR} (for write access).

Event intent

If all you want to do is add an event to the user’s calendar, you can use an {@link android.content.Intent#ACTION_INSERT} intent with the data defined by {@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI} in order to start an activity in the Calendar app that creates new events. Using the intent does not require any permission and you can specify event details with the following extras:

Voicemail Provider

The new Voicemail Provider allows applications to add voicemails to the device, in order to present all the user's voicemails in a single visual presentation. For instance, it’s possible that a user has multiple voicemail sources, such as one from the phone’s service provider and others from VoIP or other alternative voice services. These apps can use the Voicemail Provider APIs to add their voicemails to the device. The built-in Phone application then presents all voicemails to the user in a unified presentation. Although the system’s Phone application is the only application that can read all the voicemails, each application that provides voicemails can read those that it has added to the system (but cannot read voicemails from other services).

Because the APIs currently do not allow third-party apps to read all the voicemails from the system, the only third-party apps that should use the voicemail APIs are those that have voicemail to deliver to the user.

The {@link android.provider.VoicemailContract} class defines the content provider for the Voicemail Provder. The subclasses {@link android.provider.VoicemailContract.Voicemails} and {@link android.provider.VoicemailContract.Status} provide tables in which apps can insert voicemail data for storage on the device. For an example of a voicemail provider app, see the Voicemail Provider Demo.

Multimedia

Android 4.0 adds several new APIs for applications that interact with media such as photos, videos, and music.

Media Effects

A new media effects framework allows you to apply a variety of visual effects to images and videos. For example, image effects allow you to easily fix red-eye, convert an image to grayscale, adjust brightness, adjust saturation, rotate an image, apply a fisheye effect, and much more. The system performs all effects processing on the GPU to obtain maximum performance.

For maximum performance, effects are applied directly to OpenGL textures, so your application must have a valid OpenGL context before it can use the effects APIs. The textures to which you apply effects may be from bitmaps, videos or even the camera. However, there are certain restrictions that textures must meet:

  1. They must be bound to a {@link android.opengl.GLES20#GL_TEXTURE_2D} texture image
  2. They must contain at least one mipmap level

An {@link android.media.effect.Effect} object defines a single media effect that you can apply to an image frame. The basic workflow to create an {@link android.media.effect.Effect} is:

  1. Call {@link android.media.effect.EffectContext#createWithCurrentGlContext EffectContext.createWithCurrentGlContext()} from your OpenGL ES 2.0 context.
  2. Use the returned {@link android.media.effect.EffectContext} to call {@link android.media.effect.EffectContext#getFactory EffectContext.getFactory()}, which returns an instance of {@link android.media.effect.EffectFactory}.
  3. Call {@link android.media.effect.EffectFactory#createEffect createEffect()}, passing it an effect name from @link android.media.effect.EffectFactory}, such as {@link android.media.effect.EffectFactory#EFFECT_FISHEYE} or {@link android.media.effect.EffectFactory#EFFECT_VIGNETTE}.

You can adjust an effect’s parameters by calling {@link android.media.effect.Effect#setParameter setParameter()} and passing a parameter name and parameter value. Each type of effect accepts different parameters, which are documented with the effect name. For example, {@link android.media.effect.EffectFactory#EFFECT_FISHEYE} has one parameter for the {@code scale} of the distortion.

To apply an effect on a texture, call {@link android.media.effect.Effect#apply apply()} on the {@link android.media.effect.Effect} and pass in the input texture, it’s width and height, and the output texture. The input texture must be bound to a {@link android.opengl.GLES20#GL_TEXTURE_2D} texture image (usually done by calling the {@link android.opengl.GLES20#glTexImage2D glTexImage2D()} function). You may provide multiple mipmap levels. If the output texture has not been bound to a texture image, it will be automatically bound by the effect as a {@link android.opengl.GLES20#GL_TEXTURE_2D} and with one mipmap level (0), which will have the same size as the input.

All effects listed in {@link android.media.effect.EffectFactory} are guaranteed to be supported. However, some additional effects available from external libraries are not supported by all devices, so you must first check if the desired effect from the external library is supported by calling {@link android.media.effect.EffectFactory#isEffectSupported isEffectSupported()}.

Remote control client

The new {@link android.media.RemoteControlClient} allows media players to enable playback controls from remote control clients such as the device lock screen. Media players can also expose information about the media currently playing for display on the remote control, such as track information and album art.

To enable remote control clients for your media player, instantiate a {@link android.media.RemoteControlClient} with its constructor, passing it a {@link android.app.PendingIntent} that broadcasts {@link android.content.Intent#ACTION_MEDIA_BUTTON}. The intent must also declare the explicit {@link android.content.BroadcastReceiver} component in your app that handles the {@link android.content.Intent#ACTION_MEDIA_BUTTON} event.

To declare which media control inputs your player can handle, you must call {@link android.media.RemoteControlClient#setTransportControlFlags setTransportControlFlags()} on your {@link android.media.RemoteControlClient}, passing a set of {@code FLAG_KEY_MEDIA_*} flags, such as {@link android.media.RemoteControlClient#FLAG_KEY_MEDIA_PREVIOUS} and {@link android.media.RemoteControlClient#FLAG_KEY_MEDIA_NEXT}.

You must then register your {@link android.media.RemoteControlClient} by passing it to {@link android.media.AudioManager#registerRemoteControlClient MediaManager.registerRemoteControlClient()}. Once registered, the broadcast receiver you declared when you instantiated the {@link android.media.RemoteControlClient} will receive {@link android.content.Intent#ACTION_MEDIA_BUTTON} events when a button is pressed from a remote control. The intent you receive includes the {@link android.view.KeyEvent} for the media key pressed, which you can retrieve from the intent with {@link android.content.Intent#getParcelableExtra getParcelableExtra(Intent.EXTRA_KEY_EVENT)}.

To display information on the remote control about the media playing, call {@link android.media.RemoteControlClient#editMetadata editMetaData()} and add metadata to the returned {@link android.media.RemoteControlClient.MetadataEditor}. You can supply a bitmap for media artwork, numerical information such as elapsed time, and text information such as the track title. For information on available keys see the {@code METADATA_KEY_*} flags in {@link android.media.MediaMetadataRetriever}.

For a sample implementation, see the Random Music Player, which provides compatibility logic such that it enables the remote control client on Android 4.0 devices while continuing to support devices back to Android 2.1.

Media player

Media types

Android 4.0 adds support for:

For more info, see Supported Media Formats.

Camera

The {@link android.hardware.Camera} class now includes APIs for detecting faces and controlling focus and metering areas.

Face detection

Camera apps can now enhance their abilities with Android’s face detection APIs, which not only detect the face of a subject, but also specific facial features, such as the eyes and mouth.

To detect faces in your camera application, you must register a {@link android.hardware.Camera.FaceDetectionListener} by calling {@link android.hardware.Camera#setFaceDetectionListener setFaceDetectionListener()}. You can then start your camera surface and start detecting faces by calling {@link android.hardware.Camera#startFaceDetection}.

When the system detects one or more faces in the camera scene, it calls the {@link android.hardware.Camera.FaceDetectionListener#onFaceDetection onFaceDetection()} callback in your implementation of {@link android.hardware.Camera.FaceDetectionListener}, including an array of {@link android.hardware.Camera.Face} objects.

An instance of the {@link android.hardware.Camera.Face} class provides various information about the face detected, including:

Note: Face detection may not be supported on some devices, so you should check by calling {@link android.hardware.Camera.Parameters#getMaxNumDetectedFaces()} and ensure the return value is greater than zero. Also, some devices may not support identification of eyes and mouth, in which case, those fields in the {@link android.hardware.Camera.Face} object will be null.

Focus and metering areas

Camera apps can now control the areas that the camera uses for focus and for metering white balance and auto-exposure. Both features use the new {@link android.hardware.Camera.Area} class to specify the region of the camera’s current view that should be focused or metered. An instance of the {@link android.hardware.Camera.Area} class defines the bounds of the area with a {@link android.graphics.Rect} and the area's weight—representing the level of importance of that area, relative to other areas in consideration—with an integer.

Before setting either a focus area or metering area, you should first call {@link android.hardware.Camera.Parameters#getMaxNumFocusAreas} or {@link android.hardware.Camera.Parameters#getMaxNumMeteringAreas}, respectively. If these return zero, then the device does not support the corresponding feature.

To specify the focus or metering areas to use, simply call {@link android.hardware.Camera.Parameters#setFocusAreas setFocusAreas()} or {@link android.hardware.Camera.Parameters#setMeteringAreas setMeteringAreas()}. Each take a {@link java.util.List} of {@link android.hardware.Camera.Area} objects that indicate the areas to consider for focus or metering. For example, you might implement a feature that allows the user to set the focus area by touching an area of the preview, which you then translate to an {@link android.hardware.Camera.Area} object and request that the camera focus on that area of the scene. The focus or exposure in that area will continually update as the scene in the area changes.

Continuous auto focus for photos

You can now enable continuous auto focusing (CAF) when taking photos. To enable CAF in your camera app, pass {@link android.hardware.Camera.Parameters#FOCUS_MODE_CONTINUOUS_PICTURE} to {@link android.hardware.Camera.Parameters#setFocusMode setFocusMode()}. When ready to capture a photo, call {@link android.hardware.Camera#autoFocus autoFocus()}. Your {@link android.hardware.Camera.AutoFocusCallback} immediately receives a callback to indicate whether focus was achieved. To resume CAF after receiving the callback, you must call {@link android.hardware.Camera#cancelAutoFocus()}.

Note: Continuous auto focus is also supported when capturing video, using {@link android.hardware.Camera.Parameters#FOCUS_MODE_CONTINUOUS_VIDEO}, which was added in API level 9.

Other camera features

Camera broadcast intents

Android Beam (NDEF Push with NFC)

Android Beam is a new NFC feature that allows you to send NDEF messages from one device to another (a process also known as “NDEF Push"). The data transfer is initiated when two Android-powered devices that support Android Beam are in close proximity (about 4 cm), usually with their backs touching. The data inside the NDEF message can contain any data that you wish to share between devices. For example, the People app shares contacts, YouTube shares videos, and Browser shares URLs using Android Beam.

To transmit data between devices using Android Beam, you need to create an {@link android.nfc.NdefMessage} that contains the information you want to share while your activity is in the foreground. You must then pass the {@link android.nfc.NdefMessage} to the system in one of two ways:

In case you want to run some specific code once the system has successfully delivered your NDEF message to the other device, you can implement {@link android.nfc.NfcAdapter.OnNdefPushCompleteCallback} and set it with {@link android.nfc.NfcAdapter#setOnNdefPushCompleteCallback setNdefPushCompleteCallback()}. The system will then call {@link android.nfc.NfcAdapter.OnNdefPushCompleteCallback#onNdefPushComplete onNdefPushComplete()} when the message is delivered.

On the receiving device, the system dispatches NDEF Push messages in a similar way to regular NFC tags. The system invokes an intent with the {@link android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} action to start an activity, with either a URL or a MIME type set according to the first {@link android.nfc.NdefRecord} in the {@link android.nfc.NdefMessage}. For the activity you want to respond, you can declare intent filters for the URLs or MIME types your app cares about. For more information about Tag Dispatch see the NFC developer guide.

If you want your {@link android.nfc.NdefMessage} to carry a URI, you can now use the convenience method {@link android.nfc.NdefRecord#createUri createUri} to construct a new {@link android.nfc.NdefRecord} based on either a string or a {@link android.net.Uri} object. If the URI is a special format that you want your application to also receive during an Android Beam event, you should create an intent filter for your activity using the same URI scheme in order to receive the incoming NDEF message.

You should also pass an “Android application record" with your {@link android.nfc.NdefMessage} in order to guarantee that your application handles the incoming NDEF message, even if other applications filter for the same intent action. You can create an Android application record by calling {@link android.nfc.NdefRecord#createApplicationRecord createApplicationRecord()}, passing it your application’s package name. When the other device receives the NDEF message with the application record and multiple applications contain activities that handle the specified intent, the system always delivers the message to the activity in your application (based on the matching application record). If the target device does not currently have your application installed, the system uses the Android application record to launch Google Play and take the user to the application in order to install it.

If your application doesn’t use NFC APIs to perform NDEF Push messaging, then Android provides a default behavior: When your application is in the foreground on one device and Android Beam is invoked with another Android-powered device, then the other device receives an NDEF message with an Android application record that identifies your application. If the receiving device has the application installed, the system launches it; if it’s not installed, Google Play opens and takes the user to your application in order to install it.

You can read more about Android Beam and other NFC features in the NFC Basics developer guide. For some example code using Android Beam, see the Android Beam Demo.

Wi-Fi Direct

Android now supports Wi-Fi Direct for peer-to-peer (P2P) connections between Android-powered devices and other device types without a hotspot or Internet connection. The Android framework provides a set of Wi-Fi P2P APIs that allow you to discover and connect to other devices when each device supports Wi-Fi Direct, then communicate over a speedy connection across distances much longer than a Bluetooth connection.

A new package, {@link android.net.wifi.p2p}, contains all the APIs for performing peer-to-peer connections with Wi-Fi. The primary class you need to work with is {@link android.net.wifi.p2p.WifiP2pManager}, which you can acquire by calling {@link android.app.Activity#getSystemService getSystemService(WIFI_P2P_SERVICE)}. The {@link android.net.wifi.p2p.WifiP2pManager} includes APIs that allow you to:

Several other interfaces and classes are necessary as well, such as:

In order to use the Wi-Fi P2P APIs, your app must request the following user permissions:

The Android system also broadcasts several different actions during certain Wi-Fi P2P events:

See the {@link android.net.wifi.p2p.WifiP2pManager} documentation for more information. Also look at the Wi-Fi Direct Demo sample application.

Bluetooth Health Devices

Android now supports Bluetooth Health Profile devices, so you can create applications that use Bluetooth to communicate with health devices that support Bluetooth, such as heart-rate monitors, blood meters, thermometers, and scales.

Similar to regular headset and A2DP profile devices, you must call {@link android.bluetooth.BluetoothAdapter#getProfileProxy getProfileProxy()} with a {@link android.bluetooth.BluetoothProfile.ServiceListener} and the {@link android.bluetooth.BluetoothProfile#HEALTH} profile type to establish a connection with the profile proxy object.

Once you’ve acquired the Health Profile proxy (the {@link android.bluetooth.BluetoothHealth} object), connecting to and communicating with paired health devices involves the following new Bluetooth classes:

For more information about using the Bluetooth Health Profile, see the documentation for {@link android.bluetooth.BluetoothHealth}.

Accessibility

Android 4.0 improves accessibility for sight-impaired users with new explore-by-touch mode and extended APIs that allow you to provide more information about view content or develop advanced accessibility services.

Explore-by-touch mode

Users with vision loss can now explore the screen by touching and dragging a finger across the screen to hear voice descriptions of the content. Because the explore-by-touch mode works like a virtual cursor, it allows screen readers to identify the descriptive text the same way that screen readers can when the user navigates with a d-pad or trackball—by reading information provided by {@link android.R.attr#contentDescription android:contentDescription} and {@link android.view.View#setContentDescription setContentDescription()} upon a simulated "hover" event. So, consider this is a reminder that you should provide descriptive text for the views in your application, especially for {@link android.widget.ImageButton}, {@link android.widget.EditText}, {@link android.widget.ImageView} and other widgets that might not naturally contain descriptive text.

Accessibility for views

To enhance the information available to accessibility services such as screen readers, you can implement new callback methods for accessibility events in your custom {@link android.view.View} components.

It's important to first note that the behavior of the {@link android.view.View#sendAccessibilityEvent sendAccessibilityEvent()} method has changed in Android 4.0. As with previous version of Android, when the user enables accessibility services on the device and an input event such as a click or hover occurs, the respective view is notified with a call to {@link android.view.View#sendAccessibilityEvent sendAccessibilityEvent()}. Previously, the implementation of {@link android.view.View#sendAccessibilityEvent sendAccessibilityEvent()} would initialize an {@link android.view.accessibility.AccessibilityEvent} and send it to {@link android.view.accessibility.AccessibilityManager}. The new behavior involves some additional callback methods that allow the view and its parents to add more contextual information to the event:

  1. When invoked, the {@link android.view.View#sendAccessibilityEvent sendAccessibilityEvent()} and {@link android.view.View#sendAccessibilityEventUnchecked sendAccessibilityEventUnchecked()} methods defer to {@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()}.

    Custom implementations of {@link android.view.View} might want to implement {@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()} to attach additional accessibility information to the {@link android.view.accessibility.AccessibilityEvent}, but should also call the super implementation to provide default information such as the standard content description, item index, and more. However, you should not add additional text content in this callback—that happens next.

  2. Once initialized, if the event is one of several types that should be populated with text information, the view then receives a call to {@link android.view.View#dispatchPopulateAccessibilityEvent dispatchPopulateAccessibilityEvent()}, which defers to the {@link android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} callback.

    Custom implementations of {@link android.view.View} should usually implement {@link android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} to add additional text content to the {@link android.view.accessibility.AccessibilityEvent} if the {@link android.R.attr#contentDescription android:contentDescription} text is missing or insufficient. To add more text description to the {@link android.view.accessibility.AccessibilityEvent}, call {@link android.view.accessibility.AccessibilityEvent#getText()}.{@link java.util.List#add add()}.

  3. At this point, the {@link android.view.View} passes the event up the view hierarchy by calling {@link android.view.ViewGroup#requestSendAccessibilityEvent requestSendAccessibilityEvent()} on the parent view. Each parent view then has the chance to augment the accessibility information by adding an {@link android.view.accessibility.AccessibilityRecord}, until it ultimately reaches the root view, which sends the event to the {@link android.view.accessibility.AccessibilityManager} with {@link android.view.accessibility.AccessibilityManager#sendAccessibilityEvent sendAccessibilityEvent()}.

In addition to the new methods above, which are useful when extending the {@link android.view.View} class, you can also intercept these event callbacks on any {@link android.view.View} by extending {@link android.view.View.AccessibilityDelegate AccessibilityDelegate} and setting it on the view with {@link android.view.View#setAccessibilityDelegate setAccessibilityDelegate()}. When you do, each accessibility method in the view defers the call to the corresponding method in the delegate. For example, when the view receives a call to {@link android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()}, it passes it to the same method in the {@link android.view.View.AccessibilityDelegate}. Any methods not handled by the delegate are given right back to the view for default behavior. This allows you to override only the methods necessary for any given view without extending the {@link android.view.View} class.

If you want to maintain compatibility with Android versions prior to 4.0, while also supporting the new the accessibility APIs, you can do so with the latest version of the v4 support library (in Compatibility Package, r4) using a set of utility classes that provide the new accessibility APIs in a backward-compatible design.

Accessibility services

If you're developing an accessibility service, the information about various accessibility events has been significantly expanded to enable more advanced accessibility feedback for users. In particular, events are generated based on view composition, providing better context information and allowing accessibility services to traverse view hierarchies to get additional view information and deal with special cases.

If you're developing an accessibility service (such as a screen reader), you can access additional content information and traverse view hierarchies with the following procedure:

  1. Upon receiving an {@link android.view.accessibility.AccessibilityEvent} from an application, call the {@link android.view.accessibility.AccessibilityEvent#getRecord(int) AccessibilityEvent.getRecord()} to retrieve a specific {@link android.view.accessibility.AccessibilityRecord} (there may be several records attached to the event).
  2. From either {@link android.view.accessibility.AccessibilityEvent} or an individual {@link android.view.accessibility.AccessibilityRecord}, you can call {@link android.view.accessibility.AccessibilityRecord#getSource() getSource()} to retrieve a {@link android.view.accessibility.AccessibilityNodeInfo} object.

    An {@link android.view.accessibility.AccessibilityNodeInfo} represents a single node of the window content in a format that allows you to query accessibility information about that node. The {@link android.view.accessibility.AccessibilityNodeInfo} object returned from {@link android.view.accessibility.AccessibilityEvent} describes the event source, whereas the source from an {@link android.view.accessibility.AccessibilityRecord} describes the predecessor of the event source.

  3. With the {@link android.view.accessibility.AccessibilityNodeInfo}, you can query information about it, call {@link android.view.accessibility.AccessibilityNodeInfo#getParent getParent()} or {@link android.view.accessibility.AccessibilityNodeInfo#getChild getChild()} to traverse the view hierarchy, and even add child views to the node.

In order for your application to publish itself to the system as an accessibility service, it must declare an XML configuration file that corresponds to {@link android.accessibilityservice.AccessibilityServiceInfo}. For more information about creating an accessibility service, see {@link android.accessibilityservice.AccessibilityService} and {@link android.accessibilityservice.AccessibilityService#SERVICE_META_DATA SERVICE_META_DATA} for information about the XML configuration.

Other accessibility APIs

If you're interested in the device's accessibility state, the {@link android.view.accessibility.AccessibilityManager} has some new APIs such as:

Spell Checker Services

A new spell checker framework allows apps to create spell checkers in a manner similar to the input method framework (for IMEs). To create a new spell checker, you must implement a service that extends {@link android.service.textservice.SpellCheckerService} and extend the {@link android.service.textservice.SpellCheckerService.Session} class to provide spelling suggestions based on text provided by the interface's callback methods. In the {@link android.service.textservice.SpellCheckerService.Session} callback methods, you must return the spelling suggestions as {@link android.view.textservice.SuggestionsInfo} objects.

Applications with a spell checker service must declare the {@link android.Manifest.permission#BIND_TEXT_SERVICE} permission as required by the service. The service must also declare an intent filter with {@code <action android:name="android.service.textservice.SpellCheckerService" />} as the intent’s action and should include a {@code <meta-data>} element that declares configuration information for the spell checker.

See the sample Spell Checker Service app and sample Spell Checker Client app for example code.

Text-to-speech Engines

Android’s text-to-speech (TTS) APIs have been significantly extended to allow applications to more easily implement custom TTS engines, while applications that want to use a TTS engine have a couple new APIs for selecting an engine.

Using text-to-speech engines

In previous versions of Android, you could use the {@link android.speech.tts.TextToSpeech} class to perform text-to-speech (TTS) operations using the TTS engine provided by the system or set a custom engine using {@link android.speech.tts.TextToSpeech#setEngineByPackageName setEngineByPackageName()}. In Android 4.0, the {@link android.speech.tts.TextToSpeech#setEngineByPackageName setEngineByPackageName()} method has been deprecated and you can now specify the engine to use with a new {@link android.speech.tts.TextToSpeech} constructor that accepts the package name of a TTS engine.

You can also query the available TTS engines with {@link android.speech.tts.TextToSpeech#getEngines()}. This method returns a list of {@link android.speech.tts.TextToSpeech.EngineInfo} objects, which include meta data such as the engine’s icon, label, and package name.

Building text-to-speech engines

Previously, custom engines required that the engine be built using an undocumented native header file. In Android 4.0, there is a complete set of framework APIs for building TTS engines.

The basic setup requires an implementation of {@link android.speech.tts.TextToSpeechService} that responds to the {@link android.speech.tts.TextToSpeech.Engine#INTENT_ACTION_TTS_SERVICE} intent. The primary work for a TTS engine happens during the {@link android.speech.tts.TextToSpeechService#onSynthesizeText onSynthesizeText()} callback in a service that extends {@link android.speech.tts.TextToSpeechService}. The system delivers this method two objects:

Now that the framework supports a true API for creating TTS engines, support for the native code implementation has been removed. Look for a blog post about a compatibility layer that you can use to convert your old TTS engines to the new framework.

For an example TTS engine using the new APIs, see the Text To Speech Engine sample app.

Network Usage

Android 4.0 gives users precise visibility of how much network data their applications are using. The Settings app provides controls that allow users to manage set limits for network data usage and even disable the use of background data for individual apps. In order to avoid users disabling your app’s access to data from the background, you should develop strategies to use the data connection efficiently and adjust your usage depending on the type of connection available.

If your application performs a lot of network transactions, you should provide user settings that allow users to control your app’s data habits, such as how often your app syncs data, whether to perform uploads/downloads only when on Wi-Fi, whether to use data while roaming, etc. With these controls available to them, users are much less likely to disable your app’s access to data when they approach their limits, because they can instead precisely control how much data your app uses. If you provide a preference activity with these settings, you should include in its manifest declaration an intent filter for the {@link android.content.Intent#ACTION_MANAGE_NETWORK_USAGE} action. For example:

<activity android:name="DataPreferences" android:label="@string/title_preferences">
    <intent-filter>
       <action android:name="android.intent.action.MANAGE_NETWORK_USAGE" />
       <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

This intent filter indicates to the system that this is the activity that controls your application’s data usage. Thus, when the user inspects how much data your app is using from the Settings app, a “View application settings" button is available that launches your preference activity so the user can refine how much data your app uses.

Also beware that {@link android.net.ConnectivityManager#getBackgroundDataSetting()} is now deprecated and always returns true—use {@link android.net.ConnectivityManager#getActiveNetworkInfo()} instead. Before you attempt any network transactions, you should always call {@link android.net.ConnectivityManager#getActiveNetworkInfo()} to get the {@link android.net.NetworkInfo} that represents the current network and query {@link android.net.NetworkInfo#isConnected()} to check whether the device has a connection. You can then check other connection properties, such as whether the device is roaming or connected to Wi-Fi.

RenderScript

Three major features have been added to RenderScript:

The {@link android.renderscript.Allocation} class now supports a {@link android.renderscript.Allocation#USAGE_GRAPHICS_RENDER_TARGET} memory space, which allows you to render things directly into the {@link android.renderscript.Allocation} and use it as a framebuffer object.

{@link android.renderscript.RSTextureView} provides a means to display RenderScript graphics inside of a {@link android.view.View}, unlike {@link android.renderscript.RSSurfaceView}, which creates a separate window. This key difference allows you to do things such as move, transform, or animate an {@link android.renderscript.RSTextureView} as well as draw RenderScript graphics inside a view that lies within an activity layout.

The {@link android.renderscript.Script#forEach Script.forEach()} method allows you to call RenderScript compute scripts from the VM level and have them automatically delegated to available cores on the device. You do not use this method directly, but any compute RenderScript that you write will have a {@link android.renderscript.Script#forEach forEach()} method that you can call in the reflected RenderScript class. You can call the reflected {@link android.renderscript.Script#forEach forEach()} method by passing in an input {@link android.renderscript.Allocation} to process, an output {@link android.renderscript.Allocation} to write the result to, and a {@link android.renderscript.FieldPacker} data structure in case the RenderScript needs more information. Only one of the {@link android.renderscript.Allocation}s is necessary and the data structure is optional.

Enterprise

Android 4.0 expands the capabilities for enterprise application with the following features.

VPN services

The new {@link android.net.VpnService} allows applications to build their own VPN (Virtual Private Network), running as a {@link android.app.Service}. A VPN service creates an interface for a virtual network with its own address and routing rules and performs all reading and writing with a file descriptor.

To create a VPN service, use {@link android.net.VpnService.Builder}, which allows you to specify the network address, DNS server, network route, and more. When complete, you can establish the interface by calling {@link android.net.VpnService.Builder#establish()}, which returns a {@link android.os.ParcelFileDescriptor}.

Because a VPN service can intercept packets, there are security implications. As such, if you implement {@link android.net.VpnService}, then your service must require the {@link android.Manifest.permission#BIND_VPN_SERVICE} to ensure that only the system can bind to it (only the system is granted this permission—apps cannot request it). To then use your VPN service, users must manually enable it in the system settings.

Device policies

Applications that manage the device restrictions can now disable the camera using {@link android.app.admin.DevicePolicyManager#setCameraDisabled setCameraDisabled()} and the {@link android.app.admin.DeviceAdminInfo#USES_POLICY_DISABLE_CAMERA} property (applied with a {@code <disable-camera />} element in the policy configuration file).

Certificate management

The new {@link android.security.KeyChain} class provides APIs that allow you to import and access certificates in the system key store. Certificates streamline the installation of both client certificates (to validate the identity of the user) and certificate authority certificates (to verify server identity). Applications such as web browsers or email clients can access the installed certificates to authenticate users to servers. See the {@link android.security.KeyChain} documentation for more information.

Device Sensors

Two new sensor types have been added in Android 4.0:

If a device has both {@link android.hardware.Sensor#TYPE_AMBIENT_TEMPERATURE} and {@link android.hardware.Sensor#TYPE_RELATIVE_HUMIDITY} sensors, you can use them to calculate the dew point and the absolute humidity.

The previous temperature sensor, {@link android.hardware.Sensor#TYPE_TEMPERATURE}, has been deprecated. You should use the {@link android.hardware.Sensor#TYPE_AMBIENT_TEMPERATURE} sensor instead.

Additionally, Android’s three synthetic sensors have been greatly improved so they now have lower latency and smoother output. These sensors include the gravity sensor ({@link android.hardware.Sensor#TYPE_GRAVITY}), rotation vector sensor ({@link android.hardware.Sensor#TYPE_ROTATION_VECTOR}), and linear acceleration sensor ({@link android.hardware.Sensor#TYPE_LINEAR_ACCELERATION}). The improved sensors rely on the gyroscope sensor to improve their output, so the sensors appear only on devices that have a gyroscope.

Action Bar

The {@link android.app.ActionBar} has been updated to support several new behaviors. Most importantly, the system gracefully manages the action bar’s size and configuration when running on smaller screens in order to provide an optimal user experience on all screen sizes. For example, when the screen is narrow (such as when a handset is in portrait orientation), the action bar’s navigation tabs appear in a “stacked bar," which appears directly below the main action bar. You can also opt-in to a “split action bar," which places all action items in a separate bar at the bottom of the screen when the screen is narrow.

Split action bar

If your action bar includes several action items, not all of them will fit into the action bar on a narrow screen, so the system will place more of them into the overflow menu. However, Android 4.0 allows you to enable “split action bar" so that more action items can appear on the screen in a separate bar at the bottom of the screen. To enable split action bar, add {@link android.R.attr#uiOptions android:uiOptions} with {@code "splitActionBarWhenNarrow"} to either your {@code <application>} tag or individual {@code <activity>} tags in your manifest file. When enabled, the system will add an additional bar at the bottom of the screen for all action items when the screen is narrow (no action items will appear in the primary action bar).

If you want to use the navigation tabs provided by the {@link android.app.ActionBar.Tab} APIs, but don’t need the main action bar on top (you want only the tabs to appear at the top), then enable the split action bar as described above and also call {@link android.app.ActionBar#setDisplayShowHomeEnabled setDisplayShowHomeEnabled(false)} to disable the application icon in the action bar. With nothing left in the main action bar, it disappears—all that’s left are the navigation tabs at the top and the action items at the bottom of the screen.

Action bar styles

If you want to apply custom styling to the action bar, you can use new style properties {@link android.R.attr#backgroundStacked} and {@link android.R.attr#backgroundSplit} to apply a background drawable or color to the stacked bar and split bar, respectively. You can also set these styles at runtime with {@link android.app.ActionBar#setStackedBackgroundDrawable setStackedBackgroundDrawable()} and {@link android.app.ActionBar#setSplitBackgroundDrawable setSplitBackgroundDrawable()}.

Action provider

The new {@link android.view.ActionProvider} class allows you to create a specialized handler for action items. An action provider can define an action view, a default action behavior, and a submenu for each action item to which it is associated. When you want to create an action item that has dynamic behaviors (such as a variable action view, default action, or submenu), extending {@link android.view.ActionProvider} is a good solution in order to create a reusable component, rather than handling the various action item transformations in your fragment or activity.

For example, the {@link android.widget.ShareActionProvider} is an extension of {@link android.view.ActionProvider} that facilitates a “share" action from the action bar. Instead of using traditional action item that invokes the {@link android.content.Intent#ACTION_SEND} intent, you can use this action provider to present an action view with a drop-down list of applications that handle the {@link android.content.Intent#ACTION_SEND} intent. When the user selects an application to use for the action, {@link android.widget.ShareActionProvider} remembers that selection and provides it in the action view for faster access to sharing with that app.

To declare an action provider for an action item, include the {@code android:actionProviderClass} attribute in the {@code <item>} element for your activity’s options menu, with the class name of the action provider as the value. For example:

<item android:id="@+id/menu_share"
      android:title="Share"
      android:showAsAction="ifRoom"
      android:actionProviderClass="android.widget.ShareActionProvider" />

In your activity’s {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} callback method, retrieve an instance of the action provider from the menu item and set the intent:

public boolean onCreateOptionsMenu(Menu menu) {
    getMenuInflater().inflate(R.menu.options, menu);
    ShareActionProvider shareActionProvider =
          (ShareActionProvider) menu.findItem(R.id.menu_share).getActionProvider();
    // Set the share intent of the share action provider.
    shareActionProvider.setShareIntent(createShareIntent());
    ...
    return super.onCreateOptionsMenu(menu);
}

For an example using the {@link android.widget.ShareActionProvider}, see ActionBarShareActionProviderActivity in ApiDemos.

Collapsible action views

Action items that provide an action view can now toggle between their action view state and traditional action item state. Previously only the {@link android.widget.SearchView} supported collapsing when used as an action view, but now you can add an action view for any action item and switch between the expanded state (action view is visible) and collapsed state (action item is visible).

To declare that an action item that contains an action view be collapsible, include the {@code “collapseActionView"} flag in the {@code android:showAsAction} attribute for the {@code <item>} element in the menu’s XML file.

To receive callbacks when an action view switches between expanded and collapsed, register an instance of {@link android.view.MenuItem.OnActionExpandListener} with the respective {@link android.view.MenuItem} by calling {@link android.view.MenuItem#setOnActionExpandListener setOnActionExpandListener()}. Typically, you should do so during the {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} callback.

To control a collapsible action view, you can call {@link android.view.MenuItem#collapseActionView()} and {@link android.view.MenuItem#expandActionView()} on the respective {@link android.view.MenuItem}.

When creating a custom action view, you can also implement the new {@link android.view.CollapsibleActionView} interface to receive callbacks when the view is expanded and collapsed.

Other APIs for action bar

User Interface and Views

Android 4.0 introduces a variety of new views and other UI components.

GridLayout

{@link android.widget.GridLayout} is a new view group that places child views in a rectangular grid. Unlike {@link android.widget.TableLayout}, {@link android.widget.GridLayout} relies on a flat hierarchy and does not make use of intermediate views such as table rows for providing structure. Instead, children specify which row(s) and column(s) they should occupy (cells can span multiple rows and/or columns), and by default are laid out sequentially across the grid’s rows and columns. The {@link android.widget.GridLayout} orientation determines whether sequential children are by default laid out horizontally or vertically. Space between children may be specified either by using instances of the new {@link android.widget.Space} view or by setting the relevant margin parameters on children.

See ApiDemos for samples using {@link android.widget.GridLayout}.

TextureView

{@link android.view.TextureView} is a new view that allows you to display a content stream, such as a video or an OpenGL scene. Although similar to {@link android.view.SurfaceView}, {@link android.view.TextureView} is unique in that it behaves like a regular view, rather than creating a separate window, so you can treat it like any other {@link android.view.View} object. For example, you can apply transforms, animate it using {@link android.view.ViewPropertyAnimator}, or adjust its opacity with {@link android.view.View#setAlpha setAlpha()}.

Beware that {@link android.view.TextureView} works only within a hardware accelerated window.

For more information, see the {@link android.view.TextureView} documentation.

Switch widget

The new {@link android.widget.Switch} widget is a two-state toggle that users can drag to one side or the other (or simply tap) to toggle an option between two states.

You can use the {@code android:textOn} and {@code android:textOff} attributes to specify the text to appear on the switch when in the on and off setting. The {@code android:text} attribute also allows you to place a label alongside the switch.

For a sample using switches, see the switches.xml layout file and respective Switches activity.

Popup menus

Android 3.0 introduced {@link android.widget.PopupMenu} to create short contextual menus that pop up at an anchor point you specify (usually at the point of the item selected). Android 4.0 extends the {@link android.widget.PopupMenu} with a couple useful features:

Preferences

A new {@link android.preference.TwoStatePreference} abstract class serves as the basis for preferences that provide a two-state selection option. The new {@link android.preference.SwitchPreference} is an extension of {@link android.preference.TwoStatePreference} that provides a {@link android.widget.Switch} widget in the preference view to allow users to toggle a setting on or off without the need to open an additional preference screen or dialog. For example, the Settings application uses a {@link android.preference.SwitchPreference} for the Wi-Fi and Bluetooth settings.

System themes

The default theme for all applications that target Android 4.0 (by setting either {@code targetSdkVersion} or {@code minSdkVersion} to {@code “14"} or higher) is now the "device default" theme: {@link android.R.style#Theme_DeviceDefault Theme.DeviceDefault}. This may be the dark Holo theme or a different dark theme defined by the specific device.

The {@link android.R.style#Theme_Holo Theme.Holo} family of themes are guaranteed to not change from one device to another when running the same version of Android. If you explicitly apply any of the {@link android.R.style#Theme_Holo Theme.Holo} themes to your activities, you can rest assured that these themes will not change character on different devices within the same platform version.

If you wish for your app to blend in with the overall device theme (such as when different OEMs provide different default themes for the system), you should explicitly apply themes from the {@link android.R.style#Theme_DeviceDefault Theme.DeviceDefault} family.

Options menu button

Beginning with Android 4.0, you'll notice that handsets no longer require a Menu hardware button. However, there's no need for you to worry about this if your existing application provides an options menu and expects there to be a Menu button. To ensure that existing apps continue to work as they expect, the system provides an on-screen Menu button for apps that were designed for older versions of Android.

For the best user experience, new and updated apps should instead use the {@link android.app.ActionBar} to provide access to menu items and set {@code targetSdkVersion} to {@code "14"} to take advantage of the latest framework default behaviors.

Controls for system UI visibility

Since the early days of Android, the system has managed a UI component known as the status bar, which resides at the top of handset devices to deliver information such as the carrier signal, time, notifications, and so on. Android 3.0 added the system bar for tablet devices, which resides at the bottom of the screen to provide system navigation controls (Home, Back, and so forth) and also an interface for elements traditionally provided by the status bar. In Android 4.0, the system provides a new type of system UI called the navigation bar. You might consider the navigation bar a re-tuned version of the system bar designed for handsets—it provides navigation controls for devices that don’t have hardware counterparts for navigating the system, but it leaves out the system bar's notification UI and setting controls. As such, a device that provides the navigation bar also has the status bar at the top.

To this day, you can hide the status bar on handsets using the {@link android.view.WindowManager.LayoutParams#FLAG_FULLSCREEN} flag. In Android 4.0, the APIs that control the system bar’s visibility have been updated to better reflect the behavior of both the system bar and navigation bar:

You can set each of these flags for the system bar and navigation bar by calling {@link android.view.View#setSystemUiVisibility setSystemUiVisibility()} on any view in your activity. The window manager combines (OR-together) all flags from all views in your window and apply them to the system UI as long as your window has input focus. When your window loses input focus (the user navigates away from your app, or a dialog appears), your flags cease to have effect. Similarly, if you remove those views from the view hierarchy their flags no longer apply.

To synchronize other events in your activity with visibility changes to the system UI (for example, hide the action bar or other UI controls when the system UI hides), you should register a {@link android.view.View.OnSystemUiVisibilityChangeListener} to be notified when the visibility of the system bar or navigation bar changes.

See the OverscanActivity class for a demonstration of different system UI options.

Input Framework

Android 4.0 adds support for cursor hover events and new stylus and mouse button events.

Hover events

The {@link android.view.View} class now supports “hover" events to enable richer interactions through the use of pointer devices (such as a mouse or other devices that drive an on-screen cursor).

To receive hover events on a view, implement the {@link android.view.View.OnHoverListener} and register it with {@link android.view.View#setOnHoverListener setOnHoverListener()}. When a hover event occurs on the view, your listener receives a call to {@link android.view.View.OnHoverListener#onHover onHover()}, providing the {@link android.view.View} that received the event and a {@link android.view.MotionEvent} that describes the type of hover event that occurred. The hover event can be one of the following:

Your {@link android.view.View.OnHoverListener} should return true from {@link android.view.View.OnHoverListener#onHover onHover()} if it handles the hover event. If your listener returns false, then the hover event will be dispatched to the parent view as usual.

If your application uses buttons or other widgets that change their appearance based on the current state, you can now use the {@code android:state_hovered} attribute in a state list drawable to provide a different background drawable when a cursor hovers over the view.

For a demonstration of the new hover events, see the Hover class in ApiDemos.

Stylus and mouse button events

Android now provides APIs for receiving input from a stylus input device such as a digitizer tablet peripheral or a stylus-enabled touch screen.

Stylus input operates in a similar manner to touch or mouse input. When the stylus is in contact with the digitizer, applications receive touch events just like they would when a finger is used to touch the display. When the stylus is hovering above the digitizer, applications receive hover events just like they would when a mouse pointer was being moved across the display when no buttons are pressed.

Your application can distinguish between finger, mouse, stylus and eraser input by querying the “tool type" associated with each pointer in a {@link android.view.MotionEvent} using {@link android.view.MotionEvent#getToolType getToolType()}. The currently defined tool types are: {@link android.view.MotionEvent#TOOL_TYPE_UNKNOWN}, {@link android.view.MotionEvent#TOOL_TYPE_FINGER}, {@link android.view.MotionEvent#TOOL_TYPE_MOUSE}, {@link android.view.MotionEvent#TOOL_TYPE_STYLUS}, and {@link android.view.MotionEvent#TOOL_TYPE_ERASER}. By querying the tool type, your application can choose to handle stylus input in different ways from finger or mouse input.

Your application can also query which mouse or stylus buttons are pressed by querying the “button state" of a {@link android.view.MotionEvent} using {@link android.view.MotionEvent#getButtonState getButtonState()}. The currently defined button states are: {@link android.view.MotionEvent#BUTTON_PRIMARY}, {@link android.view.MotionEvent#BUTTON_SECONDARY}, {@link android.view.MotionEvent#BUTTON_TERTIARY}, {@link android.view.MotionEvent#BUTTON_BACK}, and {@link android.view.MotionEvent#BUTTON_FORWARD}. For convenience, the back and forward mouse buttons are automatically mapped to the {@link android.view.KeyEvent#KEYCODE_BACK} and {@link android.view.KeyEvent#KEYCODE_FORWARD} keys. Your application can handle these keys to support mouse button based back and forward navigation.

In addition to precisely measuring the position and pressure of a contact, some stylus input devices also report the distance between the stylus tip and the digitizer, the stylus tilt angle, and the stylus orientation angle. Your application can query this information using {@link android.view.MotionEvent#getAxisValue getAxisValue()} with the axis codes {@link android.view.MotionEvent#AXIS_DISTANCE}, {@link android.view.MotionEvent#AXIS_TILT}, and {@link android.view.MotionEvent#AXIS_ORIENTATION}.

For a demonstration of tool types, button states and the new axis codes, see the TouchPaint class in ApiDemos.

Properties

The new {@link android.util.Property} class provides a fast, efficient, and easy way to specify a property on any object that allows callers to generically set/get values on target objects. It also allows the functionality of passing around field/method references and allows code to set/get values of the property without knowing the details of what the fields/methods are.

For example, if you want to set the value of field {@code bar} on object {@code foo}, you would previously do this:

foo.bar = value;

If you want to call the setter for an underlying private field {@code bar}, you would previously do this:

foo.setBar(value);

However, if you want to pass around the {@code foo} instance and have some other code set the {@code bar} value, there is really no way to do it prior to Android 4.0.

Using the {@link android.util.Property} class, you can declare a {@link android.util.Property} object {@code BAR} on class {@code Foo} so that you can set the field on instance {@code foo} of class {@code Foo} like this:

BAR.set(foo, value);

The {@link android.view.View} class now leverages the {@link android.util.Property} class to allow you to set various fields, such as transform properties that were added in Android 3.0 ({@link android.view.View#ROTATION}, {@link android.view.View#ROTATION_X}, {@link android.view.View#TRANSLATION_X}, etc.).

The {@link android.animation.ObjectAnimator} class also uses the {@link android.util.Property} class, so you can create an {@link android.animation.ObjectAnimator} with a {@link android.util.Property}, which is faster, more efficient, and more type-safe than the string-based approach.

Hardware Acceleration

Beginning with Android 4.0, hardware acceleration for all windows is enabled by default if your application has set either {@code targetSdkVersion} or {@code minSdkVersion} to {@code “14"} or higher. Hardware acceleration generally results in smoother animations, smoother scrolling, and overall better performance and response to user interaction.

If necessary, you can manually disable hardware acceleration with the {@code hardwareAccelerated} attribute for individual {@code <activity>} elements or the {@code <application>} element. You can alternatively disable hardware acceleration for individual views by calling {@link android.view.View#setLayerType setLayerType(LAYER_TYPE_SOFTWARE)}.

For more information about hardware acceleration, including a list of unsupported drawing operations, see the Hardware Acceleration document.

JNI Changes

In previous versions of Android, JNI local references weren’t indirect handles; Android used direct pointers. This wasn't a problem as long as the garbage collector didn't move objects, but it seemed to work because it made it possible to write buggy code. In Android 4.0, the system now uses indirect references in order to detect these bugs.

The ins and outs of JNI local references are described in “Local and Global References" in JNI Tips. In Android 4.0, CheckJNI has been enhanced to detect these errors. Watch the Android Developers Blog for an upcoming post about common errors with JNI references and how you can fix them.

This change in the JNI implementation only affects apps that target Android 4.0 by setting either the {@code targetSdkVersion} or {@code minSdkVersion} to {@code “14"} or higher. If you’ve set these attributes to any lower value, then JNI local references behave the same as in previous versions.

WebKit

Android Browser

The Browser application adds the following features to support web applications:

Permissions

The following are new permissions:

Device Features

The following are new device features:

For a detailed view of all API changes in Android {@sdkPlatformVersion} (API Level {@sdkPlatformApiLevel}), see the API Differences Report.

Previous APIs

In addition to everything above, Android 4.0 naturally supports all APIs from previous releases. Because the Android 3.x platform is available only for large-screen devices, if you've been developing primarily for handsets, then you might not be aware of all the APIs added to Android in these recent releases.

Here's a look at some of the most notable APIs you might have missed that are now available on handsets as well:

Android 3.0
Android 3.1
Android 3.2

API Level

The Android {@sdkPlatformVersion} API is assigned an integer identifier—{@sdkPlatformApiLevel}—that is stored in the system itself. This identifier, called the "API level", allows the system to correctly determine whether an application is compatible with the system, prior to installing the application.

To use APIs introduced in Android {@sdkPlatformVersion} in your application, you need compile the application against an Android platform that supports API level {@sdkPlatformApiLevel} or higher. Depending on your needs, you might also need to add an android:minSdkVersion="{@sdkPlatformApiLevel}" attribute to the {@code <uses-sdk>} element.

For more information, read What is API Level?