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