| /* |
| * Copyright (C) 2015 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.service.chooser; |
| |
| import android.annotation.Nullable; |
| import android.content.ComponentName; |
| import android.content.Intent; |
| import android.content.IntentFilter; |
| import android.graphics.drawable.Icon; |
| import android.os.Bundle; |
| import android.os.Parcel; |
| import android.os.Parcelable; |
| |
| /** |
| * A ChooserTarget represents a deep-link into an application as returned by a |
| * {@link android.service.chooser.ChooserTargetService}. |
| * |
| * <p>A chooser target represents a specific deep link target into an application exposed |
| * for selection by the user. This might be a frequently emailed contact, a recently active |
| * group messaging conversation, a folder in a cloud storage app, a collection of related |
| * items published on a social media service or any other contextually relevant grouping |
| * of target app + relevant metadata.</p> |
| * |
| * <p>Creators of chooser targets should consult the relevant design guidelines for the type |
| * of target they are presenting. For example, targets involving people should be presented |
| * with a circular icon.</p> |
| */ |
| public final class ChooserTarget implements Parcelable { |
| private static final String TAG = "ChooserTarget"; |
| |
| /** |
| * The title of this target that will be shown to the user. The title may be truncated |
| * if it is too long to display in the space provided. |
| */ |
| private CharSequence mTitle; |
| |
| /** |
| * The icon that will be shown to the user to represent this target. |
| * The system may resize this icon as appropriate. |
| */ |
| private Icon mIcon; |
| |
| /** |
| * The ComponentName of the Activity to be invoked. Must be part of the target creator's |
| * own package or an Activity exported by its package. |
| */ |
| private ComponentName mComponentName; |
| |
| /** |
| * A Bundle to merge with the extras of the intent sent to this target. |
| * Any extras here will override the extras from the original intent. |
| */ |
| private Bundle mIntentExtras; |
| |
| /** |
| * The score given to this item. It can be normalized. |
| */ |
| private float mScore; |
| |
| /** |
| * Construct a deep link target for presentation by a chooser UI. |
| * |
| * <p>A target is composed of a title and an icon for presentation to the user. |
| * The UI presenting this target may truncate the title if it is too long to be presented |
| * in the available space, as well as crop, resize or overlay the supplied icon.</p> |
| * |
| * <p>The creator of a target may supply a ranking score. This score is assumed to be relative |
| * to the other targets supplied by the same |
| * {@link ChooserTargetService#onGetChooserTargets(ComponentName, IntentFilter) query}. |
| * Scores should be in the range from 0.0f (unlikely match) to 1.0f (very relevant match). |
| * Scores for a set of targets do not need to sum to 1.</p> |
| * |
| * <p>The ComponentName must be the name of an Activity component in the creator's own |
| * package, or an exported component from any other package. You may provide an optional |
| * Bundle of extras that will be merged into the final intent before it is sent to the |
| * target Activity; use this to add any additional data about the deep link that the target |
| * activity will read. e.g. conversation IDs, email addresses, etc.</p> |
| * |
| * <p>Take care not to place custom {@link android.os.Parcelable} types into |
| * the extras bundle, as the system will not be able to unparcel them to merge them.</p> |
| * |
| * @param title title of this target that will be shown to a user |
| * @param icon icon to represent this target |
| * @param score ranking score for this target between 0.0f and 1.0f, inclusive |
| * @param componentName Name of the component to be launched if this target is chosen |
| * @param intentExtras Bundle of extras to merge with the extras of the launched intent |
| */ |
| public ChooserTarget(CharSequence title, Icon icon, float score, |
| ComponentName componentName, @Nullable Bundle intentExtras) { |
| mTitle = title; |
| mIcon = icon; |
| if (score > 1.f || score < 0.f) { |
| throw new IllegalArgumentException("Score " + score + " out of range; " |
| + "must be between 0.0f and 1.0f"); |
| } |
| mScore = score; |
| mComponentName = componentName; |
| mIntentExtras = intentExtras; |
| } |
| |
| ChooserTarget(Parcel in) { |
| mTitle = in.readCharSequence(); |
| if (in.readInt() != 0) { |
| mIcon = Icon.CREATOR.createFromParcel(in); |
| } else { |
| mIcon = null; |
| } |
| mScore = in.readFloat(); |
| mComponentName = ComponentName.readFromParcel(in); |
| mIntentExtras = in.readBundle(); |
| } |
| |
| /** |
| * Returns the title of this target for display to a user. The UI displaying the title |
| * may truncate this title if it is too long to be displayed in full. |
| * |
| * @return the title of this target, intended to be shown to a user |
| */ |
| public CharSequence getTitle() { |
| return mTitle; |
| } |
| |
| /** |
| * Returns the icon representing this target for display to a user. The UI displaying the icon |
| * may crop, resize or overlay this icon. |
| * |
| * @return the icon representing this target, intended to be shown to a user |
| */ |
| public Icon getIcon() { |
| return mIcon; |
| } |
| |
| /** |
| * Returns the ranking score supplied by the creator of this ChooserTarget. |
| * Values are between 0.0f and 1.0f. The UI displaying the target may |
| * take this score into account when sorting and merging targets from multiple sources. |
| * |
| * @return the ranking score for this target between 0.0f and 1.0f, inclusive |
| */ |
| public float getScore() { |
| return mScore; |
| } |
| |
| /** |
| * Returns the ComponentName of the Activity that should be launched for this ChooserTarget. |
| * |
| * @return the name of the target Activity to launch |
| */ |
| public ComponentName getComponentName() { |
| return mComponentName; |
| } |
| |
| /** |
| * Returns the Bundle of extras to be added to an intent launched to this target. |
| * |
| * @return the extras to merge with the extras of the intent being launched |
| */ |
| public Bundle getIntentExtras() { |
| return mIntentExtras; |
| } |
| |
| @Override |
| public String toString() { |
| return "ChooserTarget{" |
| + mComponentName |
| + ", " + mIntentExtras |
| + ", '" + mTitle |
| + "', " + mScore + "}"; |
| } |
| |
| @Override |
| public int describeContents() { |
| return 0; |
| } |
| |
| @Override |
| public void writeToParcel(Parcel dest, int flags) { |
| dest.writeCharSequence(mTitle); |
| if (mIcon != null) { |
| dest.writeInt(1); |
| mIcon.writeToParcel(dest, 0); |
| } else { |
| dest.writeInt(0); |
| } |
| dest.writeFloat(mScore); |
| ComponentName.writeToParcel(mComponentName, dest); |
| dest.writeBundle(mIntentExtras); |
| } |
| |
| public static final @android.annotation.NonNull Creator<ChooserTarget> CREATOR |
| = new Creator<ChooserTarget>() { |
| @Override |
| public ChooserTarget createFromParcel(Parcel source) { |
| return new ChooserTarget(source); |
| } |
| |
| @Override |
| public ChooserTarget[] newArray(int size) { |
| return new ChooserTarget[size]; |
| } |
| }; |
| } |