From b303d8381d734f48c4e1de4f11bf25950b28adf1 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Wed, 12 Oct 2011 16:45:18 -0700 Subject: [PATCH] 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 --- .../AccessibilityService.java | 133 +++++++----------- core/java/android/view/View.java | 42 +++--- .../accessibility/AccessibilityManager.java | 11 +- 3 files changed, 80 insertions(+), 106 deletions(-) diff --git a/core/java/android/accessibilityservice/AccessibilityService.java b/core/java/android/accessibilityservice/AccessibilityService.java index 1e238f0b03b72..64a275553339d 100644 --- a/core/java/android/accessibilityservice/AccessibilityService.java +++ b/core/java/android/accessibilityservice/AccessibilityService.java @@ -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. - *

- * Lifecycle - *

+ * of the active window. Development of an accessibility service requires extending this + * class and implementing its abstract methods. + *

Lifecycle

*

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

- *

- * Declaration - *

+ *

Declaration

*

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

- *

- * - * 

- *   <service android:name=".MyAccessibilityService">
+ * 
 <service android:name=".MyAccessibilityService">
  *     <intent-filter>
- *       <action android:name="android.accessibilityservice.AccessibilityService" />
+ *         <action android:name="android.accessibilityservice.AccessibilityService" />
  *     </intent-filter>
  *     . . .
- *   </service>
- * 

- * 
- * 

- * 

- * Configuration
- * 

+ * </service>
+ *

Configuration

*

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

  • * 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: - *

    - * - * 

    - *   <service android:name=".MyAccessibilityService">
+ * 
     <service android:name=".MyAccessibilityService">
  *     <intent-filter>
- *       <action android:name="android.accessibilityservice.AccessibilityService" />
+ *         <action android:name="android.accessibilityservice.AccessibilityService" />
  *     </intent-filter>
  *     <meta-data android:name="android.accessibilityservice" android:resource="@xml/accessibilityservice" />
- *   </service>
- * 
    
- *     
- * 
    
- * 
    
- * Note:This approach enables setting all properties.
+ * </service>
    + *

    + * Note: This approach enables setting all properties. *

    *

    * For more details refer to {@link #SERVICE_META_DATA} and - * <{@link android.R.styleable#AccessibilityService accessibility-service}>.. + * <{@link android.R.styleable#AccessibilityService accessibility-service}>. *

    *
    • *
  • * Calling {@link AccessibilityService#setServiceInfo(AccessibilityServiceInfo)}. Note * that this method can be called any time to dynamically change the service configuration. - *

    + *

    * Note: This approach enables setting only dynamically configurable properties: * {@link AccessibilityServiceInfo#eventTypes}, * {@link AccessibilityServiceInfo#feedbackType}, @@ -117,9 +99,7 @@ import android.view.accessibility.AccessibilityNodeInfo; *

    *
    • * - *

    - * Retrieving window content - *

    + *

    Retrieving window content

    *

    * 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,8 +124,8 @@ 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. *

    - *

    - * NoteAn accessibility service may have requested to be notified for + *

    + * Note 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: *

    *

    - *

    - * Notification strategy - *

    + *

    Notification strategy

    *

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

    - *

    - * Event types - *

    - * {@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} - *

    - * Feedback types - *

    - * {@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 - * + *

    * Note: 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.

    + *

    Event types

    + * + *

    Feedback types

    + * + * @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 * <{@link android.R.styleable#AccessibilityService accessibility-service}> * tag. This is a a sample XML file configuring an accessibility service: - *

    - * - * 

    -     *   <accessibility-service
+     * 
     <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"
      *     . . .
-     *   />
-     * 
    
-     *     
-     * 
    
+     * />
    */ public static final String SERVICE_META_DATA = "android.accessibilityservice"; diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java index 86be28a534da1..a1847b45f681e 100644 --- a/core/java/android/view/View.java +++ b/core/java/android/view/View.java @@ -3810,7 +3810,10 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal * responsible for handling this call. *

    * - * @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)}. *

    * Example: Adding formatted date string to an accessibility event in addition - * to the text added by the super implementation. - * 

    
-     * public void onPopulateAccessibilityEvent(AccessibilityEvent event) {
+     *          to the text added by the super implementation:
+     * 
     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);
-     * }
-     * 
    
+     * }
    *

    * If an {@link AccessibilityDelegate} has been specified via calling * {@link #setAccessibilityDelegate(AccessibilityDelegate)} its * {@link AccessibilityDelegate#onPopulateAccessibilityEvent(View, AccessibilityEvent)} * is responsible for handling this call. *

    + *

    Note: Always call the super implementation before adding + * information to the event, in case the default implementation has basic information to add. + *

    * * @param event The accessibility event which to populate. * @@ -3974,20 +3978,20 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal * the event. *

    * Example: Setting the password property of an event in addition - * to properties set by the super implementation. - * 

    
-     * public void onInitializeAccessibilityEvent(AccessibilityEvent event) {
-     *    super.onInitializeAccessibilityEvent(event);
-     *    event.setPassword(true);
-     * }
-     *

    + * to properties set by the super implementation: + * 
     public void onInitializeAccessibilityEvent(AccessibilityEvent event) {
+     *     super.onInitializeAccessibilityEvent(event);
+     *     event.setPassword(true);
+     * }
    *

    * If an {@link AccessibilityDelegate} has been specified via calling * {@link #setAccessibilityDelegate(AccessibilityDelegate)} its * {@link AccessibilityDelegate#onInitializeAccessibilityEvent(View, AccessibilityEvent)} * is responsible for handling this call. *

    - * + *

    Note: Always call the super implementation before adding + * information to the event, in case the default implementation has basic information to add. + *

    * @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. *

    - * - * public boolean onGenericMotionEvent(MotionEvent event) { + * 
     public boolean onGenericMotionEvent(MotionEvent event) {
      *     if ((event.getSource() & 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);
-     * }
-     * 
+     * }
    * * @param event The generic motion event being processed. * @return True if the event was handled, false otherwise. diff --git a/core/java/android/view/accessibility/AccessibilityManager.java b/core/java/android/view/accessibility/AccessibilityManager.java index a80c2a7147c90..e37de6fc4ce9a 100644 --- a/core/java/android/view/accessibility/AccessibilityManager.java +++ b/core/java/android/view/accessibility/AccessibilityManager.java @@ -49,10 +49,8 @@ import java.util.concurrent.CopyOnWriteArrayList; *

    *

    * - * 

    - *   AccessibilityManager accessibilityManager =
- *           (AccessibilityManager) context.getSystemService(Context.ACCESSIBILITY_SERVICE);
- *
    + * 
    AccessibilityManager accessibilityManager =
+ *        (AccessibilityManager) context.getSystemService(Context.ACCESSIBILITY_SERVICE);
    *     *

    * @@ -91,7 +89,10 @@ public final class AccessibilityManager { new CopyOnWriteArrayList(); /** - * 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 {