acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
Log | Files | Refs | Archive | README | LICENSE

lv_btnmatrix.h (8927B)

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