github-code/lvgl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs): batch 8 of proofread/edited docs (#7295)

Browse Source 
Co-authored-by: Liam <30486941+liamHowatt@users.noreply.github.com>
This commit is contained in:
Victor Wheeler
2024-12-03 09:15:15 -07:00
committed by GitHub
parent 5bccba9946
commit b8c5a4123d
4 changed files with 236 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docs/details/widgets/tabview.rst
View File

@@ -1,14 +1,15 @@
.. _lv_tabview: .. _lv_tabview:
==================== =====================
Tabview (lv_tabview) Tab View (lv_tabview)
==================== =====================
Overview Overview
******** ********
The Tab view Widget can be used to organize content in tabs. The Tab The Tab View Widget can be used to organize content in tabs. The Tab
view is built from other widgets: View is built from other Widgets:
- Main container: :ref:`base_widget` - Main container: :ref:`base_widget`
- Tab buttons: an :ref:`base_widget` with :ref:`lv_button` - Tab buttons: an :ref:`base_widget` with :ref:`lv_button`
@@ -16,70 +17,77 @@ view is built from other widgets:
- Content of the tabs: :ref:`base_widget` - Content of the tabs: :ref:`base_widget`
The tab buttons can be positioned on the top, bottom, left and right The tab buttons can be positioned on the top, bottom, left and right
side of the Tab view. side of the Tab View.
A new tab can be selected either by clicking on a tab button or by A new tab can be selected either by clicking on a tab button or by
sliding horizontally on the content. sliding horizontally on the content.
.. _lv_tabview_parts_and_styles: .. _lv_tabview_parts_and_styles:
Parts and Styles Parts and Styles
**************** ****************
There are no special parts on the Tab view but the :ref:`base_widget` and There are no special parts on the Tab View but the :ref:`base_widget` and
:ref:`lv_button` widgets are used to create the Tab view. :ref:`lv_button` Widgets are used to create the Tab View.
.. _lv_tabview_usage: .. _lv_tabview_usage:
Usage Usage
***** *****
Create a Tab view Creating a Tab View
----------------- -------------------
:cpp:expr:`lv_tabview_create(parent)` creates a new empty Tab view. :cpp:expr:`lv_tabview_create(parent)` creates a new empty Tab View.
Add tabs Adding tabs
-------- -----------
New tabs can be added with :cpp:expr:`lv_tabview_add_tab(tabview, "Tab name")`. New tabs can be added with :cpp:expr:`lv_tabview_add_tab(tabview, "Tab name")`.
This will return a pointer to a :ref:`base_widget` where This will return a pointer to a :ref:`base_widget` where
the tab's content can be created. the tab's content can be created.
Rename tabs Renaming tabs
----------- -------------
A tab can be renamed with A tab can be renamed with
:cpp:expr:`lv_tabview_rename_tab(tabview, tab_id, "New Name")`. :cpp:expr:`lv_tabview_rename_tab(tabview, tab_id, "New Name")`.
Change tab Navigating to a new tab
---------- -----------------------
To select a new tab you can: To select a new tab you can:
- Click on its tab button - Click on its tab button
- Slide horizontally - Slide horizontally
- Use :cpp:expr:`lv_tabview_set_active(tabview, id, LV_ANIM_ON)` function - Use :cpp:expr:`lv_tabview_set_active(tabview, tab_id, LV_ANIM_ON / OFF)` function
Set tab bar position Setting tab bar position
-------------------- ------------------------
Using the :cpp:expr:`lv_tabview_set_tab_bar_position(tabview, LV_DIR_LEFT/RIGHT/TOP/BOTTOM)` Using the :cpp:expr:`lv_tabview_set_tab_bar_position(tabview, LV_DIR_LEFT/RIGHT/TOP/BOTTOM)`
the tab bar can be moved to any sides. the tab bar can be moved to any side.
Set tab bar size Setting tab bar size
---------------- --------------------
The size of the tab bar can be adjusted by :cpp:expr:`lv_tabview_set_tab_bar_size(tabview, size)` The size of the tab bar can be adjusted by :cpp:expr:`lv_tabview_set_tab_bar_size(tabview, size)`
In case of vertical arrangement is means the height of the tab bar, and in horizontal When tabs are on the top or bottom, this means the height of the tab bar, and when
arrangement it means the width. they are on the sides, it means the width.
Get the parts Accessing the parts
------------- -------------------
- :cpp:expr:`lv_tabview_get_content(tabview)` returns the container for tabs content - :cpp:expr:`lv_tabview_get_content(tabview)` returns a pointer to the container for
- :cpp:expr:`lv_tabview_get_tab_bar(tabview)` returns the container for tabs buttons tabs content (a :ref:`base_widget`)
- :cpp:expr:`lv_tabview_get_tab_bar(tabview)` returns a pointer to the container for
tab buttons (a :ref:`base_widget`)
@@ -106,7 +114,7 @@ Keys
**** ****
Keys have effect only on the tab buttons. Keys have effect only on the tab buttons.
Add manually to a group if required. Programmatically add these buttons to a group if required.
.. admonition:: Further Reading .. admonition:: Further Reading

199
docs/details/widgets/textarea.rst
View File

@@ -4,117 +4,135 @@
Text Area (lv_textarea) Text Area (lv_textarea)
======================= =======================
Overview Overview
******** ********
The Text Area is a :ref:`base_widget_overview` with a :ref:`lv_label` and a cursor on The Text Area is a :ref:`base_widget_overview` with a :ref:`lv_label` and a cursor on
it. Texts or characters can be added to it. Long lines are wrapped and when the it. Text or characters can be added to it. Long lines are wrapped and when the
text becomes long enough the Text area can be scrolled. text becomes long enough, the Text Area can be scrolled.
One-line mode and password modes are supported.
One line mode and password modes are supported.
.. _lv_textarea_parts_and_styles: .. _lv_textarea_parts_and_styles:
Parts and Styles Parts and Styles
**************** ****************
- :cpp:enumerator:`LV_PART_MAIN` The background of the text area. Uses all the - :cpp:enumerator:`LV_PART_MAIN` The background of the Text Area; uses the
typical background style properties and the text related style :ref:`typical background style properties <typical bg props>` and the text related
properties including ``text_align`` to align the text to the left, style properties including ``text_align`` to align the text to the left,
right or center. right or center.
- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is - :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is
too long. longer than its height.
- :cpp:enumerator:`LV_PART_SELECTED` Determines the style of the :ref:`selected - :cpp:enumerator:`LV_PART_SELECTED` Determines the style of the :ref:`selected
text <lv_label_text_selection>`. Only ``text_color`` and text <lv_label_text_selection>`. Only ``text_color`` and
``bg_color`` style properties can be used. ``bg_color`` should be set ``bg_color`` style properties can be used. ``bg_color`` should be set
directly on the label of the text area. directly on the label of the Text Area.
- :cpp:enumerator:`LV_PART_CURSOR` Marks the position where the characters are - :cpp:enumerator:`LV_PART_CURSOR` Marks the position where the characters are
inserted. The cursor's area is always the bounding box of the current inserted. The cursor's area is always the bounding box of the current
character. A block cursor can be created by adding a background color character. A block cursor can be created by adding a background color
and background opacity to :cpp:enumerator:`LV_PART_CURSOR`\ 's style. The create and background opacity to :cpp:enumerator:`LV_PART_CURSOR`\ 's style. To create
line cursor leave the cursor transparent and set a left border. The a "bar" cursor leave the cursor transparent and set a left border. The
``anim_time`` style property sets the cursor's blink time. ``anim_time`` style property sets the cursor's blink time.
- :cpp:enumerator:`LV_PART_TEXTAREA_PLACEHOLDER` Unique to Text Area, allows styling - :cpp:enumerator:`LV_PART_TEXTAREA_PLACEHOLDER` Unique to Text Area; allows styling
the placeholder text. the :ref:`placeholder text <textarea_placeholder_text>`.
.. _lv_textarea_usage: .. _lv_textarea_usage:
Usage Usage
***** *****
Add text Adding text
-------- -----------
You can insert text or characters to the current cursor's position with: You can insert text or characters to the current cursor's position with:
- :cpp:expr:`lv_textarea_add_char(textarea, 'c')` - :cpp:expr:`lv_textarea_add_char(textarea, 'c')`
- :cpp:expr:`lv_textarea_add_text(textarea, "insert this text")` - :cpp:expr:`lv_textarea_add_text(textarea, "insert this text")`
To add wide characters like ``'á'``, ``'ß'`` or CJK characters use To add wide characters like ``'á'``, ``'ß'`` or CJK characters, use
:cpp:expr:`lv_textarea_add_text(ta, "á")`. :cpp:expr:`lv_textarea_add_text(textarea, "á")`.
:cpp:expr:`lv_textarea_set_text(ta, "New text")` changes the whole text. :cpp:expr:`lv_textarea_set_text(textarea, "New text")` replaces all existing text
with "New text".
Placeholder .. _textarea_placeholder_text:
-----------
A placeholder text can be specified Placeholder text
----------------
- which is displayed when the Text area is empty Placeholder text is text that is displayed when the Text Area is empty. This can be
- with :cpp:expr:`lv_textarea_set_placeholder_text(ta, "Placeholder text")` a handy way to provide the end user with a hint about what to type there.
Specify placeholder text using
:cpp:expr:`lv_textarea_set_placeholder_text(textarea, "Placeholder text")`.
Delete character Delete character
---------------- ----------------
To delete a character from the left of the current cursor position use To delete the character to the left of the current cursor position, use
:cpp:expr:`lv_textarea_delete_char(textarea)`. :cpp:expr:`lv_textarea_delete_char(textarea)`.
To delete from the right use :cpp:expr:`lv_textarea_delete_char_forward(textarea)` To delete to the right, use :cpp:expr:`lv_textarea_delete_char_forward(textarea)`
Move the cursor Moving the cursor
--------------- -----------------
The cursor position can be modified directly like The cursor position can be modified programmatically using
:cpp:expr:`lv_textarea_set_cursor_pos(textarea, 10)`. The ``0`` position means :cpp:expr:`lv_textarea_set_cursor_pos(textarea, corsor_pos)` where ``cursor_pos`` is
"before the first characters", :cpp:enumerator:`LV_TEXTAREA_CURSOR_LAST` means "after the the zero-based index of the character the cursor should be placed in front of.
:cpp:enumerator:`LV_TEXTAREA_CURSOR_LAST` can be passed to mean "after the
last character" last character"
You can step the cursor with You can move the cursor one character-position (or line) at a time with
- :cpp:expr:`lv_textarea_cursor_right(textarea)` - :cpp:expr:`lv_textarea_cursor_right(textarea)`
- :cpp:expr:`lv_textarea_cursor_left(textarea)` - :cpp:expr:`lv_textarea_cursor_left(textarea)`
- :cpp:expr:`lv_textarea_cursor_up(textarea)` - :cpp:expr:`lv_textarea_cursor_up(textarea)`
- :cpp:expr:`lv_textarea_cursor_down(textarea)` - :cpp:expr:`lv_textarea_cursor_down(textarea)`
If :cpp:expr:`lv_textarea_set_cursor_click_pos(textarea, true)` is applied the If :cpp:expr:`lv_textarea_set_cursor_click_pos(textarea, true)` is applied, the
cursor will jump to the position where the Text area was clicked. cursor will jump to the position where the Text Area was clicked.
Hide the cursor Hiding the cursor
--------------- -----------------
The cursor is always visible, however it can be a good idea to style it The cursor is normally always visible. It it can be a good idea to style it
to be visible only in :cpp:enumerator:`LV_STATE_FOCUSED` state. to be visible only in :cpp:enumerator:`LV_STATE_FOCUSED` state. See :ref:`styles`
for more information about how to do this.
One line mode One-line mode
------------- -------------
The Text area can be configured to be on a single line with The Text Area can be configured to keep all text on a single line with
:cpp:expr:`lv_textarea_set_one_line(textarea, true)`. In this mode the height is :cpp:expr:`lv_textarea_set_one_line(textarea, true)`. In this mode:
set automatically to show only one line, line break characters are
ignored, and word wrap is disabled. - the height is set automatically to show only one line,
- line break characters are ignored, and
- word wrap is disabled.
Password mode Password mode
------------- -------------
The text area supports password mode which can be enabled with The Text Area supports password mode which can be enabled with
:cpp:expr:`lv_textarea_set_password_mode(textarea, true)`. :cpp:expr:`lv_textarea_set_password_mode(textarea, true)`.
By default, if the ``•`` (`Bullet, By default, if the ``•`` (`Bullet,
U+2022 <http://www.fileformat.info/info/unicode/char/2022/index.htm>`__) U+2022 <http://www.fileformat.info/info/unicode/char/2022/index.htm>`__)
character exists in the font, the entered characters are converted to it character exists in the font, the entered characters are converted to it after
after some time or when a new character is entered. If ``•`` does not a configurable delay after each new character is entered. If ``•`` does not
exist in the font, ``*`` will be used. You can override the default exist in the font, ``*`` will be used. You can override the default
character with :cpp:expr:`lv_textarea_set_password_bullet(textarea, "x")`. "masking" character with :cpp:expr:`lv_textarea_set_password_bullet(textarea, str)`
where ``str`` is a NUL-terminated C string. Example:
.. code-block:: c
lv_textarea_set_password_bullet(textarea, "x");
In password mode :cpp:expr:`lv_textarea_get_text(textarea)` returns the actual In password mode :cpp:expr:`lv_textarea_get_text(textarea)` returns the actual
text entered, not the bullet characters. text entered, not the bullet characters.
@@ -125,32 +143,72 @@ Accepted characters
------------------- -------------------
You can set a list of accepted characters with You can set a list of accepted characters with
:cpp:expr:`lv_textarea_set_accepted_chars(textarea, "0123456789.+-")`. Other :cpp:expr:`lv_textarea_set_accepted_chars(textarea, list)` where ``list`` is a
characters will be ignored. pointer to a NUL-terminated string, or NULL to accept all characters. Characters
entered not in this list will be ignored.
.. code-block:: c
lv_textarea_set_accepted_chars(textarea, "0123456789.+-");
Max text length Max text length
--------------- ---------------
The maximum number of characters can be limited with The maximum number of characters can be limited using
:cpp:expr:`lv_textarea_set_max_length(textarea, max_char_num)` :cpp:expr:`lv_textarea_set_max_length(textarea, max_char_num)`.
Very long texts Very long text
--------------- --------------
If there is a very long text in the Text area (e.g. > 20k characters), If the text in the Text Area is very long (e.g. > 20k characters), scrolling and
scrolling and drawing might be slow. However, by enabling drawing might be slow. However, by setting :c:macro:`LV_LABEL_LONG_TXT_HINT` in
:c:macro:`LV_LABEL_LONG_TXT_HINT` in ``lv_conf.h`` the performance can be ``lv_conf.h`` to a non-zero value, the performance with long text is significantly
hugely improved. This will save some additional information about the improved. It does this by saving some additional information about the current
label to speed up its drawing. Using :c:macro:`LV_LABEL_LONG_TXT_HINT` the vertical position of the text shown. With this mode configured, scrolling and drawing
scrolling and drawing will as fast as with "normal" short texts. is as fast as with "normal" short text. The cost is 12 extra bytes per label in RAM.
Select text This value is set to ``1`` by default. If you do not use long text, you can save
----------- 12 bytes per label by setting it to ``0``.
Selecting text
--------------
If :c:macro:`LV_LABEL_TEXT_SELECTION` is set to a non-zero value in ``lv_conf.h``,
some additional functionality (and 8 bytes per label) are added to Label Widgets
and Text Area Widgets, and text-selection functionality is automated in Text Area
Widgets. (If you do not use selected text in your application, you can save 8 bytes
per label in RAM by setting that macro to equate to ``0``.)
Any part of the text can be selected if enabled with Any part of the text can be selected if enabled with
:cpp:expr:`lv_textarea_set_text_selection(textarea, true)`. This works much like :cpp:expr:`lv_textarea_set_text_selection(textarea, true)`. This works much like
when you select text on your PC with your mouse. when you select text on your PC with your mouse. If you pass ``false`` to this
function to disable text-selection, any text selected at the time of the call will be
de-selected.
If you need to programmatically deal with selected text, in addition to the
:cpp:expr:`lv_textarea_set_text_selection(textarea, enable)` function, the following
is your tool set for doing so. (``ta_label`` is a pointer to the Text Area's
Label retrieved with ``ta_label = lv_textarea_get_label(textarea);``.)
- :cpp:expr:`lv_textarea_get_text_selection(textarea)` tells whether text selection is enabled.
- :cpp:expr:`lv_textarea_text_is_selected(textarea)` tells whether any text is currently selected.
- :cpp:expr:`lv_textarea_clear_selection(textarea)` clears current text selection.
- :cpp:expr:`lv_label_set_text_selection_start(ta_label, index)` where ``index`` is
the zero-based index of the first character of the selected text.
Pass :c:macro:`LV_DRAW_LABEL_NO_TXT_SEL` to specify no text selected.
- :cpp:expr:`lv_label_set_text_selection_end(ta_label, index)` where ``index`` is
the zero-based index of the character just after the selected text.
Pass :c:macro:`LV_DRAW_LABEL_NO_TXT_SEL` to specify no text selected.
- :cpp:expr:`lv_label_get_text_selection_start(ta_label)` zero-based index of the
first character of the selected text.
:c:macro:`LV_DRAW_LABEL_NO_TXT_SEL` indicates no text selected.
- :cpp:expr:`lv_label_get_text_selection_end(ta_label)` zero-based index of the
character just after the selected text.
:c:macro:`LV_DRAW_LABEL_NO_TXT_SEL` indicates no text selected.
Normally you won't need these since Text Area automates the text selection process,
but if you do need to change the selection programmatically, the above are your
tools to do so.
.. _lv_textarea_events: .. _lv_textarea_events:
@@ -160,14 +218,17 @@ Events
- :cpp:enumerator:`LV_EVENT_INSERT` Sent right before a character or text is - :cpp:enumerator:`LV_EVENT_INSERT` Sent right before a character or text is
inserted. The event parameter is the text about to be inserted. inserted. The event parameter is the text about to be inserted.
:cpp:expr:`lv_textarea_set_insert_replace(textarea, "New text")` replaces the :cpp:expr:`lv_textarea_set_insert_replace(textarea, "New text")` can be called
text to insert. The new text cannot be in a local variable which is from within that event to replace the text to be inserted. The contents of the
destroyed when the event callback exists. ``""`` means do not insert buffer passed must be survive long enough for the call to `lv_timer_handler()`
anything. that is driving the event to return (after which the Text Area's label will have
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the content of the text area has copied the text). So it should not be a local buffer (created on the stack)
been changed. where its contents will be destroyed before that happens. Passing ``""`` means "do
- :cpp:enumerator:`LV_EVENT_READY` Sent when :cpp:enumerator:`LV_KEY_ENTER` is pressed (or sent) to not insert anything".
a one line text area. - :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the content of the Text Area
has changed.
- :cpp:enumerator:`LV_EVENT_READY` Sent when :cpp:enumerator:`LV_KEY_ENTER` is
pressed (or sent) to a one-line Text Area.
.. admonition:: Further Reading .. admonition:: Further Reading

31
docs/details/widgets/tileview.rst
View File

@@ -4,27 +4,32 @@
Tile View (lv_tileview) Tile View (lv_tileview)
======================= =======================
Overview Overview
******** ********
The Tile view is a container Widget whose elements (called *tiles*) can The Tile View is a container Widget whose elements (called *tiles*) can
be arranged in grid form. A user can navigate between the tiles by be arranged in grid form. A user can navigate between the tiles by
swiping. Any direction of swiping can be disabled on the tiles swiping. Any direction of swiping can be disabled on the tiles
individually to not allow moving from one tile to another. individually to not allow moving from one tile to another.
If the Tile view is screen sized, the user interface resembles what you If the Tile View is screen sized, the user interface resembles what you
may have seen on smartwatches. may have seen on smartwatches.
.. _lv_tileview_parts_and_styles: .. _lv_tileview_parts_and_styles:
Parts and Styles Parts and Styles
**************** ****************
The Tile view is built from an :ref:`base_widget` container and The Tile View is built from a :ref:`base_widget` container and
:ref:`base_widget` tiles. :ref:`base_widget` tiles.
The parts and styles work the same as for :ref:`base_widget`. The parts and styles work the same as for :ref:`base_widget`.
.. _lv_tileview_usage: .. _lv_tileview_usage:
Usage Usage
@@ -34,19 +39,19 @@ Add a tile
---------- ----------
:cpp:expr:`lv_tileview_add_tile(tileview, col_id, row_id, dir)` creates a new :cpp:expr:`lv_tileview_add_tile(tileview, col_id, row_id, dir)` creates a new
tile on the ``col_id``\ th column and ``row_id``\ th row. ``dir`` can be tile on the ``col_id``\ -th column and ``row_id``\ -th row. ``dir`` can be
``LV_DIR_LEFT/RIGHT/TOP/BOTTOM/HOR/VER/ALL`` or OR-ed values to enable ``LV_DIR_LEFT/RIGHT/TOP/BOTTOM/HOR/VER/ALL`` or OR-ed values to enable
moving to the adjacent tiles into the given direction by swiping. moving to the adjacent tiles in the given direction by swiping.
The returned value is an ``lv_obj_t *`` on which the content of the tab The returned value is a pointer to the tile (a :ref:`base_widget`) on which the
can be created. content of the tab can be created.
Change tile Change tile
----------- -----------
The Tile view can scroll to a tile with The Tile View can scroll to a specified tile with
:cpp:expr:`lv_tileview_set_tile(tileview, tile_obj, LV_ANIM_ON/OFF)` or :cpp:expr:`lv_tileview_set_tile(tileview, tile, LV_ANIM_ON/OFF)` or
:cpp:expr:`lv_tileview_set_tile_by_index(tileview, col_id, row_id, LV_ANIM_ON/OFF)` :cpp:expr:`lv_tileview_set_tile_by_index(tileview, col_id, row_id, LV_ANIM_ON/OFF)`.
@@ -55,9 +60,9 @@ The Tile view can scroll to a tile with
Events Events
****** ******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new tile loaded by scrolling. - :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent after a new tile is displayed by scrolling.
:cpp:expr:`lv_tileview_get_tile_active(tabview)` can be used to get current :cpp:expr:`lv_tileview_get_tile_active(tabview)` can be used within the event to
tile. get a pointer to the newly-displayed tile.
.. admonition:: Further Reading .. admonition:: Further Reading

69
docs/details/widgets/win.rst
View File

@@ -4,58 +4,89 @@
Window (lv_win) Window (lv_win)
=============== ===============
Overview Overview
******** ********
The Window is container-like Widget built from a header with title and The Window Widget is built from a header (like a title bar) with title and
buttons and a content area. buttons and a content area.
.. _lv_win_parts_and_styles: .. _lv_win_parts_and_styles:
Parts and Styles Parts and Styles
**************** ****************
The Window is built from other widgets so you can check their The Window is built from other Widgets so you can check their
documentation for details: documentation for details:
- Background: :ref:`base_widget` - Background: :ref:`base_widget`
- Header on the background: :ref:`base_widget` - Header on the background: :ref:`base_widget`
- Title on the header: :ref:`lv_label` - Title on the header: :ref:`lv_label`
- Buttons on the header: :ref:`lv_button` - Buttons on the header: :ref:`lv_button`
- Content area on the background: :ref:`base_widget` - Content Area on the background: :ref:`base_widget`
.. _lv_win_usage: .. _lv_win_usage:
Usage Usage
***** *****
Create a Window Create a Window
--------------- ---------------
:cpp:expr:`lv_win_create(parent, header_height)` creates a Window with an empty :cpp:expr:`lv_win_create(parent)` creates a Window that is initially
header. composed of the following Widget structure:
- Background (a :ref:`base_widget`, the main window container), is set up to be a
Flex-Flow container that flows its contained Widgets vertically
(:cpp:enumerator:`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 (:cpp:enumerator:`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 :c:macro:`LV_DPI_DEF`).
- Content Area (a :ref:`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
:ref:`flex` for details.
Title and buttons Title and buttons
----------------- -----------------
Any number of texts (but typically only one) can be added to the header You can add Button and Label Widgets to the Header using these two functions. They
with :cpp:expr:`lv_win_add_title(win, "The title")`. 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.
- :cpp:expr:`lv_win_add_title(win, "The title")` adds a Label to the header, with
long mode :c:enumerator:`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 :ref:`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.
- :cpp:expr:`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 :c:macro:`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.
Control buttons can be added to the window's header with
:cpp:expr:`lv_win_add_button(win, icon, button_width)`. ``icon`` can be any image
source, and ``button_width`` is the width of the button.
The title and the buttons will be added in the order the functions are
called. So adding a button, a text and two other buttons will result in
a button on the left, a title, and 2 buttons on the right. The width of
the title is set to take all the remaining space on the header. In other
words: it pushes to the right all the buttons that are added after the
title.
.. _lv_win_get_parts: .. _lv_win_get_parts:
Get the parts Getting the parts
************* *****************
:cpp:expr:`lv_win_get_header(win)` returns a pointer to the header, :cpp:expr:`lv_win_get_header(win)` returns a pointer to the header,
:cpp:expr:`lv_win_get_content(win)` returns a pointer to the content container :cpp:expr:`lv_win_get_content(win)` returns a pointer to the content container
@@ -69,7 +100,7 @@ Events
****** ******
No special events are sent by Window Widgets, however events can be added No special events are sent by Window Widgets, however events can be added
manually to the return value of :cpp:func:`lv_win_add_button`. to any Buttons added.
.. admonition:: Further Reading .. admonition:: Further Reading