Reconcile with ics-mr1-release
Change-Id: I628448f7b618988e20f7dfdf58c53133874a3958
diff --git a/core/java/android/view/ActionMode.java b/core/java/android/view/ActionMode.java
index 34e7d4d..0349a2b 100644
--- a/core/java/android/view/ActionMode.java
+++ b/core/java/android/view/ActionMode.java
@@ -18,9 +18,15 @@
/**
- * Represents a contextual mode of the user interface. Action modes can be used for
- * modal interactions with content and replace parts of the normal UI until finished.
- * Examples of good action modes include selection modes, search, content editing, etc.
+ * Represents a contextual mode of the user interface. Action modes can be used to provide
+ * alternative interaction modes and replace parts of the normal UI until finished.
+ * Examples of good action modes include text selection and contextual actions.
+ * <div class="special reference">
+ * <h3>Developer Guides</h3>
+ * <p>For information about how to provide contextual actions with {@code ActionMode},
+ * read the <a href="{@docRoot}guide/topics/ui/menu.html#context-menu">Menus</a>
+ * developer guide.</p>
+ * </div>
*/
public abstract class ActionMode {
private Object mTag;
diff --git a/core/java/android/widget/NumberPicker.java b/core/java/android/widget/NumberPicker.java
index 13375bf..750cbaa 100644
--- a/core/java/android/widget/NumberPicker.java
+++ b/core/java/android/widget/NumberPicker.java
@@ -54,14 +54,14 @@
/**
* A widget that enables the user to select a number form a predefined range.
- * The widget presents an input filed and up and down buttons for selecting the
- * current value. Pressing/long pressing the up and down buttons increments and
- * decrements the current value respectively. Touching the input filed shows a
- * scroll wheel, tapping on which while shown and not moving allows direct edit
- * of the current value. Sliding motions up or down hide the buttons and the
- * input filed, show the scroll wheel, and rotate the latter. Flinging is
+ * The widget presents an input field and up and down buttons for selecting the
+ * current value. Pressing/long-pressing the up and down buttons increments and
+ * decrements the current value respectively. Touching the input field shows a
+ * scroll wheel, which when touched allows direct edit
+ * of the current value. Sliding gestures up or down hide the buttons and the
+ * input filed, show and rotates the scroll wheel. Flinging is
* also supported. The widget enables mapping from positions to strings such
- * that instead the position index the corresponding string is displayed.
+ * that, instead of the position index, the corresponding string is displayed.
* <p>
* For an example of using this widget, see {@link android.widget.TimePicker}.
* </p>
diff --git a/core/res/res/values/styles.xml b/core/res/res/values/styles.xml
index 73e1a7c..283c30c 100644
--- a/core/res/res/values/styles.xml
+++ b/core/res/res/values/styles.xml
@@ -112,7 +112,7 @@
</style>
<!-- Standard animations for a translucent window or activity. This
- style is <em>not<em> used by default for the translucent theme
+ style is <em>not</em> used by default for the translucent theme
(since translucent activities are a special case that have no
clear UI paradigm), but you can make your own specialized theme
with this animation style if you would like to have the standard
diff --git a/core/res/res/values/themes.xml b/core/res/res/values/themes.xml
index fe5388b..7046fc5 100644
--- a/core/res/res/values/themes.xml
+++ b/core/res/res/values/themes.xml
@@ -29,15 +29,16 @@
===============================================================
-->
<resources>
- <!-- The default system theme. This is the theme used for activities
- that have not explicitly set their own theme.
-
+ <!-- The default theme for apps on API level 10 and lower. This is the theme used for
+ activities that have not explicitly set their own theme.
<p>You can count on this being a dark
background with light text on top, but should try to make no
other assumptions about its appearance. In particular, the text
inside of widgets using this theme may be completely different,
with the widget container being a light color and the text on top
of it a dark color.
+ <p>If you're developing for API level 11 and higher, you should instead use {@link
+ #Theme_Holo} or {@link #Theme_DeviceDefault}.</p>
-->
<style name="Theme">
@@ -370,13 +371,12 @@
<item name="pointerStyle">@android:style/Pointer</item>
</style>
- <!-- Variant of the default (dark) theme with no title bar -->
+ <!-- Variant of {@link #Theme} with no title bar -->
<style name="Theme.NoTitleBar">
<item name="android:windowNoTitle">true</item>
</style>
- <!-- Variant of the default (dark) theme that has no title bar and
- fills the entire screen -->
+ <!-- Variant of {@link #Theme} that has no title bar and no status bar -->
<style name="Theme.NoTitleBar.Fullscreen">
<item name="android:windowFullscreen">true</item>
<item name="android:windowContentOverlay">@null</item>
@@ -385,7 +385,8 @@
<!-- Theme for a light background with dark text on top. Set your activity
to this theme if you would like such an appearance. As with the
default theme, you should try to assume little more than that the
- background will be a light color. -->
+ background will be a light color.
+ <p>This is designed for API level 10 and lower.</p>-->
<style name="Theme.Light">
<item name="windowBackground">@android:drawable/screen_background_selector_light</item>
<item name="colorBackground">@android:color/background_light</item>
@@ -457,19 +458,19 @@
<item name="detailsElementBackground">@android:drawable/panel_bg_holo_light</item>
</style>
- <!-- Variant of the light theme with no title bar -->
+ <!-- Variant of {@link #Theme_Light} with no title bar -->
<style name="Theme.Light.NoTitleBar">
<item name="android:windowNoTitle">true</item>
</style>
- <!-- Variant of the light theme that has no title bar and
- fills the entire screen -->
+ <!-- Variant of {@link #Theme_Light} that has no title bar and
+ no status bar -->
<style name="Theme.Light.NoTitleBar.Fullscreen">
<item name="android:windowFullscreen">true</item>
<item name="android:windowContentOverlay">@null</item>
</style>
- <!-- Special variation on the default theme that ensures the background is
+ <!-- Variant on {@link #Theme} that ensures the background is
completely black. This is useful for things like image viewers and
media players. If you want the normal (dark background) theme
do <em>not</em> use this, use {@link #Theme}. -->
@@ -478,40 +479,40 @@
<item name="android:colorBackground">@android:color/black</item>
</style>
- <!-- Variant of the black theme with no title bar -->
+ <!-- Variant of {@link #Theme_Black} with no title bar -->
<style name="Theme.Black.NoTitleBar">
<item name="android:windowNoTitle">true</item>
</style>
- <!-- Variant of the black theme that has no title bar and
- fills the entire screen -->
+ <!-- Variant of {@link #Theme_Black} that has no title bar and
+ no status bar -->
<style name="Theme.Black.NoTitleBar.Fullscreen">
<item name="android:windowFullscreen">true</item>
<item name="android:windowContentOverlay">@null</item>
</style>
- <!-- Default theme for windows that want to have the user's selected
- wallpaper appear behind them. -->
+ <!-- Theme for windows that want to have the user's selected
+ wallpaper appear behind them (for API level 10 and lower). -->
<style name="Theme.Wallpaper">
<item name="android:windowBackground">@android:color/transparent</item>
<item name="android:colorBackgroundCacheHint">@null</item>
<item name="android:windowShowWallpaper">true</item>
</style>
- <!-- Variant of the translucent theme with no title bar -->
+ <!-- Variant of {@link #Theme_Wallpaper} that has no title bar -->
<style name="Theme.Wallpaper.NoTitleBar">
<item name="android:windowNoTitle">true</item>
</style>
- <!-- Variant of the translucent theme that has no title bar and
- fills the entire screen -->
+ <!-- Variant of {@link #Theme_Wallpaper} that
+ has no title bar or status bar. -->
<style name="Theme.Wallpaper.NoTitleBar.Fullscreen">
<item name="android:windowFullscreen">true</item>
<item name="android:windowContentOverlay">@null</item>
</style>
- <!-- Theme for a wallpaper's setting activity that is designed to be on
- top of a dark background. -->
+ <!-- Theme for a wallpaper's setting activity, which is designed to be a transparent
+ background with a dark shade, so the previous Activity is visible in the background. -->
<style name="Theme.WallpaperSettings">
<item name="android:windowBackground">@android:drawable/screen_background_dark_transparent</item>
<item name="android:colorBackgroundCacheHint">@null</item>
@@ -519,8 +520,8 @@
<item name="android:windowAnimationStyle">@android:style/Animation.Translucent</item>
</style>
- <!-- Theme for a wallpaper's setting activity that is designed to be on
- top of a light background. -->
+ <!-- Theme for a wallpaper's setting activity, which is designed to be a transparent
+ background with a light shade, so the previous Activity is visible in the background. -->
<style name="Theme.Light.WallpaperSettings">
<item name="android:windowBackground">@android:drawable/screen_background_light_transparent</item>
<item name="android:colorBackgroundCacheHint">@null</item>
@@ -538,8 +539,8 @@
<style name="PreviewWallpaperSettings">
</style>
- <!-- Default theme for translucent activities, that is windows that allow you
- to see through them to the windows behind. This sets up the translucent
+ <!-- Theme for translucent activities (on API level 10 and lower). That is, windows
+ that allow you to see through them to the windows behind. This sets up the translucent
flag and appropriate animations for your windows. -->
<style name="Theme.Translucent">
<item name="android:windowBackground">@android:color/transparent</item>
@@ -551,14 +552,14 @@
<item name="android:windowAnimationStyle">@android:style/Animation</item>
</style>
- <!-- Variant of the translucent theme with no title bar -->
+ <!-- Variant of {@link #Theme_Translucent} with no title bar -->
<style name="Theme.Translucent.NoTitleBar">
<item name="android:windowNoTitle">true</item>
<item name="android:windowContentOverlay">@null</item>
</style>
- <!-- Variant of the translucent theme that has no title bar and
- fills the entire screen -->
+ <!-- Variant of {@link #Theme_Translucent} that has no title bar and
+ no status bar -->
<style name="Theme.Translucent.NoTitleBar.Fullscreen">
<item name="android:windowFullscreen">true</item>
</style>
@@ -574,7 +575,8 @@
<item name="android:windowNoDisplay">true</item>
</style>
- <!-- Default theme for dialog windows and activities, which is used by the
+ <!-- Default theme for dialog windows and activities (on API level 10 and lower),
+ which is used by the
{@link android.app.Dialog} class. This changes the window to be
floating (not fill the entire screen), and puts a frame around its
contents. You can set this theme on an activity if you would like to
@@ -622,7 +624,7 @@
<item name="listPreferredItemPaddingRight">10dip</item>
</style>
- <!-- Variation of Theme.Dialog that does not include a frame (or background).
+ <!-- Variant of {@link Theme_Dialog} that does not include a frame (or background).
The view hierarchy of the dialog is responsible for drawing all of
its pixels. -->
<style name="Theme.Dialog.NoFrame">
@@ -636,7 +638,7 @@
<item name="android:windowCloseOnTouchOutside">false</item>
</style>
- <!-- Default theme for alert dialog windows, which is used by the
+ <!-- Default theme for alert dialog windows (on API level 10 and lower), which is used by the
{@link android.app.AlertDialog} class. This is basically a dialog
but sets the background to empty so it can do two-tone backgrounds. -->
<style name="Theme.Dialog.Alert">
@@ -648,8 +650,8 @@
<item name="textAppearanceListItemSmall">@android:style/TextAppearance.Large.Inverse</item>
</style>
- <!-- Default dark theme for panel windows. This removes all extraneous
- window decorations, so you basically have an empty rectangle in which
+ <!-- Default dark theme for panel windows (on API level 10 and lower). This removes all
+ extraneous window decorations, so you basically have an empty rectangle in which
to place your content. It makes the window floating, with a transparent
background, and turns off dimming behind the window. -->
<style name="Theme.Panel">
@@ -664,8 +666,8 @@
<item name="android:windowNoTitle">true</item>
</style>
- <!-- Default light theme for panel windows. This removes all extraneous
- window decorations, so you basically have an empty rectangle in which
+ <!-- Default light theme for panel windows (on API level 10 and lower). This removes all
+ extraneous window decorations, so you basically have an empty rectangle in which
to place your content. It makes the window floating, with a transparent
background, and turns off dimming behind the window. -->
<style name="Theme.Light.Panel">
@@ -712,7 +714,7 @@
<item name="android:windowNoTitle">true</item>
</style>
- <!-- Default theme for input methods, which is used by the
+ <!-- Default theme for input methods (on API level 10 and lower), which is used by the
{@link android.inputmethodservice.InputMethodService} class.
this inherits from Theme.Panel, but sets up IME appropriate animations
and a few custom attributes. -->
@@ -723,7 +725,7 @@
<item name="android:imeExtractExitAnimation">@android:anim/input_method_extract_exit</item>
</style>
- <!-- Default theme for modern holo style input methods, which is used by the
+ <!-- Default theme for holo style input methods, which is used by the
{@link android.inputmethodservice.InputMethodService} class.
this inherits from Theme.Panel, but sets up IME appropriate animations
and a few custom attributes. -->
@@ -842,14 +844,23 @@
<item name="android:windowActionModeOverlay">true</item>
</style>
- <!-- New Honeycomb holographic theme. Dark version. The widgets in the
- holographic theme are translucent on their brackground, so applications
- must ensure that any background they use with this theme is itself
- dark; otherwise, it will be difficult to see the widgets. The new
- UI style also includes a full action bar by default.
+ <!-- Honeycomb holographic theme (dark version).
+ <p>This is the default system theme for apps that target API level 11 - 13. Starting
+ with API level 14, the default system theme is supplied by {@link #Theme_DeviceDefault},
+ which might apply a different style on different devices. If you want to ensure that your
+ app consistenly uses the Holo theme at all times, you must explicitly declare it in your
+ manifest. For example, {@code <application android:theme="@android:style/Theme.Holo">}.
+ For more information, read <a
+ href="http://android-developers.blogspot.com/2012/01/holo-everywhere.html">Holo
+ Everywhere</a>.</p>
+ <p>The widgets in the holographic theme are translucent on their brackground, so
+ applications must ensure that any background they use with this theme is itself
+ dark; otherwise, it will be difficult to see the widgets. This UI style also includes a
+ full action bar by default.</p>
- Styles used by the Holo theme are named using the convention Type.Holo.Etc.
- (For example, Widget.Holo.Button, TextAppearance.Holo.Widget.PopupMenu.Large.)
+ <p>Styles used by the Holo theme are named using the convention Type.Holo.Etc
+ (for example, {@code Widget.Holo.Button} and {@code
+ TextAppearance.Holo.Widget.PopupMenu.Large}).
Specific resources used by Holo are named using the convention @type/foo_bar_baz_holo
with trailing _dark or _light specifiers if they are not shared between both light and
dark versions of the theme. -->
@@ -951,15 +962,12 @@
<item name="listDividerAlertDialog">@android:drawable/list_divider_holo_dark</item>
<item name="expandableListPreferredItemPaddingLeft">40dip</item>
- <item name="expandableListPreferredChildPaddingLeft">
- ?android:attr/expandableListPreferredItemPaddingLeft</item>
+ <item name="expandableListPreferredChildPaddingLeft">?android:attr/expandableListPreferredItemPaddingLeft</item>
<item name="expandableListPreferredItemIndicatorLeft">3dip</item>
<item name="expandableListPreferredItemIndicatorRight">0dip</item>
- <item name="expandableListPreferredChildIndicatorLeft">
- ?android:attr/expandableListPreferredItemIndicatorLeft</item>
- <item name="expandableListPreferredChildIndicatorRight">
- ?android:attr/expandableListPreferredItemIndicatorRight</item>
+ <item name="expandableListPreferredChildIndicatorLeft">?android:attr/expandableListPreferredItemIndicatorLeft</item>
+ <item name="expandableListPreferredChildIndicatorRight">?android:attr/expandableListPreferredItemIndicatorRight</item>
<!-- Gallery attributes -->
<item name="galleryItemBackground">@android:drawable/gallery_item_background</item>
@@ -1156,10 +1164,10 @@
</style>
- <!-- New Honeycomb holographic theme. Light version. The widgets in the
+ <!-- Honeycomb holographic theme (light version). The widgets in the
holographic theme are translucent on their brackground, so applications
must ensure that any background they use with this theme is itself
- light; otherwise, it will be difficult to see the widgets. The new
+ light; otherwise, it will be difficult to see the widgets. This
UI style also includes a full action bar by default. -->
<style name="Theme.Holo.Light" parent="Theme.Light">
<item name="colorForeground">@android:color/bright_foreground_holo_light</item>
@@ -1257,15 +1265,12 @@
<item name="activatedBackgroundIndicator">@android:drawable/activated_background_holo_light</item>
<item name="expandableListPreferredItemPaddingLeft">40dip</item>
- <item name="expandableListPreferredChildPaddingLeft">
- ?android:attr/expandableListPreferredItemPaddingLeft</item>
+ <item name="expandableListPreferredChildPaddingLeft">?android:attr/expandableListPreferredItemPaddingLeft</item>
<item name="expandableListPreferredItemIndicatorLeft">3dip</item>
<item name="expandableListPreferredItemIndicatorRight">0dip</item>
- <item name="expandableListPreferredChildIndicatorLeft">
- ?android:attr/expandableListPreferredItemIndicatorLeft</item>
- <item name="expandableListPreferredChildIndicatorRight">
- ?android:attr/expandableListPreferredItemIndicatorRight</item>
+ <item name="expandableListPreferredChildIndicatorLeft">?android:attr/expandableListPreferredItemIndicatorLeft</item>
+ <item name="expandableListPreferredChildIndicatorRight">?android:attr/expandableListPreferredItemIndicatorRight</item>
<item name="listDividerAlertDialog">@android:drawable/list_divider_holo_light</item>
@@ -1522,6 +1527,7 @@
</style>
<!-- Dialog themes for Holo -->
+ <eat-comment />
<!-- Holo theme for dialog windows and activities, which is used by the
{@link android.app.Dialog} class. This changes the window to be
@@ -1554,27 +1560,27 @@
<item name="listPreferredItemPaddingRight">16dip</item>
</style>
- <!-- Variation of Theme.Holo.Dialog that has a nice minumum width for
+ <!-- Variant of Theme.Holo.Dialog that has a nice minimum width for
a regular dialog. -->
<style name="Theme.Holo.Dialog.MinWidth">
<item name="android:windowMinWidthMajor">@android:dimen/dialog_min_width_major</item>
<item name="android:windowMinWidthMinor">@android:dimen/dialog_min_width_minor</item>
</style>
- <!-- Variation of Theme.Holo.Dialog that does not include a title bar. -->
+ <!-- Variant of Theme.Holo.Dialog that does not include a title bar. -->
<style name="Theme.Holo.Dialog.NoActionBar">
<item name="android:windowActionBar">false</item>
<item name="android:windowNoTitle">true</item>
</style>
- <!-- Variation of Theme.Holo.Dialog.NoActionVar that has a nice minumum width for
+ <!-- Variant of Theme.Holo.Dialog.NoActionBar that has a nice minimum width for
a regular dialog. -->
<style name="Theme.Holo.Dialog.NoActionBar.MinWidth">
<item name="android:windowMinWidthMajor">@android:dimen/dialog_min_width_major</item>
<item name="android:windowMinWidthMinor">@android:dimen/dialog_min_width_minor</item>
</style>
- <!-- Variation of Theme.Holo.Dialog that does not include a frame (or background).
+ <!-- Variant of Theme.Holo.Dialog that does not include a frame (or background).
The view hierarchy of the dialog is responsible for drawing all of
its pixels. -->
<style name="Theme.Holo.Dialog.NoFrame">
@@ -1646,20 +1652,20 @@
<item name="listPreferredItemPaddingRight">16dip</item>
</style>
- <!-- Variation of Theme.Holo.Light.Dialog that has a nice minumum width for
+ <!-- Variant of Theme.Holo.Light.Dialog that has a nice minimum width for
a regular dialog. -->
<style name="Theme.Holo.Light.Dialog.MinWidth">
<item name="android:windowMinWidthMajor">@android:dimen/dialog_min_width_major</item>
<item name="android:windowMinWidthMinor">@android:dimen/dialog_min_width_minor</item>
</style>
- <!-- Variation of Theme.Holo.Light.Dialog that does not include a title bar. -->
+ <!-- Variant of Theme.Holo.Light.Dialog that does not include a title bar. -->
<style name="Theme.Holo.Light.Dialog.NoActionBar">
<item name="android:windowActionBar">false</item>
<item name="android:windowNoTitle">true</item>
</style>
- <!-- Variation of Theme.Holo.Light.Dialog.NoActionBar that has a nice minumum width for
+ <!-- Variant of Theme.Holo.Light.Dialog.NoActionBar that has a nice minimum width for
a regular dialog. -->
<style name="Theme.Holo.Light.Dialog.NoActionBar.MinWidth">
<item name="android:windowMinWidthMajor">@android:dimen/dialog_min_width_major</item>
@@ -1700,7 +1706,8 @@
<item name="android:windowShowWallpaper">true</item>
</style>
- <!-- Variant of the holographic (dark) theme with no title bar -->
+ <!--Default holographic (dark) for windows that want to have the user's selected
+ wallpaper appear behind them and without an action bar. -->
<style name="Theme.Holo.Wallpaper.NoTitleBar">
<item name="android:windowNoTitle">true</item>
</style>
diff --git a/core/res/res/values/themes_device_defaults.xml b/core/res/res/values/themes_device_defaults.xml
index 8135986..abe4aad 100644
--- a/core/res/res/values/themes_device_defaults.xml
+++ b/core/res/res/values/themes_device_defaults.xml
@@ -31,6 +31,24 @@
===============================================================
-->
<resources>
+
+ <!-- The default theme for apps that target API level 14 and higher.
+ <p>The DeviceDefault themes are aliases for a specific device’s native look and feel. The
+ DeviceDefault theme family and widget style family offer ways for you to target your app
+ to a device’s native theme with all device customizations intact.</p>
+ <p>For example, when you set your app's {@code targetSdkVersion} to 14 or higher, this
+ theme is applied to your application by default. As such, your app might appear with the
+ {@link #Theme_Holo Holo} styles on one device, but with a different set of styles on
+ another device. This is great if you want your app to fit with the device's native look and
+ feel. If, however, you prefer to keep your UI style the same across all devices, you should
+ apply a specific theme such as {@link #Theme_Holo Holo} or one of your own design. For more
+ information, read <a
+ href="http://android-developers.blogspot.com/2012/01/holo-everywhere.html">Holo
+ Everywhere</a>.</p>
+ <p>Styles used by the DeviceDefault theme are named using the convention
+ Type.DeviceDefault.Etc (for example, {@code Widget.DeviceDefault.Button} and
+ {@code TextAppearance.DeviceDefault.Widget.PopupMenu.Large}).</p>
+ -->
<style name="Theme.DeviceDefault" parent="Theme.Holo" >
<!-- Text styles -->
<item name="textAppearance">@android:style/TextAppearance.DeviceDefault</item>
@@ -176,12 +194,16 @@
<!-- DatePicker style -->
<item name="datePickerStyle">@style/Widget.DeviceDefault.DatePicker</item>
</style>
+
+ <!-- Variant of {@link #Theme_DeviceDefault} with no action bar -->
<style name="Theme.DeviceDefault.NoActionBar" parent="Theme.Holo.NoActionBar" >
</style>
+ <!-- Variant of {@link #Theme_DeviceDefault} with no action bar and no status bar -->
<style name="Theme.DeviceDefault.NoActionBar.Fullscreen" parent="Theme.Holo.NoActionBar.Fullscreen" >
</style>
+ <!-- Variant of {@link #Theme_DeviceDefault} with a light-colored style -->
<style name="Theme.DeviceDefault.Light" parent="Theme.Holo.Light" >
<!-- Text styles -->
<item name="textAppearance">@android:style/TextAppearance.DeviceDefault.Light</item>
@@ -322,12 +344,17 @@
<!-- DatePicker style -->
<item name="datePickerStyle">@style/Widget.DeviceDefault.Light.DatePicker</item>
</style>
+ <!-- Variant of {@link #Theme_DeviceDefault_Light} with no action bar -->
<style name="Theme.DeviceDefault.Light.NoActionBar" parent="Theme.Holo.Light.NoActionBar" >
</style>
+ <!-- Variant of {@link #Theme_DeviceDefault_Light} with no action bar and no status bar -->
<style name="Theme.DeviceDefault.Light.NoActionBar.Fullscreen" parent="Theme.Holo.Light.NoActionBar.Fullscreen" >
</style>
+ <!-- DeviceDefault theme for dialog windows and activities. This changes the window to be
+ floating (not fill the entire screen), and puts a frame around its contents. You can set this
+ theme on an activity if you would like to make an activity that looks like a Dialog. -->
<style name="Theme.DeviceDefault.Dialog" parent="Theme.Holo.Dialog" >
<item name="android:windowTitleStyle">@android:style/DialogWindowTitle.DeviceDefault</item>
<item name="android:windowAnimationStyle">@android:style/Animation.DeviceDefault.Dialog</item>
@@ -338,15 +365,23 @@
<item name="textAppearance">@android:style/TextAppearance.DeviceDefault</item>
<item name="textAppearanceInverse">@android:style/TextAppearance.DeviceDefault.Inverse</item>
</style>
+ <!-- Variant of {@link #Theme_DeviceDefault_Dialog} that has a nice minimum width for a
+ regular dialog. -->
<style name="Theme.DeviceDefault.Dialog.MinWidth" parent="Theme.Holo.Dialog.MinWidth" >
</style>
+ <!-- Variant of {@link #Theme_DeviceDefault_Dialog} without an action bar -->
<style name="Theme.DeviceDefault.Dialog.NoActionBar" parent="Theme.Holo.Dialog.NoActionBar" >
</style>
+ <!-- Variant of {@link #Theme_DeviceDefault_Dialog_NoActionBar} that has a nice minimum width
+ for a regular dialog. -->
<style name="Theme.DeviceDefault.Dialog.NoActionBar.MinWidth" parent="Theme.Holo.Dialog.NoActionBar.MinWidth" >
</style>
+ <!-- DeviceDefault light theme for dialog windows and activities. This changes the window to be
+ floating (not fill the entire screen), and puts a frame around its contents. You can set this
+ theme on an activity if you would like to make an activity that looks like a Dialog.-->
<style name="Theme.DeviceDefault.Light.Dialog" parent="Theme.Holo.Light.Dialog" >
<item name="android:windowTitleStyle">@android:style/DialogWindowTitle.DeviceDefault.Light</item>
<item name="android:windowAnimationStyle">@android:style/Animation.DeviceDefault.Dialog</item>
@@ -357,42 +392,71 @@
<item name="textAppearance">@android:style/TextAppearance.DeviceDefault.Light</item>
<item name="textAppearanceInverse">@android:style/TextAppearance.DeviceDefault.Light.Inverse</item>
</style>
+ <!-- Variant of {@link #Theme_DeviceDefault_Light_Dialog} that has a nice minimum width for a
+ regular dialog. -->
<style name="Theme.DeviceDefault.Light.Dialog.MinWidth" parent="Theme.Holo.Light.Dialog.MinWidth" >
</style>
+ <!-- Variant of {@link #Theme_DeviceDefault_Light_Dialog} without an action bar -->
<style name="Theme.DeviceDefault.Light.Dialog.NoActionBar" parent="Theme.Holo.Light.Dialog.NoActionBar" >
</style>
+ <!-- Variant of {@link #Theme_DeviceDefault_Light_Dialog_NoActionBar} that has a nice minimum
+ width for a regular dialog. -->
<style name="Theme.DeviceDefault.Light.Dialog.NoActionBar.MinWidth" parent="Theme.Holo.Light.Dialog.NoActionBar.MinWidth" >
</style>
+ <!-- DeviceDefault theme for a window that will be displayed either full-screen on smaller
+ screens (small, normal) or as a dialog on larger screens (large, xlarge). -->
<style name="Theme.DeviceDefault.DialogWhenLarge" parent="Theme.Holo.DialogWhenLarge" >
</style>
+ <!-- DeviceDefault theme for a window without an action bar that will be displayed either
+ full-screen on smaller screens (small, normal) or as a dialog on larger screens (large,
+ xlarge). -->
<style name="Theme.DeviceDefault.DialogWhenLarge.NoActionBar" parent="Theme.Holo.DialogWhenLarge.NoActionBar" >
</style>
+ <!-- DeviceDefault light theme for a window that will be displayed either full-screen on smaller
+ screens (small, normal) or as a dialog on larger screens (large, xlarge). -->
<style name="Theme.DeviceDefault.Light.DialogWhenLarge" parent="Theme.Holo.Light.DialogWhenLarge" >
</style>
+ <!-- DeviceDefault light theme for a window without an action bar that will be displayed either
+ full-screen on smaller screens (small, normal) or as a dialog on larger screens (large,
+ xlarge). -->
<style name="Theme.DeviceDefault.Light.DialogWhenLarge.NoActionBar" parent="Theme.Holo.Light.DialogWhenLarge.NoActionBar" >
</style>
+ <!-- DeviceDefault theme for panel windows. This removes all extraneous window
+ decorations, so you basically have an empty rectangle in which to place your content. It makes
+ the window floating, with a transparent background, and turns off dimming behind the window. -->
<style name="Theme.DeviceDefault.Panel" parent="Theme.Holo.Panel" >
</style>
+ <!-- DeviceDefault light theme for panel windows. This removes all extraneous window
+ decorations, so you basically have an empty rectangle in which to place your content. It makes
+ the window floating, with a transparent background, and turns off dimming behind the window. -->
<style name="Theme.DeviceDefault.Light.Panel" parent="Theme.Holo.Light.Panel" >
</style>
+ <!-- DeviceDefault theme for windows that want to have the user's selected wallpaper appear
+ behind them. -->
<style name="Theme.DeviceDefault.Wallpaper" parent="Theme.Holo.Wallpaper" >
</style>
+ <!-- DeviceDefault theme for windows that want to have the user's selected wallpaper appear
+ behind them and without an action bar. -->
<style name="Theme.DeviceDefault.Wallpaper.NoTitleBar" parent="Theme.Holo.Wallpaper.NoTitleBar" >
</style>
+ <!-- DeviceDefault style for input methods, which is used by the
+ {@link android.inputmethodservice.InputMethodService} class.-->
<style name="Theme.DeviceDefault.InputMethod" parent="Theme.Holo.InputMethod" >
</style>
+ <!-- Variant of the DeviceDefault (light) theme that has a solid (opaque) action bar with an
+ inverse color profile. -->
<style name="Theme.DeviceDefault.Light.DarkActionBar" parent="Theme.Holo.Light.DarkActionBar" >
<item name="android:actionBarStyle">@android:style/Widget.DeviceDefault.Light.ActionBar.Solid.Inverse</item>
diff --git a/docs/html/guide/appendix/market-filters.jd b/docs/html/guide/appendix/market-filters.jd
index 07b9370..d9b2155 100644
--- a/docs/html/guide/appendix/market-filters.jd
+++ b/docs/html/guide/appendix/market-filters.jd
@@ -165,10 +165,10 @@
<p><strong>Example 1</strong><br />
The manifest declares <code><uses-sdk android:minSdkVersion="3"></code>
- and does not does not include a <code><supports-screens></code> element.
- <strong>Result</strong>: Android Market will not show the app to a user of a
- small-screen device, but will show it to users of normal and large-screen
- devices, users, unless other filters apply. </p>
+ and does not include a <code><supports-screens></code> element.
+ <strong>Result</strong>: Android Market does not show the app to a user of a
+ small-screen device, but does show it to users of normal and large-screen
+ devices, unless other filters also exclude those devices. </p>
<p><strong>Example 2<br />
</strong>The manifest declares <code><uses-sdk android:minSdkVersion="3"
android:targetSdkVersion="4"></code> and does not include a
diff --git a/docs/html/guide/developing/device.jd b/docs/html/guide/developing/device.jd
index e46d07c..d390ec1 100644
--- a/docs/html/guide/developing/device.jd
+++ b/docs/html/guide/developing/device.jd
@@ -254,6 +254,10 @@
<td><code>04DD</code></td>
</tr>
<tr>
+ <td>Sony</td>
+ <td><code>054C</code></td>
+ </tr>
+ <tr>
<td>Sony Ericsson</td>
<td><code>0FCE</code></td>
</tr>
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs
index 4e5badd..4a9a684 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -8,15 +8,16 @@
<ul>
<li>
- <h2><span class="en">Android Basics</span>
- <span class="de" style="display:none">Einführung in Android</span>
- <span class="es" style="display:none">Información básica sobre Android</span>
- <span class="fr" style="display:none">Présentation d'Android</span>
- <span class="it" style="display:none">Nozioni di base su Android</span>
- <span class="ja" style="display:none">Android の基本</span>
- <span class="zh-CN" style="display:none">Android 基础知识</span>
- <span class="zh-TW" style="display:none">Android 簡介</span>
- </h2>
+ <span class="heading">
+ <span class="en">Android Basics</span>
+ <span class="de" style="display:none">Einführung in Android</span>
+ <span class="es" style="display:none">Información básica sobre Android</span>
+ <span class="fr" style="display:none">Présentation d'Android</span>
+ <span class="it" style="display:none">Nozioni di base su Android</span>
+ <span class="ja" style="display:none">Android の基本</span>
+ <span class="zh-CN" style="display:none">Android 基础知识</span>
+ <span class="zh-TW" style="display:none">Android 簡介</span>
+ </span>
<ul>
<li><a href="<?cs var:toroot ?>guide/basics/what-is-android.html">
<span class="en">What Is Android?</span>
@@ -46,7 +47,7 @@
</li>
<li>
- <h2>
+ <span class="heading">
<span class="en">Framework Topics</span>
<span class="de" style="display:none">Framework-Themen</span>
<span class="es" style="display:none">Temas sobre el framework</span>
@@ -55,7 +56,7 @@
<span class="ja" style="display:none">フレームワーク トピック</span>
<span class="zh-CN" style="display:none">框架主题</span>
<span class="zh-TW" style="display:none">架構主題</span>
- </h2>
+ </span>
<ul>
<li class="toggle-list">
<div><a href="<?cs var:toroot ?>guide/topics/fundamentals/activities.html">
@@ -130,7 +131,7 @@
</a></li>
<li><a href="<?cs var:toroot ?>guide/topics/ui/menus.html">
<span class="en">Menus</span>
- </a></li>
+ </a> <span class="new">updated</span></li>
<li><a href="<?cs var:toroot ?>guide/topics/ui/actionbar.html">
<span class="en">Action Bar</span>
</a></li>
@@ -443,9 +444,9 @@
</li>
<li>
- <h2>
+ <span class="heading">
<span class="en">Android Market Topics</span>
- </h2>
+ </span>
<ul>
<li><a href="<?cs var:toroot ?>guide/publishing/publishing.html">
<span class="en">Publishing on Android Market</span>
@@ -489,15 +490,16 @@
<li>
- <h2><span class="en">Developing</span>
- <span class="de" style="display:none">Entwicklung</span>
- <span class="es" style="display:none">Desarrollo</span>
- <span class="fr" style="display:none">Développement</span>
- <span class="it" style="display:none">Sviluppo</span>
- <span class="ja" style="display:none">開発</span>
- <span class="zh-CN" style="display:none">开发</span>
- <span class="zh-TW" style="display:none">開發</span>
- </h2>
+ <span class="heading">
+ <span class="en">Developing</span>
+ <span class="de" style="display:none">Entwicklung</span>
+ <span class="es" style="display:none">Desarrollo</span>
+ <span class="fr" style="display:none">Développement</span>
+ <span class="it" style="display:none">Sviluppo</span>
+ <span class="ja" style="display:none">開発</span>
+ <span class="zh-CN" style="display:none">开发</span>
+ <span class="zh-TW" style="display:none">開發</span>
+ </span>
<ul>
<!--<li><a href="">Developing for Android</a></li>
signing, upgrading, selecting a package name, select device profile, touch, trackball, dpad available, etc. -->
@@ -683,15 +685,16 @@
</li>
<li>
- <h2><span class="en">Publishing</span>
- <span class="de" style="display:none">Veröffentlichung</span>
- <span class="es" style="display:none">Publicación</span>
- <span class="fr" style="display:none">Publication</span>
- <span class="it" style="display:none">Pubblicazione</span>
- <span class="ja" style="display:none">公開</span>
- <span class="zh-CN" style="display:none">发布</span>
- <span class="zh-TW" style="display:none">發佈</span>
- </h2>
+ <span class="heading">
+ <span class="en">Publishing</span>
+ <span class="de" style="display:none">Veröffentlichung</span>
+ <span class="es" style="display:none">Publicación</span>
+ <span class="fr" style="display:none">Publication</span>
+ <span class="it" style="display:none">Pubblicazione</span>
+ <span class="ja" style="display:none">公開</span>
+ <span class="zh-CN" style="display:none">发布</span>
+ <span class="zh-TW" style="display:none">發佈</span>
+ </span>
<ul>
<li><a href="<?cs var:toroot ?>guide/publishing/publishing_overview.html">
<span class="en">Publishing Overview</span>
@@ -733,15 +736,16 @@
</li>
<li>
- <h2><span class="en">Best Practices</span>
- <span class="de" style="display:none">Bewährte Verfahren</span>
- <span class="es" style="display:none">Prácticas recomendadas</span>
- <span class="fr" style="display:none">Meilleures pratiques</span>
- <span class="it" style="display:none">Best practice</span>
- <span class="ja" style="display:none">ベスト プラクティス</span>
- <span class="zh-CN" style="display:none">最佳实践</span>
- <span class="zh-TW" style="display:none">最佳實務</span>
- </h2>
+ <span class="heading">
+ <span class="en">Best Practices</span>
+ <span class="de" style="display:none">Bewährte Verfahren</span>
+ <span class="es" style="display:none">Prácticas recomendadas</span>
+ <span class="fr" style="display:none">Meilleures pratiques</span>
+ <span class="it" style="display:none">Best practice</span>
+ <span class="ja" style="display:none">ベスト プラクティス</span>
+ <span class="zh-CN" style="display:none">最佳实践</span>
+ <span class="zh-TW" style="display:none">最佳實務</span>
+ </span>
<ul>
<li><a href="<?cs var:toroot ?>guide/practices/compatibility.html">
<span class="en">Compatibility</span>
@@ -837,8 +841,9 @@
</li>
<li>
- <h2><span class="en">Web Applications</span>
- </h2>
+ <span class="heading">
+ <span class="en">Web Applications</span>
+ </span>
<ul>
<li><a href="<?cs var:toroot ?>guide/webapps/index.html">
<span class="en">Web Apps Overview</span>
@@ -859,15 +864,16 @@
</li>
<li>
- <h2><span class="en">Appendix</span>
- <span class="de" style="display:none">Anhang</span>
- <span class="es" style="display:none">Apéndice</span>
- <span class="fr" style="display:none">Annexes</span>
- <span class="it" style="display:none">Appendice</span>
- <span class="ja" style="display:none">付録</span>
- <span class="zh-CN" style="display:none">附录</span>
- <span class="zh-TW" style="display:none">附錄</span>
- </h2>
+ <span class="heading">
+ <span class="en">Appendix</span>
+ <span class="de" style="display:none">Anhang</span>
+ <span class="es" style="display:none">Apéndice</span>
+ <span class="fr" style="display:none">Annexes</span>
+ <span class="it" style="display:none">Appendice</span>
+ <span class="ja" style="display:none">付録</span>
+ <span class="zh-CN" style="display:none">附录</span>
+ <span class="zh-TW" style="display:none">附錄</span>
+ </span>
<ul>
<li><a href="<?cs var:toroot ?>guide/appendix/api-levels.html">
<span class="en">Android API Levels</span>
diff --git a/docs/html/guide/practices/tablets-and-handsets.jd b/docs/html/guide/practices/tablets-and-handsets.jd
index 3f4aaa9..8e07a08 100644
--- a/docs/html/guide/practices/tablets-and-handsets.jd
+++ b/docs/html/guide/practices/tablets-and-handsets.jd
@@ -99,7 +99,8 @@
<p>You can enable items from the options menu to appear directly in the action bar as "action
items". You can also add navigation features to the action bar, such as tabs or a drop-down list,
-and use the application icon to supplement the system's BACK behavior with the option to navigate to
+and use the application icon to supplement the system's <em>Back</em> button behavior with the option to
+navigate to
your application's "home" activity or "up" the application's structural hierarchy.</p>
<p>This guide provides some tips for using the action bar in ways that support both tablets and
@@ -458,7 +459,8 @@
developer guide, you can use the application icon in the action bar to facilitate user navigation
when appropriate—either as a method to get back to the "home" activity (similar to clicking
the logo on a web site) or as a way to navigate up the application's structural hierarchy. Although
-it might seem similar to the standard BACK navigation in some cases, the up navigation option
+it might seem similar to the standard <em>Back</em> navigation in some cases, the up navigation
+option
provides a more predictable navigation method for situations in which the user may have entered
from an external location, such as a notification, app widget, or a different application.</p>
diff --git a/docs/html/guide/practices/ui_guidelines/activity_task_design.jd b/docs/html/guide/practices/ui_guidelines/activity_task_design.jd
index 5faa7ec..9be72ee 100644
--- a/docs/html/guide/practices/ui_guidelines/activity_task_design.jd
+++ b/docs/html/guide/practices/ui_guidelines/activity_task_design.jd
@@ -42,7 +42,8 @@
<li><a href=#activities_added_to_task_tip>Allow activities to add to current task</a></li>
<li><a href=#notifications_get_back_tip>Notifications and App Widgets should provide consistent back behavior</li>
<li><a href=#use_notification_tip>Use the notification system</a></li>
- <li><a href=#taking_over_back_key>Don't take over BACK key unless you absolutely need to</a></li>
+ <li><a href=#taking_over_back_key>Don't take over <em>Back</em> button unless you absolutely
+need to</a></li>
</ol>
</li>
</ol>
@@ -241,8 +242,8 @@
Android system keeps a linear navigation history of activities the
user has visited. This is the <em>activity stack</em>, also known as the
back stack. In general, when a user starts a new activity, it is added
- to the activity stack, so that pressing BACK displays the previous
- activity on the stack. However, the user cannot use the BACK key to go
+ to the activity stack, so that pressing <em>Back</em> displays the previous
+ activity on the stack. However, the user cannot use the <em>Back</em> button to go
back further than the last visit to Home. The adding of an activity to
the current stack happens whether or not that activity begins a new
<a href=#tasks title=task>task</a> (as long as that task was started
@@ -256,10 +257,11 @@
Activities are the only things that can be added to the activity stack
— views, windows, menus, and dialogs cannot. That is, when
designing the navigation, if you have screen A and you want the user
- to be able go to a subsequent screen B and then use the BACK key to go
+ to be able go to a subsequent screen B and then use the <em>Back</em> button to go
back to screen A, then the screen A needs to be implemented as an
activity. The one exception to this rule is if your application
- <a href="#taking_over_back_key">takes control of the BACK key</a> and manages the navigation
+ <a href="#taking_over_back_key">takes control of the <em>Back</em> button</a> and manages the
+navigation
itself.
</p>
@@ -287,7 +289,7 @@
launcher, Home screen shortcut or "Recent tasks" switcher (a long
press on Home on some devices). The user can return to a task by
choosing the icon for its root activity the same way they started the
- task. Once inside a task, the BACK key goes to previous activities in
+ task. Once inside a task, the <em>Back</em> button goes to previous activities in
that task. The activity stack is made up of one or more tasks.
</p>
@@ -331,7 +333,7 @@
Browser are two applications that do this. For example, choosing an
address in an email starts the Maps activity as a new task, and
choosing a link in an email starts the Browser activity as a new
- task. In these cases, the BACK key will return to the previous
+ task. In these cases, the <em>Back</em> button will return to the previous
activity in a different task (Email), because it was not started from
Home.
</p>
@@ -341,7 +343,7 @@
<p>
The following examples illustrate basic principles for applications,
- activities, the activity stack, the BACK key, tasks and intents. It
+ activities, the activity stack, the <em>Back</em> button, tasks and intents. It
shows how the system responds to user actions such as starting
activities and switching between tasks. With most of these examples
you can follow along, launching activities on your device as
@@ -367,19 +369,20 @@
<img src={@docRoot}images/activity_task_design/HomeTaskBasics1a.png>
</p>
-<h3 id=navigating_away_from_an_activity>Navigating Away from an Activity with BACK and HOME keys</h3>
+<h3 id=navigating_away_from_an_activity>Navigating Away from an Activity with <em>Back</em> and
+<em>Home</em> buttons</h3>
<p>
An activity can keep or lose its state depending on how the user
- leaves the activity — by the HOME or BACK key.
+ leaves the activity — by the <em>Home</em> or <em>Back</em> button.
</p>
<p>
- By default, pressing the BACK key finishes (destroys) the current
+ By default, pressing the <em>Back</em> button finishes (destroys) the current
activity and displays the previous activity to the user. In the
following figure, the user starts email by touching the Email icon in
the Home screen, which displays a list of email messages. The user
- scrolls down the list (changing its initial state). Pressing BACK
+ scrolls down the list (changing its initial state). Pressing <em>Back</em>
destroys the List Messages activity and returns to the previous
activity, which is Home. If the user re-launches Email, it would
re-load the messages and display its initial, non-scrolled state.
@@ -390,15 +393,15 @@
</p>
<p>
- In the above example, pressing BACK goes to Home because it was the
+ In the above example, pressing <em>Back</em> goes to Home because it was the
last activity the user was viewing. But if the user had gotten to List
- Message from some other activity, then pressing BACK would have
+ Message from some other activity, then pressing <em>Back</em> would have
returned there.
</p>
<p>
By contrast, the next figure shows the user leaving List Messages by
- pressing HOME instead of BACK — the List Messages activity is
+ pressing <em>Home</em> instead of <em>Back</em> — the List Messages activity is
stopped and moved to the background rather than being
destroyed. Starting Email again from its icon would simply bring the
List Messages activity to the foreground (changing it from stopped to
@@ -423,8 +426,8 @@
<p>
In addition, not all activities have the behavior that they are
- destroyed when BACK is pressed. When the user starts playing music in
- the Music application and then presses BACK, the application overrides
+ destroyed when <em>Back</em> is pressed. When the user starts playing music in
+ the Music application and then presses <em>Back</em>, the application overrides
the normal back behavior, preventing the player activity from being
destroyed, and continues playing music, even though its activity is no
longer visible — as a visual substitute, the Music application
@@ -451,7 +454,7 @@
activity to get a picture. This is a good example of re-use of the
Gallery activity. The following figure illustrates the sequence of
activities to do this (up to crop). This is how it's done: The user
- chooses Contacts, selects the contact for viewing, chooses MENU >
+ chooses Contacts, selects the contact for viewing, chooses <em>Menu</em> >
Edit contact and touches the picture field, which launches the Gallery
activity. The user then chooses the picture they want, crops and saves
it. Saving it causes the picture to be inserted into the picture field
@@ -484,12 +487,12 @@
<b>Gallery Re-Uses Messaging for Sharing a Picture</b> - Sharing is
another good example of one application re-using an activity from a
different application. As shown in the following figure, the user
- starts Gallery, picks a picture to view, chooses MENU > Share, and
+ starts Gallery, picks a picture to view, chooses <em>Menu</em> > Share, and
picks "Messaging". This starts the Messaging activity, creates a new
message and attaches the original picture to it. The user then fills
in the "To" field, writes a short message and sends it. User focus
remains in the Messaging program. If the user wants to go back to the
- Gallery, they must press the BACK key. (The user can back up through
+ Gallery, they must press the <em>Back</em> button. (The user can back up through
each activity all the way to Home.)
</p>
@@ -552,7 +555,7 @@
<ul>
<li>
State 2 - The user wants to do something else while they're
- waiting, so they press HOME, which does not interrupt the map's
+ waiting, so they press <em>Home</em>, which does not interrupt the map's
network connection and allows the map to continue loading in the
background.
@@ -729,7 +732,7 @@
<b>Start first task.</b> You want to send a text message and attach a photo. You would choose:
<p>
- Home > Messaging > New message > MENU > Attach
+ Home > Messaging > New message > <em>Menu</em> > Attach
> Pictures. This last step launches the picture gallery
for picking a photo. Notice that picture gallery is an
activity in a separate application.
@@ -961,7 +964,7 @@
address in an email message (or web page), where the Maps
activity is started to map the location. No result from maps
is expected to be returned to the email message; the user
- can return by pressing the BACK key. (Such an activity is
+ can return by pressing the <em>Back</em> button. (Such an activity is
started with {@link
android.content.Context#startActivity(android.content.Intent)
startActivity()}.)
@@ -1102,20 +1105,21 @@
convenience to respond to your message.
</p>
-<h3 id=taking_over_back_key>Don't take over the BACK key unless you absolutely need to</h3>
+<h3 id=taking_over_back_key>Don't take over the <em>Back</em> button unless you absolutely need
+to</h3>
<p>
As a user navigates from one activity to the next, the system adds
them to the activity stack. This forms a navigation history that is
- accessible with the BACK key. Most activities are relatively limited
+ accessible with the <em>Back</em> button. Most activities are relatively limited
in scope, with just one set of data, such as viewing a list of
contacts, composing an email, or taking a photo. But what if your
application is one big activity with several pages of content and
- needs finer-grained control of the BACK key? Examples of such Google
+ needs finer-grained control of the <em>Back</em> button? Examples of such Google
applications are the Browser, which can have several web pages open
at once, and Maps, which can have several layers of geographic data
to switch between. Both of these applications take control of the
- BACK key and maintain their own internal back stacks that operate
+ <em>Back</em> button and maintain their own internal back stacks that operate
only when these applications have focus.
</p>
@@ -1124,7 +1128,7 @@
information on a map to the user: displaying the location of a
search result, displaying locations of friends, and displaying a
line for a street path providing direction between points. Maps
- stores these layers in its own history so the BACK key can return to
+ stores these layers in its own history so the <em>Back</em> button can return to
a previous layer.
</p>
@@ -1135,8 +1139,8 @@
as Windows, Macintosh or Linux). For example, if you did a Google
web search in one window of the Android Browser, clicking on a link
in the search results displays a web page in that same window, and
- then pressing BACK would to the search results page. Pressing
- BACK goes to a previous window only if the current window was
+ then pressing <em>Back</em> would to the search results page. Pressing
+ <em>Back</em> goes to a previous window only if the current window was
launched from that previous window. If the user keeps pressing
back, they will eventually leave the browser activity and return
Home.
diff --git a/docs/html/guide/practices/ui_guidelines/menu_design.jd b/docs/html/guide/practices/ui_guidelines/menu_design.jd
index 3edf33f..7576b6c 100644
--- a/docs/html/guide/practices/ui_guidelines/menu_design.jd
+++ b/docs/html/guide/practices/ui_guidelines/menu_design.jd
@@ -71,7 +71,7 @@
<ul>
<li>The <em>Options menu</em> contains primary functionality that applies
globally to the current activity or starts a related activity.
- It is typically invoked by a user pressing a hard button, often labeled MENU.</li>
+ It is typically invoked by a user pressing a hard button, often labeled <em>Menu</em>.</li>
<li>The <em>Context menu</em> contains secondary functionality for the currently
selected item. It is typically invoked by a user's touch & hold
on an item. Like on the Options menu, the operation can run either
@@ -109,10 +109,10 @@
</p>
<p>
- On most devices, a user presses the MENU button to access the Options menu,
+ On most devices, a user presses the <em>Menu</em> button to access the Options menu,
as shown in the screenshot below. To close the menu, the user presses
- MENU again, or presses the BACK button.
- In fact, to cancel out of any menu, press the BACK button. (Pressing the MENU
+ <em>Menu</em> again, or presses the <em>Back</em> button.
+ In fact, to cancel out of any menu, press the <em>Back</em> button. (Pressing the <em>Menu</em>
button or touching outside the menu also works.) Note that how to invoke this
menu may be different on different devices.
</p>
@@ -140,7 +140,7 @@
<ul>
<li>
- <b>Options icon menu</b> - The first press of the MENU button displays a
+ <b>Options icon menu</b> - The first press of the <em>Menu</em> button displays a
non-scrollable grid of icons at the bottom of the screen. (On the G1
phone, up to 6 buttons typically appear.)
</li>
@@ -156,7 +156,7 @@
<p>
On some versions of Android, the user can display keyboard shortcuts in the
- icon menu by long pressing the MENU button — the text in the icon menu
+ icon menu by long pressing the <em>Menu</em> button — the text in the icon menu
alternates between the command names and their keyboard shortcuts (if any).
</p>
@@ -299,7 +299,7 @@
<a href="#location">location</a>) on the screen, put the command in the
Context menu for that content. If the command acts on no specific content
or location, put it in the Options menu. This separation of commands
- is enforced by the system in the following way. When you press the MENU
+ is enforced by the system in the following way. When you press the <em>Menu</em>
button to display the Options menu, the selected content becomes unselected,
and so cannot be operated on. For an explanation
of why the content becomes unselected, see the article on
@@ -340,7 +340,7 @@
<p>
Before opening a Context menu, it has no visual representation that identifies
- its presence (whereas the Options menu has the MENU button), and so is not
+ its presence (whereas the Options menu has the <em>Menu</em> button), and so is not
particularly discoverable.
Therefore, in general, a Context menu should <em>duplicate</em> commands
found in the corresponding activity screen. For example, while it's useful to
@@ -459,7 +459,8 @@
<h3 id="a_dialog_should_not_have_an_options_menu">A dialog should not have an Options menu</h3>
<p>
- When a dialog is displayed, pressing the MENU button should do nothing. This also holds true
+ When a dialog is displayed, pressing the <em>Menu</em> button should do nothing. This also holds
+true
for activities that look like dialogs. A dialog box is recognizable by being
smaller than full-screen, having zero to three buttons, is non-scrollable, and
possibly a list of selectable items that can include checkboxes or radio buttons.
@@ -475,7 +476,7 @@
<h3 id="do_not_substitute_message">If an activity has no Options menu, do not display a message</h3>
<p>
- When the user presses the MENU button, if there is no Options menu, the system
+ When the user presses the <em>Menu</em> button, if there is no Options menu, the system
currently does nothing. We recommend you do not perform any action (such as
displaying a message). It's a better user experience for this behavior to be
consistent across applications.
diff --git a/docs/html/guide/topics/fundamentals/activities.jd b/docs/html/guide/topics/fundamentals/activities.jd
index 3b31199..8736aa8 100644
--- a/docs/html/guide/topics/fundamentals/activities.jd
+++ b/docs/html/guide/topics/fundamentals/activities.jd
@@ -63,7 +63,7 @@
activity starts, the previous activity is stopped, but the system preserves the activity
in a stack (the "back stack"). When a new activity starts, it is pushed onto the back stack and
takes user focus. The back stack abides to the basic "last in, first out" queue mechanism,
-so, when the user is done with the current activity and presses the BACK key, it
+so, when the user is done with the current activity and presses the <em>Back</em> button, it
is popped from the stack (and destroyed) and the previous activity resumes. (The back stack is
discussed more in the <a href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks
and Back Stack</a> document.)</p>
@@ -649,7 +649,8 @@
<p class="note"><strong>Note:</strong> There's no guarantee that {@link
android.app.Activity#onSaveInstanceState onSaveInstanceState()} will be called before your
activity is destroyed, because there are cases in which it won't be necessary to save the state
-(such as when the user leaves your activity using the BACK key, because the user is explicitly
+(such as when the user leaves your activity using the <em>Back</em> button, because the user is
+explicitly
closing the activity). If the system calls {@link android.app.Activity#onSaveInstanceState
onSaveInstanceState()}, it does so before {@link
android.app.Activity#onStop onStop()} and possibly before {@link android.app.Activity#onPause
diff --git a/docs/html/guide/topics/fundamentals/fragments.jd b/docs/html/guide/topics/fundamentals/fragments.jd
index e8f6cd8..d4f9342 100644
--- a/docs/html/guide/topics/fundamentals/fragments.jd
+++ b/docs/html/guide/topics/fundamentals/fragments.jd
@@ -78,7 +78,7 @@
fragment transaction, you can also add it to a back stack that's managed by the
activity—each back stack entry in the activity is a record of the fragment transaction that
occurred. The back stack allows the user to reverse a fragment transaction (navigate backwards),
-by pressing the BACK button.</p>
+by pressing the <em>Back</em> button.</p>
<p>When you add a fragment as a part of your activity layout, it lives in a {@link
android.view.ViewGroup} inside the activity's view hierarchy and the fragment defines its own view
@@ -398,7 +398,7 @@
the activity layout) or {@link android.app.FragmentManager#findFragmentByTag
findFragmentByTag()} (for fragments that do or don't provide a UI).</li>
<li>Pop fragments off the back stack, with {@link
-android.app.FragmentManager#popBackStack()} (simulating a BACK command by the user).</li>
+android.app.FragmentManager#popBackStack()} (simulating a <em>Back</em> command by the user).</li>
<li>Register a listener for changes to the back stack, with {@link
android.app.FragmentManager#addOnBackStackChangedListener addOnBackStackChangedListener()}.</li>
</ul>
@@ -439,7 +439,7 @@
android.app.FragmentTransaction#commit()}, however, you might want to call {@link
android.app.FragmentTransaction#addToBackStack addToBackStack()}, in order to add the transaction
to a back stack of fragment transactions. This back stack is managed by the activity and allows
-the user to return to the previous fragment state, by pressing the BACK key.</p>
+the user to return to the previous fragment state, by pressing the <em>Back</em> button.</p>
<p>For example, here's how you can replace one fragment with another, and preserve the previous
state in the back stack:</p>
@@ -462,14 +462,14 @@
layout container identified by the {@code R.id.fragment_container} ID. By calling {@link
android.app.FragmentTransaction#addToBackStack addToBackStack()}, the replace transaction is
saved to the back stack so the user can reverse the transaction and bring back the
-previous fragment by pressing the BACK key.</p>
+previous fragment by pressing the <em>Back</em> button.</p>
<p>If you add multiple changes to the transaction (such as another {@link
android.app.FragmentTransaction#add add()} or {@link android.app.FragmentTransaction#remove
remove()}) and call {@link
android.app.FragmentTransaction#addToBackStack addToBackStack()}, then all changes applied
before you call {@link android.app.FragmentTransaction#commit commit()} are added to the
-back stack as a single transaction and the BACK key will reverse them all together.</p>
+back stack as a single transaction and the <em>Back</em> button will reverse them all together.</p>
<p>The order in which you add changes to a {@link android.app.FragmentTransaction} doesn't matter,
except:</p>
@@ -696,7 +696,7 @@
<p>The most significant difference in lifecycle between an activity and a fragment is how one is
stored in its respective back stack. An activity is placed into a back stack of activities
that's managed by the system when it's stopped, by default (so that the user can navigate back
-to it with the BACK key, as discussed in <a
+to it with the <em>Back</em> button, as discussed in <a
href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back Stack</a>).
However, a fragment is placed into a back stack managed by the host activity only when you
explicitly request that the instance be saved by calling {@link
diff --git a/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd b/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd
index 086ba71..465cf54 100644
--- a/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd
+++ b/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd
@@ -74,7 +74,7 @@
suppose you have a two-pane layout using fragments, one of which is a list view (fragment A) and the
other being a layout to display an item from the list (fragment B). When the user selects an item
from the list, fragment B is replaced by a new fragment (fragment C). In this case, it might be
-desireable for the user to navigate back to reveal fragment B, using the BACK button.</p>
+desireable for the user to navigate back to reveal fragment B, using the <em>Back</em> button.</p>
<p>In order to add fragment B to the back stack so that this is possible, you must call {@link
android.app.FragmentTransaction#addToBackStack addToBackStack()} before you {@link
android.app.FragmentTransaction#commit()} the transaction that replaces fragment B with fragment
@@ -94,22 +94,26 @@
<p>When the current activity starts another, the new activity is pushed on the top of the stack and
takes focus. The previous activity remains in the stack, but is stopped. When an activity
-stops, the system retains the current state of its user interface. When the user presses the BACK
+stops, the system retains the current state of its user interface. When the user presses the
+<em>Back</em>
button, the current activity is popped from the top of the stack (the activity is destroyed) and the
previous activity resumes (the previous state of its UI is restored). Activities in the stack are
never rearranged, only pushed and popped from the stack—pushed onto the stack when started by
-the current activity and popped off when the user leaves it using the BACK button. As such, the back
+the current activity and popped off when the user leaves it using the <em>Back</em> button. As such,
+the back
stack operates as a "last in, first out" object structure. Figure 1 visualizes
this behavior with a timeline showing the progress between activities along with the current back
stack at each point in time.</p>
<img src="{@docRoot}images/fundamentals/diagram_backstack.png" alt="" />
<p class="img-caption"><strong>Figure 1.</strong> A representation of how each new activity in a
-task adds an item to the back stack. When the user presses the BACK button, the current activity is
+task adds an item to the back stack. When the user presses the <em>Back</em> button, the current
+activity is
destroyed and the previous activity resumes.</p>
-<p>If the user continues to press BACK, then each activity in the stack is popped off to reveal the
+<p>If the user continues to press <em>Back</em>, then each activity in the stack is popped off to
+reveal the
previous one, until the user returns to the Home screen (or to whichever activity was running when
the task began). When all activities are removed from the stack, the task no longer exists.</p>
@@ -124,11 +128,13 @@
</div>
<p>A task is a cohesive unit that can move to the "background" when users begin a new task or go
-to the Home screen, via the HOME button. While in the background, all the activities in the task are
+to the Home screen, via the <em>Home</em> button. While in the background, all the activities in the
+task are
stopped, but the back stack for the task remains intact—the task has simply lost focus while
another task takes place, as shown in figure 2. A task can then return to the "foreground" so users
can pick up where they left off. Suppose, for example, that the current task (Task A) has three
-activities in its stack—two under the current activity. The user presses the HOME button, then
+activities in its stack—two under the current activity. The user presses the <em>Home</em>
+button, then
starts a new application from the application launcher. When the Home screen appears, Task A goes
into the background. When the new application starts, the system starts a task for that application
(Task B) with its own stack of activities. After interacting with
@@ -137,7 +143,8 @@
foreground—all three activities in its stack are intact and the activity at the top of the
stack resumes. At
this point, the user can also switch back to Task B by going Home and selecting the application icon
-that started that task (or by touching and holding the HOME button to reveal recent tasks and selecting
+that started that task (or by touching and holding the <em>Home</em> button to reveal recent tasks
+and selecting
one). This is an example of multitasking on Android.</p>
<p class="note"><strong>Note:</strong> Multiple tasks can be held in the background at once.
@@ -150,7 +157,8 @@
that activity is created and popped onto the stack (rather than bringing any previous instance of
the activity to the top). As such, one activity in your application might be instantiated multiple
times (even from different tasks), as shown in figure 3. As such, if the user navigates backward
-using the BACK button, each instance of the activity is revealed in the order they were opened (each
+using the <em>Back</em> button, each instance of the activity is revealed in the order they were
+opened (each
with their own UI state). However, you can modify this behavior if you do not want an activity to be
instantiated more than once. How to do so is discussed in the later section about <a
href="#ManagingTasks">Managing Tasks</a>.</p>
@@ -161,13 +169,15 @@
<ul>
<li>When Activity A starts Activity B, Activity A is stopped, but the system retains its state
(such as scroll position and text entered into forms).
-If the user presses the BACK button while in Activity B, Activity A resumes with its state
+If the user presses the <em>Back</em> button while in Activity B, Activity A resumes with its state
restored.</li>
- <li>When the user leaves a task by pressing the HOME button, the current activity is stopped and
+ <li>When the user leaves a task by pressing the <em>Home</em> button, the current activity is
+stopped and
its task goes into the background. The system retains the state of every activity in the task. If
the user later resumes the task by selecting the launcher icon that began the task, the task comes
to the foreground and resumes the activity at the top of the stack.</li>
- <li>If the user presses the BACK button, the current activity is popped from the stack and
+ <li>If the user presses the <em>Back</em> button, the current activity is popped from the stack
+and
destroyed. The previous activity in the stack is resumed. When an activity is destroyed, the system
<em>does not</em> retain the activity's state.</li>
<li>Activities can be instantiated multiple times, even from other tasks.</li>
@@ -256,7 +266,8 @@
<p class="caution"><strong>Caution:</strong> Most applications should not interrupt the default
behavior for activities and tasks. If you determine that it's necessary for your activity to modify
the default behaviors, use caution and be sure to test the usability of the activity during
-launch and when navigating back to it from other activities and tasks with the BACK button. Be sure
+launch and when navigating back to it from other activities and tasks with the <em>Back</em> button.
+Be sure
to test for navigation behaviors that might conflict with the user's expected behavior.</p>
@@ -320,8 +331,10 @@
stack remains A-B-C-D. However, if an intent arrives for an activity of type B, then a new
instance of B is added to the stack, even if its launch mode is {@code "singleTop"}.</p>
<p class="note"><strong>Note:</strong> When a new instance of an activity is created,
-the user can press the BACK button to return to the previous activity. But when an existing instance of
-an activity handles a new intent, the user cannot press the BACK button to return to the state of
+the user can press the <em>Back</em> button to return to the previous activity. But when an existing
+instance of
+an activity handles a new intent, the user cannot press the <em>Back</em> button to return to the
+state of
the activity before the new intent arrived in {@link android.app.Activity#onNewIntent
onNewIntent()}.</p>
</dd>
@@ -333,7 +346,7 @@
android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a new instance. Only
one instance of the activity can exist at a time.
<p class="note"><strong>Note:</strong> Although the activity starts in a new task, the
-BACK button still returns the user to the previous activity.</p></dd>
+<em>Back</em> button still returns the user to the previous activity.</p></dd>
<dt>{@code "singleInstance"}.</dt>
<dd>Same as {@code "singleTask"}, except that the system doesn't launch any other activities into
the task holding the instance. The activity is always the single and only member of its task;
@@ -351,7 +364,7 @@
intent.</p>
<p>Regardless of whether an activity starts in a new task or in the same task as the activity that
-started it, the BACK button always takes the user to the previous activity. However, if you
+started it, the <em>Back</em> button always takes the user to the previous activity. However, if you
start an activity that specifies the {@code singleTask} launch mode, then if an instance of
that activity exists in a background task, that whole task is brought to the foreground. At this
point, the back stack now includes all activities from the task brought forward, at the top of the
@@ -454,7 +467,8 @@
However, it doesn't have to be. If there's already an existing task with the same affinity as the
new activity, the activity is launched into that task. If not, it begins a new task.</p>
-<p>If this flag causes an activity to begin a new task and the user presses the HOME button to leave
+<p>If this flag causes an activity to begin a new task and the user presses the <em>Home</em> button
+to leave
it, there must be some way for the user to navigate back to the task. Some entities (such as the
notification manager) always start activities in an external task, never as part of their own, so
they always put {@code FLAG_ACTIVITY_NEW_TASK} in the intents they pass to {@link
@@ -556,7 +570,8 @@
and a {@link android.content.Intent#CATEGORY_LAUNCHER}
filter. Imagine, for example, what could happen if the filter is missing: An intent launches a
{@code "singleTask"} activity, initiating a new task, and the user spends some time working in
-that task. The user then presses the HOME button. The task is now sent to the background and is
+that task. The user then presses the <em>Home</em> button. The task is now sent to the background
+and is
not visible. Now the user has no way to return to the task, because it is not represented in the
application launcher.
</p>
diff --git a/docs/html/guide/topics/intents/intents-filters.jd b/docs/html/guide/topics/intents/intents-filters.jd
index 3f94553..3ad3c93 100644
--- a/docs/html/guide/topics/intents/intents-filters.jd
+++ b/docs/html/guide/topics/intents/intents-filters.jd
@@ -247,7 +247,7 @@
</tr><tr>
<td>{@code CATEGORY_HOME}
<td>The activity displays the home screen, the first screen the user sees when
- the device is turned on or when the HOME key is pressed.
+ the device is turned on or when the <em>Home</em> button is pressed.
</tr><tr>
<td>{@code CATEGORY_LAUNCHER}
<td>The activity can be the initial activity of a task and is listed in
diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd
index e76a6be..4d9603f 100644
--- a/docs/html/guide/topics/manifest/activity-element.jd
+++ b/docs/html/guide/topics/manifest/activity-element.jd
@@ -133,21 +133,21 @@
it's ignored for all other activities in the task.
<p>
-When the value is "{@code true}", every time users start the task again, they
-are brought to its root activity, regardless of what they were last doing in
-the task and regardless of whether they used BACK or HOME to last leave it.
-When the value is "{@code false}", the task may be cleared of activities in
+When the value is "{@code true}", every time users start the task again, they
+are brought to its root activity regardless of what they were last doing in
+the task and regardless of whether they used the <em>Back</em> or <em>Home</em> button to
+leave it. When the value is "{@code false}", the task may be cleared of activities in
some situations (see the
<code><a href="#always">alwaysRetainTaskState</a></code> attribute), but not always.
</p>
<p>
Suppose, for example, that someone launches activity P from the home screen,
-and from there goes to activity Q. The user next presses HOME, and then returns
+and from there goes to activity Q. The user next presses <em>Home</em>, and then returns
to activity P. Normally, the user would see activity Q, since that is what they
were last doing in P's task. However, if P set this flag to "{@code true}", all
of the activities on top of it (Q in this case) were removed when the user pressed
-HOME and the task went to the background. So the user sees only P when returning
+<em>Home</em> and the task went to the background. So the user sees only P when returning
to the task.
</p>
@@ -501,7 +501,7 @@
<p>Regardless of the launch mode that you choose, make sure to test the usability
of the activity during launch and when navigating back to it from
-other activities and tasks using the BACK key. </p>
+other activities and tasks using the <em>Back</em> button. </p>
<p>For more information on launch modes and their interaction with Intent
flags, see the
diff --git a/docs/html/guide/topics/search/search-dialog.jd b/docs/html/guide/topics/search/search-dialog.jd
index e06563d..8b8e75b 100644
--- a/docs/html/guide/topics/search/search-dialog.jd
+++ b/docs/html/guide/topics/search/search-dialog.jd
@@ -544,7 +544,8 @@
}
</pre>
-<p>If the user cancels search by pressing the BACK button, the search dialog closes and the activity
+<p>If the user cancels search by pressing the <em>Back</em> button, the search dialog closes and the
+activity
regains input focus. You can register to be notified when the search dialog is
closed with {@link android.app.SearchManager#setOnDismissListener(SearchManager.OnDismissListener)
setOnDismissListener()}
@@ -569,7 +570,8 @@
android.content.Intent#ACTION_SEARCH} intent with a call to {@link
android.app.Activity#onCreate(Bundle) onCreate()} and a new instance of the
activity is brought to the top of the activity stack. There are now two instances of your
-searchable activity in the activity stack (so pressing the BACK button goes back to the previous
+searchable activity in the activity stack (so pressing the <em>Back</em> button goes back to the
+previous
instance of the searchable activity, rather than exiting the searchable activity).</li>
<li>If you set {@code android:launchMode} to <code>"singleTop"</code>, then the
searchable activity receives the {@link android.content.Intent#ACTION_SEARCH} intent with a call
diff --git a/docs/html/guide/topics/ui/actionbar.jd b/docs/html/guide/topics/ui/actionbar.jd
index b83bde7..e59fa0f 100644
--- a/docs/html/guide/topics/ui/actionbar.jd
+++ b/docs/html/guide/topics/ui/actionbar.jd
@@ -113,9 +113,10 @@
href="{@docRoot}guide/topics/ui/menus.html#OptionsMenu">options menu</a> directly in the action bar,
as "action items." Action items can also provide an "action view," which provides an embedded
widget for even more immediate action behaviors. Menu items that are not promoted
-to an action item are available in the overflow menu, revealed by either the device MENU button
+to an action item are available in the overflow menu, revealed by either the device <em>Menu</em>
+button
(when available) or by an "overflow menu" button in the action bar (when the device does not
-include a MENU button).</p>
+include a <em>Menu</em> button).</p>
</li>
</ul>
@@ -125,6 +126,10 @@
landscape handset), showing the logo on the left, navigation tabs, and an action item on the
right (plus the overflow menu button).</p>
+<p class="note"><strong>Note:</strong> If you're looking for information about the contextual
+action bar for displaying contextual action items, see the <a
+href="{@docRoot}guide/topics/ui/menus.html#context-menu">Menu</a> guide.</p>
+
<div class="design-announce">
<p><strong>Action Bar Design</strong></p>
@@ -225,9 +230,10 @@
href="{@docRoot}guide/topics/ui/menus.html#OptionsMenu">options menu</a>. To do this, you can
declare that the menu item should appear in the action bar as an "action item." An action item can
include an icon and/or a text title. If a menu item does not appear as an action item, then the
-system places it in the overflow menu. The overflow menu is revealed either by the device MENU
+system places it in the overflow menu. The overflow menu is revealed either by the device
+<em>Menu</em>
button (if provided by the device) or an additional button in the action bar (if the device does not
-provide the MENU button).</p>
+provide the <em>Menu</em> button).</p>
<div class="figure" style="width:359px">
<img src="{@docRoot}images/ui/actionbar-item-withtext.png" height="57" alt="" />
@@ -1421,7 +1427,7 @@
</style>
<!-- style for the action bar tab text -->
- <style name="CustomTabTextStyle">
+ <style name="CustomTabTextStyle" parent="@android:style/TextAppearance.Holo">
<item name="android:textColor">#2456c2</item>
</style>
</resources>
@@ -1437,8 +1443,7 @@
manifest file like this:</p>
<pre>
-<application android:theme="@style/CustomActivityTheme"
- ... />
+<application android:theme="@style/CustomActivityTheme" ... />
</pre>
<p>For more information about using style and theme resources in your application, read <a
@@ -1457,7 +1462,7 @@
parent action bar style such as {@link android.R.style#Widget_Holo_ActionBar
Widget.Holo.ActionBar}.</p>
-<p>For example, if you want to change the action bar's background, you could use the following
+<p>For example, if you want to change the action bar's background, you can use the following
styles:</p>
<pre>
@@ -1465,14 +1470,15 @@
<resources>
<!-- the theme applied to the application or activity -->
<style name="CustomActivityTheme" parent="@android:style/Theme.Holo">
- <item name="android:actionBarTabTextStyle">@style/customTabTextStyle</item>
+ <item name="android:actionBarStyle">@style/MyActionBar</item>
<!-- other activity and action bar styles here -->
</style>
- <!-- style for the action bar, simply to change the background -->
- <style parent="@android:style/Widget.Holo.ActionBar">
+ <!-- style for the action bar backgrounds -->
+ <style name="MyActionBar" parent="@android:style/Widget.Holo.ActionBar">
<item name="android:background">@drawable/ab_background</item>
- <item name="android:backgroundSplit">@drawable/ab_background</item>
+ <item name="android:backgroundStacked">@drawable/ab_background</item>
+ <item name="android:backgroundSplit">@drawable/ab_split_background</item>
</style>
</resources>
</pre>
diff --git a/docs/html/guide/topics/ui/index.jd b/docs/html/guide/topics/ui/index.jd
index d3060c5..83c8150 100644
--- a/docs/html/guide/topics/ui/index.jd
+++ b/docs/html/guide/topics/ui/index.jd
@@ -174,7 +174,8 @@
<p>Application menus are another important part of an application's UI. Menus offers a reliable interface that reveals
application functions and settings. The most common application menu is revealed by pressing
-the MENU key on the device. However, you can also add Context Menus, which may be revealed when the user presses
+the <em>Menu</em> button on the device. However, you can also add Context Menus, which may be
+revealed when the user presses
and holds down on an item.</p>
<p>Menus are also structured using a View hierarchy, but you don't define this structure yourself. Instead,
diff --git a/docs/html/guide/topics/ui/menus.jd b/docs/html/guide/topics/ui/menus.jd
index 7b5b3dc..a2313b3 100644
--- a/docs/html/guide/topics/ui/menus.jd
+++ b/docs/html/guide/topics/ui/menus.jd
@@ -6,77 +6,129 @@
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
- <ol>
- <li><a href="#xml">Creating a Menu Resource</a></li>
- <li><a href="#Inflating">Inflating a Menu Resource</a>
- <li><a href="#options-menu">Creating an Options Menu</a>
- <ol>
- <li><a href="#ChangingTheMenu">Changing menu items at runtime</a></li>
- </ol>
- </li>
- <li><a href="#context-menu">Creating a Context Menu</a></li>
- <li><a href="#submenu">Creating a Submenu</a></li>
- <li><a href="#features">Other Menu Features</a>
- <ol>
- <li><a href="#groups">Menu groups</a></li>
- <li><a href="#checkable">Checkable menu items</a></li>
- <li><a href="#shortcuts">Shortcut keys</a></li>
- <li><a href="#intents">Dynamically adding menu intents</a></li>
- </ol>
- </li>
- </ol>
+<ol>
+ <li><a href="#xml">Defining a Menu in XML</a></li>
+ <li><a href="#options-menu">Creating an Options Menu</a>
+ <ol>
+ <li><a href="#RespondingOptionsMenu">Handling click events</a></li>
+ <li><a href="#ChangingTheMenu">Changing menu items at runtime</a></li>
+ </ol>
+ </li>
+ <li><a href="#context-menu">Creating Contextual Menus</a>
+ <ol>
+ <li><a href="#FloatingContextMenu">Creating a floating context menu</a></li>
+ <li><a href="#CAB">Using the contextual action bar</a></li>
+ </ol>
+ </li>
+ <li><a href="#PopupMenu">Creating a Popup Menu</a>
+ <ol>
+ <li><a href="#PopupEvents">Handling click events</a></li>
+ </ol>
+ </li>
+ <li><a href="#groups">Creating Menu Groups</a>
+ <ol>
+ <li><a href="#checkable">Using checkable menu items</a></li>
+ </ol>
+ </li>
+ <li><a href="#intents">Adding Menu Items Based on an Intent</a>
+ <ol>
+ <li><a href="#AllowingToAdd">Allowing your activity to be added to other menus</a></li>
+ </ol>
+ </li>
+</ol>
<h2>Key classes</h2>
<ol>
<li>{@link android.view.Menu}</li>
<li>{@link android.view.MenuItem}</li>
<li>{@link android.view.ContextMenu}</li>
- <li>{@link android.view.SubMenu}</li>
+ <li>{@link android.view.ActionMode}</li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a></li>
<li><a href="{@docRoot}guide/topics/resources/menu-resource.html">Menu Resource</a></li>
+ <li><a
+href="http://android-developers.blogspot.com/2012/01/say-goodbye-to-menu-button.html">Say
+Goodbye to the Menu Button</a></li>
</ol>
</div>
</div>
-<p>Menus are an important part of an activity's user interface, which provide users a familiar
-way to perform actions. Android offers a simple framework for you to add standard
-menus to your application.</p>
+<p>Menus are a common user interface component in many types of applications. To provide a familiar
+and consistent user experience, you should use the {@link android.view.Menu} APIs to present user
+actions and other options in your activities.</p>
-<p>There are three types of application menus:</p>
+<p>Beginning with Android 3.0 (API level 11), Android-powered devices are no longer required to
+provide a dedicated <em>Menu</em> button. With this change, Android apps should migrate away from a
+dependence on the traditional 6-item menu panel and instead provide an action bar to present common
+user actions.</p>
+
+<p>Although the design and user experience for some menu items have changed, the semantics to define
+a set of actions and options is still based on the {@link android.view.Menu} APIs. This
+guide shows how to create the three fundamental types of menus or action presentations on all
+versions of Android:</p>
+
<dl>
- <dt><strong>Options Menu</strong></dt>
- <dd>The primary collection of menu items for an activity, which appears when the user touches
-the MENU button. When your application is running on Android 3.0 or later, you can provide
-quick access to select menu items by placing them directly in the <a
-href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>, as "action items."</dd>
- <dt><strong>Context Menu</strong></dt>
- <dd>A floating list of menu items that appears when the user touches and holds a view
-that's registered to provide a context menu.
+ <dt><strong>Options menu and action bar</strong></dt>
+ <dd>The <a href="#options-menu">options menu</a> is the primary collection of menu items for an
+activity. It's where you should place actions that have a global impact on the app, such as
+"Search," "Compose email," and "Settings."
+ <p>If you're developing for Android 2.3 or lower, users can
+reveal the options menu panel by pressing the <em>Menu</em> button.</p>
+ <p>On Android 3.0 and higher, items from the options menu are presented by the <a
+href="{@docRoot}guide/topics/ui/actionbar.html">action bar</a> as a combination of on-screen action
+items and overflow options. Beginning with Android 3.0, the <em>Menu</em> button is deprecated (some
+devices
+don't have one), so you should migrate toward using the action bar to provide access to actions and
+other options.</p>
+ <p>See the section about <a href="#options-menu">Creating an Options Menu</a>.</p>
+ </dd>
+
+ <dt><strong>Context menu and contextual action mode</strong></dt>
+
+ <dd>A context menu is a <a href="#FloatingContextMenu">floating menu</a> that appears when the
+user performs a long-click on an element. It provides actions that affect the selected content or
+context frame.
+ <p>When developing for Android 3.0 and higher, you should instead use the <a
+href="#CAB">contextual action mode</a> to enable actions on selected content. This mode displays
+action items that affect the selected content in a bar at the top of the screen and allows the user
+to select multiple items.</p>
+ <p>See the section about <a href="#context-menu">Creating Contextual Menus</a>.</p>
</dd>
- <dt><strong>Submenu</strong></dt>
- <dd>A floating list of menu items that appears when the user touches a menu item that contains
-a nested menu.</dd>
+
+ <dt><strong>Popup menu</strong></dt>
+ <dd>A popup menu displays a list of items in a vertical list that's anchored to the view that
+invoked the menu. It's good for providing an overflow of actions that relate to specific content or
+to provide options for a second part of a command. Actions in a popup menu should
+<strong>not</strong> directly affect the corresponding content—that's what contextual actions
+are for. Rather, the popup menu is for extended actions that relate to regions of content in your
+activity.
+ <p>See the section about <a href="#PopupMenu">Creating a Popup Menu</a>.</p>
+</dd>
</dl>
-<p>This document shows you how to create each type of menu, using XML to define the content of
-the menu and callback methods in your activity to respond when the user selects an item.</p>
+<h2 id="xml">Defining a Menu in XML</h2>
-<h2 id="xml">Creating a Menu Resource</h2>
+<p>For all menu types, Android provides a standard XML format to define menu items.
+Instead of building a menu in your activity's code, you should define a menu and all its items in an
+XML <a href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. You can then
+inflate the menu resource (load it as a {@link android.view.Menu} object) in your activity or
+fragment.</p>
-<p>Instead of instantiating a {@link android.view.Menu} in your application code, you should
-define a menu and all its items in an XML <a
-href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>, then inflate the menu
-resource (load it as a programmable object) in your application code. Using a menu resource to
-define your menu is a good practice because it separates the content for the menu from your
-application code. It's also easier to visualize the structure and content of a menu in XML.</p>
+<p>Using a menu resource is a good practice for a few reasons:</p>
+<ul>
+ <li>It's easier to visualize the menu structure in XML.</li>
+ <li>It separates the content for the menu from your application's behavioral code.</li>
+ <li>It allows you to create alternative menu configurations for different platform versions,
+screen sizes, and other configurations by leveraging the <a
+href="{@docRoot}guide/topics/resources/index.html">app resources</a> framework.</li>
+</ul>
-<p>To create a menu resource, create an XML file inside your project's <code>res/menu/</code>
+<p>To define the menu, create an XML file inside your project's <code>res/menu/</code>
directory and build the menu with the following elements:</p>
<dl>
<dt><code><menu></code></dt>
@@ -90,8 +142,8 @@
<dt><code><group></code></dt>
<dd>An optional, invisible container for {@code <item>} elements. It allows you to
-categorize menu items so they share properties such as active state and visibility. See the
-section about <a href="#groups">Menu groups</a>.</dd>
+categorize menu items so they share properties such as active state and visibility. For more
+information, see the section about <a href="#groups">Creating Menu Groups</a>.</dd>
</dl>
@@ -101,14 +153,17 @@
<menu xmlns:android="http://schemas.android.com/apk/res/android">
<item android:id="@+id/new_game"
android:icon="@drawable/ic_new_game"
- android:title="@string/new_game" />
+ android:title="@string/new_game"
+ android:showAsAction="ifRoom"/>
<item android:id="@+id/help"
android:icon="@drawable/ic_help"
android:title="@string/help" />
</menu>
</pre>
-<p>This example defines a menu with two items. Each item includes the attributes:</p>
+<p>The <code><item></code> element supports several attributes you can use to define an item's
+appearance and behavior. The items in the above menu include the following attributes:</p>
+
<dl>
<dt>{@code android:id}</dt>
<dd>A resource ID that's unique to the item, which allows the application can recognize the item
@@ -117,312 +172,24 @@
<dd>A reference to a drawable to use as the item's icon.</dd>
<dt>{@code android:title}</dt>
<dd>A reference to a string to use as the item's title.</dd>
+ <dt>{@code android:showAsAction}</dt>
+ <dd>Specifies when and how this item should appear as an action item in the <a
+href="{@docRoot}guide/topics/ui/actionbar.html">action bar</a>.</dd>
</dl>
-<p>There are many more attributes you can include in an {@code <item>}, including some that
- specify how the item may appear in the <a
-href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>. For more information about the XML
-syntax and attributes for a menu resource, see the <a
-href="{@docRoot}guide/topics/resources/menu-resource.html">Menu Resource</a> reference.</p>
+<p>These are the most important attributes you should use, but there are many more available.
+For information about all the supported attributes, see the <a
+href="{@docRoot}guide/topics/resources/menu-resource.html">Menu Resource</a> document.</p>
-
-
-<h2 id="Inflating">Inflating a Menu Resource</h2>
-
-<p>From your application code, you can inflate a menu resource (convert the XML resource into a
-programmable object) using
-{@link android.view.MenuInflater#inflate(int,Menu) MenuInflater.inflate()}. For
-example, the following code inflates the <code>game_menu.xml</code> file defined above, during the
-{@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} callback method, to
-use the menu as the activity's Options Menu:</p>
-
-<pre>
-@Override
-public boolean onCreateOptionsMenu(Menu menu) {
- MenuInflater inflater = getMenuInflater();
- inflater.inflate(R.menu.game_menu, menu);
- return true;
-}
-</pre>
-
-<p>The {@link android.app.Activity#getMenuInflater()} method returns a {@link
-android.view.MenuInflater} for the activity. With this object, you can call {@link
-android.view.MenuInflater#inflate(int,Menu) inflate()}, which inflates a menu resource into a
-{@link android.view.Menu} object. In this example, the menu resource defined by
-<code>game_menu.xml</code>
-is inflated into the {@link android.view.Menu} that was passed into {@link
-android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()}. (This callback method for
-the Options Menu is discussed more in the next section.)</p>
-
-
-
-<h2 id="options-menu">Creating an Options Menu</h2>
-
-<div class="figure" style="width:200px">
- <img src="{@docRoot}images/options_menu.png" height="333" alt="" />
- <p class="img-caption"><strong>Figure 1.</strong> Screenshot of the Options Menu in the
-Browser.</p>
-</div>
-
-<p>The Options Menu is where you should include basic activity actions and necessary navigation
-items (for example, a button to open the application settings). Items in the Options Menu are
-accessible in two distinct ways: the MENU button or in the <a
-href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> (on devices running Android 3.0
-or higher).</p>
-
-<p>When running on a device with Android 2.3 and lower, the Options Menu appears at the bottom of
-the screen, as shown in figure 1. When opened, the first visible portion of the Options Menu is
-the icon menu. It holds the first six menu items. If you add more than six items to the
-Options Menu, Android places the sixth item and those after it into the overflow menu, which the
-user can open by touching the "More" menu item.</p>
-
-<p>On Android 3.0 and higher, items from the Options Menu is placed in the Action Bar, which appears
-at the top of the activity in place of the traditional title bar. By default all items from the
-Options Menu are placed in the overflow menu, which the user can open by touching the menu icon
-on the right side of the Action Bar. However, you can place select menu items directly in the
-Action Bar as "action items," for instant access, as shown in figure 2.</p>
-
-<p>When the Android system creates the Options Menu for the first time, it calls your
-activity's {@link android.app.Activity#onCreateOptionsMenu(Menu)
-onCreateOptionsMenu()} method. Override this method in your activity
-and populate the {@link android.view.Menu} that is passed into the method,
-{@link android.view.Menu} by inflating a menu resource as described above in <a
-href="#Inflating">Inflating a Menu Resource</a>. For example:</p>
-
-<pre>
-@Override
-public boolean onCreateOptionsMenu(Menu menu) {
- MenuInflater inflater = getMenuInflater();
- inflater.inflate(R.menu.game_menu, menu);
- return true;
-}
-</pre>
-
-<div class="figure" style="width:450px">
-<img src="{@docRoot}images/ui/actionbar.png" alt="" />
-<p class="img-caption"><strong>Figure 2.</strong> Action bar from the <a
-href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a> app, including
-navigation tabs and a camera action item (plus the overflow menu button).</p>
-</div>
-
-<p>You can also populate the menu in code, using {@link android.view.Menu#add(int,int,int,int)
-add()} to add items to the {@link android.view.Menu}.</p>
-
-<p class="note"><strong>Note:</strong> On Android 2.3 and lower, the system calls {@link
-android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} to create the Options Menu
-when the user opens it for the first time, but on Android 3.0 and greater, the system creates it as
-soon as the activity is created, in order to populate the Action Bar.</p>
-
-
-<h3 id="RespondingOptionsMenu">Responding to user action</h3>
-
-<p>When the user selects a menu item from the Options Menu (including action items in the
-Action Bar), the system calls your activity's
-{@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}
-method. This method passes the
-{@link android.view.MenuItem} that the user selected. You can identify the menu item by calling
-{@link android.view.MenuItem#getItemId()}, which returns the unique ID for the menu
-item (defined by the {@code android:id} attribute in the menu resource or with an integer
-given to the {@link android.view.Menu#add(int,int,int,int) add()} method). You can match this ID
-against known menu items and perform the appropriate action. For example:</p>
-
-<pre>
-@Override
-public boolean onOptionsItemSelected(MenuItem item) {
- // Handle item selection
- switch (item.getItemId()) {
- case R.id.new_game:
- newGame();
- return true;
- case R.id.help:
- showHelp();
- return true;
- default:
- return super.onOptionsItemSelected(item);
- }
-}
-</pre>
-
-<p>In this example, {@link android.view.MenuItem#getItemId()} queries the ID for the selected menu
-item and the switch statement compares the ID against the resource IDs that were assigned to menu
-items in the XML resource. When a switch case successfully handles the menu item, it
-returns {@code true} to indicate that the item selection was handled. Otherwise, the default
-statement passes the menu item to the super class, in
-case it can handle the item selected. (If you've directly extended the {@link android.app.Activity}
-class, then the super class returns {@code false}, but it's a good practice to
-pass unhandled menu items to the super class instead of directly returning {@code false}.)</p>
-
-<p>Additionally, Android 3.0 adds the ability for you to define the on-click behavior for a menu
-item in the <a href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a> XML,
-using the {@code android:onClick} attribute. So you don't need to implement {@link
-android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}. Using the {@code
-android:onClick} attribute, you can specify a method to call when the user selects the menu item.
-Your activity must then implement the method specified in the {@code android:onClick} attribute so
-that it accepts a single {@link android.view.MenuItem} parameter—when the system calls this
-method, it passes the menu item selected.</p>
-
-<p class="note"><strong>Tip:</strong> If your application contains multiple activities and
-some of them provide the same Options Menu, consider creating
-an activity that implements nothing except the {@link android.app.Activity#onCreateOptionsMenu(Menu)
-onCreateOptionsMenu()} and {@link android.app.Activity#onOptionsItemSelected(MenuItem)
-onOptionsItemSelected()} methods. Then extend this class for each activity that should share the
-same Options Menu. This way, you have to manage only one set of code for handling menu
-actions and each descendant class inherits the menu behaviors.<br/><br/>
-If you want to add menu items to one of your descendant activities,
-override {@link android.app.Activity#onCreateOptionsMenu(Menu)
-onCreateOptionsMenu()} in that activity. Call {@code super.onCreateOptionsMenu(menu)} so the
-original menu items are created, then add new menu items with {@link
-android.view.Menu#add(int,int,int,int) menu.add()}. You can also override the super class's
-behavior for individual menu items.</p>
-
-
-<h3 id="ChangingTheMenu">Changing menu items at runtime</h3>
-
-<p>Once the activity is created, the {@link android.app.Activity#onCreateOptionsMenu(Menu)
-onCreateOptionsMenu()} method is
-called only once, as described above. The system keeps and re-uses the {@link
-android.view.Menu} you define in this method until your activity is destroyed. If you want to change
-the Options Menu any time after it's first created, you must override the
-{@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()} method. This passes
-you the {@link android.view.Menu} object as it currently exists. This is useful if you'd like to
-remove, add, disable, or enable menu items depending on the current state of your application.</p>
-
-<p>On Android 2.3 and lower, the system calls {@link android.app.Activity#onPrepareOptionsMenu(Menu)
-onPrepareOptionsMenu()} each time the user opens the Options Menu.</p>
-
-<p>On Android 3.0 and higher, you must call {@link android.app.Activity#invalidateOptionsMenu
-invalidateOptionsMenu()} when you want to update the menu, because the menu is always open. The
-system will then call {@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()}
-so you can update the menu items.</p>
-
-<p class="note"><strong>Note:</strong>
-You should never change items in the Options Menu based on the {@link android.view.View} currently
-in focus. When in touch mode (when the user is not using a trackball or d-pad), views
-cannot take focus, so you should never use focus as the basis for modifying
-items in the Options Menu. If you want to provide menu items that are context-sensitive to a {@link
-android.view.View}, use a <a href="#context-menu">Context Menu</a>.</p>
-
-<p>If you're developing for Android 3.0 or higher, be sure to also read the <a
-href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guide.</p>
-
-
-
-
-<h2 id="context-menu">Creating a Context Menu</h2>
-
-<p>A context menu is conceptually similar to the menu displayed when the user performs a
-"right-click" on a PC. You should use a context menu to provide the user access to
-actions that pertain to a specific item in the user interface. On Android, a context menu is
-displayed when the user performs a "long press" (press and hold) on an item.</p>
-
-<p>You can create a context menu for any View, though context menus are most often used for items in
-a {@link android.widget.ListView}. When the user performs a long-press on an item in a ListView and
-the list is registered to provide a context menu, the list item signals to the user that a context
-menu is available by animating its background color—it transitions from
-orange to white before opening the context menu. (The Contacts application demonstrates this
-feature.)</p>
-
-<div class="sidebox-wrapper">
-<div class="sidebox">
-<h3>Register a ListView</h3>
-<p>If your activity uses a {@link android.widget.ListView} and
-you want all list items to provide a context menu, register all items for a context
-menu by passing the {@link android.widget.ListView} to {@link
-android.app.Activity#registerForContextMenu(View) registerForContextMenu()}. For
-example, if you're using a {@link android.app.ListActivity}, register all list items like this:</p>
-<p><code>registerForContextMenu({@link android.app.ListActivity#getListView()});</code></p>
-</div>
-</div>
-
-<p>In order for a View to provide a context menu, you must "register" the view for a context
-menu. Call {@link android.app.Activity#registerForContextMenu(View) registerForContextMenu()} and
-pass it the {@link android.view.View} you want to give a context menu. When this View then
-receives a long-press, it displays a context menu.</p>
-
-<p>To define the context menu's appearance and behavior, override your activity's context menu
-callback methods, {@link android.app.Activity#onCreateContextMenu(ContextMenu,View,ContextMenuInfo)
-onCreateContextMenu()} and
-{@link android.app.Activity#onContextItemSelected(MenuItem) onContextItemSelected()}.</p>
-
-<p>For example, here's an {@link
-android.app.Activity#onCreateContextMenu(ContextMenu,View,ContextMenuInfo)
-onCreateContextMenu()} that uses the {@code context_menu.xml} menu resource:</p>
-<pre>
-@Override
-public void onCreateContextMenu(ContextMenu menu, View v,
- ContextMenuInfo menuInfo) {
- super.onCreateContextMenu(menu, v, menuInfo);
- MenuInflater inflater = getMenuInflater();
- inflater.inflate(R.menu.context_menu, menu);
-}
-</pre>
-
-<p>{@link android.view.MenuInflater} is used to inflate the context menu from a <a
-href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. (You can also use
-{@link android.view.Menu#add(int,int,int,int) add()} to add menu items.) The callback method
-parameters include the {@link android.view.View}
-that the user selected and a {@link android.view.ContextMenu.ContextMenuInfo} object that provides
-additional information about the item selected. You might use these parameters to determine
-which context menu should be created, but in this example, all context menus for the activity are
-the same.</p>
-
-<p>Then when the user selects an item from the context menu, the system calls {@link
-android.app.Activity#onContextItemSelected(MenuItem) onContextItemSelected()}. Here is an example
-of how you can handle selected items:</p>
-
-<pre>
-@Override
-public boolean onContextItemSelected(MenuItem item) {
- AdapterContextMenuInfo info = (AdapterContextMenuInfo) item.getMenuInfo();
- switch (item.getItemId()) {
- case R.id.edit:
- editNote(info.id);
- return true;
- case R.id.delete:
- deleteNote(info.id);
- return true;
- default:
- return super.onContextItemSelected(item);
- }
-}
-</pre>
-
-<p>The structure of this code is similar to the example for <a href="#options-menu">Creating an
-Options Menu</a>, in which {@link android.view.MenuItem#getItemId()} queries the ID for the selected
-menu item and a switch statement matches the item to the IDs that are defined in the menu resource.
-And like the options menu example, the default statement calls the super class in case it
-can handle menu items not handled here, if necessary.</p>
-
-<p>In this example, the selected item is an item from a {@link android.widget.ListView}. To
-perform an action on the selected item, the application needs to know the list
-ID for the selected item (it's position in the ListView). To get the ID, the application calls
-{@link android.view.MenuItem#getMenuInfo()}, which returns a {@link
-android.widget.AdapterView.AdapterContextMenuInfo} object that includes the list ID for the
-selected item in the {@link android.widget.AdapterView.AdapterContextMenuInfo#id id} field. The
-local methods <code>editNote()</code> and <code>deleteNote()</code> methods accept this list ID to
-perform an action on the data specified by the list ID.</p>
-
-<p class="note"><strong>Note:</strong> Items in a context menu do not support icons or shortcut
-keys.</p>
-
-
-
-<h2 id="submenu">Creating Submenus</h2>
-
-<p>A submenu is a menu that the user can open by selecting an item in another menu. You can add a
-submenu to any menu (except a submenu). Submenus are useful when your application has a lot of
-functions that can be organized into topics, like items in a PC application's menu bar (File, Edit,
-View, etc.).</p>
-
-<p>When creating your <a href="{@docRoot}guide/topics/resources/menu-resource.html">menu
-resource</a>, you can create a submenu by adding a {@code <menu>} element as the child of an
-{@code <item>}. For example:</p>
+<p>You can add a submenu to an item in any menu (except a submenu) by adding a {@code <menu>}
+element as the child of an {@code <item>}. Submenus are useful when your application has a lot
+of functions that can be organized into topics, like items in a PC application's menu bar (File,
+Edit, View, etc.). For example:</p>
<pre>
<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
<item android:id="@+id/file"
- android:icon="@drawable/file"
android:title="@string/file" >
<!-- "file" submenu -->
<menu>
@@ -435,23 +202,625 @@
</menu>
</pre>
-<p>When the user selects an item from a submenu, the parent menu's respective on-item-selected
-callback method receives the event. For instance, if the above menu is applied as an Options Menu,
-then the {@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} method
-is called when a submenu item is selected.</p>
-
-<p>You can also use {@link android.view.Menu#addSubMenu(int,int,int,int) addSubMenu()} to
-dynamically add a {@link android.view.SubMenu} to an existing {@link android.view.Menu}. This
-returns the new {@link android.view.SubMenu} object, to which you can add
-submenu items, using {@link android.view.Menu#add(int,int,int,int) add()}</p>
+<p>To use the menu in your activity, you need to inflate the menu resource (convert the XML
+resource into a programmable object) using {@link android.view.MenuInflater#inflate(int,Menu)
+MenuInflater.inflate()}. In the following sections, you'll see how to inflate a menu for each
+menu type.</p>
-<h2 id="features">Other Menu Features</h2>
+<h2 id="options-menu">Creating an Options Menu</h2>
-<p>Here are some other features that you can apply to most menu items.</p>
+<div class="figure" style="width:200px;margin:0">
+ <img src="{@docRoot}images/options_menu.png" height="333" alt="" />
+ <p class="img-caption"><strong>Figure 1.</strong> Options menu in the
+Browser, on Android 2.3.</p>
+</div>
-<h3 id="groups">Menu groups</h3>
+<p>The options menu is where you should include actions and other options that are relevant to the
+current activity context, such as "Search," "Compose email," and "Settings."</p>
+
+<p>Where the items in your options menu appear on the screen depends on the version for which you've
+developed your application:</p>
+
+<ul>
+ <li>If you've developed your application for <strong>Android 2.3.x (API level 10) or
+lower</strong>, the contents of your options menu appear at the bottom of the screen when the user
+presses the <em>Menu</em> button, as shown in figure 1. When opened, the first visible portion is
+the icon
+menu, which holds up to six menu items. If your menu includes more than six items, Android places
+the sixth item and the rest into the overflow menu, which the user can open by selecting
+<em>More</em>.</li>
+
+ <li>If you've developed your application for <strong>Android 3.0 (API level 11) and
+higher</strong>, items from the options menu are available in the <a
+href="{@docRoot}guide/topics/ui/actionbar.html">action bar</a>. By default, the system
+places all items in the action overflow, which the user can reveal with the action overflow icon on
+the right side of the action bar (or by pressing the device <em>Menu</em> button, if available). To
+enable
+quick access to important actions, you can promote a few items to appear in the action bar by adding
+{@code android:showAsAction="ifRoom"} to the corresponding {@code <item>} elements (see figure
+2). <p>For more information about action items and other action bar behaviors, see the <a
+href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> guide. </p>
+<p class="note"><strong>Note:</strong> Even if you're <em>not</em> developing for Android 3.0 or
+higher, you can build your own action bar layout for a similar effect. For an example of how you can
+support older versions of Android with an action bar, see the <a
+href="{@docRoot}resources/samples/ActionBarCompat/index.html">Action Bar Compatibility</a>
+sample.</p>
+</li>
+</ul>
+
+<img src="{@docRoot}images/ui/actionbar.png" alt="" />
+<p class="img-caption"><strong>Figure 2.</strong> Action bar from the <a
+href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a> app, showing
+navigation tabs and a camera action item (plus the action overflow button).</p>
+
+<p>You can declare items for the options menu from either your {@link android.app.Activity}
+subclass or a {@link android.app.Fragment} subclass. If both your activity and fragment(s)
+declare items for the options menu, they are combined in the UI. The activity's items appear
+first, followed by those of each fragment in the order in which each fragment is added to the
+activity. If necessary, you can re-order the menu items with the {@code android:orderInCategory}
+attribute in each {@code <item>} you need to move.</p>
+
+<p>To specify the options menu for an activity, override {@link
+android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} (fragments provide their
+own {@link android.app.Fragment#onCreateOptionsMenu onCreateOptionsMenu()} callback). In this
+method, you can inflate your menu resource (<a href="#xml">defined in XML</a>) into the {@link
+android.view.Menu} provided in the callback. For example:</p>
+
+<pre>
+@Override
+public boolean onCreateOptionsMenu(Menu menu) {
+ MenuInflater inflater = {@link android.app.Activity#getMenuInflater()};
+ inflater.inflate(R.menu.game_menu, menu);
+ return true;
+}
+</pre>
+
+<p>You can also add menu items using {@link android.view.Menu#add(int,int,int,int)
+add()} and retrieve items with {@link android.view.Menu#findItem findItem()} to revise their
+properties with {@link android.view.MenuItem} APIs.</p>
+
+<p>If you've developed your application for Android 2.3.x and lower, the system calls {@link
+android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} to create the options menu
+when the user opens the menu for the first time. If you've developed for Android 3.0 and higher, the
+system calls {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} when
+starting the activity, in order to show items to the action bar.</p>
+
+
+
+<h3 id="RespondingOptionsMenu">Handling click events</h3>
+
+<p>When the user selects an item from the options menu (including action items in the action bar),
+the system calls your activity's {@link android.app.Activity#onOptionsItemSelected(MenuItem)
+onOptionsItemSelected()} method. This method passes the {@link android.view.MenuItem} selected. You
+can identify the item by calling {@link android.view.MenuItem#getItemId()}, which returns the unique
+ID for the menu item (defined by the {@code android:id} attribute in the menu resource or with an
+integer given to the {@link android.view.Menu#add(int,int,int,int) add()} method). You can match
+this ID against known menu items to perform the appropriate action. For example:</p>
+
+<pre>
+@Override
+public boolean onOptionsItemSelected(MenuItem item) {
+ // Handle item selection
+ switch (item.getItemId()) {
+ case R.id.new_game:
+ newGame();
+ return true;
+ case R.id.help:
+ showHelp();
+ return true;
+ default:
+ return super.onOptionsItemSelected(item);
+ }
+}
+</pre>
+
+<p>When you successfully handle a menu item, return {@code true}. If you don't handle the menu
+item, you should call the superclass implementation of {@link
+android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} (the default
+implementation returns false).</p>
+
+<p>If your activity includes fragments, the system first calls {@link
+android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} for the activity then
+for each fragment (in the order each fragment was added) until one returns
+{@code true} or all fragments have been called.</p>
+
+<p class="note"><strong>Tip:</strong> Android 3.0 adds the ability for you to define the on-click
+behavior for a menu item in XML, using the {@code android:onClick} attribute. The value for the
+attribute must be the name of a method defined by the activity using the menu. The method
+must be public and accept a single {@link android.view.MenuItem} parameter—when the system
+calls this method, it passes the menu item selected. For more information and an example, see the <a
+href="{@docRoot}guide/topics/resources/menu-resource.html">Menu Resource</a> document.</p>
+
+<p class="note"><strong>Tip:</strong> If your application contains multiple activities and
+some of them provide the same options menu, consider creating
+an activity that implements nothing except the {@link android.app.Activity#onCreateOptionsMenu(Menu)
+onCreateOptionsMenu()} and {@link android.app.Activity#onOptionsItemSelected(MenuItem)
+onOptionsItemSelected()} methods. Then extend this class for each activity that should share the
+same options menu. This way, you can manage one set of code for handling menu
+actions and each descendant class inherits the menu behaviors.
+If you want to add menu items to one of the descendant activities,
+override {@link android.app.Activity#onCreateOptionsMenu(Menu)
+onCreateOptionsMenu()} in that activity. Call {@code super.onCreateOptionsMenu(menu)} so the
+original menu items are created, then add new menu items with {@link
+android.view.Menu#add(int,int,int,int) menu.add()}. You can also override the super class's
+behavior for individual menu items.</p>
+
+
+<h3 id="ChangingTheMenu">Changing menu items at runtime</h3>
+
+<p>After the system calls {@link android.app.Activity#onCreateOptionsMenu(Menu)
+onCreateOptionsMenu()}, it retains an instance of the {@link android.view.Menu} you populate and
+will not call {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()}
+again unless the menu is invalidated for some reason. However, you should use {@link
+android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} only to create the initial
+menu state and not to make changes during the activity lifecycle.</p>
+
+<p>If you want to modify the options menu based on
+events that occur during the activity lifecycle, you can do so in
+the {@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()} method. This
+method passes you the {@link android.view.Menu} object as it currently exists so you can modify it,
+such as add, remove, or disable items. (Fragments also provide an {@link
+android.app.Fragment#onPrepareOptionsMenu onPrepareOptionsMenu()} callback.)</p>
+
+<p>On Android 2.3.x and lower, the system calls {@link
+android.app.Activity#onPrepareOptionsMenu(Menu)
+onPrepareOptionsMenu()} each time the user opens the options menu (presses the <em>Menu</em>
+button).</p>
+
+<p>On Android 3.0 and higher, the options menu is considered to always be open when menu items are
+presented in the action bar. When an event occurs and you want to perform a menu update, you must
+call {@link android.app.Activity#invalidateOptionsMenu invalidateOptionsMenu()} to request that the
+system call {@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()}.</p>
+
+<p class="note"><strong>Note:</strong>
+You should never change items in the options menu based on the {@link android.view.View} currently
+in focus. When in touch mode (when the user is not using a trackball or d-pad), views
+cannot take focus, so you should never use focus as the basis for modifying
+items in the options menu. If you want to provide menu items that are context-sensitive to a {@link
+android.view.View}, use a <a href="#context-menu">Context Menu</a>.</p>
+
+
+
+
+<h2 id="context-menu">Creating Contextual Menus</h2>
+
+<div class="figure" style="width:420px;margin-top:-1em">
+ <img src="{@docRoot}images/ui/menu-context.png" alt="" />
+ <p class="img-caption"><strong>Figure 3.</strong> Screenshots of a floating context menu (left)
+and the contextual action bar (right).</p>
+</div>
+
+<p>A contextual menu offers actions that affect a specific item or context frame in the UI. You
+can provide a context menu for any view, but they are most often used for items in a {@link
+android.widget.ListView}, {@link android.widget.GridView}, or other view collections in which
+the user can perform direct actions on each item.</p>
+
+<p>There are two ways to provide contextual actions:</p>
+<ul>
+ <li>In a <a href="#FloatingContextMenu">floating context menu</a>. A menu appears as a
+floating list of menu items (similar to a dialog) when the user performs a long-click (press and
+hold) on a view that declares support for a context menu. Users can perform a contextual
+action on one item at a time.</li>
+
+ <li>In the <a href="#CAB">contextual action mode</a>. This mode is a system implementation of
+{@link android.view.ActionMode} that displays a <em>contextual action bar</em> at the top of the
+screen with action items that affect the selected item(s). When this mode is active, users
+can perform an action on multiple items at once (if your app allows it).</li>
+</ul>
+
+<p class="note"><strong>Note:</strong> The contextual action mode is available on Android 3.0 (API
+level 11) and higher and is the preferred technique for displaying contextual actions when
+available. If your app supports versions lower than 3.0 then you should fall back to a floating
+context menu on those devices.</p>
+
+
+<h3 id="FloatingContextMenu">Creating a floating context menu</h3>
+
+<p>To provide a floating context menu:</p>
+<ol>
+ <li>Register the {@link android.view.View} to which the context menu should be associated by
+calling {@link android.app.Activity#registerForContextMenu(View) registerForContextMenu()} and pass
+it the {@link android.view.View}.
+ <p>If your activity uses a {@link android.widget.ListView} or {@link android.widget.GridView} and
+you want each item to provide the same context menu, register all items for a context menu by
+passing the {@link android.widget.ListView} or {@link android.widget.GridView} to {@link
+android.app.Activity#registerForContextMenu(View) registerForContextMenu()}.</p>
+</li>
+
+ <li>Implement the {@link
+android.view.View.OnCreateContextMenuListener#onCreateContextMenu onCreateContextMenu()} method
+in your {@link android.app.Activity} or {@link android.app.Fragment}.
+ <p>When the registered view receives a long-click event, the system calls your {@link
+android.view.View.OnCreateContextMenuListener#onCreateContextMenu onCreateContextMenu()}
+method. This is where you define the menu items, usually by inflating a menu resource. For
+example:</p>
+<pre>
+@Override
+public void onCreateContextMenu(ContextMenu menu, View v,
+ ContextMenuInfo menuInfo) {
+ super.onCreateContextMenu(menu, v, menuInfo);
+ MenuInflater inflater = getMenuInflater();
+ inflater.inflate(R.menu.context_menu, menu);
+}
+</pre>
+
+<p>{@link android.view.MenuInflater} allows you to inflate the context menu from a <a
+href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. The callback method
+parameters include the {@link android.view.View}
+that the user selected and a {@link android.view.ContextMenu.ContextMenuInfo} object that provides
+additional information about the item selected. If your activity has several views that each provide
+a different context menu, you might use these parameters to determine which context menu to
+inflate.</p>
+</li>
+
+<li>Implement {@link android.app.Activity#onContextItemSelected(MenuItem)
+onContextItemSelected()}.
+ <p>When the user selects a menu item, the system calls this method so you can perform the
+appropriate action. For example:</p>
+
+<pre>
+@Override
+public boolean onContextItemSelected(MenuItem item) {
+ AdapterContextMenuInfo info = (AdapterContextMenuInfo) item.getMenuInfo();
+ switch (item.getItemId()) {
+ case R.id.edit:
+ editNote(info.id);
+ return true;
+ case R.id.delete:
+ deleteNote(info.id);
+ return true;
+ default:
+ return super.onContextItemSelected(item);
+ }
+}
+</pre>
+
+<p>The {@link android.view.MenuItem#getItemId()} method queries the ID for
+the selected menu item, which you should assign to each menu item in XML using the {@code
+android:id} attribute, as shown in the section about <a href="#xml">Defining a Menu in
+XML</a>.</p>
+
+<p>When you successfully handle a menu item, return {@code true}. If you don't handle the menu item,
+you should pass the menu item to the superclass implementation. If your activity includes fragments,
+the activity receives this callback first. By calling the superclass when unhandled, the system
+passes the event to the respective callback method in each fragment, one at a time (in the order
+each fragment was added) until {@code true} or {@code false} is returned. (The default
+implementation for {@link android.app.Activity} and {@code android.app.Fragment} return {@code
+false}, so you should always call the superclass when unhandled.)</p>
+</li>
+</ol>
+
+
+<h3 id="CAB">Using the contextual action mode</h3>
+
+<p>The contextual action mode is a system implementation of {@link android.view.ActionMode} that
+focuses user interaction toward performing contextual actions. When a
+user enables this mode by selecting an item, a <em>contextual action bar</em> appears at the top of
+the screen to present actions the user can perform on the currently selected item(s). While this
+mode is enabled, the user can select multiple items (if you allow it), deselect items, and continue
+to navigate within the activity (as much as you're willing to allow). The action mode is disabled
+and the contextual action bar disappears when the user deselects all items, presses the BACK button,
+or selects the <em>Done</em> action on the left side of the bar.</p>
+
+<p class="note"><strong>Note:</strong> The contextual action bar is not necessarily
+associated with the <a href="{@docRoot}guide/topics/ui/actionbar.html">action bar</a>. They operate
+independently, even though the contextual action bar visually overtakes the action bar
+position.</p>
+
+<p>If you're developing for Android 3.0 (API level 11) or higher, you
+should usually use the contextual action mode to present contextual actions, instead of the <a
+href="#FloatingContextMenu">floating context menu</a>.</p>
+
+<p>For views that provide contextual actions, you should usually invoke the contextual action mode
+upon one of two events (or both):</p>
+<ul>
+ <li>The user performs a long-click on the view.</li>
+ <li>The user selects a checkbox or similar UI component within the view.</li>
+</ul>
+
+<p>How your application invokes the contextual action mode and defines the behavior for each
+action depends on your design. There are basically two designs:</p>
+<ul>
+ <li>For contextual actions on individual, arbitrary views.</li>
+ <li>For batch contextual actions on groups of items in a {@link
+android.widget.ListView} or {@link android.widget.GridView} (allowing the user to select multiple
+items and perform an action on them all).</li>
+</ul>
+
+<p>The following sections describe the setup required for each scenario.</p>
+
+
+<h4 id="CABforViews">Enabling the contextual action mode for individual views</h4>
+
+<p>If you want to invoke the contextual action mode only when the user selects specific
+views, you should:</p>
+<ol>
+ <li>Implement the {@link android.view.ActionMode.Callback} interface. In its callback methods, you
+can specify the actions for the contextual action bar, respond to click events on action items, and
+handle other lifecycle events for the action mode.</li>
+ <li>Call {@link android.app.Activity#startActionMode startActionMode()} when you want to show the
+bar (such as when the user long-clicks the view).</li>
+</ol>
+
+<p>For example:</p>
+
+<ol>
+ <li>Implement the {@link android.view.ActionMode.Callback ActionMode.Callback} interface:
+<pre>
+private ActionMode.Callback mActionModeCallback = new ActionMode.Callback() {
+
+ // Called when the action mode is created; startActionMode() was called
+ @Override
+ public boolean onCreateActionMode(ActionMode mode, Menu menu) {
+ // Inflate a menu resource providing context menu items
+ MenuInflater inflater = mode.getMenuInflater();
+ inflater.inflate(R.menu.context_menu, menu);
+ return true;
+ }
+
+ // Called each time the action mode is shown. Always called after onCreateActionMode, but
+ // may be called multiple times if the mode is invalidated.
+ @Override
+ public boolean onPrepareActionMode(ActionMode mode, Menu menu) {
+ return false; // Return false if nothing is done
+ }
+
+ // Called when the user selects a contextual menu item
+ @Override
+ public boolean onActionItemClicked(ActionMode mode, MenuItem item) {
+ switch (item.getItemId()) {
+ case R.id.menu_share:
+ shareCurrentItem();
+ mode.finish(); // Action picked, so close the CAB
+ return true;
+ default:
+ return false;
+ }
+ }
+
+ // Called when the user exits the action mode
+ @Override
+ public void onDestroyActionMode(ActionMode mode) {
+ mActionMode = null;
+ }
+};
+</pre>
+
+<p>Notice that these event callbacks are almost exactly the same as the callbacks for the <a
+href="#options-menu">options menu</a>, except each of these also pass the {@link
+android.view.ActionMode} object associated with the event. You can use {@link
+android.view.ActionMode} APIs to make various changes to the CAB, such as revise the title and
+subtitle with {@link android.view.ActionMode#setTitle setTitle()} and {@link
+android.view.ActionMode#setSubtitle setSubtitle()} (useful to indicate how many items are
+selected).</p>
+
+<p>Also notice that the above sample sets the {@code mActionMode} variable null when the
+action mode is destroyed. In the next step, you'll see how it's initialized and how saving
+the member variable in your activity or fragment can be useful.</p>
+</li>
+
+ <li>Call {@link android.app.Activity#startActionMode startActionMode()} to enable the contextual
+action mode when appropriate, such as in response to a long-click on a {@link
+android.view.View}:</p>
+
+<pre>
+someView.setOnLongClickListener(new View.OnLongClickListener() {
+ // Called when the user long-clicks on someView
+ public boolean onLongClick(View view) {
+ if (mActionMode != null) {
+ return false;
+ }
+
+ // Start the CAB using the ActionMode.Callback defined above
+ mActionMode = getActivity().startActionMode(mActionModeCallback);
+ view.setSelected(true);
+ return true;
+ }
+});
+</pre>
+
+<p>When you call {@link android.app.Activity#startActionMode startActionMode()}, the system returns
+the {@link android.view.ActionMode} created. By saving this in a member variable, you can
+make changes to the contextual action bar in response to other events. In the above sample, the
+{@link android.view.ActionMode} is used to ensure that the {@link android.view.ActionMode} instance
+is not recreated if it's already active, by checking whether the member is null before starting the
+action mode.</p>
+</li>
+</ol>
+
+
+
+<h4 id="CABforListView">Enabling batch contextual actions in a ListView or GridView</h4>
+
+<p>If you have a collection of items in a {@link android.widget.ListView} or {@link
+android.widget.GridView} (or another extension of {@link android.widget.AbsListView}) and want to
+allow users to perform batch actions, you should:</p>
+
+<ul>
+ <li>Implement the {@link android.widget.AbsListView.MultiChoiceModeListener} interface and set it
+for the view group with {@link android.widget.AbsListView#setMultiChoiceModeListener
+setMultiChoiceModeListener()}. In the listener's callback methods, you can specify the actions
+for the contextual action bar, respond to click events on action items, and handle other callbacks
+inherited from the {@link android.view.ActionMode.Callback} interface.</li>
+
+ <li>Call {@link android.widget.AbsListView#setChoiceMode setChoiceMode()} with the {@link
+android.widget.AbsListView#CHOICE_MODE_MULTIPLE_MODAL} argument.</li>
+</ul>
+
+<p>For example:</p>
+
+<pre>
+ListView listView = getListView();
+listView.setChoiceMode(ListView.CHOICE_MODE_MULTIPLE_MODAL);
+listView.setMultiChoiceModeListener(new MultiChoiceModeListener() {
+
+ @Override
+ public void onItemCheckedStateChanged(ActionMode mode, int position,
+ long id, boolean checked) {
+ // Here you can do something when items are selected/de-selected,
+ // such as update the title in the CAB
+ }
+
+ @Override
+ public boolean onActionItemClicked(ActionMode mode, MenuItem item) {
+ // Respond to clicks on the actions in the CAB
+ switch (item.getItemId()) {
+ case R.id.menu_delete:
+ deleteSelectedItems();
+ mode.finish(); // Action picked, so close the CAB
+ return true;
+ default:
+ return false;
+ }
+ }
+
+ @Override
+ public boolean onCreateActionMode(ActionMode mode, Menu menu) {
+ // Inflate the menu for the CAB
+ MenuInflater inflater = mode.getMenuInflater();
+ inflater.inflate(R.menu.context, menu);
+ return true;
+ }
+
+ @Override
+ public void onDestroyActionMode(ActionMode mode) {
+ // Here you can make any necessary updates to the activity when
+ // the CAB is removed. By default, selected items are deselected/unchecked.
+ }
+
+ @Override
+ public boolean onPrepareActionMode(ActionMode mode, Menu menu) {
+ // Here you can perform updates to the CAB due to
+ // an {@link android.view.ActionMode#invalidate} request
+ return false;
+ }
+});
+</pre>
+
+<p>That's it. Now when the user selects an item with a long-click, the system calls the {@link
+android.widget.AbsListView.MultiChoiceModeListener#onCreateActionMode onCreateActionMode()}
+method and displays the contextual action bar with the specified actions. While the contextual
+action bar is visible, users can select additional items.</p>
+
+<p>In some cases in which the contextual actions provide common action items, you might
+want to add a checkbox or a similar UI element that allows users to select items, because they
+might not discover the long-click behavior. When a user selects the checkbox, you
+can invoke the contextual action mode by setting the respective list item to the checked
+state with {@link android.widget.AbsListView#setItemChecked setItemChecked()}.</p>
+
+
+
+
+<h2 id="PopupMenu">Creating a Popup Menu</h2>
+
+<div class="figure" style="width:220px">
+<img src="{@docRoot}images/ui/popupmenu.png" alt="" />
+<p><strong>Figure 4.</strong> A popup menu in the Gmail app, anchored to the overflow
+button at the top-right.</p>
+</div>
+
+<p>A {@link android.widget.PopupMenu} is a modal menu anchored to a {@link android.view.View}.
+It appears below the anchor view if there is room, or above the view otherwise. It's useful for:</p>
+<ul>
+ <li>Providing an overflow-style menu for actions that <em>relate to</em> specific content (such as
+Gmail's email headers, shown in figure 4).
+ <p class="note"><strong>Note:</strong> This is not the same as a context menu, which is
+generally for actions that <em>affect</em> selected content. For actions that affect selected
+content, use the <a href="#CAB">contextual action mode</a> or <a
+href="#FloatingContextMenu">floating context menu</a>.</p></li>
+ <li>Providing a second part of a command sentence (such as a button marked "Add"
+that produces a popup menu with different "Add" options).</li>
+ <li>Providing a drop-down similar to {@link android.widget.Spinner} that does not retain
+a persistent selection.</li>
+</ul>
+
+
+<p class="note"><strong>Note:</strong> {@link android.widget.PopupMenu} is available with API
+level 11 and higher.</p>
+
+<p>If you <a href="#xml">define your menu in XML</a>, here's how you can show the popup menu:</p>
+<ol>
+ <li>Instantate a {@link android.widget.PopupMenu} with its constructor, which takes the
+current application {@link android.content.Context} and the {@link android.view.View} to which the
+menu should be anchored.</li>
+ <li>Use {@link android.view.MenuInflater} to inflate your menu resource into the {@link
+android.view.Menu} object returned by {@link
+android.widget.PopupMenu#getMenu() PopupMenu.getMenu()}. On API level 14 and above, you can use
+{@link android.widget.PopupMenu#inflate PopupMenu.inflate()} instead.</li>
+ <li>Call {@link android.widget.PopupMenu#show() PopupMenu.show()}.</li>
+</ol>
+
+<p>For example, here's a button with the {@link android.R.attr#onClick android:onClick} attribute
+that shows a popup menu:</p>
+
+<pre>
+<ImageButton
+ android:layout_width="wrap_content"
+ android:layout_height="wrap_content"
+ android:src="@drawable/ic_overflow_holo_dark"
+ android:contentDescription="@string/descr_overflow_button"
+ android:onClick="showPopup" />
+</pre>
+
+<p>The activity can then show the popup menu like this:</p>
+
+<pre>
+public void showPopup(View v) {
+ PopupMenu popup = new PopupMenu(this, v);
+ MenuInflater inflater = popup.getMenuInflater();
+ inflater.inflate(R.menu.actions, popup.getMenu());
+ popup.show();
+}
+</pre>
+
+<p>In API level 14 and higher, you can combine the two lines that inflate the menu with {@link
+android.widget.PopupMenu#inflate PopupMenu.inflate()}.</p>
+
+<p>The menu is dismissed when the user selects an item or touches outside the menu
+area. You can listen for the dismiss event using {@link
+android.widget.PopupMenu.OnDismissListener}.</p>
+
+<h3 id="PopupEvents">Handling click events</h3>
+
+<p>To perform an
+action when the user selects a menu item, you must implement the {@link
+android.widget.PopupMenu.OnMenuItemClickListener} interface and register it with your {@link
+android.widget.PopupMenu} by calling {@link android.widget.PopupMenu#setOnMenuItemClickListener
+setOnMenuItemclickListener()}. When the user selects an item, the system calls the {@link
+android.widget.PopupMenu.OnMenuItemClickListener#onMenuItemClick onMenuItemClick()} callback in
+your interface.</p>
+
+<p>For example:</p>
+
+<pre>
+public void showMenu(View v) {
+ PopupMenu popup = new PopupMenu(this, v);
+
+ // This activity implements OnMenuItemClickListener
+ popup.setOnMenuItemClickListener(this);
+ popup.inflate(R.menu.actions);
+ popup.show();
+}
+
+@Override
+public boolean onMenuItemClick(MenuItem item) {
+ switch (item.getItemId()) {
+ case R.id.archive:
+ archive(item);
+ return true;
+ case R.id.delete:
+ delete(item);
+ return true;
+ default:
+ return false;
+ }
+}
+</pre>
+
+
+<h2 id="groups">Creating Menu Groups</h2>
<p>A menu group is a collection of menu items that share certain traits. With a group, you
can:</p>
@@ -473,38 +842,41 @@
<pre>
<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
- <item android:id="@+id/item1"
- android:icon="@drawable/item1"
- android:title="@string/item1" />
+ <item android:id="@+id/menu_save"
+ android:icon="@drawable/menu_save"
+ android:title="@string/menu_save" />
<!-- menu group -->
- <group android:id="@+id/group1">
- <item android:id="@+id/groupItem1"
- android:title="@string/groupItem1" />
- <item android:id="@+id/groupItem2"
- android:title="@string/groupItem2" />
+ <group android:id="@+id/group_delete">
+ <item android:id="@+id/menu_archive"
+ android:title="@string/menu_archive" />
+ <item android:id="@+id/menu_delete"
+ android:title="@string/menu_delete" />
</group>
</menu>
</pre>
-<p>The items that are in the group appear the same as the first item that is not in a
-group—all three items in the menu are siblings. However, you can modify the traits of the two
-items in the group by referencing the group ID and using the methods listed above.</p>
+<p>The items that are in the group appear at the same level as the first item—all three items
+in the menu are siblings. However, you can modify the traits of the two
+items in the group by referencing the group ID and using the methods listed above. The system
+will also never separate grouped items. For example, if you declare {@code
+android:showAsAction="ifRoom"} for each item, they will either both appear in the action
+bar or both appear in the action overflow.</p>
-<h3 id="checkable">Checkable menu items</h3>
+<h3 id="checkable">Using checkable menu items</h3>
<div class="figure" style="width:200px">
<img src="{@docRoot}images/radio_buttons.png" height="333" alt="" />
- <p class="img-caption"><strong>Figure 3.</strong> Screenshot of a submenu with checkable
+ <p class="img-caption"><strong>Figure 5.</strong> Screenshot of a submenu with checkable
items.</p>
</div>
<p>A menu can be useful as an interface for turning options on and off, using a checkbox for
stand-alone options, or radio buttons for groups of
-mutually exclusive options. Figure 2 shows a submenu with items that are checkable with radio
+mutually exclusive options. Figure 5 shows a submenu with items that are checkable with radio
buttons.</p>
-<p class="note"><strong>Note:</strong> Menu items in the Icon Menu (from the Options Menu) cannot
+<p class="note"><strong>Note:</strong> Menu items in the Icon Menu (from the options menu) cannot
display a checkbox or radio button. If you choose to make items in the Icon Menu checkable,
you must manually indicate the checked state by swapping the icon and/or text
each time the state changes.</p>
@@ -550,15 +922,15 @@
<pre>
@Override
public boolean onOptionsItemSelected(MenuItem item) {
- switch (item.getItemId()) {
- case R.id.vibrate:
- case R.id.dont_vibrate:
- if (item.isChecked()) item.setChecked(false);
- else item.setChecked(true);
- return true;
- default:
- return super.onOptionsItemSelected(item);
- }
+ switch (item.getItemId()) {
+ case R.id.vibrate:
+ case R.id.dont_vibrate:
+ if (item.isChecked()) item.setChecked(false);
+ else item.setChecked(true);
+ return true;
+ default:
+ return super.onOptionsItemSelected(item);
+ }
}
</pre>
@@ -575,30 +947,8 @@
href="{@docRoot}guide/topics/data/data-storage.html#pref">Shared Preferences</a>.</p>
-<h3 id="shortcuts">Shortcut keys</h3>
-<p>To facilitate quick access to items in the Options Menu when the user's device has a hardware
-keyboard, you can add quick-access shortcut keys using letters and/or numbers, with the
-{@code android:alphabeticShortcut} and {@code android:numericShortcut} attributes in the {@code
-<item>} element. You can also use the methods {@link
-android.view.MenuItem#setAlphabeticShortcut(char)} and {@link
-android.view.MenuItem#setNumericShortcut(char)}. Shortcut keys are <em>not</em>
-case sensitive.</p>
-
-<p>For example, if you apply the "s" character as an alphabetic shortcut to a "save" menu item, then
-when the menu is open (or while the user holds the MENU button) and the user presses the "s" key,
-the "save" menu item is selected.</p>
-
-<p>This shortcut key is displayed as a tip in the menu item, below the menu item name
-(except for items in the Icon Menu, which are displayed only if the user holds the MENU
-button).</p>
-
-<p class="note"><strong>Note:</strong> Shortcut keys for menu items only work on devices with a
-hardware keyboard. Shortcuts cannot be added to items in a Context Menu.</p>
-
-
-
-<h3 id="intents">Dynamically adding menu intents</h3>
+<h2 id="intents">Adding Menu Items Based on an Intent</h2>
<p>Sometimes you'll want a menu item to launch an activity using an {@link android.content.Intent}
(whether it's an activity in your application or another application). When you know the intent you
@@ -671,7 +1021,7 @@
argument.</p>
-<h4>Allowing your activity to be added to other menus</h4>
+<h3 id="AllowingToAdd">Allowing your activity to be added to other menus</h3>
<p>You can also offer the services of your activity to other applications, so your
application can be included in the menu of others (reverse the roles described above).</p>
@@ -681,7 +1031,7 @@
and/or {@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE} values for the intent filter
category. For example:</p>
<pre>
-<intent-filter label="Resize Image">
+<intent-filter label="@string/resize_image">
...
<category android:name="android.intent.category.ALTERNATIVE" />
<category android:name="android.intent.category.SELECTED_ALTERNATIVE" />
diff --git a/docs/html/guide/topics/ui/notifiers/notifications.jd b/docs/html/guide/topics/ui/notifiers/notifications.jd
index bef9671..d104b4b 100644
--- a/docs/html/guide/topics/ui/notifiers/notifications.jd
+++ b/docs/html/guide/topics/ui/notifiers/notifications.jd
@@ -173,7 +173,7 @@
</li>
<li>
The user has seen enough to know they have a meeting coming up,
- so they press the BACK button. They are now returned to Email, which
+ so they press the <em>Back</em> button. They are now returned to Email, which
is where they were when they took the notification.
</li>
</ol>
@@ -198,8 +198,8 @@
(writing an e-mail), but that message is still saved in their drafts.
</li>
<li>
- The user presses BACK once to go to the message list (the typical flow in the
- Email app), and press BACK again to return to Calendar as they left it.
+ The user presses <em>Back</em> once to go to the message list (the typical flow in the
+ Email app), and press <em>Back</em> again to return to Calendar as they left it.
</li>
</ol>
@@ -216,7 +216,7 @@
most interest is the <code>makeMessageIntentStack()</code> method, which constructs
an array of intents representing the app's new activity stack for this state.
(If you are using fragments, you may need to initialize your fragment and
-app state so that pressing BACK will switch the UI back to its parent state.)
+app state so that pressing <em>Back</em> will switch the UI back to its parent state.)
The core of this is the {@link android.content.Intent#makeRestartActivityTask
Intent.makeRestartActivityTask()} method, which constructs the root activity
of the stack with the appropriate flags, such as
diff --git a/docs/html/guide/webapps/webview.jd b/docs/html/guide/webapps/webview.jd
index ed28f21..66b5501 100644
--- a/docs/html/guide/webapps/webview.jd
+++ b/docs/html/guide/webapps/webview.jd
@@ -298,18 +298,18 @@
pages. You can navigate backward and forward through the history with {@link
android.webkit.WebView#goBack()} and {@link android.webkit.WebView#goForward()}.</p>
-<p>For example, here's how your {@link android.app.Activity} can use the device BACK key to navigate
-backward:</p>
+<p>For example, here's how your {@link android.app.Activity} can use the device <em>Back</em> button
+to navigate backward:</p>
<pre>
@Override
public boolean {@link android.app.Activity#onKeyDown(int,KeyEvent) onKeyDown}(int keyCode, KeyEvent event) {
- // Check if the key event was the BACK key and if there's history
+ // Check if the key event was the Back button and if there's history
if ((keyCode == KeyEvent.KEYCODE_BACK) && myWebView.{@link android.webkit.WebView#canGoBack() canGoBack}() {
myWebView.{@link android.webkit.WebView#goBack() goBack}();
return true;
}
- // If it wasn't the BACK key or there's no web page history, bubble up to the default
+ // If it wasn't the Back key or there's no web page history, bubble up to the default
// system behavior (probably exit the activity)
return super.onKeyDown(keyCode, event);
}
diff --git a/docs/html/images/ui/menu-context.png b/docs/html/images/ui/menu-context.png
new file mode 100644
index 0000000..f6975fb
--- /dev/null
+++ b/docs/html/images/ui/menu-context.png
Binary files differ
diff --git a/docs/html/images/ui/popupmenu.png b/docs/html/images/ui/popupmenu.png
new file mode 100644
index 0000000..5c99821
--- /dev/null
+++ b/docs/html/images/ui/popupmenu.png
Binary files differ
diff --git a/docs/html/index.jd b/docs/html/index.jd
index c14c0ae..b9d6758 100644
--- a/docs/html/index.jd
+++ b/docs/html/index.jd
@@ -1,4 +1,5 @@
home=true
+page.metaDescription=The official site for Android developers. Provides the Android SDK and documentation for app developers and designers.
@jd:body
@@ -153,7 +154,7 @@
+ "href='https://plus.google.com/108967384991768947849'>+Android Developers</a>. "
+ "We'll use it to host Hangouts for developers, talk about the latest releases, "
+ "development and design tips, and much more.</p>"
-+ "<div style='margin-top:.7em'><g:plus href='https://plus.google.com/108967384991768947849' "
++ "<div style='margin:.7em 0 0 -1.2em'><g:plus href='https://plus.google.com/108967384991768947849' "
+ "size=\"smallbadge\" width=\"275\"></g:plus></div>"
},
@@ -213,6 +214,3 @@
var s = document.getElementsByTagName("script")[0];
s.parentNode.insertBefore(po, s);
})();</script>
-<style type="text/css">
- #___plus_0, #___plus_0 iframe, #___plus_0 { width: 275px !important; }
-</style>
diff --git a/docs/html/resources/dashboard/opengl.jd b/docs/html/resources/dashboard/opengl.jd
index 357c1ea..d55ab2b 100644
--- a/docs/html/resources/dashboard/opengl.jd
+++ b/docs/html/resources/dashboard/opengl.jd
@@ -57,7 +57,7 @@
<div class="dashboard-panel">
<img alt="" width="400" height="250"
-src="http://chart.googleapis.com/chart?cht=p&chs=400x250&chco=c4df9b,6fad0c&chl=GL%201.1|GL%202.0%20%26%201.1&chd=t%3A9.5,90.5" />
+src="http://chart.googleapis.com/chart?cht=p&chs=400x250&chco=c4df9b,6fad0c&chl=GL%201.1%20only|GL%202.0%20%26%201.1&chd=t%3A10.7,89.3" />
<table>
<tr>
@@ -65,15 +65,15 @@
<th scope="col">Distribution</th>
</tr>
<tr>
-<td>1.1</th>
-<td>9.5%</td>
+<td>1.1 only</th>
+<td>10.7%</td>
</tr>
<tr>
-<td>2.0</th>
-<td>90.5%</td>
+<td>2.0 & 1.1</th>
+<td>89.3%</td>
</tr>
</table>
-<p><em>Data collected during a 7-day period ending on January 3, 2012</em></p>
+<p><em>Data collected during a 7-day period ending on February 1, 2012</em></p>
</div>
diff --git a/docs/html/resources/dashboard/platform-versions.jd b/docs/html/resources/dashboard/platform-versions.jd
index 2618a04..4ea52af 100644
--- a/docs/html/resources/dashboard/platform-versions.jd
+++ b/docs/html/resources/dashboard/platform-versions.jd
@@ -52,7 +52,7 @@
<div class="dashboard-panel">
<img alt="" height="250" width="470"
-src="http://chart.apis.google.com/chart?&cht=p&chs=460x250&chd=t:0.6,1.1,8.5,30.4,0.6,54.9,0.1,1.5,1.7,0.3,0.3&chl=Android%201.5|Android%201.6|Android%202.1|Android%202.2|Android%202.3|Android%202.3.3|Android%203.0|Android%203.1|Android%203.2|Android%204.0|Android%204.0.3&chco=c4df9b,6fad0c" />
+src="http://chart.apis.google.com/chart?&cht=p&chs=460x250&chd=t:0.6,1.0,7.6,27.8,0.5,58.1,0.1,1.4,1.9,0.3,0.7&chl=Android%201.5|Android%201.6|Android%202.1|Android%202.2|Android%202.3|Android%202.3.3|Android%203.0|Android%203.1|Android%203.2|Android%204.0|Android%204.0.3&chco=c4df9b,6fad0c" />
<table>
<tr>
@@ -62,24 +62,24 @@
<th>Distribution</th>
</tr>
<tr><td><a href="{@docRoot}sdk/android-1.5.html">Android 1.5</a></td><td>Cupcake</td> <td>3</td><td>0.6%</td></tr>
-<tr><td><a href="{@docRoot}sdk/android-1.6.html">Android 1.6</a></td><td>Donut</td> <td>4</td><td>1.1%</td></tr>
-<tr><td><a href="{@docRoot}sdk/android-2.1.html">Android 2.1</a></td><td>Eclair</td> <td>7</td><td>8.5%</td></tr>
-<tr><td><a href="{@docRoot}sdk/android-2.2.html">Android 2.2</a></td><td>Froyo</td> <td>8</td><td>30.4%</td></tr>
+<tr><td><a href="{@docRoot}sdk/android-1.6.html">Android 1.6</a></td><td>Donut</td> <td>4</td><td>1.0%</td></tr>
+<tr><td><a href="{@docRoot}sdk/android-2.1.html">Android 2.1</a></td><td>Eclair</td> <td>7</td><td>7.6%</td></tr>
+<tr><td><a href="{@docRoot}sdk/android-2.2.html">Android 2.2</a></td><td>Froyo</td> <td>8</td><td>27.8%</td></tr>
<tr><td><a href="{@docRoot}sdk/android-2.3.html">Android 2.3 -<br/>
- Android 2.3.2</a></td><td rowspan="2">Gingerbread</td> <td>9</td><td>0.6%</td></tr>
+ Android 2.3.2</a></td><td rowspan="2">Gingerbread</td> <td>9</td><td>0.5%</td></tr>
<tr><td><a href="{@docRoot}sdk/android-2.3.3.html">Android 2.3.3 -<br/>
- Android 2.3.7</a></td><!-- Gingerbread --> <td>10</td><td>54.9%</td></tr>
+ Android 2.3.7</a></td><!-- Gingerbread --> <td>10</td><td>58.1%</td></tr>
<tr><td><a href="{@docRoot}sdk/android-3.0.html">Android 3.0</a></td>
<td rowspan="3">Honeycomb</td> <td>11</td><td>0.1%</td></tr>
-<tr><td><a href="{@docRoot}sdk/android-3.1.html">Android 3.1</a></td><!-- Honeycomb --><td>12</td><td>1.5%</td></tr>
-<tr><td><a href="{@docRoot}sdk/android-3.2.html">Android 3.2</a></td><!-- Honeycomb --><td>13</td><td>1.7%</td></tr>
+<tr><td><a href="{@docRoot}sdk/android-3.1.html">Android 3.1</a></td><!-- Honeycomb --><td>12</td><td>1.4%</td></tr>
+<tr><td><a href="{@docRoot}sdk/android-3.2.html">Android 3.2</a></td><!-- Honeycomb --><td>13</td><td>1.9%</td></tr>
<tr><td><a href="{@docRoot}sdk/android-4.0.html">Android 4.0 -<br/>
Android 4.0.2</a></td>
<td rowspan="2">Ice Cream Sandwich</td><td>14</td><td>0.3%</td></tr>
-<tr><td><a href="{@docRoot}sdk/android-4.0.3.html">Android 4.0.3</a></td><!-- ICS --><td>15</td><td>0.3%</td></tr>
+<tr><td><a href="{@docRoot}sdk/android-4.0.3.html">Android 4.0.3</a></td><!-- ICS --><td>15</td><td>0.7%</td></tr>
</table>
-<p><em>Data collected during a 14-day period ending on January 3, 2012</em></p>
+<p><em>Data collected during a 14-day period ending on February 1, 2012</em></p>
<!--
<p style="font-size:.9em">* <em>Other: 0.1% of devices running obsolete versions</em></p>
-->
@@ -108,9 +108,9 @@
<div class="dashboard-panel">
<img alt="" height="250" width="660" style="padding:5px;background:#fff"
-src="http://chart.apis.google.com/chart?&cht=lc&chs=660x250&chxt=x,x,y,r&chxr=0,0,12|1,0,12|2,0,100|3,0,100&chxl=0%3A%7C07/01%7C07/15%7C08/01%7C08/15%7C09/01%7C09/15%7C10/01%7C10/15%7C11/01%7C11/15%7C12/01%7C12/15%7C01/01%7C1%3A%7C2011%7C%7C%7C%7C%7C%7C%7C%7C%7C%7C%7C%7C2012%7C2%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25%7C3%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25&chxp=0,0,1,2,3,4,5,6,7,8,9,10,11,12&chxtc=0,5&chd=t:99.2,99.0,98.8,98.7,98.5,98.5,98.2,98.1,98.0,99.9,99.9,99.7,99.2|97.7,97.6,97.5,97.5,97.5,97.5,97.1,97.1,97.0,99.1,99.1,99.0,98.6|95.5,95.5,95.5,95.6,95.7,95.8,95.6,95.9,95.7,97.7,97.8,97.8,97.5|77.6,79.0,80.2,81.1,82.4,83.3,83.8,84.9,85.1,87.5,88.2,88.6,89.0|17.8,20.6,24.3,27.5,31.2,34.7,38.3,41.3,44.0,48.9,52.9,55.7,58.5|16.8,20.0,23.7,26.9,30.6,34.1,37.8,40.8,43.5,48.4,52.4,55.2,57.9|0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,2.0,2.3,2.6,3.2|0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,1.0,1.2,1.3,1.7&chm=b,c3df9b,0,1,0|b,b8dc82,1,2,0|tAndroid 2.1,608920,2,0,15,,t::-5|b,addb67,2,3,0|tAndroid 2.2,517617,3,0,15,,t::-5|b,a3db4b,3,4,0|b,98dc2e,4,5,0|tAndroid 2.3.3,334d0a,5,0,15,,t::-5|b,8cd41b,5,6,0|b,7ec113,6,7,0|B,6fad0c,7,8,0&chg=7,25&chdl=Android 1.5|Android 1.6|Android 2.1|Android 2.2|Android 2.3|Android 2.3.3|Android 3.1|Android 3.2&chco=add274,a2d15a,97d13e,8bcb28,7dba1e,6ea715,5f920e,507d08" />
+src="http://chart.apis.google.com/chart?&cht=lc&chs=660x250&chxt=x,x,y,r&chxr=0,0,12|1,0,12|2,0,100|3,0,100&chxl=0%3A%7C08/01%7C08/15%7C09/01%7C09/15%7C10/01%7C10/15%7C11/01%7C11/15%7C12/01%7C12/15%7C01/01%7C01/15%7C02/01%7C1%3A%7C2011%7C%7C%7C%7C%7C%7C%7C%7C%7C%7C2012%7C%7C2012%7C2%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25%7C3%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25&chxp=0,0,1,2,3,4,5,6,7,8,9,10,11,12&chxtc=0,5&chd=t:98.2,98.1,97.9,97.9,97.7,97.6,97.5,99.4,99.4,99.2,98.6,98.4,98.5|96.9,96.9,96.9,96.9,96.6,96.6,96.5,98.6,98.6,98.5,98.0,97.8,97.9|94.9,95.0,95.1,95.2,95.1,95.4,95.2,97.2,97.3,97.3,96.9,96.8,96.9|79.6,80.5,81.8,82.7,83.3,84.4,84.6,87.0,87.7,88.1,88.4,88.8,89.2|23.7,26.9,30.6,34.1,37.8,40.8,43.5,48.4,52.4,55.2,57.9,59.7,61.3|0.0,0.0,0.0,0.0,0.0,0.0,0.0,2.0,2.3,2.6,3.2,3.2,3.3|0.0,0.0,0.0,0.0,0.0,0.0,0.0,1.0,1.2,1.3,1.7,1.8,1.9&chm=b,c3df9b,0,1,0|b,b6dc7d,1,2,0|tAndroid%202.1,5b831d,2,0,15,,t::-5|b,aadb5e,2,3,0|tAndroid%202.2,496c13,3,0,15,,t::-5|b,9ddb3d,3,4,0|tAndroid%202.3.3,38540b,4,0,15,,t::-5|b,91da1e,4,5,0|b,80c414,5,6,0|B,6fad0c,6,7,0&chg=7,25&chdl=Android%201.5|Android%201.6|Android%202.1|Android%202.2|Android%202.3.3|Android%203.1|Android%203.2&chco=add274,a0d155,94d134,84c323,73ad18,62960f,507d08" />
-<p><em>Last historical dataset collected during a 14-day period ending on January 3, 2012</em></p>
+<p><em>Last historical dataset collected during a 14-day period ending on February 1, 2012</em></p>
</div><!-- end dashboard-panel -->
diff --git a/docs/html/resources/dashboard/screens.jd b/docs/html/resources/dashboard/screens.jd
index 79d59d9..ae5cdc7 100644
--- a/docs/html/resources/dashboard/screens.jd
+++ b/docs/html/resources/dashboard/screens.jd
@@ -60,7 +60,7 @@
<div class="dashboard-panel">
<img alt="" width="400" height="250"
-src="http://chart.googleapis.com/chart?cht=p&chs=400x250&chco=c4df9b,6fad0c&chl=Xlarge%20/%20mdpi|Large%20/%20ldpi|Large%20/%20mdpi|Normal%20/%20hdpi|Normal%20/%20ldpi|Normal%20/%20mdpi|Small%20/%20hdpi|Small%20/%20ldpi&chd=t%3A3.1,0.1,3.1,71.0,1.0,17.5,2.9,1.3" />
+src="http://chart.googleapis.com/chart?cht=p&chs=400x250&chco=c4df9b,6fad0c&chl=Xlarge%20/%20mdpi|Large%20/%20ldpi|Large%20/%20mdpi|Normal%20/%20hdpi|Normal%20/%20ldpi|Normal%20/%20mdpi|Normal%20/%20xhdpi|Small%20/%20hdpi|Small%20/%20ldpi&chd=t%3A4.8,0.2,2.9,67.1,0.7,18.4,1.8,2.5,1.6" />
<table>
<tr>
@@ -71,31 +71,31 @@
<th scope="col">xhdpi</th>
</tr>
<tr><th scope="row">small</th>
-<td>1.3%</td> <!-- small/ldpi -->
+<td>1.6%</td> <!-- small/ldpi -->
<td></td> <!-- small/mdpi -->
-<td>2.9%</td> <!-- small/hdpi -->
+<td>2.5%</td> <!-- small/hdpi -->
<td></td> <!-- small/xhdpi -->
</tr>
<tr><th scope="row">normal</th>
-<td>1.0%</td> <!-- normal/ldpi -->
-<td>17.5%</td> <!-- normal/mdpi -->
-<td>71%</td> <!-- normal/hdpi -->
-<td></td> <!-- normal/xhdpi -->
+<td>0.7%</td> <!-- normal/ldpi -->
+<td>18.4%</td> <!-- normal/mdpi -->
+<td>67.1%</td> <!-- normal/hdpi -->
+<td>1.8%</td> <!-- normal/xhdpi -->
</tr>
<tr><th scope="row">large</th>
-<td>0.1%</td> <!-- large/ldpi -->
-<td>3.1%</td> <!-- large/mdpi -->
+<td>0.2%</td> <!-- large/ldpi -->
+<td>2.9%</td> <!-- large/mdpi -->
<td></td> <!-- large/hdpi -->
<td></td> <!-- large/xhdpi -->
</tr>
<tr><th scope="row">xlarge</th>
<td></td> <!-- xlarge/ldpi -->
-<td>3.1%</td> <!-- xlarge/mdpi -->
+<td>4.8%</td> <!-- xlarge/mdpi -->
<td></td> <!-- xlarge/hdpi -->
<td></td> <!-- xlarge/xhdpi -->
</tr>
</table>
-<p><em>Data collected during a 7-day period ending on December 1, 2011</em></p>
+<p><em>Data collected during a 7-day period ending on February 1, 2012</em></p>
</div>
diff --git a/docs/html/resources/resources_toc.cs b/docs/html/resources/resources_toc.cs
index 628df9e..8483037 100644
--- a/docs/html/resources/resources_toc.cs
+++ b/docs/html/resources/resources_toc.cs
@@ -1,7 +1,8 @@
<ul>
<li>
- <h2><span class="en">Android Training</span>
- </h2>
+ <span class="heading">
+ <span class="en">Android Training</span>
+ </span>
<ul>
<li><a href="<?cs var:toroot ?>training/index.html">
@@ -237,8 +238,9 @@
<li>
- <h2><span class="en">Technical Resources</span>
- </h2>
+ <span class="heading">
+ <span class="en">Technical Resources</span>
+ </span>
<ul>
<li class="toggle-list">
<div><a href="<?cs var:toroot ?>resources/browser.html?tag=sample">
@@ -288,15 +290,16 @@
</ul>
</li>
<li>
- <h2><span class="en">Community</span>
- <span style="display:none" class="de"></span>
- <span style="display:none" class="es">Comunidad</span>
- <span style="display:none" class="fr">Communauté</span>
- <span style="display:none" class="it"></span>
- <span style="display:none" class="ja">コミュニティ</span>
- <span style="display:none" class="zh-CN">社区</span>
- <span style="display:none" class="zh-TW">社群</span>
- </h2>
+ <span class="heading">
+ <span class="en">Community</span>
+ <span style="display:none" class="de"></span>
+ <span style="display:none" class="es">Comunidad</span>
+ <span style="display:none" class="fr">Communauté</span>
+ <span style="display:none" class="it"></span>
+ <span style="display:none" class="ja">コミュニティ</span>
+ <span style="display:none" class="zh-CN">社区</span>
+ <span style="display:none" class="zh-TW">社群</span>
+ </span>
<ul>
<li><a href="<?cs var:toroot ?>resources/community-groups.html">
<span class="en">Developer Forums</span>
@@ -309,8 +312,9 @@
<?cs
if:android.whichdoc == "online" ?>
<li>
- <h2><span class="en">Device Dashboard</span>
- </h2>
+ <span class="heading">
+ <span class="en">Device Dashboard</span>
+ </span>
<ul>
<li><a href="<?cs var:toroot ?>resources/dashboard/platform-versions.html">
<span class="en">Platform Versions</span>
@@ -327,7 +331,9 @@
?>
<li>
- <h2><span class="en">More</span></h2>
+ <span class="heading">
+ <span class="en">More</span>
+ </span>
<ul>
<li><a href="<?cs var:toroot ?>resources/faq/commontasks.html">
<span class="en">Common Tasks </span>
diff --git a/docs/html/resources/tutorials/hello-world.jd b/docs/html/resources/tutorials/hello-world.jd
index 9afab6a..cc8cb3e 100644
--- a/docs/html/resources/tutorials/hello-world.jd
+++ b/docs/html/resources/tutorials/hello-world.jd
@@ -24,7 +24,7 @@
management to greatly speed up your development cycles.</p>
<p>This tutorial assumes that you're using Eclipse. If you're using the command line, see
-<a href="{@docRoot}/guide/developing/building/building-cmdline.html">Building and Running from the
+<a href="{@docRoot}guide/developing/building/building-cmdline.html">Building and Running from the
Command Line</a>. You can then return to this tutorial and ignore anything about Eclipse.</p>
<p>Before you start, you should already have the SDK installed, and if you're
diff --git a/docs/html/sdk/android-2.3.3.jd b/docs/html/sdk/android-2.3.3.jd
index 7a5b044..023e2e4 100644
--- a/docs/html/sdk/android-2.3.3.jd
+++ b/docs/html/sdk/android-2.3.3.jd
@@ -336,7 +336,7 @@
<li>English, New Zealand (en_NZ)</li>
<li>English, Singapore(en_SG)</li>
<li>English, US (en_US)</li>
-<li>English, Zimbabwe (en_ZA)</li>
+<li>English, South Africa (en_ZA)</li>
<li>Spanish (es_ES)</li>
<li>Spanish, US (es_US)</li>
<li>Finnish, Finland (fi_FI)</li>
diff --git a/docs/html/sdk/android-2.3.4.jd b/docs/html/sdk/android-2.3.4.jd
index 4cb44b9..eeaa69a 100644
--- a/docs/html/sdk/android-2.3.4.jd
+++ b/docs/html/sdk/android-2.3.4.jd
@@ -296,7 +296,7 @@
<li>English, New Zealand (en_NZ)</li>
<li>English, Singapore(en_SG)</li>
<li>English, US (en_US)</li>
-<li>English, Zimbabwe (en_ZA)</li>
+<li>English, South Africa (en_ZA)</li>
<li>Spanish (es_ES)</li>
<li>Spanish, US (es_US)</li>
<li>Finnish, Finland (fi_FI)</li>
diff --git a/docs/html/sdk/android-2.3.jd b/docs/html/sdk/android-2.3.jd
index e7aa0fa..fc4f5aa 100644
--- a/docs/html/sdk/android-2.3.jd
+++ b/docs/html/sdk/android-2.3.jd
@@ -859,7 +859,7 @@
<li>English, New Zealand (en_NZ)</li>
<li>English, Singapore(en_SG)</li>
<li>English, US (en_US)</li>
-<li>English, Zimbabwe (en_ZA)</li>
+<li>English, South Africa (en_ZA)</li>
<li>Spanish (es_ES)</li>
<li>Spanish, US (es_US)</li>
<li>Finnish, Finland (fi_FI)</li>
diff --git a/docs/html/sdk/android-3.0.jd b/docs/html/sdk/android-3.0.jd
index 96b92d9..49fefee 100644
--- a/docs/html/sdk/android-3.0.jd
+++ b/docs/html/sdk/android-3.0.jd
@@ -1119,7 +1119,7 @@
<li>English, New Zealand (en_NZ)</li>
<li>English, Singapore(en_SG)</li>
<li>English, US (en_US)</li>
-<li>English, Zimbabwe (en_ZA)</li>
+<li>English, South Africa (en_ZA)</li>
<li>Spanish (es_ES)</li>
<li>Spanish, US (es_US)</li>
<li>Finnish, Finland (fi_FI)</li>
diff --git a/docs/html/sdk/android-3.1.jd b/docs/html/sdk/android-3.1.jd
index 78f265d..b9cf969 100644
--- a/docs/html/sdk/android-3.1.jd
+++ b/docs/html/sdk/android-3.1.jd
@@ -1040,7 +1040,7 @@
<li>English, New Zealand (en_NZ)</li>
<li>English, Singapore(en_SG)</li>
<li>English, US (en_US)</li>
-<li>English, Zimbabwe (en_ZA)</li>
+<li>English, South Africa (en_ZA)</li>
<li>Spanish (es_ES)</li>
<li>Spanish, US (es_US)</li>
<li>Finnish, Finland (fi_FI)</li>
diff --git a/docs/html/sdk/android-4.0.3.jd b/docs/html/sdk/android-4.0.3.jd
index 1fca8df..809c83c 100644
--- a/docs/html/sdk/android-4.0.3.jd
+++ b/docs/html/sdk/android-4.0.3.jd
@@ -435,7 +435,7 @@
<li>English, New Zealand (en_NZ)</li>
<li>English, Singapore(en_SG)</li>
<li>English, US (en_US)</li>
-<li>English, Zimbabwe (en_ZA)</li>
+<li>English, South Africa (en_ZA)</li>
<li>Spanish (es_ES)</li>
<li>Spanish, US (es_US)</li>
<li>Finnish, Finland (fi_FI)</li>
diff --git a/docs/html/sdk/android-4.0.jd b/docs/html/sdk/android-4.0.jd
index 5f55947..2cad86b 100644
--- a/docs/html/sdk/android-4.0.jd
+++ b/docs/html/sdk/android-4.0.jd
@@ -1963,7 +1963,7 @@
<li>English, New Zealand (en_NZ)</li>
<li>English, Singapore(en_SG)</li>
<li>English, US (en_US)</li>
-<li>English, Zimbabwe (en_ZA)</li>
+<li>English, South Africa (en_ZA)</li>
<li>Spanish (es_ES)</li>
<li>Spanish, US (es_US)</li>
<li>Finnish, Finland (fi_FI)</li>
diff --git a/docs/html/sdk/eclipse-adt.jd b/docs/html/sdk/eclipse-adt.jd
index f15da78..30825ee 100644
--- a/docs/html/sdk/eclipse-adt.jd
+++ b/docs/html/sdk/eclipse-adt.jd
@@ -42,7 +42,7 @@
<p>Developing in Eclipse with ADT is highly recommended and is the fastest way
to get started. With the guided project setup it provides, as well as tools
-integration, custom XML editors, and debug ouput pane, ADT gives you an
+integration, custom XML editors, and debug output pane, ADT gives you an
incredible boost in developing Android applications. </p>
<p>This document provides step-by-step instructions on how to download the ADT
@@ -1104,7 +1104,7 @@
<h3 id="downloading">Downloading the ADT Plugin</h3>
<p>Use the Update Manager feature of your Eclipse installation to install the latest
-revision of ADT on your development computer.<>
+revision of ADT on your development computer.</p>
<p>Assuming that you have a compatible version of the Eclipse IDE installed, as
described in <a href="#preparing">Preparing for Installation</a>, above, follow
diff --git a/docs/html/sdk/index.jd b/docs/html/sdk/index.jd
index 65a1f46..5cf05e0 100644
--- a/docs/html/sdk/index.jd
+++ b/docs/html/sdk/index.jd
@@ -1,4 +1,5 @@
page.title=Android SDK
+page.metaDescription=Download the official Android SDK to develop apps for Android-powered devices.
sdk.redirect=0
sdk.win_installer=installer_r16-windows.exe
diff --git a/docs/html/sdk/sdk_toc.cs b/docs/html/sdk/sdk_toc.cs
index 5f6a57f..0de477a 100644
--- a/docs/html/sdk/sdk_toc.cs
+++ b/docs/html/sdk/sdk_toc.cs
@@ -1,7 +1,7 @@
<?cs if:!sdk.redirect ?>
<ul>
<li>
- <h2>
+ <span class="heading">
<span class="en">Android SDK Starter Package</span>
<span style="display:none" class="de">Aktuelle SDK-Version</span>
<span style="display:none" class="es">Versión actual del SDK</span>
@@ -10,7 +10,7 @@
<span style="display:none" class="ja">現在リリースされている SDK</span>
<span style="display:none" class="zh-CN">当前的 SDK 版本</span>
<span style="display:none" class="zh-TW">目前 SDK 發行版本</span>
- </h2>
+ </span>
<ul><?cs
if:android.whichdoc == "online" ?>
<li><a href="<?cs var:toroot ?>sdk/index.html">
@@ -37,7 +37,8 @@
</ul>
</li><?cs
if:sdk.preview ?>
- <li><h2>Android 3.0 Preview SDK</h2>
+ <li>
+ <span class="heading">Android 3.0 Preview SDK</span>
<ul>
<li><a href="<?cs var:toroot ?>sdk/preview/start.html">Getting Started</a> <span
class="new">new!</span></li>
@@ -46,13 +47,14 @@
/if ?>
<?cs
if:sdk.preview ?>
- <li><h2>Android x.x Preview</h2>
+ <li>
+ <span class="heading">Android x.x Preview</span>
<ul>
</ul>
</li><?cs
/if ?>
<li>
- <h2>
+ <span class="heading">
<span class="en">Downloadable SDK Components</span>
<span style="display:none" class="de"></span>
<span style="display:none" class="es"></span>
@@ -61,7 +63,7 @@
<span style="display:none" class="ja"></span>
<span style="display:none" class="zh-CN"></span>
<span style="display:none" class="zh-TW"></span>
- </h2>
+ </span>
<ul>
<li><a href="<?cs var:toroot ?>sdk/adding-components.html">
<span class="en">Adding SDK Components</span>
@@ -158,7 +160,7 @@
</ul>
</li>
<li>
- <h2>
+ <span class="heading">
<span class="en">ADT Plugin for Eclipse</span>
<span style="display:none" class="de"></span>
<span style="display:none" class="es"></span>
@@ -167,7 +169,7 @@
<span style="display:none" class="ja"></span>
<span style="display:none" class="zh-CN"></span>
<span style="display:none" class="zh-TW"></span>
- </h2>
+ </span>
<ul>
<li><a href="<?cs var:toroot ?>sdk/eclipse-adt.html">ADT 16.0.1
<span style="display:none" class="de"></span>
@@ -182,7 +184,8 @@
</ul>
</li>
<li>
- <h2><span class="en">Native Development Tools</span>
+ <span class="heading">
+ <span class="en">Native Development Tools</span>
<span style="display:none" class="de"></span>
<span style="display:none" class="es"></span>
<span style="display:none" class="fr"></span>
@@ -190,7 +193,7 @@
<span style="display:none" class="ja"></span>
<span style="display:none" class="zh-CN"></span>
<span style="display:none" class="zh-TW"></span>
- </h2>
+ </span>
<ul>
<li><a href="<?cs var:toroot ?>sdk/ndk/index.html">Android NDK, r7</a>
<span class="new">new!</span>
@@ -200,7 +203,7 @@
</li>
<li>
- <h2>
+ <span class="heading">
<span class="en">More Information</span>
<span style="display:none" class="de"></span>
<span style="display:none" class="es"></span>
@@ -209,7 +212,7 @@
<span style="display:none" class="ja"></span>
<span style="display:none" class="zh-CN"></span>
<span style="display:none" class="zh-TW"></span>
- </h2>
+ </span>
<ul>
<li><a href="<?cs var:toroot ?>sdk/oem-usb.html">
<span class="en">OEM USB Drivers</span>
diff --git a/docs/html/training/design-navigation/ancestral-temporal.jd b/docs/html/training/design-navigation/ancestral-temporal.jd
index c0b1aef..ab6a64d 100644
--- a/docs/html/training/design-navigation/ancestral-temporal.jd
+++ b/docs/html/training/design-navigation/ancestral-temporal.jd
@@ -29,7 +29,10 @@
</div>
-<p>Now that users can navigate <a href="descendant-lateral.html">deep into</a> the application's screen hierarchy, we need to provide a method for navigating up the hierarchy, to parent and ancestor screens. Additionally, we should ensure that temporal navigation via the BACK button is respected to respect Android conventions.</p>
+<p>Now that users can navigate <a href="descendant-lateral.html">deep into</a> the application's
+screen hierarchy, we need to provide a method for navigating up the hierarchy, to parent and
+ancestor screens. Additionally, we should ensure that temporal navigation via the <em>Back</em>
+button is respected to respect Android conventions.</p>
<div class="design-announce">
<p><strong>Back/Up Navigation Design</strong></p>
@@ -39,27 +42,52 @@
<h2 id="temporal-navigation">Support Temporal Navigation: <em>Back</em></h2>
-<p>Temporal navigation, or navigation between historical screens, is deeply rooted in the Android system. All Android users expect the BACK button to take them to the previous screen, regardless of other state. The set of historical screens is always rooted at the user's Launcher application (the phone's "home" screen). That is, pressing BACK enough times should land you back at the Launcher, after which the BACK button will do nothing.</p>
+<p>Temporal navigation, or navigation between historical screens, is deeply rooted in the Android
+system. All Android users expect the <em>Back</em> button to take them to the previous screen,
+regardless of other state. The set of historical screens is always rooted at the user's Launcher
+application (the phone's "home" screen). That is, pressing <em>Back</em> enough times should land
+you back at the Launcher, after which the <em>Back</em> button will do nothing.</p>
<img src="{@docRoot}images/training/app-navigation-ancestral-navigate-back.png"
- alt="The BACK button behavior after entering the Email app from the People (or Contacts) app" id="figure-navigate-back">
+ alt="The Back button behavior after entering the Email app from the People (or Contacts) app"
+id="figure-navigate-back">
-<p class="img-caption"><strong>Figure 1.</strong> The BACK button behavior after entering the Email app from the People (or Contacts) app.</p>
+<p class="img-caption"><strong>Figure 1.</strong> The <em>Back</em> button behavior after entering
+the Email app from the People (or Contacts) app.</p>
-<p>Applications generally don't have to worry about managing the BACK button themselves; the system handles <a href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">tasks and the <em>back stack</em></a>, or the list of previous screens, automatically. The BACK button by default simply traverses this list of screens, removing the current screen from the list upon being pressed.</p>
+<p>Applications generally don't have to worry about managing the <em>Back</em> button themselves;
+the system handles <a href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">tasks and
+the <em>back stack</em></a>, or the list of previous screens, automatically. The <em>Back</em>
+button by default simply traverses this list of screens, removing the current screen from the list
+upon being pressed.</p>
-<p>There are, however, cases where you may want to override the behavior for BACK. For example, if your screen contains an embedded web browser where users can interact with page elements to navigate between web pages, you may wish to trigger the embedded browser's default <em>back</em> behavior when users press the device's BACK button. Upon reaching the beginning of the browser's internal history, you should always defer to the system's default behavior for the BACK button.</p>
+<p>There are, however, cases where you may want to override the behavior for <em>Back</em>. For
+example, if your screen contains an embedded web browser where users can interact with page elements
+to navigate between web pages, you may wish to trigger the embedded browser's default <em>back</em>
+behavior when users press the device's <em>Back</em> button. Upon reaching the beginning of the
+browser's internal history, you should always defer to the system's default behavior for the
+<em>Back</em> button.</p>
<h2 id="ancestral-navigation">Provide Ancestral Navigation: <em>Up</em> and <em>Home</em></h2>
-<p>Before Android 3.0, the most common form of ancestral navigation was the <em>Home</em> metaphor. This was generally implemented as a <em>Home</em> item accessible via the device's MENU button, or a <em>Home</em> button at the top-left of the screen, usually as a component of the Action Bar (<a href="{@docRoot}design/patterns/actionbar.html">pattern docs</a> at Android Design). Upon selecting <em>Home</em>, the user would be taken to the screen at the top of the screen hierarchy, generally known as the application's home screen.</p>
+<p>Before Android 3.0, the most common form of ancestral navigation was the <em>Home</em> metaphor.
+This was generally implemented as a <em>Home</em> item accessible via the device's <em>Menu</em>
+button, or a <em>Home</em> button at the top-left of the screen, usually as a component of the
+Action Bar (<a href="{@docRoot}design/patterns/actionbar.html">pattern docs</a> at Android Design).
+Upon selecting <em>Home</em>, the user would be taken to the screen at the top of the screen
+hierarchy, generally known as the application's home screen.</p>
<p>Providing direct access to the application's home screen can give the user a sense of comfort and security. Regardless of where they are in the application, if they get lost in the app, they can select <em>Home</em> to arrive back at the familiar home screen.</p>
-<p>Android 3.0 introduced the <em>Up</em> metaphor, which is presented in the Action Bar as a substitute for the <em>Home</em> button described above. Upon tapping <em>Up</em>, the user should be taken to the parent screen in the hierarchy. This navigation step is usually the previous screen (as described with the BACK button discussion above), but this is not universally the case. Thus, developers must ensure that <em>Up</em> for each screen navigates to a single, predetermined parent screen.</p>
+<p>Android 3.0 introduced the <em>Up</em> metaphor, which is presented in the Action Bar as a
+substitute for the <em>Home</em> button described above. Upon tapping <em>Up</em>, the user should
+be taken to the parent screen in the hierarchy. This navigation step is usually the previous screen
+(as described with the <em>Back</em> button discussion above), but this is not universally the case.
+Thus, developers must ensure that <em>Up</em> for each screen navigates to a single, predetermined
+parent screen.</p>
<img src="{@docRoot}images/training/app-navigation-ancestral-navigate-up.png"
@@ -70,6 +98,12 @@
<p>In some cases, it's appropriate for <em>Up</em> to perform an action rather than navigating to a parent screen. Take for example, the Gmail application for Android 3.0-based tablets. When viewing a mail conversation while holding the device in landscape, the conversation list, as well as the conversation details are presented side-by-side. This is a form of parent-child screen grouping, as discussed in a <a href="multiple-sizes.html">previous lesson</a>. However, when viewing a mail conversation in the portrait orientation, only the conversation details are shown. The <em>Up</em> button is used to temporarily show the parent pane, which slides in from the left of the screen. Pressing the <em>Up</em> button again while the left pane is visible exits the context of the individual conversation, up to a full-screen list of conversations.</p>
-<p class="note"><strong>Implementation Note:</strong> As a best practice, when implementing either <em>Home</em> or <em>Up</em>, make sure to clear the back stack of any descendent screens. For <em>Home</em>, the only remaining screen on the back stack should be the home screen. For <em>Up</em> navigation, the current screen should be removed from the back stack, unless BACK navigates across screen hierarchies. You can use the {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP} and {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK} intent flags together to achieve this.</p>
+<p class="note"><strong>Implementation Note:</strong> As a best practice, when implementing either
+<em>Home</em> or <em>Up</em>, make sure to clear the back stack of any descendent screens. For
+<em>Home</em>, the only remaining screen on the back stack should be the home screen. For
+<em>Up</em> navigation, the current screen should be removed from the back stack, unless
+<em>Back</em> navigates across screen hierarchies. You can use the {@link
+android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP} and {@link
+android.content.Intent#FLAG_ACTIVITY_NEW_TASK} intent flags together to achieve this.</p>
<p>In the last lesson, we apply the concepts discussed in all of the lessons so far to create interaction design wireframes for our example news application.</p>
diff --git a/docs/html/training/design-navigation/descendant-lateral.jd b/docs/html/training/design-navigation/descendant-lateral.jd
index 0064bd4..2d97e40 100644
--- a/docs/html/training/design-navigation/descendant-lateral.jd
+++ b/docs/html/training/design-navigation/descendant-lateral.jd
@@ -117,7 +117,16 @@
<p class="img-caption"><strong>Figure 5.</strong> Example phone and tablet tab-based navigation interfaces with relevant screen map excerpt.</p>
-<p>Several best practices apply when using tabs. Tabs should be persistent across immediate related screens. Only the designated content region should change when selecting a tab, and tab indicators should remain available at all times. Additionally, tab switches should not be treated as history. For example, if a user switches from a tab <em>A</em> to another tab <em>B</em>, pressing the BACK button (more on that in the <a href="ancestral-temporal.html">next lesson</a>) should not re-select tab <em>A</em>. Tabs are usually laid out horizontally, although other presentations of tab navigation such as using a drop-down list in the Action Bar (<a href="{@docRoot}design/patterns/actionbar.html">pattern docs</a> at Android Design) are sometimes appropriate. Lastly, and most importantly, <em>tabs should always run along the top of the screen</em>, and should not be aligned to the bottom of the screen.</p>
+<p>Several best practices apply when using tabs. Tabs should be persistent across immediate related
+screens. Only the designated content region should change when selecting a tab, and tab indicators
+should remain available at all times. Additionally, tab switches should not be treated as history.
+For example, if a user switches from a tab <em>A</em> to another tab <em>B</em>, pressing the
+<em>Back</em> button (more on that in the <a href="ancestral-temporal.html">next lesson</a>) should
+not re-select tab <em>A</em>. Tabs are usually laid out horizontally, although other presentations
+of tab navigation such as using a drop-down list in the Action Bar (<a
+href="{@docRoot}design/patterns/actionbar.html">pattern docs</a> at Android Design) are sometimes
+appropriate. Lastly, and most importantly, <em>tabs should always run along the top of the
+screen</em>, and should not be aligned to the bottom of the screen.</p>
<p>There are some obvious immediate benefits of tabs over simpler list- and button-based navigation:</p>
diff --git a/docs/html/training/design-navigation/index.jd b/docs/html/training/design-navigation/index.jd
index cb20a60..af60717 100644
--- a/docs/html/training/design-navigation/index.jd
+++ b/docs/html/training/design-navigation/index.jd
@@ -41,7 +41,9 @@
<dd>Learn about techniques for allowing users to navigate deep into, as well as across, your content hierarchy. Also learn about pros and cons of, and best practices for, specific navigational UI elements for various situations.</dd>
<dt><strong><a href="ancestral-temporal.html">Providing Ancestral and Temporal Navigation</a></strong></dt>
- <dd>Learn how to allow users to navigate upwards in the content hierarchy. Also learn about best practices for the BACK button and temporal navigation, or navigation to previous screens that may not be hierarchically related.</dd>
+ <dd>Learn how to allow users to navigate upwards in the content hierarchy. Also learn about best
+practices for the <em>Back</em> button and temporal navigation, or navigation to previous screens
+that may not be hierarchically related.</dd>
<dt><strong><a href="wireframing.html">Putting it All Together: Wireframing the Example App</a></strong></dt>
<dd>Learn how to create screen wireframes (low-fidelity graphic mockups) representing the screens in a news application based on the desired information model. These wireframes utilize navigational elements discussed in previous lessons to demonstrate intuitive and efficient navigation.</dd>
diff --git a/tests/RenderScriptTests/ImageProcessing/src/com/android/rs/image/ImageProcessingTest.java b/tests/RenderScriptTests/ImageProcessing/src/com/android/rs/image/ImageProcessingTest.java
index f96e68b..912d863 100644
--- a/tests/RenderScriptTests/ImageProcessing/src/com/android/rs/image/ImageProcessingTest.java
+++ b/tests/RenderScriptTests/ImageProcessing/src/com/android/rs/image/ImageProcessingTest.java
@@ -84,7 +84,7 @@
Log.v(TAG, "RenderScript framew time core: " + t + " ms");
}
long avgValue = sum/ITERATION;
- rsWriter.write("Averge frame time: " + avgValue + " ms\n");
+ rsWriter.write("Average frame time: " + avgValue + " ms\n");
Log.v(TAG, "Average frame time: " + avgValue + " ms");
rsWriter.close();
} catch (IOException e) {
diff --git a/tools/aapt/XMLNode.cpp b/tools/aapt/XMLNode.cpp
index c0d7427..95a68d1 100644
--- a/tools/aapt/XMLNode.cpp
+++ b/tools/aapt/XMLNode.cpp
@@ -45,6 +45,7 @@
static const String16 RESOURCES_PREFIX(RESOURCES_ROOT_NAMESPACE);
static const String16 RESOURCES_PRV_PREFIX(RESOURCES_ROOT_PRV_NAMESPACE);
+static const String16 RESOURCES_TOOLS_NAMESPACE("http://schemas.android.com/tools");
String16 getNamespaceResourcePackage(String16 namespaceUri, bool* outIsPublic)
{
@@ -761,13 +762,16 @@
SourcePos(mFilename, getStartLineNumber()).error("Child to CDATA node.");
return UNKNOWN_ERROR;
}
- attribute_entry e;
- e.index = mNextAttributeIndex++;
- e.ns = ns;
- e.name = name;
- e.string = value;
- mAttributes.add(e);
- mAttributeOrder.add(e.index, mAttributes.size()-1);
+
+ if (ns != RESOURCES_TOOLS_NAMESPACE) {
+ attribute_entry e;
+ e.index = mNextAttributeIndex++;
+ e.ns = ns;
+ e.name = name;
+ e.string = value;
+ mAttributes.add(e);
+ mAttributeOrder.add(e.index, mAttributes.size()-1);
+ }
return NO_ERROR;
}
@@ -1215,11 +1219,13 @@
collect_attr_strings(dest, outResIds, true);
int i;
- if (mNamespacePrefix.size() > 0) {
- dest->add(mNamespacePrefix, true);
- }
- if (mNamespaceUri.size() > 0) {
- dest->add(mNamespaceUri, true);
+ if (RESOURCES_TOOLS_NAMESPACE != mNamespaceUri) {
+ if (mNamespacePrefix.size() > 0) {
+ dest->add(mNamespacePrefix, true);
+ }
+ if (mNamespaceUri.size() > 0) {
+ dest->add(mNamespaceUri, true);
+ }
}
if (mElementName.size() > 0) {
dest->add(mElementName, true);
@@ -1338,6 +1344,7 @@
const void* extData = NULL;
size_t extSize = 0;
ResXMLTree_attribute attr;
+ bool writeCurrentNode = true;
const size_t NA = mAttributes.size();
const size_t NC = mChildren.size();
@@ -1350,7 +1357,7 @@
const String16 style16("style");
const type type = getType();
-
+
memset(&node, 0, sizeof(node));
memset(&attr, 0, sizeof(attr));
node.header.headerSize = htods(sizeof(node));
@@ -1395,17 +1402,21 @@
}
}
} else if (type == TYPE_NAMESPACE) {
- node.header.type = htods(RES_XML_START_NAMESPACE_TYPE);
- extData = &namespaceExt;
- extSize = sizeof(namespaceExt);
- memset(&namespaceExt, 0, sizeof(namespaceExt));
- if (mNamespacePrefix.size() > 0) {
- namespaceExt.prefix.index = htodl(strings.offsetForString(mNamespacePrefix));
+ if (mNamespaceUri == RESOURCES_TOOLS_NAMESPACE) {
+ writeCurrentNode = false;
} else {
- namespaceExt.prefix.index = htodl((uint32_t)-1);
+ node.header.type = htods(RES_XML_START_NAMESPACE_TYPE);
+ extData = &namespaceExt;
+ extSize = sizeof(namespaceExt);
+ memset(&namespaceExt, 0, sizeof(namespaceExt));
+ if (mNamespacePrefix.size() > 0) {
+ namespaceExt.prefix.index = htodl(strings.offsetForString(mNamespacePrefix));
+ } else {
+ namespaceExt.prefix.index = htodl((uint32_t)-1);
+ }
+ namespaceExt.prefix.index = htodl(strings.offsetForString(mNamespacePrefix));
+ namespaceExt.uri.index = htodl(strings.offsetForString(mNamespaceUri));
}
- namespaceExt.prefix.index = htodl(strings.offsetForString(mNamespacePrefix));
- namespaceExt.uri.index = htodl(strings.offsetForString(mNamespaceUri));
LOG_ALWAYS_FATAL_IF(NA != 0, "Namespace nodes can't have attributes!");
} else if (type == TYPE_CDATA) {
node.header.type = htods(RES_XML_CDATA_TYPE);
@@ -1422,9 +1433,11 @@
node.header.size = htodl(sizeof(node) + extSize + (sizeof(attr)*NA));
- dest->writeData(&node, sizeof(node));
- if (extSize > 0) {
- dest->writeData(extData, extSize);
+ if (writeCurrentNode) {
+ dest->writeData(&node, sizeof(node));
+ if (extSize > 0) {
+ dest->writeData(extData, extSize);
+ }
}
for (i=0; i<NA; i++) {
@@ -1476,12 +1489,14 @@
dest->writeData(&node, sizeof(node));
dest->writeData(&endElementExt, sizeof(endElementExt));
} else if (type == TYPE_NAMESPACE) {
- node.header.type = htods(RES_XML_END_NAMESPACE_TYPE);
- node.lineNumber = htodl(getEndLineNumber());
- node.comment.index = htodl((uint32_t)-1);
- node.header.size = htodl(sizeof(node)+extSize);
- dest->writeData(&node, sizeof(node));
- dest->writeData(extData, extSize);
+ if (writeCurrentNode) {
+ node.header.type = htods(RES_XML_END_NAMESPACE_TYPE);
+ node.lineNumber = htodl(getEndLineNumber());
+ node.comment.index = htodl((uint32_t)-1);
+ node.header.size = htodl(sizeof(node)+extSize);
+ dest->writeData(&node, sizeof(node));
+ dest->writeData(extData, extSize);
+ }
}
return NO_ERROR;
diff --git a/tools/layoutlib/bridge/resources/bars/action_bar.xml b/tools/layoutlib/bridge/resources/bars/action_bar.xml
index 51983f2..7adc5af 100644
--- a/tools/layoutlib/bridge/resources/bars/action_bar.xml
+++ b/tools/layoutlib/bridge/resources/bars/action_bar.xml
@@ -1,9 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<merge xmlns:android="http://schemas.android.com/apk/res/android">
- <ImageView
- android:layout_height="wrap_content"
- android:layout_width="wrap_content"/>
- <TextView
- android:layout_width="wrap_content"
- android:layout_height="wrap_content"/>
+ <include layout="@android:layout/action_bar_home" />
+ <TextView
+ android:layout_width="wrap_content"
+ android:layout_height="wrap_content"/>
</merge>
diff --git a/tools/layoutlib/bridge/src/android/graphics/Matrix_Delegate.java b/tools/layoutlib/bridge/src/android/graphics/Matrix_Delegate.java
index 451edd2..5df2a21 100644
--- a/tools/layoutlib/bridge/src/android/graphics/Matrix_Delegate.java
+++ b/tools/layoutlib/bridge/src/android/graphics/Matrix_Delegate.java
@@ -474,7 +474,7 @@
}
Matrix_Delegate other = sManager.getDelegate(other_matrix);
- if (d == null) {
+ if (other == null) {
return false;
}
@@ -570,7 +570,7 @@
}
Matrix_Delegate other = sManager.getDelegate(other_matrix);
- if (d == null) {
+ if (other == null) {
return false;
}
diff --git a/tools/layoutlib/bridge/src/com/android/layoutlib/bridge/bars/CustomBar.java b/tools/layoutlib/bridge/src/com/android/layoutlib/bridge/bars/CustomBar.java
index 72ed351..cd4fbfe 100644
--- a/tools/layoutlib/bridge/src/com/android/layoutlib/bridge/bars/CustomBar.java
+++ b/tools/layoutlib/bridge/src/com/android/layoutlib/bridge/bars/CustomBar.java
@@ -145,6 +145,14 @@
}
}
+ protected void loadIconById(int id, String iconReference) {
+ ResourceValue value = getResourceValue(iconReference);
+ if (value != null) {
+ loadIconById(id, value);
+ }
+ }
+
+
protected Drawable loadIcon(int index, ResourceType type, String name) {
BridgeContext bridgeContext = (BridgeContext) mContext;
RenderResources res = bridgeContext.getRenderResources();
@@ -162,34 +170,64 @@
if (child instanceof ImageView) {
ImageView imageView = (ImageView) child;
- Drawable drawable = ResourceHelper.getDrawable(
- value, (BridgeContext) mContext);
- if (drawable != null) {
- imageView.setBackgroundDrawable(drawable);
- }
-
- return drawable;
+ return loadIcon(imageView, value);
}
return null;
}
+ private Drawable loadIconById(int id, ResourceValue value) {
+ View child = findViewById(id);
+ if (child instanceof ImageView) {
+ ImageView imageView = (ImageView) child;
+
+ return loadIcon(imageView, value);
+ }
+
+ return null;
+ }
+
+
+ private Drawable loadIcon(ImageView imageView, ResourceValue value) {
+ Drawable drawable = ResourceHelper.getDrawable(value, (BridgeContext) mContext);
+ if (drawable != null) {
+ imageView.setImageDrawable(drawable);
+ }
+
+ return drawable;
+ }
+
protected TextView setText(int index, String stringReference) {
View child = getChildAt(index);
if (child instanceof TextView) {
TextView textView = (TextView) child;
- ResourceValue value = getResourceValue(stringReference);
- if (value != null) {
- textView.setText(value.getValue());
- } else {
- textView.setText(stringReference);
- }
+ setText(textView, stringReference);
return textView;
}
return null;
}
+ protected TextView setTextById(int id, String stringReference) {
+ View child = findViewById(id);
+ if (child instanceof TextView) {
+ TextView textView = (TextView) child;
+ setText(textView, stringReference);
+ return textView;
+ }
+
+ return null;
+ }
+
+ private void setText(TextView textView, String stringReference) {
+ ResourceValue value = getResourceValue(stringReference);
+ if (value != null) {
+ textView.setText(value.getValue());
+ } else {
+ textView.setText(stringReference);
+ }
+ }
+
protected void setStyle(String themeEntryName) {
BridgeContext bridgeContext = (BridgeContext) mContext;
diff --git a/tools/layoutlib/bridge/src/com/android/layoutlib/bridge/bars/FakeActionBar.java b/tools/layoutlib/bridge/src/com/android/layoutlib/bridge/bars/FakeActionBar.java
index f6edea4..68f5aba 100644
--- a/tools/layoutlib/bridge/src/com/android/layoutlib/bridge/bars/FakeActionBar.java
+++ b/tools/layoutlib/bridge/src/com/android/layoutlib/bridge/bars/FakeActionBar.java
@@ -34,7 +34,7 @@
// Cannot access the inside items through id because no R.id values have been
// created for them.
// We do know the order though.
- loadIcon(0, icon);
+ loadIconById(android.R.id.home, icon);
mTextView = setText(1, label);
setStyle("actionBarStyle");