Window (lv_win)

Overview

The Window is container-like objects built from a header with title and button and a content area.

Parts and Styles

The main part is LV_WIN_PART_BG which holds the two other real parts:

  1. LV_WIN_PART_HEADER: a header Container on the top with a title and control buttons

  2. LV_WIN_PART_CONTENT_SCRL the scrollable part of a Page for the content below the header.

Besides these, LV_WIN_PART_CONTENT_SCRL has a scrollbar part called LV_WIN_PART_CONTENT_SCRL. Read the documentation of Page for more details on the scrollbars.

All parts supports the typical background properties. The title uses the Text properties of the header part.

The height of the control buttons is: header height - header padding_top - header padding_bottom.

Title

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

Control buttons

Control buttons can be added to the right of the window header with: lv_win_add_btn_right(win, LV_SYMBOL_CLOSE), to add a button to the left side of the window header use lv_win_add_btn_left(win, LV_SYMBOL_CLOSE) instead. The second parameter is an Image source so it can be a symbol, a pointer to an lv_img_dsc_t variable or a path to file.

The width of the buttons can be set with lv_win_set_btn_width(win, w). If w == 0 the buttons will be square-shaped.

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

Scrollbars

The scrollbar behavior can be set by lv_win_set_scrlbar_mode(win, LV_SCRLBAR_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.

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 "../../../lv_examples.h"
#if LV_USE_WIN

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\n"
                           "automatically scrollable is it's \n"
                           "large enough.\n\n"
                           " You can scroll the content\n"
                           "See the scroll bar on the right!");
}

#endif

MicroPython

No examples yet.

API

Enums

enum [anonymous]

Window parts.

Values:

enumerator LV_WIN_PART_BG = LV_OBJ_PART_MAIN

Window object background style.

enumerator _LV_WIN_PART_VIRTUAL_LAST
enumerator LV_WIN_PART_HEADER = _LV_OBJ_PART_REAL_LAST

Window titlebar background style.

enumerator LV_WIN_PART_CONTENT_SCROLLABLE

Window content style.

enumerator LV_WIN_PART_SCROLLBAR

Window scrollbar style.

enumerator _LV_WIN_PART_REAL_LAST

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_right(lv_obj_t *win, const void *img_src)

Add control button on the right side of the window header

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)

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

Add control button on the left side of the window header

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 the 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_header_height(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_btn_width(lv_obj_t *win, lv_coord_t width)

Set the width of the control buttons on the header

Parameters
  • win: pointer to a window object

  • width: width of the control button. 0: to make them square automatically.

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_scrollbar_mode(lv_obj_t *win, lv_scrollbar_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_scrollbar_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_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_header_height(const lv_obj_t *win)

Get the header height

Return

header height

Parameters
  • win: pointer to a window object

lv_coord_t lv_win_get_btn_width(lv_obj_t *win)

Get the width of the control buttons on the header

Return

width of the control button. 0: square.

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_scrollbar_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

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

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)

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
char *title_txt
lv_coord_t btn_w