Overview

Buttons can react on user press, release or long press via callback functions (lv_action_t function pointers). You can set the callback functions with: lv_btn_set_action(btn, ACTION_TYPE, callback_func) The possible action types are:

  • LV_BTN_ACTION_CLICK: the button is released after pressing (clicked)
  • LV_BTN_ACTION_PR: the button is pressed
  • LV_BTN_ACTION_LONG_PR: the button is long pressed
  • LV_BTN_ACTION_LONG_PR_REPEAT: the button is long pressed and this action is triggered periodically

A buttons can be in one of the five possible states:

  • LV_BTN_STATE_REL Released state
  • LV_BTN_STATE_PR Pressed state
  • LV_BTN_STATE_TGL_REL Toggled released state (On state)
  • LV_BTN_STATE_TGL_PR Toggled pressed state (On pressed state)
  • LV_BTN_STATE_INA Inactive state

The buttons can be configured as toggle button with lv_btn_set_toggle(btn, true). In this case on release the button goes to toggled released state.

You can set the button's state manually by: lv_btn_set_state(btn, LV_BTN_STATE_TGL_REL)

A button can go to Inactive state only manually (by lv_btn_set_state()). In Inactive state none of the action will be called.

Similarly to Containers buttons also have layout and auto fit:

  • lv_btn_set_layout(btn, LV_LAYOUT_...) set a layout. The default is LV_LAYOUT_CENTER. So if you add a label then it will automatically aligned to the middle.
  • lv_btn_set_fit(btn, hor_en, ver_en) enables to set the button width and/or height automatically according to the children.

Style usage

A button van have 5 independent styles for the 5 state. You ca set them via: lv_btn_set_style(btn, LV_BTN_STYLE_..., &style). The styles uses the style.body properties.

  • LV_BTN_STYLE_REL style of the released state. Default: lv_style_btn_rel
  • LV_BTN_STYLE_PR style of the pressed state. Default: lv_style_btn_pr
  • LV_BTN_STYLE_TGL_REL style of the toggled released state. Default: lv_style_btn_tgl_rel
  • LV_BTN_STYLE_TGL_PR style of the toggled pressed state. Default: lv_style_btn_tgl_pr
  • LV_BTN_STYLE_INA style of the inactive state. Default: lv_style_btn_ina

Notes

  • If a button is dragged its click and long press action will not be called
  • If a button was long pressed and its long press action was set then its click action will not be called
Example of Button in Littlev Graphics Library

						static lv_res_t btn_click_action(lv_obj_t * btn)
{
    uint8_t id = lv_obj_get_free_num(btn);

    printf("Button %d is released\n", id);

    /* The button is released.
     * Make something here */

    return LV_RES_OK; /*Return OK if the button is not deleted*/
}

.
.
.

/*Create a title label*/
lv_obj_t * label = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(label, "Default buttons");
lv_obj_align(label, NULL, LV_ALIGN_IN_TOP_MID, 0, 5);

/*Create a normal button*/
lv_obj_t * btn1 = lv_btn_create(lv_scr_act(), NULL);
lv_cont_set_fit(btn1, true, true); /*Enable resizing horizontally and vertically*/
lv_obj_align(btn1, label, LV_ALIGN_OUT_BOTTOM_MID, 0, 10);
lv_obj_set_free_num(btn1, 1);   /*Set a unique number for the button*/
lv_btn_set_action(btn1, LV_BTN_ACTION_CLICK, btn_click_action);

/*Add a label to the button*/
label = lv_label_create(btn1, NULL);
lv_label_set_text(label, "Normal");

/*Copy the button and set toggled state. (The release action is copied too)*/
lv_obj_t * btn2 = lv_btn_create(lv_scr_act(), btn1);
lv_obj_align(btn2, btn1, LV_ALIGN_OUT_BOTTOM_MID, 0, 10);
lv_btn_set_state(btn2, LV_BTN_STATE_TGL_REL);  /*Set toggled state*/
lv_obj_set_free_num(btn2, 2);               /*Set a unique number for the button*/

/*Add a label to the toggled button*/
label = lv_label_create(btn2, NULL);
lv_label_set_text(label, "Toggled");

/*Copy the button and set inactive state.*/
lv_obj_t * btn3 = lv_btn_create(lv_scr_act(), btn1);
lv_obj_align(btn3, btn2, LV_ALIGN_OUT_BOTTOM_MID, 0, 10);
lv_btn_set_state(btn3, LV_BTN_STATE_INA);   /*Set inactive state*/
lv_obj_set_free_num(btn3, 3);               /*Set a unique number for the button*/

/*Add a label to the inactive button*/
label = lv_label_create(btn3, NULL);
lv_label_set_text(label, "Inactive");

lv_obj_t *

lv_btn_create

(lv_obj_t * par, lv_obj_t * copy);

Create a button objects

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

copy pointer to a button object, if not NULL then the new object will be copied from it

return pointer to the created button

void

lv_btn_set_toggle

(lv_obj_t * btn, bool tgl);

Enable the toggled states. On release the button will change from/to toggled state.

btn pointer to a button object

tgl true: enable toggled states, false: disable

void

lv_btn_set_state

(lv_obj_t * btn, lv_btn_state_t state);

Set the state of the button

btn pointer to a button object

state the new state of the button (from lv_btn_state_t enum)

void

lv_btn_toggle

(lv_obj_t * btn);

Toggle the state of the button (ON->OFF, OFF->ON)

btn pointer to a button object

void

lv_btn_set_action

(lv_obj_t * btn, lv_btn_action_t type, lv_action_t action);

Set a function to call when the button event happens

btn pointer to a button object

action type of event form 'lv_action_t' (press, release, long press, long press repeat)

void

lv_btn_set_layout

(lv_obj_t * btn, lv_layout_t layout);

Set the layout on a button

btn pointer to a button object

layout a layout from 'lv_cont_layout_t'

void

lv_btn_set_fit

(lv_obj_t * btn, bool hor_en, bool ver_en);

Enable the horizontal or vertical fit.
The button size will be set to involve the children horizontally or vertically.

btn pointer to a button object

hor_en true: enable the horizontal fit

ver_en true: enable the vertical fit

void

lv_btn_set_style

(lv_obj_t * btn, lv_btn_style_t type, lv_style_t *style);

Set a style of a button.

btn pointer to button object

type which style should be set

style pointer to a style

lv_btn_state_t

lv_btn_get_state

(lv_obj_t * btn);

Get the current state of the button

btn pointer to a button object

return the state of the button (from lv_btn_state_t enum)

bool

lv_btn_get_toggle

(lv_obj_t * btn);

Get the toggle enable attribute of the button

btn pointer to a button object

return ture: toggle enabled, false: disabled

lv_action_t

lv_btn_get_action

(lv_obj_t * btn, lv_btn_action_t type);

Get the release action of a button

btn pointer to a button object

return pointer to the release action function

lv_layout_t

lv_btn_get_layout

(lv_obj_t * btn);

Get the layout of a button

btn pointer to button object

return the layout from 'lv_cont_layout_t'

bool

lv_btn_get_hor_fit

(lv_obj_t * btn);

Get horizontal fit enable attribute of a button

btn pointer to a button object

return true: horizontal fit is enabled; false: disabled

bool

lv_btn_get_ver_fit

(lv_obj_t * btn);

Get vertical fit enable attribute of a container

btn pointer to a button object

return true: vertical fit is enabled; false: disabled

lv_style_t *

lv_btn_get_style

(lv_obj_t * btn, lv_btn_style_t type);

Get style of a button.

btn pointer to button object

type which style should be get

return style pointer to the style

LittlevGL - Open-source Embedded GUI Library

LittlevGL is a free and open-source graphics library providing everything you need to create embedded GUI with easy-to-use graphical elements, beautiful visual effects and low memory footprint.

If you like LittlevGL, please
support its deveopment!


The founder of Littlev Graphics Library (LittlevGL) and related software modules is:
Gábor Kiss-Vámosi
All Rights Reserved ©  2018 Hungary