552 lines
20 KiB
Java
552 lines
20 KiB
Java
/*
|
|
* Copyright (C) 2017 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.app.slice;
|
|
|
|
import android.annotation.NonNull;
|
|
import android.annotation.Nullable;
|
|
import android.annotation.StringDef;
|
|
import android.app.PendingIntent;
|
|
import android.app.RemoteInput;
|
|
import android.graphics.drawable.Icon;
|
|
import android.net.Uri;
|
|
import android.os.Bundle;
|
|
import android.os.Parcel;
|
|
import android.os.Parcelable;
|
|
|
|
import com.android.internal.util.ArrayUtils;
|
|
|
|
import java.lang.annotation.Retention;
|
|
import java.lang.annotation.RetentionPolicy;
|
|
import java.util.ArrayList;
|
|
import java.util.Arrays;
|
|
import java.util.List;
|
|
import java.util.Objects;
|
|
|
|
/**
|
|
* A slice is a piece of app content and actions that can be surfaced outside of the app.
|
|
*
|
|
* <p>They are constructed using {@link Builder} in a tree structure
|
|
* that provides the OS some information about how the content should be displayed.
|
|
* @deprecated Slice framework has been deprecated, it will not receive any updates from
|
|
* {@link android.os.Build.VANILLA_ICE_CREAM} and forward. If you are looking for a
|
|
* framework that sends displayable data from one app to another, consider using
|
|
* {@link android.app.appsearch.AppSearchManager}.
|
|
*/
|
|
@Deprecated
|
|
public final class Slice implements Parcelable {
|
|
|
|
/**
|
|
* @hide
|
|
*/
|
|
@StringDef(prefix = { "HINT_" }, value = {
|
|
HINT_TITLE,
|
|
HINT_LIST,
|
|
HINT_LIST_ITEM,
|
|
HINT_LARGE,
|
|
HINT_ACTIONS,
|
|
HINT_SELECTED,
|
|
HINT_NO_TINT,
|
|
HINT_SHORTCUT,
|
|
HINT_TOGGLE,
|
|
HINT_HORIZONTAL,
|
|
HINT_PARTIAL,
|
|
HINT_SEE_MORE,
|
|
HINT_KEYWORDS,
|
|
HINT_ERROR,
|
|
HINT_TTL,
|
|
HINT_LAST_UPDATED,
|
|
HINT_PERMISSION_REQUEST,
|
|
})
|
|
@Retention(RetentionPolicy.SOURCE)
|
|
public @interface SliceHint {}
|
|
/**
|
|
* @hide
|
|
*/
|
|
@StringDef(prefix = { "SUBTYPE_" }, value = {
|
|
SUBTYPE_COLOR,
|
|
SUBTYPE_CONTENT_DESCRIPTION,
|
|
SUBTYPE_MAX,
|
|
SUBTYPE_MESSAGE,
|
|
SUBTYPE_PRIORITY,
|
|
SUBTYPE_RANGE,
|
|
SUBTYPE_SOURCE,
|
|
SUBTYPE_TOGGLE,
|
|
SUBTYPE_VALUE,
|
|
SUBTYPE_LAYOUT_DIRECTION,
|
|
})
|
|
@Retention(RetentionPolicy.SOURCE)
|
|
public @interface SliceSubtype {}
|
|
|
|
/**
|
|
* Hint that this content is a title of other content in the slice. This can also indicate that
|
|
* the content should be used in the shortcut representation of the slice (icon, label, action),
|
|
* normally this should be indicated by adding the hint on the action containing that content.
|
|
*
|
|
* @see SliceItem#FORMAT_ACTION
|
|
*/
|
|
public static final String HINT_TITLE = "title";
|
|
/**
|
|
* Hint that all sub-items/sub-slices within this content should be considered
|
|
* to have {@link #HINT_LIST_ITEM}.
|
|
*/
|
|
public static final String HINT_LIST = "list";
|
|
/**
|
|
* Hint that this item is part of a list and should be formatted as if is part
|
|
* of a list.
|
|
*/
|
|
public static final String HINT_LIST_ITEM = "list_item";
|
|
/**
|
|
* Hint that this content is important and should be larger when displayed if
|
|
* possible.
|
|
*/
|
|
public static final String HINT_LARGE = "large";
|
|
/**
|
|
* Hint that this slice contains a number of actions that can be grouped together
|
|
* in a sort of controls area of the UI.
|
|
*/
|
|
public static final String HINT_ACTIONS = "actions";
|
|
/**
|
|
* Hint indicating that this item (and its sub-items) are the current selection.
|
|
*/
|
|
public static final String HINT_SELECTED = "selected";
|
|
/**
|
|
* Hint to indicate that this content should not be tinted.
|
|
*/
|
|
public static final String HINT_NO_TINT = "no_tint";
|
|
/**
|
|
* Hint to indicate that this content should only be displayed if the slice is presented
|
|
* as a shortcut.
|
|
*/
|
|
public static final String HINT_SHORTCUT = "shortcut";
|
|
/**
|
|
* Hint indicating this content should be shown instead of the normal content when the slice
|
|
* is in small format.
|
|
*/
|
|
public static final String HINT_SUMMARY = "summary";
|
|
/**
|
|
* Hint to indicate that this content has a toggle action associated with it. To indicate that
|
|
* the toggle is on, use {@link #HINT_SELECTED}. When the toggle state changes, the intent
|
|
* associated with it will be sent along with an extra {@link #EXTRA_TOGGLE_STATE} which can be
|
|
* retrieved to see the new state of the toggle.
|
|
* @hide
|
|
*/
|
|
public static final String HINT_TOGGLE = "toggle";
|
|
/**
|
|
* Hint that list items within this slice or subslice would appear better
|
|
* if organized horizontally.
|
|
*/
|
|
public static final String HINT_HORIZONTAL = "horizontal";
|
|
/**
|
|
* Hint to indicate that this slice is incomplete and an update will be sent once
|
|
* loading is complete. Slices which contain HINT_PARTIAL will not be cached by the
|
|
* OS and should not be cached by apps.
|
|
*/
|
|
public static final String HINT_PARTIAL = "partial";
|
|
/**
|
|
* A hint representing that this item should be used to indicate that there's more
|
|
* content associated with this slice.
|
|
*/
|
|
public static final String HINT_SEE_MORE = "see_more";
|
|
/**
|
|
* @see Builder#setCallerNeeded
|
|
* @hide
|
|
*/
|
|
public static final String HINT_CALLER_NEEDED = "caller_needed";
|
|
/**
|
|
* A hint to indicate that the contents of this subslice represent a list of keywords
|
|
* related to the parent slice.
|
|
* Expected to be on an item of format {@link SliceItem#FORMAT_SLICE}.
|
|
*/
|
|
public static final String HINT_KEYWORDS = "keywords";
|
|
/**
|
|
* A hint to indicate that this slice represents an error.
|
|
*/
|
|
public static final String HINT_ERROR = "error";
|
|
/**
|
|
* Hint indicating an item representing a time-to-live for the content.
|
|
*/
|
|
public static final String HINT_TTL = "ttl";
|
|
/**
|
|
* Hint indicating an item representing when the content was created or last updated.
|
|
*/
|
|
public static final String HINT_LAST_UPDATED = "last_updated";
|
|
/**
|
|
* A hint to indicate that this slice represents a permission request for showing
|
|
* slices.
|
|
*/
|
|
public static final String HINT_PERMISSION_REQUEST = "permission_request";
|
|
/**
|
|
* Subtype to indicate that this item indicates the layout direction for content
|
|
* in the slice.
|
|
* Expected to be an item of format {@link SliceItem#FORMAT_INT}.
|
|
*/
|
|
public static final String SUBTYPE_LAYOUT_DIRECTION = "layout_direction";
|
|
/**
|
|
* Key to retrieve an extra added to an intent when a control is changed.
|
|
*/
|
|
public static final String EXTRA_TOGGLE_STATE = "android.app.slice.extra.TOGGLE_STATE";
|
|
/**
|
|
* Key to retrieve an extra added to an intent when the value of an input range is changed.
|
|
*/
|
|
public static final String EXTRA_RANGE_VALUE = "android.app.slice.extra.RANGE_VALUE";
|
|
/**
|
|
* Subtype to indicate that this is a message as part of a communication
|
|
* sequence in this slice.
|
|
* Expected to be on an item of format {@link SliceItem#FORMAT_SLICE}.
|
|
*/
|
|
public static final String SUBTYPE_MESSAGE = "message";
|
|
/**
|
|
* Subtype to tag the source (i.e. sender) of a {@link #SUBTYPE_MESSAGE}.
|
|
* Expected to be on an item of format {@link SliceItem#FORMAT_TEXT},
|
|
* {@link SliceItem#FORMAT_IMAGE} or an {@link SliceItem#FORMAT_SLICE} containing them.
|
|
*/
|
|
public static final String SUBTYPE_SOURCE = "source";
|
|
/**
|
|
* Subtype to tag an item as representing a color.
|
|
* Expected to be on an item of format {@link SliceItem#FORMAT_INT}.
|
|
*/
|
|
public static final String SUBTYPE_COLOR = "color";
|
|
/**
|
|
* Subtype to tag an item as representing a range.
|
|
* Expected to be on an item of format {@link SliceItem#FORMAT_SLICE} containing
|
|
* a {@link #SUBTYPE_VALUE} and possibly a {@link #SUBTYPE_MAX}.
|
|
*/
|
|
public static final String SUBTYPE_RANGE = "range";
|
|
/**
|
|
* Subtype to tag an item as representing the max int value for a {@link #SUBTYPE_RANGE}.
|
|
* Expected to be on an item of format {@link SliceItem#FORMAT_INT}.
|
|
*/
|
|
public static final String SUBTYPE_MAX = "max";
|
|
/**
|
|
* Subtype to tag an item as representing the current int value for a {@link #SUBTYPE_RANGE}.
|
|
* Expected to be on an item of format {@link SliceItem#FORMAT_INT}.
|
|
*/
|
|
public static final String SUBTYPE_VALUE = "value";
|
|
/**
|
|
* Subtype to indicate that this content has a toggle action associated with it. To indicate
|
|
* that the toggle is on, use {@link #HINT_SELECTED}. When the toggle state changes, the
|
|
* intent associated with it will be sent along with an extra {@link #EXTRA_TOGGLE_STATE}
|
|
* which can be retrieved to see the new state of the toggle.
|
|
*/
|
|
public static final String SUBTYPE_TOGGLE = "toggle";
|
|
/**
|
|
* Subtype to tag an item representing priority.
|
|
* Expected to be on an item of format {@link SliceItem#FORMAT_INT}.
|
|
*/
|
|
public static final String SUBTYPE_PRIORITY = "priority";
|
|
/**
|
|
* Subtype to tag an item to use as a content description.
|
|
* Expected to be on an item of format {@link SliceItem#FORMAT_TEXT}.
|
|
*/
|
|
public static final String SUBTYPE_CONTENT_DESCRIPTION = "content_description";
|
|
/**
|
|
* Subtype to tag an item as representing a time in milliseconds since midnight,
|
|
* January 1, 1970 UTC.
|
|
*/
|
|
public static final String SUBTYPE_MILLIS = "millis";
|
|
|
|
private final SliceItem[] mItems;
|
|
private final @SliceHint String[] mHints;
|
|
private SliceSpec mSpec;
|
|
private Uri mUri;
|
|
|
|
Slice(ArrayList<SliceItem> items, @SliceHint String[] hints, Uri uri, SliceSpec spec) {
|
|
mHints = hints;
|
|
mItems = items.toArray(new SliceItem[items.size()]);
|
|
mUri = uri;
|
|
mSpec = spec;
|
|
}
|
|
|
|
protected Slice(Parcel in) {
|
|
mHints = in.readStringArray();
|
|
int n = in.readInt();
|
|
mItems = new SliceItem[n];
|
|
for (int i = 0; i < n; i++) {
|
|
mItems[i] = SliceItem.CREATOR.createFromParcel(in);
|
|
}
|
|
mUri = Uri.CREATOR.createFromParcel(in);
|
|
mSpec = in.readTypedObject(SliceSpec.CREATOR);
|
|
}
|
|
|
|
/**
|
|
* @return The spec for this slice
|
|
*/
|
|
public @Nullable SliceSpec getSpec() {
|
|
return mSpec;
|
|
}
|
|
|
|
/**
|
|
* @return The Uri that this Slice represents.
|
|
*/
|
|
public Uri getUri() {
|
|
return mUri;
|
|
}
|
|
|
|
/**
|
|
* @return All child {@link SliceItem}s that this Slice contains.
|
|
*/
|
|
public List<SliceItem> getItems() {
|
|
return Arrays.asList(mItems);
|
|
}
|
|
|
|
/**
|
|
* @return All hints associated with this Slice.
|
|
*/
|
|
public @SliceHint List<String> getHints() {
|
|
return Arrays.asList(mHints);
|
|
}
|
|
|
|
@Override
|
|
public void writeToParcel(Parcel dest, int flags) {
|
|
dest.writeStringArray(mHints);
|
|
dest.writeInt(mItems.length);
|
|
for (int i = 0; i < mItems.length; i++) {
|
|
mItems[i].writeToParcel(dest, flags);
|
|
}
|
|
mUri.writeToParcel(dest, 0);
|
|
dest.writeTypedObject(mSpec, flags);
|
|
}
|
|
|
|
@Override
|
|
public int describeContents() {
|
|
return 0;
|
|
}
|
|
|
|
/**
|
|
* @hide
|
|
*/
|
|
public boolean hasHint(@SliceHint String hint) {
|
|
return ArrayUtils.contains(mHints, hint);
|
|
}
|
|
|
|
/**
|
|
* Returns whether the caller for this slice matters.
|
|
* @see Builder#setCallerNeeded
|
|
*/
|
|
public boolean isCallerNeeded() {
|
|
return hasHint(HINT_CALLER_NEEDED);
|
|
}
|
|
|
|
/**
|
|
* A Builder used to construct {@link Slice}s
|
|
* @deprecated Slice framework has been deprecated, it will not receive any updates from
|
|
* {@link android.os.Build.VANILLA_ICE_CREAM} and forward. If you are looking for a
|
|
* framework that sends displayable data from one app to another, consider using
|
|
* {@link android.app.appsearch.AppSearchManager}.
|
|
*/
|
|
@Deprecated
|
|
public static class Builder {
|
|
|
|
private final Uri mUri;
|
|
private ArrayList<SliceItem> mItems = new ArrayList<>();
|
|
private @SliceHint ArrayList<String> mHints = new ArrayList<>();
|
|
private SliceSpec mSpec;
|
|
|
|
/**
|
|
* Create a builder which will construct a {@link Slice} for the given Uri.
|
|
* @param uri Uri to tag for this slice.
|
|
* @param spec the spec for this slice.
|
|
*/
|
|
public Builder(@NonNull Uri uri, SliceSpec spec) {
|
|
mUri = uri;
|
|
mSpec = spec;
|
|
}
|
|
|
|
/**
|
|
* Create a builder for a {@link Slice} that is a sub-slice of the slice
|
|
* being constructed by the provided builder.
|
|
* @param parent The builder constructing the parent slice
|
|
*/
|
|
public Builder(@NonNull Slice.Builder parent) {
|
|
mUri = parent.mUri.buildUpon().appendPath("_gen")
|
|
.appendPath(String.valueOf(mItems.size())).build();
|
|
}
|
|
|
|
/**
|
|
* Tells the system whether for this slice the return value of
|
|
* {@link SliceProvider#onBindSlice(Uri, java.util.Set)} may be different depending on
|
|
* {@link SliceProvider#getCallingPackage()} and should not be cached for multiple
|
|
* apps.
|
|
*/
|
|
public Builder setCallerNeeded(boolean callerNeeded) {
|
|
if (callerNeeded) {
|
|
mHints.add(HINT_CALLER_NEEDED);
|
|
} else {
|
|
mHints.remove(HINT_CALLER_NEEDED);
|
|
}
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Add hints to the Slice being constructed
|
|
*/
|
|
public Builder addHints(@SliceHint List<String> hints) {
|
|
mHints.addAll(hints);
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Add a sub-slice to the slice being constructed
|
|
* @param subType Optional template-specific type information
|
|
* @see SliceItem#getSubType()
|
|
*/
|
|
public Builder addSubSlice(@NonNull Slice slice, @Nullable @SliceSubtype String subType) {
|
|
Objects.requireNonNull(slice);
|
|
mItems.add(new SliceItem(slice, SliceItem.FORMAT_SLICE, subType,
|
|
slice.getHints().toArray(new String[slice.getHints().size()])));
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Add an action to the slice being constructed
|
|
* @param subType Optional template-specific type information
|
|
* @see SliceItem#getSubType()
|
|
*/
|
|
public Slice.Builder addAction(@NonNull PendingIntent action, @NonNull Slice s,
|
|
@Nullable @SliceSubtype String subType) {
|
|
Objects.requireNonNull(action);
|
|
Objects.requireNonNull(s);
|
|
List<String> hints = s.getHints();
|
|
s.mSpec = null;
|
|
mItems.add(new SliceItem(action, s, SliceItem.FORMAT_ACTION, subType, hints.toArray(
|
|
new String[hints.size()])));
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Add text to the slice being constructed
|
|
* @param subType Optional template-specific type information
|
|
* @see SliceItem#getSubType()
|
|
*/
|
|
public Builder addText(CharSequence text, @Nullable @SliceSubtype String subType,
|
|
@SliceHint List<String> hints) {
|
|
mItems.add(new SliceItem(text, SliceItem.FORMAT_TEXT, subType, hints));
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Add an image to the slice being constructed
|
|
* @param subType Optional template-specific type information
|
|
* @see SliceItem#getSubType()
|
|
*/
|
|
public Builder addIcon(Icon icon, @Nullable @SliceSubtype String subType,
|
|
@SliceHint List<String> hints) {
|
|
Objects.requireNonNull(icon);
|
|
mItems.add(new SliceItem(icon, SliceItem.FORMAT_IMAGE, subType, hints));
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Add remote input to the slice being constructed
|
|
* @param subType Optional template-specific type information
|
|
* @see SliceItem#getSubType()
|
|
*/
|
|
public Slice.Builder addRemoteInput(RemoteInput remoteInput,
|
|
@Nullable @SliceSubtype String subType,
|
|
@SliceHint List<String> hints) {
|
|
Objects.requireNonNull(remoteInput);
|
|
mItems.add(new SliceItem(remoteInput, SliceItem.FORMAT_REMOTE_INPUT,
|
|
subType, hints));
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Add an integer to the slice being constructed
|
|
* @param subType Optional template-specific type information
|
|
* @see SliceItem#getSubType()
|
|
*/
|
|
public Builder addInt(int value, @Nullable @SliceSubtype String subType,
|
|
@SliceHint List<String> hints) {
|
|
mItems.add(new SliceItem(value, SliceItem.FORMAT_INT, subType, hints));
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Add a long to the slice being constructed
|
|
* @param subType Optional template-specific type information
|
|
* @see SliceItem#getSubType()
|
|
*/
|
|
public Slice.Builder addLong(long value, @Nullable @SliceSubtype String subType,
|
|
@SliceHint List<String> hints) {
|
|
mItems.add(new SliceItem(value, SliceItem.FORMAT_LONG, subType,
|
|
hints.toArray(new String[hints.size()])));
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Add a bundle to the slice being constructed.
|
|
* <p>Expected to be used for support library extension, should not be used for general
|
|
* development
|
|
* @param subType Optional template-specific type information
|
|
* @see SliceItem#getSubType()
|
|
*/
|
|
public Slice.Builder addBundle(Bundle bundle, @Nullable @SliceSubtype String subType,
|
|
@SliceHint List<String> hints) {
|
|
Objects.requireNonNull(bundle);
|
|
mItems.add(new SliceItem(bundle, SliceItem.FORMAT_BUNDLE, subType,
|
|
hints));
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Construct the slice.
|
|
*/
|
|
public Slice build() {
|
|
return new Slice(mItems, mHints.toArray(new String[mHints.size()]), mUri, mSpec);
|
|
}
|
|
}
|
|
|
|
public static final @android.annotation.NonNull Creator<Slice> CREATOR = new Creator<Slice>() {
|
|
@Override
|
|
public Slice createFromParcel(Parcel in) {
|
|
return new Slice(in);
|
|
}
|
|
|
|
@Override
|
|
public Slice[] newArray(int size) {
|
|
return new Slice[size];
|
|
}
|
|
};
|
|
|
|
/**
|
|
* @hide
|
|
* @return A string representation of this slice.
|
|
*/
|
|
public String toString() {
|
|
return toString("");
|
|
}
|
|
|
|
private String toString(String indent) {
|
|
StringBuilder sb = new StringBuilder();
|
|
for (int i = 0; i < mItems.length; i++) {
|
|
sb.append(indent);
|
|
if (Objects.equals(mItems[i].getFormat(), SliceItem.FORMAT_SLICE)) {
|
|
sb.append("slice:\n");
|
|
sb.append(mItems[i].getSlice().toString(indent + " "));
|
|
} else if (Objects.equals(mItems[i].getFormat(), SliceItem.FORMAT_TEXT)) {
|
|
sb.append("text: ");
|
|
sb.append(mItems[i].getText());
|
|
sb.append("\n");
|
|
} else {
|
|
sb.append(mItems[i].getFormat());
|
|
sb.append("\n");
|
|
}
|
|
}
|
|
return sb.toString();
|
|
}
|
|
}
|