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  */
14 package android.support.v17.leanback.widget;
15 
16 import android.content.Context;
17 import android.content.Intent;
18 import android.graphics.drawable.Drawable;
19 import 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  */
33 public 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          */
build()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          */
id(long id)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          */
title(String title)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          */
description(String description)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          */
intent(Intent intent)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          */
icon(Drawable icon)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          */
iconResourceId(int iconResourceId, Context context)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          */
checked(boolean checked)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          */
checkSetId(int checkSetId)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          */
multilineDescription(boolean multilineDescription)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          */
hasNext(boolean hasNext)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          */
infoOnly(boolean infoOnly)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          */
enabled(boolean enabled)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 
GuidedAction()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      */
getTitle()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      */
getDescription()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      */
getIntent()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      */
isChecked()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      */
setChecked(boolean checked)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      */
getCheckSetId()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      */
hasMultilineDescription()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      */
isEnabled()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      */
setEnabled(boolean enabled)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      */
hasNext()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      */
infoOnly()305     public boolean infoOnly() {
306         return mInfoOnly;
307     }
308 
309 }
310