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