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 and lv_event_get_current_target(e) will return the message box. lv_msgbox_get_active_btn(msgbox) and lv_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

MicroPython code  

 GitHub Simulator

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

参数

• 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

返回

pointer to the message box object

lv_obj_t *lv_msgbox_get_title(lv_obj_t *obj)

lv_obj_t *lv_msgbox_get_close_btn(lv_obj_t *obj)

lv_obj_t *lv_msgbox_get_text(lv_obj_t *obj)

lv_obj_t *lv_msgbox_get_content(lv_obj_t *obj)

lv_obj_t *lv_msgbox_get_btns(lv_obj_t *obj)

uint16_t lv_msgbox_get_active_btn(lv_obj_t *mbox)

Get the index of the selected button

参数

mbox -- message box object

返回

index of the button (LV_BTNMATRIX_BTN_NONE: if unset)

const char *lv_msgbox_get_active_btn_text(lv_obj_t *mbox)

void lv_msgbox_close(lv_obj_t *mbox)

void lv_msgbox_close_async(lv_obj_t *mbox)

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

Public Members

lv_obj_t obj

lv_obj_t *title

lv_obj_t *close_btn

lv_obj_t *content

lv_obj_t *text

lv_obj_t *btns