path: root/android/slice/Slice.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.slice;

import static android.slice.SliceItem.TYPE_ACTION;
import static android.slice.SliceItem.TYPE_COLOR;
import static android.slice.SliceItem.TYPE_IMAGE;
import static android.slice.SliceItem.TYPE_REMOTE_INPUT;
import static android.slice.SliceItem.TYPE_REMOTE_VIEW;
import static android.slice.SliceItem.TYPE_SLICE;
import static android.slice.SliceItem.TYPE_TEXT;
import static android.slice.SliceItem.TYPE_TIMESTAMP;

import android.annotation.NonNull;
import android.annotation.StringDef;
import android.app.PendingIntent;
import android.app.RemoteInput;
import android.graphics.drawable.Icon;
import android.net.Uri;
import android.os.Parcel;
import android.os.Parcelable;
import android.widget.RemoteViews;

import com.android.internal.util.ArrayUtils;

import java.util.ArrayList;
import java.util.Arrays;

/**
 * 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.
 * @hide
 */
public final class Slice implements Parcelable {

    /**
     * @hide
     */
    @StringDef({HINT_TITLE, HINT_LIST, HINT_LIST_ITEM, HINT_LARGE, HINT_ACTIONS, HINT_SELECTED,
            HINT_SOURCE, HINT_MESSAGE, HINT_HORIZONTAL, HINT_NO_TINT})
    public @interface SliceHint{ }

    /**
     * Hint that this content is a title of other content in the slice.
     */
    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 is a message as part of a communication
     * sequence in this slice.
     */
    public static final String HINT_MESSAGE     = "message";
    /**
     * Hint to tag the source (i.e. sender) of a {@link #HINT_MESSAGE}.
     */
    public static final String HINT_SOURCE      = "source";
    /**
     * 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 content should not be tinted.
     */
    public static final String HINT_NO_TINT     = "no_tint";

    // These two are coming over from prototyping, but we probably don't want in
    // public API, at least not right now.
    /**
     * @hide
     */
    public static final String HINT_ALT         = "alt";
    /**
     * @hide
     */
    public static final String HINT_PARTIAL     = "partial";

    private final SliceItem[] mItems;
    private final @SliceHint String[] mHints;
    private Uri mUri;

    /**
     * @hide
     */
    public Slice(ArrayList<SliceItem> items, @SliceHint String[] hints, Uri uri) {
        mHints = hints;
        mItems = items.toArray(new SliceItem[items.size()]);
        mUri = uri;
    }

    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);
    }

    /**
     * @return The Uri that this Slice represents.
     */
    public Uri getUri() {
        return mUri;
    }

    /**
     * @return All child {@link SliceItem}s that this Slice contains.
     */
    public SliceItem[] getItems() {
        return mItems;
    }

    /**
     * @return All hints associated with this Slice.
     */
    public @SliceHint String[] getHints() {
        return mHints;
    }

    /**
     * @hide
     */
    public SliceItem getPrimaryIcon() {
        for (SliceItem item : getItems()) {
            if (item.getType() == TYPE_IMAGE) {
                return item;
            }
            if (!(item.getType() == TYPE_SLICE && item.hasHint(Slice.HINT_LIST))
                    && !item.hasHint(Slice.HINT_ACTIONS)
                    && !item.hasHint(Slice.HINT_LIST_ITEM)
                    && (item.getType() != TYPE_ACTION)) {
                SliceItem icon = SliceQuery.find(item, TYPE_IMAGE);
                if (icon != null) return icon;
            }
        }
        return null;
    }

    @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);
    }

    @Override
    public int describeContents() {
        return 0;
    }

    /**
     * @hide
     */
    public boolean hasHint(@SliceHint String hint) {
        return ArrayUtils.contains(mHints, hint);
    }

    /**
     * A Builder used to construct {@link Slice}s
     */
    public static class Builder {

        private final Uri mUri;
        private ArrayList<SliceItem> mItems = new ArrayList<>();
        private @SliceHint ArrayList<String> mHints = new ArrayList<>();

        /**
         * Create a builder which will construct a {@link Slice} for the Given Uri.
         * @param uri Uri to tag for this slice.
         */
        public Builder(@NonNull Uri uri) {
            mUri = uri;
        }

        /**
         * 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();
        }

        /**
         * Add hints to the Slice being constructed
         */
        public Builder addHints(@SliceHint String... hints) {
            mHints.addAll(Arrays.asList(hints));
            return this;
        }

        /**
         * Add a sub-slice to the slice being constructed
         */
        public Builder addSubSlice(@NonNull Slice slice) {
            mItems.add(new SliceItem(slice, TYPE_SLICE, slice.getHints()));
            return this;
        }

        /**
         * Add an action to the slice being constructed
         */
        public Slice.Builder addAction(@NonNull PendingIntent action, @NonNull Slice s) {
            mItems.add(new SliceItem(action, s, TYPE_ACTION, new String[0]));
            return this;
        }

        /**
         * Add text to the slice being constructed
         */
        public Builder addText(CharSequence text, @SliceHint String... hints) {
            mItems.add(new SliceItem(text, TYPE_TEXT, hints));
            return this;
        }

        /**
         * Add an image to the slice being constructed
         */
        public Builder addIcon(Icon icon, @SliceHint String... hints) {
            mItems.add(new SliceItem(icon, TYPE_IMAGE, hints));
            return this;
        }

        /**
         * @hide This isn't final
         */
        public Builder addRemoteView(RemoteViews remoteView, @SliceHint String... hints) {
            mItems.add(new SliceItem(remoteView, TYPE_REMOTE_VIEW, hints));
            return this;
        }

        /**
         * Add remote input to the slice being constructed
         */
        public Slice.Builder addRemoteInput(RemoteInput remoteInput, @SliceHint String... hints) {
            mItems.add(new SliceItem(remoteInput, TYPE_REMOTE_INPUT, hints));
            return this;
        }

        /**
         * Add a color to the slice being constructed
         */
        public Builder addColor(int color, @SliceHint String... hints) {
            mItems.add(new SliceItem(color, TYPE_COLOR, hints));
            return this;
        }

        /**
         * Add a timestamp to the slice being constructed
         */
        public Slice.Builder addTimestamp(long time, @SliceHint String... hints) {
            mItems.add(new SliceItem(time, TYPE_TIMESTAMP, hints));
            return this;
        }

        /**
         * Construct the slice.
         */
        public Slice build() {
            return new Slice(mItems, mHints.toArray(new String[mHints.size()]), mUri);
        }
    }

    public static final 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 getString() {
        return getString("");
    }

    private String getString(String indent) {
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < mItems.length; i++) {
            sb.append(indent);
            if (mItems[i].getType() == TYPE_SLICE) {
                sb.append("slice:\n");
                sb.append(mItems[i].getSlice().getString(indent + "   "));
            } else if (mItems[i].getType() == TYPE_TEXT) {
                sb.append("text: ");
                sb.append(mItems[i].getText());
                sb.append("\n");
            } else {
                sb.append(SliceItem.typeToString(mItems[i].getType()));
                sb.append("\n");
            }
        }
        return sb.toString();
    }
}