From 8dfe3fa979d7a261675473d44e0b8c6a35ce6c5f Mon Sep 17 00:00:00 2001 From: Felipe Leme Date: Thu, 25 May 2017 10:55:36 -0700 Subject: [PATCH] Improved autofillHints documentation. Bug: 38086244 Test: ran 'mmm -j frameworks/base/:doc-comment-check-docs' and checked HTML. Change-Id: Ia7d2f75ae1db067106af36aa8dbb1cdbf3b40b3a --- core/java/android/view/View.java | 160 +++++++++++++++++++++++++++------------ 1 file changed, 111 insertions(+), 49 deletions(-) diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java index 5b51c16a1dfb..eafd17bd9e0a 100644 --- a/core/java/android/view/View.java +++ b/core/java/android/view/View.java @@ -964,115 +964,155 @@ public class View implements Drawable.Callback, KeyEvent.Callback, private static final int[] VISIBILITY_FLAGS = {VISIBLE, INVISIBLE, GONE}; /** - * This view contains an email address. + * Hint indicating that this view can be autofilled with an email address. * - * Use with {@link #setAutofillHints(String[])}, or set "{@value #AUTOFILL_HINT_EMAIL_ADDRESS}" - * to {@code android:autofillHint}. + *

Can be used with either {@link #setAutofillHints(String[])} or + * {@code android:autofillHint} (in which case the + * value should be {@value #AUTOFILL_HINT_EMAIL_ADDRESS}). + * + *

See {@link #setAutofillHints(String...)} for more info about autofill hints. */ public static final String AUTOFILL_HINT_EMAIL_ADDRESS = "emailAddress"; /** - * The view contains a real name. + * Hint indicating that this view can be autofilled with a user's real name. + * + *

Can be used with either {@link #setAutofillHints(String[])} or + * {@code android:autofillHint} (in which case the + * value should be {@value #AUTOFILL_HINT_NAME}). * - * Use with {@link #setAutofillHints(String[])}, or set "{@value #AUTOFILL_HINT_NAME}" to - * {@code android:autofillHint}. + *

See {@link #setAutofillHints(String...)} for more info about autofill hints. */ public static final String AUTOFILL_HINT_NAME = "name"; /** - * The view contains a user name. + * Hint indicating that this view can be autofilled with a username. + * + *

Can be used with either {@link #setAutofillHints(String[])} or + * {@code android:autofillHint} (in which case the + * value should be {@value #AUTOFILL_HINT_USERNAME}). * - * Use with {@link #setAutofillHints(String[])}, or set "{@value #AUTOFILL_HINT_USERNAME}" to - * {@code android:autofillHint}. + *

See {@link #setAutofillHints(String...)} for more info about autofill hints. */ public static final String AUTOFILL_HINT_USERNAME = "username"; /** - * The view contains a password. + * Hint indicating that this view can be autofilled with a password. * - * Use with {@link #setAutofillHints(String[])}, or set "{@value #AUTOFILL_HINT_PASSWORD}" to - * {@code android:autofillHint}. + *

Can be used with either {@link #setAutofillHints(String[])} or + * {@code android:autofillHint} (in which case the + * value should be {@value #AUTOFILL_HINT_PASSWORD}). + * + *

See {@link #setAutofillHints(String...)} for more info about autofill hints. */ public static final String AUTOFILL_HINT_PASSWORD = "password"; /** - * The view contains a phone number. + * Hint indicating that this view can be autofilled with a phone number. + * + *

Can be used with either {@link #setAutofillHints(String[])} or + * {@code android:autofillHint} (in which case the + * value should be {@value #AUTOFILL_HINT_PHONE}). * - * Use with {@link #setAutofillHints(String[])}, or set "{@value #AUTOFILL_HINT_PHONE}" to - * {@code android:autofillHint}. + *

See {@link #setAutofillHints(String...)} for more info about autofill hints. */ public static final String AUTOFILL_HINT_PHONE = "phone"; /** - * The view contains a postal address. + * Hint indicating that this view can be autofilled with a postal address. * - * Use with {@link #setAutofillHints(String[])}, or set "{@value #AUTOFILL_HINT_POSTAL_ADDRESS}" - * to {@code android:autofillHint}. + *

Can be used with either {@link #setAutofillHints(String[])} or + * {@code android:autofillHint} (in which case the + * value should be {@value #AUTOFILL_HINT_POSTAL_ADDRESS}). + * + *

See {@link #setAutofillHints(String...)} for more info about autofill hints. */ public static final String AUTOFILL_HINT_POSTAL_ADDRESS = "postalAddress"; /** - * The view contains a postal code. + * Hint indicating that this view can be autofilled with a postal code. + * + *

Can be used with either {@link #setAutofillHints(String[])} or + * {@code android:autofillHint} (in which case the + * value should be {@value #AUTOFILL_HINT_POSTAL_CODE}). * - * Use with {@link #setAutofillHints(String[])}, or set "{@value #AUTOFILL_HINT_POSTAL_CODE}" to - * {@code android:autofillHint}. + *

See {@link #setAutofillHints(String...)} for more info about autofill hints. */ public static final String AUTOFILL_HINT_POSTAL_CODE = "postalCode"; /** - * The view contains a credit card number. + * Hint indicating that this view can be autofilled with a credit card number. * - * Use with {@link #setAutofillHints(String[])}, or set "{@value - * #AUTOFILL_HINT_CREDIT_CARD_NUMBER}" to {@code - * android:autofillHint}. + *

Can be used with either {@link #setAutofillHints(String[])} or + * {@code android:autofillHint} (in which case the + * value should be {@value #AUTOFILL_HINT_CREDIT_CARD_NUMBER}). + * + *

See {@link #setAutofillHints(String...)} for more info about autofill hints. */ public static final String AUTOFILL_HINT_CREDIT_CARD_NUMBER = "creditCardNumber"; /** - * The view contains a credit card security code. + * Hint indicating that this view can be autofilled with a credit card security code. + * + *

Can be used with either {@link #setAutofillHints(String[])} or + * {@code android:autofillHint} (in which case the + * value should be {@value #AUTOFILL_HINT_CREDIT_CARD_SECURITY_CODE}). * - * Use with {@link #setAutofillHints(String[])}, or set "{@value - * #AUTOFILL_HINT_CREDIT_CARD_SECURITY_CODE}" to {@code - * android:autofillHint}. + *

See {@link #setAutofillHints(String...)} for more info about autofill hints. */ public static final String AUTOFILL_HINT_CREDIT_CARD_SECURITY_CODE = "creditCardSecurityCode"; /** - * The view contains a credit card expiration date. + * Hint indicating that this view can be autofilled with a credit card expiration date. * - * Use with {@link #setAutofillHints(String[])}, or set "{@value - * #AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_DATE}" to {@code - * android:autofillHint}. + *

It should be used when the credit card expiration date is represented by just one view; + * if it is represented by more than one (for example, one view for the month and another view + * for the year), then each of these views should use the hint specific for the unit + * ({@link #AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_DAY}, + * {@link #AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_MONTH}, + * or {@link #AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_YEAR}). + * + *

Can be used with either {@link #setAutofillHints(String[])} or + * {@code android:autofillHint} (in which case the + * value should be {@value #AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_DATE}). + * + *

See {@link #setAutofillHints(String...)} for more info about autofill hints. */ public static final String AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_DATE = "creditCardExpirationDate"; /** - * The view contains the month a credit card expires. + * Hint indicating that this view can be autofilled with a credit card expiration month. * - * Use with {@link #setAutofillHints(String[])}, or set "{@value - * #AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_MONTH}" to {@code - * android:autofillHint}. + *

Can be used with either {@link #setAutofillHints(String[])} or + * {@code android:autofillHint} (in which case the + * value should be {@value #AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_MONTH}). + * + *

See {@link #setAutofillHints(String...)} for more info about autofill hints. */ public static final String AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_MONTH = "creditCardExpirationMonth"; /** - * The view contains the year a credit card expires. + * Hint indicating that this view can be autofilled with a credit card expiration year. + * + *

Can be used with either {@link #setAutofillHints(String[])} or + * {@code android:autofillHint} (in which case the + * value should be {@value #AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_YEAR}). * - * Use with {@link #setAutofillHints(String[])}, or set "{@value - * #AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_YEAR}" to {@code - * android:autofillHint}. + *

See {@link #setAutofillHints(String...)} for more info about autofill hints. */ public static final String AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_YEAR = "creditCardExpirationYear"; /** - * The view contains the day a credit card expires. + * Hint indicating that this view can be autofilled with a credit card expiration day. * - * Use with {@link #setAutofillHints(String[])}, or set "{@value - * #AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_DAY}" to {@code - * android:autofillHint}. + *

Can be used with either {@link #setAutofillHints(String[])} or + * {@code android:autofillHint} (in which case the + * value should be {@value #AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_DAY}). + * + *

See {@link #setAutofillHints(String...)} for more info about autofill hints. */ public static final String AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_DAY = "creditCardExpirationDay"; @@ -7575,9 +7615,13 @@ public class View implements Drawable.Callback, KeyEvent.Callback, } /** - * Describes the content of a view so that a autofill service can fill in the appropriate data. + * Gets the hints that help an {@link android.service.autofill.AutofillService} determine how + * to autofill the view with the user's data. + * + *

See {@link #setAutofillHints(String...)} for more info about these hints. * - * @return The hints set via the attribute or {@code null} if no hint it set. + * @return The hints set via the attribute or {@link #setAutofillHints(String...)}, or + * {@code null} if no hints were set. * * @attr ref android.R.styleable#View_autofillHints */ @@ -9242,8 +9286,26 @@ public class View implements Drawable.Callback, KeyEvent.Callback, } /** - * Sets the hints that helps the autofill service to select the appropriate data to fill the - * view. + * Sets the hints that help an {@link android.service.autofill.AutofillService} determine how + * to autofill the view with the user's data. + * + *

Typically, there is only one way to autofill a view, but there could be more than one. + * For example, if the application accepts either an username or email address to identify + * an user. + * + *

These hints are not validated by the Android System, but passed "as is" to the service. + * Hence, they can have any value, but it's recommended to use the {@code AUTOFILL_HINT_} + * constants such as: + * {@link #AUTOFILL_HINT_USERNAME}, {@link #AUTOFILL_HINT_PASSWORD}, + * {@link #AUTOFILL_HINT_EMAIL_ADDRESS}, + * {@link #AUTOFILL_HINT_NAME}, + * {@link #AUTOFILL_HINT_PHONE}, + * {@link #AUTOFILL_HINT_POSTAL_ADDRESS}, {@link #AUTOFILL_HINT_POSTAL_CODE}, + * {@link #AUTOFILL_HINT_CREDIT_CARD_NUMBER}, {@link #AUTOFILL_HINT_CREDIT_CARD_SECURITY_CODE}, + * {@link #AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_DATE}, + * {@link #AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_DAY}, + * {@link #AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_MONTH} or + * {@link #AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_YEAR}. * * @param autofillHints The autofill hints to set. If the array is emtpy, {@code null} is set. * @attr ref android.R.styleable#View_autofillHints -- 2.11.0