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

Commit 1357246c authored by Sally's avatar Sally
Browse files

Improve javadocs for a11y live regions and minimum durations 

For live regions:
- Make descriptions generally  more concise.
- Reformat the docs so there is more structure (i.e. lists)
- Separate behavior from semantics by separating notifications from
  announcements
- Discourage live regions for UI that frequently updates
- Link to setMinDurationBetweenContentChanges

For min durations:
- Add examples of widgets that could use durations
- Link to Progressbar

Bug: 332393061
Test: n/a (docs)
Change-Id: I6fcdda3d15d45a572cc9def39e8b3a640a39687c
parent 976207c4

core/java/android/view/View.java

+59 −31
Original line number Original line Diff line number Diff line
@@ -203,6 +203,7 @@ import java.lang.reflect.Field; 
import java.lang.reflect.InvocationTargetException;

import java.lang.reflect.InvocationTargetException;

import java.lang.reflect.Method;

import java.lang.reflect.Method;

import java.lang.reflect.Modifier;

import java.lang.reflect.Modifier;

import java.time.Duration;

import java.util.ArrayList;

import java.util.ArrayList;

import java.util.Arrays;

import java.util.Arrays;

import java.util.Calendar;

import java.util.Calendar;
@@ -3206,16 +3207,17 @@ public class View implements Drawable.Callback, KeyEvent.Callback, 
    public static final int ACCESSIBILITY_LIVE_REGION_NONE = 0x00000000;

    public static final int ACCESSIBILITY_LIVE_REGION_NONE = 0x00000000;

















    /**







    /**











     * Live region mode specifying that accessibility services should announce







     * Live region mode specifying that accessibility services should notify users of changes to











     * changes to this view.







     * this view.











     * <p>







     * <p>











     * Use with {@link #setAccessibilityLiveRegion(int)}.







     * Use with {@link #setAccessibilityLiveRegion(int)}.











     */







     */











    public static final int ACCESSIBILITY_LIVE_REGION_POLITE = 0x00000001;







    public static final int ACCESSIBILITY_LIVE_REGION_POLITE = 0x00000001;



























    /**







    /**











     * Live region mode specifying that accessibility services should interrupt







     * Live region mode specifying that accessibility services should immediately notify users of











     * ongoing speech to immediately announce changes to this view.







     * changes to this view. For example, a screen reader may interrupt ongoing speech to














     * immediately announce these changes.











     * <p>







     * <p>











     * Use with {@link #setAccessibilityLiveRegion(int)}.







     * Use with {@link #setAccessibilityLiveRegion(int)}.











     */







     */










@@ -8492,14 +8494,17 @@ public class View implements Drawable.Callback, KeyEvent.Callback,









     *







     *











     * <p>







     * <p>











     * When transitioning from one Activity to another, instead of using







     * When transitioning from one Activity to another, instead of using











     * setAccessibilityPaneTitle(), set a descriptive title for its window by using android:label







     * {@code setAccessibilityPaneTitle()}, set a descriptive title for its window by using











     * for the matching <activity> entry in your application’s manifest or updating the title at







     * {@code android:label}














     * for the matching Activity entry in your application's manifest or updating the title at











     * runtime with {@link android.app.Activity#setTitle(CharSequence)}.







     * runtime with {@link android.app.Activity#setTitle(CharSequence)}.











     *







     *











     * <p>







     * <p>














     * <aside>











     * <b>Note:</b> Use







     * <b>Note:</b> Use











     * {@link androidx.core.view.ViewCompat#setAccessibilityPaneTitle(View, CharSequence)}







     * {@link androidx.core.view.ViewCompat#setAccessibilityPaneTitle(View, CharSequence)}











     * for backwards-compatibility. </aside>







     * for backwards-compatibility.














     * </aside>











     * @param accessibilityPaneTitle The pane's title. Setting to {@code null} indicates that this







     * @param accessibilityPaneTitle The pane's title. Setting to {@code null} indicates that this











     *                               View is not a pane.







     *                               View is not a pane.











     *







     *










@@ -8607,7 +8612,7 @@ public class View implements Drawable.Callback, KeyEvent.Callback,









     * They should not need to specify what exactly is announced to users.







     * They should not need to specify what exactly is announced to users.











     *







     *











     * <p>







     * <p>











     * In general, only announce transitions and don’t generate a confirmation message for simple







     * In general, only announce transitions and don't generate a confirmation message for simple











     * actions like a button press. Label your controls concisely and precisely instead, and for







     * actions like a button press. Label your controls concisely and precisely instead, and for











     * significant UI changes like window changes, use







     * significant UI changes like window changes, use











     * {@link android.app.Activity#setTitle(CharSequence)} and







     * {@link android.app.Activity#setTitle(CharSequence)} and










@@ -14796,33 +14801,56 @@ public class View implements Drawable.Callback, KeyEvent.Callback,









     * to the view's content description or text, or to the content descriptions







     * to the view's content description or text, or to the content descriptions











     * or text of the view's children (where applicable).







     * or text of the view's children (where applicable).











     * <p>







     * <p>











     * To indicate that the user should be notified of changes, use







     * Different priority levels are available:











     * {@link #ACCESSIBILITY_LIVE_REGION_POLITE}. Announcements from this region are queued and







     * <ul>











     * do not disrupt ongoing speech.







     *   <li>














     *       {@link #ACCESSIBILITY_LIVE_REGION_POLITE}:














     *       Indicates that updates to the region should be presented to the user. Suitable in most














     *       cases for prominent updates within app content that don't require the user's immediate














     *       attention.














     *   </li>














     *   <li>














     *       {@link #ACCESSIBILITY_LIVE_REGION_ASSERTIVE}: Indicates that updates to the region have














     *       the highest priority and should be presented to the user immediately. This may result














     *       in disruptive notifications from an accessibility service, which may potentially














     *       interrupt other feedback or user actions, so it should generally be used only for














     *       critical, time-sensitive information.














     *   </li>














     *   <li>














     *       {@link #ACCESSIBILITY_LIVE_REGION_NONE}: Disables change announcements (the default for














     *       most views).














     *   </li>














     * </ul>











     * <p>







     * <p>











     * For example, selecting an option in a dropdown menu may update a panel below with the updated







     * Examples:














     * <ul>














     *     <li>














     *         Selecting an option in a dropdown menu updates a panel below with the updated











     *         content. This panel may be marked as a live region with







     *         content. This panel may be marked as a live region with











     * {@link #ACCESSIBILITY_LIVE_REGION_POLITE} to notify users of the change.







     *         {@link #ACCESSIBILITY_LIVE_REGION_POLITE} to notify users of the change. A screen














     *         reader may queue changes as announcements that don't disrupt ongoing speech.














     *      </li>














     *      <li>














     *          An emergency alert may be marked with {@link #ACCESSIBILITY_LIVE_REGION_ASSERTIVE}














     *          to immediately inform users of the emergency.














     *      </li>














     * </ul>











     * <p>







     * <p>











     * For notifying users about errors, such as in a login screen with text that displays an







     * For error notifications, like an "incorrect password" warning in a login screen, views











     * "incorrect password" notification, that view should send an AccessibilityEvent of type







     * should send a {@link AccessibilityEvent#TYPE_WINDOW_CONTENT_CHANGED}














     * {@code AccessibilityEvent} with a content change type











     * {@link AccessibilityEvent#CONTENT_CHANGE_TYPE_ERROR} and set







     * {@link AccessibilityEvent#CONTENT_CHANGE_TYPE_ERROR} and set











     * {@link AccessibilityNodeInfo#setError(CharSequence)} instead. Custom widgets should expose







     * {@link AccessibilityNodeInfo#setError(CharSequence)}. Custom widgets should provide











     * error-setting methods that support accessibility automatically. For example, instead of







     * error-setting methods that support accessibility. For example, use











     * explicitly sending this event when using a TextView, use







     * {@link android.widget.TextView#setError(CharSequence)} instead of explicitly sending events.











     * {@link android.widget.TextView#setError(CharSequence)}.














     * <p>














     * To disable change notifications for this view, use














     * {@link #ACCESSIBILITY_LIVE_REGION_NONE}. This is the default live region














     * mode for most views.














     * <p>







     * <p>











     * If the view's changes should interrupt ongoing speech and notify the user







     * Don't use live regions for frequently-updating UI elements (e.g., progress bars), as this can











     * immediately, use {@link #ACCESSIBILITY_LIVE_REGION_ASSERTIVE}. This may result in disruptive







     * overwhelm the user with feedback from accessibility services. If necessary, use











     * announcements from an accessibility service, so it should generally be used only to convey







     * {@link AccessibilityNodeInfo#setMinDurationBetweenContentChanges(Duration)} to throttle











     * information that is time-sensitive or critical for use of the application. Examples may







     * feedback and reduce disruptions.











     * include an incoming call or an emergency alert.














     * <p>







     * <p>











     * <b>Note:</b> Use {@link androidx.core.view.ViewCompat#setAccessibilityLiveRegion(View, int)}







     * <aside><b>Note:</b> Use














     * {@link androidx.core.view.ViewCompat#setAccessibilityLiveRegion(View, int)}











     * for backwards-compatibility. </aside>







     * for backwards-compatibility. </aside>











     *







     *











     * @param mode The live region mode for this view, one of:







     * @param mode The live region mode for this view, one of:

























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



+16
−10




























Original line number
Original line
Diff line number
Diff line








@@ -159,7 +159,7 @@ public class AccessibilityNodeInfo implements Parcelable {









     * <p> To avoid disconnected trees, this flag will also prefetch the parent. Siblings will be







     * <p> To avoid disconnected trees, this flag will also prefetch the parent. Siblings will be











     * prefetched before descendants.







     * prefetched before descendants.











     *







     *











     * @see #FLAG_PREFETCH_ANCESTORS for where to use these flags.







     * <p> See {@link #FLAG_PREFETCH_ANCESTORS} for information on where these flags can be used.











     */







     */











    public static final int FLAG_PREFETCH_SIBLINGS = 1 << 1;







    public static final int FLAG_PREFETCH_SIBLINGS = 1 << 1;





























@@ -171,7 +171,7 @@ public class AccessibilityNodeInfo implements Parcelable {









     * {@link #FLAG_PREFETCH_DESCENDANTS_BREADTH_FIRST} or this will trigger an







     * {@link #FLAG_PREFETCH_DESCENDANTS_BREADTH_FIRST} or this will trigger an











     * IllegalArgumentException.







     * IllegalArgumentException.











     *







     *











     * @see #FLAG_PREFETCH_ANCESTORS for where to use these flags.







     * <p> See {@link #FLAG_PREFETCH_ANCESTORS} for information on where these flags can be used.











     */







     */











    public static final int FLAG_PREFETCH_DESCENDANTS_HYBRID = 1 << 2;







    public static final int FLAG_PREFETCH_DESCENDANTS_HYBRID = 1 << 2;





























@@ -181,7 +181,7 @@ public class AccessibilityNodeInfo implements Parcelable {









     * {@link #FLAG_PREFETCH_DESCENDANTS_BREADTH_FIRST} or this will trigger an







     * {@link #FLAG_PREFETCH_DESCENDANTS_BREADTH_FIRST} or this will trigger an











     * IllegalArgumentException.







     * IllegalArgumentException.











     *







     *











     * @see #FLAG_PREFETCH_ANCESTORS for where to use these flags.







     * <p> See {@link #FLAG_PREFETCH_ANCESTORS} for information on where these flags can be used.











     */







     */











    public static final int FLAG_PREFETCH_DESCENDANTS_DEPTH_FIRST = 1 << 3;







    public static final int FLAG_PREFETCH_DESCENDANTS_DEPTH_FIRST = 1 << 3;





























@@ -191,7 +191,7 @@ public class AccessibilityNodeInfo implements Parcelable {









     * {@link #FLAG_PREFETCH_DESCENDANTS_DEPTH_FIRST} or this will trigger an







     * {@link #FLAG_PREFETCH_DESCENDANTS_DEPTH_FIRST} or this will trigger an











     * IllegalArgumentException.







     * IllegalArgumentException.











     *







     *











     * @see #FLAG_PREFETCH_ANCESTORS for where to use these flags.







     * <p> See {@link #FLAG_PREFETCH_ANCESTORS} for information on where these flags can be used.











     */







     */











    public static final int FLAG_PREFETCH_DESCENDANTS_BREADTH_FIRST = 1 << 4;







    public static final int FLAG_PREFETCH_DESCENDANTS_BREADTH_FIRST = 1 << 4;





























@@ -199,7 +199,7 @@ public class AccessibilityNodeInfo implements Parcelable {









     * Prefetching flag that specifies prefetching should not be interrupted by a request to







     * Prefetching flag that specifies prefetching should not be interrupted by a request to











     * retrieve a node or perform an action on a node.







     * retrieve a node or perform an action on a node.











     *







     *











     * @see #FLAG_PREFETCH_ANCESTORS for where to use these flags.







     * <p> See {@link #FLAG_PREFETCH_ANCESTORS} for information on where these flags can be used.











     */







     */











    public static final int FLAG_PREFETCH_UNINTERRUPTIBLE = 1 << 5;







    public static final int FLAG_PREFETCH_UNINTERRUPTIBLE = 1 << 5;






























@@ -1295,6 +1295,8 @@ public class AccessibilityNodeInfo implements Parcelable {









    /**







    /**











     * Get the child at given index.







     * Get the child at given index.











     *







     *














     * <p>














     * See {@link #getParent(int)} for a description of prefetching.











     * @param index The child index.







     * @param index The child index.











     * @param prefetchingStrategy the prefetching strategy.







     * @param prefetchingStrategy the prefetching strategy.











     * @return The child node.







     * @return The child node.









@@ -1302,7 +1304,6 @@ public class AccessibilityNodeInfo implements Parcelable {









     * @throws IllegalStateException If called outside of an {@link AccessibilityService} and before







     * @throws IllegalStateException If called outside of an {@link AccessibilityService} and before











     *                               calling {@link #setQueryFromAppProcessEnabled}.







     *                               calling {@link #setQueryFromAppProcessEnabled}.











     *







     *











     * @see AccessibilityNodeInfo#getParent(int) for a description of prefetching.














     */







     */











    @Nullable







    @Nullable











    public AccessibilityNodeInfo getChild(int index, @PrefetchingStrategy int prefetchingStrategy) {







    public AccessibilityNodeInfo getChild(int index, @PrefetchingStrategy int prefetchingStrategy) {










@@ -1903,8 +1904,13 @@ public class AccessibilityNodeInfo implements Parcelable {









     * Accessibility service will throttle those content change events and only handle one event







     * Accessibility service will throttle those content change events and only handle one event











     * per minute for that view.







     * per minute for that view.











     * </p>







     * </p>














     * <p>














     * Example UI elements that frequently update and may benefit from a duration are progress bars,














     * timers, and stopwatches.














     * </p>











     *







     *











     * @see AccessibilityEvent#getContentChangeTypes for all content change types.







     * @see AccessibilityEvent#TYPE_WINDOW_CONTENT_CHANGED














     * @see AccessibilityEvent#getContentChangeTypes











     * @param duration the minimum duration between content change events.







     * @param duration the minimum duration between content change events.











     *                                         Negative duration would be treated as zero.







     *                                         Negative duration would be treated as zero.











     */







     */










@@ -3954,7 +3960,7 @@ public class AccessibilityNodeInfo implements Parcelable {









    /**







    /**











     * Returns the container title.







     * Returns the container title.











     *







     *











     * @see #setContainerTitle for details.







     * @see #setContainerTitle











     */







     */











    @Nullable







    @Nullable











    public CharSequence getContainerTitle() {







    public CharSequence getContainerTitle() {










@@ -5185,8 +5191,8 @@ public class AccessibilityNodeInfo implements Parcelable {









         * <p>The node that is focused should return {@code true} for







         * <p>The node that is focused should return {@code true} for











         * {@link AccessibilityNodeInfo#isFocused()}.







         * {@link AccessibilityNodeInfo#isFocused()}.











         *







         *











         * @see #ACTION_ACCESSIBILITY_FOCUS for the difference between system and accessibility







         * See {@link #ACTION_ACCESSIBILITY_FOCUS} for the difference between system and











         * focus.







         * accessibility focus.











         */







         */











        public static final AccessibilityAction ACTION_FOCUS =







        public static final AccessibilityAction ACTION_FOCUS =











                new AccessibilityAction(AccessibilityNodeInfo.ACTION_FOCUS);







                new AccessibilityAction(AccessibilityNodeInfo.ACTION_FOCUS);