From f70342502f58b1d2ad556c71a426a2c2d203dc1f Mon Sep 17 00:00:00 2001 From: Sally Date: Tue, 2 May 2023 17:56:01 +0000 Subject: [PATCH] Make a11y traversal documenation clearer - Add clearer phrasing and give an example that explicitly uses the method - Soften the language, since it's the screen reader that ultimately decides traversal order. - Add a note that recommends not using this API - Add a suggesting to avoid loops - Add a bit about importantce in the attr documentation Bug: 280091061 Test: n/a (documentation change) Change-Id: I792f72354664cb0b04696d716118f96980721d23 --- core/java/android/view/View.java | 72 ++++++++++++++++++++------------ core/res/res/values/attrs.xml | 12 +++--- 2 files changed, 51 insertions(+), 33 deletions(-) diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java index 003307db832a5..9b442f6b01192 100644 --- a/core/java/android/view/View.java +++ b/core/java/android/view/View.java @@ -11230,26 +11230,36 @@ public class View implements Drawable.Callback, KeyEvent.Callback, } /** - * Sets the id of a view before which this one is visited in accessibility traversal. - * A screen-reader must visit the content of this view before the content of the one - * it precedes. For example, if view B is set to be before view A, then a screen-reader - * will traverse the entire content of B before traversing the entire content of A, - * regardles of what traversal strategy it is using. + * Sets the id of a view that screen readers are requested to visit after this view. + * *

- * Views that do not have specified before/after relationships are traversed in order - * determined by the screen-reader. - *

+ * + * For example, if view B should be visited before view A, with + * B.setAccessibilityTraversalBefore(A), this requests that screen readers visit and traverse + * view B before visiting view A. + * *

- * Setting that this view is before a view that is not important for accessibility - * or if this view is not important for accessibility will have no effect as the - * screen-reader is not aware of unimportant views. - *

+ * Note: Views are visited in the order determined by the screen reader. Avoid + * explicitly manipulating focus order, as this may result in inconsistent user + * experiences between apps. Instead, use other semantics, such as restructuring the view + * hierarchy layout, to communicate order. + * + *

+ * Setting this view to be after a view that is not important for accessibility, + * or if this view is not important for accessibility, means this method will have no effect if + * the service is not aware of unimportant views. + * + *

+ * To avoid a risk of loops, set clear relationships between views. For example, if focus order + * should be B -> A, and B.setAccessibilityTraversalBefore(A), then also call + * A.setAccessibilityTraversalAfter(B). * * @param beforeId The id of a view this one precedes in accessibility traversal. * * @attr ref android.R.styleable#View_accessibilityTraversalBefore * * @see #setImportantForAccessibility(int) + * @see #setAccessibilityTraversalAfter(int) */ @RemotableViewMethod public void setAccessibilityTraversalBefore(@IdRes int beforeId) { @@ -11276,26 +11286,34 @@ public class View implements Drawable.Callback, KeyEvent.Callback, } /** - * Sets the id of a view after which this one is visited in accessibility traversal. - * A screen-reader must visit the content of the other view before the content of this - * one. For example, if view B is set to be after view A, then a screen-reader - * will traverse the entire content of A before traversing the entire content of B, - * regardles of what traversal strategy it is using. - *

- * Views that do not have specified before/after relationships are traversed in order - * determined by the screen-reader. - *

- *

- * Setting that this view is after a view that is not important for accessibility - * or if this view is not important for accessibility will have no effect as the - * screen-reader is not aware of unimportant views. - *

+ * Sets the id of a view that screen readers are requested to visit before this view. * - * @param afterId The id of a view this one succedees in accessibility traversal. + *

+ * For example, if view B should be visited after A, with B.setAccessibilityTraversalAfter(A), + * then this requests that screen readers visit and traverse view A before visiting view B. + * + *

+ * Note: Views are visited in the order determined by the screen reader. Avoid + * explicitly manipulating focus order, as this may result in inconsistent user + * experiences between apps. Instead, use other semantics, such as restructuring the view + * hierarchy layout, to communicate order. + * + *

+ * Setting this view to be after a view that is not important for accessibility, + * or if this view is not important for accessibility, means this method will have no effect if + * the service is not aware of unimportant views. + * + *

+ * To avoid a risk of loops, set clear relationships between views. For example, if focus order + * should be B -> A, and B.setAccessibilityTraversalBefore(A), then also call + * A.setAccessibilityTraversalAfter(B). + * + * @param afterId The id of a view this one succeeds in accessibility traversal. * * @attr ref android.R.styleable#View_accessibilityTraversalAfter * * @see #setImportantForAccessibility(int) + * @see #setAccessibilityTraversalBefore(int) */ @RemotableViewMethod public void setAccessibilityTraversalAfter(@IdRes int afterId) { diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml index 599d72aa332a9..e813e775ed024 100644 --- a/core/res/res/values/attrs.xml +++ b/core/res/res/values/attrs.xml @@ -3022,15 +3022,15 @@ representation this attribute can be used for providing such. --> - -