[中文]

Message Box (lv_msgbox)

Overview

Message boxes act as pop-ups. They are built from a content area with a helper to add text, an optional header (which can have a title, a close button, and other buttons), and an optional footer with buttons.

The text will be broken into multiple lines and the height will be set automatically. If the height is set manually, the content will become scrollable.

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.

Usage

Create a message box

lv_msgbox_create(parent) creates a message box. If parent is NULL the message box will be modal.

E.g. const char * btn_txts[] = {"Ok", "Cancel", NULL}.

Get the parts

The building blocks of the message box can be obtained using the following functions:

lv_obj_t * lv_msgbox_get_content(lv_obj_t * widget);
lv_obj_t * lv_msgbox_get_title(lv_obj_t * widget);
lv_obj_t * lv_msgbox_get_header(lv_obj_t * widget);
lv_obj_t * lv_msgbox_get_footer(lv_obj_t * widget);

Functions that add something to the message box return the newly added Widget:

lv_obj_t * lv_msgbox_add_text(lv_obj_t * widget, const char * text);
lv_obj_t * lv_msgbox_add_title(lv_obj_t * widget, const char * title);
lv_obj_t * lv_msgbox_add_close_button(lv_obj_t * widget);
lv_obj_t * lv_msgbox_add_header_button(lv_obj_t * widget, const void * icon);
lv_obj_t * lv_msgbox_add_footer_button(lv_obj_t * widget, const char * text);

Close the message box

lv_msgbox_close(msgbox) closes (deletes) the message box.

lv_msgbox_close_async(msgbox) closes (deletes) the message box asynchronously. This is useful if you want the message box to close the on the next call to lv_timer_handler instead of immediately.

Events

No special events are sent by this widget.

Further Reading

Learn more about Base-Widget Events emitted by all Widgets.

Learn more about Events.

Keys

No Keys are processed by Msgbox Widgets.

Further Reading

Learn more about Keys.

Example

[中文]

Simple Message box

#include "../../lv_examples.h"
#if LV_USE_MSGBOX && LV_BUILD_EXAMPLES

static void event_cb(lv_event_t * e)
{
    lv_obj_t * btn = lv_event_get_target(e);
    lv_obj_t * label = lv_obj_get_child(btn, 0);
    LV_UNUSED(label);
    LV_LOG_USER("Button %s clicked", lv_label_get_text(label));
}

void lv_example_msgbox_1(void)
{
    lv_obj_t * mbox1 = lv_msgbox_create(NULL);

    lv_msgbox_add_title(mbox1, "Hello");

    lv_msgbox_add_text(mbox1, "This is a message box with two buttons.");
    lv_msgbox_add_close_button(mbox1);

    lv_obj_t * btn;
    btn = lv_msgbox_add_footer_button(mbox1, "Apply");
    lv_obj_add_event_cb(btn, event_cb, LV_EVENT_CLICKED, NULL);
    btn = lv_msgbox_add_footer_button(mbox1, "Cancel");
    lv_obj_add_event_cb(btn, event_cb, LV_EVENT_CLICKED, NULL);
    return;
}

#endif

Scrolling and styled Message box

#include "../../lv_examples.h"
#if LV_USE_MSGBOX && LV_BUILD_EXAMPLES

static void minimize_button_event_cb(lv_event_t * e)
{
    lv_obj_t * mbox = (lv_obj_t *) lv_event_get_user_data(e);
    lv_obj_add_flag(mbox, LV_OBJ_FLAG_HIDDEN);
}

void lv_example_msgbox_2(void)
{
    lv_obj_t * setting = lv_msgbox_create(lv_screen_active());
    lv_obj_set_style_clip_corner(setting, true, 0);

    /* setting fixed size */
    lv_obj_set_size(setting, 300, 200);

    /* setting's titlebar/header */
    lv_msgbox_add_title(setting, "Setting");
    lv_obj_t * minimize_button = lv_msgbox_add_header_button(setting, LV_SYMBOL_MINUS);
    lv_obj_add_event_cb(minimize_button, minimize_button_event_cb, LV_EVENT_CLICKED, setting);
    lv_msgbox_add_close_button(setting);

    /* setting's content*/
    lv_obj_t * content = lv_msgbox_get_content(setting);
    lv_obj_set_flex_flow(content, LV_FLEX_FLOW_COLUMN);
    lv_obj_set_flex_align(content, LV_FLEX_ALIGN_START, LV_FLEX_ALIGN_CENTER, LV_FLEX_ALIGN_CENTER);
    lv_obj_set_style_pad_right(content, -1, LV_PART_SCROLLBAR);

    lv_obj_t * cont_brightness = lv_obj_create(content);
    lv_obj_set_size(cont_brightness, lv_pct(100), LV_SIZE_CONTENT);
    lv_obj_set_flex_flow(cont_brightness, LV_FLEX_FLOW_COLUMN);
    lv_obj_set_flex_align(cont_brightness, LV_FLEX_ALIGN_CENTER,  LV_FLEX_ALIGN_START, LV_FLEX_ALIGN_CENTER);

    lv_obj_t * lb_brightness = lv_label_create(cont_brightness);
    lv_label_set_text(lb_brightness, "Brightness : ");
    lv_obj_t * slider_brightness = lv_slider_create(cont_brightness);
    lv_obj_set_width(slider_brightness, lv_pct(100));
    lv_slider_set_value(slider_brightness, 50, LV_ANIM_OFF);

    lv_obj_t * cont_speed = lv_obj_create(content);
    lv_obj_set_size(cont_speed, lv_pct(100), LV_SIZE_CONTENT);
    lv_obj_set_flex_flow(cont_speed, LV_FLEX_FLOW_COLUMN);
    lv_obj_set_flex_align(cont_speed, LV_FLEX_ALIGN_CENTER,  LV_FLEX_ALIGN_START, LV_FLEX_ALIGN_CENTER);

    lv_obj_t * lb_speed = lv_label_create(cont_speed);
    lv_label_set_text(lb_speed, "Speed : ");
    lv_obj_t * slider_speed = lv_slider_create(cont_speed);
    lv_obj_set_width(slider_speed, lv_pct(100));
    lv_slider_set_value(slider_speed, 80, LV_ANIM_OFF);

    /* footer */
    lv_obj_t * apply_button = lv_msgbox_add_footer_button(setting, "Apply");
    lv_obj_set_flex_grow(apply_button, 1);

    lv_obj_t * cancel_button = lv_msgbox_add_footer_button(setting, "Cancel");
    lv_obj_set_flex_grow(cancel_button, 1);

    lv_obj_t * footer = lv_msgbox_get_footer(setting);
    lv_obj_set_style_bg_color(footer, lv_palette_main(LV_PALETTE_INDIGO), 0);
    lv_obj_set_style_bg_opa(footer, LV_OPA_100, 0);
}
#endif

API

lv_msgbox.h

lv_types.h