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

Commit 9042643c authored by Phil Weaver's avatar Phil Weaver
Browse files

Clarify accessibility event documentation 

Removing suggestions to get information from events that
can instead be extracted from the node hierarchy.

Clarifying window change and announcement.

Comment changes only. I'm trying to steer developers to
use the APIs as we currently thing about them, but I'm
not changing any behavior.

Test: make
Change-Id: Ieecedbb98bdf11cf0cf4a29856db497986faaca6
parent 01b2f0e1

core/java/android/view/accessibility/AccessibilityEvent.java

+35 −172
Original line number Diff line number Diff line
@@ -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;
@@ -796,6 +647,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,
@@ -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;

    }