lv_btnmatrix.h

Defines

LV_BTNMATRIX_BTN_NONE

Typedefs

typedef _lv_btnmatrix_ctrl_t lv_btnmatrix_ctrl_t
typedef bool (*lv_btnmatrix_btn_draw_cb_t)(lv_obj_t *btnm, uint32_t btn_id, const lv_area_t *draw_area, const lv_area_t *clip_area)

Enums

enum _lv_btnmatrix_ctrl_t

Type to store button control bits (disabled, hidden etc.) The first 3 bits are used to store the width

Values:

enumerator _LV_BTNMATRIX_WIDTH

Reserved to store the size units

enumerator LV_BTNMATRIX_CTRL_HIDDEN

Button hidden

enumerator LV_BTNMATRIX_CTRL_NO_REPEAT

Do not repeat press this button.

enumerator LV_BTNMATRIX_CTRL_DISABLED

Disable this button.

enumerator LV_BTNMATRIX_CTRL_CHECKABLE

The button can be toggled.

enumerator LV_BTNMATRIX_CTRL_CHECKED

Button is currently toggled (e.g. checked).

enumerator LV_BTNMATRIX_CTRL_CLICK_TRIG

1: Send LV_EVENT_VALUE_CHANGE on CLICK, 0: Send LV_EVENT_VALUE_CHANGE on PRESS

enumerator LV_BTNMATRIX_CTRL_POPOVER

Show a popover when pressing this key

enumerator LV_BTNMATRIX_CTRL_RECOLOR

Enable text recoloring with #color

enumerator _LV_BTNMATRIX_CTRL_RESERVED_1

Reserved for later use

enumerator _LV_BTNMATRIX_CTRL_RESERVED_2

Reserved for later use

enumerator LV_BTNMATRIX_CTRL_CUSTOM_1

Custom free to use flag

enumerator LV_BTNMATRIX_CTRL_CUSTOM_2

Custom free to use flag

enum lv_btnmatrix_draw_part_type_t

type field in lv_obj_draw_part_dsc_t if class_p = lv_btnmatrix_class Used in LV_EVENT_DRAW_PART_BEGIN and LV_EVENT_DRAW_PART_END

Values:

enumerator LV_BTNMATRIX_DRAW_PART_BTN

The rectangle and label of buttons

Functions

lv_obj_t *lv_btnmatrix_create(lv_obj_t *parent)

Create a button matrix object

Parameters:

parent -- pointer to an object, it will be the parent of the new button matrix

Returns:

pointer to the created button matrix

void lv_btnmatrix_set_map(lv_obj_t *obj, const char *map[])

Set a new map. Buttons will be created/deleted according to the map. The button matrix keeps a reference to the map and so the string array must not be deallocated during the life of the matrix.

Parameters:

  • obj -- pointer to a button matrix object

  • map -- pointer a string array. The last string has to be: "". Use "\n" to make a line break.

void lv_btnmatrix_set_ctrl_map(lv_obj_t *obj, const lv_btnmatrix_ctrl_t ctrl_map[])

Set the button control map (hidden, disabled etc.) for a button matrix. The control map array will be copied and so may be deallocated after this function returns.

Parameters:

  • obj -- pointer to a button matrix object

  • ctrl_map -- pointer to an array of lv_btn_ctrl_t control bytes. The length of the array and position of the elements must match the number and order of the individual buttons (i.e. excludes newline entries). An element of the map should look like e.g.: ctrl_map[0] = width | LV_BTNMATRIX_CTRL_NO_REPEAT | LV_BTNMATRIX_CTRL_TGL_ENABLE

void lv_btnmatrix_set_selected_btn(lv_obj_t *obj, uint16_t btn_id)

Set the selected buttons

Parameters:

  • obj -- pointer to button matrix object

  • btn_id -- 0 based index of the button to modify. (Not counting new lines)

void lv_btnmatrix_set_btn_ctrl(lv_obj_t *obj, uint16_t btn_id, lv_btnmatrix_ctrl_t ctrl)

Set the attributes of a button of the button matrix

Parameters:

  • obj -- pointer to button matrix object

  • btn_id -- 0 based index of the button to modify. (Not counting new lines)

  • ctrl -- OR-ed attributs. E.g. LV_BTNMATRIX_CTRL_NO_REPEAT | LV_BTNMATRIX_CTRL_CHECKABLE

void lv_btnmatrix_clear_btn_ctrl(lv_obj_t *obj, uint16_t btn_id, lv_btnmatrix_ctrl_t ctrl)

Clear the attributes of a button of the button matrix

Parameters:

  • obj -- pointer to button matrix object

  • btn_id -- 0 based index of the button to modify. (Not counting new lines)

  • ctrl -- OR-ed attributs. E.g. LV_BTNMATRIX_CTRL_NO_REPEAT | LV_BTNMATRIX_CTRL_CHECKABLE

void lv_btnmatrix_set_btn_ctrl_all(lv_obj_t *obj, lv_btnmatrix_ctrl_t ctrl)

Set attributes of all buttons of a button matrix

Parameters:

  • obj -- pointer to a button matrix object

  • ctrl -- attribute(s) to set from lv_btnmatrix_ctrl_t. Values can be ORed.

void lv_btnmatrix_clear_btn_ctrl_all(lv_obj_t *obj, lv_btnmatrix_ctrl_t ctrl)

Clear the attributes of all buttons of a button matrix

Parameters:

  • obj -- pointer to a button matrix object

  • ctrl -- attribute(s) to set from lv_btnmatrix_ctrl_t. Values can be ORed.

  • en -- true: set the attributes; false: clear the attributes

void lv_btnmatrix_set_btn_width(lv_obj_t *obj, uint16_t btn_id, uint8_t width)

Set a single button's relative width. This method will cause the matrix be regenerated and is a relatively expensive operation. It is recommended that initial width be specified using lv_btnmatrix_set_ctrl_map and this method only be used for dynamic changes.

Parameters:

  • obj -- pointer to button matrix object

  • btn_id -- 0 based index of the button to modify.

  • width -- relative width compared to the buttons in the same row. [1..7]

void lv_btnmatrix_set_one_checked(lv_obj_t *obj, bool en)

Make the button matrix like a selector widget (only one button may be checked at a time). LV_BTNMATRIX_CTRL_CHECKABLE must be enabled on the buttons to be selected using lv_btnmatrix_set_ctrl() or lv_btnmatrix_set_btn_ctrl_all().

Parameters:

  • obj -- pointer to a button matrix object

  • en -- whether "one check" mode is enabled

const char **lv_btnmatrix_get_map(const lv_obj_t *obj)

Get the current map of a button matrix

Parameters:

obj -- pointer to a button matrix object

Returns:

the current map

uint16_t lv_btnmatrix_get_selected_btn(const lv_obj_t *obj)

Get the index of the lastly "activated" button by the user (pressed, released, focused etc) Useful in the event_cb to get the text of the button, check if hidden etc.

Parameters:

obj -- pointer to button matrix object

Returns:

index of the last released button (LV_BTNMATRIX_BTN_NONE: if unset)

const char *lv_btnmatrix_get_btn_text(const lv_obj_t *obj, uint16_t btn_id)

Get the button's text

Parameters:

  • obj -- pointer to button matrix object

  • btn_id -- the index a button not counting new line characters.

Returns:

text of btn_index` button

bool lv_btnmatrix_has_btn_ctrl(lv_obj_t *obj, uint16_t btn_id, lv_btnmatrix_ctrl_t ctrl)

Get the whether a control value is enabled or disabled for button of a button matrix

Parameters:

  • obj -- pointer to a button matrix object

  • btn_id -- the index of a button not counting new line characters.

  • ctrl -- control values to check (ORed value can be used)

Returns:

true: the control attribute is enabled false: disabled

bool lv_btnmatrix_get_one_checked(const lv_obj_t *obj)

Tell whether "one check" mode is enabled or not.

Parameters:

obj -- Button matrix object

Returns:

true: "one check" mode is enabled; false: disabled

Variables

const lv_obj_class_t lv_btnmatrix_class
struct lv_btnmatrix_t

Public Members

lv_obj_t obj
const char **map_p
lv_area_t *button_areas
lv_btnmatrix_ctrl_t *ctrl_bits
uint16_t btn_cnt
uint16_t row_cnt
uint16_t btn_id_sel
uint8_t one_check