1.. _lv_win:
2
3===============
4Window (lv_win)
5===============
6
7
8Overview
9********
10
11The Window Widget is built from a header (like a title bar) with title and
12buttons and a content area.
13
14
15
16.. _lv_win_parts_and_styles:
17
18Parts and Styles
19****************
20
21The Window is built from other Widgets so you can check their
22documentation for details:
23
24- Background: :ref:`base_widget`
25- Header on the background: :ref:`base_widget`
26- Title on the header: :ref:`lv_label`
27- Buttons on the header: :ref:`lv_button`
28- Content Area on the background: :ref:`base_widget`
29
30
31
32.. _lv_win_usage:
33
34Usage
35*****
36
37
38Create a Window
39---------------
40
41:cpp:expr:`lv_win_create(parent)` creates a Window that is initially
42composed of the following Widget structure:
43
44- Background (a :ref:`base_widget`, the main window container), is set up to be a
45  Flex-Flow container that flows its contained Widgets vertically
46  (:cpp:enumerator:`LV_FLEX_FLOW_COLUMN`).
47
48- Header (like a title bar) is initially empty, and is a Flex-Flow container set up
49  to flow its contained Widgets horizontally (:cpp:enumerator:`LV_FLEX_FLOW_ROW`),
50  left to right.  The Header occupies the full width of the Background (its parent)
51  and the top approximately 1/2 inch (according to :c:macro:`LV_DPI_DEF`).
52
53- Content Area (a :ref:`base_widget`) occupies the full width of the Background (its
54  parent) the remainder of the available Background area below the Header.  It is
55  *not itself* a Flex-Flow container, but you can make it so if you wish.  See
56  :ref:`flex` for details.
57
58
59Title and buttons
60-----------------
61
62You can add Button and Label Widgets to the Header using these two functions.  They
63will be placed in the Header in left-to-right order as they are added.  These
64functions can be called in any order, any number of times.
65
66- :cpp:expr:`lv_win_add_title(win, "The title")` adds a Label to the header, with
67  long mode :c:enumerator:`LV_LABEL_LONG_DOT` so that if its text contents are wider
68  than the area it has, the text will be truncated with an ellipsis ("...") placed
69  at the end of the text.  It is set to be FLEX GROW 1, so if it is the only Label
70  in the header, it will occupy all available space after any Buttons are added.
71  If more than one label is added, each label will share that space equally unless
72  its FLEX GROW value is altered.  See :ref:`flex` for details about how this works.
73  Because of this, any buttons added after the last Label added will be "stacked"
74  on the far right of the Header.
75
76- :cpp:expr:`lv_win_add_button(win, icon, button_width)` adds a Button with the
77  specified width that occupies the full height of the Header (its parent).  If
78  ``icon`` is not NULL, an image is created, centered on the button, using ``icon``
79  as its image source.  All valid image sources are supported, but a common source
80  to use is one of the ``LV_SYMBOL_...`` macros, such as :c:macro:`LV_SYMBOL_CLOSE`
81  to provide an "x" (close) symbol.  You get back a pointer to the Button created so
82  you can add an event callback with it and/or whatever else might be needed.
83
84
85
86.. _lv_win_get_parts:
87
88Getting the parts
89*****************
90
91:cpp:expr:`lv_win_get_header(win)` returns a pointer to the header,
92:cpp:expr:`lv_win_get_content(win)` returns a pointer to the content container
93to which the content of the window can be added.
94
95
96
97.. _lv_win_events:
98
99Events
100******
101
102No special events are sent by Window Widgets, however events can be added
103to any Buttons added.
104
105.. admonition::  Further Reading
106
107    Learn more about :ref:`lv_obj_events` emitted by all Widgets.
108
109    Learn more about :ref:`events`.
110
111
112
113.. _lv_win_keys:
114
115Keys
116****
117
118No *Keys* are processed by Window Widgets.
119
120.. admonition::  Further Reading
121
122    Learn more about :ref:`indev_keys`.
123
124
125
126.. _lv_win_example:
127
128Example
129*******
130
131.. include:: ../../examples/widgets/win/index.rst
132
133
134
135.. _lv_win_api:
136
137API
138***
139