Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Overall improvement on Autofill javadocs for autofillable APIs." into oc-dev

Browse Source 
am: 9be8c96918

Change-Id: Ib165e14765a74e77fd41d15d979bf7f7ac0726ed
This commit is contained in:
Felipe Leme
2017-06-08 06:07:15 +00:00
committed by android-build-merger
parent d88c71a6e2 9be8c96918
commit 4d579eacec
3 changed files with 307 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
core/java/android/app/assist/AssistStructure.java
View File

@@ -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;

366
core/java/android/view/View.java
View File

@@ -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>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
@@ -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>
*
* @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
@@ -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 (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;
@@ -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:
*
* <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},
@@ -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).
* (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.
*
@@ -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 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

7
core/java/android/view/ViewStructure.java
View File

@@ -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);