Overview

The message boxes act as pop-ups. They are built from a background, a text and buttons. The background is a Container object with enabled vertical fit to ensure that the text and the buttons are always visible.

To set the text use the lv_mbox_set_text(mbox, "My text") function.

The buttons are a Button matrix. To add buttons use the lv_mbox_add_btns(mbox, btn_str, action) function. In this you can specify the button text e.g (const char * btn_str[] = {"btn1", "btn2", ""}) and add a callback which is called when a button is released. For more information visit the [Button matrix(/object-types/button-matrix-lv_btnm)'s documentation

With lv_mbox_start_auto_close(mbox, delay) the message box can be closed automatically after delay milliseconds with a long animation. The lv_mbox_stop_auto_close(mbox) function will stop a started auto close .

The close animation time can be adjusted by lv_mbox_set_anim_time(mbox, anim_time).

Style usage

Use lv_mbox_set_style(mbox, LV_MBOX_STYLE_..., &style) to set a new style for an element of the message box:

  • LV_MBOX_STYLE_BG specifies the background container's style. style.body for background and style.label for the text appearance. Default: lv_style_pretty
  • LV_MBOX_STYLE_BTN_BG style of the buttons (button matrix) background. Default: lv_style_transp
  • LV_MBOX_STYLE_BTN_REL style of the released buttons. Default: lv_style_btn_rel
  • LV_MBOX_STYLE_BTN_PR style of the pressed buttons. Default: lv_style_btn_pr
  • LV_MBOX_STYLE_BTN_TGL_REL style of the toggled released buttons. Default: lv_style_btn_tgl_rel
  • LV_MBOX_STYLE_BTN_TGL_PR style of the toggled pressed buttons. Default: lv_style_btn_tgl_pr
  • LV_MBOX_STYLE_BTN_INA style of the inactive buttons. Default: lv_style_btn_ina

Note

  • The height of the buttons comes from the font height + 2 × body.vpad of LV_MBOX_STYLE_BTN_REL
Example of Message box in Littlev Graphics Library

						/*Called when a button is clicked*/
static lv_res_t mbox_apply_action(lv_obj_t * mbox, const char * txt)
{
    printf("Mbox button: %s\n", txt);

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

.
.
.
.

/*******************************
 * Create a default message box
 *******************************/

lv_obj_t * mbox1 = lv_mbox_create(lv_scr_act(), NULL);
lv_mbox_set_text(mbox1, "Default message box\n"
                        "with buttons");                    /*Set the text*/
/*Add two buttons*/
static const char * btns[] ={"\221Apply", "\221Close", ""}; /*Button description. '\221' lv_btnm like control char*/
lv_mbox_add_btns(mbox1, btns, NULL);
lv_obj_set_width(mbox1, 250);
lv_obj_align(mbox1, NULL, LV_ALIGN_IN_TOP_LEFT, 10, 10); /*Align to the corner*/

/****************************************
 * Create a message box with new styles
 ***************************************/

/*Create a new background style*/
static lv_style_t style_bg;
lv_style_copy(&style_bg, &lv_style_pretty);
style_bg.body.main_color = LV_COLOR_MAKE(0xf5, 0x45, 0x2e);
style_bg.body.grad_color = LV_COLOR_MAKE(0xb9, 0x1d, 0x09);
style_bg.body.border.color = LV_COLOR_MAKE(0x3f, 0x0a, 0x03);
style_bg.text.color = LV_COLOR_WHITE;
style_bg.body.padding.hor = 12;
style_bg.body.padding.ver = 8;
style_bg.body.shadow.width = 8;

/*Create released and pressed button styles*/
static lv_style_t style_btn_rel;
static lv_style_t style_btn_pr;
lv_style_copy(&style_btn_rel, &lv_style_btn_rel);
style_btn_rel.body.empty = 1;                    /*Draw only the border*/
style_btn_rel.body.border.color = LV_COLOR_WHITE;
style_btn_rel.body.border.width = 2;
style_btn_rel.body.border.opa = LV_OPA_70;
style_btn_rel.body.padding.hor = 12;
style_btn_rel.body.padding.ver = 8;

lv_style_copy(&style_btn_pr, &style_btn_rel);
style_btn_pr.body.empty = 0;
style_btn_pr.body.main_color = LV_COLOR_MAKE(0x5d, 0x0f, 0x04);
style_btn_pr.body.grad_color = LV_COLOR_MAKE(0x5d, 0x0f, 0x04);

/*Copy the message box (The buttons will be copied too)*/
lv_obj_t * mbox2 = lv_mbox_create(lv_scr_act(), mbox1);
lv_mbox_set_text(mbox2, "Message box with\n"
                        "with modified styles");
lv_mbox_set_style(mbox2, LV_MBOX_STYLE_BG, &style_bg);
lv_mbox_set_style(mbox2, LV_MBOX_STYLE_BTN_REL, &style_btn_rel);
lv_mbox_set_style(mbox2, LV_MBOX_STYLE_BTN_PR, &style_btn_pr);
lv_obj_align(mbox2, mbox1, LV_ALIGN_OUT_BOTTOM_LEFT, 50, -20);   /*Align according to the previous message box */

lv_obj_t *

lv_mbox_create

(lv_obj_t * par, lv_obj_t * copy);

Create a message box objects

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

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

return pointer to the created message box

void

lv_mbox_add_btns

(lv_obj_t * mbox, const char **btn_map, lv_btnm_action_t action);

Add button to the message box

mbox pointer to message box object

btn_map button descriptor (button matrix map).
E.g. a const char *txt[] = {"ok", "close", ""} (Can not be local variable)

action a function which will be called when a button is released

void

lv_mbox_set_text

(lv_obj_t * mbox, const char * txt);

Set the text of the message box

mbox pointer to a message box

txt a '\0' terminated character string which will be the message box text

void

lv_mbox_set_action

(lv_obj_t * mbox, lv_btnm_action_t action);

Stop the action to call when button is released

mbox pointer to a message box object

pointer to an 'lv_btnm_action_t' action

void

lv_mbox_set_anim_time

(lv_obj_t * mbox, uint16_t anim_time);

Set animation duration

mbox pointer to a message box object

anim_time animation length in milliseconds (0: no animation)

void

lv_mbox_start_auto_close

(lv_obj_t * mbox, uint16_t delay);

Automatically delete the message box after a given time

mbox pointer to a message box object

delay a time (in milliseconds) to wait before delete the message box

void

lv_mbox_stop_auto_close

(lv_obj_t * mbox);

Stop the auto. closing of message box

mbox pointer to a message box object

void

lv_mbox_set_style

(lv_obj_t *mbox, lv_mbox_style_t type, lv_style_t *style);

Set a style of a message box

mbox pointer to a message box object

type which style should be set

style pointer to a style

const

char

* lv_mbox_get_text(lv_obj_t * mbox);

Get the text of the message box

mbox pointer to a message box object

return pointer to the text of the message box

lv_obj_t *

lv_mbox_get_from_btn

(lv_obj_t * btn);

Get the message box object from one of its button.
It is useful in the button release actions where only the button is known

btn pointer to a button of a message box

return pointer to the button's message box

uint16_t

lv_mbox_get_anim_time

(lv_obj_t * mbox);

Get the animation duration (close animation time)

mbox pointer to a message box object

return animation length in milliseconds (0: no animation)

lv_style_t *

lv_mbox_get_style

(lv_obj_t *mbox, lv_mbox_style_t type);

Get a style of a message box

mbox pointer to a message box object

type which style should be get

return style pointer to a 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