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

Commit f7034250 authored by Sally's avatar Sally Committed by Sally Yuen
Browse files

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
parent 5ac54421

core/java/android/view/View.java

+43 −25
Original line number Diff line number Diff line
@@ -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.













     *















     * <p>













     * Views that do not have specified before/after relationships are traversed in order













     * determined by the screen-reader.













     * </p>













     *













     * 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.













     *















     * <p>













     * 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.













     * </p>













     * <b>Note:</b> 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.













     *













     * <p>













     * 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.













     *













     * <p>













     * 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.













     * Sets the id of a view that screen readers are requested to visit before this view.













     *















     * <p>













     * Views that do not have specified before/after relationships are traversed in order













     * determined by the screen-reader.













     * </p>













     * 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.













     *















     * <p>













     * 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.













     * </p>













     * <b>Note:</b> 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.















     *













     * @param afterId The id of a view this one succedees in accessibility traversal.













     * <p>













     * 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.













     *













     * <p>













     * 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) {

























core/res/res/values/attrs.xml



+6
−6




























Original line number
Diff line number
Diff line








@@ -3022,15 +3022,15 @@













             representation this attribute can be used for providing such. -->















        <attr name="contentDescription" format="string" localization="suggested" />



























        <!-- 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.













        <!-- Sets the id of a view that screen readers are requested to visit after this view.













             Requests that a screen-reader visits the content of this view before the content of the













             one it precedes. This does nothing if either view is not important for accessibility.















             {@see android.view.View#setAccessibilityTraversalBefore(int)} -->















        <attr name="accessibilityTraversalBefore" format="integer" />



























        <!-- 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.













        <!-- Sets the id of a view that screen readers are requested to visit before this view.













             Requests that a screen-reader visits the content of the other view before the content













             of this one. This does nothing if either view is not important for accessibility.















             {@see android.view.View#setAccessibilityTraversalAfter(int)} -->















        <attr name="accessibilityTraversalAfter" format="integer" />