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