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

Commit d25aeaa8 authored by Sally Yuen's avatar Sally Yuen
Browse files

Impove scrolling and drag accessibility documentation 

- Specify that scroll actions should send TYPE_VIEW_SCROLLED events
- Add examples of adding and implementing the actions
- Recommend adding the scroll direction or page direction actions
- Specify more properies that should be popualted for scroll events
- Add more details on expected implementation for drag actions

Bug: 283458590
Test: n/a
Change-Id: I3dc8bbfb52fd243ba707d5b2a40732261ce906e5
parent d9b8ce09

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

+14 −2
Original line number Diff line number Diff line
@@ -192,6 +192,8 @@ import java.util.List; 
 *   <li>{@link #getEventTime()}  - The event time.</li>

 *   <li>{@link #getScrollDeltaX()} - The difference in the horizontal position.</li>

 *   <li>{@link #getScrollDeltaY()} - The difference in the vertical position.</li>

 *   <li>{@link #getMaxScrollX()} ()} -  The max scroll offset of the source left edge</li>

 *   <li>{@link #getMaxScrollY()} ()} - The max scroll offset of the source top edge.</li>

 * </ul>

 * </p>

 * <p>
@@ -534,8 +536,18 @@ public final class AccessibilityEvent extends AccessibilityRecord implements Par 
    public static final int TYPE_WINDOW_CONTENT_CHANGED = 1 << 11;



    /**

     * Represents the event of scrolling a view. This event type is generally not sent directly.

     * @see android.view.View#onScrollChanged(int, int, int, int)

     * Represents the event of scrolling a view. This event type is generally not sent directly. In

     * the View system, this is sent in

     * {@link android.view.View#onScrollChanged(int, int, int, int)}

     * <p>In addition to the source and package name, the event should populate scroll-specific

     * properties like {@link #setScrollDeltaX(int)}, {@link #setScrollDeltaY(int)},

     * {@link #setMaxScrollX(int)}, and {@link #setMaxScrollY(int)}.

     * <p>Services are encouraged to rely on the source to query UI state over AccessibilityEvents

     * properties. For example, to check after a scroll if the bottom of the scrolling UI element

     * has been reached, check if the source node is scrollable and has the

     * {@link AccessibilityNodeInfo.AccessibilityAction#ACTION_SCROLL_BACKWARD} action but not the

     * {@link AccessibilityNodeInfo.AccessibilityAction#ACTION_SCROLL_FORWARD} action.

     * For scrolling to a target, use {@link #TYPE_VIEW_TARGETED_BY_SCROLL}.

     */

    public static final int TYPE_VIEW_SCROLLED = 1 << 12;

core/java/android/view/accessibility/AccessibilityNodeInfo.java

+111 −3
Original line number Diff line number Diff line
@@ -421,11 +421,13 @@ public class AccessibilityNodeInfo implements Parcelable { 


    /**

     * Action to scroll the node content forward.

     * @see AccessibilityAction#ACTION_SCROLL_FORWARD

     */

    public static final int ACTION_SCROLL_FORWARD = 1 << 12;



    /**

     * Action to scroll the node content backward.

     * @see AccessibilityAction#ACTION_SCROLL_BACKWARD

     */

    public static final int ACTION_SCROLL_BACKWARD = 1 << 13;
@@ -5363,6 +5365,42 @@ public class AccessibilityNodeInfo implements Parcelable { 
         *     <strong>Arguments:</strong>

         *     {@link #ACTION_ARGUMENT_SCROLL_AMOUNT_FLOAT}. This is an optional argument.

         * </p>

         * <p>The UI element that implements this should send a

         * {@link AccessibilityEvent#TYPE_VIEW_SCROLLED} event. Depending on the orientation,

         * this element should also add the relevant directional scroll actions of

         * {@link #ACTION_SCROLL_LEFT}, {@link #ACTION_SCROLL_RIGHT},

         * {@link #ACTION_SCROLL_UP}, and {@link #ACTION_SCROLL_DOWN}. If the scrolling brings

         * the next or previous element into view as the center element, such as in a ViewPager2,

         * use {@link #ACTION_PAGE_DOWN} and the other page actions instead of the directional

         * actions.

         * <p>Example: a scrolling UI of vertical orientation with a forward

         * scroll action should also add the scroll down action:

         * <pre class="prettyprint"><code>

         *     onInitializeAccessibilityNodeInfo(AccessibilityNodeInfo info) {

         *          super.onInitializeAccessibilityNodeInfo(info);

         *          if (canScrollForward) {

         *              info.addAction(ACTION_SCROLL_FORWARD);

         *              info.addAction(ACTION_SCROLL_DOWN);

         *          }

         *     }

         *     performAccessibilityAction(int action, Bundle bundle) {

         *          if (action == ACTION_SCROLL_FORWARD || action == ACTION_SCROLL_DOWN) {

         *              scrollForward();

         *          }

         *     }

         *     scrollForward() {

         *         ...

         *         if (mAccessibilityManager.isEnabled()) {

         *             event = new AccessibilityEvent(AccessibilityEvent.TYPE_VIEW_SCROLLED);

         *             event.setScrollDeltaX(dx);

         *             event.setScrollDeltaY(dy);

         *             event.setMaxScrollX(maxDx);

         *             event.setMaxScrollY(maxDY);

         *             sendAccessibilityEventUnchecked(event);

         *        }

         *     }

         *      </code>

         * </pre></p>

         */

        public static final AccessibilityAction ACTION_SCROLL_FORWARD =

                new AccessibilityAction(AccessibilityNodeInfo.ACTION_SCROLL_FORWARD);
@@ -5373,6 +5411,54 @@ public class AccessibilityNodeInfo implements Parcelable { 
         *     <strong>Arguments:</strong>

         *     {@link #ACTION_ARGUMENT_SCROLL_AMOUNT_FLOAT}. This is an optional argument.

         * </p>

         * <p>The UI element that implements this should send a

         * {@link AccessibilityEvent#TYPE_VIEW_SCROLLED} event. Depending on the orientation,

         * this element should also add the relevant directional scroll actions of

         * {@link #ACTION_SCROLL_LEFT}, {@link #ACTION_SCROLL_RIGHT},

         * {@link #ACTION_SCROLL_UP}, and {@link #ACTION_SCROLL_DOWN}. If the scrolling brings

         * the next or previous element into view as the center element, such as in a ViewPager2,

         * use {@link #ACTION_PAGE_DOWN} and the other page actions instead of the directional

         * actions.

         * <p> Example: a scrolling UI of horizontal orientation with a backward

         * scroll action should also add the scroll left/right action (LTR/RTL):

         * <pre class="prettyprint"><code>

         *     onInitializeAccessibilityNodeInfo(AccessibilityNodeInfo info) {

         *          super.onInitializeAccessibilityNodeInfo(info);

         *          if (canScrollBackward) {

         *              info.addAction(ACTION_SCROLL_FORWARD);

         *              if (leftToRight) {

         *                  info.addAction(ACTION_SCROLL_LEFT);

         *              } else {

         *                  info.addAction(ACTION_SCROLL_RIGHT);

         *              }

         *          }

         *     }

         *     performAccessibilityAction(int action, Bundle bundle) {

         *          if (action == ACTION_SCROLL_BACKWARD) {

         *              scrollBackward();

         *          } else if (action == ACTION_SCROLL_LEFT) {

         *              if (!isRTL()){

         *                  scrollBackward();

         *              }

         *          } else if (action == ACTION_SCROLL_RIGHT) {

         *              if (isRTL()){

         *                  scrollBackward();

         *              }

         *          }

         *     }

         *     scrollBackward() {

         *         ...

         *         if (mAccessibilityManager.isEnabled()) {

         *             event = new AccessibilityEvent(AccessibilityEvent.TYPE_VIEW_SCROLLED);

         *             event.setScrollDeltaX(dx);

         *             event.setScrollDeltaY(dy);

         *             event.setMaxScrollX(maxDx);

         *             event.setMaxScrollY(maxDY);

         *             sendAccessibilityEventUnchecked(event);

         *        }

         *     }

         *      </code>

         * </pre></p>

         */

        public static final AccessibilityAction ACTION_SCROLL_BACKWARD =

                new AccessibilityAction(AccessibilityNodeInfo.ACTION_SCROLL_BACKWARD);
@@ -5468,6 +5554,8 @@ public class AccessibilityNodeInfo implements Parcelable { 
        /**

         * Action that requests the node make its bounding rectangle visible

         * on the screen, scrolling if necessary just enough.

         * <p>The UI element that implements this should send a

         * {@link AccessibilityEvent#TYPE_VIEW_SCROLLED} event.

         *

         * @see View#requestRectangleOnScreen(Rect)

         */
@@ -5483,6 +5571,8 @@ public class AccessibilityNodeInfo implements Parcelable { 
         *     <li>{@link AccessibilityNodeInfo#ACTION_ARGUMENT_ROW_INT}</li>

         *     <li>{@link AccessibilityNodeInfo#ACTION_ARGUMENT_COLUMN_INT}</li>

         * <ul>

         * <p>The UI element that implements this should send a

         * {@link AccessibilityEvent#TYPE_VIEW_SCROLLED} event.

         *

         * @see AccessibilityNodeInfo#getCollectionInfo()

         */
@@ -5521,6 +5611,8 @@ public class AccessibilityNodeInfo implements Parcelable { 
         *     <strong>Arguments:</strong>

         *     {@link #ACTION_ARGUMENT_SCROLL_AMOUNT_FLOAT}. This is an optional argument.

         * </p>

         * <p>The UI element that implements this should send a

         * {@link AccessibilityEvent#TYPE_VIEW_SCROLLED} event.

         */

        public static final AccessibilityAction ACTION_SCROLL_UP =

                new AccessibilityAction(R.id.accessibilityActionScrollUp);
@@ -5531,6 +5623,8 @@ public class AccessibilityNodeInfo implements Parcelable { 
         *     <strong>Arguments:</strong>

         *     {@link #ACTION_ARGUMENT_SCROLL_AMOUNT_FLOAT}. This is an optional argument.

         * </p>

         * <p>The UI element that implements this should send a

         * {@link AccessibilityEvent#TYPE_VIEW_SCROLLED} event.

         */

        public static final AccessibilityAction ACTION_SCROLL_LEFT =

                new AccessibilityAction(R.id.accessibilityActionScrollLeft);
@@ -5541,6 +5635,8 @@ public class AccessibilityNodeInfo implements Parcelable { 
         *     <strong>Arguments:</strong>

         *     {@link #ACTION_ARGUMENT_SCROLL_AMOUNT_FLOAT}. This is an optional argument.

         * </p>

         * <p>The UI element that implements this should send a

         * {@link AccessibilityEvent#TYPE_VIEW_SCROLLED} event.

         */

        public static final AccessibilityAction ACTION_SCROLL_DOWN =

                new AccessibilityAction(R.id.accessibilityActionScrollDown);
@@ -5551,30 +5647,40 @@ public class AccessibilityNodeInfo implements Parcelable { 
         *     <strong>Arguments:</strong>

         *     {@link #ACTION_ARGUMENT_SCROLL_AMOUNT_FLOAT}. This is an optional argument.

         * </p>

         * <p>The UI element that implements this should send a

         * {@link AccessibilityEvent#TYPE_VIEW_SCROLLED} event.

         */

        public static final AccessibilityAction ACTION_SCROLL_RIGHT =

                new AccessibilityAction(R.id.accessibilityActionScrollRight);



        /**

         * Action to move to the page above.

         * <p>The UI element that implements this should send a

         * {@link AccessibilityEvent#TYPE_VIEW_SCROLLED} event.

         */

        public static final AccessibilityAction ACTION_PAGE_UP =

                new AccessibilityAction(R.id.accessibilityActionPageUp);



        /**

         * Action to move to the page below.

         * <p>The UI element that implements this should send a

         * {@link AccessibilityEvent#TYPE_VIEW_SCROLLED} event.

         */

        public static final AccessibilityAction ACTION_PAGE_DOWN =

                new AccessibilityAction(R.id.accessibilityActionPageDown);



        /**

         * Action to move to the page left.

         * <p>The UI element that implements this should send a

         * {@link AccessibilityEvent#TYPE_VIEW_SCROLLED} event.

         */

        public static final AccessibilityAction ACTION_PAGE_LEFT =

                new AccessibilityAction(R.id.accessibilityActionPageLeft);



        /**

         * Action to move to the page right.

         * <p>The UI element that implements this should send a

         * {@link AccessibilityEvent#TYPE_VIEW_SCROLLED} event.

         */

        public static final AccessibilityAction ACTION_PAGE_RIGHT =

                new AccessibilityAction(R.id.accessibilityActionPageRight);
@@ -5679,8 +5785,9 @@ public class AccessibilityNodeInfo implements Parcelable { 
         * This action initiates a drag & drop within the system. The source's dragged content is

         * prepared before the drag begins. In View, this action should prepare the arguments to

         * {@link View#startDragAndDrop(ClipData, View.DragShadowBuilder, Object, int)} and then

         * call {@link View#startDragAndDrop(ClipData, View.DragShadowBuilder, Object, int)}. The

         * equivalent should be performed for other UI toolkits.

         * call {@link View#startDragAndDrop(ClipData, View.DragShadowBuilder, Object, int)} with

         * {@link View#DRAG_FLAG_ACCESSIBILITY_ACTION}. The equivalent should be performed for other

         * UI toolkits.

         * </p>

         *

         * @see AccessibilityEvent#CONTENT_CHANGE_TYPE_DRAG_STARTED
@@ -5694,7 +5801,8 @@ public class AccessibilityNodeInfo implements Parcelable { 
         * This action is added to potential drop targets if the source started a drag with

         * {@link #ACTION_DRAG_START}. In View, these targets are Views that accepted

         * {@link android.view.DragEvent#ACTION_DRAG_STARTED} and have an

         * {@link View.OnDragListener}.

         * {@link View.OnDragListener}, and the drop occurs at the center location of the View's

         * window bounds.

         * </p>

         *

         * @see AccessibilityEvent#CONTENT_CHANGE_TYPE_DRAG_DROPPED