| /* |
| * Copyright (C) 2014 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package android.support.v4.app; |
| |
| import android.content.Intent; |
| import android.os.Build; |
| import android.os.Bundle; |
| import android.util.Log; |
| |
| /** |
| * Helper for using the {@link android.app.RemoteInput} API |
| * introduced after API level 4 in a backwards compatible fashion. |
| */ |
| public final class RemoteInput extends RemoteInputCompatBase.RemoteInput { |
| private static final String TAG = "RemoteInput"; |
| |
| /** Label used to denote the clip data type used for remote input transport */ |
| public static final String RESULTS_CLIP_LABEL = RemoteInputCompatJellybean.RESULTS_CLIP_LABEL; |
| |
| /** Extra added to a clip data intent object to hold the results bundle. */ |
| public static final String EXTRA_RESULTS_DATA = RemoteInputCompatJellybean.EXTRA_RESULTS_DATA; |
| |
| private final String mResultKey; |
| private final CharSequence mLabel; |
| private final CharSequence[] mChoices; |
| private final boolean mAllowFreeFormInput; |
| private final Bundle mExtras; |
| |
| private RemoteInput(String resultKey, CharSequence label, CharSequence[] choices, |
| boolean allowFreeFormInput, Bundle extras) { |
| this.mResultKey = resultKey; |
| this.mLabel = label; |
| this.mChoices = choices; |
| this.mAllowFreeFormInput = allowFreeFormInput; |
| this.mExtras = extras; |
| } |
| |
| /** |
| * Get the key that the result of this input will be set in from the Bundle returned by |
| * {@link #getResultsFromIntent} when the {@link android.app.PendingIntent} is sent. |
| */ |
| public String getResultKey() { |
| return mResultKey; |
| } |
| |
| /** |
| * Get the label to display to users when collecting this input. |
| */ |
| public CharSequence getLabel() { |
| return mLabel; |
| } |
| |
| /** |
| * Get possible input choices. This can be {@code null} if there are no choices to present. |
| */ |
| public CharSequence[] getChoices() { |
| return mChoices; |
| } |
| |
| /** |
| * Get whether or not users can provide an arbitrary value for |
| * input. If you set this to {@code false}, users must select one of the |
| * choices in {@link #getChoices}. An {@link IllegalArgumentException} is thrown |
| * if you set this to false and {@link #getChoices} returns {@code null} or empty. |
| */ |
| public boolean getAllowFreeFormInput() { |
| return mAllowFreeFormInput; |
| } |
| |
| /** |
| * Get additional metadata carried around with this remote input. |
| */ |
| public Bundle getExtras() { |
| return mExtras; |
| } |
| |
| /** |
| * Builder class for {@link android.support.v4.app.RemoteInput} objects. |
| */ |
| public static final class Builder { |
| private final String mResultKey; |
| private CharSequence mLabel; |
| private CharSequence[] mChoices; |
| private boolean mAllowFreeFormInput = true; |
| private Bundle mExtras = new Bundle(); |
| |
| /** |
| * Create a builder object for {@link android.support.v4.app.RemoteInput} objects. |
| * @param resultKey the Bundle key that refers to this input when collected from the user |
| */ |
| public Builder(String resultKey) { |
| if (resultKey == null) { |
| throw new IllegalArgumentException("Result key can't be null"); |
| } |
| mResultKey = resultKey; |
| } |
| |
| /** |
| * 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. |
| * @return this object for method chaining |
| */ |
| public Builder setLabel(CharSequence label) { |
| mLabel = label; |
| return this; |
| } |
| |
| /** |
| * Specifies choices available to the user to satisfy this input. |
| * @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}. |
| * @return this object for method chaining |
| */ |
| public Builder setChoices(CharSequence[] choices) { |
| mChoices = choices; |
| return this; |
| } |
| |
| /** |
| * Specifies whether the user can provide arbitrary values. |
| * |
| * @param allowFreeFormInput The default is {@code true}. |
| * If you specify {@code false}, you must provide a non-null |
| * and non-empty array to {@link #setChoices} or an |
| * {@link IllegalArgumentException} is thrown. |
| * @return this object for method chaining |
| */ |
| public Builder setAllowFreeFormInput(boolean allowFreeFormInput) { |
| mAllowFreeFormInput = allowFreeFormInput; |
| return this; |
| } |
| |
| /** |
| * Merge additional metadata into this builder. |
| * |
| * <p>Values within the Bundle will replace existing extras values in this Builder. |
| * |
| * @see RemoteInput#getExtras |
| */ |
| public Builder addExtras(Bundle extras) { |
| if (extras != null) { |
| mExtras.putAll(extras); |
| } |
| return this; |
| } |
| |
| /** |
| * Get the metadata Bundle used by this Builder. |
| * |
| * <p>The returned Bundle is shared with this Builder. |
| */ |
| public Bundle getExtras() { |
| return mExtras; |
| } |
| |
| /** |
| * Combine all of the options that have been set and return a new |
| * {@link android.support.v4.app.RemoteInput} object. |
| */ |
| public RemoteInput build() { |
| return new RemoteInput(mResultKey, mLabel, mChoices, mAllowFreeFormInput, mExtras); |
| } |
| } |
| |
| /** |
| * Get the remote input results bundle from an intent. The returned Bundle will |
| * contain a key/value for every result key populated by remote input collector. |
| * Use the {@link Bundle#getCharSequence(String)} method to retrieve a value. |
| * @param intent The intent object that fired in response to an action or content intent |
| * which also had one or more remote input requested. |
| */ |
| public static Bundle getResultsFromIntent(Intent intent) { |
| return IMPL.getResultsFromIntent(intent); |
| } |
| |
| /** |
| * Populate an intent object with the results gathered from remote input. This method |
| * should only be called by remote input collection services when sending results to a |
| * pending intent. |
| * @param remoteInputs The remote inputs for which results are being provided |
| * @param intent The intent to add remote inputs to. The {@link android.content.ClipData} |
| * field of the intent will be modified to contain the results. |
| * @param results A bundle holding the remote input results. This bundle should |
| * be populated with keys matching the result keys specified in |
| * {@code remoteInputs} with values being the result per key. |
| */ |
| public static void addResultsToIntent(RemoteInput[] remoteInputs, Intent intent, |
| Bundle results) { |
| IMPL.addResultsToIntent(remoteInputs, intent, results); |
| } |
| |
| private static final Impl IMPL; |
| |
| interface Impl { |
| Bundle getResultsFromIntent(Intent intent); |
| void addResultsToIntent(RemoteInput[] remoteInputs, Intent intent, |
| Bundle results); |
| } |
| |
| static class ImplBase implements Impl { |
| @Override |
| public Bundle getResultsFromIntent(Intent intent) { |
| Log.w(TAG, "RemoteInput is only supported from API Level 16"); |
| return null; |
| } |
| |
| @Override |
| public void addResultsToIntent(RemoteInput[] remoteInputs, Intent intent, Bundle results) { |
| Log.w(TAG, "RemoteInput is only supported from API Level 16"); |
| } |
| } |
| |
| static class ImplJellybean implements Impl { |
| @Override |
| public Bundle getResultsFromIntent(Intent intent) { |
| return RemoteInputCompatJellybean.getResultsFromIntent(intent); |
| } |
| |
| @Override |
| public void addResultsToIntent(RemoteInput[] remoteInputs, Intent intent, Bundle results) { |
| RemoteInputCompatJellybean.addResultsToIntent(remoteInputs, intent, results); |
| } |
| } |
| |
| static class ImplApi20 implements Impl { |
| @Override |
| public Bundle getResultsFromIntent(Intent intent) { |
| return RemoteInputCompatApi20.getResultsFromIntent(intent); |
| } |
| |
| @Override |
| public void addResultsToIntent(RemoteInput[] remoteInputs, Intent intent, Bundle results) { |
| RemoteInputCompatApi20.addResultsToIntent(remoteInputs, intent, results); |
| } |
| } |
| |
| static { |
| if (Build.VERSION.SDK_INT >= 20) { |
| IMPL = new ImplApi20(); |
| } else if (Build.VERSION.SDK_INT >= 16) { |
| IMPL = new ImplJellybean(); |
| } else { |
| IMPL = new ImplBase(); |
| } |
| } |
| |
| /** @hide */ |
| public static final Factory FACTORY = new Factory() { |
| @Override |
| public RemoteInput build(String resultKey, |
| CharSequence label, CharSequence[] choices, boolean allowFreeFormInput, |
| Bundle extras) { |
| return new RemoteInput(resultKey, label, choices, allowFreeFormInput, extras); |
| } |
| |
| @Override |
| public RemoteInput[] newArray(int size) { |
| return new RemoteInput[size]; |
| } |
| }; |
| } |