mirror of
https://github.com/lvgl/lvgl.git
synced 2025-01-14 06:42:58 +08:00
feat(docs): batch 8 of proofread/edited docs (#7295)
Co-authored-by: Liam <30486941+liamHowatt@users.noreply.github.com>
This commit is contained in:
Victor Wheeler
GitHub
parent
5bccba9946
commit
b8c5a4123d
@ -1,14 +1,15 @@
|
||||
.. _lv_tabview:
|
||||
|
||||
====================
|
||||
Tabview (lv_tabview)
|
||||
====================
|
||||
=====================
|
||||
Tab View (lv_tabview)
|
||||
=====================
|
||||
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
The Tab view Widget can be used to organize content in tabs. The Tab
|
||||
view is built from other widgets:
|
||||
The Tab View Widget can be used to organize content in tabs. The Tab
|
||||
View is built from other Widgets:
|
||||
|
||||
- Main container: :ref:`base_widget`
|
||||
- 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`
|
||||
|
||||
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
|
||||
sliding horizontally on the content.
|
||||
|
||||
|
||||
|
||||
.. _lv_tabview_parts_and_styles:
|
||||
|
||||
|
||||
Parts and Styles
|
||||
****************
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
|
||||
|
||||
.. _lv_tabview_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")`.
|
||||
This will return a pointer to a :ref:`base_widget` where
|
||||
the tab's content can be created.
|
||||
|
||||
Rename tabs
|
||||
-----------
|
||||
Renaming tabs
|
||||
-------------
|
||||
|
||||
A tab can be renamed with
|
||||
: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:
|
||||
|
||||
- Click on its tab button
|
||||
- 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)`
|
||||
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)`
|
||||
In case of vertical arrangement is means the height of the tab bar, and in horizontal
|
||||
arrangement it means the width.
|
||||
When tabs are on the top or bottom, this means the height of the tab bar, and when
|
||||
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_tab_bar(tabview)` returns the container for tabs buttons
|
||||
- :cpp:expr:`lv_tabview_get_content(tabview)` returns a pointer to the container for
|
||||
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.
|
||||
Add manually to a group if required.
|
||||
Programmatically add these buttons to a group if required.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
|
||||
@ -4,117 +4,135 @@
|
||||
Text Area (lv_textarea)
|
||||
=======================
|
||||
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
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
|
||||
text becomes long enough the Text area can be scrolled.
|
||||
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.
|
||||
|
||||
One-line mode and password modes are supported.
|
||||
|
||||
|
||||
One line mode and password modes are supported.
|
||||
|
||||
.. _lv_textarea_parts_and_styles:
|
||||
|
||||
Parts and Styles
|
||||
****************
|
||||
|
||||
- :cpp:enumerator:`LV_PART_MAIN` The background of the text area. Uses all the
|
||||
typical background style properties and the text related style
|
||||
properties including ``text_align`` to align the text to the left,
|
||||
- :cpp:enumerator:`LV_PART_MAIN` The background of the Text Area; uses the
|
||||
:ref:`typical background style properties <typical bg props>` and the text related
|
||||
style properties including ``text_align`` to align the text to the left,
|
||||
right or center.
|
||||
- :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
|
||||
text <lv_label_text_selection>`. Only ``text_color`` and
|
||||
``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
|
||||
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
|
||||
and background opacity to :cpp:enumerator:`LV_PART_CURSOR`\ 's style. The create
|
||||
line cursor leave the cursor transparent and set a left border. The
|
||||
and background opacity to :cpp:enumerator:`LV_PART_CURSOR`\ 's style. To create
|
||||
a "bar" cursor leave the cursor transparent and set a left border. The
|
||||
``anim_time`` style property sets the cursor's blink time.
|
||||
- :cpp:enumerator:`LV_PART_TEXTAREA_PLACEHOLDER` Unique to Text Area, allows styling
|
||||
the placeholder text.
|
||||
- :cpp:enumerator:`LV_PART_TEXTAREA_PLACEHOLDER` Unique to Text Area; allows styling
|
||||
the :ref:`placeholder text <textarea_placeholder_text>`.
|
||||
|
||||
|
||||
|
||||
.. _lv_textarea_usage:
|
||||
|
||||
Usage
|
||||
*****
|
||||
|
||||
Add text
|
||||
--------
|
||||
Adding text
|
||||
-----------
|
||||
|
||||
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_text(textarea, "insert this text")`
|
||||
|
||||
To add wide characters like ``'á'``, ``'ß'`` or CJK characters use
|
||||
:cpp:expr:`lv_textarea_add_text(ta, "á")`.
|
||||
To add wide characters like ``'á'``, ``'ß'`` or CJK characters, use
|
||||
: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
|
||||
- with :cpp:expr:`lv_textarea_set_placeholder_text(ta, "Placeholder text")`
|
||||
Placeholder text is text that is displayed when the Text Area is empty. This can be
|
||||
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
|
||||
----------------
|
||||
|
||||
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)`.
|
||||
|
||||
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
|
||||
:cpp:expr:`lv_textarea_set_cursor_pos(textarea, 10)`. The ``0`` position means
|
||||
"before the first characters", :cpp:enumerator:`LV_TEXTAREA_CURSOR_LAST` means "after the
|
||||
The cursor position can be modified programmatically using
|
||||
:cpp:expr:`lv_textarea_set_cursor_pos(textarea, corsor_pos)` where ``cursor_pos`` is
|
||||
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"
|
||||
|
||||
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_left(textarea)`
|
||||
- :cpp:expr:`lv_textarea_cursor_up(textarea)`
|
||||
- :cpp:expr:`lv_textarea_cursor_down(textarea)`
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Hide the cursor
|
||||
---------------
|
||||
Hiding the cursor
|
||||
-----------------
|
||||
|
||||
The cursor is always visible, however it can be a good idea to style it
|
||||
to be visible only in :cpp:enumerator:`LV_STATE_FOCUSED` state.
|
||||
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. 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
|
||||
:cpp:expr:`lv_textarea_set_one_line(textarea, true)`. In this mode the height is
|
||||
set automatically to show only one line, line break characters are
|
||||
ignored, and word wrap is disabled.
|
||||
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 set automatically to show only one line,
|
||||
- line break characters are ignored, and
|
||||
- word wrap is disabled.
|
||||
|
||||
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)`.
|
||||
|
||||
By default, if the ``•`` (`Bullet,
|
||||
U+2022 <http://www.fileformat.info/info/unicode/char/2022/index.htm>`__)
|
||||
character exists in the font, the entered characters are converted to it
|
||||
after some time or when a new character is entered. If ``•`` does not
|
||||
character exists in the font, the entered characters are converted to it after
|
||||
a configurable delay after each new character is entered. If ``•`` does not
|
||||
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
|
||||
text entered, not the bullet characters.
|
||||
@ -125,32 +143,72 @@ Accepted characters
|
||||
-------------------
|
||||
|
||||
You can set a list of accepted characters with
|
||||
:cpp:expr:`lv_textarea_set_accepted_chars(textarea, "0123456789.+-")`. Other
|
||||
characters will be ignored.
|
||||
:cpp:expr:`lv_textarea_set_accepted_chars(textarea, list)` where ``list`` is a
|
||||
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
|
||||
---------------
|
||||
|
||||
The maximum number of characters can be limited with
|
||||
:cpp:expr:`lv_textarea_set_max_length(textarea, max_char_num)`
|
||||
The maximum number of characters can be limited using
|
||||
: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),
|
||||
scrolling and drawing might be slow. However, by enabling
|
||||
:c:macro:`LV_LABEL_LONG_TXT_HINT` in ``lv_conf.h`` the performance can be
|
||||
hugely improved. This will save some additional information about the
|
||||
label to speed up its drawing. Using :c:macro:`LV_LABEL_LONG_TXT_HINT` the
|
||||
scrolling and drawing will as fast as with "normal" short texts.
|
||||
If the text in the Text Area is very long (e.g. > 20k characters), scrolling and
|
||||
drawing might be slow. However, by setting :c:macro:`LV_LABEL_LONG_TXT_HINT` in
|
||||
``lv_conf.h`` to a non-zero value, the performance with long text is significantly
|
||||
improved. It does this by saving some additional information about the current
|
||||
vertical position of the text shown. With this mode configured, scrolling and drawing
|
||||
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
|
||||
:cpp:expr:`lv_textarea_set_text_selection(textarea, true)`. This works much like
|
||||
when you select text on your PC with your mouse.
|
||||
:cpp:expr:`lv_textarea_set_text_selection(textarea, true)`. This works much like
|
||||
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:
|
||||
@ -160,14 +218,17 @@ Events
|
||||
|
||||
- :cpp:enumerator:`LV_EVENT_INSERT` Sent right before a character or text is
|
||||
inserted. The event parameter is the text about to be inserted.
|
||||
:cpp:expr:`lv_textarea_set_insert_replace(textarea, "New text")` replaces the
|
||||
text to insert. The new text cannot be in a local variable which is
|
||||
destroyed when the event callback exists. ``""`` means do not insert
|
||||
anything.
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the content of the text area has
|
||||
been changed.
|
||||
- :cpp:enumerator:`LV_EVENT_READY` Sent when :cpp:enumerator:`LV_KEY_ENTER` is pressed (or sent) to
|
||||
a one line text area.
|
||||
:cpp:expr:`lv_textarea_set_insert_replace(textarea, "New text")` can be called
|
||||
from within that event to replace the text to be inserted. The contents of the
|
||||
buffer passed must be survive long enough for the call to `lv_timer_handler()`
|
||||
that is driving the event to return (after which the Text Area's label will have
|
||||
copied the text). So it should not be a local buffer (created on the stack)
|
||||
where its contents will be destroyed before that happens. Passing ``""`` means "do
|
||||
not insert anything".
|
||||
- :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
|
||||
|
||||
|
||||
@ -4,27 +4,32 @@
|
||||
Tile View (lv_tileview)
|
||||
=======================
|
||||
|
||||
|
||||
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
|
||||
swiping. Any direction of swiping can be disabled on the tiles
|
||||
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.
|
||||
|
||||
|
||||
|
||||
.. _lv_tileview_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.
|
||||
|
||||
The parts and styles work the same as for :ref:`base_widget`.
|
||||
|
||||
|
||||
|
||||
.. _lv_tileview_usage:
|
||||
|
||||
Usage
|
||||
@ -34,19 +39,19 @@ Add a tile
|
||||
----------
|
||||
|
||||
: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
|
||||
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
|
||||
can be created.
|
||||
The returned value is a pointer to the tile (a :ref:`base_widget`) on which the
|
||||
content of the tab can be created.
|
||||
|
||||
Change tile
|
||||
-----------
|
||||
|
||||
The Tile view can scroll to a tile with
|
||||
:cpp:expr:`lv_tileview_set_tile(tileview, tile_obj, LV_ANIM_ON/OFF)` or
|
||||
:cpp:expr:`lv_tileview_set_tile_by_index(tileview, col_id, row_id, LV_ANIM_ON/OFF)`
|
||||
The Tile View can scroll to a specified tile with
|
||||
: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)`.
|
||||
|
||||
|
||||
|
||||
@ -55,9 +60,9 @@ The Tile view can scroll to a tile with
|
||||
Events
|
||||
******
|
||||
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new tile loaded by scrolling.
|
||||
:cpp:expr:`lv_tileview_get_tile_active(tabview)` can be used to get current
|
||||
tile.
|
||||
- :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 within the event to
|
||||
get a pointer to the newly-displayed tile.
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
|
||||
@ -4,58 +4,89 @@
|
||||
Window (lv_win)
|
||||
===============
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
.. _lv_win_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:
|
||||
|
||||
- Background: :ref:`base_widget`
|
||||
- Header on the background: :ref:`base_widget`
|
||||
- Title on the header: :ref:`lv_label`
|
||||
- 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:
|
||||
|
||||
Usage
|
||||
*****
|
||||
|
||||
|
||||
Create a Window
|
||||
---------------
|
||||
|
||||
:cpp:expr:`lv_win_create(parent, header_height)` creates a Window with an empty
|
||||
header.
|
||||
:cpp:expr:`lv_win_create(parent)` creates a Window that is initially
|
||||
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
|
||||
-----------------
|
||||
|
||||
Any number of texts (but typically only one) can be added to the header
|
||||
with :cpp:expr:`lv_win_add_title(win, "The title")`.
|
||||
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.
|
||||
|
||||
- :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:
|
||||
|
||||
Get the parts
|
||||
*************
|
||||
Getting the parts
|
||||
*****************
|
||||
|
||||
: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
|
||||
@ -69,7 +100,7 @@ Events
|
||||
******
|
||||
|
||||
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
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user