1 /**
2 * @file lv_list.h
3 *
4 */
5
6 #ifndef LV_LIST_H
7 #define LV_LIST_H
8
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12
13 /*********************
14 * INCLUDES
15 *********************/
16 #include "../lv_conf_internal.h"
17
18 #if LV_USE_LIST != 0
19
20 /*Testing of dependencies*/
21 #if LV_USE_PAGE == 0
22 #error "lv_list: lv_page is required. Enable it in lv_conf.h (LV_USE_PAGE 1) "
23 #endif
24
25 #if LV_USE_BTN == 0
26 #error "lv_list: lv_btn is required. Enable it in lv_conf.h (LV_USE_BTN 1) "
27 #endif
28
29 #if LV_USE_LABEL == 0
30 #error "lv_list: lv_label is required. Enable it in lv_conf.h (LV_USE_LABEL 1) "
31 #endif
32
33 #include "../lv_core/lv_obj.h"
34 #include "lv_page.h"
35 #include "lv_btn.h"
36 #include "lv_label.h"
37 #include "lv_img.h"
38
39 /*********************
40 * DEFINES
41 *********************/
42
43 /**********************
44 * TYPEDEFS
45 **********************/
46 /*Data of list*/
47 typedef struct {
48 lv_page_ext_t page; /*Ext. of ancestor*/
49 /*New data for this type */
50
51 #if LV_USE_GROUP
52 lv_obj_t * last_sel_btn; /* The last selected button. It will be reverted when the list is focused again */
53 #endif
54 lv_obj_t * act_sel_btn; /* The button is currently being selected*/
55 } lv_list_ext_t;
56
57 /** List styles. */
58 enum {
59 LV_LIST_PART_BG = LV_PAGE_PART_BG, /**< List background style */
60 LV_LIST_PART_SCROLLBAR = LV_PAGE_PART_SCROLLBAR, /**< List scrollbar style. */
61 LV_LIST_PART_EDGE_FLASH = LV_PAGE_PART_EDGE_FLASH, /**< List edge flash style. */
62 _LV_LIST_PART_VIRTUAL_LAST = _LV_PAGE_PART_VIRTUAL_LAST,
63 LV_LIST_PART_SCROLLABLE = LV_PAGE_PART_SCROLLABLE, /**< List scrollable area style. */
64 _LV_LIST_PART_REAL_LAST = _LV_PAGE_PART_REAL_LAST,
65 };
66 typedef uint8_t lv_list_style_t;
67
68 /**********************
69 * GLOBAL PROTOTYPES
70 **********************/
71
72 /**
73 * Create a list objects
74 * @param par pointer to an object, it will be the parent of the new list
75 * @param copy pointer to a list object, if not NULL then the new object will be copied from it
76 * @return pointer to the created list
77 */
78 lv_obj_t * lv_list_create(lv_obj_t * par, const lv_obj_t * copy);
79
80 /**
81 * Delete all children of the scrl object, without deleting scrl child.
82 * @param list pointer to an object
83 */
84 void lv_list_clean(lv_obj_t * list);
85
86 /*======================
87 * Add/remove functions
88 *=====================*/
89
90 /**
91 * Add a list element to the list
92 * @param list pointer to list object
93 * @param img_fn file name of an image before the text (NULL if unused)
94 * @param txt text of the list element (NULL if unused)
95 * @return pointer to the new list element which can be customized (a button)
96 */
97 lv_obj_t * lv_list_add_btn(lv_obj_t * list, const void * img_src, const char * txt);
98
99 /**
100 * Remove the index of the button in the list
101 * @param list pointer to a list object
102 * @param index pointer to a the button's index in the list, index must be 0 <= index <
103 * lv_list_ext_t.size
104 * @return true: successfully deleted
105 */
106 bool lv_list_remove(const lv_obj_t * list, uint16_t index);
107
108 /*=====================
109 * Setter functions
110 *====================*/
111
112 /**
113 * Make a button selected
114 * @param list pointer to a list object
115 * @param btn pointer to a button to select
116 * NULL to not select any buttons
117 */
118 void lv_list_focus_btn(lv_obj_t * list, lv_obj_t * btn);
119
120 /**
121 * Set the scroll bar mode of a list
122 * @param list pointer to a list object
123 * @param sb_mode the new mode from 'lv_page_sb_mode_t' enum
124 */
lv_list_set_scrollbar_mode(lv_obj_t * list,lv_scrollbar_mode_t mode)125 static inline void lv_list_set_scrollbar_mode(lv_obj_t * list, lv_scrollbar_mode_t mode)
126 {
127 lv_page_set_scrollbar_mode(list, mode);
128 }
129
130 /**
131 * Enable the scroll propagation feature. If enabled then the List will move its parent if there is
132 * no more space to scroll.
133 * @param list pointer to a List
134 * @param en true or false to enable/disable scroll propagation
135 */
lv_list_set_scroll_propagation(lv_obj_t * list,bool en)136 static inline void lv_list_set_scroll_propagation(lv_obj_t * list, bool en)
137 {
138 lv_page_set_scroll_propagation(list, en);
139 }
140
141 /**
142 * Enable the edge flash effect. (Show an arc when the an edge is reached)
143 * @param list pointer to a List
144 * @param en true or false to enable/disable end flash
145 */
lv_list_set_edge_flash(lv_obj_t * list,bool en)146 static inline void lv_list_set_edge_flash(lv_obj_t * list, bool en)
147 {
148 lv_page_set_edge_flash(list, en);
149 }
150
151 /**
152 * Set scroll animation duration on 'list_up()' 'list_down()' 'list_focus()'
153 * @param list pointer to a list object
154 * @param anim_time duration of animation [ms]
155 */
lv_list_set_anim_time(lv_obj_t * list,uint16_t anim_time)156 static inline void lv_list_set_anim_time(lv_obj_t * list, uint16_t anim_time)
157 {
158 lv_page_set_anim_time(list, anim_time);
159 }
160
161 /**
162 * Set layout of a list
163 * @param list pointer to a list object
164 * @param layout which layout should be used
165 */
166 void lv_list_set_layout(lv_obj_t * list, lv_layout_t layout);
167
168 /*=====================
169 * Getter functions
170 *====================*/
171
172 /**
173 * Get the text of a list element
174 * @param btn pointer to list element
175 * @return pointer to the text
176 */
177 const char * lv_list_get_btn_text(const lv_obj_t * btn);
178 /**
179 * Get the label object from a list element
180 * @param btn pointer to a list element (button)
181 * @return pointer to the label from the list element or NULL if not found
182 */
183 lv_obj_t * lv_list_get_btn_label(const lv_obj_t * btn);
184
185 /**
186 * Get the image object from a list element
187 * @param btn pointer to a list element (button)
188 * @return pointer to the image from the list element or NULL if not found
189 */
190 lv_obj_t * lv_list_get_btn_img(const lv_obj_t * btn);
191
192 /**
193 * Get the next button from list. (Starts from the bottom button)
194 * @param list pointer to a list object
195 * @param prev_btn pointer to button. Search the next after it.
196 * @return pointer to the next button or NULL when no more buttons
197 */
198 lv_obj_t * lv_list_get_prev_btn(const lv_obj_t * list, lv_obj_t * prev_btn);
199
200 /**
201 * Get the previous button from list. (Starts from the top button)
202 * @param list pointer to a list object
203 * @param prev_btn pointer to button. Search the previous before it.
204 * @return pointer to the previous button or NULL when no more buttons
205 */
206 lv_obj_t * lv_list_get_next_btn(const lv_obj_t * list, lv_obj_t * prev_btn);
207
208 /**
209 * Get the index of the button in the list
210 * @param list pointer to a list object. If NULL, assumes btn is part of a list.
211 * @param btn pointer to a list element (button)
212 * @return the index of the button in the list, or -1 of the button not in this list
213 */
214 int32_t lv_list_get_btn_index(const lv_obj_t * list, const lv_obj_t * btn);
215
216 /**
217 * Get the number of buttons in the list
218 * @param list pointer to a list object
219 * @return the number of buttons in the list
220 */
221 uint16_t lv_list_get_size(const lv_obj_t * list);
222
223 #if LV_USE_GROUP
224 /**
225 * Get the currently selected button. Can be used while navigating in the list with a keypad.
226 * @param list pointer to a list object
227 * @return pointer to the selected button
228 */
229 lv_obj_t * lv_list_get_btn_selected(const lv_obj_t * list);
230 #endif
231
232 /**
233 * Get layout of a list
234 * @param list pointer to a list object
235 * @return layout of the list object
236 */
237 lv_layout_t lv_list_get_layout(lv_obj_t * list);
238
239 /**
240 * Get the scroll bar mode of a list
241 * @param list pointer to a list object
242 * @return scrollbar mode from 'lv_scrollbar_mode_t' enum
243 */
lv_list_get_scrollbar_mode(const lv_obj_t * list)244 static inline lv_scrollbar_mode_t lv_list_get_scrollbar_mode(const lv_obj_t * list)
245 {
246 return lv_page_get_scrollbar_mode(list);
247 }
248
249 /**
250 * Get the scroll propagation property
251 * @param list pointer to a List
252 * @return true or false
253 */
lv_list_get_scroll_propagation(lv_obj_t * list)254 static inline bool lv_list_get_scroll_propagation(lv_obj_t * list)
255 {
256 return lv_page_get_scroll_propagation(list);
257 }
258
259 /**
260 * Get the scroll propagation property
261 * @param list pointer to a List
262 * @return true or false
263 */
lv_list_get_edge_flash(lv_obj_t * list)264 static inline bool lv_list_get_edge_flash(lv_obj_t * list)
265 {
266 return lv_page_get_edge_flash(list);
267 }
268
269 /**
270 * Get scroll animation duration
271 * @param list pointer to a list object
272 * @return duration of animation [ms]
273 */
lv_list_get_anim_time(const lv_obj_t * list)274 static inline uint16_t lv_list_get_anim_time(const lv_obj_t * list)
275 {
276 return lv_page_get_anim_time(list);
277 }
278
279 /*=====================
280 * Other functions
281 *====================*/
282
283 /**
284 * Move the list elements up by one
285 * @param list pointer a to list object
286 */
287 void lv_list_up(const lv_obj_t * list);
288 /**
289 * Move the list elements down by one
290 * @param list pointer to a list object
291 */
292 void lv_list_down(const lv_obj_t * list);
293
294 /**
295 * Focus on a list button. It ensures that the button will be visible on the list.
296 * @param btn pointer to a list button to focus
297 * @param anim LV_ANOM_ON: scroll with animation, LV_ANIM_OFF: without animation
298 */
299 void lv_list_focus(const lv_obj_t * btn, lv_anim_enable_t anim);
300
301 /**********************
302 * MACROS
303 **********************/
304
305 #endif /*LV_USE_LIST*/
306
307 #ifdef __cplusplus
308 } /* extern "C" */
309 #endif
310
311 #endif /*LV_LIST_H*/
312
