1 /**
2 * @file lv_ddlist.h
3 *
4 */
5
6 #ifndef LV_DDLIST_H
7 #define LV_DDLIST_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 LV_USE_DDLIST != 0
23
24 /*Testing of dependencies*/
25 #if LV_USE_PAGE == 0
26 #error "lv_ddlist: lv_page is required. Enable it in lv_conf.h (LV_USE_PAGE 1) "
27 #endif
28
29 #if LV_USE_LABEL == 0
30 #error "lv_ddlist: 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_objx/lv_page.h"
35 #include "../lv_objx/lv_label.h"
36
37 /*********************
38 * DEFINES
39 *********************/
40
41 /**********************
42 * TYPEDEFS
43 **********************/
44 /*Data of drop down list*/
45 typedef struct
46 {
47 lv_page_ext_t page; /*Ext. of ancestor*/
48 /*New data for this type */
49 lv_obj_t * label; /*Label for the options*/
50 const lv_style_t * sel_style; /*Style of the selected option*/
51 uint16_t option_cnt; /*Number of options*/
52 uint16_t sel_opt_id; /*Index of the current option*/
53 uint16_t sel_opt_id_ori; /*Store the original index on focus*/
54 uint8_t opened : 1; /*1: The list is opened (handled by the library)*/
55 uint8_t force_sel : 1; /*1: Keep the selection highlight even if the list is closed*/
56 uint8_t draw_arrow : 1; /*1: Draw arrow*/
57 uint8_t stay_open : 1; /*1: Don't close the list when a new item is selected*/
58 lv_coord_t fix_height; /*Height of the ddlist when opened. (0: auto-size)*/
59 } lv_ddlist_ext_t;
60
61 enum {
62 LV_DDLIST_STYLE_BG,
63 LV_DDLIST_STYLE_SEL,
64 LV_DDLIST_STYLE_SB,
65 };
66 typedef uint8_t lv_ddlist_style_t;
67
68 /**********************
69 * GLOBAL PROTOTYPES
70 **********************/
71 /**
72 * Create a drop down list objects
73 * @param par pointer to an object, it will be the parent of the new drop down list
74 * @param copy pointer to a drop down list object, if not NULL then the new object will be copied
75 * from it
76 * @return pointer to the created drop down list
77 */
78 lv_obj_t * lv_ddlist_create(lv_obj_t * par, const lv_obj_t * copy);
79
80 /*=====================
81 * Setter functions
82 *====================*/
83
84 /**
85 * Set the options in a drop down list from a string
86 * @param ddlist pointer to drop down list object
87 * @param options a string with '\n' separated options. E.g. "One\nTwo\nThree"
88 */
89 void lv_ddlist_set_options(lv_obj_t * ddlist, const char * options);
90
91 /**
92 * Set the selected option
93 * @param ddlist pointer to drop down list object
94 * @param sel_opt id of the selected option (0 ... number of option - 1);
95 */
96 void lv_ddlist_set_selected(lv_obj_t * ddlist, uint16_t sel_opt);
97
98 /**
99 * Set a fix height for the drop down list
100 * If 0 then the opened ddlist will be auto. sized else the set height will be applied.
101 * @param ddlist pointer to a drop down list
102 * @param h the height when the list is opened (0: auto size)
103 */
104 void lv_ddlist_set_fix_height(lv_obj_t * ddlist, lv_coord_t h);
105
106 /**
107 * Set a fix width for the drop down list
108 * @param ddlist pointer to a drop down list
109 * @param w the width when the list is opened (0: auto size)
110 */
111 void lv_ddlist_set_fix_width(lv_obj_t * ddlist, lv_coord_t w);
112
113 /**
114 * Set arrow draw in a drop down list
115 * @param ddlist pointer to drop down list object
116 * @param en enable/disable a arrow draw. E.g. "true" for draw.
117 */
118 void lv_ddlist_set_draw_arrow(lv_obj_t * ddlist, bool en);
119
120 /**
121 * Leave the list opened when a new value is selected
122 * @param ddlist pointer to drop down list object
123 * @param en enable/disable "stay open" feature
124 */
125 void lv_ddlist_set_stay_open(lv_obj_t * ddlist, bool en);
126
127 /**
128 * Set the scroll bar mode of a drop down list
129 * @param ddlist pointer to a drop down list object
130 * @param sb_mode the new mode from 'lv_page_sb_mode_t' enum
131 */
lv_ddlist_set_sb_mode(lv_obj_t * ddlist,lv_sb_mode_t mode)132 static inline void lv_ddlist_set_sb_mode(lv_obj_t * ddlist, lv_sb_mode_t mode)
133 {
134 lv_page_set_sb_mode(ddlist, mode);
135 }
136 /**
137 * Set the open/close animation time.
138 * @param ddlist pointer to a drop down list
139 * @param anim_time: open/close animation time [ms]
140 */
lv_ddlist_set_anim_time(lv_obj_t * ddlist,uint16_t anim_time)141 static inline void lv_ddlist_set_anim_time(lv_obj_t * ddlist, uint16_t anim_time)
142 {
143 lv_page_set_anim_time(ddlist, anim_time);
144 }
145
146 /**
147 * Set a style of a drop down list
148 * @param ddlist pointer to a drop down list object
149 * @param type which style should be set
150 * @param style pointer to a style
151 * */
152 void lv_ddlist_set_style(lv_obj_t * ddlist, lv_ddlist_style_t type, const lv_style_t * style);
153
154 /**
155 * Set the alignment of the labels in a drop down list
156 * @param ddlist pointer to a drop down list object
157 * @param align alignment of labels
158 */
159 void lv_ddlist_set_align(lv_obj_t * ddlist, lv_label_align_t align);
160
161 /*=====================
162 * Getter functions
163 *====================*/
164
165 /**
166 * Get the options of a drop down list
167 * @param ddlist pointer to drop down list object
168 * @return the options separated by '\n'-s (E.g. "Option1\nOption2\nOption3")
169 */
170 const char * lv_ddlist_get_options(const lv_obj_t * ddlist);
171
172 /**
173 * Get the selected option
174 * @param ddlist pointer to drop down list object
175 * @return id of the selected option (0 ... number of option - 1);
176 */
177 uint16_t lv_ddlist_get_selected(const lv_obj_t * ddlist);
178
179 /**
180 * Get the current selected option as a string
181 * @param ddlist pointer to ddlist object
182 * @param buf pointer to an array to store the string
183 * @param buf_size size of `buf` in bytes. 0: to ignore it.
184 */
185 void lv_ddlist_get_selected_str(const lv_obj_t * ddlist, char * buf, uint16_t buf_size);
186
187 /**
188 * Get the fix height value.
189 * @param ddlist pointer to a drop down list object
190 * @return the height if the ddlist is opened (0: auto size)
191 */
192 lv_coord_t lv_ddlist_get_fix_height(const lv_obj_t * ddlist);
193
194 /**
195 * Get arrow draw in a drop down list
196 * @param ddlist pointer to drop down list object
197 */
198 bool lv_ddlist_get_draw_arrow(lv_obj_t * ddlist);
199
200 /**
201 * Get whether the drop down list stay open after selecting a value or not
202 * @param ddlist pointer to drop down list object
203 */
204 bool lv_ddlist_get_stay_open(lv_obj_t * ddlist);
205
206 /**
207 * Get the scroll bar mode of a drop down list
208 * @param ddlist pointer to a drop down list object
209 * @return scrollbar mode from 'lv_page_sb_mode_t' enum
210 */
lv_ddlist_get_sb_mode(const lv_obj_t * ddlist)211 static inline lv_sb_mode_t lv_ddlist_get_sb_mode(const lv_obj_t * ddlist)
212 {
213 return lv_page_get_sb_mode(ddlist);
214 }
215
216 /**
217 * Get the open/close animation time.
218 * @param ddlist pointer to a drop down list
219 * @return open/close animation time [ms]
220 */
lv_ddlist_get_anim_time(const lv_obj_t * ddlist)221 static inline uint16_t lv_ddlist_get_anim_time(const lv_obj_t * ddlist)
222 {
223 return lv_page_get_anim_time(ddlist);
224 }
225
226 /**
227 * Get a style of a drop down list
228 * @param ddlist pointer to a drop down list object
229 * @param type which style should be get
230 * @return style pointer to a style
231 */
232 const lv_style_t * lv_ddlist_get_style(const lv_obj_t * ddlist, lv_ddlist_style_t type);
233
234 /**
235 * Get the alignment of the labels in a drop down list
236 * @param ddlist pointer to a drop down list object
237 * @return alignment of labels
238 */
239 lv_label_align_t lv_ddlist_get_align(const lv_obj_t * ddlist);
240
241 /*=====================
242 * Other functions
243 *====================*/
244
245 /**
246 * Open the drop down list with or without animation
247 * @param ddlist pointer to drop down list object
248 * @param anim_en LV_ANIM_ON: use animation; LV_ANOM_OFF: not use animations
249 */
250 void lv_ddlist_open(lv_obj_t * ddlist, lv_anim_enable_t anim);
251
252 /**
253 * Close (Collapse) the drop down list
254 * @param ddlist pointer to drop down list object
255 * @param anim_en LV_ANIM_ON: use animation; LV_ANOM_OFF: not use animations
256 */
257 void lv_ddlist_close(lv_obj_t * ddlist, lv_anim_enable_t anim);
258
259 /**********************
260 * MACROS
261 **********************/
262
263 #endif /*LV_USE_DDLIST*/
264
265 #ifdef __cplusplus
266 } /* extern "C" */
267 #endif
268
269 #endif /*LV_DDLIST_H*/
270