diff options
Diffstat (limited to 'docs/html/guide/topics/ui')
| -rw-r--r-- | docs/html/guide/topics/ui/accessibility/apps.jd | 574 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/accessibility/index.jd | 55 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/accessibility/services.jd | 290 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/actionbar.jd | 56 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/declaring-layout.jd | 2 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/dialogs.jd | 12 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/index.jd | 5 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/layout-objects.jd | 2 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/menus.jd | 1008 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/notifiers/notifications.jd | 143 |
10 files changed, 1797 insertions, 350 deletions
diff --git a/docs/html/guide/topics/ui/accessibility/apps.jd b/docs/html/guide/topics/ui/accessibility/apps.jd new file mode 100644 index 0000000..dc91638 --- /dev/null +++ b/docs/html/guide/topics/ui/accessibility/apps.jd @@ -0,0 +1,574 @@ +page.title=Making Applications Accessible +parent.title=Accessibility +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>In this document</h2> + <ol> + <li><a href="#label-ui">Labeling User Interface Elements</a></li> + <li><a href="#focus-nav">Enabling Focus Navigation</a> + <ol> + <li><a href="#focus-enable">Enabling view focus</a></li> + <li><a href="#focus-order">Controlling focus order</a></li> + </ol> + </li> + <li><a href="#custom-views">Building Accessible Custom Views</a> + <ol> + <li><a href="#directional-control">Handling directional controller clicks</a></li> + <li><a href="#accessibility-methods">Implementing accessibility API methods</a></li> + <li><a href="#send-events">Sending accessibility events</a></li> + <li><a href="#populate-events">Populating accessibility events</a></li> + </ol> + </li> + <li><a href="#test">Testing Accessibility</a> + <ol> + <li><a href="#test-audibles">Testing audible feedback</a></li> + <li><a href="#test-navigation">Testing focus navigation</a></li> + </ol> + </li> + </ol> + + <h2>Key classes</h2> + <ol> + <li>{@link android.view.accessibility.AccessibilityEvent}</li> + <li>{@link android.view.accessibility.AccessibilityNodeInfo}</li> + <li>{@link android.support.v4.view.accessibility.AccessibilityNodeInfoCompat}</li> + <li>{@link android.view.View.AccessibilityDelegate}</li> + <li>{@link android.support.v4.view.AccessibilityDelegateCompat}</li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}training/accessibility/index.html">Implementing Accessibility</a></li> + <li><a href="{@docRoot}training/design-navigation/index.html">Designing Effective Navigation</a> + </li> + <li><a href="{@docRoot}design/index.html">Android Design</a></li> + </ol> + +</div> +</div> + +<p>Applications built for Android are accessible to users with visual, physical or age-related +disabilities when they activate accessibility features and services on a device. By default, +these services make your application more accessible. However, there are further steps you should +take to optimize the accessibility of your application and ensure a pleasant experience for all your +users.</p> + +<p>Making sure your application is accessible to all users is relatively easy, particularly when you +use framework-provided user interface components. If you only use these standard components for your +application, there are just a few steps required to ensure your application is accessible:</p> + +<ol> + <li>Label your {@link android.widget.ImageButton}, {@link android.widget.ImageView}, {@link +android.widget.EditText}, {@link android.widget.CheckBox} and other user interface controls using +the <a href="{@docRoot}reference/android/view/View.html#attr_android:contentDescription"> + {@code android:contentDescription}</a> attribute.</li> + <li>Make all of your user interface elements accessible with a directional controller, + such as a trackball or D-pad.</li> + <li>Test your application by turning on accessibility services like TalkBack and Explore by + Touch, and try using your application using only directional controls.</li> +</ol> + +<p>Developers who create custom controls that extend from the {@link android.view.View} class have +some additional responsibilities for making sure their components are accessible for users. This +document also discusses how to make custom view controls compatible with accessibility services.</p> + + +<h2 id="label-ui">Labeling User Interface Elements</h2> + +<p>Many user interface controls rely on visual cues to inform users of their meaning. For +example, a note-taking application might use an {@link android.widget.ImageButton} with a +picture of a plus sign to indicate that the user can add a new note. Or, an {@link +android.widget.EditText} component may have a label near it that indicates its purpose. When a user +with impaired vision accesses your application, these visual cues are often useless.</p> + +<p>To provide textual information about interface controls (as an alternative to the visual cues), +use the <a href="{@docRoot}reference/android/view/View.html#attr_android:contentDescription"> +{@code android:contentDescription}</a> attribute. The text you provide in this attribute is not +visible on the screen, but if a user has enabled accessibility services that provide audible +prompts, then the description in this attribute is read aloud to the user.</p> + +<p>Set the <a href="{@docRoot}reference/android/view/View.html#attr_android:contentDescription"> +{@code android:contentDescription}</a> attribute for every {@link android.widget.ImageButton}, +{@link android.widget.ImageView}, {@link android.widget.EditText}, {@link android.widget.CheckBox} +in your application's user interface, and on any other input controls that might require additional +information for users who are not able to see it.</p> + +<p>For example, the following {@link android.widget.ImageButton} sets the content description for +the plus button to the {@code add_note} string resource, which could be defined as “Add note" for an +English language interface:</p> + +<pre> +<ImageButton + android:id=”@+id/add_note_button” + android:src=”@drawable/add_note” + android:contentDescription=”@string/add_note”/> +</pre> + +<p>By including the description, speech-based accessibility services can announce "Add note" when a +user moves focus to this button or hovers over it.</p> + +<p class="note"><strong>Note:</strong> For {@link android.widget.EditText} fields, provide an +<a href="{@docRoot}reference/android/widget/TextView.html#attr_android:hint">android:hint</a> +attribute to help users understand what content is expected.</p> + +<h2 id="focus-nav">Enabling Focus Navigation</h2> + +<p>Focus navigation allows users with disabilities to step through user interface controls using a +directional controller. Directional controllers can be physical, such as a clickable trackball, +directional pad (D-pad) or arrow keys, tab key navigation with an attached keyboard or a software +application, such as the +<a href="https://play.google.com/store/apps/details?id=com.googlecode.eyesfree.inputmethod.latin"> +Eyes-Free Keyboard</a>, that provides an on-screen directional control.</p> + +<p>A directional controller is a primary means of navigation for many users. +Verify that all user interface (UI) controls in your application are accessible +without using the touchscreen and that clicking with the center button (or OK button) of a +directional controller has the same effect as touching the controls on the touchscreen. For +information on testing directional controls, see <a href="#test-navigation">Testing focus +navigation</a>.</p> + +<h3 id="focus-enable">Enabling view focus</h3> + +<p>A user interface element is accessible using directional controls when its +<a href="{@docRoot}reference/android/view/View.html#attr_android:focusable"> +{@code android:focusable}</a> attribute is set to {@code true}. This setting allows users to focus +on the element using the directional controls and then interact with it. The user interface controls +provided by the Android framework are focusable by default and visually indicate focus by changing +the control’s appearance.</p> + +<p>Android provides several APIs that let you control whether a user interface control is focusable +and even request that a control be given focus:</p> + +<ul> + <li>{@link android.view.View#setFocusable setFocusable()}</li> + <li>{@link android.view.View#isFocusable isFocusable()}</li> + <li>{@link android.view.View#requestFocus requestFocus()}</li> +</ul> + +<p>When working with a view that is not focusable by default, you can make it focusable from the XML +layout file by setting the +<a href="{@docRoot}reference/android/view/View.html#attr_android:focusable"> +{@code android:focusable}</a> attribute to {@code true} or by using the {@link +android.view.View#setFocusable setFocusable()} method.</p> + +<h3 id="focus-order">Controlling focus order</h3> + +<p>When users navigate in any direction using directional controls, focus is passed from one +user interface element (View) to another, as determined by the focus ordering. The ordering of the +focus movement is based on an algorithm that finds the nearest neighbor in a given direction. In +rare cases, the default algorithm may not match the order that you intended for your UI. In these +situations, you can provide explicit overrides to the ordering using the following XML attributes in +the layout file:</p> + +<dl> + <dt><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusDown" +>{@code android:nextFocusDown}</a></dt> + <dd>Defines the next view to receive focus when the user navigates down.</dd> + <a><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusLeft" +>{@code android:nextFocusLeft}</a></dt> + <dd>Defines the next view to receive focus when the user navigates left.</dd> + <dt><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusRight" +>{@code android:nextFocusRight}</a></dt> + <dd>Defines the next view to receive focus when the user navigates right.</dd> + <dt><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusUp" +>{@code android:nextFocusUp}</a></dt> + <dd>Defines the next view to receive focus when the user navigates up.</dd> +</dl> + +<p>The following example XML layout shows two focusable user interface elements where the <a +href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusDown" +>{@code android:nextFocusDown}</a> and <a +href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusUp" +>{@code android:nextFocusUp}</a> attributes have been explicitly set. The {@link android.widget.TextView} is +located to the right of the {@link android.widget.EditText}. However, since these properties have +been set, the {@link android.widget.TextView} element can now be reached by pressing the down arrow +when focus is on the {@link android.widget.EditText} element: </p> + +<pre> +<LinearLayout android:orientation="horizontal" + ... > + <EditText android:id="@+id/edit" + android:nextFocusDown=”@+id/text” + ... /> + <TextView android:id="@+id/text" + android:focusable=”true” + android:text="Hello, I am a focusable TextView" + android:nextFocusUp=”@id/edit” + ... /> +</LinearLayout> +</pre> + +<p>When modifying focus order, be sure that the navigation works as expected in all directions from +each user interface control and when navigating in reverse (to get back to where you came from).</p> + +<p class="note"><strong>Note:</strong> You can modify the focus order of user interface components +at runtime, using methods such as {@link android.view.View#setNextFocusDownId setNextFocusDownId()} +and {@link android.view.View#setNextFocusRightId setNextFocusRightId()}.</p> + + +<h2 id="custom-views">Building Accessible Custom Views</h2> + +<p>If your application requires a <a href="{@docRoot}guide/topics/ui/custom-components.html">custom +view component</a>, you must do some additional work to ensure that your custom view is accessible. +These are the main tasks for ensuring the accessibility of your view:</p> + +<ul> + <li>Handle directional controller clicks</li> + <li>Implement Accessibility API methods</li> + <li>Send {@link android.view.accessibility.AccessibilityEvent} objects specific to your custom view</li> + <li>Populate {@link android.view.accessibility.AccessibilityEvent} and {@link + android.view.accessibility.AccessibilityNodeInfo} for your view</li> +</ul> + + +<h3 id="directional-control">Handling directional controller clicks</h3> + +<p>On most devices, clicking a view using a directional controller sends a {@link +android.view.KeyEvent} with {@link android.view.KeyEvent#KEYCODE_DPAD_CENTER} to the view currently +in focus. All standard Android views already handle {@link +android.view.KeyEvent#KEYCODE_DPAD_CENTER} appropriately. When building a custom {@link +android.view.View} control, make sure this event has the same effect as touching the view on the +touchscreen. </p> + +<p>Your custom control should also treat the {@link android.view.KeyEvent#KEYCODE_ENTER} event the +same as {@link android.view.KeyEvent#KEYCODE_DPAD_CENTER}. This approach makes interaction from a +full keyboard much easier for users.</p> + + +<h3 id="accessibility-methods">Implementing accessibility API methods</h3> + +<p>Accessibility events are messages about users interaction with visual interface components in +your application. These messages are handled by <a href="services.html">Accessibility Services</a>, +which use the information in these events to produce supplemental feedback and prompts when users +have enabled accessibility services. As of Android 4.0 (API Level 14) and higher, the methods for +generating accessibility events have been expanded to provide more detailed information beyond the +{@link android.view.accessibility.AccessibilityEventSource} interface introduced in Android 1.6 (API +Level 4). The expanded accessibility methods are part of the {@link android.view.View} class as well +as the {@link android.view.View.AccessibilityDelegate} class. The methods are as follows:</p> + +<dl> + <dt>{@link android.view.View#sendAccessibilityEvent sendAccessibilityEvent()}</dt> + <dd>(API Level 4) This method is called when a user takes action on a view. The event is +classified with a user action type such as {@link +android.view.accessibility.AccessibilityEvent#TYPE_VIEW_CLICKED TYPE_VIEW_CLICKED}. You typically do +not need to implement this method unless you are creating a custom view.</dd> + + <dt>{@link android.view.View#sendAccessibilityEventUnchecked +sendAccessibilityEventUnchecked()}</dt> + <dd>(API Level 4) This method is used when the calling code needs to directly control the check +for accessibility being enabled on the device ({@link +android.view.accessibility.AccessibilityManager#isEnabled AccessibilityManager.isEnabled()}). If +you do implement this method, you must assume that the calling method has already checked that +accessibility is enabled and the result is {@code true}. You typically do not need to implement this +method for a custom view.</dd> + + <dt>{@link android.view.View#dispatchPopulateAccessibilityEvent +dispatchPopulateAccessibilityEvent()} </dt> + <dd>(API Level 4) The system calls this method when your custom view generates an +accessibility event. As of API Level 14, the default implementation of this method calls {@link +android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} for this view and +then the {@link android.view.View#dispatchPopulateAccessibilityEvent +dispatchPopulateAccessibilityEvent()} method for each child of this view. In order to support +accessibility services on revisions of Android <em>prior</em> to 4.0 (API Level 14) you +<em>must</em> override this method and populate {@link +android.view.accessibility.AccessibilityEvent#getText} with descriptive text for your custom +view.</dd> + + <dt>{@link android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()}</dt> + <dd>(API Level 14) This method sets the text output of an {@link +android.view.accessibility.AccessibilityEvent} for your view. This method is also called if the +view is a child of a view which generates an accessibility event. + + <p class="note"><strong>Note:</strong> Modifying additional attributes beyond the text within +this method potentially overwrites properties set by other methods. So, while you are able modify +attributes of the accessibility event with this method, you should limit these changes +to text content only and use the {@link android.view.View#onInitializeAccessibilityEvent +onInitializeAccessibilityEvent()} method to modify other properties of the event.</p> + + <p class="note"><strong>Note:</strong> If your implementation of this event calls for completely +overiding the output text without allowing other parts of your layout to modify its content, then +do not call the super implementation of this method in your code.</p> + </dd> + + <dt>{@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()}</dt> + <dd>(API Level 14) The system calls this method to obtain additional information about the +state of the view, beyond text content. If your custom view provides interactive control beyond a +simple {@link android.widget.TextView} or {@link android.widget.Button}, you should override this +method and set the additional information about your view into the event using this method, such as +password field type, checkbox type or states that provide user interaction or feedback. If you +do override this method, you must call its super implementation and then only modify properties +that have not been set by the super class.</dd> + + <dt>{@link android.view.View#onInitializeAccessibilityNodeInfo +onInitializeAccessibilityNodeInfo()}</dt> + <dd>(API Level 14) This method provides accessibility services with information about the state of +the view. The default {@link android.view.View} implementation sets a standard set of view +properties, but if your custom view provides interactive control beyond a simple {@link +android.widget.TextView} or {@link android.widget.Button}, you should override this method and set +the additional information about your view into the {@link +android.view.accessibility.AccessibilityNodeInfo} object handled by this method.</dd> + + <dt>{@link android.view.ViewGroup#onRequestSendAccessibilityEvent +onRequestSendAccessibilityEvent()}</dt> + <dd>(API Level 14) The system calls this method when a child of your view has generated an +{@link android.view.accessibility.AccessibilityEvent}. This step allows the the parent view to amend +the accessibility event with additional information. You should implement this method only if your +custom view can have child views and if the parent view can provide context information to the +accessibility event that would be useful to accessibility services.</dd> +</dl> + +<p>In order to support these accessibility methods for a custom view, you should take one of the +following approaches:</p> + +<ul> + <li>If your application targets Android 4.0 (API level 14) and higher, override and implement the +accessibility methods listed above directly in your custom view class.</li> + <li>If your custom view is intended to be compatible with Android 1.6 (API Level 4) and above, add +the Android <a href="{@docRoot}sdk/compatibility-library.html">Support Library</a>, revision 5 or +higher, to your project. Then, within your custom view class, call the +{@link android.support.v4.view.ViewCompat#setAccessibilityDelegate +ViewCompat.setAccessibilityDelegate()} method to implement the accessibility methods +above. For an example of this approach, see the Android Support Library (revision 5 or higher) +sample {@code AccessibilityDelegateSupportActivity} in +({@code <sdk>/extras/android/support/v4/samples/Support4Demos/}) + </li> +</ul> + +<p>In either case, you should implement the following accessibility methods for your custom view +class:</p> + +<ul> + <li>{@link android.view.View#dispatchPopulateAccessibilityEvent + dispatchPopulateAccessibilityEvent()}</li> + <li>{@link android.view.View#onPopulateAccessibilityEvent + onPopulateAccessibilityEvent()}</li> + <li>{@link android.view.View#onInitializeAccessibilityEvent + onInitializeAccessibilityEvent()}</li> + <li>{@link android.view.View#onInitializeAccessibilityNodeInfo + onInitializeAccessibilityNodeInfo()}</li> +</ul> + +<p>For more information about implementing these methods, see <a href="#populate-events">Populating +Accessibility Events</a>.</p> + + +<h3 id="send-events">Sending accessibility events</h3> + +<p>Depending on the specifics of your custom view, it may need to send {@link +android.view.accessibility.AccessibilityEvent} objects at a different times or for events not +handled by the default implementation. The {@link android.view.View} class provides a default +implementation for these event types:</p> + +<ul> + <li>Starting with API Level 4: + <ul> + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_CLICKED}</li> + + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_LONG_CLICKED}</li> + + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_FOCUSED}</li> + </ul> + </li> + <li>Starting with API Level 14: + <ul> + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_SCROLLED}</li> + + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_HOVER_ENTER}</li> + + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_HOVER_EXIT}</li> + </ul> + </li> +</ul> + +<p class="note"><strong>Note:</strong> Hover events are associated with the Explore by +Touch feature, which uses these events as triggers for providing audible prompts for user interface +elements.</p> + +<p>In general, you should send an {@link android.view.accessibility.AccessibilityEvent} whenever the +content of your custom view changes. For example, if you are implementing a custom slider bar that +allows a user to select a numeric value by pressing the left or right arrows, your custom view +should emit an event of type {@link +android.view.accessibility.AccessibilityEvent#TYPE_VIEW_TEXT_CHANGED} whenever the slider +value changes. The following sample code demonstrates the use of the {@link +android.view.accessibility.AccessibilityEventSource#sendAccessibilityEvent +sendAccessibilityEvent()} method to report this event.</p> + +<pre> +@Override +public boolean onKeyUp (int keyCode, KeyEvent event) { + if (keyCode == KeyEvent.KEYCODE_DPAD_LEFT) { + mCurrentValue--; + sendAccessibilityEvent(AccessibilityEvent.TYPE_VIEW_TEXT_CHANGED); + return true; + } + ... +} +</pre> + + +<h3 id="populate-events">Populating accessibility events</h3> + +<p>Each {@link android.view.accessibility.AccessibilityEvent} has a set of required properties that +describe the current state of the view. These properties include things such as the view’s class +name, content description and checked state. The specific properties required for each event type +are described in the {@link android.view.accessibility.AccessibilityEvent} reference documentation. +The {@link android.view.View} implementation provides default values for these properties. Many of +these values, including the class name and event timestamp, are provided automatically. If you are +creating a custom view component, you must provide some information about the content and +characteristics of the view. This information may be as simple as a button label, but may also +include additional state information that you want to add to the event.</p> + +<p>The minimum requirement for providing information to accessibility services with a custom +view is to implement {@link android.view.View#dispatchPopulateAccessibilityEvent +dispatchPopulateAccessibilityEvent()}. This method is called by the system to request +information for an {@link android.view.accessibility.AccessibilityEvent} and makes your custom +view compatible with accessibility services on Android 1.6 (API Level 4) and higher. The +following example code demonstrates a basic implementation of this method.</p> + +<pre> +@Override +public void dispatchPopulateAccessibilityEvent(AccessibilityEvent event) { + super.dispatchPopulateAccessibilityEvent(event); + // Call the super implementation to populate its text to the event, which + // calls onPopulateAccessibilityEvent() on API Level 14 and up. + + // In case this is running on a API revision earlier that 14, check + // the text content of the event and add an appropriate text + // description for this custom view: + CharSequence text = getText(); + if (!TextUtils.isEmpty(text)) { + event.getText().add(text); + } +} +</pre> + +<p>On Android 4.0 (API Level 14) and higher, the {@link +android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} and +{@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()} +methods are the recommended way to populate or modify the information in an {@link +android.view.accessibility.AccessibilityEvent}. Use the +{@link android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} method +specifically for adding or modifying the text content of the event, which is turned into audible +prompts by accessibility services such as TalkBack. Use the +{@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()} method for +populating additional information about the event, such as the selection state of the view.</p> + +<p>In addition, you should also implement the +{@link android.view.View#onInitializeAccessibilityNodeInfo onInitializeAccessibilityNodeInfo()} +method. {@link android.view.accessibility.AccessibilityNodeInfo} objects populated by this method +are used by accessibility services to investigate the view hierarchy that generated an accessibility +event after receiving that event, to obtain a more detailed context information and provide +appropriate feedback to users.</p> + +<p>The example code below shows how override these three methods by using +{@link android.support.v4.view.ViewCompat#setAccessibilityDelegate +ViewCompat.setAccessibilityDelegate()}. Note that this sample code requires that the Android +<a href="{@docRoot}sdk/compatibility-library.html">Support Library</a> for API Level 4 (revision 5 +or higher) is added to your project.</p> + +<pre> +ViewCompat.setAccessibilityDelegate(new AccessibilityDelegateCompat() { + @Override + public void onPopulateAccessibilityEvent(View host, AccessibilityEvent event) { + super.onPopulateAccessibilityEvent(host, event); + // We call the super implementation to populate its text for the + // event. Then we add our text not present in a super class. + // Very often you only need to add the text for the custom view. + CharSequence text = getText(); + if (!TextUtils.isEmpty(text)) { + event.getText().add(text); + } + } + @Override + public void onInitializeAccessibilityEvent(View host, AccessibilityEvent event) { + super.onInitializeAccessibilityEvent(host, event); + // We call the super implementation to let super classes + // set appropriate event properties. Then we add the new property + // (checked) which is not supported by a super class. + event.setChecked(isChecked()); + } + @Override + public void onInitializeAccessibilityNodeInfo(View host, + AccessibilityNodeInfoCompat info) { + super.onInitializeAccessibilityNodeInfo(host, info); + // We call the super implementation to let super classes set + // appropriate info properties. Then we add our properties + // (checkable and checked) which are not supported by a super class. + info.setCheckable(true); + info.setChecked(isChecked()); + // Quite often you only need to add the text for the custom view. + CharSequence text = getText(); + if (!TextUtils.isEmpty(text)) { + info.setText(text); + } + } +} +</pre> + +<p>On applications targeting Android 4.0 (API Level 14) and higher, these methods can be implemented +directly in your custom view class. For another example of this approach, see the Android +<a href="{@docRoot}sdk/compatibility-library.html">Support Library</a> (revision 5 or higher) sample +{@code AccessibilityDelegateSupportActivity} in +({@code <sdk>/extras/android/support/v4/samples/Support4Demos/}).</p> + +<p class="note"><strong>Note:</strong> You may find information on implementing accessibility for +custom views written prior to Android 4.0 that describes the use of the +{@link android.view.View#dispatchPopulateAccessibilityEvent dispatchPopulateAccessibilityEvent()} +method for populating AccessibilityEvents. As of the Android 4.0 release, however, the recommended +approach is to use the +{@link android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} and +{@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()} +methods.</p> + + +<h2 id="test">Testing Accessibility</h2> + +<p>Testing the accessibility of your application is an important part of ensuring your users have a +great experience. You can test the most important parts of accessibility by testing your application +with audible feedback enabled and testing navigation within your application using directional +controls.</p> + +<h3 id="test-audibles">Testing audible feedback</h3> +<p>You can simulate the experience for many users by enabling an accessibility service that speaks +as you move around the screen. The Explore by Touch accessibility service, which is available on +devices with Android 4.0 and later. The <a +href="https://play.google.com/store/apps/details?id=com.google.android.marvin.talkback">TalkBack</a> +accessibility service, by the <a href="http://code.google.com/p/eyes-free/">Eyes-Free +Project</a> comes preinstalled on many Android devices.</p> + +<p>To enable TalkBack on revisions of Android prior to Android 4.0:</p> +<ol> + <li>Launch the Settings application.</li> + <li>Navigate to the <strong>Accessibility</strong> category and select it.</li> + <li>Select <strong>Accessibility</strong> to enable it.</li> + <li>Select <strong>TalkBack</strong> to enable it.</li> +</ol> + +<p class="note"><strong>Note:</strong> If the TalkBack accessibility service is not available, you +can install it for free from <a href="http://play.google.com">Google Play</a>.</p> + +<p>To enable Explore by Touch on Android 4.0 and later:</p> +<ol> + <li>Launch the Settings application.</li> + <li>Navigate to the <strong>Accessibility</strong> category and select it.</li> + <li>Select the <strong>TalkBack</strong> to enable it.</li> + <li>Return to the <strong>Accessibility</strong> category and select <strong>Explore by +Touch</strong> to enable it. + <p class="note"><strong>Note:</strong> You must turn on TalkBack <em>first</em>, otherwise this +option is not available.</p> + </li> +</ol> + +<h3 id="test-navigation">Testing focus navigation</h3> + +<p>As part of your accessibility testing, you can test navigation of your application using focus, +even if your test devices does not have a directional controller. The <a +href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> provides a +simulated directional controller that you can easily use to test navigation. You can also use a +software-based directional controller, such as the one provided by the +<a href="https://play.google.com/store/apps/details?id=com.googlecode.eyesfree.inputmethod.latin"> +Eyes-Free Keyboard</a> to simulate use of a D-pad.</p> diff --git a/docs/html/guide/topics/ui/accessibility/index.jd b/docs/html/guide/topics/ui/accessibility/index.jd new file mode 100644 index 0000000..414d5f3 --- /dev/null +++ b/docs/html/guide/topics/ui/accessibility/index.jd @@ -0,0 +1,55 @@ +page.title=Accessibility +parent.title=User Interface +parent.link=../index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Topics</h2> + <ol> + <li><a href="{@docRoot}guide/topics/ui/accessibility/apps.html">Making Applications Accessible</a> + </li> + <li><a href="{@docRoot}guide/topics/ui/accessibility/services.html">Building Accessibility + Services</a></li> + </ol> + + <h2>Key classes</h2> + <ol> + <li>{@link android.view.accessibility.AccessibilityEvent}</li> + <li>{@link android.accessibilityservice.AccessibilityService}</li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}training/accessibility/index.html">Implementing Accessibility</a></li> + </ol> + +</div> +</div> + +<p>Many Android users have disabilities that require them to interact with their Android devices in +different ways. These include users who have visual, physical or age-related disabilities that +prevent them from fully seeing or using a touchscreen.</p> + +<p>Android provides accessibility features and services for helping these users navigate their +devices more easily, including text-to-speech, haptic feedback, trackball and D-pad navigation that +augment their experience. Android application developers can take advantage of these services to +make their applications more accessible and also build their own accessibility services.</p> + +<p>The following topics show you how to use the Android framework to make applications more +accessible.</p> + +<dl> + <dt><strong><a href="{@docRoot}guide/topics/ui/accessibility/apps.html">Making Applications +Accessible</a></strong> + </dt> + <dd>Development practices and API features to ensure your application is accessible to users with +disabilities.</dd> + + <dt><strong><a href="{@docRoot}guide/topics/ui/accessibility/service.html">Building Accessibility +Services</a></strong> + </dt> + <dd>How to use API features to build services that make other applications more accessible for +users.</dd> +</dl>
\ No newline at end of file diff --git a/docs/html/guide/topics/ui/accessibility/services.jd b/docs/html/guide/topics/ui/accessibility/services.jd new file mode 100644 index 0000000..0dad4ec --- /dev/null +++ b/docs/html/guide/topics/ui/accessibility/services.jd @@ -0,0 +1,290 @@ +page.title=Building Accessibility Services +parent.title=Accessibility +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Topics</h2> + <ol> + <li><a href="#manifest">Manifest Declarations and Permissions</a> + <ol> + <li><a href="service-declaration">Accessibility service declaration</a></li> + <li><a href="#service-config">Accessibility service configuration</a></li> + </ol> + </li> + <li><a href="#methods">AccessibilityService Methods</a></li> + <li><a href="#event-details">Getting Event Details</a></li> + <li><a href="#examples">Example Code</a></li> + </ol> + + <h2>Key classes</h2> + <ol> + <li>{@link android.accessibilityservice.AccessibilityService}</li> + <li>{@link android.accessibilityservice.AccessibilityServiceInfo}</li> + <li>{@link android.view.accessibility.AccessibilityEvent}</li> + <li>{@link android.view.accessibility.AccessibilityRecord}</li> + <li>{@link android.view.accessibility.AccessibilityNodeInfo}</li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}training/accessibility/index.html">Implementing Accessibility</a></li> + </ol> + +</div> +</div> + +<p>An accessibility service is an application that provides user interface enhancements to +assist users with disabilities, or who may temporarily be unable to fully interact with a device. +For example, users who are driving, taking care of a young child or attending a very loud party +might need additional or alternative interface feedback.</p> + +<p>Android provides standard accessibility services, including TalkBack, and developers can +create and distribute their own services. This document explains the basics of building an +accessibility service.</p> + +<p>The ability for you to build and deploy accessibility services was introduced with Android +1.6 (API Level 4) and received significant improvements with Android 4.0 (API Level 14). The Android +Support Library was also updated with the release of Android 4.0 to provide support for these +enhanced accessibility features back to Android 1.6. Developers aiming for widely compatible +accessibility services are encouraged to use the +<a href="{@docRoot}sdk/compatibility-library.html">Support Library</a> and develop for the more +advanced accessibility features introduced in Android 4.0.</p> + + +<h2 id="manifest">Manifest Declarations and Permissions</h2> + +<p>Applications that provide accessibility services must include specific declarations in their + application manifests in order to be treated as an accessibility service by an Android system. + This section explains the required and optional settings for accessibility services.</p> + + +<h3 id="service-declaration">Accessibility service declaration</h3> + +<p>In order to be treated as an accessibility service, your application must include the +{@code service} element (rather than the {@code activity} element) within the {@code application} +element in its manifest. In addition, within the {@code service} element, you must also include an +accessibility service intent filter, as shown in the following sample:</p> + +<pre> +<application> + <service android:name=".MyAccessibilityService" + android:label="@string/accessibility_service_label"> + <intent-filter> + <action android:name="android.accessibilityservice.AccessibilityService" /> + </intent-filter> + </service> +</application> +</pre> + +<p>These declarations are required for all accessibility services deployed on Android 1.6 (API Level + 4) or higher.</p> + + +<h3 id="service-config">Accessibility service configuration</h3> + +<p>Accessibility services must also provide a configuration which specifies the types of +accessibility events that the service handles and additional information about the service. The +configuration of an accessibility service is contained in the {@link +android.accessibilityservice.AccessibilityServiceInfo} class. Your service can build and set a +configuration using an instance of this class and {@link +android.accessibilityservice.AccessibilityService#setServiceInfo setServiceInfo()} at runtime. +However, not all configuration options are available using this method.</p> + +<p>Beginning with Android 4.0, you can include a {@code <meta-data>} element in your manifest +with a reference to a configuration file, which allows you to set the full range of options for +your accessibility service, as shown in the following example:</p> + +<pre> +<service android:name=".MyAccessibilityService"> + ... + <meta-data + android:name="android.accessibilityservice" + android:resource="@xml/accessibility_service_config" /> +</service> +</pre> + +<p>This meta-data element refers to an XML file that you create in your application’s resource +directory ({@code <project_dir>/res/xml/accessibility_service_config.xml}). The following code +shows example contents for the service configuration file:</p> + +<pre> +<accessibility-service xmlns:android="http://schemas.android.com/apk/res/android" + android:description="@string/accessibility_service_description" + android:packageNames="com.example.android.apis" + android:accessibilityEventTypes="typeAllMask" + android:accessibilityFlags="flagDefault" + android:accessibilityFeedbackType="feedbackSpoken" + android:notificationTimeout="100" + android:canRetrieveWindowContent="true" + android:settingsActivity="com.example.android.accessibility.ServiceSettingsActivity" +/> +</pre> + +<p>One of the most important functions of the accessibility service configuration parameters is to +allow you to specify what types of accessibility events your service can handle. Being able to +specify this information enables accessibility services to cooperate with each other, and allows you +as a developer the flexibility to handle only specific events types from specific applications. The +event filtering can include the following criteria:</p> + +<ul> + <li><strong>Package Names</strong> - Specify the package names of applications whose accessibility +events you want your service to handle. If this parameter is omitted, your accessibility service is +considered available to service accessibility events for any application. This parameter can be set +in the accessibility service configuration files with the {@code android:packageNames} attribute as +a comma-separated list, or set using the {@link +android.accessibilityservice.AccessibilityServiceInfo#packageNames +AccessibilityServiceInfo.packageNames} member.</li> + <li><strong>Event Types</strong> - Specify the types of accessibility events you want your service +to handle. This parameter can be set in the accessibility service configuration files with the +{@code android:accessibilityEventTypes} attribute as a comma-separated list, or set using the +{@link android.accessibilityservice.AccessibilityServiceInfo#eventTypes +AccessibilityServiceInfo.eventTypes} member. </li> +</ul> + +<p>For more information about the XML attributes which can be used in the accessibility service + configuration file, follow these links to the reference documentation:</p> + +<ul> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_description">{@code android:description}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_packageNames">{@code android:packageNames}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_accessibilityEventTypes">{@code android:accessibilityEventTypes}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_accessibilityFlags">{@code android:accessibilityFlags}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_accessibilityFeedbackType">{@code android:accessibilityFeedbackType}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_notificationTimeout">{@code android:notificationTimeout}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_canRetrieveWindowContent">{@code android:canRetrieveWindowContent}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_settingsActivity">{@code android:settingsActivity}</a></li> +</ul> + +<p>For more information about which configuration settings can be dynamically set at runtime, see +the {@link android.accessibilityservice.AccessibilityServiceInfo} reference documentation.</p> + + +<h2 id="methods">AccessibilityService Methods</h2> + +<p>An application that provides accessibility service must extend the {@link +android.accessibilityservice.AccessibilityService} class and override the following methods from +that class. These methods are presented in the order in which they are called by the Android system, +from when the service is started +({@link android.accessibilityservice.AccessibilityService#onServiceConnected onServiceConnected()}), +while it is running ({@link android.accessibilityservice.AccessibilityService#onAccessibilityEvent +onAccessibilityEvent()}, +{@link android.accessibilityservice.AccessibilityService#onInterrupt onInterrupt()}) to when it is +shut down ({@link android.accessibilityservice.AccessibilityService#onUnbind onUnbind()}).</p> + +<ul> + <li>{@link android.accessibilityservice.AccessibilityService#onServiceConnected +onServiceConnected()} - (optional) This system calls this method when it successfully connects to +your accessibility service. Use this method to do any one-time setup steps for your service, +including connecting to user feedback system services, such as the audio manager or device vibrator. +If you want to set the configuration of your service at runtime or make one-time adjustments, this +is a convenient location from which to call {@link +android.accessibilityservice.AccessibilityService#setServiceInfo setServiceInfo()}.</li> + + <li>{@link android.accessibilityservice.AccessibilityService#onAccessibilityEvent +onAccessibilityEvent()} - (required) This method is called back by the system when it detects an +{@link android.view.accessibility.AccessibilityEvent} that matches the event filtering parameters +specified by your accessibility service. For example, when the user clicks a button or focuses on a +user interface control in an application for which your accessibility service is providing feedback. +When this happens, the system calls this method of your service with the associated {@link +android.view.accessibility.AccessibilityEvent}, which you can then interpret and provide feedback to +the user. This method may be called many times over the lifecycle of your service.</li> + + <li>{@link android.accessibilityservice.AccessibilityService#onInterrupt onInterrupt()} - +(required) This method is called when the system wants to interrupt the feedback your service is +providing, usually in response to a user taking action, such as moving focus to a different user +interface control than the one for which you are currently providing feedback. This method may be +called many times over the lifecycle of your service.</li> + + <li>{@link android.accessibilityservice.AccessibilityService#onUnbind onUnbind()} - (optional) +This method is called when the system is about to shutdown the accessibility service. Use this +method to do any one-time shutdown procedures, including de-allocating user feedback system +services, such as the audio manager or device vibrator.</li> +</ul> + +<p>These callback methods provide the basic structure for your accessibility service. It is up to +you to decide on how to process data provided by the Android system in the form of {@link +android.view.accessibility.AccessibilityEvent} objects and provide feedback to the user.</p> + + +<h2 id="event-details">Getting Event Details</h2> + +<p>The Android system provides information to accessibility services about the user interface +interaction through {@link android.view.accessibility.AccessibilityEvent} objects. Prior to Android +4.0, the information available in an accessibility event, while providing a significant amount of +detail about a user interface control selected by the user, typically provided limited contextual +information. In many cases, this missing context information might be critical to understanding the +meaning of the selected control.</p> + +<p>A typical example of an interface where context is of critical importance is a calendar or day +planner. If a user selects a 4:00 PM time slot in a Monday to Friday day list and the accessibility +service announces “4 PM”, but fails to indicate this is a Friday a Monday, the month or day, this is +hardly ideal feedback for the user. In this case, the context of a user interface control is of +critical importance to a user who wants to schedule a meeting.</p> + +<p>Android 4.0 significantly extends the amount of information that an accessibility service can +obtain about an user interface interaction by composing accessibility events based on the view +hierarchy. A view hierarchy is the set of user interface components that contain the component (its +parents) and the user interface elements that may be contained by that component (its children). In +this way, the Android system can provide much richer detail about accessibility events, allowing +accessibility services to provide more useful feedback to users.</p> + +<p>An accessibility service gets information about an user interface event through an {@link +android.view.accessibility.AccessibilityEvent} passed by the system to the service’s +{@link android.accessibilityservice.AccessibilityService#onAccessibilityEvent +onAccessibilityEvent()} callback method. This object provides details about the event, including the +type of object being acted upon, its descriptive text and other details. Starting in Android 4.0 +(and supported in previous releases through the {@link +android.support.v4.view.accessibility.AccessibilityEventCompat} object in the Support Library), you +can obtain additional information about the event using these calls:</p> + +<ul> + <li>{@link android.view.accessibility.AccessibilityEvent#getRecordCount +AccessibilityEvent.getRecordCount()} and {@link +android.view.accessibility.AccessibilityEvent#getRecord getRecord(int)} - These methods allow you to +retrieve the set of {@link android.view.accessibility.AccessibilityRecord} objects which contributed +to the {@link android.view.accessibility.AccessibilityEvent} passed to you by the system, which can +provide more context for your accessibility service.</li> + + <li>{@link android.view.accessibility.AccessibilityEvent#getSource +AccessibilityEvent.getSource()} - This method returns an {@link +android.view.accessibility.AccessibilityNodeInfo} object. This object allows you to request the +parents and children of the component that originated the accessibility event and investigate their +contents and state in order to provide + + <p class="caution"><strong>Important:</strong> The ability to investigate the full view +hierarchy from an {@link android.view.accessibility.AccessibilityEvent} potentially exposes private +user information to your accessibility service. For this reason, your service must request this +level of access through the accessibility <a href="#service-config">service configuration XML</a> +file, by including the {@code canRetrieveWindowContent} attribute and setting it to {@code true}. If +you do not include this setting in your service configuration xml file, calls to {@link +android.view.accessibility.AccessibilityEvent#getSource getSource()} fail.</p> + </li> +</ul> + + +<h2 id="examples">Example Code</h2> + +<p>The API Demo project contains two samples which can be used as a starting point for generating +accessibility services +({@code <sdk>/samples/<platform>/ApiDemos/src/com/example/android/apis/accessibility}): +</p> + +<ul> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/accessibility/ClockBackService.html">ClockBackService</a> + - This service is based on the original implementation of {@link +android.accessibilityservice.AccessibilityService} and can be used as a base for developing basic +accessibility services that are compatible with Android 1.6 (API Level 4) and higher.</li> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/accessibility/TaskBackService.html">TaskBackService</a> + - This service is based on the enhanced accessibility APIs introduced in Android 4.0 (API Level +14). However, you can use the Android <a href="{@docRoot}sdk/compatibility-library.html">Support +Libary</a> to substitute classes introduced in later API levels (e.g., +{@link android.view.accessibility.AccessibilityRecord}, +{@link android.view.accessibility.AccessibilityNodeInfo} +) with equivalent support package classes (e.g., +{@link android.support.v4.view.accessibility.AccessibilityRecordCompat}, +{@link android.support.v4.view.accessibility.AccessibilityNodeInfoCompat} +) to make this example work with API versions back to Android 1.6 (API Level 4).</li> +</ul> diff --git a/docs/html/guide/topics/ui/actionbar.jd b/docs/html/guide/topics/ui/actionbar.jd index 3c0ef26..bf7369a 100644 --- a/docs/html/guide/topics/ui/actionbar.jd +++ b/docs/html/guide/topics/ui/actionbar.jd @@ -73,8 +73,10 @@ href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/inde API Demos</a></li> </ol> - <h2>See also</h2>item + <h2>See also</h2> <ol> + <li><a +href="{@docRoot}design/patterns/actionbar.html">Android Design: Action Bar</a></li> <li><a href="{@docRoot}guide/topics/ui/menus.html">Menus</a></li> <li><a href="{@docRoot}guide/practices/tablets-and-handsets.html">Supporting Tablets and Handsets</a></li> @@ -111,9 +113,10 @@ accessible to the user in a predictable way. 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> @@ -123,6 +126,18 @@ href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery 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> + <p>For design guidelines, read Android Design's <a +href="{@docRoot}design/patterns/actionbar.html">Action Bar</a> guide.</p> +</div> + + <div class="sidebox-wrapper"> <div class="sidebox"> @@ -215,9 +230,10 @@ later—calling {@link android.app.Activity#getActionBar()} will return null 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="" /> @@ -333,7 +349,7 @@ of the following:</p> <li><strong>Frequently used</strong>: It's an action that your users need seven out of ten visits or they use it several times in a row. <p>Example frequent actions: "New message" in the Messaging app and -"Search" in Android Market.</p> +"Search" on Google Play.</p> </li> <li><strong>Important</strong>: It's an action that you need users to easily discover or, if it's @@ -536,6 +552,12 @@ the email application, but presses the action bar icon to navigate up, rather th <p class="img-caption"><strong>Figure 6.</strong> Example behavior for UP navigation after entering the Email app from the People app.</p> +<div class="design-announce"> +<p><strong>Navigation Design</strong></p> + <p>For more about how <em>Up</em> and <em>Back</em> navigation differ, read Android Design's <a +href="{@docRoot}design/patterns/navigation.html">Navigation</a> guide.</p> +</div> + <p>To enable the icon for up navigation (which displays the "up" indicator next to the icon), call {@link android.app.ActionBar#setDisplayHomeAsUpEnabled setDisplayHomeAsUpEnabled(true)} on your {@link android.app.ActionBar}:</p> @@ -642,7 +664,7 @@ work as designed otherwise.</p> <p>Adding this value requires that you set your build target to Android 4.0 or higher in order to compile. Older versions of Android ignore the {@code "collapseActionView"} value because they don't understand it. Just be sure not to use other APIs in your source code that are not supported in the -version declared by your <a href="{@docRoot}guide/topics/manifest/uses-sdk-elementl.html#min">{@code +version declared by your <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a>, unless you add the appropriate version check at runtime.</p> </div> </div> @@ -843,8 +865,8 @@ you <em>do not</em> need to handle click events from the {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} callback method.</p> <p>For a sample using the share action provider, see -<a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ActionBarActionProviderActivity.html" ->ActionBarActionProviderActivity</a>. +<a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ActionBarShareActionProviderActivity.html" +>ActionBarShareActionProviderActivity</a>. @@ -1405,7 +1427,7 @@ href="#ActionView">action views</a>. (Added in API level 14.)</dd> </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> @@ -1421,8 +1443,7 @@ action bar styles you want to change without re-implementing the styles you want 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 @@ -1441,7 +1462,7 @@ android:backgroundStacked}. If you override these action bar styles, be sure tha 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> @@ -1449,14 +1470,15 @@ styles:</p> <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/declaring-layout.jd b/docs/html/guide/topics/ui/declaring-layout.jd index 4dc915f..8af4a1c 100644 --- a/docs/html/guide/topics/ui/declaring-layout.jd +++ b/docs/html/guide/topics/ui/declaring-layout.jd @@ -194,7 +194,7 @@ contains property types that define the size and position for each child view, a appropriate for the view group. As you can see in figure 1, the parent view group defines layout parameters for each child view (including the child view group).</p> -<img src="{@docRoot}images/layoutparams.png" alt="" height="300" align="center"/> +<img src="{@docRoot}images/layoutparams.png" alt="" /> <p class="img-caption"><strong>Figure 1.</strong> Visualization of a view hierarchy with layout parameters associated with each view.</p> diff --git a/docs/html/guide/topics/ui/dialogs.jd b/docs/html/guide/topics/ui/dialogs.jd index 16f14cb..82cbfd1 100644 --- a/docs/html/guide/topics/ui/dialogs.jd +++ b/docs/html/guide/topics/ui/dialogs.jd @@ -37,6 +37,11 @@ DatePicker</a></li> <li><a href="{@docRoot}resources/tutorials/views/hello-timepicker.html">Hello TimePicker</a></li> </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}design/building-blocks/dialogs.html">Android Design: Dialogs</a></li> + </ol> </div> </div> @@ -70,6 +75,13 @@ of the following subclasses:</p> base {@link android.app.Dialog} object or any of the subclasses listed above and define a new layout. See the section on <a href="#CustomDialog">Creating a Custom Dialog</a> below.</p> +<div class="design-announce"> +<p><strong>Dialog Design</strong></p> + <p>For design guidelines, read Android Design's <a +href="{@docRoot}design/building-blocks/dialogs.html">Dialogs</a> guide.</p> +</div> + + <h2 id="ShowingADialog">Showing a Dialog</h2> diff --git a/docs/html/guide/topics/ui/index.jd b/docs/html/guide/topics/ui/index.jd index d3060c5..45c9ac9 100644 --- a/docs/html/guide/topics/ui/index.jd +++ b/docs/html/guide/topics/ui/index.jd @@ -51,7 +51,7 @@ as shown in the diagram below. This hierarchy tree can be as simple or complex a can build it up using Android's set of predefined widgets and layouts, or with custom Views that you create yourself.</p> -<img src="{@docRoot}images/viewgroup.png" alt="" width="312" height="211" align="center"/> +<img src="{@docRoot}images/viewgroup.png" alt="" /> <p> In order to attach the view hierarchy tree to the screen for rendering, your Activity must call the @@ -174,7 +174,8 @@ href="ui-events.html">Input Events</a> document.</p> <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/layout-objects.jd b/docs/html/guide/topics/ui/layout-objects.jd index 8b2792d..e251fe9 100644 --- a/docs/html/guide/topics/ui/layout-objects.jd +++ b/docs/html/guide/topics/ui/layout-objects.jd @@ -163,7 +163,7 @@ refer to the ID using the syntax of a relative resource <td> <pre> <?xml version="1.0" encoding="utf-8"?> -<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android +<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="fill_parent" android:layout_height="wrap_content" android:background="@drawable/blue" diff --git a/docs/html/guide/topics/ui/menus.jd b/docs/html/guide/topics/ui/menus.jd index 7b5b3dc..d51a378 100644 --- a/docs/html/guide/topics/ui/menus.jd +++ b/docs/html/guide/topics/ui/menus.jd @@ -6,77 +6,129 @@ parent.link=index.html <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 mode</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>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> -<p>There are three types of application menus:</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>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> - <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> </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 @@ element may contain a nested <code><menu></code> element in order to create a <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 @@ section about <a href="#groups">Menu groups</a>.</dd> <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,158 +172,175 @@ when the user selects it.</dd> <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> +<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> -@Override -public boolean onCreateOptionsMenu(Menu menu) { - MenuInflater inflater = getMenuInflater(); - inflater.inflate(R.menu.game_menu, menu); - return true; -} +<?xml version="1.0" encoding="utf-8"?> +<menu xmlns:android="http://schemas.android.com/apk/res/android"> + <item android:id="@+id/file" + android:title="@string/file" > + <!-- "file" submenu --> + <menu> + <item android:id="@+id/create_new" + android:title="@string/create_new" /> + <item android:id="@+id/open" + android:title="@string/open" /> + </menu> + </item> +</menu> </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> +<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="options-menu">Creating an Options Menu</h2> -<div class="figure" style="width:200px"> +<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> Screenshot of the Options Menu in the -Browser.</p> + <p class="img-caption"><strong>Figure 1.</strong> Options menu in the +Browser, on Android 2.3.</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> +<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 = getMenuInflater(); + MenuInflater inflater = {@link android.app.Activity#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 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>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>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> -<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> +<h3 id="RespondingOptionsMenu">Handling click events</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> +<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); + 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>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 +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, +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 @@ -278,180 +350,477 @@ 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>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, 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>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 +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 +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 Contextual Menus</h2> -<h2 id="context-menu">Creating a Context Menu</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 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>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>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> +<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> -<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 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> -<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> +<h3 id="FloatingContextMenu">Creating a floating context menu</h3> -<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> +<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); + 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 +<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. 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> +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> -<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> +<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); - } + 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>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>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>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> Items in a context menu do not support icons or shortcut -keys.</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> -<h2 id="submenu">Creating Submenus</h2> +<p>The following sections describe the setup required for each scenario.</p> -<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> +<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> -<?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> - <item android:id="@+id/create_new" - android:title="@string/create_new" /> - <item android:id="@+id/open" - android:title="@string/open" /> - </menu> - </item> -</menu> +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>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>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>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 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); -<h2 id="features">Other Menu Features</h2> + // 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> -<p>Here are some other features that you can apply to most menu items.</p> -<h3 id="groups">Menu groups</h3> +<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 @@ android.view.Menu#add(int,int,int,int) add()} method.</p> <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 @@ user selected it) with {@link android.view.MenuItem#isChecked()} and then set th <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 @@ you should store the data using <a 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 @@ addIntentOptions()}, it overrides any and all menu items by the menu group speci 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 @@ filter as usual, but be sure to include the {@link android.content.Intent#CATEGO 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 7bc1cde..d104b4b 100644 --- a/docs/html/guide/topics/ui/notifiers/notifications.jd +++ b/docs/html/guide/topics/ui/notifiers/notifications.jd @@ -16,6 +16,7 @@ user clicks it</li> <h2>In this document</h2> <ol> <li><a href="#Basics">The Basics</a></li> + <li><a href="#HandlingNotifications">Responding to Notifications</a></li> <li><a href="#ManageYourNotifications">Managing your Notifications</a></li> <li><a href="#CreateANotification">Creating a Notification</a> <ol> @@ -33,6 +34,12 @@ user clicks it</li> <li>{@link android.app.Notification}</li> <li>{@link android.app.NotificationManager}</li> </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}design/patterns/notifications.html">Android +Design: Notifications</a></li> + </ol> </div> </div> @@ -61,6 +68,14 @@ when selected by the user.</p> <p class="img-caption"><strong>Figure 2.</strong> The notifications window.</p> +<div class="design-announce"> +<p><strong>Notification Design</strong></p> + <p>For design guidelines, read Android Design's <a +href="{@docRoot}design/patterns/notifications.html">Notifications</a> guide.</p> +</div> + + + <h2 id="Basics">The Basics</h2> <p>An {@link android.app.Activity} or {@link android.app.Service} can initiate a status bar @@ -123,6 +138,134 @@ mNotificationManager.notify(HELLO_ID, notification); </ol> +<h2 id="HandlingNotifications">Responding to Notifications</h2> + +<p>A central part of the user's experience with a notification revolves around +how it interacts with the application's UI flow. You must implement +this correctly to provide a consistent user experience within your app.</p> + +<p>Two typical examples of notifications are provided by Calendar, which can send out +notifications of upcoming events, and Email, which can send out notifications +when new messages arrive. These represent the two recommended patterns for handling +notifications: either launching into an activity that is separate from the +main application, or launching an entirely new instance of the application +showing the appropriate point for the notification.</p> + +<p>The following scenario shows how the activity stack should work +in these two typical notification flows, first handling a Calendar notification: +</p> + +<ol> + <li>User is creating a new event in Calendar. They realize they + need to copy part of an email message into this event. + </li> + <li> + The user chooses Home > Email. + </li> + <li> + While in Email, they receive a notification from Calendar for an upcoming + meeting. + </li> + <li> + So they choose that notification, which takes them to a + dedicated Calendar activity that displays brief details of the + upcoming meeting. + </li> + <li> + The user has seen enough to know they have a meeting coming up, + 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> + +<p>Handling an Email notification:</p> + +<ol> + <li> + The user is currently in Email composing a message, and needs to + check a date in their calendar. + </li> + <li> + The user chooses Home > Calendar. + </li> + <li> + While in Calendar, they receive a notification from Email about a new + message. + </li> + <li> + They select the notification, which brings them to Email with the message + details displayed. This has replaced what they were previously doing + (writing an e-mail), but that message is still saved in their drafts. + </li> + <li> + 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> + +<p>In an Email style of notification, the UI launched by the notification +shows the main application in a state representing that notification. +For example, when the Email application comes to the foreground from its +notification, it displays either the conversion list or a specific +conversation depending on whether there are multiple or only one new +email. To achieve this, we want to completely replace whatever current +state the application is in with a new activity stack representing the +new notification state.</p> + +<p>The following code illustrates how to show this kind of notification. Of +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 <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 +{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TASK Intent.FLAG_ACTIVITY_CLEAR_TASK}.</p> + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/IncomingMessage.java + app_notification} + +<p>In a Calendar style of notification, the UI launched by the notification +is a dedicated activity that is not part of the normal application flow. +For example, when the user receives a Calendar notification, choosing that +notification starts a special activity that displays a list +of upcoming calendar events — this view is available only +from the notification, not through the Calendar's normal user +interface.</p> + +<p>The code for posting this type of notification is very straight-forward; it +is like the above, but the {@link android.app.PendingIntent} is for just a single +activity, our dedicated notification activity.</p> + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/IncomingMessage.java + interstitial_notification} + +<p>This is not enough, however. Normally Android considers all activities within +an application to be part of that application's UI flow, so simply launching the +activity like this can cause it to be mixed with your normal application back stack +in undesired ways. To make it behave correctly, in the manifest declaration +for the activity the attributes +<code>android:launchMode="singleTask"</code>, +<code>android:taskAffinity=""</code> and +<code>android:excludeFromRecents="true"</code> +must be set. The full activity declaration for this sample is:</p> + +{@sample development/samples/ApiDemos/AndroidManifest.xml interstitial_affinity} + +<p>You must be careful when launching other activities from this initial activity, +because this is not a top-level part of the application, does not appear in +recents, and needs to be relaunched at any point from the notification with new data +to show. This best approach is to make sure any activity launched from it is +launched in its own task. When doing this care must be taken to make sure this +new task interacts well with the current state of your exiting application's +task. This is essentially +the same as switching to the main application as described for the Email style +notification shown before. Given the <code>makeMessageIntentStack()</code> +method previously shown, handling a click then would look something like this:</p> + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/IncomingMessageInterstitial.java + app_launch} + <h2 id="ManageYourNotifications">Managing your Notifications</h2> <p>The {@link android.app.NotificationManager} is a system service that manages all |