Merge "Clarify accessibility event documentation"

1 files changed, 35 insertions, 172 deletions

diff --git a/core/java/android/view/accessibility/AccessibilityEvent.java b/core/java/android/view/accessibility/AccessibilityEvent.java
index 98715395f976..6c2d34988896 100644
--- a/core/java/android/view/accessibility/AccessibilityEvent.java
+++ b/core/java/android/view/accessibility/AccessibilityEvent.java
@@ -38,19 +38,14 @@ import java.util.List;
  * <p>
  * An accessibility event is fired by an individual view which populates the event with
  * data for its state and requests from its parent to send the event to interested
- * parties. The parent can optionally add an {@link AccessibilityRecord} for itself before
- * dispatching a similar request to its parent. A parent can also choose not to respect the
- * request for sending an event. The accessibility event is sent by the topmost view in the
- * view tree. Therefore, an {@link android.accessibilityservice.AccessibilityService} can
- * explore all records in an accessibility event to obtain more information about the
- * context in which the event was fired.
+ * parties. The parent can optionally modify or even block the event based on its broader
+ * understanding of the user interface's context.
  * </p>
  * <p>
- * The main purpose of an accessibility event is to expose enough information for an
- * {@link android.accessibilityservice.AccessibilityService} to provide meaningful feedback
- * to the user. Sometimes however, an accessibility service may need more contextual
- * information then the one in the event pay-load. In such cases the service can obtain
- * the event source which is an {@link AccessibilityNodeInfo} (snapshot of a View state)
+ * The main purpose of an accessibility event is to communicate changes in the UI to an
+ * {@link android.accessibilityservice.AccessibilityService}. The service may then inspect,
+ * if needed the user interface by examining the View hierarchy, as represented by a tree of
+ * {@link AccessibilityNodeInfo}s (snapshot of a View state)
  * which can be used for exploring the window content. Note that the privilege for accessing
  * an event's source, thus the window content, has to be explicitly requested. For more
  * details refer to {@link android.accessibilityservice.AccessibilityService}. If an
@@ -85,21 +80,6 @@ import java.util.List;
  *   <li>{@link #getClassName()} - The class name of the source.</li>
  *   <li>{@link #getPackageName()} - The package name of the source.</li>
  *   <li>{@link #getEventTime()}  - The event time.</li>
- *   <li>{@link #getText()} - The text of the source's sub-tree.</li>
- *   <li>{@link #isEnabled()} - Whether the source is enabled.</li>
- *   <li>{@link #isPassword()} - Whether the source is password.</li>
- *   <li>{@link #isChecked()} - Whether the source is checked.</li>
- *   <li>{@link #getContentDescription()} - The content description of the source.</li>
- *   <li>{@link #getScrollX()} - The offset of the source left edge in pixels
- *       (without descendants of AdapterView).</li>
- *   <li>{@link #getScrollY()} - The offset of the source top edge in pixels
- *       (without descendants of AdapterView).</li>
- *   <li>{@link #getFromIndex()} - The zero based index of the first visible item of the source,
- *       inclusive (for descendants of AdapterView).</li>
- *   <li>{@link #getToIndex()} - The zero based index of the last visible item of the source,
- *       inclusive (for descendants of AdapterView).</li>
- *   <li>{@link #getItemCount()} - The total items of the source
- *       (for descendants of AdapterView).</li>
  * </ul>
  * </p>
  * <p>
@@ -113,21 +93,6 @@ import java.util.List;
  *   <li>{@link #getClassName()} - The class name of the source.</li>
  *   <li>{@link #getPackageName()} - The package name of the source.</li>
  *   <li>{@link #getEventTime()}  - The event time.</li>
- *   <li>{@link #getText()} - The text of the source's sub-tree.</li>
- *   <li>{@link #isEnabled()} - Whether the source is enabled.</li>
- *   <li>{@link #isPassword()} - Whether the source is password.</li>
- *   <li>{@link #isChecked()} - Whether the source is checked.</li>
- *   <li>{@link #getContentDescription()} - The content description of the source.</li>
- *   <li>{@link #getScrollX()} - The offset of the source left edge in pixels
- *       (without descendants of AdapterView).</li>
- *   <li>{@link #getScrollY()} - The offset of the source top edge in pixels
- *       (without descendants of AdapterView).</li>
- *   <li>{@link #getFromIndex()} - The zero based index of the first visible item of the source,
- *       inclusive (for descendants of AdapterView).</li>
- *   <li>{@link #getToIndex()} - The zero based index of the last visible item of the source,
- *       inclusive (for descendants of AdapterView).</li>
- *   <li>{@link #getItemCount()} - The total items of the source
- *       (for descendants of AdapterView).</li>
  * </ul>
  * </p>
  * <p>
@@ -141,23 +106,6 @@ import java.util.List;
  *   <li>{@link #getClassName()} - The class name of the source.</li>
  *   <li>{@link #getPackageName()} - The package name of the source.</li>
  *   <li>{@link #getEventTime()}  - The event time.</li>
- *   <li>{@link #getText()} - The text of the source's sub-tree.</li>
- *   <li>{@link #isEnabled()} - Whether the source is enabled.</li>
- *   <li>{@link #isPassword()} - Whether the source is password.</li>
- *   <li>{@link #isChecked()} - Whether the source is checked.</li>
- *   <li>{@link #getItemCount()} - The number of selectable items of the source.</li>
- *   <li>{@link #getCurrentItemIndex()} - The currently selected item index.</li>
- *   <li>{@link #getContentDescription()} - The content description of the source.</li>
- *   <li>{@link #getScrollX()} - The offset of the source left edge in pixels
- *       (without descendants of AdapterView).</li>
- *   <li>{@link #getScrollY()} - The offset of the source top edge in pixels
- *       (without descendants of AdapterView).</li>
- *   <li>{@link #getFromIndex()} - The zero based index of the first visible item of the source,
- *       inclusive (for descendants of AdapterView).</li>
- *   <li>{@link #getToIndex()} - The zero based index of the last visible item of the source,
- *       inclusive (for descendants of AdapterView).</li>
- *   <li>{@link #getItemCount()} - The total items of the source
- *       (for descendants of AdapterView).</li>
  * </ul>
  * </p>
  * <p>
@@ -171,23 +119,6 @@ import java.util.List;
  *   <li>{@link #getClassName()} - The class name of the source.</li>
  *   <li>{@link #getPackageName()} - The package name of the source.</li>
  *   <li>{@link #getEventTime()}  - The event time.</li>
- *   <li>{@link #getText()} - The text of the source's sub-tree.</li>
- *   <li>{@link #isEnabled()} - Whether the source is enabled.</li>
- *   <li>{@link #isPassword()} - Whether the source is password.</li>
- *   <li>{@link #isChecked()} - Whether the source is checked.</li>
- *   <li>{@link #getItemCount()} - The number of focusable items on the screen.</li>
- *   <li>{@link #getCurrentItemIndex()} - The currently focused item index.</li>
- *   <li>{@link #getContentDescription()} - The content description of the source.</li>
- *   <li>{@link #getScrollX()} - The offset of the source left edge in pixels
- *       (without descendants of AdapterView).</li>
- *   <li>{@link #getScrollY()} - The offset of the source top edge in pixels
- *       (without descendants of AdapterView).</li>
- *   <li>{@link #getFromIndex()} - The zero based index of the first visible item of the source,
- *       inclusive (for descendants of AdapterView).</li>
- *   <li>{@link #getToIndex()} - The zero based index of the last visible item of the source,
- *       inclusive (for descendants of AdapterView).</li>
- *   <li>{@link #getItemCount()} - The total items of the source
- *       (for descendants of AdapterView).</li>
  * </ul>
  * </p>
  * <p>
@@ -201,15 +132,11 @@ import java.util.List;
  *   <li>{@link #getClassName()} - The class name of the source.</li>
  *   <li>{@link #getPackageName()} - The package name of the source.</li>
  *   <li>{@link #getEventTime()}  - The event time.</li>
- *   <li>{@link #getText()} - The text of the source.</li>
- *   <li>{@link #isEnabled()} - Whether the source is enabled.</li>
- *   <li>{@link #isPassword()} - Whether the source is password.</li>
- *   <li>{@link #isChecked()} - Whether the source is checked.</li>
+ *   <li>{@link #getText()} - The new text of the source.</li>
+ *   <li>{@link #getBeforeText()} - The text of the source before the change.</li>
  *   <li>{@link #getFromIndex()} - The text change start index.</li>
  *   <li>{@link #getAddedCount()} - The number of added characters.</li>
  *   <li>{@link #getRemovedCount()} - The number of removed characters.</li>
- *   <li>{@link #getBeforeText()} - The text of the source before the change.</li>
- *   <li>{@link #getContentDescription()} - The content description of the source.</li>
  * </ul>
  * </p>
  * <p>
@@ -223,13 +150,6 @@ import java.util.List;
  *   <li>{@link #getClassName()} - The class name of the source.</li>
  *   <li>{@link #getPackageName()} - The package name of the source.</li>
  *   <li>{@link #getEventTime()}  - The event time.</li>
- *   <li>{@link #getText()} - The text of the source.</li>
- *   <li>{@link #isPassword()} - Whether the source is password.</li>
- *   <li>{@link #getFromIndex()} - The selection start index.</li>
- *   <li>{@link #getToIndex()} - The selection end index.</li>
- *   <li>{@link #getItemCount()} - The length of the source text.</li>
- *   <li>{@link #isEnabled()} - Whether the source is enabled.</li>
- *   <li>{@link #getContentDescription()} - The content description of the source.</li>
  * </ul>
  * </p>
  * <b>View text traversed at movement granularity</b> - represents the event of traversing the
@@ -251,23 +171,11 @@ import java.util.List;
  *   <li>{@link #getToIndex()} - The end of the text that was skipped over in this movement.
  *       This is the ending point when moving forward through the text, but not when moving
  *       back.</li>
- *   <li>{@link #isPassword()} - Whether the source is password.</li>
- *   <li>{@link #isEnabled()} - Whether the source is enabled.</li>
- *   <li>{@link #getContentDescription()} - The content description of the source.</li>
- *   <li>{@link #getMovementGranularity()} - Sets the granularity at which a view's text
- *       was traversed.</li>
  *   <li>{@link #getAction()} - Gets traversal action which specifies the direction.</li>
  * </ul>
  * </p>
  * <p>
- * <b>View scrolled</b> - represents the event of scrolling a view. If
- * the source is a descendant of {@link android.widget.AdapterView} the
- * scroll is reported in terms of visible items - the first visible item,
- * the last visible item, and the total items - because the the source
- * is unaware of its pixel size since its adapter is responsible for
- * creating views. In all other cases the scroll is reported as the current
- * scroll on the X and Y axis respectively plus the height of the source in
- * pixels.</br>
+ * <b>View scrolled</b> - represents the event of scrolling a view. </br>
  * <em>Type:</em> {@link #TYPE_VIEW_SCROLLED}</br>
  * <em>Properties:</em></br>
  * <ul>
@@ -276,29 +184,9 @@ import java.util.List;
  *   <li>{@link #getClassName()} - The class name of the source.</li>
  *   <li>{@link #getPackageName()} - The package name of the source.</li>
  *   <li>{@link #getEventTime()}  - The event time.</li>
- *   <li>{@link #getText()} - The text of the source's sub-tree.</li>
- *   <li>{@link #isEnabled()} - Whether the source is enabled.</li>
- *   <li>{@link #getContentDescription()} - The content description of the source.</li>
- *   <li>{@link #getScrollX()} - The offset of the source left edge in pixels
- *       (without descendants of AdapterView).</li>
- *   <li>{@link #getScrollY()} - The offset of the source top edge in pixels
- *       (without descendants of AdapterView).</li>
- *   <li>{@link #getFromIndex()} - The zero based index of the first visible item of the source,
- *       inclusive (for descendants of AdapterView).</li>
- *   <li>{@link #getToIndex()} - The zero based index of the last visible item of the source,
- *       inclusive (for descendants of AdapterView).</li>
- *   <li>{@link #getItemCount()} - The total items of the source
- *       (for descendants of AdapterView).</li>
+ *   <li>{@link #getScrollDeltaX()} - The difference in the horizontal position.</li>
+ *   <li>{@link #getScrollDeltaY()} - The difference in the vertical position.</li>
  * </ul>
- * <em>Note:</em> This event type is not dispatched to descendants though
- * {@link android.view.View#dispatchPopulateAccessibilityEvent(AccessibilityEvent)
- * View.dispatchPopulateAccessibilityEvent(AccessibilityEvent)}, hence the event
- * source {@link android.view.View} and the sub-tree rooted at it will not receive
- * calls to {@link android.view.View#onPopulateAccessibilityEvent(AccessibilityEvent)
- * View.onPopulateAccessibilityEvent(AccessibilityEvent)}. The preferred way to add
- * text content to such events is by setting the
- * {@link android.R.styleable#View_contentDescription contentDescription} of the source
- * view.</br>
  * </p>
  * <p>
  * <b>TRANSITION TYPES</b></br>
@@ -316,7 +204,6 @@ import java.util.List;
  *   <li>{@link #getPackageName()} - The package name of the source.</li>
  *   <li>{@link #getEventTime()}  - The event time.</li>
  *   <li>{@link #getText()} - The text of the source's sub-tree.</li>
- *   <li>{@link #isEnabled()} - Whether the source is enabled.</li>
  * </ul>
  * </p>
  * <p>
@@ -325,10 +212,6 @@ import java.util.List;
  * a view size, etc.</br>
  * </p>
  * <p>
- * <strong>Note:</strong> This event is fired only for the window source of the
- * last accessibility event different from {@link #TYPE_NOTIFICATION_STATE_CHANGED}
- * and its purpose is to notify clients that the content of the user interaction
- * window has changed.</br>
  * <em>Type:</em> {@link #TYPE_WINDOW_CONTENT_CHANGED}</br>
  * <em>Properties:</em></br>
  * <ul>
@@ -339,21 +222,14 @@ import java.util.List;
  *   <li>{@link #getPackageName()} - The package name of the source.</li>
  *   <li>{@link #getEventTime()}  - The event time.</li>
  * </ul>
- * <em>Note:</em> This event type is not dispatched to descendants though
- * {@link android.view.View#dispatchPopulateAccessibilityEvent(AccessibilityEvent)
- * View.dispatchPopulateAccessibilityEvent(AccessibilityEvent)}, hence the event
- * source {@link android.view.View} and the sub-tree rooted at it will not receive
- * calls to {@link android.view.View#onPopulateAccessibilityEvent(AccessibilityEvent)
- * View.onPopulateAccessibilityEvent(AccessibilityEvent)}. The preferred way to add
- * text content to such events is by setting the
- * {@link android.R.styleable#View_contentDescription contentDescription} of the source
- * view.</br>
  * </p>
  * <p>
  * <b>Windows changed</b> - represents a change in the windows shown on
  * the screen such as a window appeared, a window disappeared, a window size changed,
  * a window layer changed, etc. These events should only come from the system, which is responsible
- * for managing windows. For regions of the user interface that are presented as windows but are
+ * for managing windows. The list of windows is available from
+ * {@link android.accessibilityservice.AccessibilityService#getWindows()}.
+ * For regions of the user interface that are presented as windows but are
  * controlled by an app's process, use {@link #TYPE_WINDOW_STATE_CHANGED}.</br>
  * <em>Type:</em> {@link #TYPE_WINDOWS_CHANGED}</br>
  * <em>Properties:</em></br>
@@ -403,19 +279,6 @@ import java.util.List;
  *   <li>{@link #getClassName()} - The class name of the source.</li>
  *   <li>{@link #getPackageName()} - The package name of the source.</li>
  *   <li>{@link #getEventTime()}  - The event time.</li>
- *   <li>{@link #getText()} - The text of the source's sub-tree.</li>
- *   <li>{@link #isEnabled()} - Whether the source is enabled.</li>
- *   <li>{@link #getContentDescription()} - The content description of the source.</li>
- *   <li>{@link #getScrollX()} - The offset of the source left edge in pixels
- *       (without descendants of AdapterView).</li>
- *   <li>{@link #getScrollY()} - The offset of the source top edge in pixels
- *       (without descendants of AdapterView).</li>
- *   <li>{@link #getFromIndex()} - The zero based index of the first visible item of the source,
- *       inclusive (for descendants of AdapterView).</li>
- *   <li>{@link #getToIndex()} - The zero based index of the last visible item of the source,
- *       inclusive (for descendants of AdapterView).</li>
- *   <li>{@link #getItemCount()} - The total items of the source
- *       (for descendants of AdapterView).</li>
  * </ul>
  * </p>
  * <b>View hover exit</b> - represents the event of stopping to hover
@@ -429,19 +292,6 @@ import java.util.List;
  *   <li>{@link #getClassName()} - The class name of the source.</li>
  *   <li>{@link #getPackageName()} - The package name of the source.</li>
  *   <li>{@link #getEventTime()}  - The event time.</li>
- *   <li>{@link #getText()} - The text of the source's sub-tree.</li>
- *   <li>{@link #isEnabled()} - Whether the source is enabled.</li>
- *   <li>{@link #getContentDescription()} - The content description of the source.</li>
- *   <li>{@link #getScrollX()} - The offset of the source left edge in pixels
- *       (without descendants of AdapterView).</li>
- *   <li>{@link #getScrollY()} - The offset of the source top edge in pixels
- *       (without descendants of AdapterView).</li>
- *   <li>{@link #getFromIndex()} - The zero based index of the first visible item of the source,
- *       inclusive (for descendants of AdapterView).</li>
- *   <li>{@link #getToIndex()} - The zero based index of the last visible item of the source,
- *       inclusive (for descendants of AdapterView).</li>
- *   <li>{@link #getItemCount()} - The total items of the source
- *       (for descendants of AdapterView).</li>
  * </ul>
  * </p>
  * <p>
@@ -514,10 +364,10 @@ import java.util.List;
  * <b>MISCELLANEOUS TYPES</b></br>
  * </p>
  * <p>
- * <b>Announcement</b> - represents the event of an application making an
- * announcement. Usually this announcement is related to some sort of a context
- * change for which none of the events representing UI transitions is a good fit.
- * For example, announcing a new page in a book.</br>
+ * <b>Announcement</b> - represents the event of an application requesting a screen reader to make
+ * an announcement. Because the event carries no semantic meaning, this event is appropriate only
+ * in exceptional situations where additional screen reader output is needed but other types of
+ * accessibility services do not need to be aware of the change.</br>
  * <em>Type:</em> {@link #TYPE_ANNOUNCEMENT}</br>
  * <em>Properties:</em></br>
  * <ul>
@@ -527,7 +377,6 @@ import java.util.List;
  *   <li>{@link #getPackageName()} - The package name of the source.</li>
  *   <li>{@link #getEventTime()}  - The event time.</li>
  *   <li>{@link #getText()} - The text of the announcement.</li>
- *   <li>{@link #isEnabled()} - Whether the source is enabled.</li>
  * </ul>
  * </p>
  *
@@ -675,7 +524,8 @@ public final class AccessibilityEvent extends AccessibilityRecord implements Par
     public static final int TYPE_TOUCH_INTERACTION_END = 0x00200000;
 
     /**
-     * Represents the event change in the windows shown on the screen.
+     * Represents the event change in the system windows shown on the screen. This event type should
+     * only be dispatched by the system.
      */
     public static final int TYPE_WINDOWS_CHANGED = 0x00400000;
 
@@ -697,7 +547,8 @@ public final class AccessibilityEvent extends AccessibilityRecord implements Par
 
     /**
      * Change type for {@link #TYPE_WINDOW_CONTENT_CHANGED} event:
-     * A node in the subtree rooted at the source node was added or removed.
+     * One or more content changes occurred in the the subtree rooted at the source node,
+     * or the subtree's structure changed when a node was added or removed.
      */
     public static final int CONTENT_CHANGE_TYPE_SUBTREE = 0x00000001;
 
@@ -797,6 +648,17 @@ public final class AccessibilityEvent extends AccessibilityRecord implements Par
     public @interface WindowsChangeTypes {}
 
     /** @hide */
+    @Retention(RetentionPolicy.SOURCE)
+    @IntDef(flag = true, prefix = { "CONTENT_CHANGE_TYPE_" },
+            value = {
+                    CONTENT_CHANGE_TYPE_UNDEFINED,
+                    CONTENT_CHANGE_TYPE_SUBTREE,
+                    CONTENT_CHANGE_TYPE_TEXT,
+                    CONTENT_CHANGE_TYPE_CONTENT_DESCRIPTION
+            })
+    public @interface ContentChangeTypes {}
+
+    /** @hide */
     @IntDef(flag = true, prefix = { "TYPE_" }, value = {
             TYPE_VIEW_CLICKED,
             TYPE_VIEW_LONG_CLICKED,
@@ -970,6 +832,7 @@ public final class AccessibilityEvent extends AccessibilityRecord implements Par
      *         <li>{@link AccessibilityEvent#CONTENT_CHANGE_TYPE_UNDEFINED}
      *         </ul>
      */
+    @ContentChangeTypes
     public int getContentChangeTypes() {
         return mContentChangeTypes;
     }
@@ -998,7 +861,7 @@ public final class AccessibilityEvent extends AccessibilityRecord implements Par
      * @throws IllegalStateException If called from an AccessibilityService.
      * @see #getContentChangeTypes()
      */
-    public void setContentChangeTypes(int changeTypes) {
+    public void setContentChangeTypes(@ContentChangeTypes int changeTypes) {
         enforceNotSealed();
         mContentChangeTypes = changeTypes;
     }