From 4b3a54710792d24233b77bcd6cca120b9ffe0b32 Mon Sep 17 00:00:00 2001 From: Kodlee Yin Date: Wed, 9 May 2018 16:19:56 -0700 Subject: [PATCH] Update RemoteInput#setChoices documentation The behavior that #setChoices didn't render on mobile devices from apps that target SDK < P went undocumented. Because this is changing in P and above, this documentation needs to point out this behavior. Also updated formatting and style of docs to improve interop with kotlin. Test: none Bug: 79244189 Change-Id: Iabfe3b2ddcc369e5ec15f9773481468cbc48dabb --- core/java/android/app/RemoteInput.java | 40 ++++++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/core/java/android/app/RemoteInput.java b/core/java/android/app/RemoteInput.java index 6feb38e9d791..85fe99d95969 100644 --- a/core/java/android/app/RemoteInput.java +++ b/core/java/android/app/RemoteInput.java @@ -17,6 +17,8 @@ package android.app; import android.annotation.IntDef; +import android.annotation.NonNull; +import android.annotation.Nullable; import android.content.ClipData; import android.content.ClipDescription; import android.content.Intent; @@ -178,17 +180,18 @@ public final class RemoteInput implements Parcelable { */ public static final class Builder { private final String mResultKey; + private final ArraySet mAllowedDataTypes = new ArraySet<>(); + private final Bundle mExtras = new Bundle(); private CharSequence mLabel; private CharSequence[] mChoices; private int mFlags = DEFAULT_FLAGS; - private Bundle mExtras = new Bundle(); - private final ArraySet mAllowedDataTypes = new ArraySet<>(); /** * Create a builder object for {@link RemoteInput} objects. + * * @param resultKey the Bundle key that refers to this input when collected from the user */ - public Builder(String resultKey) { + public Builder(@NonNull String resultKey) { if (resultKey == null) { throw new IllegalArgumentException("Result key can't be null"); } @@ -197,22 +200,30 @@ public final class RemoteInput implements Parcelable { /** * Set a label to be displayed to the user when collecting this input. - * @param label The label to show to users when they input a response. + * + * @param label The label to show to users when they input a response * @return this object for method chaining */ - public Builder setLabel(CharSequence label) { + @NonNull + public Builder setLabel(@Nullable CharSequence label) { mLabel = Notification.safeCharSequence(label); return this; } /** * Specifies choices available to the user to satisfy this input. + * + *

Note: Starting in Android P, these choices will always be shown on phones if the app's + * target SDK is >= P. However, these choices may also be rendered on other types of devices + * regardless of target SDK. + * * @param choices an array of pre-defined choices for users input. * You must provide a non-null and non-empty array if - * you disabled free form input using {@link #setAllowFreeFormInput}. + * you disabled free form input using {@link #setAllowFreeFormInput} * @return this object for method chaining */ - public Builder setChoices(CharSequence[] choices) { + @NonNull + public Builder setChoices(@Nullable CharSequence[] choices) { if (choices == null) { mChoices = null; } else { @@ -232,11 +243,12 @@ public final class RemoteInput implements Parcelable { * @param mimeType A mime type that results are allowed to come in. * Be aware that text results (see {@link #setAllowFreeFormInput} * are allowed by default. If you do not want text results you will have to - * pass false to {@code setAllowFreeFormInput}. - * @param doAllow Whether the mime type should be allowed or not. + * pass false to {@code setAllowFreeFormInput} + * @param doAllow Whether the mime type should be allowed or not * @return this object for method chaining */ - public Builder setAllowDataType(String mimeType, boolean doAllow) { + @NonNull + public Builder setAllowDataType(@NonNull String mimeType, boolean doAllow) { if (doAllow) { mAllowedDataTypes.add(mimeType); } else { @@ -252,9 +264,10 @@ public final class RemoteInput implements Parcelable { * If you specify {@code false}, you must either provide a non-null * and non-empty array to {@link #setChoices}, or enable a data result * in {@code setAllowDataType}. Otherwise an - * {@link IllegalArgumentException} is thrown. + * {@link IllegalArgumentException} is thrown * @return this object for method chaining */ + @NonNull public Builder setAllowFreeFormInput(boolean allowFreeFormTextInput) { setFlag(mFlags, allowFreeFormTextInput); return this; @@ -267,7 +280,8 @@ public final class RemoteInput implements Parcelable { * * @see RemoteInput#getExtras */ - public Builder addExtras(Bundle extras) { + @NonNull + public Builder addExtras(@NonNull Bundle extras) { if (extras != null) { mExtras.putAll(extras); } @@ -279,6 +293,7 @@ public final class RemoteInput implements Parcelable { * *

The returned Bundle is shared with this Builder. */ + @NonNull public Bundle getExtras() { return mExtras; } @@ -295,6 +310,7 @@ public final class RemoteInput implements Parcelable { * Combine all of the options that have been set and return a new {@link RemoteInput} * object. */ + @NonNull public RemoteInput build() { return new RemoteInput( mResultKey, mLabel, mChoices, mFlags, mExtras, mAllowedDataTypes); -- 2.11.0