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 programmatically, 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.

Content, header, and footer: Base Widget (lv_obj)
Buttons: Button (lv_button)
Title and content text: Label (lv_label)

Usage¶

Create a message box¶

lv_msgbox_create(parent) creates a message box. If parent is NULL the message box will be modal, and will use the Default Display's Top Layer as a parent.

Adding buttons¶

If you want to add an [OK] or [Cancel] or other buttons for the user to have a choice of responses, add each button using the lv_msgbox_add_footer_button(msgbox, btn_text) function. Calling this function adds a footer (container) if one was not already present, and it returns a pointer to the button created, which can be used to add LV_EVENT_CLICKED (or other) events to detect and act on the user's response.

Footer buttons so added are evenly spaced and centered.

Buttons can also be added to the header if desired with lv_msgbox_add_header_button(msgbox, symbol). Buttons so added are added to the right end of the header.

Getting 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 * msgbox);
lv_obj_t * lv_msgbox_get_title(lv_obj_t * msgbox);
lv_obj_t * lv_msgbox_get_header(lv_obj_t * msgbox);
lv_obj_t * lv_msgbox_get_footer(lv_obj_t * msgbox);

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

lv_obj_t * lv_msgbox_add_text(lv_obj_t * msgbox, const char * text);
lv_obj_t * lv_msgbox_add_text_fmt(lv_obj_t * obj, const char * fmt, ...);
lv_obj_t * lv_msgbox_add_title(lv_obj_t * msgbox, const char * title);
lv_obj_t * lv_msgbox_add_close_button(lv_obj_t * msgbox);
lv_obj_t * lv_msgbox_add_header_button(lv_obj_t * msgbox, const void * symbol);
lv_obj_t * lv_msgbox_add_footer_button(lv_obj_t * msgbox, 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 Message Box Widgets. See these Widgets' documentation for details: Button (lv_button) and Label (lv_label).

Keys¶

No Keys are processed by Message Box Widgets.

Examples¶

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_obj(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));
}

/**
 * @title Modal message box with footer buttons
 * @brief A modal "Hello" dialog with Apply and Cancel footer buttons and a close icon.
 *
 * `lv_msgbox_create(NULL)` opens a modal message box on the top
 * layer. `lv_msgbox_add_title` sets the title to `Hello`,
 * `lv_msgbox_add_text` writes the body, and
 * `lv_msgbox_add_close_button` installs the header close icon. Two
 * `lv_msgbox_add_footer_button` calls add `Apply` and `Cancel`, each
 * wired to a shared `LV_EVENT_CLICKED` handler that logs which label
 * was tapped.
 */
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);
}

/**
 * @title Settings dialog with minimize button
 * @brief A 300x200 non-modal settings panel with Brightness and Speed sliders.
 *
 * A non-modal `lv_msgbox` on the active screen gets a header with
 * title `Setting`, a close icon, and a minus header button whose
 * `LV_EVENT_CLICKED` handler hides the panel with
 * `LV_OBJ_FLAG_HIDDEN`. `lv_msgbox_get_content` is flipped to
 * `LV_FLEX_FLOW_COLUMN` and holds two column containers that pair a
 * label with a full-width `lv_slider`, preset to Brightness 50 and
 * Speed 80. The footer adds flex-growing `Apply` and `Cancel`
 * buttons tinted indigo.
 */
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

Message box with blurred background¶

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

static void dropdown_value_changed_event_cb(lv_event_t * e)
{
    lv_obj_t * dropdown = lv_event_get_target_obj(e);
    lv_obj_t * msgbox = (lv_obj_t *)lv_event_get_user_data(e);
    lv_obj_t * top_layer = lv_layer_top();
    uint32_t opt = lv_dropdown_get_selected(dropdown);

    /*Blur screen*/
    if(opt == 0) {
        lv_obj_set_style_blur_radius(msgbox, 0, 0);
        lv_obj_set_style_blur_radius(top_layer, 24, 0);
    }
    /*Blur Message box*/
    else {
        lv_obj_set_style_blur_radius(msgbox, 24, 0);
        lv_obj_set_style_blur_radius(top_layer, 0, 0);
    }
}

/**
 * @title Blurred message box over background
 * @brief Toggle a blur radius between the screen backdrop and the message box itself.
 *
 * A long Lorem ipsum `lv_label` fills 60% width behind a translucent
 * `lv_msgbox` placed on `lv_layer_top()` with a black header and
 * body at `LV_OPA_40` and `blur_backdrop` enabled. A `lv_dropdown`
 * offering `Blur screen` and `Blur msgbox` is anchored at (5, 5); its
 * `LV_EVENT_VALUE_CHANGED` callback sets a blur radius of 24 on
 * either `lv_layer_top()` or the message box. A synthetic event is
 * sent to initialize the state.
 */
void lv_example_msgbox_3(void)
{

    lv_obj_t * label = lv_label_create(lv_screen_active());
    lv_label_set_text(label, "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
                      " Ut orci mauris, placerat et euismod eu, ullamcorper eget massa. "
                      "Suspendisse sodales vitae augue ut vestibulum. "
                      "Nunc fringilla leo ut tellus consectetur tincidunt. "
                      "Quisque eu tortor semper odio aliquet congue egestas ac massa. "
                      "Phasellus elit lectus, finibus tempor augue in, elementum lobortis nisl. "
                      "Donec tristique lorem et tincidunt faucibus.\n\n"
                      "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
                      " Ut orci mauris, placerat et euismod eu, ullamcorper eget massa. "
                      "Suspendisse sodales vitae augue ut vestibulum. "
                      "Nunc fringilla leo ut tellus consectetur tincidunt. "
                      "Quisque eu tortor semper odio aliquet congue egestas ac massa. "
                      "Phasellus elit lectus, finibus tempor augue in, elementum lobortis nisl. "
                      "Donec tristique lorem et tincidunt faucibus.");

    lv_obj_set_width(label, lv_pct(60));
    lv_obj_center(label);
    lv_obj_set_style_text_color(label, lv_palette_main(LV_PALETTE_BLUE), 0);

    lv_obj_t * msgbox1 = lv_msgbox_create(lv_layer_top());
    lv_msgbox_add_title(msgbox1, "Setting");
    lv_msgbox_add_text(msgbox1, "Hello!\n\n"
                       "Scroll the text in the background to see how it behaves.");

    /*Just a little styling on the message box*/
    lv_obj_set_style_bg_opa(msgbox1, LV_OPA_40, 0);
    lv_obj_set_style_bg_opa(lv_msgbox_get_header(msgbox1), LV_OPA_50, 0);
    lv_obj_set_style_bg_color(lv_msgbox_get_header(msgbox1), lv_color_black(), 0);
    lv_obj_set_style_bg_color(msgbox1, lv_color_black(), 0);
    lv_obj_set_style_text_color(msgbox1, lv_color_white(), 0);
    lv_obj_set_style_text_color(lv_msgbox_get_header(msgbox1), lv_color_white(), 0);
    lv_obj_set_style_blur_backdrop(msgbox1, true, 0);

    /*A dropdown to select what to blur*/
    lv_obj_t * dropdown = lv_dropdown_create(lv_layer_top());
    lv_dropdown_set_options(dropdown, "Blur screen\nBlur msgbox");
    lv_obj_set_pos(dropdown, 5, 5);
    lv_obj_add_event_cb(dropdown, dropdown_value_changed_event_cb, LV_EVENT_VALUE_CHANGED, msgbox1);
    /*Also make the list blurred*/
    lv_obj_set_style_blur_radius(lv_dropdown_get_list(dropdown), 24, 0);
    lv_obj_set_style_blur_backdrop(lv_dropdown_get_list(dropdown), true, 0);
    lv_obj_set_style_bg_opa(lv_dropdown_get_list(dropdown), LV_OPA_50, 0);

    /*Send a value changed event to set the initial state*/
    lv_obj_send_event(dropdown, LV_EVENT_VALUE_CHANGED, NULL);


}
#endif

API¶

lv_msgbox.h

lv_msgbox_private.h