1 /** 2 * @file lv_buttonmatrix.h 3 * 4 */ 5 6 #ifndef LV_BUTTONMATRIX_H 7 #define LV_BUTTONMATRIX_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_BUTTONMATRIX != 0 19 20 #include "../../core/lv_obj.h" 21 22 /********************* 23 * DEFINES 24 *********************/ 25 #define LV_BUTTONMATRIX_BUTTON_NONE 0xFFFF 26 LV_EXPORT_CONST_INT(LV_BUTTONMATRIX_BUTTON_NONE); 27 28 /********************** 29 * TYPEDEFS 30 **********************/ 31 32 /** Type to store button control flags (disabled, hidden etc.) 33 * The least-significant 4 bits are used to store button-width proportions in range [1..15]. */ 34 typedef enum { 35 LV_BUTTONMATRIX_CTRL_HIDDEN = 0x0010, /**< Hides button; it continues to hold its space in layout. */ 36 LV_BUTTONMATRIX_CTRL_NO_REPEAT = 0x0020, /**< Do not emit LV_EVENT_LONG_PRESSED_REPEAT events while button is long-pressed. */ 37 LV_BUTTONMATRIX_CTRL_DISABLED = 0x0040, /**< Disables button like LV_STATE_DISABLED on normal Widgets. */ 38 LV_BUTTONMATRIX_CTRL_CHECKABLE = 0x0080, /**< Enable toggling of LV_STATE_CHECKED when clicked. */ 39 LV_BUTTONMATRIX_CTRL_CHECKED = 0x0100, /**< Make the button checked. It will use the :cpp:enumerator:`LV_STATE_CHECHKED` styles. */ 40 LV_BUTTONMATRIX_CTRL_CLICK_TRIG = 0x0200, /**< 1: Enables sending LV_EVENT_VALUE_CHANGE on CLICK, 0: sends LV_EVENT_VALUE_CHANGE on PRESS. */ 41 LV_BUTTONMATRIX_CTRL_POPOVER = 0x0400, /**< Show button text in a pop-over while being pressed. */ 42 LV_BUTTONMATRIX_CTRL_RECOLOR = 0x0800, /**< Enable text recoloring with `#color` */ 43 LV_BUTTONMATRIX_CTRL_RESERVED_2 = 0x1000, /**< Reserved for later use */ 44 LV_BUTTONMATRIX_CTRL_RESERVED_3 = 0x2000, /**< Reserved for later use */ 45 LV_BUTTONMATRIX_CTRL_CUSTOM_1 = 0x4000, /**< Custom free-to-use flag */ 46 LV_BUTTONMATRIX_CTRL_CUSTOM_2 = 0x8000, /**< Custom free-to-use flag */ 47 } lv_buttonmatrix_ctrl_t; 48 49 typedef bool (*lv_buttonmatrix_button_draw_cb_t)(lv_obj_t * btnm, uint32_t btn_id, const lv_area_t * draw_area, 50 const lv_area_t * clip_area); 51 52 LV_ATTRIBUTE_EXTERN_DATA extern const lv_obj_class_t lv_buttonmatrix_class; 53 54 /********************** 55 * GLOBAL PROTOTYPES 56 **********************/ 57 58 /** 59 * Create a button matrix object 60 * @param parent pointer to an object, it will be the parent of the new button matrix 61 * @return pointer to the created button matrix 62 */ 63 lv_obj_t * lv_buttonmatrix_create(lv_obj_t * parent); 64 65 /*===================== 66 * Setter functions 67 *====================*/ 68 69 /** 70 * Set a new map. Buttons will be created/deleted according to the map. The 71 * button matrix keeps a reference to the map and so the string array must not 72 * be deallocated during the life of the matrix. 73 * @param obj pointer to a button matrix object 74 * @param map pointer a string array. The last string has to be: "". Use "\n" to make a line break. 75 */ 76 void lv_buttonmatrix_set_map(lv_obj_t * obj, const char * const map[]); 77 78 /** 79 * Set the button control map (hidden, disabled etc.) for a button matrix. 80 * The control map array will be copied and so may be deallocated after this 81 * function returns. 82 * @param obj pointer to a button matrix object 83 * @param ctrl_map pointer to an array of `lv_button_ctrl_t` control bytes. The 84 * length of the array and position of the elements must match 85 * the number and order of the individual buttons (i.e. excludes 86 * newline entries). 87 * An element of the map should look like e.g.: 88 * `ctrl_map[0] = width | LV_BUTTONMATRIX_CTRL_NO_REPEAT | LV_BUTTONMATRIX_CTRL_TGL_ENABLE` 89 */ 90 void lv_buttonmatrix_set_ctrl_map(lv_obj_t * obj, const lv_buttonmatrix_ctrl_t ctrl_map[]); 91 92 /** 93 * Set the selected buttons 94 * @param obj pointer to button matrix object 95 * @param btn_id 0 based index of the button to modify. (Not counting new lines) 96 */ 97 void lv_buttonmatrix_set_selected_button(lv_obj_t * obj, uint32_t btn_id); 98 99 /** 100 * Set the attributes of a button of the button matrix 101 * @param obj pointer to button matrix object 102 * @param btn_id 0 based index of the button to modify. (Not counting new lines) 103 * @param ctrl OR-ed attributes. E.g. `LV_BUTTONMATRIX_CTRL_NO_REPEAT | LV_BUTTONMATRIX_CTRL_CHECKABLE` 104 */ 105 void lv_buttonmatrix_set_button_ctrl(lv_obj_t * obj, uint32_t btn_id, lv_buttonmatrix_ctrl_t ctrl); 106 107 /** 108 * Clear the attributes of a button of the button matrix 109 * @param obj pointer to button matrix object 110 * @param btn_id 0 based index of the button to modify. (Not counting new lines) 111 * @param ctrl OR-ed attributes. E.g. `LV_BUTTONMATRIX_CTRL_NO_REPEAT | LV_BUTTONMATRIX_CTRL_CHECKABLE` 112 */ 113 void lv_buttonmatrix_clear_button_ctrl(lv_obj_t * obj, uint32_t btn_id, lv_buttonmatrix_ctrl_t ctrl); 114 115 /** 116 * Set attributes of all buttons of a button matrix 117 * @param obj pointer to a button matrix object 118 * @param ctrl attribute(s) to set from `lv_buttonmatrix_ctrl_t`. Values can be ORed. 119 */ 120 void lv_buttonmatrix_set_button_ctrl_all(lv_obj_t * obj, lv_buttonmatrix_ctrl_t ctrl); 121 122 /** 123 * Clear the attributes of all buttons of a button matrix 124 * @param obj pointer to a button matrix object 125 * @param ctrl attribute(s) to set from `lv_buttonmatrix_ctrl_t`. Values can be ORed. 126 */ 127 void lv_buttonmatrix_clear_button_ctrl_all(lv_obj_t * obj, lv_buttonmatrix_ctrl_t ctrl); 128 129 /** 130 * Set a single button's relative width. 131 * This method will cause the matrix be regenerated and is a relatively 132 * expensive operation. It is recommended that initial width be specified using 133 * `lv_buttonmatrix_set_ctrl_map` and this method only be used for dynamic changes. 134 * @param obj pointer to button matrix object 135 * @param btn_id 0 based index of the button to modify. 136 * @param width relative width compared to the buttons in the same row. [1..15] 137 */ 138 void lv_buttonmatrix_set_button_width(lv_obj_t * obj, uint32_t btn_id, uint32_t width); 139 140 /** 141 * Make the button matrix like a selector widget (only one button may be checked at a time). 142 * `LV_BUTTONMATRIX_CTRL_CHECKABLE` must be enabled on the buttons to be selected using 143 * `lv_buttonmatrix_set_ctrl()` or `lv_buttonmatrix_set_button_ctrl_all()`. 144 * @param obj pointer to a button matrix object 145 * @param en whether "one check" mode is enabled 146 */ 147 void lv_buttonmatrix_set_one_checked(lv_obj_t * obj, bool en); 148 149 /*===================== 150 * Getter functions 151 *====================*/ 152 153 /** 154 * Get the current map of a button matrix 155 * @param obj pointer to a button matrix object 156 * @return the current map 157 */ 158 const char * const * lv_buttonmatrix_get_map(const lv_obj_t * obj); 159 160 /** 161 * Get the index of the lastly "activated" button by the user (pressed, released, focused etc) 162 * Useful in the `event_cb` to get the text of the button, check if hidden etc. 163 * @param obj pointer to button matrix object 164 * @return index of the last released button (LV_BUTTONMATRIX_BUTTON_NONE: if unset) 165 */ 166 uint32_t lv_buttonmatrix_get_selected_button(const lv_obj_t * obj); 167 168 /** 169 * Get the button's text 170 * @param obj pointer to button matrix object 171 * @param btn_id the index a button not counting new line characters. 172 * @return text of btn_index` button 173 */ 174 const char * lv_buttonmatrix_get_button_text(const lv_obj_t * obj, uint32_t btn_id); 175 176 /** 177 * Get the whether a control value is enabled or disabled for button of a button matrix 178 * @param obj pointer to a button matrix object 179 * @param btn_id the index of a button not counting new line characters. 180 * @param ctrl control values to check (ORed value can be used) 181 * @return true: the control attribute is enabled false: disabled 182 */ 183 bool lv_buttonmatrix_has_button_ctrl(lv_obj_t * obj, uint32_t btn_id, lv_buttonmatrix_ctrl_t ctrl); 184 185 /** 186 * Tell whether "one check" mode is enabled or not. 187 * @param obj Button matrix object 188 * @return true: "one check" mode is enabled; false: disabled 189 */ 190 bool lv_buttonmatrix_get_one_checked(const lv_obj_t * obj); 191 192 /********************** 193 * MACROS 194 **********************/ 195 196 #endif /*LV_USE_BUTTONMATRIX*/ 197 198 #ifdef __cplusplus 199 } /*extern "C"*/ 200 #endif 201 202 #endif /*LV_BUTTONMATRIX_H*/ 203