Allowing association between a view and its label for accessibility.
1. For accessibility purposes it is important to be able to associate
a view with content with a view that labels it. For example, if
an accessibility service knows that a TextView is associated with
an EditText, it can provide much richer feedback.
This change adds APIs for setting a view to be the label for another
one and setting the label for a view, i.e. the reverse association.
bug:5016937
Change-Id: I7b837265c5ed9302e3ce352396dc6e88413038b5
diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index 8f77663..03f9b72 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -2759,6 +2759,23 @@
private CharSequence mContentDescription;
/**
+ * Specifies the id of a view for which this view serves as a label for
+ * accessibility purposes.
+ */
+ private int mLabelForId = View.NO_ID;
+
+ /**
+ * Predicate for matching labeled view id with its label for
+ * accessibility purposes.
+ */
+ private MatchLabelForPredicate mMatchLabelForPredicate;
+
+ /**
+ * Predicate for matching a view by its id.
+ */
+ private MatchIdPredicate mMatchIdPredicate;
+
+ /**
* Cache the paddingRight set by the user to append to the scrollbar's size.
*
* @hide
@@ -3370,6 +3387,9 @@
case com.android.internal.R.styleable.View_contentDescription:
setContentDescription(a.getString(attr));
break;
+ case com.android.internal.R.styleable.View_labelFor:
+ setLabelFor(a.getResourceId(attr, NO_ID));
+ break;
case com.android.internal.R.styleable.View_soundEffectsEnabled:
if (!a.getBoolean(attr, true)) {
viewFlagValues &= ~SOUND_EFFECTS_ENABLED;
@@ -4837,6 +4857,28 @@
info.setParent((View) parent);
}
+ if (mID != View.NO_ID) {
+ View rootView = getRootView();
+ if (rootView == null) {
+ rootView = this;
+ }
+ View label = rootView.findLabelForView(this, mID);
+ if (label != null) {
+ info.setLabeledBy(label);
+ }
+ }
+
+ if (mLabelForId != View.NO_ID) {
+ View rootView = getRootView();
+ if (rootView == null) {
+ rootView = this;
+ }
+ View labeled = rootView.findViewInsideOutShouldExist(this, mLabelForId);
+ if (labeled != null) {
+ info.setLabelFor(labeled);
+ }
+ }
+
info.setVisibleToUser(isVisibleToUser());
info.setPackageName(mContext.getPackageName());
@@ -4888,6 +4930,14 @@
}
}
+ private View findLabelForView(View view, int labeledId) {
+ if (mMatchLabelForPredicate == null) {
+ mMatchLabelForPredicate = new MatchLabelForPredicate();
+ }
+ mMatchLabelForPredicate.mLabeledId = labeledId;
+ return findViewByPredicateInsideOut(view, mMatchLabelForPredicate);
+ }
+
/**
* Computes whether this view is visible to the user. Such a view is
* attached, visible, all its predecessors are visible, it is not clipped
@@ -5059,6 +5109,32 @@
}
/**
+ * Gets the id of a view for which this view serves as a label for
+ * accessibility purposes.
+ *
+ * @return The labeled view id.
+ */
+ @ViewDebug.ExportedProperty(category = "accessibility")
+ public int getLabelFor() {
+ return mLabelForId;
+ }
+
+ /**
+ * Sets the id of a view for which this view serves as a label for
+ * accessibility purposes.
+ *
+ * @param id The labeled view id.
+ */
+ @RemotableViewMethod
+ public void setLabelFor(int id) {
+ mLabelForId = id;
+ if (mLabelForId != View.NO_ID
+ && mID == View.NO_ID) {
+ mID = generateViewId();
+ }
+ }
+
+ /**
* Invoked whenever this view loses focus, either by losing window focus or by losing
* focus within its window. This method can be used to clear any state tied to the
* focus. For instance, if a button is held pressed with the trackball and the window
@@ -6110,17 +6186,14 @@
return null;
}
- private View findViewInsideOutShouldExist(View root, final int childViewId) {
- View result = root.findViewByPredicateInsideOut(this, new Predicate<View>() {
- @Override
- public boolean apply(View t) {
- return t.mID == childViewId;
- }
- });
-
+ private View findViewInsideOutShouldExist(View root, int id) {
+ if (mMatchIdPredicate == null) {
+ mMatchIdPredicate = new MatchIdPredicate();
+ }
+ mMatchIdPredicate.mId = id;
+ View result = root.findViewByPredicateInsideOut(this, mMatchIdPredicate);
if (result == null) {
- Log.w(VIEW_LOG_TAG, "couldn't find next focus view specified "
- + "by user for id " + childViewId);
+ Log.w(VIEW_LOG_TAG, "couldn't find view with id " + id);
}
return result;
}
@@ -14922,6 +14995,9 @@
*/
public void setId(int id) {
mID = id;
+ if (mID == View.NO_ID && mLabelForId != View.NO_ID) {
+ mID = generateViewId();
+ }
}
/**
@@ -18008,4 +18084,22 @@
return null;
}
}
+
+ private class MatchIdPredicate implements Predicate<View> {
+ public int mId;
+
+ @Override
+ public boolean apply(View view) {
+ return (view.mID == mId);
+ }
+ }
+
+ private class MatchLabelForPredicate implements Predicate<View> {
+ private int mLabeledId;
+
+ @Override
+ public boolean apply(View view) {
+ return (view.mLabelForId == mLabeledId);
+ }
+ }
}
diff --git a/core/java/android/view/accessibility/AccessibilityNodeInfo.java b/core/java/android/view/accessibility/AccessibilityNodeInfo.java
index 768744b..1dc2487 100644
--- a/core/java/android/view/accessibility/AccessibilityNodeInfo.java
+++ b/core/java/android/view/accessibility/AccessibilityNodeInfo.java
@@ -365,6 +365,8 @@
private int mWindowId = UNDEFINED;
private long mSourceNodeId = ROOT_NODE_ID;
private long mParentNodeId = ROOT_NODE_ID;
+ private long mLabelForId = ROOT_NODE_ID;
+ private long mLabeledById = ROOT_NODE_ID;
private int mBooleanProperties;
private final Rect mBoundsInParent = new Rect();
@@ -1233,6 +1235,120 @@
}
/**
+ * Sets the view for which the view represented by this info serves as a
+ * label for accessibility purposes.
+ *
+ * @param labeled The view for which this info serves as a label.
+ */
+ public void setLabelFor(View labeled) {
+ setLabelFor(labeled, UNDEFINED);
+ }
+
+ /**
+ * Sets the view for which the view represented by this info serves as a
+ * label for accessibility purposes. If <code>virtualDescendantId</code>
+ * is {@link View#NO_ID} the root is set as the labeled.
+ * <p>
+ * A virtual descendant is an imaginary View that is reported as a part of the view
+ * hierarchy for accessibility purposes. This enables custom views that draw complex
+ * content to report themselves as a tree of virtual views, thus conveying their
+ * logical structure.
+ * </p>
+ * <p>
+ * <strong>Note:</strong> Cannot be called from an
+ * {@link android.accessibilityservice.AccessibilityService}.
+ * This class is made immutable before being delivered to an AccessibilityService.
+ * </p>
+ *
+ * @param root The root whose virtual descendant serves as a label.
+ * @param virtualDescendantId The id of the virtual descendant.
+ */
+ public void setLabelFor(View root, int virtualDescendantId) {
+ enforceNotSealed();
+ final int rootAccessibilityViewId = (root != null)
+ ? root.getAccessibilityViewId() : UNDEFINED;
+ mLabelForId = makeNodeId(rootAccessibilityViewId, virtualDescendantId);
+ }
+
+ /**
+ * Gets the node info for which the view represented by this info serves as
+ * a label for accessibility purposes.
+ * <p>
+ * <strong>Note:</strong> It is a client responsibility to recycle the
+ * received info by calling {@link AccessibilityNodeInfo#recycle()}
+ * to avoid creating of multiple instances.
+ * </p>
+ *
+ * @return The labeled info.
+ */
+ public AccessibilityNodeInfo getLabelFor() {
+ enforceSealed();
+ if (!canPerformRequestOverConnection(mLabelForId)) {
+ return null;
+ }
+ AccessibilityInteractionClient client = AccessibilityInteractionClient.getInstance();
+ return client.findAccessibilityNodeInfoByAccessibilityId(mConnectionId,
+ mWindowId, mLabelForId, FLAG_PREFETCH_DESCENDANTS | FLAG_PREFETCH_SIBLINGS);
+ }
+
+ /**
+ * Sets the view which serves as the label of the view represented by
+ * this info for accessibility purposes.
+ *
+ * @param label The view that labels this node's source.
+ */
+ public void setLabeledBy(View label) {
+ setLabeledBy(label, UNDEFINED);
+ }
+
+ /**
+ * Sets the view which serves as the label of the view represented by
+ * this info for accessibility purposes. If <code>virtualDescendantId</code>
+ * is {@link View#NO_ID} the root is set as the label.
+ * <p>
+ * A virtual descendant is an imaginary View that is reported as a part of the view
+ * hierarchy for accessibility purposes. This enables custom views that draw complex
+ * content to report themselves as a tree of virtual views, thus conveying their
+ * logical structure.
+ * </p>
+ * <p>
+ * <strong>Note:</strong> Cannot be called from an
+ * {@link android.accessibilityservice.AccessibilityService}.
+ * This class is made immutable before being delivered to an AccessibilityService.
+ * </p>
+ *
+ * @param root The root whose virtual descendant labels this node's source.
+ * @param virtualDescendantId The id of the virtual descendant.
+ */
+ public void setLabeledBy(View root, int virtualDescendantId) {
+ enforceNotSealed();
+ final int rootAccessibilityViewId = (root != null)
+ ? root.getAccessibilityViewId() : UNDEFINED;
+ mLabeledById = makeNodeId(rootAccessibilityViewId, virtualDescendantId);
+ }
+
+ /**
+ * Gets the node info which serves as the label of the view represented by
+ * this info for accessibility purposes.
+ * <p>
+ * <strong>Note:</strong> It is a client responsibility to recycle the
+ * received info by calling {@link AccessibilityNodeInfo#recycle()}
+ * to avoid creating of multiple instances.
+ * </p>
+ *
+ * @return The label.
+ */
+ public AccessibilityNodeInfo getLabeledBy() {
+ enforceSealed();
+ if (!canPerformRequestOverConnection(mLabeledById)) {
+ return null;
+ }
+ AccessibilityInteractionClient client = AccessibilityInteractionClient.getInstance();
+ return client.findAccessibilityNodeInfoByAccessibilityId(mConnectionId,
+ mWindowId, mLabeledById, FLAG_PREFETCH_DESCENDANTS | FLAG_PREFETCH_SIBLINGS);
+ }
+
+ /**
* Gets the value of a boolean property.
*
* @param property The property.
@@ -1462,6 +1578,8 @@
parcel.writeLong(mSourceNodeId);
parcel.writeInt(mWindowId);
parcel.writeLong(mParentNodeId);
+ parcel.writeLong(mLabelForId);
+ parcel.writeLong(mLabeledById);
parcel.writeInt(mConnectionId);
SparseLongArray childIds = mChildNodeIds;
@@ -1507,6 +1625,8 @@
mSealed = other.mSealed;
mSourceNodeId = other.mSourceNodeId;
mParentNodeId = other.mParentNodeId;
+ mLabelForId = other.mLabelForId;
+ mLabeledById = other.mLabeledById;
mWindowId = other.mWindowId;
mConnectionId = other.mConnectionId;
mBoundsInParent.set(other.mBoundsInParent);
@@ -1534,6 +1654,8 @@
mSourceNodeId = parcel.readLong();
mWindowId = parcel.readInt();
mParentNodeId = parcel.readLong();
+ mLabelForId = parcel.readLong();
+ mLabeledById = parcel.readLong();
mConnectionId = parcel.readInt();
SparseLongArray childIds = mChildNodeIds;
@@ -1572,6 +1694,8 @@
mSealed = false;
mSourceNodeId = ROOT_NODE_ID;
mParentNodeId = ROOT_NODE_ID;
+ mLabelForId = ROOT_NODE_ID;
+ mLabeledById = ROOT_NODE_ID;
mWindowId = UNDEFINED;
mConnectionId = UNDEFINED;
mMovementGranularities = 0;
diff --git a/core/java/android/widget/RemoteViews.java b/core/java/android/widget/RemoteViews.java
index dcf90e9..c65a67b 100644
--- a/core/java/android/widget/RemoteViews.java
+++ b/core/java/android/widget/RemoteViews.java
@@ -2077,15 +2077,25 @@
}
/**
- * Equivalent to calling View.setContentDescription
+ * Equivalent to calling View.setContentDescription(CharSequence).
*
- * @param viewId The id of the view whose content description should change
- * @param contentDescription The new content description for the view
+ * @param viewId The id of the view whose content description should change.
+ * @param contentDescription The new content description for the view.
*/
public void setContentDescription(int viewId, CharSequence contentDescription) {
setCharSequence(viewId, "setContentDescription", contentDescription);
}
+ /**
+ * Equivalent to calling View.setLabelFor(int).
+ *
+ * @param viewId The id of the view whose property to set.
+ * @param labeledId The id of a view for which this view serves as a label.
+ */
+ public void setLabelFor(int viewId, int labeledId) {
+ setInt(viewId, "setLabelFor", labeledId);
+ }
+
private RemoteViews getRemoteViewsToApply(Context context) {
if (hasLandscapeAndPortraitLayouts()) {
int orientation = context.getResources().getConfiguration().orientation;
diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml
index 3dacc61..0755038 100755
--- a/core/res/res/values/attrs.xml
+++ b/core/res/res/values/attrs.xml
@@ -2163,6 +2163,12 @@
<enum name="no" value="2" />
</attr>
+ <!-- Specifies the id of a view for which this view serves as a label for
+ accessibility purposes. For example, a TextView before an EditText in
+ the UI usually specifies what infomation is contained in the EditText.
+ Hence, the TextView is a label for the EditText. -->
+ <attr name="labelFor" format="integer" />
+
</declare-styleable>
<!-- Attributes that can be used with a {@link android.view.ViewGroup} or any
diff --git a/core/res/res/values/public.xml b/core/res/res/values/public.xml
index 60b7dba..7dc19bf 100644
--- a/core/res/res/values/public.xml
+++ b/core/res/res/values/public.xml
@@ -2016,5 +2016,6 @@
<public type="attr" name="widgetFeatures" />
<public type="attr" name="widgetCategory" />
<public type="attr" name="permissionGroupFlags" />
+ <public type="attr" name="labelFor" />
</resources>