From b57769a738332d62384fa060b257893eedfb01e1 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Mon, 17 Oct 2011 11:20:49 -0700 Subject: docs: revisions to api overview Change-Id: If23f1119290d93494a6bec7021ecdc7e354b0504 --- docs/html/sdk/android-4.0.jd | 126 ++++++++++++++++++++++++++----------------- 1 file changed, 76 insertions(+), 50 deletions(-) diff --git a/docs/html/sdk/android-4.0.jd b/docs/html/sdk/android-4.0.jd index b8cd947755f4..9a9f02a37cfd 100644 --- a/docs/html/sdk/android-4.0.jd +++ b/docs/html/sdk/android-4.0.jd @@ -200,15 +200,14 @@ method associated with each person and provide better suggestions for contacting

Calendar Provider

-

The new calendar APIs allow you to access and modify the user’s calendars and events using the -Calendar Provider. You can read, add, modify and delete calendars, events, attendees, reminders and -alerts.

+

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, for example, uses a sync adapter to synchronize Google -Calendar events with the Calendar Provider, which can then be viewed with Android's built-in +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 @@ -303,7 +302,7 @@ read voicemails from other services).

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

@@ -337,13 +336,19 @@ 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

@@ -370,18 +375,37 @@ android.hardware.Camera.Area} object and request that the camera focus on that a 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 acheived. 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

- -

For more info, see Supported Media +

For more info, see Supported Media Formats.

@@ -477,7 +501,7 @@ 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 +href="{@docRoot}resources/samples/RandomMusicPlayer/index.html">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.

@@ -485,9 +509,9 @@ devices while continuing to support devices back to Android 2.1.

Media Effects

A new media effects framework allows you to apply a variety of visual effects to images and -videos. The system performs all effects processing on the GPU to obtain maximum performance. -New applications for Android 4.0 such as Google Talk and the Gallery editor make use of the -effects API to apply real-time effects to video and photos.

+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 @@ -572,7 +596,7 @@ android.bluetooth.BluetoothHealth}.

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 +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 @@ -619,7 +643,7 @@ action to start an activity, with either a URL or a MIME type set according to t 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.

+href="{@docRoot}guide/topics/nfc/index.html#dispatch">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 @@ -628,7 +652,7 @@ a special format that you want your application to also receive during an Androi 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 +

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 @@ -705,8 +729,8 @@ formed and who is the group owner.

  • {@link android.Manifest.permission#ACCESS_WIFI_STATE}
  • {@link android.Manifest.permission#CHANGE_WIFI_STATE}
  • {@link android.Manifest.permission#INTERNET} (although your app doesn’t technically connect -to the Internet, the WiFi Direct implementation uses sockets that do require Internet -permission to work).
    • +to the Internet, communicating to Wi-Fi Direct peers with standard java sockets requires Internet +permission).

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

    @@ -732,7 +756,7 @@ this device have changed.

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

    @@ -767,7 +791,7 @@ action. For example:

    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 +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 @@ -1102,7 +1126,7 @@ implementation has been removed. Look for a blog post about a compatibility laye 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.

    +href="{@docRoot}resources/samples/TtsEngine/index.html">Text To Speech Engine sample app.

    @@ -1141,8 +1165,8 @@ checker.

    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 +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.

    @@ -1150,9 +1174,9 @@ of the screen when the screen is narrow.

    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 +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 +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 @@ -1188,7 +1212,7 @@ android.view.ActionProvider} is a good solution in order to create a reusable co 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 +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 @@ -1224,7 +1248,8 @@ public boolean onCreateOptionsMenu(Menu menu) {

    For an example using the {@link android.widget.ShareActionProvider}, see the ActionBarActionProviderActivity +href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ +ActionBarActionProviderActivity.html">ActionBarActionProviderActivity class in ApiDemos.

    @@ -1237,7 +1262,7 @@ switch between the expanded state (action view is visible) and collapsed state ( 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.

    @@ -1259,7 +1284,7 @@ collapsed.

    Other APIs for action bar