1 /** 2 * @file lv_btnmatrix.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 "../core/lv_obj.h" 21 22 /********************* 23 * DEFINES 24 *********************/ 25 #define LV_BTNMATRIX_BTN_NONE 0xFFFF 26 LV_EXPORT_CONST_INT(LV_BTNMATRIX_BTN_NONE); 27 28 /********************** 29 * TYPEDEFS 30 **********************/ 31 32 /** Type to store button control bits (disabled, hidden etc.) 33 * The first 3 bits are used to store the width*/ 34 enum { 35 _LV_BTNMATRIX_WIDTH = 0x000F, /**< Reserved to store the size units*/ 36 LV_BTNMATRIX_CTRL_HIDDEN = 0x0010, /**< Button hidden*/ 37 LV_BTNMATRIX_CTRL_NO_REPEAT = 0x0020, /**< Do not repeat press this button.*/ 38 LV_BTNMATRIX_CTRL_DISABLED = 0x0040, /**< Disable this button.*/ 39 LV_BTNMATRIX_CTRL_CHECKABLE = 0x0080, /**< The button can be toggled.*/ 40 LV_BTNMATRIX_CTRL_CHECKED = 0x0100, /**< Button is currently toggled (e.g. checked).*/ 41 LV_BTNMATRIX_CTRL_CLICK_TRIG = 0x0200, /**< 1: Send LV_EVENT_VALUE_CHANGE on CLICK, 0: Send LV_EVENT_VALUE_CHANGE on PRESS*/ 42 LV_BTNMATRIX_CTRL_POPOVER = 0x0400, /**< Show a popover when pressing this key*/ 43 LV_BTNMATRIX_CTRL_RECOLOR = 0x0800, /**< Enable text recoloring with `#color`*/ 44 _LV_BTNMATRIX_CTRL_RESERVED_1 = 0x1000, /**< Reserved for later use*/ 45 _LV_BTNMATRIX_CTRL_RESERVED_2 = 0x2000, /**< Reserved for later use*/ 46 LV_BTNMATRIX_CTRL_CUSTOM_1 = 0x4000, /**< Custom free to use flag*/ 47 LV_BTNMATRIX_CTRL_CUSTOM_2 = 0x8000, /**< Custom free to use flag*/ 48 }; 49 50 typedef uint16_t lv_btnmatrix_ctrl_t; 51 52 typedef bool (*lv_btnmatrix_btn_draw_cb_t)(lv_obj_t * btnm, uint32_t btn_id, const lv_area_t * draw_area, 53 const lv_area_t * clip_area); 54 55 /*Data of button matrix*/ 56 typedef struct { 57 lv_obj_t obj; 58 const char ** map_p; /*Pointer to the current map*/ 59 lv_area_t * button_areas; /*Array of areas of buttons*/ 60 lv_btnmatrix_ctrl_t * ctrl_bits; /*Array of control bytes*/ 61 uint16_t btn_cnt; /*Number of button in 'map_p'(Handled by the library)*/ 62 uint16_t row_cnt; /*Number of rows in 'map_p'(Handled by the library)*/ 63 uint16_t btn_id_sel; /*Index of the active button (being pressed/released etc) or LV_BTNMATRIX_BTN_NONE*/ 64 uint8_t one_check : 1; /*Single button toggled at once*/ 65 } lv_btnmatrix_t; 66 67 extern const lv_obj_class_t lv_btnmatrix_class; 68 69 /** 70 * `type` field in `lv_obj_draw_part_dsc_t` if `class_p = lv_btnmatrix_class` 71 * Used in `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` 72 */ 73 typedef enum { 74 LV_BTNMATRIX_DRAW_PART_BTN, /**< The rectangle and label of buttons*/ 75 } lv_btnmatrix_draw_part_type_t; 76 77 /********************** 78 * GLOBAL PROTOTYPES 79 **********************/ 80 81 /** 82 * Create a button matrix object 83 * @param parent pointer to an object, it will be the parent of the new button matrix 84 * @return pointer to the created button matrix 85 */ 86 lv_obj_t * lv_btnmatrix_create(lv_obj_t * parent); 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 obj 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_btnmatrix_set_map(lv_obj_t * obj, const char * map[]); 100 101 /** 102 * Set the button control map (hidden, disabled etc.) for a button matrix. 103 * The control map array will be copied and so may be deallocated after this 104 * function returns. 105 * @param obj 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_BTNMATRIX_CTRL_NO_REPEAT | LV_BTNMATRIX_CTRL_TGL_ENABLE` 112 */ 113 void lv_btnmatrix_set_ctrl_map(lv_obj_t * obj, const lv_btnmatrix_ctrl_t ctrl_map[]); 114 115 /** 116 * Set the selected buttons 117 * @param obj pointer to button matrix object 118 * @param btn_id 0 based index of the button to modify. (Not counting new lines) 119 */ 120 void lv_btnmatrix_set_selected_btn(lv_obj_t * obj, uint16_t btn_id); 121 122 /** 123 * Set the attributes of a button of the button matrix 124 * @param obj pointer to button matrix object 125 * @param btn_id 0 based index of the button to modify. (Not counting new lines) 126 * @param ctrl OR-ed attributs. E.g. `LV_BTNMATRIX_CTRL_NO_REPEAT | LV_BTNMATRIX_CTRL_CHECKABLE` 127 */ 128 void lv_btnmatrix_set_btn_ctrl(lv_obj_t * obj, uint16_t btn_id, lv_btnmatrix_ctrl_t ctrl); 129 130 /** 131 * Clear the attributes of a button of the button matrix 132 * @param obj pointer to button matrix object 133 * @param btn_id 0 based index of the button to modify. (Not counting new lines) 134 * @param ctrl OR-ed attributs. E.g. `LV_BTNMATRIX_CTRL_NO_REPEAT | LV_BTNMATRIX_CTRL_CHECKABLE` 135 */ 136 void lv_btnmatrix_clear_btn_ctrl(lv_obj_t * obj, uint16_t btn_id, lv_btnmatrix_ctrl_t ctrl); 137 138 /** 139 * Set attributes of all buttons of a button matrix 140 * @param obj pointer to a button matrix object 141 * @param ctrl attribute(s) to set from `lv_btnmatrix_ctrl_t`. Values can be ORed. 142 */ 143 void lv_btnmatrix_set_btn_ctrl_all(lv_obj_t * obj, lv_btnmatrix_ctrl_t ctrl); 144 145 /** 146 * Clear the attributes of all buttons of a button matrix 147 * @param obj pointer to a button matrix object 148 * @param ctrl attribute(s) to set from `lv_btnmatrix_ctrl_t`. Values can be ORed. 149 * @param en true: set the attributes; false: clear the attributes 150 */ 151 void lv_btnmatrix_clear_btn_ctrl_all(lv_obj_t * obj, lv_btnmatrix_ctrl_t ctrl); 152 153 /** 154 * Set a single button's relative width. 155 * This method will cause the matrix be regenerated and is a relatively 156 * expensive operation. It is recommended that initial width be specified using 157 * `lv_btnmatrix_set_ctrl_map` and this method only be used for dynamic changes. 158 * @param obj pointer to button matrix object 159 * @param btn_id 0 based index of the button to modify. 160 * @param width relative width compared to the buttons in the same row. [1..7] 161 */ 162 void lv_btnmatrix_set_btn_width(lv_obj_t * obj, uint16_t btn_id, uint8_t width); 163 164 /** 165 * Make the button matrix like a selector widget (only one button may be checked at a time). 166 * `LV_BTNMATRIX_CTRL_CHECKABLE` must be enabled on the buttons to be selected using 167 * `lv_btnmatrix_set_ctrl()` or `lv_btnmatrix_set_btn_ctrl_all()`. 168 * @param obj pointer to a button matrix object 169 * @param en whether "one check" mode is enabled 170 */ 171 void lv_btnmatrix_set_one_checked(lv_obj_t * obj, bool en); 172 173 /*===================== 174 * Getter functions 175 *====================*/ 176 177 /** 178 * Get the current map of a button matrix 179 * @param obj pointer to a button matrix object 180 * @return the current map 181 */ 182 const char ** lv_btnmatrix_get_map(const lv_obj_t * obj); 183 184 /** 185 * Get the index of the lastly "activated" button by the user (pressed, released, focused etc) 186 * Useful in the `event_cb` to get the text of the button, check if hidden etc. 187 * @param obj pointer to button matrix object 188 * @return index of the last released button (LV_BTNMATRIX_BTN_NONE: if unset) 189 */ 190 uint16_t lv_btnmatrix_get_selected_btn(const lv_obj_t * obj); 191 192 /** 193 * Get the button's text 194 * @param obj pointer to button matrix object 195 * @param btn_id the index a button not counting new line characters. 196 * @return text of btn_index` button 197 */ 198 const char * lv_btnmatrix_get_btn_text(const lv_obj_t * obj, uint16_t btn_id); 199 200 /** 201 * Get the whether a control value is enabled or disabled for button of a button matrix 202 * @param obj pointer to a button matrix object 203 * @param btn_id the index of a button not counting new line characters. 204 * @param ctrl control values to check (ORed value can be used) 205 * @return true: the control attribute is enabled false: disabled 206 */ 207 bool lv_btnmatrix_has_btn_ctrl(lv_obj_t * obj, uint16_t btn_id, lv_btnmatrix_ctrl_t ctrl); 208 209 /** 210 * Tell whether "one check" mode is enabled or not. 211 * @param obj Button matrix object 212 * @return true: "one check" mode is enabled; false: disabled 213 */ 214 bool lv_btnmatrix_get_one_checked(const lv_obj_t * obj); 215 216 /********************** 217 * MACROS 218 **********************/ 219 220 #endif /*LV_USE_BTNMATRIX*/ 221 222 #ifdef __cplusplus 223 } /*extern "C"*/ 224 #endif 225 226 #endif /*LV_BTNMATRIX_H*/ 227
