GuidedAction.java revision ebd3d9078dbaebd10a9506ca086435eb63e8a2d2 
1/*
2 * Copyright (C) 2015 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.content.Context;
17import android.content.Intent;
18import android.graphics.drawable.Drawable;
19import android.util.Log;
20
21/**
22 * A data class which represents an action within a {@link
23 * android.support.v17.leanback.app.GuidedStepFragment}. GuidedActions contain at minimum a title
24 * and a description, and typically also an icon.
25 * <p>
26 * A GuidedAction typically represents a single action a user may take, but may also represent a
27 * possible choice out of a group of mutually exclusive choices (similar to radio buttons), or an
28 * information-only label (in which case the item cannot be clicked).
29 * <p>
30 * GuidedActions may optionally be checked. They may also indicate that they will request further
31 * user input on selection, in which case they will be displayed with a chevron indicator.
32 */
33public class GuidedAction extends Action {
34
35    private static final String TAG = "GuidedAction";
36
37    public static final int NO_DRAWABLE = 0;
38    public static final int NO_CHECK_SET = 0;
39    public static final int DEFAULT_CHECK_SET_ID = 1;
40
41    /**
42     * Builds a {@link GuidedAction} object.
43     */
44    public static class Builder {
45        private long mId;
46        private String mTitle;
47        private String mDescription;
48        private Drawable mIcon;
49        private boolean mChecked;
50        private boolean mMultilineDescription;
51        private boolean mHasNext;
52        private boolean mInfoOnly;
53        private int mCheckSetId = NO_CHECK_SET;
54        private boolean mEnabled = true;
55        private Intent mIntent;
56
57        /**
58         * Builds the GuidedAction corresponding to this Builder.
59         * @return the GuidedAction as configured through this Builder.
60         */
61        public GuidedAction build() {
62            GuidedAction action = new GuidedAction();
63            // Base Action values
64            action.setId(mId);
65            action.setLabel1(mTitle);
66            action.setLabel2(mDescription);
67            action.setIcon(mIcon);
68
69            // Subclass values
70            action.mIntent = mIntent;
71            action.mChecked = mChecked;
72            action.mCheckSetId = mCheckSetId;
73            action.mMultilineDescription = mMultilineDescription;
74            action.mHasNext = mHasNext;
75            action.mInfoOnly = mInfoOnly;
76            action.mEnabled = mEnabled;
77            return action;
78        }
79
80        /**
81         * Sets the ID associated with this action.  The ID can be any value the client wishes;
82         * it is typically used to determine what to do when an action is clicked.
83         * @param id The ID to associate with this action.
84         */
85        public Builder id(long id) {
86            mId = id;
87            return this;
88        }
89
90        /**
91         * Sets the title for this action.  The title is typically a short string indicating the
92         * action to be taken on click, e.g. "Continue" or "Cancel".
93         * @param title The title for this action.
94         */
95        public Builder title(String title) {
96            mTitle = title;
97            return this;
98        }
99
100        /**
101         * Sets the description for this action.  The description is typically a longer string
102         * providing extra information on what the action will do.
103         * @param description The description for this action.
104         */
105        public Builder description(String description) {
106            mDescription = description;
107            return this;
108        }
109
110        /**
111         * Sets the intent associated with this action.  Clients would typically fire this intent
112         * directly when the action is clicked.
113         * @param intent The intent associated with this action.
114         */
115        public Builder intent(Intent intent) {
116            mIntent = intent;
117            return this;
118        }
119
120        /**
121         * Sets the action's icon drawable.
122         * @param icon The drawable for the icon associated with this action.
123         */
124        public Builder icon(Drawable icon) {
125            mIcon = icon;
126            return this;
127        }
128
129        /**
130         * Sets the action's icon drawable by retrieving it by resource ID from the specified
131         * context. This is a convenience function that simply looks up the drawable and calls
132         * {@link #icon}.
133         * @param iconResourceId The resource ID for the icon associated with this action.
134         * @param context The context whose resource ID should be retrieved.
135         */
136        public Builder iconResourceId(int iconResourceId, Context context) {
137            return icon(context.getResources().getDrawable(iconResourceId));
138        }
139
140        /**
141         * Indicates whether this action is initially checked.
142         * @param checked Whether this action is checked.
143         */
144        public Builder checked(boolean checked) {
145            mChecked = checked;
146            return this;
147        }
148
149        /**
150         * Indicates whether this action is part of a single-select group similar to radio buttons.
151         * When one item in a check set is checked, all others with the same check set ID will be
152         * unchecked automatically.
153         * @param checkSetId The check set ID, or {@link #NO_CHECK_SET) to indicate no check set.
154         */
155        public Builder checkSetId(int checkSetId) {
156            mCheckSetId = checkSetId;
157            return this;
158        }
159
160        /**
161         * Indicates whether the title and description are long, and should be displayed
162         * appropriately.
163         * @param multilineDescription Whether this action has a multiline description.
164         */
165        public Builder multilineDescription(boolean multilineDescription) {
166            mMultilineDescription = multilineDescription;
167            return this;
168        }
169
170        /**
171         * Indicates whether this action has a next state and should display a chevron.
172         * @param hasNext Whether this action has a next state.
173         */
174        public Builder hasNext(boolean hasNext) {
175            mHasNext = hasNext;
176            return this;
177        }
178
179        /**
180         * Indicates whether this action is for information purposes only and cannot be clicked.
181         * @param infoOnly Whether this action has a next state.
182         */
183        public Builder infoOnly(boolean infoOnly) {
184            mInfoOnly = infoOnly;
185            return this;
186        }
187
188        /**
189         * Indicates whether this action is enabled.  If not enabled, an action cannot be clicked.
190         * @param enabled Whether the action is enabled.
191         */
192        public Builder enabled(boolean enabled) {
193            mEnabled = enabled;
194            return this;
195        }
196    }
197
198    private boolean mChecked;
199    private boolean mMultilineDescription;
200    private boolean mHasNext;
201    private boolean mInfoOnly;
202    private int mCheckSetId;
203    private boolean mEnabled;
204
205    private Intent mIntent;
206
207    private GuidedAction() {
208        super(0);
209    }
210
211    /**
212     * Returns the title of this action.
213     * @return The title set when this action was built.
214     */
215    public CharSequence getTitle() {
216        return getLabel1();
217    }
218
219    /**
220     * Returns the description of this action.
221     * @return The description set when this action was built.
222     */
223    public CharSequence getDescription() {
224        return getLabel2();
225    }
226
227    /**
228     * Returns the intent associated with this action.
229     * @return The intent set when this action was built.
230     */
231    public Intent getIntent() {
232        return mIntent;
233    }
234
235    /**
236     * Returns whether this action is checked.
237     * @return true if the action is currently checked, false otherwise.
238     */
239    public boolean isChecked() {
240        return mChecked;
241    }
242
243    /**
244     * Sets whether this action is checked.
245     * @param checked Whether this action should be checked.
246     */
247    public void setChecked(boolean checked) {
248        mChecked = checked;
249    }
250
251    /**
252     * Returns the check set id this action is a part of. All actions in the
253     * same list with the same check set id are considered linked. When one
254     * of the actions within that set is selected, that action becomes
255     * checked, while all the other actions become unchecked.
256     *
257     * @return an integer representing the check set this action is a part of, or
258     *         {@link #NO_CHECK_SET} if this action isn't a part of a check set.
259     */
260    public int getCheckSetId() {
261        return mCheckSetId;
262    }
263
264    /**
265     * Returns whether this action is has a multiline description.
266     * @return true if the action was constructed as having a multiline description, false
267     * otherwise.
268     */
269    public boolean hasMultilineDescription() {
270        return mMultilineDescription;
271    }
272
273    /**
274     * Returns whether this action is enabled.
275     * @return true if the action is currently enabled, false otherwise.
276     */
277    public boolean isEnabled() {
278        return mEnabled;
279    }
280
281    /**
282     * Sets whether this action is enabled.
283     * @param enabled Whether this action should be enabled.
284     */
285    public void setEnabled(boolean enabled) {
286        mEnabled = enabled;
287    }
288
289    /**
290     * Returns whether this action will request further user input when selected, such as showing
291     * another GuidedStepFragment or launching a new activity. Configured during construction.
292     * @return true if the action will request further user input when selected, false otherwise.
293     */
294    public boolean hasNext() {
295        return mHasNext;
296    }
297
298    /**
299     * Returns whether the action will only display information and is thus not clickable. If both
300     * this and {@link #hasNext()} are true, infoOnly takes precedence. The default is false. For
301     * example, this might represent e.g. the amount of storage a document uses, or the cost of an
302     * app.
303     * @return true if will only display information, false otherwise.
304     */
305    public boolean infoOnly() {
306        return mInfoOnly;
307    }
308
309}
310