From e1302edd40c5cc264f842e17e3796e0a11d6f045 Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Mon, 6 Feb 2012 14:30:15 -0800 Subject: docs: Accessibility Dev Guide (subsumes Accessibility Best Practices) Change-Id: Id7e3f647042d2afd390abe851be1c3b561af33ca --- .../html/guide/practices/design/accessibility.html | 11 + docs/html/guide/practices/design/accessibility.jd | 352 --------------------- 2 files changed, 11 insertions(+), 352 deletions(-) create mode 100644 docs/html/guide/practices/design/accessibility.html delete mode 100644 docs/html/guide/practices/design/accessibility.jd (limited to 'docs/html/guide/practices') diff --git a/docs/html/guide/practices/design/accessibility.html b/docs/html/guide/practices/design/accessibility.html new file mode 100644 index 0000000..0fa7b32 --- /dev/null +++ b/docs/html/guide/practices/design/accessibility.html @@ -0,0 +1,11 @@ + + + +Redirecting... + + +

You should be redirected. Please click here.

+ + \ No newline at end of file diff --git a/docs/html/guide/practices/design/accessibility.jd b/docs/html/guide/practices/design/accessibility.jd deleted file mode 100644 index 72da04e..0000000 --- a/docs/html/guide/practices/design/accessibility.jd +++ /dev/null @@ -1,352 +0,0 @@ -page.title=Designing for Accessibility -@jd:body - - -
-
- -

Quickview

-
    -
  • To make your application more accessible, you should make sure your UI is navigable -using a directional controller and your widgets provide content descriptions
    • -
  • If you implement a custom view, you should ensure that it delivers the appropriate -accessibility events during user interaction
    • -
- -

In this document

-
    -
  1. Allow Navigation with a Directional Controller -
      -
    1. Controlling focus order
      2. -
    2. Clicking with a directional controller
      3. -
    -
    2. -
  2. Label Your Input Widgets
    3. -
  3. Follow Android UI Best Practices
    4. -
  4. Send Accessibility Events from Custom View Components
    5. -
  5. Test Your Application’s Accessibility
    6. -
- -

Key classes

-
    -
  1. {@link android.view.accessibility.AccessibilityEvent}
    2. -
  2. {@link android.view.accessibility.AccessibilityEventSource}
    3. -
- -

Related samples

-
    -
  1. Accessibility Service
    2. -
- -
-
- - - -

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 using or seeing a touchscreen.

- -

Android provides an accessibility layer that helps these users navigate their Android-powered -devices more easily. Android's accessibility services provide things like text-to-speech, haptic -feedback, and trackball/d-pad navigation that augment the user experience.

- -

Your application should follow the guidelines in this document to ensure that it provides a -good experience for users with disabilities. Following these two basic rules will solve most -access-related problems:

- - - - - - - -

Many Android devices come with some sort of directional controller, such as:

- - -

All of these directional controllers allow users to navigate the screen without using the -touchscreen. On some devices, a user can also navigate to the top or bottom of a list by holding -down the alt key while pressing a discrete key for up or down.

- -

A directional controller is the primary means of navigation for users with visual or some -physical impairments (and also for users without impairments when using devices that don't -have a touchscreen). You should verify that all UI controls in your application are -accessible without using the touchscreen and that clicking with the center button (or OK button) has -the same effect as touching the controls on the touchscreen.

- -

A UI control (also called a "widget") is accessible using directional controls when it's -"focusable" property is "true." This means that users can focus on the widget using the directional -controls and then interact with it. Widgets provided by the Android APIs are focusable by default -and visually indicate focus by changing the widget visual appearance in some way.

- -

Android provides several APIs that let you control whether a widget is focusable and even -request that a widget be given focus. Such methods include:

- - - -

When working with a view that is not focusable by default, you can make it focusable from the XML -layout file by setting the {@code -android:focusable} attribute to {@code "true"}.

- - - -

Controlling focus order

- -

When the user navigates in any direction using the directional controls, focus is passed from one -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:

- -
-
{@code android:nextFocusDown}
-
Defines the next view to receive focus when the user navigates down.
- {@code android:nextFocusLeft} -
Defines the next view to receive focus when the user navigates left.
-
{@code android:nextFocusRight}
-
Defines the next view to receive focus when the user navigates right.
-
{@code android:nextFocusUp}
-
Defines the next view to receive focus when the user navigates up.
-
- -

For example, here is an XML layout that contains a focusable {@link android.widget.TextView}. -While the {@link android.widget.TextView} is located to the right of the {@link -android.widget.EditText}, it can now be reached by pressing the down arrow when focus is on the -{@link android.widget.EditText}:

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

When modifying this ordering, be sure that the navigation works as expected in all directions -from each widget and when navigating in reverse (to get back to where you came from).

- -

You can also modify the focus ordering at runtime, using methods in the {@link -android.view.View} class, such as {@link android.view.View#setNextFocusDownId -setNextFocusDownId()} and {@link android.view.View#setNextFocusRightId -setNextFocusRightId()}.

- - -

Clicking with a directional controller

- -

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. Make sure this event has the same effect as touching the view on the touchscreen. All -standard Android views already handle {@link android.view.KeyEvent#KEYCODE_DPAD_CENTER} -appropriately.

- -

If possible, also treat the {@link android.view.KeyEvent#KEYCODE_ENTER} event the same as -{@link android.view.KeyEvent#KEYCODE_DPAD_CENTER}. That makes interaction much easier from a full -keyboard.

- - - - -

Label Your Input Widgets

- -

Many input widgets rely on visual cues to inform the user of their meaning. For example, a -notepad 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} may have -a label near it that indicates its purpose. When a visually impaired user accesses your -application, these visual cues are often useless.

- -

To provide textual information about these widgets (as an alternative to the visual cues), you -should use the {@code android:contentDescription} attribute. The text you provide in this attribute -is not visible on the screen, but if a user has enabled accessibility speech tools then the -description in this attribute is read aloud to the user.

- -

You should set the {@code -android:contentDescription} attribute on every {@link android.widget.ImageButton}, {@link -android.widget.EditText}, {@link android.widget.CheckBox}, and on any other input widgets that might -benefit users with extra information.

- -

For example, the following {@link android.widget.ImageButton} sets the content description for -the plus button to the {@code add_note} string resource, which might be defined in English as -“Add note":

- -
-<ImageButton
-    android:id=”@+id/add_entry_button”
-    android:src=”@drawable/plus”
-    android:contentDescription=”@string/add_note”/>
-
- -

This way, when using speech accessibility tools, the user hears "Add note" when focused on -this widget.

- - - -

Follow Android UI Best Practices

- -

You can make it easier for users to learn how to use your application by developing a user -interface that complies with Android's standard interaction patterns, instead of creating your own -or using interaction patterns from another platform. This consistency is especially important for -many disabled users, as they may have less contextual information available to try to understand -your application’s interface.

- -

Specifically, you should:

- - - - - -

Send Accessibility Events from Custom View Components

- -

If your application requires that you create a custom view component, you may need to -do some additional work to ensure that your view is accessible. Specifically, you should make sure -that your view implements the {@link android.view.accessibility.AccessibilityEventSource} -interface and emits {@link android.view.accessibility.AccessibilityEvent}s at the proper times, -and that each {@link android.view.accessibility.AccessibilityEvent} contains relevant information -about the state of the view.

- -

Events are emitted whenever something notable happens in the user interface. Currently, there -are five types of accessibility events that a view should send to the system as the user interacts -with it:

- -
-
{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_CLICKED}
-
Indicates that the user clicked on the view (for example, the user selects a button).
- -
{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_LONG_CLICKED}
-
Indicates that the user performed a long press on the view.
- -
{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_SELECTED}
-
Indicates that the user selected an item from within the view. This is usually used in the -context of an {@link android.widget.AdapterView}.
- -
{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_FOCUSED}
-
Indicates that the user moved the focus to the view.
- -
{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_TEXT_CHANGED}
-
Indicates that the text or contents of the view changed.
-
- - -

The basic {@link android.view.View} class implements {@link -android.view.accessibility.AccessibilityEventSource} and emits these events at the proper time in -the standard cases. Your custom view should extend from {@link android.view.View} (or one of its -subclasses) to take advantage of these default implementations.

- -

Depending on the specifics of your custom view, your view may need to emit one of these events at -a different time than the default {@link android.view.View} implementation. To do so, simply call -{@link android.view.accessibility.AccessibilityEventSource#sendAccessibilityEvent -sendAccessibilityEvent()} with the specific event type at the correct time.

- -

For example, say you are implementing a custom slider bar that allows the user to select a -numeric value by pressing the left or right arrows. This view should emit an event of type {@link -android.view.accessibility.AccessibilityEvent#TYPE_VIEW_TEXT_CHANGED} whenever the slider value -changes:

- -
-@Override
-public boolean onKeyUp (int keyCode, KeyEvent event) {
-  if (keyCode == KeyEvent.KEYCODE_DPAD_LEFT) {
-    mCurrentValue--;
-    sendAccessibilityEvent(AccessibilityEvent.TYPE_VIEW_TEXT_CHANGED);
-    return true;
-  }
-  ...
-}
-
- -

Each {@link android.view.accessibility.AccessibilityEvent} has a set of required properties that -describe the current state of the view. These properties include things like the view’s class name, -text and checked state. The specific properties required for each event type are described in the -{@link android.view.accessibility.AccessibilityEvent} documentation. The {@link android.view.View} -implementation will fill in default values for these properties. Most of these values, like the -class name and event timestamp, will not need to be changed. However, depending on the specifics of -your custom view, you may want to provide a different value for one or more of the properties. For -example, your view may have additional state information that you want to add to the event text.

- -

The {@link android.view.View#dispatchPopulateAccessibilityEvent -dispatchPopulateAccessibilityEvent()} method in {@link android.view.View} provides a hook for making -changes to the {@link android.view.accessibility.AccessibilityEvent} object before it is -emitted.

- -

In the above slider bar example, the view should add the current value of the slider bar to the -text of the event:

- -
-@Override
-public boolean dispatchPopulateAccessibilityEvent(final AccessibilityEvent event) {
-  super.dispatchPopulateAccessibilityEvent(event);
-  if (!isShown()) {
-    return false;
-  }
-  CharSequence text = String.valueOf(mCurrentValue);
-  if (text.length() > AccessibilityEvent.MAX_TEXT_LENGTH) {
-    text = text.subSequence(0, AccessiblityEvent.MAX_TEXT_LENGTH);
-  }
-  event.getText().add(text);
-  return true;
-}
-
- - -

Test Your Application’s Accessibility

- -

You can simulate the experience for many users by enabling an accessibility service that speaks -as you move around the screen. One such service is TalkBack, by the -Eyes-Free Project. It comes preinstalled on many -Android-powered devices, but is also available for free from the Google Play store.

- -

This service requires that you have a text-to-speech engine installed on your phone. You can -verify if you have one installed in the Text-to-speech settings menu by selecting -Listen to an example. If you do not hear anything spoken, install the required -voice data by selecting Install voice data.

- -

Once text-to-speech is functioning correctly, you can enable TalkBack (or another accessibility -service) in the Accessibility settings menu. Enable both -Accessibility and TalkBack. As you navigate about the device, you -should now hear spoken feedback.

- -

You can now attempt to use your application as a blind user would. As you move around using only -the directional controller, make sure that the spoken feedback you hear makes sense and is -sufficient to navigate the application without any visual cues.

-- cgit v1.1