Window (lv_win)

Overview

The windows are one of the most complex container-like objects. They are built from two main parts:

  1. a header Container on the top

  2. a Page for the content below the header.

Title

On the header, there is a title which can be modified by: lv_win_set_title(win, "New title"). The title always inherits the style of the header.

Control buttons

You can add control buttons to the right side of the header with: lv_win_add_btn(win, LV_SYMBOL_CLOSE). The second parameter is an Image source.

lv_win_close_event_cb can be used as an event callback to close the Window.

You can modify the size of the control buttons with the lv_win_set_btn_size(win, new_size) function.

Scrollbars

The scrollbar behavior can be set by lv_win_set_sb_mode(win, LV_SB_MODE_...). See Page for details.

Manual scroll and focus

To scroll the Window directly you can use lv_win_scroll_hor(win, dist_px) or lv_win_scroll_ver(win, dist_px).

To make the Window show an object on it use lv_win_focus(win, child, LV_ANIM_ON/OFF).

The time of scroll and focus animations can be adjusted with lv_win_set_anim_time(win, anim_time_ms)

Layout

To set a layout for the content use lv_win_set_layout(win, LV_LAYOUT_...). See Container for details.

Style usage

Use lv_win_set_style(win, LV_WIN_STYLE_...,  &style) to set a new style for an element of the Window:

  • LV_WIN_STYE_BG main background which uses all style.body properties (header and content page are placed on it) (default: lv_style_plain)

  • LV_WIN_STYLE_CONTENT content page’s scrollable part which uses all style.body properties (default: lv_style_transp)

  • LV_WIN_STYLE_SB scroll bar’s style which uses all style.body properties. left/top padding sets the scrollbars’ padding respectively and the inner padding sets the scrollbar’s width. (default: lv_style_pretty_color)

  • LV_WIN_STYLE_HEADER header’s style which uses all style.body properties (default: lv_style_plain_color)

  • LV_WIN_STYLE_BTN_REL released button’s style (on header) which uses all style.body properties (default: lv_style_btn_rel)

  • LV_WIN_STYLE_BTN_PR released button’s style (on header) which uses all style.body properties (default: lv_style_btn_pr)

The height of the header is set to the greater value from buttons’ height (set by lv_win_set_btn_size) and title height (comes from header_style.text.font) plus the body.padding.top and body.padding.bottom of the header style.

Events

Only the Generic events are sent by the object type.

Learn more about Events.

Keys

The following Keys are processed by the Page:

  • LV_KEY_RIGHT/LEFT/UP/DOWN Scroll the page

Learn more about Keys.

Example

C

Simple window

Window example in LittlevGL

code

#include "lvgl/lvgl.h"

void lv_ex_win_1(void)
{
    /*Create a window*/
    lv_obj_t * win = lv_win_create(lv_scr_act(), NULL);
    lv_win_set_title(win, "Window title");                        /*Set the title*/


    /*Add control button to the header*/
    lv_obj_t * close_btn = lv_win_add_btn(win, LV_SYMBOL_CLOSE);           /*Add close button and use built-in close action*/
    lv_obj_set_event_cb(close_btn, lv_win_close_event_cb);
    lv_win_add_btn(win, LV_SYMBOL_SETTINGS);        /*Add a setup button*/

    /*Add some dummy content*/
    lv_obj_t * txt = lv_label_create(win, NULL);
    lv_label_set_text(txt, "This is the content of the window\n\n"
                           "You can add control buttons to\n"
                           "the window header\n\n"
                           "The content area becomes automatically\n"
                           "scrollable is it's large enough.\n\n"
                           " You can scroll the content\n"
                           "See the scroll bar on the right!");
}

MicroPython

Simple window

Window example in LittlevGL

code

# Create a window
win = lv.win(lv.scr_act())
win.set_title("Window title")                 # Set the title


# Add control button to the header
close_btn = win.add_btn(lv.SYMBOL.CLOSE)      # Add close button and use built-in close action
close_btn.set_event_cb(lv.win.close_event_cb)
win.add_btn(lv.SYMBOL.SETTINGS)               # Add a setup button

# Add some dummy content
txt = lv.label(win)
txt.set_text(
"""This is the content of the window

You can add control buttons to
the window header

The content area becomes automatically
scrollable is it's large enough.

You can scroll the content
See the scroll bar on the right!"""
)

API

Typedefs

typedef uint8_t lv_win_style_t

Enums

enum [anonymous]

Window styles.

Values:

LV_WIN_STYLE_BG

Window object background style.

LV_WIN_STYLE_CONTENT

Window content style.

LV_WIN_STYLE_SB

Window scrollbar style.

LV_WIN_STYLE_HEADER

Window titlebar background style.

LV_WIN_STYLE_BTN_REL

Same meaning as ordinary button styles.

LV_WIN_STYLE_BTN_PR

Functions

lv_obj_t *lv_win_create(lv_obj_t *par, const lv_obj_t *copy)

Create a window objects

Return

pointer to the created window

Parameters
  • par: pointer to an object, it will be the parent of the new window

  • copy: pointer to a window object, if not NULL then the new object will be copied from it

void lv_win_clean(lv_obj_t *win)

Delete all children of the scrl object, without deleting scrl child.

Parameters
  • win: pointer to an object

lv_obj_t *lv_win_add_btn(lv_obj_t *win, const void *img_src)

Add control button to the header of the window

Return

pointer to the created button object

Parameters
  • win: pointer to a window object

  • img_src: an image source (‘lv_img_t’ variable, path to file or a symbol)

void lv_win_close_event_cb(lv_obj_t *btn, lv_event_t event)

Can be assigned to a window control button to close the window

Parameters
  • btn: pointer to the control button on teh widows header

  • evet: the event type

void lv_win_set_title(lv_obj_t *win, const char *title)

Set the title of a window

Parameters
  • win: pointer to a window object

  • title: string of the new title

void lv_win_set_btn_size(lv_obj_t *win, lv_coord_t size)

Set the control button size of a window

Return

control button size

Parameters
  • win: pointer to a window object

void lv_win_set_content_size(lv_obj_t *win, lv_coord_t w, lv_coord_t h)

Set the size of the content area.

Parameters
  • win: pointer to a window object

  • w: width

  • h: height (the window will be higher with the height of the header)

void lv_win_set_layout(lv_obj_t *win, lv_layout_t layout)

Set the layout of the window

Parameters
  • win: pointer to a window object

  • layout: the layout from ‘lv_layout_t’

void lv_win_set_sb_mode(lv_obj_t *win, lv_sb_mode_t sb_mode)

Set the scroll bar mode of a window

Parameters
  • win: pointer to a window object

  • sb_mode: the new scroll bar mode from ‘lv_sb_mode_t’

void lv_win_set_anim_time(lv_obj_t *win, uint16_t anim_time)

Set focus animation duration on lv_win_focus()

Parameters
  • win: pointer to a window object

  • anim_time: duration of animation [ms]

void lv_win_set_style(lv_obj_t *win, lv_win_style_t type, const lv_style_t *style)

Set a style of a window

Parameters
  • win: pointer to a window object

  • type: which style should be set

  • style: pointer to a style

void lv_win_set_drag(lv_obj_t *win, bool en)

Set drag status of a window. If set to ‘true’ window can be dragged like on a PC.

Parameters
  • win: pointer to a window object

  • en: whether dragging is enabled

const char *lv_win_get_title(const lv_obj_t *win)

Get the title of a window

Return

title string of the window

Parameters
  • win: pointer to a window object

lv_obj_t *lv_win_get_content(const lv_obj_t *win)

Get the content holder object of window (lv_page) to allow additional customization

Return

the Page object where the window’s content is

Parameters
  • win: pointer to a window object

lv_coord_t lv_win_get_btn_size(const lv_obj_t *win)

Get the control button size of a window

Return

control button size

Parameters
  • win: pointer to a window object

lv_obj_t *lv_win_get_from_btn(const lv_obj_t *ctrl_btn)

Get the pointer of a widow from one of its control button. It is useful in the action of the control buttons where only button is known.

Return

pointer to the window of ‘ctrl_btn’

Parameters
  • ctrl_btn: pointer to a control button of a window

lv_layout_t lv_win_get_layout(lv_obj_t *win)

Get the layout of a window

Return

the layout of the window (from ‘lv_layout_t’)

Parameters
  • win: pointer to a window object

lv_sb_mode_t lv_win_get_sb_mode(lv_obj_t *win)

Get the scroll bar mode of a window

Return

the scroll bar mode of the window (from ‘lv_sb_mode_t’)

Parameters
  • win: pointer to a window object

uint16_t lv_win_get_anim_time(const lv_obj_t *win)

Get focus animation duration

Return

duration of animation [ms]

Parameters
  • win: pointer to a window object

lv_coord_t lv_win_get_width(lv_obj_t *win)

Get width of the content area (page scrollable) of the window

Return

the width of the content area

Parameters
  • win: pointer to a window object

const lv_style_t *lv_win_get_style(const lv_obj_t *win, lv_win_style_t type)

Get a style of a window

Return

style pointer to a style

Parameters
  • win: pointer to a button object

  • type: which style window be get

static bool lv_win_get_drag(const lv_obj_t *win)

Get drag status of a window. If set to ‘true’ window can be dragged like on a PC.

Return

whether window is draggable

Parameters
  • win: pointer to a window object

void lv_win_focus(lv_obj_t *win, lv_obj_t *obj, lv_anim_enable_t anim_en)

Focus on an object. It ensures that the object will be visible in the window.

Parameters
  • win: pointer to a window object

  • obj: pointer to an object to focus (must be in the window)

  • anim_en: LV_ANIM_ON focus with an animation; LV_ANIM_OFF focus without animation

static void lv_win_scroll_hor(lv_obj_t *win, lv_coord_t dist)

Scroll the window horizontally

Parameters
  • win: pointer to a window object

  • dist: the distance to scroll (< 0: scroll right; > 0 scroll left)

static void lv_win_scroll_ver(lv_obj_t *win, lv_coord_t dist)

Scroll the window vertically

Parameters
  • win: pointer to a window object

  • dist: the distance to scroll (< 0: scroll down; > 0 scroll up)

struct lv_win_ext_t

Public Members

lv_obj_t *page
lv_obj_t *header
lv_obj_t *title
const lv_style_t *style_btn_rel
const lv_style_t *style_btn_pr
lv_coord_t btn_size