docs: revisions to api overview
Change-Id: If23f1119290d93494a6bec7021ecdc7e354b0504
diff --git a/docs/html/sdk/android-4.0.jd b/docs/html/sdk/android-4.0.jd
index b8cd947..9a9f02a 100644
--- a/docs/html/sdk/android-4.0.jd
+++ b/docs/html/sdk/android-4.0.jd
@@ -200,15 +200,14 @@
<h3 id="Calendar">Calendar Provider</h3>
-<p>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.</p>
+<p>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.</p>
<p>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.</p>
<p>The data model for calendars and event-related information in the Calendar Provider is
@@ -303,7 +302,7 @@
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
-<a href=”{@docRoot}resources/samples/VoicemailProviderDemo/index.html”>Voicemail Provider
+<a href="{@docRoot}resources/samples/VoicemailProviderDemo/index.html">Voicemail Provider
Demo</a>.</p>
@@ -337,13 +336,19 @@
<ul>
<li>A {@link android.graphics.Rect} that specifies the bounds of the face, relative to the camera's
current field of view</li>
-<li>An integer betwen 0 and 100 that indicates how confident the system is that the object is a
+<li>An integer betwen 1 and 100 that indicates how confident the system is that the object is a
human face</li>
<li>A unique ID so you can track multiple faces</li>
<li>Several {@link android.graphics.Point} objects that indicate where the eyes and mouth are
located</li>
</ul>
+<p class="note"><strong>Note:</strong> 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.</p>
+
<h4>Focus and metering areas</h4>
@@ -370,18 +375,37 @@
The focus or exposure in that area will continually update as the scene in the area changes.</p>
+<h4>Continuous auto focus for photos</h4>
+
+<p>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()}.</p>
+
+<p class="note"><strong>Note:</strong> 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.</p>
+
+
<h4>Other camera features</h4>
-<ul>
+<ul>
<li>While recording video, you can now call {@link android.hardware.Camera#takePicture
takePicture()} to save a photo without interrupting the video session. Before doing so, you should
call {@link android.hardware.Camera.Parameters#isVideoSnapshotSupported} to be sure the hardware
supports it.</li>
-<li>Lock auto exposure and white balance with {@link
+<li>You can now lock auto exposure and white balance with {@link
android.hardware.Camera.Parameters#setAutoExposureLock setAutoExposureLock()} and {@link
-android.hardware.Camera.Parameters#setAutoWhiteBalanceLock setAutoWhiteBalanceLock()}, to prevent
+android.hardware.Camera.Parameters#setAutoWhiteBalanceLock setAutoWhiteBalanceLock()} to prevent
these properties from changing.</li>
+
+<li>You can now call {@link android.hardware.Camera#setDisplayOrientation
+setDisplayOrientation()} while the camera preview is running. Previously, you could call this
+only before beginning the preview, but you can now change the orientation at any time.</li>
</ul>
@@ -436,7 +460,7 @@
<li>WEBP images</li>
<li>Matroska video</li>
</ul>
-<p>For more info, see <a href=”{@docRoot}guide/appendix/media-formats.html”>Supported Media
+<p>For more info, see <a href="{@docRoot}guide/appendix/media-formats.html">Supported Media
Formats</a>.</p>
@@ -477,7 +501,7 @@
android.media.MediaMetadataRetriever}.</p>
<p>For a sample implementation, see the <a
-href=”{@docRoot}resources/samples/RandomMusicPlayer/index.html”>Random Music Player</a>, which
+href="{@docRoot}resources/samples/RandomMusicPlayer/index.html">Random Music Player</a>, 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.</p>
@@ -485,9 +509,9 @@
<h4>Media Effects</h4>
<p>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.</p>
+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.</p>
<p>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 @@
<h3 id="AndroidBeam">Android Beam (NDEF Push with NFC)</h3>
<p>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 @@
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 <a
-href=”{@docRoot}guide/topics/nfc/index.html#dispatch”>NFC</a> developer guide.</p>
+href="{@docRoot}guide/topics/nfc/index.html#dispatch">NFC</a> developer guide.</p>
<p>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 @@
should create an intent filter for your activity using the same URI scheme in order to receive the
incoming NDEF message.</p>
-<p>You should also pass an “Android application record” with your {@link android.nfc.NdefMessage} in
+<p>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 @@
<li>{@link android.Manifest.permission#ACCESS_WIFI_STATE}</li>
<li>{@link android.Manifest.permission#CHANGE_WIFI_STATE}</li>
<li>{@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).</li>
+to the Internet, communicating to Wi-Fi Direct peers with standard java sockets requires Internet
+permission).</li>
</ul>
<p>The Android system also broadcasts several different actions during certain Wi-Fi P2P events:</p>
@@ -732,7 +756,7 @@
</ul>
<p>See the {@link android.net.wifi.p2p.WifiP2pManager} documentation for more information. Also
-look at the <a href=”{@docRoot}resources/samples/WiFiDirectDemo/index.html”>Wi-Fi Direct Demo</a>
+look at the <a href="{@docRoot}resources/samples/WiFiDirectDemo/index.html">Wi-Fi Direct Demo</a>
sample application.</p>
@@ -767,7 +791,7 @@
<p>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.</p>
<p>Also beware that {@link android.net.ConnectivityManager#getBackgroundDataSetting()} is now
@@ -1102,7 +1126,7 @@
that you can use to convert your old TTS engines to the new framework.</p>
<p>For an example TTS engine using the new APIs, see the <a
-href=”{@docRoot}resources/samples/TtsEngine/index.html”>Text To Speech Engine</a> sample app.</p>
+href="{@docRoot}resources/samples/TtsEngine/index.html">Text To Speech Engine</a> sample app.</p>
@@ -1141,8 +1165,8 @@
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.</p>
@@ -1150,9 +1174,9 @@
<p>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
<a href="guide/topics/manifest/application-element.html">{@code <application>}</a> tag or
individual <a href="guide/topics/manifest/activity-element.html">{@code <activity>}</a> tags
in your manifest file. When enabled, the system will add an additional bar at the bottom of the
@@ -1188,7 +1212,7 @@
handling the various action item transformations in your fragment or activity.</p>
<p>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 @@
</pre>
<p>For an example using the {@link android.widget.ShareActionProvider}, see the <a
-href=”{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ActionBarActionProviderActivity.html”>ActionBarActionProviderActivity</a>
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/
+ActionBarActionProviderActivity.html">ActionBarActionProviderActivity</a>
class in ApiDemos.</p>
@@ -1237,7 +1262,7 @@
visible).</p>
<p>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 <a
+“collapseActionView"} flag in the {@code android:showAsAction} attribute for the <a
href="{@docRoot}guide/topics/resources/menu-resource.html#item-element">{@code
<item>}</a> element in the menu’s XML file.</p>
@@ -1259,7 +1284,7 @@
<h4>Other APIs for action bar</h4>
<ul>
<li>{@link android.app.ActionBar#setHomeButtonEnabled setHomeButtonEnabled()} allows you to specify
-whether the icon/logo behaves as a button to navigate home or “up” (pass “true” to make it behave as
+whether the icon/logo behaves as a button to navigate home or “up" (pass “true" to make it behave as
a button).</li>
<li>{@link android.app.ActionBar#setIcon setIcon()} and {@link android.app.ActionBar#setLogo
@@ -1307,7 +1332,7 @@
and navigation bar:</p>
<ul>
<li>The {@link android.view.View#SYSTEM_UI_FLAG_LOW_PROFILE} flag replaces View.STATUS_BAR_HIDDEN
-flag. When set, this flag enables “low profile” mode for the system bar or
+flag. When set, this flag enables “low profile" mode for the system bar or
navigation bar. Navigation buttons dim and other elements in the system bar also hide.</li>
<li>The {@link android.view.View#SYSTEM_UI_FLAG_VISIBLE} flag replaces the {@code
@@ -1334,7 +1359,7 @@
of the system bar or navigation bar changes.</p>
<p>See the <a
-href=”{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/OverscanActivity.html”>
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/OverscanActivity.html">
OverscanActivity</a> class for a demonstration of different system UI options.</p>
@@ -1351,7 +1376,8 @@
on children.</p>
<p>See <a
-href=”{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/index.html”>ApiDemos</a>
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/index.html">ApiDemos</a
+>
for samples using {@link android.widget.GridLayout}.</p>
@@ -1380,9 +1406,9 @@
allows you to place a label alongside the switch.</p>
<p>For a sample using switches, see the <a
-href=”{@docRoot}resources/samples/ApiDemos/res/layout/switches.html”>switches.xml</a> layout file
+href="{@docRoot}resources/samples/ApiDemos/res/layout/switches.html">switches.xml</a> layout file
and respective <a
-href=”{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/Switches.html”>Switches
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/Switches.html">Switches
</a> activity.</p>
@@ -1393,7 +1419,7 @@
the {@link android.widget.PopupMenu} with a couple useful features:</p>
<ul>
<li>You can now easily inflate the contents of a popup menu from an XML <a
-href=”{@docRoot}guide/topics/resources/menu-resource.html”>menu resource</a> with {@link
+href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a> with {@link
android.widget.PopupMenu#inflate inflate()}, passing it the menu resource ID.</li>
<li>You can also now create a {@link android.widget.PopupMenu.OnDismissListener} that receives a
callback when the menu is dismissed.</li>
@@ -1413,7 +1439,7 @@
<h4>Hover events</h4>
-<p>The {@link android.view.View} class now supports “hover” events to enable richer interactions
+<p>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).</p>
@@ -1435,11 +1461,11 @@
<p>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 <a
-href=”{@docRoot}guide/topics/resources/drawable-resource.html#StateList”>state list drawable</a> to
+href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">state list drawable</a> to
provide a different background drawable when a cursor hovers over the view.</p>
<p>For a demonstration of the new hover events, see the <a
-href=”{@docRoot}samples/ApiDemos/src/com/example/android/apis/view/Hover.html”>Hover</a> class in
+href="{@docRoot}samples/ApiDemos/src/com/example/android/apis/view/Hover.html">Hover</a> class in
ApiDemos.</p>
@@ -1455,7 +1481,7 @@
are pressed.</p>
<p>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
+“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},
@@ -1463,7 +1489,7 @@
can choose to handle stylus input in different ways from finger or mouse input.</p>
<p>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
+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
@@ -1480,7 +1506,7 @@
android.view.MotionEvent#AXIS_ORIENTATION}.</p>
<p>For a demonstration of tool types, button states and the new axis codes, see the <a
-href=”{@docRoot}samples/ApiDemos/src/com/example/android/apis/graphics/TouchPaint.html”>TouchPaint
+href="{@docRoot}samples/ApiDemos/src/com/example/android/apis/graphics/TouchPaint.html">TouchPaint
</a> class in ApiDemos.</p>
@@ -1538,11 +1564,11 @@
application has set either <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> or
<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> to
-{@code “14”} or higher. Hardware acceleration generally results in smoother animations, smoother
+{@code “14"} or higher. Hardware acceleration generally results in smoother animations, smoother
scrolling, and overall better performance and response to user interaction.</p>
<p>If necessary, you can manually disable hardware acceleration with the <a
-href=”{@docRoot}guide/topics/manifest/activity-element.html#hwaccel”>{@code hardwareAccelerated}</a>
+href="{@docRoot}guide/topics/manifest/activity-element.html#hwaccel">{@code hardwareAccelerated}</a>
attribute for individual <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code
<activity>}</a> elements or the <a
href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a>
@@ -1562,17 +1588,17 @@
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.</p>
-<p>The ins and outs of JNI local references are described in “Local and Global References” in <a
+<p>The ins and outs of JNI local references are described in “Local and Global References" in <a
href="{@docRoot}guide/practices/design/jni.html">JNI Tips</a>. In Android 4.0, <a
href="http://android-developers.blogspot.com/2011/07/debugging-android-jni-with-checkjni.html">
CheckJNI</a> has been enhanced to detect these errors. Watch the <a
-href=”http://android-developers.blogspot.com/”>Android Developers Blog</a> for an upcoming post
+href="http://android-developers.blogspot.com/">Android Developers Blog</a> for an upcoming post
about common errors with JNI references and how you can fix them.</p>
<p>This change in the JNI implementation only affects apps that target Android 4.0 by setting either
the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
targetSdkVersion}</a> or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
-minSdkVersion}</a> to {@code “14”} or higher. If you’ve set these attributes to any lower value,
+minSdkVersion}</a> 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.</p>
@@ -1598,7 +1624,7 @@
<ul>
<li>Updated V8 JavaScript compiler for faster performance</li>
<li>Plus other notable enhancements carried over from <a
-href=”{@docRoot}sdk/android-3.0.html”>Android
+href="{@docRoot}sdk/android-3.0.html">Android
3.0</a> are now available for handsets:
<ul>
<li>Support for fixed position elements on all pages</li>