Window (lv_win)

Overview

The Window Widget is built from a header (like a title bar) with title and buttons and a content area.

Parts and Styles

The Window is built from other Widgets so you can check their documentation for details:

Usage

Create a Window

lv_win_create(parent) creates a Window that is initially composed of the following Widget structure:

  • Background (a Base Widget, the main window container), is set up to be a Flex-Flow container that flows its contained Widgets vertically (LV_FLEX_FLOW_COLUMN).

  • Header (like a title bar) is initially empty, and is a Flex-Flow container set up to flow its contained Widgets horizontally (LV_FLEX_FLOW_ROW), left to right. The Header occupies the full width of the Background (its parent) and the top approximately 1/2 inch (according to LV_DPI_DEF).

  • Content Area (a Base Widget) occupies the full width of the Background (its parent) the remainder of the available Background area below the Header. It is not itself a Flex-Flow container, but you can make it so if you wish. See Flex for details.

Title and buttons

You can add Button and Label Widgets to the Header using these two functions. They will be placed in the Header in left-to-right order as they are added. These functions can be called in any order, any number of times.

  • lv_win_add_title(win, "The title") adds a Label to the header, with long mode LV_LABEL_LONG_DOT so that if its text contents are wider than the area it has, the text will be truncated with an ellipsis ("...") placed at the end of the text. It is set to be FLEX GROW 1, so if it is the only Label in the header, it will occupy all available space after any Buttons are added. If more than one label is added, each label will share that space equally unless its FLEX GROW value is altered. See Flex for details about how this works. Because of this, any buttons added after the last Label added will be "stacked" on the far right of the Header.

  • lv_win_add_button(win, icon, button_width) adds a Button with the specified width that occupies the full hight of the Header (its parent). If icon is not NULL, an image is created, centered on the button, using icon as its image source. All valid image sources are supported, but a common source to use is one of the LV_SYMBOL_... macros, such as LV_SYMBOL_CLOSE to provide an "x" (close) symbol. You get back a pointer to the Button created so you can add an event callback with it and/or whatever else might be needed.

Getting the parts

lv_win_get_header(win) returns a pointer to the header, lv_win_get_content(win) returns a pointer to the content container to which the content of the window can be added.

Events

No special events are sent by Window Widgets, however events can be added to any Buttons added.

Further Reading

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

Learn more about Events.

Keys

No Keys are processed by Window Widgets.

Further Reading

Learn more about Keys.

Example

Simple window

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

static void event_handler(lv_event_t * e)
{
    lv_obj_t * obj = lv_event_get_target(e);
    LV_UNUSED(obj);
    LV_LOG_USER("Button %d clicked", (int)lv_obj_get_index(obj));
}

void lv_example_win_1(void)
{
    lv_obj_t * win = lv_win_create(lv_screen_active());
    lv_obj_t * btn;
    btn = lv_win_add_button(win, LV_SYMBOL_LEFT, 40);
    lv_obj_add_event_cb(btn, event_handler, LV_EVENT_CLICKED, NULL);

    lv_win_add_title(win, "A title");

    btn = lv_win_add_button(win, LV_SYMBOL_RIGHT, 40);
    lv_obj_add_event_cb(btn, event_handler, LV_EVENT_CLICKED, NULL);

    btn = lv_win_add_button(win, LV_SYMBOL_CLOSE, 60);
    lv_obj_add_event_cb(btn, event_handler, LV_EVENT_CLICKED, NULL);

    lv_obj_t * cont = lv_win_get_content(win);  /*Content can be added here*/
    lv_obj_t * label = lv_label_create(cont);
    lv_label_set_text(label, "This is\n"
                      "a pretty\n"
                      "long text\n"
                      "to see how\n"
                      "the window\n"
                      "becomes\n"
                      "scrollable.\n"
                      "\n"
                      "\n"
                      "Some more\n"
                      "text to be\n"
                      "sure it\n"
                      "overflows. :)");

}

#endif

API

lv_win.h

lv_types.h