| /* |
| * Copyright 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 androidx.slice; |
| |
| import static android.app.slice.Slice.HINT_ACTIONS; |
| import static android.app.slice.Slice.HINT_PARTIAL; |
| import static android.app.slice.Slice.HINT_SHORTCUT; |
| import static android.app.slice.SliceItem.FORMAT_ACTION; |
| import static android.app.slice.SliceItem.FORMAT_IMAGE; |
| import static android.app.slice.SliceItem.FORMAT_REMOTE_INPUT; |
| import static android.app.slice.SliceItem.FORMAT_SLICE; |
| import static android.app.slice.SliceItem.FORMAT_TEXT; |
| |
| import static androidx.slice.SliceMetadata.LOADED_ALL; |
| import static androidx.slice.SliceMetadata.LOADED_NONE; |
| import static androidx.slice.SliceMetadata.LOADED_PARTIAL; |
| import static androidx.slice.core.SliceHints.HINT_KEYWORDS; |
| |
| import static java.lang.annotation.RetentionPolicy.SOURCE; |
| |
| import android.content.Context; |
| import android.net.Uri; |
| import android.text.TextUtils; |
| |
| import androidx.annotation.IntDef; |
| import androidx.annotation.NonNull; |
| import androidx.annotation.Nullable; |
| import androidx.annotation.RestrictTo; |
| import androidx.slice.core.SliceQuery; |
| |
| import java.io.IOException; |
| import java.io.InputStream; |
| import java.io.OutputStream; |
| import java.lang.annotation.Retention; |
| import java.util.ArrayList; |
| import java.util.List; |
| |
| /** |
| * Utilities for dealing with slices. |
| */ |
| public class SliceUtils { |
| |
| private SliceUtils() { |
| } |
| |
| /** |
| * Serialize a slice to an OutputStream. |
| * <p> |
| * The slice can later be read into slice form again with {@link #parseSlice}. |
| * Some slice types cannot be serialized, their handling is controlled by |
| * {@link SerializeOptions}. |
| * |
| * @param s The slice to serialize. |
| * @param context Context used to load any resources in the slice. |
| * @param output The output of the serialization. |
| * @param encoding The encoding to use for serialization. |
| * @param options Options defining how to handle non-serializable items. |
| * @throws IllegalArgumentException if the slice cannot be serialized using the given options. |
| */ |
| public static void serializeSlice(@NonNull Slice s, @NonNull Context context, |
| @NonNull OutputStream output, @NonNull String encoding, |
| @NonNull SerializeOptions options) throws IOException, IllegalArgumentException { |
| SliceXml.serializeSlice(s, context, output, encoding, options); |
| } |
| |
| /** |
| * Parse a slice that has been previously serialized. |
| * <p> |
| * Parses a slice that was serialized with {@link #serializeSlice}. |
| * <p> |
| * Note: Slices returned by this cannot be passed to {@link SliceConvert#unwrap(Slice)}. |
| * |
| * @param input The input stream to read from. |
| * @param encoding The encoding to read as. |
| * @param listener Listener used to handle actions when reconstructing the slice. |
| * @throws SliceParseException if the InputStream cannot be parsed. |
| */ |
| public static @NonNull Slice parseSlice(@NonNull Context context, @NonNull InputStream input, |
| @NonNull String encoding, @NonNull SliceActionListener listener) |
| throws IOException, SliceParseException { |
| return SliceXml.parseSlice(context, input, encoding, listener); |
| } |
| |
| /** |
| * Holds options for how to handle SliceItems that cannot be serialized. |
| */ |
| public static class SerializeOptions { |
| /** |
| * Constant indicating that the an {@link IllegalArgumentException} should be thrown |
| * when this format is encountered. |
| */ |
| public static final int MODE_THROW = 0; |
| /** |
| * Constant indicating that the SliceItem should be removed when this format is encountered. |
| */ |
| public static final int MODE_REMOVE = 1; |
| /** |
| * Constant indicating that the SliceItem should be serialized as much as possible. |
| * <p> |
| * For images this means they will be attempted to be serialized. For actions, the |
| * action will be removed but the content of the action will be serialized. The action |
| * may be triggered later on a de-serialized slice by binding the slice again and activating |
| * a pending-intent at the same location as the serialized action. |
| */ |
| public static final int MODE_CONVERT = 2; |
| |
| @IntDef({MODE_THROW, MODE_REMOVE, MODE_CONVERT}) |
| @Retention(SOURCE) |
| @interface FormatMode { |
| } |
| |
| private int mActionMode = MODE_THROW; |
| private int mImageMode = MODE_THROW; |
| private int mMaxWidth = 1000; |
| private int mMaxHeight = 1000; |
| |
| /** |
| * @hide |
| */ |
| @RestrictTo(RestrictTo.Scope.LIBRARY) |
| public void checkThrow(String format) { |
| switch (format) { |
| case FORMAT_ACTION: |
| case FORMAT_REMOTE_INPUT: |
| if (mActionMode != MODE_THROW) return; |
| break; |
| case FORMAT_IMAGE: |
| if (mImageMode != MODE_THROW) return; |
| break; |
| default: |
| return; |
| } |
| throw new IllegalArgumentException(format + " cannot be serialized"); |
| } |
| |
| /** |
| * @hide |
| */ |
| @RestrictTo(RestrictTo.Scope.LIBRARY) |
| public @FormatMode int getActionMode() { |
| return mActionMode; |
| } |
| |
| /** |
| * @hide |
| */ |
| @RestrictTo(RestrictTo.Scope.LIBRARY) |
| public @FormatMode int getImageMode() { |
| return mImageMode; |
| } |
| |
| /** |
| * @hide |
| */ |
| @RestrictTo(RestrictTo.Scope.LIBRARY) |
| public int getMaxWidth() { |
| return mMaxWidth; |
| } |
| |
| /** |
| * @hide |
| */ |
| @RestrictTo(RestrictTo.Scope.LIBRARY) |
| public int getMaxHeight() { |
| return mMaxHeight; |
| } |
| |
| /** |
| * Sets how {@link android.app.slice.SliceItem#FORMAT_ACTION} items should be handled. |
| * |
| * The default mode is {@link #MODE_THROW}. |
| * @param mode The desired mode. |
| */ |
| public SerializeOptions setActionMode(@FormatMode int mode) { |
| mActionMode = mode; |
| return this; |
| } |
| |
| /** |
| * Sets how {@link android.app.slice.SliceItem#FORMAT_IMAGE} items should be handled. |
| * |
| * The default mode is {@link #MODE_THROW}. |
| * @param mode The desired mode. |
| */ |
| public SerializeOptions setImageMode(@FormatMode int mode) { |
| mImageMode = mode; |
| return this; |
| } |
| |
| /** |
| * Set the maximum width of an image to use when serializing. |
| * <p> |
| * Will only be used if the {@link #setImageMode(int)} is set to {@link #MODE_CONVERT}. |
| * Any images larger than the maximum size will be scaled down to fit within that size. |
| * The default value is 1000. |
| */ |
| public SerializeOptions setMaxImageWidth(int width) { |
| mMaxWidth = width; |
| return this; |
| } |
| |
| /** |
| * Set the maximum height of an image to use when serializing. |
| * <p> |
| * Will only be used if the {@link #setImageMode(int)} is set to {@link #MODE_CONVERT}. |
| * Any images larger than the maximum size will be scaled down to fit within that size. |
| * The default value is 1000. |
| */ |
| public SerializeOptions setMaxImageHeight(int height) { |
| mMaxHeight = height; |
| return this; |
| } |
| } |
| |
| /** |
| * Indicates this slice is empty and waiting for content to be loaded. |
| * |
| * @deprecated TO BE REMOVED: use {@link SliceMetadata#LOADED_NONE} |
| */ |
| @Deprecated |
| public static final int LOADING_ALL = 0; |
| /** |
| * Indicates this slice has some content but is waiting for other content to be loaded. |
| * |
| * @deprecated TO BE REMOVED: use {@link SliceMetadata#LOADED_PARTIAL} |
| */ |
| @Deprecated |
| public static final int LOADING_PARTIAL = 1; |
| /** |
| * Indicates this slice has fully loaded and is not waiting for other content. |
| * |
| * @deprecated TO BE REMOVED: use {@link SliceMetadata#LOADED_ALL} |
| */ |
| @Deprecated |
| public static final int LOADING_COMPLETE = 2; |
| |
| /** |
| * @return the current loading state of the provided {@link Slice}. |
| * |
| * @deprecated TO BE REMOVED: use {@link SliceMetadata#getLoadingState()} |
| */ |
| @Deprecated |
| public static int getLoadingState(@NonNull Slice slice) { |
| // Check loading state |
| boolean hasHintPartial = |
| SliceQuery.find(slice, null, HINT_PARTIAL, null) != null; |
| if (slice.getItems().size() == 0) { |
| // Empty slice |
| return LOADED_NONE; |
| } else if (hasHintPartial) { |
| // Slice with specific content to load |
| return LOADED_PARTIAL; |
| } else { |
| // Full slice |
| return LOADED_ALL; |
| } |
| } |
| |
| /** |
| * @return the group of actions associated with the provided slice, if they exist. |
| * |
| * @deprecated TO BE REMOVED; use {@link SliceMetadata#getSliceActions()} |
| */ |
| @Deprecated |
| @Nullable |
| public static List<SliceItem> getSliceActions(@NonNull Slice slice) { |
| SliceItem actionGroup = SliceQuery.find(slice, FORMAT_SLICE, HINT_ACTIONS, null); |
| String[] hints = new String[] {HINT_ACTIONS, HINT_SHORTCUT}; |
| return (actionGroup != null) |
| ? SliceQuery.findAll(actionGroup, FORMAT_SLICE, hints, null) |
| : null; |
| } |
| |
| /** |
| * @return the list of keywords associated with the provided slice, null if no keywords were |
| * specified or an empty list if the slice was specified to have no keywords. |
| * |
| * @deprecated TO BE REMOVED; use {@link SliceMetadata#getSliceKeywords()} |
| */ |
| @Deprecated |
| @Nullable |
| public static List<String> getSliceKeywords(@NonNull Slice slice) { |
| SliceItem keywordGroup = SliceQuery.find(slice, FORMAT_SLICE, HINT_KEYWORDS, null); |
| if (keywordGroup != null) { |
| List<SliceItem> itemList = SliceQuery.findAll(keywordGroup, FORMAT_TEXT); |
| if (itemList != null) { |
| ArrayList<String> stringList = new ArrayList<>(); |
| for (int i = 0; i < itemList.size(); i++) { |
| String keyword = (String) itemList.get(i).getText(); |
| if (!TextUtils.isEmpty(keyword)) { |
| stringList.add(keyword); |
| } |
| } |
| return stringList; |
| } |
| } |
| return null; |
| } |
| |
| /** |
| * A listener used to receive events on slices parsed with |
| * {@link #parseSlice(Context, InputStream, String, SliceActionListener)}. |
| */ |
| public interface SliceActionListener { |
| /** |
| * Called when an action is triggered on a slice parsed with |
| * {@link #parseSlice(Context, InputStream, String, SliceActionListener)}. |
| * @param actionUri The uri of the action selected. |
| */ |
| void onSliceAction(Uri actionUri); |
| } |
| |
| /** |
| * Exception thrown during |
| * {@link #parseSlice(Context, InputStream, String, SliceActionListener)}. |
| */ |
| public static class SliceParseException extends Exception { |
| /** |
| * @hide |
| */ |
| @RestrictTo(RestrictTo.Scope.LIBRARY) |
| public SliceParseException(String s, Throwable e) { |
| super(s, e); |
| } |
| |
| /** |
| * @hide |
| */ |
| @RestrictTo(RestrictTo.Scope.LIBRARY) |
| public SliceParseException(String s) { |
| super(s); |
| } |
| } |
| } |