Merge "Improve javadocs for a11y live regions and minimum durations" into main (22503b19) · Commits · e / os / android_frameworks_base

core/java/android/view/View.java

+59 −31

Original line number	Diff line number	Diff line
		@@ -226,6 +226,7 @@ import java.lang.reflect.Field;
		import java.lang.reflect.InvocationTargetException;
		import java.lang.reflect.Method;
		import java.lang.reflect.Modifier;
		import java.time.Duration;
		import java.util.ArrayList;
		import java.util.Arrays;
		import java.util.Calendar;
		@@ -3334,16 +3335,17 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
		public static final int ACCESSIBILITY_LIVE_REGION_NONE = 0x00000000;

		/**
		* Live region mode specifying that accessibility services should announce
		* changes to this view.
		* Live region mode specifying that accessibility services should notify users of changes to
		* this view.
		* <p>
		* Use with {@link #setAccessibilityLiveRegion(int)}.
		*/
		public static final int ACCESSIBILITY_LIVE_REGION_POLITE = 0x00000001;

		/**
		* Live region mode specifying that accessibility services should interrupt
		* ongoing speech to immediately announce changes to this view.
		* Live region mode specifying that accessibility services should immediately notify users of
		* changes to this view. For example, a screen reader may interrupt ongoing speech to
		* immediately announce these changes.
		* <p>
		* Use with {@link #setAccessibilityLiveRegion(int)}.
		*/
		@@ -8797,14 +8799,17 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
		*
		* <p>
		* When transitioning from one Activity to another, instead of using
		* setAccessibilityPaneTitle(), set a descriptive title for its window by using android:label
		* for the matching <activity> entry in your application’s manifest or updating the title at
		* {@code setAccessibilityPaneTitle()}, set a descriptive title for its window by using
		* {@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)}.
		*
		* <p>
		* <aside>
		* <b>Note:</b> Use
		* {@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
		* View is not a pane.
		*
		@@ -8912,7 +8917,7 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
		* They should not need to specify what exactly is announced to users.
		*
		* <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
		* significant UI changes like window changes, use
		* {@link android.app.Activity#setTitle(CharSequence)} and
		@@ -15305,33 +15310,56 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
		* to the view's content description or text, or to the content descriptions
		* or text of the view's children (where applicable).
		* <p>
		* To indicate that the user should be notified of changes, use
		* {@link #ACCESSIBILITY_LIVE_REGION_POLITE}. Announcements from this region are queued and
		* do not disrupt ongoing speech.
		* Different priority levels are available:
		* <ul>
		* <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>
		* 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
		* {@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>
		* For notifying users about errors, such as in a login screen with text that displays an
		* "incorrect password" notification, that view should send an AccessibilityEvent of type
		* For error notifications, like an "incorrect password" warning in a login screen, views
		* 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 AccessibilityNodeInfo#setError(CharSequence)} instead. Custom widgets should expose
		* error-setting methods that support accessibility automatically. For example, instead of
		* explicitly sending this event when using a TextView, use
		* {@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.
		* {@link AccessibilityNodeInfo#setError(CharSequence)}. Custom widgets should provide
		* error-setting methods that support accessibility. For example, use
		* {@link android.widget.TextView#setError(CharSequence)} instead of explicitly sending events.
		* <p>
		* If the view's changes should interrupt ongoing speech and notify the user
		* immediately, use {@link #ACCESSIBILITY_LIVE_REGION_ASSERTIVE}. This may result in disruptive
		* announcements from an accessibility service, so it should generally be used only to convey
		* information that is time-sensitive or critical for use of the application. Examples may
		* include an incoming call or an emergency alert.
		* Don't use live regions for frequently-updating UI elements (e.g., progress bars), as this can
		* overwhelm the user with feedback from accessibility services. If necessary, use
		* {@link AccessibilityNodeInfo#setMinDurationBetweenContentChanges(Duration)} to throttle
		* feedback and reduce disruptions.
		* <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>
		*
		* @param mode The live region mode for this view, one of:

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

+16 −10

Original line number	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
		* 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;

		@@ -171,7 +171,7 @@ public class AccessibilityNodeInfo implements Parcelable {
		* {@link #FLAG_PREFETCH_DESCENDANTS_BREADTH_FIRST} or this will trigger an
		* 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;

		@@ -181,7 +181,7 @@ public class AccessibilityNodeInfo implements Parcelable {
		* {@link #FLAG_PREFETCH_DESCENDANTS_BREADTH_FIRST} or this will trigger an
		* 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;

		@@ -191,7 +191,7 @@ public class AccessibilityNodeInfo implements Parcelable {
		* {@link #FLAG_PREFETCH_DESCENDANTS_DEPTH_FIRST} or this will trigger an
		* 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;

		@@ -199,7 +199,7 @@ public class AccessibilityNodeInfo implements Parcelable {
		* Prefetching flag that specifies prefetching should not be interrupted by a request to
		* 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;

		@@ -1295,6 +1295,8 @@ public class AccessibilityNodeInfo implements Parcelable {
		/**
		* Get the child at given index.
		*
		* <p>
		* See {@link #getParent(int)} for a description of prefetching.
		* @param index The child index.
		* @param prefetchingStrategy the prefetching strategy.
		* @return The child node.
		@@ -1302,7 +1304,6 @@ public class AccessibilityNodeInfo implements Parcelable {
		* @throws IllegalStateException If called outside of an {@link AccessibilityService} and before
		* calling {@link #setQueryFromAppProcessEnabled}.
		*
		* @see AccessibilityNodeInfo#getParent(int) for a description of prefetching.
		*/
		@Nullable
		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
		* per minute for that view.
		* </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.
		* Negative duration would be treated as zero.
		*/
		@@ -3954,7 +3960,7 @@ public class AccessibilityNodeInfo implements Parcelable {
		/**
		* Returns the container title.
		*
		* @see #setContainerTitle for details.
		* @see #setContainerTitle
		*/
		@Nullable
		public CharSequence getContainerTitle() {
		@@ -5187,8 +5193,8 @@ public class AccessibilityNodeInfo implements Parcelable {
		* <p>The node that is focused should return {@code true} for
		* {@link AccessibilityNodeInfo#isFocused()}.
		*
		* @see #ACTION_ACCESSIBILITY_FOCUS for the difference between system and accessibility
		* focus.
		* See {@link #ACTION_ACCESSIBILITY_FOCUS} for the difference between system and
		* accessibility focus.
		*/
		public static final AccessibilityAction ACTION_FOCUS =
		new AccessibilityAction(AccessibilityNodeInfo.ACTION_FOCUS);