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
#ifdef LV_CONF_INCLUDE_SIMPLE
17
#include "lv_conf.h"
18
#else
19
#include "../../lv_conf.h"
20
#endif
21

22
#if USE_LV_LIST != 0
23

24
/*Testing of dependencies*/
25
#if USE_LV_PAGE == 0
26
#error "lv_list: lv_page is required. Enable it in lv_conf.h (USE_LV_PAGE  1) "
27
#endif
28

29
#if USE_LV_BTN == 0
30
#error "lv_list: lv_btn is required. Enable it in lv_conf.h (USE_LV_BTN  1) "
31
#endif
32

33
#if USE_LV_LABEL == 0
34
#error "lv_list: lv_label is required. Enable it in lv_conf.h (USE_LV_LABEL  1) "
35
#endif
36

37

38
#include "../lv_core/lv_obj.h"
39
#include "lv_page.h"
40
#include "lv_btn.h"
41
#include "lv_label.h"
42
#include "lv_img.h"
43

44
/*********************
45
 *      DEFINES
46
 *********************/
47

48
/**********************
49
 *      TYPEDEFS
50
 **********************/
51
/*Data of list*/
52
typedef struct
53
{
54
    lv_page_ext_t page; /*Ext. of ancestor*/
55
    /*New data for this type */
56
    uint16_t anim_time;                          /*Scroll animation time*/
57
    lv_style_t *styles_btn[LV_BTN_STATE_NUM];    /*Styles of the list element buttons*/
58
    lv_style_t *style_img;                       /*Style of the list element images on buttons*/
59
    uint32_t size; /*the number of items(buttons) in the list*/
60
    bool single_mode; /* whether single selected mode is enabled */
61
#if USE_LV_GROUP
62
    lv_obj_t * last_sel;                          /* The last selected button. It will be reverted when the list is focused again */
63
    lv_obj_t * selected_btn;                      /* The button is currently being selected*/
64
#endif
65
} lv_list_ext_t;
66

67
enum {
68
    LV_LIST_STYLE_BG,
69
    LV_LIST_STYLE_SCRL,
70
    LV_LIST_STYLE_SB,
71
    LV_LIST_STYLE_EDGE_FLASH,
72
    LV_LIST_STYLE_BTN_REL,
73
    LV_LIST_STYLE_BTN_PR,
74
    LV_LIST_STYLE_BTN_TGL_REL,
75
    LV_LIST_STYLE_BTN_TGL_PR,
76
    LV_LIST_STYLE_BTN_INA,
77
};
78
typedef uint8_t lv_list_style_t;
79

80

81
/**********************
82
 * GLOBAL PROTOTYPES
83
 **********************/
84

85
/**
86
 * Create a list objects
87
 * @param par pointer to an object, it will be the parent of the new list
88
 * @param copy pointer to a list object, if not NULL then the new object will be copied from it
89
 * @return pointer to the created list
90
 */
91
lv_obj_t * lv_list_create(lv_obj_t * par, const lv_obj_t * copy);
92

93
/**
94
 * Delete all children of the scrl object, without deleting scrl child.
95
 * @param obj pointer to an object
96
 */
97
void lv_list_clean(lv_obj_t *obj);
98

99
/*======================
100
 * Add/remove functions
101
 *=====================*/
102

103
/**
104
 * Add a list element to the list
105
 * @param list pointer to list object
106
 * @param img_fn file name of an image before the text (NULL if unused)
107
 * @param txt text of the list element (NULL if unused)
108
 * @param rel_action pointer to release action function (like with lv_btn)
109
 * @return pointer to the new list element which can be customized (a button)
110
 */
111
lv_obj_t * lv_list_add(lv_obj_t * list, const void * img_src, const char * txt, lv_action_t rel_action);
112

113
/**
114
 * Remove the index of the button in the list
115
 * @param list pointer to a list object
116
 * @param index pointer to a the button's index in the list, index must be 0 <= index < lv_list_ext_t.size
117
 * @return true: successfully deleted
118
 */
119
bool lv_list_remove(const lv_obj_t * list, uint32_t index);
120

121
/*=====================
122
 * Setter functions
123
 *====================*/
124

125
/**
126
 * Set single button selected mode, only one button will be selected if enabled.
127
 * @param list pointer to the currently pressed list object
128
 * @param mode, enable(true)/disable(false) single selected mode.
129
 */
130
void lv_list_set_single_mode(lv_obj_t *list, bool mode);
131

132
#if USE_LV_GROUP
133

134
/**
135
 * Make a button selected. Can be used while navigating in the list with a keypad.
136
 * @param list pointer to a list object
137
 * @param btn pointer to a button to select
138
 */
139
void lv_list_set_btn_selected(lv_obj_t * list, lv_obj_t * btn);
140
#endif
141

142
/**
143
 * Set scroll animation duration on 'list_up()' 'list_down()' 'list_focus()'
144
 * @param list pointer to a list object
145
 * @param anim_time duration of animation [ms]
146
 */
147
void lv_list_set_anim_time(lv_obj_t *list, uint16_t anim_time);
148

149
/**
150
 * Set the scroll bar mode of a list
151
 * @param list pointer to a list object
152
 * @param sb_mode the new mode from 'lv_page_sb_mode_t' enum
153
 */
154
static inline void lv_list_set_sb_mode(lv_obj_t * list, lv_sb_mode_t mode)
155
{
156
    lv_page_set_sb_mode(list, mode);
157
}
158

159
/**
160
 * Enable the scroll propagation feature. If enabled then the List will move its parent if there is no more space to scroll.
161
 * @param list pointer to a List
162
 * @param en true or false to enable/disable scroll propagation
163
 */
164
static inline void lv_list_set_scroll_propagation(lv_obj_t * list, bool en)
165
{
166
    lv_page_set_scroll_propagation(list, en);
167
}
168

169
/**
170
 * Enable the edge flash effect. (Show an arc when the an edge is reached)
171
 * @param list pointer to a List
172
 * @param en true or false to enable/disable end flash
173
 */
174
static inline void lv_list_set_edge_flash(lv_obj_t * list, bool en)
175
{
176
    lv_page_set_edge_flash(list, en);
177
}
178

179
/**
180
 * Set a style of a list
181
 * @param list pointer to a list object
182
 * @param type which style should be set
183
 * @param style pointer to a style
184
 */
185
void lv_list_set_style(lv_obj_t *list, lv_list_style_t type, lv_style_t *style);
186

187
/*=====================
188
 * Getter functions
189
 *====================*/
190

191
/**
192
 * Get single button selected mode.
193
 * @param list pointer to the currently pressed list object.
194
 */
195
bool lv_list_get_single_mode(lv_obj_t *list);
196

197
/**
198
 * Get the text of a list element
199
 * @param btn pointer to list element
200
 * @return pointer to the text
201
 */
202
const char * lv_list_get_btn_text(const lv_obj_t * btn);
203
/**
204
 * Get the label object from a list element
205
 * @param btn pointer to a list element (button)
206
 * @return pointer to the label from the list element or NULL if not found
207
 */
208
lv_obj_t * lv_list_get_btn_label(const lv_obj_t * btn);
209

210
/**
211
 * Get the image object from a list element
212
 * @param btn pointer to a list element (button)
213
 * @return pointer to the image from the list element or NULL if not found
214
 */
215
lv_obj_t * lv_list_get_btn_img(const lv_obj_t * btn);
216

217
/**
218
 * Get the next button from list. (Starts from the bottom button)
219
 * @param list pointer to a list object
220
 * @param prev_btn pointer to button. Search the next after it.
221
 * @return pointer to the next button or NULL when no more buttons
222
 */
223
lv_obj_t * lv_list_get_prev_btn(const lv_obj_t * list, lv_obj_t * prev_btn);
224

225
/**
226
 * Get the previous button from list. (Starts from the top button)
227
 * @param list pointer to a list object
228
 * @param prev_btn pointer to button. Search the previous before it.
229
 * @return pointer to the previous button or NULL when no more buttons
230
 */
231
lv_obj_t * lv_list_get_next_btn(const lv_obj_t * list, lv_obj_t * prev_btn);
232

233
/**
234
 * Get the index of the button in the list
235
 * @param list pointer to a list object. If NULL, assumes btn is part of a list.
236
 * @param btn pointer to a list element (button)
237
 * @return the index of the button in the list, or -1 of the button not in this list
238
 */
239
int32_t lv_list_get_btn_index(const lv_obj_t * list, const lv_obj_t * btn);
240

241
/**
242
 * Get the number of buttons in the list
243
 * @param list pointer to a list object
244
 * @return the number of buttons in the list
245
 */
246
uint32_t lv_list_get_size(const lv_obj_t * list);
247

248
#if USE_LV_GROUP
249
/**
250
 * Get the currently selected button. Can be used while navigating in the list with a keypad.
251
 * @param list pointer to a list object
252
 * @return pointer to the selected button
253
 */
254
lv_obj_t * lv_list_get_btn_selected(const lv_obj_t * list);
255
#endif
256

257

258
/**
259
 * Get scroll animation duration
260
 * @param list pointer to a list object
261
 * @return duration of animation [ms]
262
 */
263
uint16_t lv_list_get_anim_time(const lv_obj_t *list);
264

265

266
/**
267
 * Get the scroll bar mode of a list
268
 * @param list pointer to a list object
269
 * @return scrollbar mode from 'lv_page_sb_mode_t' enum
270
 */
271
static inline lv_sb_mode_t lv_list_get_sb_mode(const lv_obj_t * list)
272
{
273
    return lv_page_get_sb_mode(list);
274
}
275

276
/**
277
 * Get the scroll propagation property
278
 * @param list pointer to a List
279
 * @return true or false
280
 */
281
static inline bool lv_list_get_scroll_propagation(lv_obj_t * list)
282
{
283
    return lv_page_get_scroll_propagation(list);
284
}
285

286
/**
287
 * Get the scroll propagation property
288
 * @param list pointer to a List
289
 * @return true or false
290
 */
291
static inline bool lv_list_get_edge_flash(lv_obj_t * list)
292
{
293
    return lv_page_get_edge_flash(list);
294
}
295

296
/**
297
 * Get a style of a list
298
 * @param list pointer to a list object
299
 * @param type which style should be get
300
 * @return style pointer to a style
301
 *  */
302
lv_style_t * lv_list_get_style(const lv_obj_t *list, lv_list_style_t type);
303

304
/*=====================
305
 * Other functions
306
 *====================*/
307

308
/**
309
 * Move the list elements up by one
310
 * @param list pointer a to list object
311
 */
312
void lv_list_up(const lv_obj_t * list);
313
/**
314
 * Move the list elements down by one
315
 * @param list pointer to a list object
316
 */
317
void lv_list_down(const lv_obj_t * list);
318

319
/**
320
 * Focus on a list button. It ensures that the button will be visible on the list.
321
 * @param btn pointer to a list button to focus
322
 * @param anim_en true: scroll with animation, false: without animation
323
 */
324
void lv_list_focus(const lv_obj_t *btn, bool anim_en);
325

326
/**********************
327
 *      MACROS
328
 **********************/
329

330
#endif  /*USE_LV_LIST*/
331

332
#ifdef __cplusplus
333
} /* extern "C" */
334
#endif
335

336
#endif  /*LV_LIST_H*/
337

338