Merge "Overall improvement on Autofill javadocs for autofillable APIs." into oc-dev
diff --git a/core/java/android/app/assist/AssistStructure.java b/core/java/android/app/assist/AssistStructure.java
index c99a1e4..266fa7e 100644
--- a/core/java/android/app/assist/AssistStructure.java
+++ b/core/java/android/app/assist/AssistStructure.java
@@ -18,7 +18,6 @@
import android.os.PooledStringWriter;
import android.os.RemoteException;
import android.os.SystemClock;
-import android.service.autofill.FillContext;
import android.service.autofill.FillRequest;
import android.text.TextUtils;
import android.util.Log;
@@ -31,7 +30,6 @@
import android.view.WindowManager;
import android.view.WindowManagerGlobal;
import android.view.autofill.AutofillId;
-import android.view.autofill.AutofillManager;
import android.view.autofill.AutofillValue;
import java.util.ArrayList;
@@ -39,18 +37,18 @@
import java.util.List;
/**
- * Assist data automatically created by the platform's implementation of Assist and Autofill.
+ * Assist data automatically created by the platform's implementation of assist and autofill.
*
- * <p>The structure is used for Assist purposes when created by
+ * <p>The structure is used for assist purposes when created by
* {@link android.app.Activity#onProvideAssistData}, {@link View#onProvideStructure(ViewStructure)},
* or {@link View#onProvideVirtualStructure(ViewStructure)}.
*
- * <p>The structure is used for Autofill purposes when created by
+ * <p>The structure is used for autofill purposes when created by
* {@link View#onProvideAutofillStructure(ViewStructure, int)},
* or {@link View#onProvideAutofillVirtualStructure(ViewStructure, int)}.
*
- * <p>For performance reasons, some properties of the Assist data might be available just for Assist
- * or Autofill purposes; in those case, the property availability will be document in its javadoc.
+ * <p>For performance reasons, some properties of the assist data might be available just for assist
+ * or autofill purposes; in those case, the property availability will be document in its javadoc.
*/
public class AssistStructure implements Parcelable {
static final String TAG = "AssistStructure";
@@ -958,10 +956,10 @@
/**
* Gets the id that can be used to autofill the view contents.
*
- * <p>It's relevant set when the {@link AssistStructure} is used for Autofill purposes.
+ * <p>It's only relevant when the {@link AssistStructure} is used for autofill purposes.
*
* @return id that can be used to autofill the view contents, or {@code null} if the
- * structure was created for Assist purposes.
+ * structure was created for assist purposes.
*/
@Nullable public AutofillId getAutofillId() {
return mAutofillId;
@@ -970,10 +968,10 @@
/**
* Gets the the type of value that can be used to autofill the view contents.
*
- * <p>It's only relevant when the {@link AssistStructure} is used for Autofill purposes.
+ * <p>It's only relevant when the {@link AssistStructure} is used for autofill purposes.
*
* @return autofill type as defined by {@link View#getAutofillType()},
- * or {@link View#AUTOFILL_TYPE_NONE} if the structure was created for Assist purposes.
+ * or {@link View#AUTOFILL_TYPE_NONE} if the structure was created for assist purposes.
*/
public @View.AutofillType int getAutofillType() {
return mAutofillType;
@@ -983,11 +981,11 @@
* Describes the content of a view so that a autofill service can fill in the appropriate
* data.
*
- * <p>It's only relevant when the {@link AssistStructure} is used for Autofill purposes,
+ * <p>It's only relevant when the {@link AssistStructure} is used for autofill purposes,
* not for Assist - see {@link View#getAutofillHints()} for more info.
*
* @return The autofill hints for this view, or {@code null} if the structure was created
- * for Assist purposes.
+ * for assist purposes.
*/
@Nullable public String[] getAutofillHints() {
return mAutofillHints;
@@ -996,11 +994,11 @@
/**
* Gets the the value of this view.
*
- * <p>It's only relevant when the {@link AssistStructure} is used for Autofill purposes,
- * not for Assist purposes.
+ * <p>It's only relevant when the {@link AssistStructure} is used for autofill purposes,
+ * not for assist purposes.
*
* @return the autofill value of this view, or {@code null} if the structure was created
- * for Assist purposes.
+ * for assist purposes.
*/
@Nullable public AutofillValue getAutofillValue() {
return mAutofillValue;
@@ -1017,11 +1015,11 @@
* <p>Typically used by nodes whose {@link View#getAutofillType()} is a list to indicate
* the meaning of each possible value in the list.
*
- * <p>It's relevant when the {@link AssistStructure} is used for Autofill purposes, not
- * for Assist purposes.
+ * <p>It's relevant when the {@link AssistStructure} is used for autofill purposes, not
+ * for assist purposes.
*
* @return the options that can be used to autofill this view, or {@code null} if the
- * structure was created for Assist purposes.
+ * structure was created for assist purposes.
*/
@Nullable public CharSequence[] getAutofillOptions() {
return mAutofillOptions;
@@ -1106,8 +1104,8 @@
* or scaling. The returned Matrix object is owned by ViewNode; do not modify it.
* Returns null if there is no transformation applied to the view.
*
- * <p>It's only relevant when the {@link AssistStructure} is used for Assist purposes,
- * not for Autofill purposes.
+ * <p>It's only relevant when the {@link AssistStructure} is used for assist purposes,
+ * not for autofill purposes.
*/
public Matrix getTransformation() {
return mMatrix;
@@ -1118,8 +1116,8 @@
* characterstics, as set by {@link ViewStructure#setElevation
* ViewStructure.setElevation(float)}.
*
- * <p>It's only relevant when the {@link AssistStructure} is used for Assist purposes,
- * not for Autofill purposes.
+ * <p>It's only relevant when the {@link AssistStructure} is used for assist purposes,
+ * not for autofill purposes.
*/
public float getElevation() {
return mElevation;
@@ -1130,8 +1128,8 @@
* of the view's contents, as set by {@link ViewStructure#setAlpha
* ViewStructure.setAlpha(float)}.
*
- * <p>It's only relevant when the {@link AssistStructure} is used for Assist purposes,
- * not for Autofill purposes.
+ * <p>It's only relevant when the {@link AssistStructure} is used for assist purposes,
+ * not for autofill purposes.
*/
public float getAlpha() {
return mAlpha;
@@ -1260,7 +1258,7 @@
* document.
*
* <strong>WARNING:</strong> a {@link android.service.autofill.AutofillService} should only
- * use this domain for Autofill purposes when it trusts the app generating it (i.e., the app
+ * use this domain for autofill purposes when it trusts the app generating it (i.e., the app
* defined by {@link AssistStructure#getActivityComponent()}).
*
* @return domain-only part of the document. For example, if the full URL is
@@ -1273,11 +1271,11 @@
/**
* Returns the HTML properties associated with this view.
*
- * <p>It's only relevant when the {@link AssistStructure} is used for Autofill purposes,
- * not for Assist purposes.
+ * <p>It's only relevant when the {@link AssistStructure} is used for autofill purposes,
+ * not for assist purposes.
*
* @return the HTML properties associated with this view, or {@code null} if the
- * structure was created for Assist purposes.
+ * structure was created for assist purposes.
*/
@Nullable public HtmlInfo getHtmlInfo() {
return mHtmlInfo;
@@ -1301,8 +1299,8 @@
/**
* If {@link #getText()} is non-null, this is where the current selection starts.
*
- * <p>It's only relevant when the {@link AssistStructure} is used for Assist purposes,
- * not for Autofill purposes.
+ * <p>It's only relevant when the {@link AssistStructure} is used for assist purposes,
+ * not for autofill purposes.
*/
public int getTextSelectionStart() {
return mText != null ? mText.mTextSelectionStart : -1;
@@ -1313,8 +1311,8 @@
* If there is no selection, returns the same value as {@link #getTextSelectionStart()},
* indicating the cursor position.
*
- * <p>It's only relevant when the {@link AssistStructure} is used for Assist purposes,
- * not for Autofill purposes.
+ * <p>It's only relevant when the {@link AssistStructure} is used for assist purposes,
+ * not for autofill purposes.
*/
public int getTextSelectionEnd() {
return mText != null ? mText.mTextSelectionEnd : -1;
@@ -1337,8 +1335,8 @@
* Note that the text may also contain style spans that modify the color of specific
* parts of the text.
*
- * <p>It's only relevant when the {@link AssistStructure} is used for Assist purposes,
- * not for Autofill purposes.
+ * <p>It's only relevant when the {@link AssistStructure} is used for assist purposes,
+ * not for autofill purposes.
*/
public int getTextBackgroundColor() {
return mText != null ? mText.mTextBackgroundColor : TEXT_COLOR_UNDEFINED;
@@ -1350,8 +1348,8 @@
* Note that the text may also contain style spans that modify the size of specific
* parts of the text.
*
- * <p>It's only relevant when the {@link AssistStructure} is used for Assist purposes,
- * not for Autofill purposes.
+ * <p>It's only relevant when the {@link AssistStructure} is used for assist purposes,
+ * not for autofill purposes.
*/
public float getTextSize() {
return mText != null ? mText.mTextSize : 0;
@@ -1365,8 +1363,8 @@
* Note that the text may also contain style spans that modify the style of specific
* parts of the text.
*
- * <p>It's only relevant when the {@link AssistStructure} is used for Assist purposes,
- * not for Autofill purposes.
+ * <p>It's only relevant when the {@link AssistStructure} is used for assist purposes,
+ * not for autofill purposes.
*/
public int getTextStyle() {
return mText != null ? mText.mTextStyle : 0;
@@ -1378,8 +1376,8 @@
* into the text string where that line starts. May return null if there is no line
* information.
*
- * <p>It's only relevant when the {@link AssistStructure} is used for Assist purposes,
- * not for Autofill purposes.
+ * <p>It's only relevant when the {@link AssistStructure} is used for assist purposes,
+ * not for autofill purposes.
*/
public int[] getTextLineCharOffsets() {
return mText != null ? mText.mLineCharOffsets : null;
@@ -1391,8 +1389,8 @@
* where that text appears in the view. May return null if there is no line
* information.
*
- * <p>It's only relevant when the {@link AssistStructure} is used for Assist purposes,
- * not for Autofill purposes.
+ * <p>It's only relevant when the {@link AssistStructure} is used for assist purposes,
+ * not for autofill purposes.
*/
public int[] getTextLineBaselines() {
return mText != null ? mText.mLineBaselines : null;
diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index 19ae253..a9c85f0 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -1139,6 +1139,10 @@
/**
* Autofill type for views that cannot be autofilled.
+ *
+ * <p>Typically used when the view is read-only; for example, a text label.
+ *
+ * @see #getAutofillType()
*/
public static final int AUTOFILL_TYPE_NONE = 0;
@@ -1148,6 +1152,8 @@
* <p>{@link AutofillValue} instances for autofilling a {@link View} can be obtained through
* {@link AutofillValue#forText(CharSequence)}, and the value passed to autofill a
* {@link View} can be fetched through {@link AutofillValue#getTextValue()}.
+ *
+ * @see #getAutofillType()
*/
public static final int AUTOFILL_TYPE_TEXT = 1;
@@ -1157,6 +1163,8 @@
* <p>{@link AutofillValue} instances for autofilling a {@link View} can be obtained through
* {@link AutofillValue#forToggle(boolean)}, and the value passed to autofill a
* {@link View} can be fetched through {@link AutofillValue#getToggleValue()}.
+ *
+ * @see #getAutofillType()
*/
public static final int AUTOFILL_TYPE_TOGGLE = 2;
@@ -1170,6 +1178,8 @@
*
* <p>The available options in the selection list are typically provided by
* {@link android.app.assist.AssistStructure.ViewNode#getAutofillOptions()}.
+ *
+ * @see #getAutofillType()
*/
public static final int AUTOFILL_TYPE_LIST = 3;
@@ -1182,6 +1192,8 @@
* <p>{@link AutofillValue} instances for autofilling a {@link View} can be obtained through
* {@link AutofillValue#forDate(long)}, and the values passed to
* autofill a {@link View} can be fetched through {@link AutofillValue#getDateValue()}.
+ *
+ * @see #getAutofillType()
*/
public static final int AUTOFILL_TYPE_DATE = 4;
@@ -1198,26 +1210,41 @@
/**
* Automatically determine whether a view is important for autofill.
+ *
+ * @see #isImportantForAutofill()
+ * @see #setImportantForAutofill(int)
*/
public static final int IMPORTANT_FOR_AUTOFILL_AUTO = 0x0;
/**
* The view is important for autofill, and its children (if any) will be traversed.
+ *
+ * @see #isImportantForAutofill()
+ * @see #setImportantForAutofill(int)
*/
public static final int IMPORTANT_FOR_AUTOFILL_YES = 0x1;
/**
* The view is not important for autofill, but its children (if any) will be traversed.
+ *
+ * @see #isImportantForAutofill()
+ * @see #setImportantForAutofill(int)
*/
public static final int IMPORTANT_FOR_AUTOFILL_NO = 0x2;
/**
* The view is important for autofill, but its children (if any) will not be traversed.
+ *
+ * @see #isImportantForAutofill()
+ * @see #setImportantForAutofill(int)
*/
public static final int IMPORTANT_FOR_AUTOFILL_YES_EXCLUDE_DESCENDANTS = 0x4;
/**
* The view is not important for autofill, and its children (if any) will not be traversed.
+ *
+ * @see #isImportantForAutofill()
+ * @see #setImportantForAutofill(int)
*/
public static final int IMPORTANT_FOR_AUTOFILL_NO_EXCLUDE_DESCENDANTS = 0x8;
@@ -7366,23 +7393,70 @@
}
/**
- * Called when assist structure is being retrieved from a view as part of an autofill request.
+ * Populates a {@link ViewStructure} to fullfil an autofill request.
*
- * <p>This method already provides most of what's needed for autofill, but should be overridden
- * when:
+ * <p>The structure should contain at least the following properties:
* <ul>
- * <li>The view contents does not include PII (Personally Identifiable Information), so it
- * can call {@link ViewStructure#setDataIsSensitive(boolean)} passing {@code false}.
- * <li>It must set fields such {@link ViewStructure#setText(CharSequence)},
- * {@link ViewStructure#setAutofillOptions(CharSequence[])},
- * or {@link ViewStructure#setWebDomain(String)}.
- * <li> The {@code left} and {@code top} values set in
- * {@link ViewStructure#setDimens(int, int, int, int, int, int)} need to be relative to the next
- * {@link ViewGroup#isImportantForAutofill() included} parent in the structure.
+ * <li>Autofill id ({@link ViewStructure#setAutofillId(AutofillId, int)}).
+ * <li>Autofill type ({@link ViewStructure#setAutofillType(int)}).
+ * <li>Autofill value ({@link ViewStructure#setAutofillValue(AutofillValue)}).
+ * <li>Whether the data is sensitive ({@link ViewStructure#setDataIsSensitive(boolean)}).
* </ul>
*
- * @param structure Fill in with structured view data. The default implementation
- * fills in all data that can be inferred from the view itself.
+ * <p>It's also recommended to set the following properties - the more properties the structure
+ * has, the higher the changes of an {@link android.service.autofill.AutofillService} properly
+ * using the structure:
+ *
+ * <ul>
+ * <li>Autofill hints ({@link ViewStructure#setAutofillHints(String[])}).
+ * <li>Autofill options ({@link ViewStructure#setAutofillOptions(CharSequence[])}) when the
+ * view can only be filled with predefined values (typically used when the autofill type
+ * is {@link #AUTOFILL_TYPE_LIST}).
+ * <li>Resource id ({@link ViewStructure#setId(int, String, String, String)}).
+ * <li>Class name ({@link ViewStructure#setClassName(String)}).
+ * <li>Content description ({@link ViewStructure#setContentDescription(CharSequence)}).
+ * <li>Visual properties such as visibility ({@link ViewStructure#setVisibility(int)}),
+ * dimensions ({@link ViewStructure#setDimens(int, int, int, int, int, int)}), and
+ * opacity ({@link ViewStructure#setOpaque(boolean)}).
+ * <li>For views representing text fields, text properties such as the text itself
+ * ({@link ViewStructure#setText(CharSequence)}), text hints
+ * ({@link ViewStructure#setHint(CharSequence)}, input type
+ * ({@link ViewStructure#setInputType(int)}),
+ * <li>For views representing HTML nodes, its web domain
+ * ({@link ViewStructure#setWebDomain(String)}) and HTML properties
+ * (({@link ViewStructure#setHtmlInfo(android.view.ViewStructure.HtmlInfo)}).
+ * </ul>
+ *
+ * <p>The default implementation of this method already sets most of these properties based on
+ * related {@link View} methods (for example, the autofill id is set using
+ * {@link #getAutofillId()}, the autofill type set using {@link #getAutofillType()}, etc.),
+ * and views in the standard Android widgets library also override it to set their
+ * relevant properties (for example, {@link android.widget.TextView} already sets the text
+ * properties), so it's recommended to only override this method
+ * (and call {@code super.onProvideAutofillStructure()}) when:
+ *
+ * <ul>
+ * <li>The view contents does not include PII (Personally Identifiable Information), so it
+ * can call {@link ViewStructure#setDataIsSensitive(boolean)} passing {@code false}.
+ * <li>The view can only be autofilled with predefined options, so it can call
+ * {@link ViewStructure#setAutofillOptions(CharSequence[])}.
+ * </ul>
+ *
+ * <p><b>NOTE:</b> the {@code left} and {@code top} values set in
+ * {@link ViewStructure#setDimens(int, int, int, int, int, int)} must be relative to the next
+ * {@link ViewGroup#isImportantForAutofill()} predecessor view included in the structure.
+ *
+ * <p>Views support the Autofill Framework mainly by:
+ * <ul>
+ * <li>Providing the metadata defining what the view means and how it can be autofilled.
+ * <li>Notifying the Android System when the view value changed by calling
+ * {@link AutofillManager#notifyValueChanged(View)}.
+ * <li>Implementing the methods that autofill the view.
+ * </ul>
+ * <p>This method is responsible for the former; {@link #autofill(AutofillValue)} is responsible
+ * for the latter.
+ *
+ * @param structure fill in with structured view data for autofill purposes.
* @param flags optional flags.
*
* @see #AUTOFILL_FLAG_INCLUDE_NOT_IMPORTANT_VIEWS
@@ -7510,32 +7584,56 @@
}
/**
- * Called when assist structure is being retrieved from a view as part of an autofill request
- * to generate additional virtual structure under this view.
+ * Populates a {@link ViewStructure} containing virtual children to fullfil an autofill
+ * request.
+ *
+ * <p>This method should be used when the view manages a virtual structure under this view. For
+ * example, a view that draws input fields using {@link #draw(Canvas)}.
*
* <p>When implementing this method, subclasses must follow the rules below:
*
- * <ol>
- * <li>Also implement {@link #autofill(SparseArray)} to autofill the virtual
- * children.
- * <li>Call
- * {@link android.view.autofill.AutofillManager#notifyViewEntered} and
- * {@link android.view.autofill.AutofillManager#notifyViewExited(View, int)}
- * when the focus inside the view changed.
- * <li>Call {@link android.view.autofill.AutofillManager#notifyValueChanged(View, int,
- * AutofillValue)} when the value of a child changed.
- * <li>Call {@link AutofillManager#commit()} when the autofill context
- * of the view structure changed and you want the current autofill interaction if such
- * to be commited.
- * <li>Call {@link AutofillManager#cancel()} when the autofill context
- * of the view structure changed and you want the current autofill interaction if such
- * to be cancelled.
- * <li> The {@code left} and {@code top} values set in
- * {@link ViewStructure#setDimens(int, int, int, int, int, int)} need to be relative to the next
- * {@link ViewGroup#isImportantForAutofill() included} parent in the structure.
- * </ol>
+ * <ul>
+ * <li>Add virtual children by calling the {@link ViewStructure#newChild(int)} or
+ * {@link ViewStructure#asyncNewChild(int)} methods, where the {@code id} is an unique id
+ * identifying the children in the virtual structure.
+ * <li>The children hierarchy can have multiple levels if necessary, but ideally it should
+ * exclude intermediate levels that are irrelevant for autofill; that would improve the
+ * autofill performance.
+ * <li>Also implement {@link #autofill(SparseArray)} to autofill the virtual
+ * children.
+ * <li>Set the autofill properties of the child structure as defined by
+ * {@link #onProvideAutofillStructure(ViewStructure, int)}, using
+ * {@link ViewStructure#setAutofillId(AutofillId, int)} to set its autofill id.
+ * <li>Call {@link android.view.autofill.AutofillManager#notifyViewEntered(View, int, Rect)}
+ * and/or {@link android.view.autofill.AutofillManager#notifyViewExited(View, int)}
+ * when the focused virtual child changed.
+ * <li>Call
+ * {@link android.view.autofill.AutofillManager#notifyValueChanged(View, int, AutofillValue)}
+ * when the value of a virtual child changed.
+ * <li>Call {@link AutofillManager#commit()} when the autofill context of the view structure
+ * changed and the current context should be committed (for example, when the user tapped
+ * a {@code SUBMIT} button in an HTML page).
+ * <li>Call {@link AutofillManager#cancel()} when the autofill context of the view structure
+ * changed and the current context should be canceled (for example, when the user tapped
+ * a {@code CANCEL} button in an HTML page).
+ * <li>Provide ways for users to manually request autofill by calling
+ * {@link AutofillManager#requestAutofill(View, int, Rect)}.
+ * <li>The {@code left} and {@code top} values set in
+ * {@link ViewStructure#setDimens(int, int, int, int, int, int)} must be relative to the
+ * next {@link ViewGroup#isImportantForAutofill()} predecessor view included in the
+ * structure.
+ * </ul>
*
- * @param structure Fill in with structured view data.
+ * <p>Views with virtual children support the Autofill Framework mainly by:
+ * <ul>
+ * <li>Providing the metadata defining what the virtual children mean and how they can be
+ * autofilled.
+ * <li>Implementing the methods that autofill the virtual children.
+ * </ul>
+ * <p>This method is responsible for the former; {@link #autofill(SparseArray)} is responsible
+ * for the latter.
+ *
+ * @param structure fill in with virtual children data for autofill purposes.
* @param flags optional flags.
*
* @see #AUTOFILL_FLAG_INCLUDE_NOT_IMPORTANT_VIEWS
@@ -7546,15 +7644,21 @@
/**
* Automatically fills the content of this view with the {@code value}.
*
- * <p>By default does nothing, but views should override it (and {@link #getAutofillType()},
- * {@link #getAutofillValue()}, and {@link #onProvideAutofillStructure(ViewStructure, int)}
- * to support the Autofill Framework.
+ * <p>Views support the Autofill Framework mainly by:
+ * <ul>
+ * <li>Providing the metadata defining what the view means and how it can be autofilled.
+ * <li>Implementing the methods that autofill the view.
+ * </ul>
+ * <p>{@link #onProvideAutofillStructure(ViewStructure, int)} is responsible for the former,
+ * this method is responsible for latter.
*
- * <p>Typically, it is implemented by:
- *
+ * <p>This method does nothing by default, but when overridden it typically:
* <ol>
- * <li>Calling the proper getter method on {@link AutofillValue} to fetch the actual value.
- * <li>Passing the actual value to the equivalent setter in the view.
+ * <li>Checks if the provided value matches the expected type (which is defined by
+ * {@link #getAutofillType()}).
+ * <li>Checks if the view is editable - if it isn't, it should return right away.
+ * <li>Call the proper getter method on {@link AutofillValue} to fetch the actual value.
+ * <li>Pass the actual value to the equivalent setter in the view.
* </ol>
*
* <p>For example, a text-field view could implement the method this way:
@@ -7573,7 +7677,7 @@
* </pre>
*
* <p>If the value is updated asynchronously the next call to
- * {@link AutofillManager#notifyValueChanged(View)} must happen <u>after</u> the value was
+ * {@link AutofillManager#notifyValueChanged(View)} must happen <b>after</b> the value was
* changed to the autofilled value. If not, the view will not be considered autofilled.
*
* @param value value to be autofilled.
@@ -7582,11 +7686,19 @@
}
/**
- * Automatically fills the content of a virtual views.
+ * Automatically fills the content of the virtual children within this view.
*
- * <p>See {@link #autofill(AutofillValue)} and
- * {@link #onProvideAutofillVirtualStructure(ViewStructure, int)} for more info.
- * <p>To indicate that a virtual view was autofilled
+ * <p>Views with virtual children support the Autofill Framework mainly by:
+ * <ul>
+ * <li>Providing the metadata defining what the virtual children mean and how they can be
+ * autofilled.
+ * <li>Implementing the methods that autofill the virtual children.
+ * </ul>
+ * <p>{@link #onProvideAutofillVirtualStructure(ViewStructure, int)} is responsible for the
+ * former, this method is responsible for the latter - see {@link #autofill(AutofillValue)} and
+ * {@link #onProvideAutofillVirtualStructure(ViewStructure, int)} for more info about autofill.
+ *
+ * <p><b>NOTE:</b> to indicate that a virtual view was autofilled,
* <code>?android:attr/autofilledHighlight</code> should be drawn over it until the data
* changes.
*
@@ -7598,9 +7710,9 @@
}
/**
- * Gets the unique identifier of this view on the screen for Autofill purposes.
+ * Gets the unique identifier of this view in the screen, for autofill purposes.
*
- * @return The View's Autofill id.
+ * @return The View's autofill id.
*/
public final AutofillId getAutofillId() {
if (mAutofillId == null) {
@@ -7612,11 +7724,18 @@
}
/**
- * Describes the autofill type that should be used on calls to
- * {@link #autofill(AutofillValue)} and {@link #autofill(SparseArray)}.
+ * Describes the autofill type of this view, so an
+ * {@link android.service.autofill.AutofillService} can create the proper {@link AutofillValue}
+ * when autofilling the view.
*
- * <p>By default returns {@link #AUTOFILL_TYPE_NONE}, but views should override it (and
- * {@link #autofill(AutofillValue)} to support the Autofill Framework.
+ * <p>By default returns {@link #AUTOFILL_TYPE_NONE}, but views should override it to properly
+ * support the Autofill Framework.
+ *
+ * @return either {@link #AUTOFILL_TYPE_NONE}, {@link #AUTOFILL_TYPE_TEXT},
+ * {@link #AUTOFILL_TYPE_LIST}, {@link #AUTOFILL_TYPE_DATE}, or {@link #AUTOFILL_TYPE_TOGGLE}.
+ *
+ * @see #onProvideAutofillStructure(ViewStructure, int)
+ * @see #autofill(AutofillValue)
*/
public @AutofillType int getAutofillType() {
return AUTOFILL_TYPE_NONE;
@@ -7648,9 +7767,11 @@
/**
* Gets the {@link View}'s current autofill value.
*
- * <p>By default returns {@code null}, but views should override it (and
- * {@link #autofill(AutofillValue)}, and {@link #getAutofillType()} to support the Autofill
- * Framework.
+ * <p>By default returns {@code null}, but views should override it to properly support the
+ * Autofill Framework.
+ *
+ * @see #onProvideAutofillStructure(ViewStructure, int)
+ * @see #autofill(AutofillValue)
*/
@Nullable
public AutofillValue getAutofillValue() {
@@ -7658,9 +7779,10 @@
}
/**
- * Gets the mode for determining whether this View is important for autofill.
+ * Gets the mode for determining whether this view is important for autofill.
*
- * <p>See {@link #setImportantForAutofill(int)} for more info about this mode.
+ * <p>See {@link #setImportantForAutofill(int)} and {@link #isImportantForAutofill()} for more
+ * info about this mode.
*
* @return {@link #IMPORTANT_FOR_AUTOFILL_AUTO} by default, or value passed to
* {@link #setImportantForAutofill(int)}.
@@ -7681,20 +7803,29 @@
}
/**
- * Sets the mode for determining whether this View is important for autofill.
- *
- * <p>This property controls how this view is presented to the autofill components
- * which help users to fill credentials, addresses, etc. For example, views
- * that contain labels and input fields are useful for autofill components to
- * determine the user context and provide values for the inputs. Note that the
- * user can always override this by manually triggering autotill which would
- * expose the view to the autofill provider.
+ * Sets the mode for determining whether this view is considered important for autofill.
*
* <p>The platform determines the importance for autofill automatically but you
- * can use this method to customize the behavior. See the autofill modes below
- * for more details.
+ * can use this method to customize the behavior. For example:
*
- * <p>See {@link #setImportantForAutofill(int)} for more info about this mode.
+ * <ol>
+ * <li>When the view contents is irrelevant for autofill (for example, a text field used in a
+ * "Captcha" challenge), it should be {@link #IMPORTANT_FOR_AUTOFILL_NO}.
+ * <li>When both the view and its children are irrelevant for autofill (for example, the root
+ * view of an activity containing a spreadhseet editor), it should be
+ * {@link #IMPORTANT_FOR_AUTOFILL_NO_EXCLUDE_DESCENDANTS}.
+ * <li>When the view content is relevant for autofill but its children aren't (for example,
+ * a credit card expiration date represented by a custom view that overrides the proper
+ * autofill methods and has 2 children representing the month and year), it should
+ * be {@link #IMPORTANT_FOR_AUTOFILL_YES_EXCLUDE_DESCENDANTS}.
+ * </ol>
+ *
+ * <p><b>NOTE:</strong> setting the mode as does {@link #IMPORTANT_FOR_AUTOFILL_NO} or
+ * {@link #IMPORTANT_FOR_AUTOFILL_NO_EXCLUDE_DESCENDANTS} does not guarantee the view (and its
+ * children) will be always be considered not important; for example, when the user explicitly
+ * makes an autofill request, all views are considered important. See
+ * {@link #isImportantForAutofill()} for more details about how the View's importance for
+ * autofill is used.
*
* @param mode {@link #IMPORTANT_FOR_AUTOFILL_AUTO}, {@link #IMPORTANT_FOR_AUTOFILL_YES},
* {@link #IMPORTANT_FOR_AUTOFILL_NO}, {@link #IMPORTANT_FOR_AUTOFILL_YES_EXCLUDE_DESCENDANTS},
@@ -7710,40 +7841,51 @@
/**
* Hints the Android System whether the {@link android.app.assist.AssistStructure.ViewNode}
- * associated with this View should be included in a {@link ViewStructure} used for
- * autofill purposes.
+ * associated with this view is considered important for autofill purposes.
*
* <p>Generally speaking, a view is important for autofill if:
* <ol>
- * <li>The view can-be autofilled by an {@link android.service.autofill.AutofillService}.
- * <li>The view contents can help an {@link android.service.autofill.AutofillService} to
- * autofill other views.
+ * <li>The view can be autofilled by an {@link android.service.autofill.AutofillService}.
+ * <li>The view contents can help an {@link android.service.autofill.AutofillService}
+ * determine how other views can be autofilled.
* <ol>
*
* <p>For example, view containers should typically return {@code false} for performance reasons
- * (since the important info is provided by their children), but if the container is actually
- * whose children are part of a compound view, it should return {@code true} (and then override
- * {@link #dispatchProvideAutofillStructure(ViewStructure, int)} to simply call
- * {@link #onProvideAutofillStructure(ViewStructure, int)} so its children are not included in
- * the structure). On the other hand, views representing labels or editable fields should
- * typically return {@code true}, but in some cases they could return {@code false} (for
- * example, if they're part of a "Captcha" mechanism).
+ * (since the important info is provided by their children), but if its properties have relevant
+ * information (for example, a resource id called {@code credentials}, it should return
+ * {@code true}. On the other hand, views representing labels or editable fields should
+ * typically return {@code true}, but in some cases they could return {@code false}
+ * (for example, if they're part of a "Captcha" mechanism).
*
- * <p>By default, this method returns {@code true} if {@link #getImportantForAutofill()} returns
- * {@link #IMPORTANT_FOR_AUTOFILL_YES}, {@code false } if it returns
- * {@link #IMPORTANT_FOR_AUTOFILL_NO}, and use some heuristics to define the importance when it
- * returns {@link #IMPORTANT_FOR_AUTOFILL_AUTO}. Hence, it should rarely be overridden - Views
- * should use {@link #setImportantForAutofill(int)} instead.
+ * <p>The value returned by this method depends on the value returned by
+ * {@link #getImportantForAutofill()}:
*
- * <p><strong>Note:</strong> returning {@code false} does not guarantee the view will be
- * excluded from the structure; for example, if the user explicitly requested autofill, the
- * View might be always included.
+ * <ol>
+ * <li>if it returns {@link #IMPORTANT_FOR_AUTOFILL_YES} or
+ * {@link #IMPORTANT_FOR_AUTOFILL_YES_EXCLUDE_DESCENDANTS}, then it returns {@code true}
+ * <li>if it returns {@link #IMPORTANT_FOR_AUTOFILL_NO} or
+ * {@link #IMPORTANT_FOR_AUTOFILL_NO_EXCLUDE_DESCENDANTS}, then it returns {@code false}
+ * <li>if it returns {@link #IMPORTANT_FOR_AUTOFILL_AUTO}, then it uses some simple heuristics
+ * that can return {@code true} in some cases (like a container with a resource id),
+ * but {@code false} in most.
+ * <li>otherwise, it returns {@code false}.
+ * </ol>
*
- * <p>This decision applies just for the view, not its children - if the view children are not
- * important for autofill, the view should override
- * {@link #dispatchProvideAutofillStructure(ViewStructure, int)} to simply call
- * {@link #onProvideAutofillStructure(ViewStructure, int)} (instead of calling
- * {@link #dispatchProvideAutofillStructure(ViewStructure, int)} for each child).
+ * <p>When a view is considered important for autofill:
+ * <ul>
+ * <li>The view might automatically trigger an autofill request when focused on.
+ * <li>The contents of the view are included in the {@link ViewStructure} used in an autofill
+ * request.
+ * </ul>
+ *
+ * <p>On the other hand, when a view is considered not important for autofill:
+ * <ul>
+ * <li>The view never automatically triggers autofill requests, but it can trigger a manual
+ * request through {@link AutofillManager#requestAutofill(View)}.
+ * <li>The contents of the view are not included in the {@link ViewStructure} used in an
+ * autofill request, unless the request has the
+ * {@link #AUTOFILL_FLAG_INCLUDE_NOT_IMPORTANT_VIEWS} flag.
+ * </ul>
*
* @return whether the view is considered important for autofill.
*
@@ -7753,6 +7895,7 @@
* @see #IMPORTANT_FOR_AUTOFILL_NO
* @see #IMPORTANT_FOR_AUTOFILL_YES_EXCLUDE_DESCENDANTS
* @see #IMPORTANT_FOR_AUTOFILL_NO_EXCLUDE_DESCENDANTS
+ * @see AutofillManager#requestAutofill(View)
*/
public final boolean isImportantForAutofill() {
// Check parent mode to ensure we're not hidden.
@@ -7877,29 +8020,38 @@
}
/**
- * Dispatch creation of {@link ViewStructure} down the hierarchy.
+ * Dispatches creation of a {@link ViewStructure}s for autofill purposes down the hierarchy,
+ * when an Assist structure is being created as part of an autofill request.
*
* <p>The default implementation does the following:
- *
* <ul>
* <li>Sets the {@link AutofillId} in the structure.
* <li>Calls {@link #onProvideAutofillStructure(ViewStructure, int)}.
* <li>Calls {@link #onProvideAutofillVirtualStructure(ViewStructure, int)}.
* </ul>
*
- * <p>When overridden, it must either call
- * {@code super.dispatchProvideAutofillStructure(structure, flags)} or explicitly
- * set the {@link AutofillId} in the structure (for example, by calling
- * {@code structure.setAutofillId(getAutofillId())}).
+ * <p>Typically, this method should only be overridden by subclasses that provide a view
+ * hierarchy (such as {@link ViewGroup}) - other classes should override
+ * {@link #onProvideAutofillStructure(ViewStructure, int)} or
+ * {@link #onProvideAutofillVirtualStructure(ViewStructure, int)} instead.
*
- * <p>When providing your implementation you need to decide how to handle
- * the {@link #AUTOFILL_FLAG_INCLUDE_NOT_IMPORTANT_VIEWS} flag which instructs you
- * to report all views to the structure regardless if {@link #isImportantForAutofill()}
- * returns true. We encourage you respect the importance property for a better
- * user experience in your app. If the flag is not set then you should filter out
- * not important views to optimize autofill performance in your app.
+ * <p>When overridden, it must:
*
- * @param structure Fill in with structured view data.
+ * <ul>
+ * <li>Either call
+ * {@code super.dispatchProvideAutofillStructure(structure, flags)} or explicitly
+ * set the {@link AutofillId} in the structure (for example, by calling
+ * {@code structure.setAutofillId(getAutofillId())}).
+ * <li>Decide how to handle the {@link #AUTOFILL_FLAG_INCLUDE_NOT_IMPORTANT_VIEWS} flag - when
+ * set, all views in the structure should be considered important for autofill,
+ * regardless of what {@link #isImportantForAutofill()} returns. We encourage you to
+ * respect this flag to provide a better user experience - this flag is typically used
+ * when an user explicitly requested autofill. If the flag is not set,
+ * then only views marked as important for autofill should be included in the
+ * structure - skipping non-important views optimizes the overall autofill performance.
+ * </ul>
+ *
+ * @param structure fill in with structured view data for autofill purposes.
* @param flags optional flags.
*
* @see #AUTOFILL_FLAG_INCLUDE_NOT_IMPORTANT_VIEWS
diff --git a/core/java/android/view/ViewStructure.java b/core/java/android/view/ViewStructure.java
index ddfe697..0ecd20d 100644
--- a/core/java/android/view/ViewStructure.java
+++ b/core/java/android/view/ViewStructure.java
@@ -269,6 +269,9 @@
* Create a new child {@link ViewStructure} in this view, putting into the list of
* children at <var>index</var>.
*
+ * <p><b>NOTE: </b>you must pre-allocate space for the child first, by calling either
+ * {@link #addChildCount(int)} or {@link #setChildCount(int)}.
+ *
* @return Returns an fresh {@link ViewStructure} ready to be filled in.
*/
public abstract ViewStructure newChild(int index);
@@ -279,6 +282,10 @@
* to build its content (and children etc). Once done, some thread must call
* {@link #asyncCommit} to tell the containing {@link ViewStructure} that the async
* population is done.
+ *
+ * <p><b>NOTE: </b>you must pre-allocate space for the child first, by calling either
+ * {@link #addChildCount(int)} or {@link #setChildCount(int)}.
+ *
* @return Returns an fresh {@link ViewStructure} ready to be filled in.
*/
public abstract ViewStructure asyncNewChild(int index);