From 2f6fc72efcb67737f45edb881eb2aed120a1b0bf Mon Sep 17 00:00:00 2001 From: Felipe Leme Date: Wed, 31 May 2017 11:57:46 -0700 Subject: Overall improvement on Autofill javadocs for autofillable APIs. Bug: 37567048 Test: ran 'm -j doc-comment-check-docs' and checked resulting HTML Change-Id: I7eaf0a521c3777baf0dc0002ae814990fd96a14c --- core/java/android/app/assist/AssistStructure.java | 84 +++-- core/java/android/view/View.java | 370 +++++++++++++++------- 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. * - *

The structure is used for Assist purposes when created by + *

The structure is used for assist purposes when created by * {@link android.app.Activity#onProvideAssistData}, {@link View#onProvideStructure(ViewStructure)}, * or {@link View#onProvideVirtualStructure(ViewStructure)}. * - *

The structure is used for Autofill purposes when created by + *

The structure is used for autofill purposes when created by * {@link View#onProvideAutofillStructure(ViewStructure, int)}, * or {@link View#onProvideAutofillVirtualStructure(ViewStructure, int)}. * - *

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

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

It's relevant set when the {@link AssistStructure} is used for Autofill purposes. + *

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

It's only relevant when the {@link AssistStructure} is used for Autofill purposes. + *

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

It's only relevant when the {@link AssistStructure} is used for Autofill purposes, + *

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

It's only relevant when the {@link AssistStructure} is used for Autofill purposes, - * not for Assist purposes. + *

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

Typically used by nodes whose {@link View#getAutofillType()} is a list to indicate * the meaning of each possible value in the list. * - *

It's relevant when the {@link AssistStructure} is used for Autofill purposes, not - * for Assist purposes. + *

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

It's only relevant when the {@link AssistStructure} is used for Assist purposes, - * not for Autofill purposes. + *

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

It's only relevant when the {@link AssistStructure} is used for Assist purposes, - * not for Autofill purposes. + *

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

It's only relevant when the {@link AssistStructure} is used for Assist purposes, - * not for Autofill purposes. + *

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

It's only relevant when the {@link AssistStructure} is used for Autofill purposes, - * not for Assist purposes. + *

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

It's only relevant when the {@link AssistStructure} is used for Assist purposes, - * not for Autofill purposes. + *

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

It's only relevant when the {@link AssistStructure} is used for Assist purposes, - * not for Autofill purposes. + *

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

It's only relevant when the {@link AssistStructure} is used for Assist purposes, - * not for Autofill purposes. + *

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

It's only relevant when the {@link AssistStructure} is used for Assist purposes, - * not for Autofill purposes. + *

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

It's only relevant when the {@link AssistStructure} is used for Assist purposes, - * not for Autofill purposes. + *

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

It's only relevant when the {@link AssistStructure} is used for Assist purposes, - * not for Autofill purposes. + *

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

It's only relevant when the {@link AssistStructure} is used for Assist purposes, - * not for Autofill purposes. + *

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 19ae25335f22..a9c85f0e1488 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. + * + *

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

{@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, *

{@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, * *

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

{@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; @@ -7366,23 +7393,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. + * + *

The structure should contain at least the following properties: + *

+ * + *

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: + * + *

+ * + *

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

This method already provides most of what's needed for autofill, but should be overridden - * when: *

* - * @param structure Fill in with structured view data. The default implementation - * fills in all data that can be inferred from the view itself. + *

NOTE: 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. + * + *

Views support the Autofill Framework mainly by: + *

+ *

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

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

When implementing this method, subclasses must follow the rules below: * - *

    - *
  1. Also implement {@link #autofill(SparseArray)} to autofill the virtual - * children. - *
  2. Call - * {@link android.view.autofill.AutofillManager#notifyViewEntered} and - * {@link android.view.autofill.AutofillManager#notifyViewExited(View, int)} - * when the focus inside the view changed. - *
  3. Call {@link android.view.autofill.AutofillManager#notifyValueChanged(View, int, - * AutofillValue)} when the value of a child changed. - *
  4. 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. - *
  5. 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. - *
  6. 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. - *
+ * + * + *

Views with virtual children support the Autofill Framework mainly by: + *

+ *

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 @@ -7546,15 +7644,21 @@ public class View implements Drawable.Callback, KeyEvent.Callback, /** * Automatically fills the content of this view with the {@code value}. * - *

By default does nothing, but views should override it (and {@link #getAutofillType()}, - * {@link #getAutofillValue()}, and {@link #onProvideAutofillStructure(ViewStructure, int)} - * to support the Autofill Framework. - * - *

Typically, it is implemented by: + *

Views support the Autofill Framework mainly by: + *

+ *

{@link #onProvideAutofillStructure(ViewStructure, int)} is responsible for the former, + * this method is responsible for latter. * + *

This method does nothing by default, but when overridden it typically: *

    - *
  1. Calling the proper getter method on {@link AutofillValue} to fetch the actual value. - *
  2. Passing the actual value to the equivalent setter in the view. + *
  3. Checks if the provided value matches the expected type (which is defined by + * {@link #getAutofillType()}). + *
  4. Checks if the view is editable - if it isn't, it should return right away. + *
  5. Call the proper getter method on {@link AutofillValue} to fetch the actual value. + *
  6. Pass the actual value to the equivalent setter in the view. *
* *

For example, a text-field view could implement the method this way: @@ -7573,7 +7677,7 @@ public class View implements Drawable.Callback, KeyEvent.Callback, * * *

If the value is updated asynchronously the next call to - * {@link AutofillManager#notifyValueChanged(View)} must happen after the value was + * {@link AutofillManager#notifyValueChanged(View)} must happen after 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 @@ 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. * - *

See {@link #autofill(AutofillValue)} and - * {@link #onProvideAutofillVirtualStructure(ViewStructure, int)} for more info. - *

To indicate that a virtual view was autofilled + *

Views with virtual children support the Autofill Framework mainly by: + *

+ *

{@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. + * + *

NOTE: to indicate that a virtual view was autofilled, * ?android:attr/autofilledHighlight should be drawn over it until the data * changes. * @@ -7598,9 +7710,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) { @@ -7612,11 +7724,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. + * + *

By default returns {@link #AUTOFILL_TYPE_NONE}, but views should override it to properly + * support the Autofill Framework. * - *

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; @@ -7648,9 +7767,11 @@ public class View implements Drawable.Callback, KeyEvent.Callback, /** * Gets the {@link View}'s current autofill value. * - *

By default returns {@code null}, but views should override it (and - * {@link #autofill(AutofillValue)}, and {@link #getAutofillType()} to support the Autofill - * Framework. + *

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

See {@link #setImportantForAutofill(int)} for more info about this mode. + *

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 @@ public class View implements Drawable.Callback, KeyEvent.Callback, } /** - * Sets the mode for determining whether this View is important for autofill. - * - *

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

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: + * + *

    + *
  1. 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}. + *
  2. 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}. + *
  3. 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}. + *
* - *

See {@link #setImportantForAutofill(int)} for more info about this mode. + *

NOTE: 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 @@ 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. * *

Generally speaking, a view is important for autofill if: *

    - *
  1. The view can-be autofilled by an {@link android.service.autofill.AutofillService}. - *
  2. The view contents can help an {@link android.service.autofill.AutofillService} to - * autofill other views. + *
  3. The view can be autofilled by an {@link android.service.autofill.AutofillService}. + *
  4. The view contents can help an {@link android.service.autofill.AutofillService} + * determine how other views can be autofilled. *
      * *

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

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

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

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

      The value returned by this method depends on the value returned by + * {@link #getImportantForAutofill()}: + * + *

        + *
      1. if it returns {@link #IMPORTANT_FOR_AUTOFILL_YES} or + * {@link #IMPORTANT_FOR_AUTOFILL_YES_EXCLUDE_DESCENDANTS}, then it returns {@code true} + *
      2. if it returns {@link #IMPORTANT_FOR_AUTOFILL_NO} or + * {@link #IMPORTANT_FOR_AUTOFILL_NO_EXCLUDE_DESCENDANTS}, then it returns {@code false} + *
      3. 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. + *
      4. otherwise, it returns {@code false}. + *
      + * + *

      When a view is considered important for autofill: + *

        + *
      • The view might automatically trigger an autofill request when focused on. + *
      • The contents of the view are included in the {@link ViewStructure} used in an autofill + * request. + *
      + * + *

      On the other hand, when a view is considered not important for autofill: + *

        + *
      • The view never automatically triggers autofill requests, but it can trigger a manual + * request through {@link AutofillManager#requestAutofill(View)}. + *
      • 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. + *
      * * @return whether the view is considered important for autofill. * @@ -7753,6 +7895,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. @@ -7877,29 +8020,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. * *

      The default implementation does the following: - * *

        *
      • Sets the {@link AutofillId} in the structure. *
      • Calls {@link #onProvideAutofillStructure(ViewStructure, int)}. *
      • Calls {@link #onProvideAutofillVirtualStructure(ViewStructure, int)}. *
      * - *

      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())}). + *

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

      When overridden, it must: * - *

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

        + *
      • Either call + * {@code super.dispatchProvideAutofillStructure(structure, flags)} or explicitly + * set the {@link AutofillId} in the structure (for example, by calling + * {@code structure.setAutofillId(getAutofillId())}). + *
      • 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. + *
      * - * @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 index. * + *

      NOTE: 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. + * + *

      NOTE: 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); -- cgit v1.2.3-59-g8ed1b