1/*
2 * Copyright (C) 2016 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5 * in compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License
10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11 * or implied. See the License for the specific language governing permissions and limitations under
12 * the License.
13 */
14package android.support.v17.leanback.widget;
15
16import android.graphics.drawable.Drawable;
17
18/**
19 * An interface implemented by the user if they wish to provide actions for a media item row to
20 * be displayed by an {@link AbstractMediaItemPresenter}.
21 *
22 * A media row consists of media item details together with a number of custom actions,
23 * following the media item details. Classes implementing {@link MultiActionsProvider} can define
24 * their own media data model within their derived classes.
25 * <p>
26 *     The actions are provided by overriding {@link MultiActionsProvider#getActions()}
27 *     Provided actions should be instances of {@link MultiAction}.
28 * </p>
29 */
30public interface MultiActionsProvider {
31
32    /**
33     * MultiAction represents an action that can have multiple states. {@link #getIndex()} returns
34     * the current index within the drawables. Both list of drawables and index can be updated
35     * dynamically in the program, and the UI could be updated by notifying the listeners
36     * provided in {@link AbstractMediaItemPresenter.ViewHolder}.
37     */
38    public static class MultiAction {
39        private long mId;
40        private int mIndex;
41        private Drawable[] mDrawables;
42
43        public MultiAction(long id) {
44            mId = id;
45            mIndex = 0;
46        }
47
48        /**
49         * Sets the drawables used for displaying different states within this {@link MultiAction}.
50         * The size of drawables determines the set of states this action represents.
51         * @param drawables Array of drawables for different MultiAction states.
52         */
53        public void setDrawables(Drawable[] drawables) {
54            mDrawables = drawables;
55            if (mIndex > drawables.length - 1) {
56                mIndex = drawables.length - 1;
57            }
58        }
59
60        /**
61         * Returns the drawables used for displaying different states within this
62         * {@link MultiAction}.
63         * @return The drawables used for displaying different states within this
64         *         {@link MultiAction}.
65         */
66        public Drawable[] getDrawables() {
67            return mDrawables;
68        }
69
70        /**
71         * Increments the index which this MultiAction currently represents. The index is wrapped
72         * around to zero when the end is reached.
73         */
74        public void incrementIndex() {
75            setIndex(mIndex < (mDrawables.length - 1) ? (mIndex + 1) : 0);
76        }
77
78        /**
79         * Sets the index which this MultiAction currently represents.
80         * @param index The current action index.
81         */
82        public void setIndex(int index) {
83            mIndex = index;
84        }
85
86        /**
87         * Returns the currently selected index in this MultiAction.
88         * @return The currently selected index in this MultiAction.
89         */
90        public int getIndex() {
91            return mIndex;
92        }
93
94        /**
95         * @return The icon drawable for the current state of this MultiAction.
96         */
97        public Drawable getCurrentDrawable() {
98            return mDrawables[mIndex];
99        }
100
101        /**
102         * @return The id for this MultiAction.
103         */
104        public long getId() {
105            return mId;
106        }
107    }
108
109    /**
110     * Should override this method in order to provide a custom set of actions for a media item row
111     * @return Array of MultiAction items to be displayed for this media item row.
112     */
113    public MultiAction[] getActions();
114}
115