Message box (lv_msdbox)¶
Overview¶
The Message boxes act as pop-ups. They are built from a background Container, a Label and a Button matrix for buttons.
The text will be broken into multiple lines automatically (has LV_LABEL_LONG_MODE_BREAK
) and the height will be set automatically to involve the text and the buttons (LV_FIT_TIGHT
fit vertically)-
Parts and Styles¶
The Message box's main part is called LV_MSGBOX_PART_MAIN
and it uses all the typical background style properties. Using padding will add space on the sides. pad_inner will add space between the text and the buttons.
The label style properties affect the style of text.
The buttons parts are the same as in case of Button matrix:
LV_MSGBOX_PART_BTN_BG
the background of the buttonsLV_MSGBOX_PART_BTN
the buttons
Usage¶
Set text¶
To set the text use the lv_msgbox_set_text(msgbox, "My text")
function. Not only the pointer of the text will be saved, so the the text can be in a local variable too.
Add buttons¶
To add buttons use the lv_msgbox_add_btns(msgbox, btn_str)
function. The button's text needs to be specified like const char * btn_str[] = {"Apply", "Close", ""}
.
For more information visit the Button matrix documentation.
The button matrix will be created only when lv_msgbox_add_btns()
is called for the first time.
Auto-close¶
With lv_msgbox_start_auto_close(mbox, delay)
the message box can be closed automatically after delay
milliseconds with an animation. The lv_mbox_stop_auto_close(mbox)
function stops a started auto close.
The duration of the close animation can be set by lv_mbox_set_anim_time(mbox, anim_time)
.
Events¶
Besides the Generic events the following Special events are sent by the Message boxes:
LV_EVENT_VALUE_CHANGED sent when the button is clicked. The event data is set to ID of the clicked button.
The Message box has a default event callback which closes itself when a button is clicked.
Learn more about Events.
##Keys
The following Keys are processed by the Buttons:
LV_KEY_RIGHT/DOWN Select the next button
LV_KEY_LEFT/TOP Select the previous button
LV_KEY_ENTER Clicks the selected button
Learn more about Keys.
Example¶
C¶
Simple Message box¶
code
#include "../../../lv_examples.h"
#include <stdio.h>
#if LV_USE_MSGBOX
static void event_handler(lv_obj_t * obj, lv_event_t event)
{
if(event == LV_EVENT_VALUE_CHANGED) {
printf("Button: %s\n", lv_msgbox_get_active_btn_text(obj));
}
}
void lv_ex_msgbox_1(void)
{
static const char * btns[] ={"Apply", "Close", ""};
lv_obj_t * mbox1 = lv_msgbox_create(lv_scr_act(), NULL);
lv_msgbox_set_text(mbox1, "A message box with two buttons.");
lv_msgbox_add_btns(mbox1, btns);
lv_obj_set_width(mbox1, 200);
lv_obj_set_event_cb(mbox1, event_handler);
lv_obj_align(mbox1, NULL, LV_ALIGN_CENTER, 0, 0); /*Align to the corner*/
}
#endif
Modal¶
code
#include "../../../lv_examples.h"
#if LV_USE_MSGBOX
static void mbox_event_cb(lv_obj_t *obj, lv_event_t evt);
static void btn_event_cb(lv_obj_t *btn, lv_event_t evt);
static void opa_anim(void * bg, lv_anim_value_t v);
static lv_obj_t *mbox, *info;
static lv_style_t style_modal;
static const char welcome_info[] = "Welcome to the modal message box demo!\n"
"Press the button to display a message box.";
static const char in_msg_info[] = "Notice that you cannot touch "
"the button again while the message box is open.";
void lv_ex_msgbox_2(void)
{
lv_style_init(&style_modal);
lv_style_set_bg_color(&style_modal, LV_STATE_DEFAULT, LV_COLOR_BLACK);
/* Create a button, then set its position and event callback */
lv_obj_t *btn = lv_btn_create(lv_scr_act(), NULL);
lv_obj_set_size(btn, 200, 60);
lv_obj_set_event_cb(btn, btn_event_cb);
lv_obj_align(btn, NULL, LV_ALIGN_IN_TOP_LEFT, 20, 20);
/* Create a label on the button */
lv_obj_t *label = lv_label_create(btn, NULL);
lv_label_set_text(label, "Display a message box!");
/* Create an informative label on the screen */
info = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(info, welcome_info);
lv_label_set_long_mode(info, LV_LABEL_LONG_BREAK); /* Make sure text will wrap */
lv_obj_set_width(info, LV_HOR_RES - 10);
lv_obj_align(info, NULL, LV_ALIGN_IN_BOTTOM_LEFT, 5, -5);
}
static void mbox_event_cb(lv_obj_t *obj, lv_event_t evt)
{
if(evt == LV_EVENT_DELETE && obj == mbox) {
/* Delete the parent modal background */
lv_obj_del_async(lv_obj_get_parent(mbox));
mbox = NULL; /* happens before object is actually deleted! */
lv_label_set_text(info, welcome_info);
} else if(evt == LV_EVENT_VALUE_CHANGED) {
/* A button was clicked */
lv_msgbox_start_auto_close(mbox, 0);
}
}
static void btn_event_cb(lv_obj_t *btn, lv_event_t evt)
{
if(evt == LV_EVENT_CLICKED) {
/* Create a full-screen background */
/* Create a base object for the modal background */
lv_obj_t *obj = lv_obj_create(lv_scr_act(), NULL);
lv_obj_reset_style_list(obj, LV_OBJ_PART_MAIN);
lv_obj_add_style(obj, LV_OBJ_PART_MAIN, &style_modal);
lv_obj_set_pos(obj, 0, 0);
lv_obj_set_size(obj, LV_HOR_RES, LV_VER_RES);
static const char * btns2[] = {"Ok", "Cancel", ""};
/* Create the message box as a child of the modal background */
mbox = lv_msgbox_create(obj, NULL);
lv_msgbox_add_btns(mbox, btns2);
lv_msgbox_set_text(mbox, "Hello world!");
lv_obj_align(mbox, NULL, LV_ALIGN_CENTER, 0, 0);
lv_obj_set_event_cb(mbox, mbox_event_cb);
/* Fade the message box in with an animation */
lv_anim_t a;
lv_anim_init(&a);
lv_anim_set_var(&a, obj);
lv_anim_set_time(&a, 500);
lv_anim_set_values(&a, LV_OPA_TRANSP, LV_OPA_50);
lv_anim_set_exec_cb(&a, (lv_anim_exec_xcb_t)opa_anim);
lv_anim_start(&a);
lv_label_set_text(info, in_msg_info);
lv_obj_align(info, NULL, LV_ALIGN_IN_BOTTOM_LEFT, 5, -5);
}
}
static void opa_anim(void * bg, lv_anim_value_t v)
{
lv_obj_set_style_local_bg_opa(bg, LV_OBJ_PART_MAIN, LV_STATE_DEFAULT, v);
}
#endif
MicroPython¶
No examples yet.
API¶
Typedefs
-
typedef uint8_t
lv_msgbox_style_t
¶
Enums
Functions
-
lv_obj_t *
lv_msgbox_create
(lv_obj_t *par, const lv_obj_t *copy)¶ Create a message box objects
- Return
pointer to the created message box
- Parameters
par
: pointer to an object, it will be the parent of the new message boxcopy
: pointer to a message box object, if not NULL then the new object will be copied from it
-
void
lv_msgbox_add_btns
(lv_obj_t *mbox, const char *btn_mapaction[])¶ Add button to the message box
- Parameters
mbox
: pointer to message box objectbtn_map
: button descriptor (button matrix map). E.g. a const char *txt[] = {"ok", "close", ""} (Can not be local variable)
-
void
lv_msgbox_set_text
(lv_obj_t *mbox, const char *txt)¶ Set the text of the message box
- Parameters
mbox
: pointer to a message boxtxt
: a '\0' terminated character string which will be the message box text
-
void
lv_msgbox_set_anim_time
(lv_obj_t *mbox, uint16_t anim_time)¶ Set animation duration
- Parameters
mbox
: pointer to a message box objectanim_time
: animation length in milliseconds (0: no animation)
-
void
lv_msgbox_start_auto_close
(lv_obj_t *mbox, uint16_t delay)¶ Automatically delete the message box after a given time
- Parameters
mbox
: pointer to a message box objectdelay
: a time (in milliseconds) to wait before delete the message box
-
void
lv_msgbox_stop_auto_close
(lv_obj_t *mbox)¶ Stop the auto. closing of message box
- Parameters
mbox
: pointer to a message box object
-
void
lv_msgbox_set_recolor
(lv_obj_t *mbox, bool en)¶ Set whether recoloring is enabled. Must be called after
lv_msgbox_add_btns
.- Parameters
mbox
: pointer to message box objecten
: whether recoloring is enabled
-
const char *
lv_msgbox_get_text
(const lv_obj_t *mbox)¶ Get the text of the message box
- Return
pointer to the text of the message box
- Parameters
mbox
: pointer to a message box object
-
uint16_t
lv_msgbox_get_active_btn
(lv_obj_t *mbox)¶ Get the index of the lastly "activated" button by the user (pressed, released etc) Useful in the
event_cb
.- Return
index of the last released button (LV_BTNMATRIX_BTN_NONE: if unset)
- Parameters
mbox
: pointer to message box object
-
const char *
lv_msgbox_get_active_btn_text
(lv_obj_t *mbox)¶ Get the text of the lastly "activated" button by the user (pressed, released etc) Useful in the
event_cb
.- Return
text of the last released button (NULL: if unset)
- Parameters
mbox
: pointer to message box object
-
uint16_t
lv_msgbox_get_anim_time
(const lv_obj_t *mbox)¶ Get the animation duration (close animation time)
- Return
animation length in milliseconds (0: no animation)
- Parameters
mbox
: pointer to a message box object
-
struct
lv_msgbox_ext_t
¶