Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit b303d838 authored by Scott Main's avatar Scott Main
Browse files

docs: a couple notes for a11y methods in View and cleanup to the 

A11y service HTML to be semantically correct and thus improve its accessibility :)

Change-Id: I483a8a441d802b056f68f82e0e782d86a73298ac
parent f4b40de6

core/java/android/accessibilityservice/AccessibilityService.java

+52 −81
Original line number Diff line number Diff line
@@ -32,11 +32,9 @@ import android.view.accessibility.AccessibilityNodeInfo; 
 * when {@link AccessibilityEvent}s are fired. Such events denote some state transition

 * in the user interface, for example, the focus has changed, a button has been clicked,

 * etc. Such a service can optionally request the capability for querying the content

 * of the active window. Development of an accessibility service requires extends this

 * class and implements its abstract methods.

 * <p>

 * <strong>Lifecycle</strong>

 * </p>

 * of the active window. Development of an accessibility service requires extending this

 * class and implementing its abstract methods.

 * <h3>Lifecycle</h3>

 * <p>

 * The lifecycle of an accessibility service is managed exclusively by the system and

 * follows the established service life cycle. Additionally, starting or stopping an
@@ -45,30 +43,20 @@ import android.view.accessibility.AccessibilityNodeInfo; 
 * calls {@link AccessibilityService#onServiceConnected()}. This method can be

 * overriden by clients that want to perform post binding setup.

 * </p>

 * <p>

 * <strong>Declaration</strong>

 * </p>

 * <h3>Declaration</h3>

 * <p>

 * An accessibility is declared as any other service in an AndroidManifest.xml but it

 * must also specify that it handles the "android.accessibilityservice.AccessibilityService"

 * {@link android.content.Intent}. Failure to declare this intent will cause the system to

 * ignore the accessibility service. Following is an example declaration:

 * </p>

 * <p>

 * <code>

 * <pre>

 *   &lt;service android:name=".MyAccessibilityService"&gt;

 * <pre> &lt;service android:name=".MyAccessibilityService"&gt;

 *     &lt;intent-filter&gt;

 *         &lt;action android:name="android.accessibilityservice.AccessibilityService" /&gt;

 *     &lt;/intent-filter&gt;

 *     . . .

 *   &lt;/service&gt;

 * </pre>

 * </code>

 * </p>

 * <p>

 * <strong>Configuration</strong>

 * </p>

 * &lt;/service&gt;</pre>

 * <h3>Configuration</h3>

 * <p>

 * An accessibility service can be configured to receive specific types of accessibility events,

 * listen only to specific packages, get events from each type only once in a given time frame,
@@ -81,30 +69,24 @@ import android.view.accessibility.AccessibilityNodeInfo; 
 * <li>

 * Providing a {@link #SERVICE_META_DATA meta-data} entry in the manifest when declaring

 * the service. A service declaration with a meta-data tag is presented below:

 * <p>

 * <code>

 * <pre>

 *   &lt;service android:name=".MyAccessibilityService"&gt;

 * <pre> &lt;service android:name=".MyAccessibilityService"&gt;

 *     &lt;intent-filter&gt;

 *         &lt;action android:name="android.accessibilityservice.AccessibilityService" /&gt;

 *     &lt;/intent-filter&gt;

 *     &lt;meta-data android:name="android.accessibilityservice" android:resource="@xml/accessibilityservice" /&gt;

 *   &lt;/service&gt;

 * </pre>

 * </code>

 * </p>

 * <p>

 * &lt;/service&gt;</pre>

 * <p class="note">

 * <strong>Note:</strong> This approach enables setting all properties.

 * </p>

 * <p>

 * For more details refer to {@link #SERVICE_META_DATA} and

 * <code>&lt;{@link android.R.styleable#AccessibilityService accessibility-service}&gt;</code>..

 * <code>&lt;{@link android.R.styleable#AccessibilityService accessibility-service}&gt;</code>.

 * </p>

 * </li>

 * <li>

 * Calling {@link AccessibilityService#setServiceInfo(AccessibilityServiceInfo)}. Note

 * that this method can be called any time to dynamically change the service configuration.

 * <p>

 * <p class="note">

 * <strong>Note:</strong> This approach enables setting only dynamically configurable properties:

 * {@link AccessibilityServiceInfo#eventTypes},

 * {@link AccessibilityServiceInfo#feedbackType},
@@ -117,9 +99,7 @@ import android.view.accessibility.AccessibilityNodeInfo; 
 * </p>

 * </li>

 * </ul>

 * <p>

 * <strong>Retrieving window content</strong>

 * </p>

 * <h3>Retrieving window content</h3>

 * <p>

 * An service can specify in its declaration that it can retrieve the active window

 * content which is represented as a tree of {@link AccessibilityNodeInfo}. Note that
@@ -144,7 +124,7 @@ import android.view.accessibility.AccessibilityNodeInfo; 
 * this method will return an {@link AccessibilityNodeInfo} that can be used to traverse the

 * window content which represented as a tree of such objects.

 * </p>

 * <p>

 * <p class="note">

 * <strong>Note</strong> An accessibility service may have requested to be notified for

 * a subset of the event types, thus be unaware that the active window has changed. Therefore

 * accessibility service that would like to retrieve window content should:
@@ -158,15 +138,13 @@ import android.view.accessibility.AccessibilityNodeInfo; 
 * <li>

 * Prepare that a retrieval method on {@link AccessibilityNodeInfo} may fail since the

 * active window has changed and the service did not get the accessibility event yet. Note

 * that it is possible to have a retrieval method failing event adopting the strategy

 * that it is possible to have a retrieval method failing even adopting the strategy

 * specified in the previous bullet because the accessibility event dispatch is asynchronous

 * and crosses process boundaries.

 * </li>

 * </ul>

 * </p>

 * <p>

 * <b>Notification strategy</b>

 * </p>

 * <h3>Notification strategy</h3>

 * <p>

 * For each feedback type only one accessibility service is notified. Services are notified

 * in the order of registration. Hence, if two services are registered for the same
@@ -178,40 +156,39 @@ import android.view.accessibility.AccessibilityNodeInfo; 
 * well with most applications to coexist with "polished" ones that are targeted for

 * specific applications.

 * </p>

 * <p>

 * <b>Event types</b>

 * </p>

 * {@link AccessibilityEvent#TYPE_VIEW_CLICKED}

 * {@link AccessibilityEvent#TYPE_VIEW_LONG_CLICKED}

 * {@link AccessibilityEvent#TYPE_VIEW_FOCUSED}

 * {@link AccessibilityEvent#TYPE_VIEW_SELECTED}

 * {@link AccessibilityEvent#TYPE_VIEW_TEXT_CHANGED}

 * {@link AccessibilityEvent#TYPE_WINDOW_STATE_CHANGED}

 * {@link AccessibilityEvent#TYPE_NOTIFICATION_STATE_CHANGED}

 * {@link AccessibilityEvent#TYPE_TOUCH_EXPLORATION_GESTURE_START}

 * {@link AccessibilityEvent#TYPE_TOUCH_EXPLORATION_GESTURE_END}

 * {@link AccessibilityEvent#TYPE_VIEW_HOVER_ENTER}

 * {@link AccessibilityEvent#TYPE_VIEW_HOVER_EXIT}

 * {@link AccessibilityEvent#TYPE_VIEW_SCROLLED}

 * {@link AccessibilityEvent#TYPE_VIEW_TEXT_SELECTION_CHANGED}

 * {@link AccessibilityEvent#TYPE_WINDOW_CONTENT_CHANGED}

 * <p>

 * <b>Feedback types</b>

 * <p>

 * {@link AccessibilityServiceInfo#FEEDBACK_AUDIBLE}

 * {@link AccessibilityServiceInfo#FEEDBACK_HAPTIC}

 * {@link AccessibilityServiceInfo#FEEDBACK_AUDIBLE}

 * {@link AccessibilityServiceInfo#FEEDBACK_VISUAL}

 * {@link AccessibilityServiceInfo#FEEDBACK_GENERIC}

 *

 * @see AccessibilityEvent

 * @see AccessibilityServiceInfo

 * @see android.view.accessibility.AccessibilityManager

 *

 * <p class="note">

 * <strong>Note:</strong> The event notification timeout is useful to avoid propagating

 * events to the client too frequently since this is accomplished via an expensive

 * interprocess call. One can think of the timeout as a criteria to determine when

 * event generation has settled down.

 * event generation has settled down.</p>

 * <h3>Event types</h3>

 * <ul>

 * <li>{@link AccessibilityEvent#TYPE_VIEW_CLICKED}

 * <li>{@link AccessibilityEvent#TYPE_VIEW_LONG_CLICKED}

 * <li>{@link AccessibilityEvent#TYPE_VIEW_FOCUSED}

 * <li>{@link AccessibilityEvent#TYPE_VIEW_SELECTED}

 * <li>{@link AccessibilityEvent#TYPE_VIEW_TEXT_CHANGED}

 * <li>{@link AccessibilityEvent#TYPE_WINDOW_STATE_CHANGED}

 * <li>{@link AccessibilityEvent#TYPE_NOTIFICATION_STATE_CHANGED}

 * <li>{@link AccessibilityEvent#TYPE_TOUCH_EXPLORATION_GESTURE_START}

 * <li>{@link AccessibilityEvent#TYPE_TOUCH_EXPLORATION_GESTURE_END}

 * <li>{@link AccessibilityEvent#TYPE_VIEW_HOVER_ENTER}

 * <li>{@link AccessibilityEvent#TYPE_VIEW_HOVER_EXIT}

 * <li>{@link AccessibilityEvent#TYPE_VIEW_SCROLLED}

 * <li>{@link AccessibilityEvent#TYPE_VIEW_TEXT_SELECTION_CHANGED}

 * <li>{@link AccessibilityEvent#TYPE_WINDOW_CONTENT_CHANGED}

 * </ul>

 * <h3>Feedback types</h3>

 * <ul>

 * <li>{@link AccessibilityServiceInfo#FEEDBACK_AUDIBLE}

 * <li>{@link AccessibilityServiceInfo#FEEDBACK_HAPTIC}

 * <li>{@link AccessibilityServiceInfo#FEEDBACK_AUDIBLE}

 * <li>{@link AccessibilityServiceInfo#FEEDBACK_VISUAL}

 * <li>{@link AccessibilityServiceInfo#FEEDBACK_GENERIC}

 * </ul>

 * @see AccessibilityEvent

 * @see AccessibilityServiceInfo

 * @see android.view.accessibility.AccessibilityManager

 */

public abstract class AccessibilityService extends Service {

    /**
@@ -225,10 +202,7 @@ public abstract class AccessibilityService extends Service { 
     * about itself. This meta-data must reference an XML resource containing an

     * <code>&lt;{@link android.R.styleable#AccessibilityService accessibility-service}&gt;</code>

     * tag. This is a a sample XML file configuring an accessibility service:

     * <p>

     * <code>

     * <pre>

     *   &lt;accessibility-service

     * <pre> &lt;accessibility-service

     *     android:accessibilityEventTypes="typeViewClicked|typeViewFocused"

     *     android:packageNames="foo.bar, foo.baz"

     *     android:accessibilityFeedbackType="feedbackSpoken"
@@ -237,10 +211,7 @@ public abstract class AccessibilityService extends Service { 
     *     android:settingsActivity="foo.bar.TestBackActivity"

     *     android:canRetrieveWindowContent="true"

     *     . . .

     *   /&gt;

     * </pre>

     * </code>

     * </p>

     * /&gt;</pre>

     */

    public static final String SERVICE_META_DATA = "android.accessibilityservice";

core/java/android/view/View.java

+22 −20
Original line number Diff line number Diff line
@@ -3810,7 +3810,10 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal 
     * responsible for handling this call.

     * </p>

     *

     * @param eventType The type of the event to send.

     * @param eventType The type of the event to send, as defined by several types from

     * {@link android.view.accessibility.AccessibilityEvent}, such as

     * {@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_CLICKED} or

     * {@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_HOVER_ENTER}.

     *

     * @see #onInitializeAccessibilityEvent(AccessibilityEvent)

     * @see #dispatchPopulateAccessibilityEvent(AccessibilityEvent)
@@ -3923,27 +3926,28 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal 
    /**

     * Called from {@link #dispatchPopulateAccessibilityEvent(AccessibilityEvent)}

     * giving a chance to this View to populate the accessibility event with its

     * text content. While the implementation is free to modify other event

     * attributes this should be performed in

     * text content. While this method is free to modify event

     * attributes other than text content, doing so should normally be performed in

     * {@link #onInitializeAccessibilityEvent(AccessibilityEvent)}.

     * <p>

     * Example: Adding formatted date string to an accessibility event in addition

     *          to the text added by the super implementation.

     * </p><p><pre><code>

     * public void onPopulateAccessibilityEvent(AccessibilityEvent event) {

     *          to the text added by the super implementation:

     * <pre> public void onPopulateAccessibilityEvent(AccessibilityEvent event) {

     *     super.onPopulateAccessibilityEvent(event);

     *     final int flags = DateUtils.FORMAT_SHOW_DATE | DateUtils.FORMAT_SHOW_WEEKDAY;

     *     String selectedDateUtterance = DateUtils.formatDateTime(mContext,

     *         mCurrentDate.getTimeInMillis(), flags);

     *     event.getText().add(selectedDateUtterance);

     * }

     * </code></pre></p>

     * }</pre>

     * <p>

     * If an {@link AccessibilityDelegate} has been specified via calling

     * {@link #setAccessibilityDelegate(AccessibilityDelegate)} its

     * {@link AccessibilityDelegate#onPopulateAccessibilityEvent(View, AccessibilityEvent)}

     * is responsible for handling this call.

     * </p>

     * <p class="note"><strong>Note:</strong> Always call the super implementation before adding

     * information to the event, in case the default implementation has basic information to add.

     * </p>

     *

     * @param event The accessibility event which to populate.

     *
@@ -3974,20 +3978,20 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal 
     * the event.

     * <p>

     * Example: Setting the password property of an event in addition

     *          to properties set by the super implementation.

     * </p><p><pre><code>

     * public void onInitializeAccessibilityEvent(AccessibilityEvent event) {

     *          to properties set by the super implementation:

     * <pre> public void onInitializeAccessibilityEvent(AccessibilityEvent event) {

     *     super.onInitializeAccessibilityEvent(event);

     *     event.setPassword(true);

     * }

     * </code></pre></p>

     * }</pre>

     * <p>

     * If an {@link AccessibilityDelegate} has been specified via calling

     * {@link #setAccessibilityDelegate(AccessibilityDelegate)} its

     * {@link AccessibilityDelegate#onInitializeAccessibilityEvent(View, AccessibilityEvent)}

     * is responsible for handling this call.

     * </p>

     *

     * <p class="note"><strong>Note:</strong> Always call the super implementation before adding

     * information to the event, in case the default implementation has basic information to add.

     * </p>

     * @param event The event to initialize.

     *

     * @see #sendAccessibilityEvent(int)
@@ -6159,8 +6163,7 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal 
     * are delivered to the view under the pointer.  All other generic motion events are

     * delivered to the focused view.

     * </p>

     * <code>

     * public boolean onGenericMotionEvent(MotionEvent event) {

     * <pre> public boolean onGenericMotionEvent(MotionEvent event) {

     *     if ((event.getSource() &amp; InputDevice.SOURCE_CLASS_JOYSTICK) != 0) {

     *         if (event.getAction() == MotionEvent.ACTION_MOVE) {

     *             // process the joystick movement...
@@ -6178,8 +6181,7 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal 
     *         }

     *     }

     *     return super.onGenericMotionEvent(event);

     * }

     * </code>

     * }</pre>

     *

     * @param event The generic motion event being processed.

     * @return True if the event was handled, false otherwise.

core/java/android/view/accessibility/AccessibilityManager.java

+6 −5
Original line number Diff line number Diff line
@@ -49,10 +49,8 @@ import java.util.concurrent.CopyOnWriteArrayList; 
 * </p>

 * <p>

 * <code>

 * <pre>

 *   AccessibilityManager accessibilityManager =

 *           (AccessibilityManager) context.getSystemService(Context.ACCESSIBILITY_SERVICE);

 * </pre>

 * <pre>AccessibilityManager accessibilityManager =

 *        (AccessibilityManager) context.getSystemService(Context.ACCESSIBILITY_SERVICE);</pre>

 * </code>

 * </p>

 *
@@ -91,7 +89,10 @@ public final class AccessibilityManager { 
        new CopyOnWriteArrayList<AccessibilityStateChangeListener>();



    /**

     * Listener for the accessibility state.

     * Listener for the system accessibility state. To listen for changes to the accessibility

     * state on the device, implement this interface and register it with the system by

     * calling {@link AccessibilityManager#addAccessibilityStateChangeListener

     * addAccessibilityStateChangeListener()}.

     */

    public interface AccessibilityStateChangeListener {