1 /** 2 * @file lv_btnm.h 3 * 4 */ 5 6 #ifndef LV_BTNM_H 7 #define LV_BTNM_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_BTNM != 0 23 24 #include "../lv_core/lv_obj.h" 25 #include "lv_label.h" 26 #include "lv_btn.h" 27 28 /********************* 29 * DEFINES 30 *********************/ 31 #define LV_BTNM_WIDTH_MASK 0x0007 32 #define LV_BTNM_BTN_NONE 0xFFFF 33 34 /********************** 35 * TYPEDEFS 36 **********************/ 37 38 /** Type to store button control bits (disabled, hidden etc.) */ 39 enum { 40 LV_BTNM_CTRL_HIDDEN = 0x0008, /**< Button hidden */ 41 LV_BTNM_CTRL_NO_REPEAT = 0x0010, /**< Do not repeat press this button. */ 42 LV_BTNM_CTRL_INACTIVE = 0x0020, /**< Disable this button. */ 43 LV_BTNM_CTRL_TGL_ENABLE = 0x0040, /**< Button *can* be toggled. */ 44 LV_BTNM_CTRL_TGL_STATE = 0x0080, /**< Button is currently toggled (e.g. checked). */ 45 LV_BTNM_CTRL_CLICK_TRIG = 0x0100, /**< 1: Send LV_EVENT_SELECTED on CLICK, 0: Send LV_EVENT_SELECTED on PRESS*/ 46 }; 47 typedef uint16_t lv_btnm_ctrl_t; 48 49 /*Data of button matrix*/ 50 typedef struct 51 { 52 /*No inherited ext.*/ /*Ext. of ancestor*/ 53 /*New data for this type */ 54 const char ** map_p; /*Pointer to the current map*/ 55 lv_area_t * button_areas; /*Array of areas of buttons*/ 56 lv_btnm_ctrl_t * ctrl_bits; /*Array of control bytes*/ 57 const lv_style_t * styles_btn[_LV_BTN_STATE_NUM]; /*Styles of buttons in each state*/ 58 uint16_t btn_cnt; /*Number of button in 'map_p'(Handled by the library)*/ 59 uint16_t btn_id_pr; /*Index of the currently pressed button or LV_BTNM_BTN_NONE*/ 60 uint16_t btn_id_act; /*Index of the active button (being pressed/released etc) or LV_BTNM_BTN_NONE */ 61 uint8_t recolor : 1; /*Enable button recoloring*/ 62 uint8_t one_toggle : 1; /*Single button toggled at once*/ 63 } lv_btnm_ext_t; 64 65 enum { 66 LV_BTNM_STYLE_BG, 67 LV_BTNM_STYLE_BTN_REL, 68 LV_BTNM_STYLE_BTN_PR, 69 LV_BTNM_STYLE_BTN_TGL_REL, 70 LV_BTNM_STYLE_BTN_TGL_PR, 71 LV_BTNM_STYLE_BTN_INA, 72 }; 73 typedef uint8_t lv_btnm_style_t; 74 75 /********************** 76 * GLOBAL PROTOTYPES 77 **********************/ 78 79 /** 80 * Create a button matrix objects 81 * @param par pointer to an object, it will be the parent of the new button matrix 82 * @param copy pointer to a button matrix object, if not NULL then the new object will be copied 83 * from it 84 * @return pointer to the created button matrix 85 */ 86 lv_obj_t * lv_btnm_create(lv_obj_t * par, const lv_obj_t * copy); 87 88 /*===================== 89 * Setter functions 90 *====================*/ 91 92 /** 93 * Set a new map. Buttons will be created/deleted according to the map. The 94 * button matrix keeps a reference to the map and so the string array must not 95 * be deallocated during the life of the matrix. 96 * @param btnm pointer to a button matrix object 97 * @param map pointer a string array. The last string has to be: "". Use "\n" to make a line break. 98 */ 99 void lv_btnm_set_map(const lv_obj_t * btnm, const char * map[]); 100 101 /** 102 * Set the button control map (hidden, disabled etc.) for a button matrix. The 103 * control map array will be copied and so may be deallocated after this 104 * function returns. 105 * @param btnm pointer to a button matrix object 106 * @param ctrl_map pointer to an array of `lv_btn_ctrl_t` control bytes. The 107 * length of the array and position of the elements must match 108 * the number and order of the individual buttons (i.e. excludes 109 * newline entries). 110 * An element of the map should look like e.g.: 111 * `ctrl_map[0] = width | LV_BTNM_CTRL_NO_REPEAT | LV_BTNM_CTRL_TGL_ENABLE` 112 */ 113 void lv_btnm_set_ctrl_map(const lv_obj_t * btnm, const lv_btnm_ctrl_t ctrl_map[]); 114 115 /** 116 * Set the pressed button i.e. visually highlight it. 117 * Mainly used a when the btnm is in a group to show the selected button 118 * @param btnm pointer to button matrix object 119 * @param id index of the currently pressed button (`LV_BTNM_BTN_NONE` to unpress) 120 */ 121 void lv_btnm_set_pressed(const lv_obj_t * btnm, uint16_t id); 122 123 /** 124 * Set a style of a button matrix 125 * @param btnm pointer to a button matrix object 126 * @param type which style should be set 127 * @param style pointer to a style 128 */ 129 void lv_btnm_set_style(lv_obj_t * btnm, lv_btnm_style_t type, const lv_style_t * style); 130 131 /** 132 * Enable recoloring of button's texts 133 * @param btnm pointer to button matrix object 134 * @param en true: enable recoloring; false: disable 135 */ 136 void lv_btnm_set_recolor(const lv_obj_t * btnm, bool en); 137 138 /** 139 * Set the attributes of a button of the button matrix 140 * @param btnm pointer to button matrix object 141 * @param btn_id 0 based index of the button to modify. (Not counting new lines) 142 */ 143 void lv_btnm_set_btn_ctrl(const lv_obj_t * btnm, uint16_t btn_id, lv_btnm_ctrl_t ctrl); 144 145 /** 146 * Clear the attributes of a button of the button matrix 147 * @param btnm pointer to button matrix object 148 * @param btn_id 0 based index of the button to modify. (Not counting new lines) 149 */ 150 void lv_btnm_clear_btn_ctrl(const lv_obj_t * btnm, uint16_t btn_id, lv_btnm_ctrl_t ctrl); 151 152 /** 153 * Set the attributes of all buttons of a button matrix 154 * @param btnm pointer to a button matrix object 155 * @param ctrl attribute(s) to set from `lv_btnm_ctrl_t`. Values can be ORed. 156 */ 157 void lv_btnm_set_btn_ctrl_all(lv_obj_t * btnm, lv_btnm_ctrl_t ctrl); 158 159 /** 160 * Clear the attributes of all buttons of a button matrix 161 * @param btnm pointer to a button matrix object 162 * @param ctrl attribute(s) to set from `lv_btnm_ctrl_t`. Values can be ORed. 163 * @param en true: set the attributes; false: clear the attributes 164 */ 165 void lv_btnm_clear_btn_ctrl_all(lv_obj_t * btnm, lv_btnm_ctrl_t ctrl); 166 167 /** 168 * Set a single buttons relative width. 169 * This method will cause the matrix be regenerated and is a relatively 170 * expensive operation. It is recommended that initial width be specified using 171 * `lv_btnm_set_ctrl_map` and this method only be used for dynamic changes. 172 * @param btnm pointer to button matrix object 173 * @param btn_id 0 based index of the button to modify. 174 * @param width Relative width compared to the buttons in the same row. [1..7] 175 */ 176 void lv_btnm_set_btn_width(const lv_obj_t * btnm, uint16_t btn_id, uint8_t width); 177 178 /** 179 * Make the button matrix like a selector widget (only one button may be toggled at a time). 180 * 181 * Toggling must be enabled on the buttons you want to be selected with `lv_btnm_set_ctrl` or 182 * `lv_btnm_set_btn_ctrl_all`. 183 * 184 * @param btnm Button matrix object 185 * @param one_toggle Whether "one toggle" mode is enabled 186 */ 187 void lv_btnm_set_one_toggle(lv_obj_t * btnm, bool one_toggle); 188 189 /*===================== 190 * Getter functions 191 *====================*/ 192 193 /** 194 * Get the current map of a button matrix 195 * @param btnm pointer to a button matrix object 196 * @return the current map 197 */ 198 const char ** lv_btnm_get_map_array(const lv_obj_t * btnm); 199 200 /** 201 * Check whether the button's text can use recolor or not 202 * @param btnm pointer to button matrix object 203 * @return true: text recolor enable; false: disabled 204 */ 205 bool lv_btnm_get_recolor(const lv_obj_t * btnm); 206 207 /** 208 * Get the index of the lastly "activated" button by the user (pressed, released etc) 209 * Useful in the the `event_cb` to get the text of the button, check if hidden etc. 210 * @param btnm pointer to button matrix object 211 * @return index of the last released button (LV_BTNM_BTN_NONE: if unset) 212 */ 213 uint16_t lv_btnm_get_active_btn(const lv_obj_t * btnm); 214 215 /** 216 * Get the text of the lastly "activated" button by the user (pressed, released etc) 217 * Useful in the the `event_cb` 218 * @param btnm pointer to button matrix object 219 * @return text of the last released button (NULL: if unset) 220 */ 221 const char * lv_btnm_get_active_btn_text(const lv_obj_t * btnm); 222 223 /** 224 * Get the pressed button's index. 225 * The button be really pressed by the user or manually set to pressed with `lv_btnm_set_pressed` 226 * @param btnm pointer to button matrix object 227 * @return index of the pressed button (LV_BTNM_BTN_NONE: if unset) 228 */ 229 uint16_t lv_btnm_get_pressed_btn(const lv_obj_t * btnm); 230 231 /** 232 * Get the button's text 233 * @param btnm pointer to button matrix object 234 * @param btn_id the index a button not counting new line characters. (The return value of 235 * lv_btnm_get_pressed/released) 236 * @return text of btn_index` button 237 */ 238 const char * lv_btnm_get_btn_text(const lv_obj_t * btnm, uint16_t btn_id); 239 240 /** 241 * Get the whether a control value is enabled or disabled for button of a button matrix 242 * @param btnm pointer to a button matrix object 243 * @param btn_id the index a button not counting new line characters. (E.g. the return value of 244 * lv_btnm_get_pressed/released) 245 * @param ctrl control values to check (ORed value can be used) 246 * @return true: long press repeat is disabled; false: long press repeat enabled 247 */ 248 bool lv_btnm_get_btn_ctrl(lv_obj_t * btnm, uint16_t btn_id, lv_btnm_ctrl_t ctrl); 249 250 /** 251 * Get a style of a button matrix 252 * @param btnm pointer to a button matrix object 253 * @param type which style should be get 254 * @return style pointer to a style 255 */ 256 const lv_style_t * lv_btnm_get_style(const lv_obj_t * btnm, lv_btnm_style_t type); 257 258 /** 259 * Find whether "one toggle" mode is enabled. 260 * @param btnm Button matrix object 261 * @return whether "one toggle" mode is enabled 262 */ 263 bool lv_btnm_get_one_toggle(const lv_obj_t * btnm); 264 /********************** 265 * MACROS 266 **********************/ 267 268 #endif /*LV_USE_BTNM*/ 269 270 #ifdef __cplusplus 271 } /* extern "C" */ 272 #endif 273 274 #endif /*LV_BTNM_H*/ 275