diff options
| -rw-r--r-- | core/java/android/app/assist/AssistStructure.java | 84 | ||||
| -rw-r--r-- | core/java/android/view/View.java | 370 | ||||
| -rw-r--r-- | core/java/android/view/ViewStructure.java | 7 |
3 files changed, 309 insertions, 152 deletions
diff --git a/core/java/android/app/assist/AssistStructure.java b/core/java/android/app/assist/AssistStructure.java index c99a1e4311dd..266fa7e24b2c 100644 --- a/core/java/android/app/assist/AssistStructure.java +++ b/core/java/android/app/assist/AssistStructure.java @@ -18,7 +18,6 @@ import android.os.PooledStringReader; 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.ViewStructure.HtmlInfo.Builder; 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.Arrays; 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 @@ public class AssistStructure implements Parcelable { /** * 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 @@ public class AssistStructure implements Parcelable { /** * 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 @@ public class AssistStructure implements Parcelable { * 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 @@ public class AssistStructure implements Parcelable { /** * 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 @@ public class AssistStructure implements Parcelable { * <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 @@ public class AssistStructure implements Parcelable { * 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 @@ public class AssistStructure implements Parcelable { * 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 @@ public class AssistStructure implements Parcelable { * 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 @@ public class AssistStructure implements Parcelable { * 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 @@ public class AssistStructure implements Parcelable { /** * 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 @@ public class AssistStructure implements Parcelable { /** * 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 @@ public class AssistStructure implements Parcelable { * 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 @@ public class AssistStructure implements Parcelable { * 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 @@ public class AssistStructure implements Parcelable { * 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 @@ public class AssistStructure implements Parcelable { * 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 @@ public class AssistStructure implements Parcelable { * 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 @@ public class AssistStructure implements Parcelable { * 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 8105d243bd3c..44f70000d590 100644 --- a/core/java/android/view/View.java +++ b/core/java/android/view/View.java @@ -1139,6 +1139,10 @@ public class View implements Drawable.Callback, KeyEvent.Callback, /** * 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 @@ public class View implements Drawable.Callback, KeyEvent.Callback, * <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 @@ public class View implements Drawable.Callback, KeyEvent.Callback, * <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 @@ public class View implements Drawable.Callback, KeyEvent.Callback, * * <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 @@ public class View implements Drawable.Callback, KeyEvent.Callback, * <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 @@ public class View implements Drawable.Callback, KeyEvent.Callback, /** * 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; @@ -7364,23 +7391,70 @@ public class View implements Drawable.Callback, KeyEvent.Callback, } /** - * 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>The structure should contain at least the following properties: + * <ul> + * <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> + * + * <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: * - * <p>This method already provides most of what's needed for autofill, but should be overridden - * 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>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. + * 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> * - * @param structure Fill in with structured view data. The default implementation - * fills in all data that can be inferred from the view itself. + * <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 @@ -7508,32 +7582,56 @@ public class View implements Drawable.Callback, KeyEvent.Callback, } /** - * 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> + * + * <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 structured view data. + * @param structure fill in with virtual children data for autofill purposes. * @param flags optional flags. * * @see #AUTOFILL_FLAG_INCLUDE_NOT_IMPORTANT_VIEWS @@ -7544,15 +7642,21 @@ public class View implements Drawable.Callback, KeyEvent.Callback, /** * 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>Typically, it is implemented by: + * <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>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: @@ -7571,7 +7675,7 @@ public class View implements Drawable.Callback, KeyEvent.Callback, * </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. @@ -7580,11 +7684,19 @@ public class View implements Drawable.Callback, KeyEvent.Callback, } /** - * 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. * @@ -7596,9 +7708,9 @@ public class View implements Drawable.Callback, KeyEvent.Callback, } /** - * 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) { @@ -7610,11 +7722,18 @@ public class View implements Drawable.Callback, KeyEvent.Callback, } /** - * 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 to properly + * support the Autofill Framework. * - * <p>By default returns {@link #AUTOFILL_TYPE_NONE}, but views should override it (and - * {@link #autofill(AutofillValue)} to 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; @@ -7646,9 +7765,11 @@ public class View implements Drawable.Callback, KeyEvent.Callback, /** * 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() { @@ -7656,9 +7777,10 @@ public class View implements Drawable.Callback, KeyEvent.Callback, } /** - * 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)}. @@ -7679,20 +7801,29 @@ public class View implements Drawable.Callback, KeyEvent.Callback, } /** - * 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: + * + * <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>See {@link #setImportantForAutofill(int)} for more info about this mode. + * <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}, @@ -7708,40 +7839,51 @@ public class View implements Drawable.Callback, KeyEvent.Callback, /** * 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). - * - * <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><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. - * - * <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). + * (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>The value returned by this method depends on the value returned by + * {@link #getImportantForAutofill()}: + * + * <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>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. * @@ -7751,6 +7893,7 @@ public class View implements Drawable.Callback, KeyEvent.Callback, * @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. @@ -7875,29 +8018,38 @@ public class View implements Drawable.Callback, KeyEvent.Callback, } /** - * 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 overridden, it must: * - * <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. + * <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. + * @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 ddfe697da053..0ecd20da21c5 100644 --- a/core/java/android/view/ViewStructure.java +++ b/core/java/android/view/ViewStructure.java @@ -269,6 +269,9 @@ public abstract class ViewStructure { * 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 @@ public abstract class ViewStructure { * 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); |