1/*
2 * Copyright 2018 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package androidx.slice.builders.impl;
18
19import static androidx.annotation.RestrictTo.Scope.LIBRARY;
20
21import android.app.PendingIntent;
22import android.net.Uri;
23
24import androidx.annotation.ColorInt;
25import androidx.annotation.NonNull;
26import androidx.annotation.RestrictTo;
27import androidx.core.graphics.drawable.IconCompat;
28import androidx.slice.builders.SliceAction;
29
30import java.util.List;
31
32/**
33 * @hide
34 */
35@RestrictTo(LIBRARY)
36public interface ListBuilder {
37
38    /**
39     * Add a row to list builder.
40     */
41    void addRow(TemplateBuilderImpl impl);
42    /**
43     * Add a grid row to the list builder.
44     */
45    void addGridRow(TemplateBuilderImpl impl);
46
47    /**
48     * Adds a header to this template.
49     * <p>
50     * The header should contain a title that is representative of the content in this slice along
51     * with an intent that links to the app activity associated with this content.
52     */
53    void setHeader(TemplateBuilderImpl impl);
54
55    /**
56     * Adds an action to this template. Actions added with this method are grouped together and
57     * may be shown on the template in large or small formats.
58     */
59    void addAction(SliceAction action);
60
61    /**
62     * Add an input range row to the list builder.
63     */
64    void addInputRange(TemplateBuilderImpl builder);
65
66    /**
67     * Add a range row to the list builder.
68     */
69    void addRange(TemplateBuilderImpl builder);
70
71    /**
72     * If all content in a slice cannot be shown, the row added here will be displayed where the
73     * content is cut off. This row should have an affordance to take the user to an activity to
74     * see all of the content.
75     * <p>
76     * Only one see more affordance can be added, this throws {@link IllegalStateException} if
77     * a row or action has been previously added.
78     * </p>
79     */
80    void setSeeMoreRow(TemplateBuilderImpl builder);
81    /**
82     * If all content in a slice cannot be shown, a "see more" affordance will be displayed where
83     * the content is cut off. The action added here should take the user to an activity to see
84     * all of the content, and will be invoked when the "see more" affordance is tapped.
85     * <p>
86     * Only one see more affordance can be added, this throws {@link IllegalStateException} if
87     * a row or action has been previously added.
88     * </p>
89     */
90    void setSeeMoreAction(PendingIntent intent);
91
92    /**
93     * Sets the color to tint items displayed by this template (e.g. icons).
94     */
95    void setColor(@ColorInt int color);
96
97    /**
98     * Sets keywords to associate with this slice.
99     */
100    void setKeywords(List<String> keywords);
101
102    /**
103     * Sets the time-to-live for this slice, i.e. how long the data contained in the slice
104     * can remain fresh.
105     *
106     * @param ttl the length in milliseconds that this content can live for.
107     */
108    void setTtl(long ttl);
109
110    /**
111     * Create a builder that implements {@link RowBuilder}.
112     */
113    TemplateBuilderImpl createRowBuilder();
114    /**
115     * Create a builder that implements {@link RowBuilder}.
116     */
117    TemplateBuilderImpl createRowBuilder(Uri uri);
118    /**
119     * Create a builder that implements {@link GridRowBuilder}.
120     */
121    TemplateBuilderImpl createGridBuilder();
122    /**
123     * Create a builder that implements {@link HeaderBuilder}.
124     */
125    TemplateBuilderImpl createHeaderBuilder();
126    /**
127     * Create a builder that implements {@link HeaderBuilder}.
128     */
129    TemplateBuilderImpl createHeaderBuilder(Uri uri);
130    /**
131     * Create a builder that implements {@link InputRangeBuilder}.
132     */
133    TemplateBuilderImpl createInputRangeBuilder();
134    /**
135     * Create a builder that implements {@link RangeBuilder}.
136     */
137    TemplateBuilderImpl createRangeBuilder();
138
139    /**
140     * Builder to construct a range.
141     */
142    interface RangeBuilder {
143        /**
144         * Set the lower limit.
145         */
146        void setMin(int min);
147
148        /**
149         * Set the upper limit.
150         */
151        void setMax(int max);
152
153        /**
154         * Set the current value.
155         */
156        void setValue(int value);
157
158        /**
159         * Set the title.
160         */
161        void setTitle(@NonNull CharSequence title);
162
163        /**
164         * Set the subtitle.
165         */
166        void setSubtitle(@NonNull CharSequence title);
167
168        /**
169         * Set the primary action.
170         */
171        void setPrimaryAction(@NonNull SliceAction action);
172
173        /**
174         * Sets the content description.
175         */
176        void setContentDescription(CharSequence description);
177    }
178
179    /**
180     * Builder to construct an input range.
181     */
182    interface InputRangeBuilder extends RangeBuilder {
183        /**
184         * Set the {@link PendingIntent} to send when the value changes.
185         */
186        void setInputAction(@NonNull PendingIntent action);
187
188        /**
189         * Set the {@link IconCompat} to be displayed as the thumb on the input range.
190         */
191        void setThumb(@NonNull IconCompat thumb);
192    }
193
194    /**
195     */
196    interface RowBuilder {
197
198        /**
199         * Sets the title item to be the provided timestamp. Only one timestamp can be added, if
200         * one is already added this will throw {@link IllegalArgumentException}.
201         * <p>
202         * There can only be one title item, this will replace any other title
203         * items that may have been set.
204         */
205        void setTitleItem(long timeStamp);
206
207        /**
208         * Sets the title item to be the provided icon. There can only be one title item, this
209         * will replace any other title items that may have been set.
210         *  @param icon the image to display.
211         * @param imageMode the mode that image should be displayed in.
212         */
213        void setTitleItem(IconCompat icon, int imageMode);
214
215        /**
216         * Sets the title item to be the provided icon. There can only be one title item, this
217         * will replace any other title items that may have been set.
218         * <p>
219         * When set to true, the parameter {@code isLoading} indicates that the app is doing work
220         * to load this content in the background, in this case the template displays a placeholder
221         * until updated.
222         *  @param icon the image to display.
223         * @param imageMode the mode that image should be displayed in.
224         * @param isLoading whether this content is being loaded in the background.
225         */
226        void setTitleItem(IconCompat icon, int imageMode, boolean isLoading);
227
228        /**
229         * Sets the title item to be a tappable icon. There can only be one title item, this will
230         * replace any other title items that may have been set.
231         */
232        void setTitleItem(SliceAction action);
233
234        /**
235         * Sets the title item to be a tappable icon. There can only be one title item, this will
236         * replace any other title items that may have been set.
237         * <p>
238         * When set to true, the parameter {@code isLoading} indicates that the app is doing work
239         * to load this content in the background, in this case the template displays a placeholder
240         * until updated.
241         */
242        void setTitleItem(SliceAction action, boolean isLoading);
243
244        /**
245         * Sets the action to be invoked if the user taps on the main content of the template.
246         */
247        void setPrimaryAction(SliceAction action);
248
249        /**
250         * Sets the title text.
251         */
252        void setTitle(CharSequence title);
253
254        /**
255         * Sets the title text.
256         * <p>
257         * When set to true, the parameter {@code isLoading} indicates that the app is doing work
258         * to load this content in the background, in this case the template displays a placeholder
259         * until updated.
260         */
261        void setTitle(CharSequence title, boolean isLoading);
262
263        /**
264         * Sets the subtitle text.
265         */
266        void setSubtitle(CharSequence subtitle);
267
268        /**
269         * Sets the subtitle text.
270         * <p>
271         * When set to true, the parameter {@code isLoading} indicates that the app is doing work
272         * to load this content in the background, in this case the template displays a placeholder
273         * until updated.
274         */
275        void setSubtitle(CharSequence subtitle, boolean isLoading);
276
277        /**
278         * Adds a timestamp to be displayed at the end of the row.
279         */
280        void addEndItem(long timeStamp);
281
282        /**
283         * Adds an icon to be displayed at the end of the row.
284         *  @param icon the image to display.
285         * @param imageMode the mode that image should be displayed in.
286         */
287        void addEndItem(IconCompat icon, int imageMode);
288
289        /**
290         * Adds an icon to be displayed at the end of the row.
291         * <p>
292         * When set to true, the parameter {@code isLoading} indicates that the app is doing work
293         * to load this content in the background, in this case the template displays a placeholder
294         * until updated.
295         *  @param icon the image to display.
296         * @param imageMode the mode that image should be displayed in.
297         * @param isLoading whether this content is being loaded in the background.
298         */
299        void addEndItem(IconCompat icon, int imageMode, boolean isLoading);
300
301        /**
302         * Adds a tappable icon to be displayed at the end of the row.
303         */
304        void addEndItem(SliceAction action);
305
306        /**
307         * Adds a tappable icon to be displayed at the end of the row.
308         * <p>
309         * When set to true, the parameter {@code isLoading} indicates that the app is doing work
310         * to load this content in the background, in this case the template displays a placeholder
311         * until updated.
312         */
313        void addEndItem(SliceAction action, boolean isLoading);
314
315        /**
316         * Sets the content description for this row.
317         */
318        void setContentDescription(CharSequence description);
319    }
320
321
322    /**
323     * Builder to construct a header. A header is displayed at the top of a list and can have
324     * a title, subtitle, and an action.
325     */
326    public interface HeaderBuilder {
327
328        /**
329         * Sets the title to be shown in this header.
330         */
331        void setTitle(CharSequence title, boolean isLoading);
332
333        /**
334         * Sets the subtitle to be shown in this header.
335         */
336        void setSubtitle(CharSequence subtitle, boolean isLoading);
337
338        /**
339         * Sets the summary subtitle to be shown in this header. If unset, the normal subtitle
340         * will be used. The summary is used when the parent template is presented in a
341         * small format.
342         */
343        void setSummary(CharSequence summarySubtitle, boolean isLoading);
344
345        /**
346         * Sets the action to invoke when the header is activated.
347         */
348        void setPrimaryAction(SliceAction action);
349
350        /**
351         * Sets the content description for the header.
352         */
353        void setContentDescription(CharSequence description);
354    }
355}
356
357