Message box (lv_msgbox)¶
Overview¶
The Message boxes act as pop-ups. They are built from a background container, a title, an optional close button, a text and optional buttons.
The text will be broken into multiple lines automatically and the height will be set automatically to include the text and the buttons.
The message box can be modal (blocking clicks on the rest of the screen) or not modal.
Parts and Styles¶
The message box is built from other widgets, so you can check these widgets' documentation for details.
Background: lv_obj
Close button: lv_btn
Title and text: lv_label
Buttons: lv_btnmatrix
Usage¶
Create a message box¶
lv_msgbox_create(parent, title, txt, btn_txts[], add_close_btn)
creates a message box.
If parent
is NULL
the message box will be modal. title
and txt
are strings for the title and the text.
btn_txts[]
is an array with the buttons' text. E.g. const char * btn_txts[] = {"Ok", "Cancel", NULL}
.
add_colse_btn
can be true
or false
to add/don't add a close button.
Get the parts¶
The building blocks of the message box can be obtained using the following functions:
lv_obj_t * lv_msgbox_get_title(lv_obj_t * mbox);
lv_obj_t * lv_msgbox_get_close_btn(lv_obj_t * mbox);
lv_obj_t * lv_msgbox_get_text(lv_obj_t * mbox);
lv_obj_t * lv_msgbox_get_btns(lv_obj_t * mbox);
Close the message box¶
lv_msgbox_close(msgbox)
closes (deletes) the message box.
Events¶
LV_EVENT_VALUE_CHANGED
is sent by the buttons if one of them is clicked.LV_OBJ_FLAG_EVENT_BUBBLE
is enabled on the buttons so you can add events to the message box itself. In the event handler,lv_event_get_target(e)
will return the button matrix andlv_event_get_current_target(e)
will return the message box.lv_msgbox_get_active_btn(msgbox)
andlv_msgbox_get_active_btn_text(msgbox)
can be used to get the index and text of the clicked button.
Learn more about Events.
Keys¶
Keys have effect on the close button and button matrix. You can add them manually to a group if required.
Learn more about Keys.
Example¶
Simple Message box¶
C code
GitHub#include "../../lv_examples.h"
#if LV_USE_MSGBOX && LV_BUILD_EXAMPLES
static void event_cb(lv_event_t * e)
{
lv_obj_t * obj = lv_event_get_current_target(e);
LV_LOG_USER("Button %s clicked", lv_msgbox_get_active_btn_text(obj));
}
void lv_example_msgbox_1(void)
{
static const char * btns[] ={"Apply", "Close", ""};
lv_obj_t * mbox1 = lv_msgbox_create(NULL, "Hello", "This is a message box with two buttons.", btns, true);
lv_obj_add_event_cb(mbox1, event_cb, LV_EVENT_VALUE_CHANGED, NULL);
lv_obj_center(mbox1);
}
#endif
def event_cb(e):
mbox = e.get_current_target()
print("Button %s clicked" % mbox.get_active_btn_text())
btns = ["Apply", "Close", ""]
mbox1 = lv.msgbox(lv.scr_act(), "Hello", "This is a message box with two buttons.", btns, True)
mbox1.add_event_cb(event_cb, lv.EVENT.VALUE_CHANGED, None)
mbox1.center()
API¶
Functions
-
lv_obj_t *lv_msgbox_create(lv_obj_t *parent, const char *title, const char *txt, const char *btn_txts[], bool add_close_btn)¶
Create a message box object
- Parameters
parent -- pointer to parent or NULL to create a full screen modal message box
title -- the title of the message box
txt -- the text of the message box
btn_txts -- the buttons as an array of texts terminated by an "" element. E.g. {"btn1", "btn2", ""}
add_close_btn -- true: add a close button
- Returns
pointer to the message box object
Variables
-
const lv_obj_class_t lv_msgbox_class¶
-
const lv_obj_class_t lv_msgbox_content_class¶
-
const lv_obj_class_t lv_msgbox_backdrop_class¶
-
struct lv_msgbox_t¶