1 /** 2 * @file lv_dropdown.h 3 * 4 */ 5 6 #ifndef LV_DROPDOWN_H 7 #define LV_DROPDOWN_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_DROPDOWN != 0 19 20 /*Testing of dependencies*/ 21 22 #if LV_USE_LABEL == 0 23 #error "lv_dropdown: lv_label is required. Enable it in lv_conf.h (LV_USE_LABEL 1)" 24 #endif 25 26 #include "../widgets/lv_label.h" 27 28 /********************* 29 * DEFINES 30 *********************/ 31 #define LV_DROPDOWN_POS_LAST 0xFFFF 32 LV_EXPORT_CONST_INT(LV_DROPDOWN_POS_LAST); 33 34 /********************** 35 * TYPEDEFS 36 **********************/ 37 38 typedef struct { 39 lv_obj_t obj; 40 lv_obj_t * list; /**< The dropped down list*/ 41 const char * text; /**< Text to display on the dropdown's button*/ 42 const void * symbol; /**< Arrow or other icon when the drop-down list is closed*/ 43 char * options; /**< Options in a '\n' separated list*/ 44 uint16_t option_cnt; /**< Number of options*/ 45 uint16_t sel_opt_id; /**< Index of the currently selected option*/ 46 uint16_t sel_opt_id_orig; /**< Store the original index on focus*/ 47 uint16_t pr_opt_id; /**< Index of the currently pressed option*/ 48 lv_dir_t dir : 4; /**< Direction in which the list should open*/ 49 uint8_t static_txt : 1; /**< 1: Only a pointer is saved in `options`*/ 50 uint8_t selected_highlight: 1; /**< 1: Make the selected option highlighted in the list*/ 51 } lv_dropdown_t; 52 53 typedef struct { 54 lv_obj_t obj; 55 lv_obj_t * dropdown; 56 } lv_dropdown_list_t; 57 58 extern const lv_obj_class_t lv_dropdown_class; 59 extern const lv_obj_class_t lv_dropdownlist_class; 60 61 /********************** 62 * GLOBAL PROTOTYPES 63 **********************/ 64 65 /** 66 * Create a drop-down list object 67 * @param parent pointer to an object, it will be the parent of the new drop-down list 68 * @return pointer to the created drop-down list 69 */ 70 lv_obj_t * lv_dropdown_create(lv_obj_t * parent); 71 72 /*===================== 73 * Setter functions 74 *====================*/ 75 76 /** 77 * Set text of the drop-down list's button. 78 * If set to `NULL` the selected option's text will be displayed on the button. 79 * If set to a specific text then that text will be shown regardless of the selected option. 80 * @param obj pointer to a drop-down list object 81 * @param txt the text as a string (Only its pointer is saved) 82 */ 83 void lv_dropdown_set_text(lv_obj_t * obj, const char * txt); 84 85 /** 86 * Set the options in a drop-down list from a string. 87 * The options will be copied and saved in the object so the `options` can be destroyed after calling this function 88 * @param obj pointer to drop-down list object 89 * @param options a string with '\n' separated options. E.g. "One\nTwo\nThree" 90 */ 91 void lv_dropdown_set_options(lv_obj_t * obj, const char * options); 92 93 /** 94 * Set the options in a drop-down list from a static string (global, static or dynamically allocated). 95 * Only the pointer of the option string will be saved. 96 * @param obj pointer to drop-down list object 97 * @param options a static string with '\n' separated options. E.g. "One\nTwo\nThree" 98 */ 99 void lv_dropdown_set_options_static(lv_obj_t * obj, const char * options); 100 101 /** 102 * Add an options to a drop-down list from a string. Only works for non-static options. 103 * @param obj pointer to drop-down list object 104 * @param option a string without '\n'. E.g. "Four" 105 * @param pos the insert position, indexed from 0, LV_DROPDOWN_POS_LAST = end of string 106 */ 107 void lv_dropdown_add_option(lv_obj_t * obj, const char * option, uint32_t pos); 108 109 /** 110 * Clear all options in a drop-down list. Works with both static and dynamic options. 111 * @param obj pointer to drop-down list object 112 */ 113 void lv_dropdown_clear_options(lv_obj_t * obj); 114 115 /** 116 * Set the selected option 117 * @param obj pointer to drop-down list object 118 * @param sel_opt id of the selected option (0 ... number of option - 1); 119 */ 120 void lv_dropdown_set_selected(lv_obj_t * obj, uint16_t sel_opt); 121 122 /** 123 * Set the direction of the a drop-down list 124 * @param obj pointer to a drop-down list object 125 * @param dir LV_DIR_LEFT/RIGHT/TOP/BOTTOM 126 */ 127 void lv_dropdown_set_dir(lv_obj_t * obj, lv_dir_t dir); 128 129 /** 130 * Set an arrow or other symbol to display when on drop-down list's button. Typically a down caret or arrow. 131 * @param obj pointer to drop-down list object 132 * @param symbol a text like `LV_SYMBOL_DOWN`, an image (pointer or path) or NULL to not draw symbol icon 133 * @note angle and zoom transformation can be applied if the symbol is an image. 134 * E.g. when drop down is checked (opened) rotate the symbol by 180 degree 135 */ 136 void lv_dropdown_set_symbol(lv_obj_t * obj, const void * symbol); 137 138 /** 139 * Set whether the selected option in the list should be highlighted or not 140 * @param obj pointer to drop-down list object 141 * @param en true: highlight enabled; false: disabled 142 */ 143 void lv_dropdown_set_selected_highlight(lv_obj_t * obj, bool en); 144 145 /*===================== 146 * Getter functions 147 *====================*/ 148 149 /** 150 * Get the list of a drop-down to allow styling or other modifications 151 * @param obj pointer to a drop-down list object 152 * @return pointer to the list of the drop-down 153 */ 154 lv_obj_t * lv_dropdown_get_list(lv_obj_t * obj); 155 156 /** 157 * Get text of the drop-down list's button. 158 * @param obj pointer to a drop-down list object 159 * @return the text as string, `NULL` if no text 160 */ 161 const char * lv_dropdown_get_text(lv_obj_t * obj); 162 163 /** 164 * Get the options of a drop-down list 165 * @param obj pointer to drop-down list object 166 * @return the options separated by '\n'-s (E.g. "Option1\nOption2\nOption3") 167 */ 168 const char * lv_dropdown_get_options(const lv_obj_t * obj); 169 170 /** 171 * Get the index of the selected option 172 * @param obj pointer to drop-down list object 173 * @return index of the selected option (0 ... number of option - 1); 174 */ 175 uint16_t lv_dropdown_get_selected(const lv_obj_t * obj); 176 177 /** 178 * Get the total number of options 179 * @param obj pointer to drop-down list object 180 * @return the total number of options in the list 181 */ 182 uint16_t lv_dropdown_get_option_cnt(const lv_obj_t * obj); 183 184 /** 185 * Get the current selected option as a string 186 * @param obj pointer to drop-down object 187 * @param buf pointer to an array to store the string 188 * @param buf_size size of `buf` in bytes. 0: to ignore it. 189 */ 190 void lv_dropdown_get_selected_str(const lv_obj_t * obj, char * buf, uint32_t buf_size); 191 192 /** 193 * Get the index of an option. 194 * @param obj pointer to drop-down object 195 * @param option an option as string 196 * @return index of `option` in the list of all options. -1 if not found. 197 */ 198 int32_t lv_dropdown_get_option_index(lv_obj_t * obj, const char * option); 199 200 /** 201 * Get the symbol on the drop-down list. Typically a down caret or arrow. 202 * @param obj pointer to drop-down list object 203 * @return the symbol or NULL if not enabled 204 */ 205 const char * lv_dropdown_get_symbol(lv_obj_t * obj); 206 207 /** 208 * Get whether the selected option in the list should be highlighted or not 209 * @param obj pointer to drop-down list object 210 * @return true: highlight enabled; false: disabled 211 */ 212 bool lv_dropdown_get_selected_highlight(lv_obj_t * obj); 213 214 /** 215 * Get the direction of the drop-down list 216 * @param obj pointer to a drop-down list object 217 * @return LV_DIR_LEF/RIGHT/TOP/BOTTOM 218 */ 219 lv_dir_t lv_dropdown_get_dir(const lv_obj_t * obj); 220 221 /*===================== 222 * Other functions 223 *====================*/ 224 225 /** 226 * Open the drop.down list 227 * @param obj pointer to drop-down list object 228 */ 229 void lv_dropdown_open(lv_obj_t * dropdown_obj); 230 231 /** 232 * Close (Collapse) the drop-down list 233 * @param obj pointer to drop-down list object 234 */ 235 void lv_dropdown_close(lv_obj_t * obj); 236 237 /** 238 * Tells whether the list is opened or not 239 * @param obj pointer to a drop-down list object 240 * @return true if the list os opened 241 */ 242 bool lv_dropdown_is_open(lv_obj_t * obj); 243 244 /********************** 245 * MACROS 246 **********************/ 247 248 #endif /*LV_USE_DROPDOWN*/ 249 250 #ifdef __cplusplus 251 } /*extern "C"*/ 252 #endif 253 254 #endif /*LV_DROPDOWN_H*/ 255
