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