Merge "Update RemoteInput#setChoices documentation" into pi-dev am: bef37f23d6
am: f4a2505e3e
Change-Id: I8490319bf518be784fa73902bc4535f22e96727a
diff --git a/core/java/android/app/RemoteInput.java b/core/java/android/app/RemoteInput.java
index 6feb38e..85fe99d 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 static final class Builder {
private final String mResultKey;
+ private final ArraySet<String> 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<String> 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 @@
/**
* 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.
+ *
+ * <p>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 @@
* @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 @@
* 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 @@
*
* @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 @@
*
* <p>The returned Bundle is shared with this Builder.
*/
+ @NonNull
public Bundle getExtras() {
return mExtras;
}
@@ -295,6 +310,7 @@
* 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);