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

feat(docs): reorganize docs (#7136)

Browse Source
This commit is contained in:
Victor Wheeler
2024-10-23 12:53:33 -06:00
committed by GitHub
parent c61ca42a2a
commit 9b6f6d23f1
212 changed files with 6314 additions and 5806 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
docs/details/widgets/animimg.rst Normal file
View File

@@ -0,0 +1,88 @@
.. _lv_animimg:
============================
Animation Image (lv_animimg)
============================
Overview
********
The animation image is similar to the normal 'Image' Widget. The only
difference is that instead of one source image, you set an array of
multiple source images that supply "frames" in an animation.
You can specify a duration and repeat count.
.. _lv_animimg_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` A background rectangle that uses the typical
background style properties and the image itself using the image
style properties.
.. _lv_animimg_usage:
Usage
*****
Image sources
-------------
To set the image in a state, use the
:cpp:expr:`lv_animimg_set_src(imagebutton, dsc[], num)`.
Using the inner animation
-------------------------
For more advanced use cases, the animation internally used by the image can be
retrieved using the :cpp:expr:`lv_animimg_get_anim(image)`. This way, the
:ref:`Animation <animation>` functions can be used, for example to
override the animation values using the
:cpp:expr:`lv_anim_set_values(anim, start, end)` or to set a callback
on the animation completed event.
.. _lv_animimg_events:
Events
******
No special events are sent by Animation-Image Widgets.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_animimg_keys:
Keys
****
No *Keys* are processed by Animation-Image Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_animimg_example:
Example
*******
.. include:: ../../examples/widgets/animimg/index.rst
.. _lv_animimg_api:
API
***

201
docs/details/widgets/arc.rst Normal file
View File

@@ -0,0 +1,201 @@
.. _lv_arc:
============
Arc (lv_arc)
============
Overview
********
The Arc consists of a background and a foreground arc. The foreground
(indicator) can be touch-adjusted.
.. _lv_arc_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` Draws a background using the typical background
style properties and an arc using the arc style properties. The arc's
size and position will respect the *padding* style properties.
- :cpp:enumerator:`LV_PART_INDICATOR` Draws another arc using the *arc* style
properties. Its padding values are interpreted relative to the
background arc.
- :cpp:enumerator:`LV_PART_KNOB` Draws a handle on the end of the indicator using all
background properties and padding values. With zero padding the knob
size is the same as the indicator's width. Larger padding makes it
larger, smaller padding makes it smaller.
.. _lv_arc_usage:
Usage
*****
Value and range
---------------
A new value can be set using :cpp:expr:`lv_arc_set_value(arc, new_value)`. The
value is interpreted in a range (minimum and maximum values) which can
be modified with :cpp:expr:`lv_arc_set_range(arc, min, max)`. The default range
is 0..100.
The indicator arc is drawn on the main part's arc. This if the value is
set to maximum the indicator arc will cover the entire "background" arc.
To set the start and end angle of the background arc use the
:cpp:expr:`lv_arc_set_bg_angles(arc, start_angle, end_angle)` functions or
``lv_arc_set_bg_start/end_angle(arc, angle)``.
Zero degrees is at the middle right (3 o'clock) of the Widget and the
degrees are increasing in clockwise direction. The angles should be in
the [0;360] range.
Rotation
--------
An offset to the 0 degree position can be added with
:cpp:expr:`lv_arc_set_rotation(arc, deg)`.
Mode
----
The arc can be one of the following modes:
- :cpp:enumerator:`LV_ARC_MODE_NORMAL` The indicator arc is drawn from the minimum value to the current.
- :cpp:enumerator:`LV_ARC_MODE_REVERSE` The indicator arc is drawn counter-clockwise
from the maximum value to the current.
- :cpp:enumerator:`LV_ARC_MODE_SYMMETRICAL` The indicator arc is drawn from the middle point to the current value.
The mode can be set by :cpp:expr:`lv_arc_set_mode(arc, LV_ARC_MODE_...)` and
used only if the angle is set by :cpp:func:`lv_arc_set_value` or the arc is
adjusted by finger.
Change rate
-----------
If the arc is pressed the current value will set with a limited speed
according to the set *change rate*. The change rate is defined in
degree/second unit and can be set with
:cpp:expr:`lv_arc_set_change_rage(arc, rate)`
Knob offset
-----------
Changing the knob offset allows the location of the knob to be moved
relative to the end of the arc The knob offset can be set by
:cpp:expr:`lv_arc_set_knob_offset(arc, offset_angle)`, will only be visible if
:cpp:enumerator:`LV_PART_KNOB` is visible
Setting the indicator manually
------------------------------
It's also possible to set the angles of the indicator arc directly with
:cpp:expr:`lv_arc_set_angles(arc, start_angle, end_angle)` function or
``lv_arc_set_start/end_angle(arc, start_angle)``. In this case the set
"value" and "mode" are ignored.
In other words, the angle and value settings are independent. You should
exclusively use one or the other. Mixing the two might result in
unintended behavior.
To make the arc non-adjustable, remove the style of the knob and make
the Widget non-clickable:
.. code-block:: c
lv_obj_remove_style(arc, NULL, LV_PART_KNOB);
lv_obj_remove_flag(arc, LV_OBJ_FLAG_CLICKABLE);
Interactive area
----------------
By default :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST` is disabled which
means the arc's whole area is interactive.
As usual :cpp:func:`lv_obj_set_ext_click_size` can be used to increase
the sensitive area outside the arc by a specified number of pixels.
If :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST` is enabled the arc will be sensitive only
in the range of start and end background angles and on the arc itself (not inside the arc).
In this case ``ext_click_size`` makes the sensitive area ticker both inward and outward.
Additionally, a tolerance of :cpp:expr:`lv_dpx(50)` pixels is applied to each angle, extending the
hit-test range along the arc's length.
Place another Widget to the knob
--------------------------------
Another Widget can be positioned according to the current position of
the arc in order to follow the arc's current value (angle). To do this
use :cpp:expr:`lv_arc_align_obj_to_angle(arc, obj_to_align, radius_offset)`.
Similarly
:cpp:expr:`lv_arc_rotate_obj_to_angle(arc, obj_to_rotate, radius_offset)` can be
used to rotate the Widget to the current value of the arc.
It's a typical use case to call these functions in the ``VALUE_CHANGED``
event of the arc.
.. _lv_arc_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` sent when the arc is pressed/dragged to
set a new value.
- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` are sent
with the following types:
- :cpp:enumerator:`LV_ARC_DRAW_PART_BACKGROUND` The background arc.
- ``part``: :cpp:enumerator:`LV_PART_MAIN`
- ``p1``: center of the arc
- ``radius``: radius of the arc
- ``arc_dsc``
- :cpp:enumerator:`LV_ARC_DRAW_PART_FOREGROUND` The foreground arc.
- ``part``: :cpp:enumerator:`LV_PART_INDICATOR`
- ``p1``: center of the arc
- ``radius``: radius of the arc
- ``arc_dsc``
- LV_ARC_DRAW_PART_KNOB The knob
- ``part``: :cpp:enumerator:`LV_PART_KNOB`
- ``draw_area``: the area of the knob
- ``rect_dsc``:
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_arc_keys:
Keys
****
- ``LV_KEY_RIGHT/UP`` Increases the value by one.
- ``LV_KEY_LEFT/DOWN`` Decreases the value by one.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_arc_example:
Example
*******
.. include:: ../../examples/widgets/arc/index.rst
.. _lv_arc_api:
API
***

104
docs/details/widgets/bar.rst Normal file
View File

@@ -0,0 +1,104 @@
.. _lv_bar:
============
Bar (lv_bar)
============
Overview
********
The bar Widget has a background and an indicator on it. The width of the
indicator is set according to the current value of the bar.
Vertical bars can be created if the width of the Widget is smaller than
its height.
Not only the end, but also the start value of the bar can be set, which
changes the start position of the indicator.
.. _lv_bar_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` The background of the bar and it uses the typical
background style properties. Adding padding makes the indicator
smaller or larger. The ``anim_time`` style property sets the
animation time if the values set with :cpp:enumerator:`LV_ANIM_ON`.
- :cpp:enumerator:`LV_PART_INDICATOR` The indicator itself; also uses all the typical
background properties.
.. _lv_bar_usage:
Usage
*****
Value and range
---------------
A new value can be set by
``lv_bar_set_value(bar, new_value, LV_ANIM_ON/OFF)``. The value is
interpreted in a range (minimum and maximum values) which can be
modified with :cpp:expr:`lv_bar_set_range(bar, min, max)`. The default range is
0..100, and the default drawing direction is from left to right in horizontal mode and
bottom to top in vertical mode. If the minimum value is greater than the maximum value, like
100..0, the drawing direction changes to the opposite direction.
The new value in :cpp:func:`lv_bar_set_value` can be set with or without an
animation depending on the last parameter (``LV_ANIM_ON/OFF``).
Modes
-----
The bar can be one of the following modes:
- :cpp:enumerator:`LV_BAR_MODE_NORMAL` A normal bar as described above
- :cpp:enumerator:`LV_BAR_MODE_SYMMETRICAL` Draw the indicator from the zero value to current value. Requires a negative
minimum range and positive maximum range.
- :cpp:enumerator:`LV_BAR_MODE_RANGE` Allows setting the start value as well by
``lv_bar_set_start_value(bar, new_value, LV_ANIM_ON/OFF)``. The start
value always has to be smaller than the end value.
.. _lv_bar_events:
Events
******
No special events are sent by Bar Widgets.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_bar_keys:
Keys
****
No *Keys* are processed by Bar Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_bar_example:
Example
*******
.. include:: ../../examples/widgets/bar/index.rst
.. _lv_bar_api:
API
***

78
docs/details/widgets/button.rst Normal file
View File

@@ -0,0 +1,78 @@
.. _lv_button:
==================
Button (lv_button)
==================
Overview
********
Buttons have no new features compared to the :ref:`base_widget`.
They are useful for semantic purposes and have slightly different default settings.
Buttons, by default, differ from Base Widget in the following ways: -
Not scrollable - Added to the default group - Default height and width
set to :cpp:enumerator:`LV_SIZE_CONTENT`
.. _lv_button_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` The background of the button. Uses the typical
background style properties.
.. _lv_button_usage:
Usage
*****
There are no new features compared to :ref:`Base Widget <base_widget>`.
.. _lv_button_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` when the :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` flag is
enabled and the Widget is clicked. The event happens on transition
to/from the checked state.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_button_keys:
Keys
****
Note that the state of :cpp:enumerator:`LV_KEY_ENTER` is translated to
:cpp:enumerator:`LV_EVENT_PRESSED`, :cpp:enumerator:`LV_EVENT_PRESSING`
and :cpp:enumerator:`LV_EVENT_RELEASED` etc.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_button_example:
Example
*******
.. include:: ../../examples/widgets/button/index.rst
.. _lv_button_api:
API
***

164
docs/details/widgets/buttonmatrix.rst Normal file
View File

@@ -0,0 +1,164 @@
.. _lv_buttonmatrix:
===============================
Button Matrix (lv_buttonmatrix)
===============================
Overview
********
The Button Matrix Widget is a lightweight way to display multiple
buttons in rows and columns. Lightweight because the buttons are not
actually created but just virtually drawn on the fly. This way, one
button use only eight extra bytes of memory instead of the ~100-150
bytes a normal :ref:`Button <lv_button>` Widget plus the 100 or so bytes
for the :ref:`Label <lv_label>` Widget.
The Button matrix is added to the default group (if one is set). Besides
the Button matrix is an editable Widget to allow selecting and clicking
the buttons with encoder navigation as well.
.. _lv_buttonmatrix_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` The background of the button matrix, uses the
typical background style properties. ``pad_row`` and ``pad_column``
sets the space between the buttons.
- :cpp:enumerator:`LV_PART_ITEMS` The buttons all use the text and typical background
style properties except translations and transformations.
.. _lv_buttonmatrix_usage:
Usage
*****
Button's text
-------------
There is a text on each button. To specify them a descriptor string
array, called *map*, needs to be used. The map can be set with
:cpp:expr:`lv_buttonmatrix_set_map(buttonm, my_map)`. The declaration of a map should
look like ``const char * map[] = {"button1", "button2", "button3", NULL}``. Note
that the last element has to be either ``NULL`` or an empty string
(``""``)!
Use ``"\n"`` in the map to insert a **line break**. E.g.
``{"button1", "button2", "\n", "button3", ""}``. Each line's buttons have their
width calculated automatically. So in the example the first row will
have 2 buttons each with 50% width and a second row with 1 button having
100% width.
Control buttons
---------------
The buttons' width can be set relative to the other button in the same
row with :cpp:expr:`lv_buttonmatrix_set_button_width(buttonm, button_id, width)` E.g. in a
line with two buttons: *buttonA, width = 1* and *buttonB, width = 2*, *buttonA*
will have 33 % width and *buttonB* will have 66 % width. It's similar to
how the
`"flex-grow" <https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow>`__
property works in CSS. The width must be in the [1..15] range and the
default width is 1.
In addition to the width, each button can be customized with the
following parameters:
- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_HIDDEN`: Makes a button hidden (hidden buttons still take up space in the layout, they are just not visible or clickable)
- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_NO_REPEAT`: Disable repeating when the button is long pressed
- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_DISABLED`: Makes a button disabled Like :cpp:enumerator:`LV_STATE_DISABLED` on normal Widgets
- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CHECKABLE`: Enable toggling of a button. I.e. :cpp:enumerator:`LV_STATE_CHECKED` will be added/removed as the button is clicked
- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CHECKED`: Make the button checked. It will use the :cpp:enumerator:`LV_STATE_CHECHKED` styles.
- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CLICK_TRIG`: Enabled: send LV_EVENT_VALUE_CHANGE on CLICK, Disabled: send :cpp:enumerator:`LV_EVENT_VALUE_CHANGE` on PRESS
- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_POPOVER`: Show the button label in a popover when pressing this key
- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CUSTOM_1`: Custom free to use flag
- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CUSTOM_2`: Custom free to use flag
By default, all flags are disabled.
To set or clear a button's control attribute, use
:cpp:expr:`lv_buttonmatrix_set_button_ctrl(buttonm, button_id, LV_BUTTONMATRIX_CTRL_...)` and
:cpp:expr:`lv_buttonmatrix_clear_button_ctrl(buttonm, button_id, LV_BUTTONMATRIX_CTRL_...)`
respectively. More ``LV_BUTTONMATRIX_CTRL_...`` values can be OR-ed
To set/clear the same control attribute for all buttons of a button
matrix, use :cpp:expr:`lv_buttonmatrix_set_button_ctrl_all(buttonm, LV_BUTTONMATRIX_CTRL_...)`
and :cpp:expr:`lv_buttonmatrix_clear_button_ctrl_all(buttonm, LV_BUTTONMATRIX_CTRL_...)`.
The set a control map for a button matrix (similarly to the map for the
text), use :cpp:expr:`lv_buttonmatrix_set_ctrl_map(buttonm, ctrl_map)`. An element of
``ctrl_map`` should look like
:cpp:expr:`ctrl_map[0] = width | LV_BUTTONMATRIX_CTRL_NO_REPEAT | LV_BUTTONMATRIX_CTRL_CHECHKABLE`.
The number of elements should be equal to the number of buttons
(excluding newlines characters).
One check
---------
The "One check" feature can be enabled with
:cpp:expr:`lv_buttonmatrix_set_one_checked(buttonm, true)` to allow only one button to
be checked at a time.
.. _lv_buttonmatrix_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED`: Sent when a button is pressed/released or
repeated after long press. The event parameter is set to the ID of
the pressed/released button.
:cpp:expr:`lv_buttonmatrix_get_selected_button(buttonm)` returns the index of the most
recently released or focused button or :cpp:enumerator:`LV_BUTTONMATRIX_BUTTON_NONE` if no
such button.
:cpp:expr:`lv_buttonmatrix_get_button_text(buttonm, button_id)` returns a pointer to the
text of ``button_id``\ th button.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_buttonmatrix_keys:
Keys
****
- ``LV_KEY_RIGHT/UP/LEFT/RIGHT`` To navigate among the buttons to
select one
- :cpp:enumerator:`LV_KEY_ENTER` To press/release the selected button
Note that long pressing the button matrix with an encoder can mean to
enter/leave edit mode and simply long pressing a button to make it
repeat as well. To avoid this contradiction it's suggested to add
:cpp:expr:`lv_buttonmatrix_set_button_ctrl_all(buttonm, LV_BUTTONMATRIX_CTRL_CLICK_TRIG | LV_BUTTONMATRIX_CTRL_NO_REPEAT)`
to the button matrix if used with encoder. This way, the pressed button
repeat feature is disabled and on leaving edit mode the selected button
won't be activated.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_buttonmatrix_example:
Example
*******
.. include:: ../../examples/widgets/buttonmatrix/index.rst
.. _lv_buttonmatrix_api:
API
***

170
docs/details/widgets/calendar.rst Normal file
View File

@@ -0,0 +1,170 @@
.. _lv_calendar:
======================
Calendar (lv_calendar)
======================
Overview
********
The Calendar Widget is a classic calendar which can: - show the days of
any month in a 7x7 matrix - Show the name of the days - highlight the
current day (today) - highlight any user-defined dates
The Calendar is added to the default group (if it is set). Calendar is
an editable Widget which allow selecting and clicking the dates with
encoder navigation as well.
To make the Calendar flexible, by default it doesn't show the current
year or month. Instead, there are optional "headers" that can be
attached to the calendar.
.. _lv_calendar_parts_and_styles:
Parts and Styles
****************
The calendar Widget uses the :ref:`Button Matrix <lv_buttonmatrix>`
Widget under the hood to arrange the days into a matrix.
- :cpp:enumerator:`LV_PART_MAIN` The background of the calendar. Uses all the background related style properties.
- :cpp:enumerator:`LV_PART_ITEMS` Refers to the dates and day names. Button matrix control flags are set to differentiate the
buttons and a custom drawer event is added modify the properties of the buttons as follows:
- day names have no border, no background and drawn with a gray color
- days of the previous and next month have :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_DISABLED` flag
- today has a thicker border with the theme's primary color - highlighted days have some opacity with the theme's primary color.
.. _lv_calendar_usage:
Usage
*****
Some functions use the :cpp:struct:`lv_calendar_date_t` type which is a structure
with ``year``, ``month`` and ``day`` fields.
Current date
------------
To set the current date (today), use the
:cpp:expr:`lv_calendar_set_today_date(calendar, year, month, day)` function.
``month`` needs to be in 1..12 range and ``day`` in 1..31 range.
Shown date
----------
To set the shown date, use
:cpp:expr:`lv_calendar_set_shown_date(calendar, year, month)`
Highlighted days
----------------
The list of highlighted dates should be stored in a
:cpp:struct:`lv_calendar_date_t` array loaded by
:cpp:expr:`lv_calendar_set_highlighted_dates(calendar, highlighted_dates, date_num)`.
Only the array's pointer will be saved so the array should be a static
or global variable.
Name of the days
----------------
The name of the days can be adjusted with
:cpp:expr:`lv_calendar_set_day_names(calendar, day_names)` where ``day_names``
looks like ``const char * day_names[7] = {"Su", "Mo", ...};`` Only the
pointer of the day names is saved so the elements should be static,
global or constant variables.
Custom year list
----------------
Sets a custom year list with :cpp:expr:`lv_calendar_header_dropdown_set_year_list(calendar, years_list)`
where ``years_list`` is a pointer to the custom years list. It can be a constant string
like ``static const char * years = "2023\n2022\n2021\n2020\n2019";``,
or can be generated dynamically into a buffer as well.
Chinese calendar
----------------
The Chinese calendar is a traditional cultural tool that integrates elements
such as the lunar calendar, solar terms, and traditional festivals. It is
widely used in Chinese social life, helping people understand the dates of
the lunar calendar, arrange festival activities, and inherit the excellent
traditional culture of the Chinese nation. Whether in families, businesses,
or education, the Chinese calendar plays an irreplaceable role, enabling
people to better understand and appreciate the charm of Chinese traditional
culture.
If you want to use the Chinese calendar, please
use :cpp:expr:`lv_calendar_set_chinese_mode(calendar, true)` to enable it.
.. _lv_calendar_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent if a date is clicked.
:cpp:expr:`lv_calendar_get_pressed_date(calendar, &date)` set ``date`` to the
date currently being pressed. Returns :cpp:enumerator:`LV_RESULT_OK` if there is a
valid pressed date, else :cpp:enumerator:`LV_RESULT_INVALID`.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_calendar_keys:
Keys
****
- ``LV_KEY_RIGHT/UP/LEFT/RIGHT`` To navigate among the buttons to dates
- :cpp:enumerator:`LV_KEY_ENTER` To press/release the selected date
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_calendar_header:
Headers
*******
**From v8.1 the header is added directly into the Calendar widget and
the API of the headers has been changed.**
Arrow buttons
-------------
:cpp:expr:`lv_calendar_header_arrow_create(calendar)` creates a header that
contains a left and right arrow on the sides and a text with the current
year and month between them.
Drop-down
---------
:cpp:expr:`lv_calendar_header_dropdown_create(calendar)` creates a header that
contains 2 drop-drown lists: one for the year and another for the month.
.. _lv_calendar_example:
Example
*******
.. include:: ../../examples/widgets/calendar/index.rst
.. _lv_calendar_api:
API
***

119
docs/details/widgets/canvas.rst Normal file
View File

@@ -0,0 +1,119 @@
.. _lv_canvas:
==================
Canvas (lv_canvas)
==================
Overview
********
A Canvas inherits from :ref:`Image <lv_image>` where the user can draw
anything. Rectangles, texts, images, lines, arcs can be drawn here using
lvgl's drawing engine.
.. _lv_canvas_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` Uses the typical rectangle style properties and image
style properties.
.. _lv_canvas_usage:
Usage
*****
Buffer
------
The Canvas needs a buffer in which it stores the drawn image. To assign a
buffer to a Canvas, use
:cpp:expr:`lv_canvas_set_buffer(canvas, buffer, width, height, LV_COLOR_FORMAT_...)`.
Where ``buffer`` is a static buffer (not just a local variable) to hold
the image of the canvas. For example for a 100x50 ARGB8888 buffer:
``static uint8_t buffer[100 * 50 * 4]``.
Or you can use
``static uint8_t buffer[LV_CANVAS_BUF_SIZE(width, height, bit_per_pixel, stride_in_bytes)]``.
The canvas supports all the color formats like
:cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888` or :cpp:enumerator:`LV_COLOR_FORMAT_I2`. See the full
list in the :ref:`Color formats <overview_image_color_formats>` section.
Indexed colors
--------------
For ``LV_COLOR_FORMAT_I1/2/4/8`` color formats a palette needs to be
initialized with :cpp:expr:`lv_canvas_set_palette(canvas, 3, lv_color_hex(0xff0000))`. It
sets pixels with *index=3* to red.
Drawing
-------
To set a pixel's color on the canvas, use
:cpp:expr:`lv_canvas_set_px_color(canvas, x, y, color, opa)`. With
``LV_COLOR_FORMAT_I1/2/4/8`` the index of the color needs to be passed as
color like this ``lv_color_from_int(13);``. It passes index 13 as a color.
:cpp:expr:`lv_canvas_fill_bg(canvas, lv_color_hex(0x00ff00), LV_OPA_50)` fills the whole
canvas to blue with 50% opacity. Note that if the current color format
doesn't support colors (e.g. :cpp:enumerator:`LV_COLOR_FORMAT_A8`) the color will be
ignored. Similarly, if opacity is not supported
(e.g. :cpp:enumerator:`LV_COLOR_FORMAT_RGB565`) it will be ignored.
An array of pixels can be copied to the canvas with
:cpp:expr:`lv_canvas_copy_buf(canvas, buffer_to_copy, x, y, width, height)`. The
color format of the buffer and the canvas need to match.
To draw something to the canvas use LVGL's draw functions directly. See the examples for more details.
The draw function can draw to any color format to which LVGL can render. Typically it means
:cpp:enumerator:`LV_COLOR_FORMAT_RGB565`, :cpp:enumerator:`LV_COLOR_FORMAT_RGB888`,
:cpp:enumerator:`LV_COLOR_FORMAT_XRGB888`, and :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888`.
.. _lv_canvas_events:
Events
******
No special events are sent by canvas Widgets. The same events are sent
as for the
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_canvas_keys:
Keys
****
No *Keys* are processed by Canvas Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_canvas_example:
Example
*******
.. include:: ../../examples/widgets/canvas/index.rst
.. _lv_canvas_api:
API
***

249
docs/details/widgets/chart.rst Normal file
View File

@@ -0,0 +1,249 @@
.. _lv_chart:
================
Chart (lv_chart)
================
Overview
********
Charts are a basic Widget to visualize data points. Currently *Line*
charts (connect points with lines and/or draw points on them) and *Bar*
charts are supported.
Charts can have: - division lines - 2 y axis - axis ticks and texts on
ticks - cursors - scrolling and zooming
.. _lv_chart_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` The background of the chart. Uses all the typical
background and *line* (for the division lines) related style
properties. *Padding* makes the series area smaller. For column
charts ``pad_column`` sets the space between the columns of the
adjacent indices.
- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar used if the chart is zoomed. See
:ref:`base_widget`'s documentation for details.
- :cpp:enumerator:`LV_PART_ITEMS` Refers to the line or bar series.
- Line chart: The *line* properties are used by the lines.
``width``, ``height``, ``bg_color`` and ``radius`` is used to set
the appearance of points.
- Bar chart: The typical background properties are used to style the
bars. ``pad_column`` sets the space between the columns on the
same index.
- :cpp:enumerator:`LV_PART_INDICATOR` Refers to the points on line and scatter chart
(small circles or squares).
- :cpp:enumerator:`LV_PART_CURSOR` *Line* properties are used to style the cursors.
``width``, ``height``, ``bg_color`` and ``radius`` are used to set
the appearance of points.
.. _lv_chart_usage:
Usage
*****
Chart type
----------
The following data display types exist:
- :cpp:enumerator:`LV_CHART_TYPE_NONE`: Do not display any data. Can be used to hide the series.
- :cpp:enumerator:`LV_CHART_TYPE_LINE`: Draw lines between the data points and/or points (rectangles or circles) on the data points.
- :cpp:enumerator:`LV_CHART_TYPE_BAR`: Draw bars.
- :cpp:enumerator:`LV_CHART_TYPE_SCATTER`: X/Y chart drawing point's and lines between the points. .
You can specify the display type with
:cpp:expr:`lv_chart_set_type(chart, LV_CHART_TYPE_...)`.
Data series
-----------
You can add any number of series to the charts by
:cpp:expr:`lv_chart_add_series(chart, color, axis)`. This allocates an
:cpp:expr:`lv_chart_series_t` structure which contains the chosen ``color`` and
an array for the data points. ``axis`` can have the following values:
- :cpp:enumerator:`LV_CHART_AXIS_PRIMARY_Y`: Left axis
- :cpp:enumerator:`LV_CHART_AXIS_SECONDARY_Y`: Right axis
- :cpp:enumerator:`LV_CHART_AXIS_PRIMARY_X`: Bottom axis
- :cpp:enumerator:`LV_CHART_AXIS_SECONDARY_X`: Top axis
``axis`` tells which axis's range should be used to scale the values.
:cpp:expr:`lv_chart_set_ext_y_array(chart, ser, value_array)` makes the chart
use an external array for the given series. ``value_array`` should look
like this: ``int32_t * value_array[num_points]``. The array size
needs to be large enough to hold all the points of that series. The
array's pointer will be saved in the chart so it needs to be global,
static or dynamically allocated. Note: you should call
:cpp:expr:`lv_chart_refresh(chart)` after the external data source has been
updated to update the chart.
The value array of a series can be obtained with
:cpp:expr:`lv_chart_get_y_array(chart, ser)`, which can be used with
``ext_array`` or *normal array*\ s.
For :cpp:enumerator:`LV_CHART_TYPE_SCATTER` type
:cpp:expr:`lv_chart_set_ext_x_array(chart, ser, value_array)` and
:cpp:expr:`lv_chart_get_x_array(chart, ser)` can be used as well.
Modify the data
---------------
You have several options to set the data of series:
1. Set the values manually in the array like ``ser1->points[3] = 7`` and refresh the chart with :cpp:enumerator:`lv_chart_refresh(chart)`.
2. Use :cpp:expr:`lv_chart_set_value_by_id(chart, ser, id, value)` where ``id`` is the index of the point you wish to update.
3. Use the :cpp:expr:`lv_chart_set_next_value(chart, ser, value)`.
4. Initialize all points to a given value with :cpp:expr:`lv_chart_set_all_value(chart, ser, value)`.
Use :cpp:enumerator:`LV_CHART_POINT_NONE` as value to make the library skip drawing
that point, column, or line segment.
For :cpp:enumerator:`LV_CHART_TYPE_SCATTER` type
:cpp:expr:`lv_chart_set_value_by_id2(chart, ser, id, value)` and
:cpp:expr:`lv_chart_set_next_value2(chart, ser, x_value, y_value)` can be used
as well.
Update modes
------------
:cpp:func:`lv_chart_set_next_value` can behave in two ways depending on *update
mode*:
- :cpp:enumerator:`LV_CHART_UPDATE_MODE_SHIFT`: Shift old data to the left and add the new one to the right.
- :cpp:enumerator:`LV_CHART_UPDATE_MODE_CIRCULAR`: Add the new data in circular fashion, like an ECG diagram.
The update mode can be changed with
:cpp:expr:`lv_chart_set_update_mode(chart, LV_CHART_UPDATE_MODE_...)`.
Number of points
----------------
The number of points in the series can be modified by
:cpp:expr:`lv_chart_set_point_count(chart, point_num)`. The default value is 10.
Note: this also affects the number of points processed when an external
buffer is assigned to a series, so you need to be sure the external
array is large enough.
Handling large number of points
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
On line charts, if the number of points is greater than the pixels
horizontally, the Chart will draw only vertical lines to make the
drawing of large amount of data effective. If there are, let's say, 10
points to a pixel, LVGL searches the smallest and the largest value and
draws a vertical lines between them to ensure no peaks are missed.
Vertical range
--------------
You can specify the minimum and maximum values in y-direction with
:cpp:expr:`lv_chart_set_range(chart, axis, min, max)`. ``axis`` can be
:cpp:enumerator:`LV_CHART_AXIS_PRIMARY` (left axis) or :cpp:enumerator:`LV_CHART_AXIS_SECONDARY`
(right axis).
The value of the points will be scaled proportionally. The default range
is: 0..100.
Division lines
--------------
The number of horizontal and vertical division lines can be modified by
:cpp:expr:`lv_chart_set_div_line_count(chart, hdiv_num, vdiv_num)`. The default
settings are 3 horizontal and 5 vertical division lines. If there is a
visible border on a side and no padding on that side, the division line
would be drawn on top of the border and therefore it won't be drawn.
Override default start point for series
---------------------------------------
If you want a plot to start from a point other than the default which is
``point[0]`` of the series, you can set an alternative index with the
function :cpp:expr:`lv_chart_set_x_start_point(chart, ser, id)` where ``id`` is
the new index position to start plotting from.
Note that :cpp:enumerator:`LV_CHART_UPDATE_MODE_SHIFT` also changes the
``start_point``.
Tick marks and labels
---------------------
With the help of :ref:`Scale <lv_scale>`, vertical and horizontal scales can be added in a very flexible way.
See the example below to learn more.
Zoom
----
To zoom the chart all you need to is wrapping it into a parent container and set the chart's width or height
to larger value. This way the chart will be scrollable on its parent.
Cursor
------
A cursor can be added with ``lv_chart_cursor_t * c1 = lv_chart_add_cursor(chart, color, dir);``.
The possible values of ``dir`` ``LV_DIR_NONE/RIGHT/UP/LEFT/DOWN/HOR/VER/ALL`` or their OR-ed values to
tell in which direction(s) should the cursor be drawn.
:cpp:expr:`lv_chart_set_cursor_pos(chart, cursor, &point)` sets the position of
the cursor. ``pos`` is a pointer to an :cpp:struct:`lv_point_t` variable. E.g.
``lv_point_t point = {10, 20}``. If the chart is scrolled the cursor
will remain in the same place.
:cpp:expr:`lv_chart_get_point_pos_by_id(chart, series, id, &point_out)` gets the
coordinate of a given point. It's useful to place the cursor at a given
point.
:cpp:expr:`lv_chart_set_cursor_point(chart, cursor, series, point_id)` sticks
the cursor at a point. If the point's position changes (new value or
scrolling) the cursor will move with the point.
.. _lv_chart_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new point is clicked pressed.
:cpp:expr:`lv_chart_get_pressed_point(chart)` returns the zero-based index of
the pressed point.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_chart_keys:
Keys
****
No *Keys* are processed by Chart Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_chart_example:
Example
*******
.. include:: ../../examples/widgets/chart/index.rst
.. _lv_chart_api:
API
***

107
docs/details/widgets/checkbox.rst Normal file
View File

@@ -0,0 +1,107 @@
.. _lv_checkbox:
======================
Checkbox (lv_checkbox)
======================
Overview
********
The Checkbox Widget is created from a "tick box" and a label. When the
Checkbox is clicked the tick box is toggled.
.. _lv_checkbox_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` The is the background of the Checkbox and it uses
the text and all the typical background style properties.
``pad_column`` adjusts the spacing between the tickbox and the label
- :cpp:enumerator:`LV_PART_INDICATOR` The "tick box" is a square that uses all the
typical background style properties. By default, its size is equal to
the height of the main part's font. Padding properties make the tick
box larger in the respective directions.
The Checkbox is added to the default group (if it is set).
.. _lv_checkbox_usage:
Usage
*****
Text
----
The text can be modified with the
:cpp:expr:`lv_checkbox_set_text(cb, "New text")` function and will be
dynamically allocated.
To set a static text, use :cpp:expr:`lv_checkbox_set_static_text(cb, txt)`. This
way, only a pointer to ``txt`` will be stored. The text then shouldn't
be deallocated while the checkbox exists.
Check, uncheck, disable
-----------------------
You can manually check, un-check, and disable the Checkbox by using the
common state add/clear function:
.. code-block:: c
lv_obj_add_state(cb, LV_STATE_CHECKED); /* Make the checkbox checked */
lv_obj_remove_state(cb, LV_STATE_CHECKED); /* Make the checkbox unchecked */
lv_obj_add_state(cb, LV_STATE_CHECKED | LV_STATE_DISABLED); /* Make the checkbox checked and disabled */
To get whether the checkbox is checked or not use:
:cpp:expr:`lv_obj_has_state(cb, LV_STATE_CHECKED)`.
.. _lv_checkbox_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the checkbox is toggled.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_checkbox_keys:
Keys
****
The following *Keys* are processed by the 'Buttons': -
``LV_KEY_RIGHT/UP`` Go to toggled state if toggling is enabled -
``LV_KEY_LEFT/DOWN`` Go to non-toggled state if toggling is enabled -
:cpp:enumerator:`LV_KEY_ENTER` Clicks the checkbox and toggles it
Note that, as usual, the state of :cpp:enumerator:`LV_KEY_ENTER` is translated to
``LV_EVENT_PRESSED/PRESSING/RELEASED`` etc.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_checkbox_example:
Example
*******
.. include:: ../../examples/widgets/checkbox/index.rst
.. _lv_checkboxapi:
API
***

180
docs/details/widgets/dropdown.rst Normal file
View File

@@ -0,0 +1,180 @@
.. _lv_dropdown:
============================
Drop-Down List (lv_dropdown)
============================
Overview
********
The drop-down list allows the user to select one value from a list.
The drop-down list is closed by default and displays a single value or a
predefined text. When activated (by click on the drop-down list), a list
is created from which the user may select one option. When the user
selects a new value, the list is deleted again.
The Drop-down list is added to the default group (if it is set). Besides
the Drop-down list is an editable Widget to allow selecting an option
with encoder navigation as well.
.. _lv_dropdown_parts_and_styles:
Parts and Styles
****************
The Dropdown widget is built from the elements: "button" and "list"
(both not related to the button and list widgets)
Button
------
- :cpp:enumerator:`LV_PART_MAIN` The background of the button. Uses the typical
background properties and text properties for the text on it.
- :cpp:enumerator:`LV_PART_INDICATOR` Typically an arrow symbol that can be an image
or a text (:cpp:enumerator:`LV_SYMBOL`).
The button goes to :cpp:enumerator:`LV_STATE_CHECKED` when it's opened.
List
----
- :cpp:enumerator:`LV_PART_MAIN` The list itself. Uses the typical background
properties. ``max_height`` can be used to limit the height of the
list.
- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar background, border, shadow
properties and width (for its own width) and right padding for the
spacing on the right.
- :cpp:enumerator:`LV_PART_SELECTED` Refers to the currently pressed, checked or
pressed+checked option. Also uses the typical background properties.
The list is hidden/shown on open/close. To add styles to it use
:cpp:expr:`lv_dropdown_get_list(dropdown)` to get the list Widget. For example:
.. code-block:: c
lv_obj_t * list = lv_dropdown_get_list(dropdown) /*Get the list*/
lv_obj_add_style(list, &my_style, selector) /*Add the styles to the list*/
Alternatively the theme can be extended with the new styles.
.. _lv_dropdown_usage:
Usage
*****
.. _lv_dropdown_options:
Options
*******
Set options
-----------
Options are passed to the drop-down list as a string with
:cpp:expr:`lv_dropdown_set_options(dropdown, options)`. Options should be
separated by ``\n``. For example: ``"First\nSecond\nThird"``. This
string will be saved in the drop-down list, so it can in a local
variable.
The :cpp:expr:`lv_dropdown_add_option(dropdown, "New option", pos)` function
inserts a new option to ``pos`` index.
To save memory the options can set from a static(constant) string as well
with :cpp:expr:`lv_dropdown_set_static_options(dropdown, options)`. In this case
the options string should be alive while the drop-down list exists and
:cpp:func:`lv_dropdown_add_option` can't be used
You can select an option manually with
:cpp:expr:`lv_dropdown_set_selected(dropdown, id)`, where ``id`` is the index of
an option.
Get selected option
-------------------
The get the *index* of the selected option, use
:cpp:expr:`lv_dropdown_get_selected(dropdown)`.
:cpp:expr:`lv_dropdown_get_selected_str(dropdown, buf, buf_size)` copies the
*name* of the selected option to ``buf``.
Direction
---------
The list can be created on any side. The default :cpp:enumerator:`LV_DIR_BOTTOM` can
be modified by :cpp:expr:`lv_dropdown_set_dir(dropdown, LV_DIR_LEFT)` function.
If the list would be vertically out of the screen, it will be aligned to
the edge.
Symbol
------
A symbol (typically an arrow) can be added to the dropdown list with
:cpp:expr:`lv_dropdown_set_symbol(dropdown, LV_SYMBOL_...)`
If the direction of the drop-down list is :cpp:enumerator:`LV_DIR_LEFT` the symbol
will be shown on the left, otherwise on the right.
Show selected
-------------
The main part can either show the selected option or a static text. If a
static is set with :cpp:expr:`lv_dropdown_set_text(dropdown, "Some text")` it
will be shown regardless to th selected option. If the text is ``NULL``
the selected option is displayed on the button.
Manually open/close
-------------------
To manually open or close the drop-down list the
``lv_dropdown_open/close(dropdown)`` function can be used.
.. _lv_dropdown_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the new option is selected or the list is opened/closed.
- :cpp:enumerator:`LV_EVENT_CANCEL` Sent when the list is closed
- :cpp:enumerator:`LV_EVENT_READY` Sent when the list is opened
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_dropdown_keys:
Keys
****
- ``LV_KEY_RIGHT/DOWN`` Select the next option.
- ``LV_KEY_LEFT/UP`` Select the previous option.
- :cpp:enumerator:`LV_KEY_ENTER` Apply the selected option (Sends
:cpp:enumerator:`LV_EVENT_VALUE_CHANGED` event and closes the drop-down list).
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_dropdown_example:
Example
*******
.. include:: ../../examples/widgets/dropdown/index.rst
.. _lv_dropdown_api:
API
***

232
docs/details/widgets/image.rst Normal file
View File

@@ -0,0 +1,232 @@
.. _lv_image:
================
Image (lv_image)
================
Overview
********
Images are the basic Widget to display images from flash (as arrays) or
from files. Images can display symbols (``LV_SYMBOL_...``) as well.
Using the :ref:`Image decoder interface <overview_image_decoder>` custom image formats
can be supported as well.
.. _lv_image_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` A background rectangle that uses the typical
background style properties and the image itself using the image
style properties.
.. _lv_image_usage:
Usage
*****
Image source
------------
To provide maximum flexibility, the source of the image can be:
- a variable in code (a C array with the pixels).
- a file stored externally (e.g. on an SD card).
- a text with :ref:`Symbols <fonts_symbols>`.
To set the source of an image, use :cpp:expr:`lv_image_set_src(img, src)`.
To generate a pixel array from a PNG, JPG or BMP image, use the `Online image converter tool <https://lvgl.io/tools/imageconverter>`__
and set the converted image with its pointer :cpp:expr:`lv_image_set_src(img1, &converted_img_var)`
To make the variable visible in the C file, you need to declare it with
:cpp:expr:`LV_IMAGE_DECLARE(converted_img_var)`.
To use external files, you also need to convert the image files using
the online converter tool but now you should select the binary output
format. You also need to use LVGL's file system module and register a
driver with some functions for the basic file operation. Go to the
:ref:`File system <overview_file_system>` to learn more. To set an image sourced
from a file, use :cpp:expr:`lv_image_set_src(img, "S:folder1/my_img.bin")`.
You can also set a symbol similarly to :ref:`Labels <lv_label>`. In
this case, the image will be rendered as text according to the *font*
specified in the style. It enables to use of light-weight monochrome
"letters" instead of real images. You can set symbol like
:cpp:expr:`lv_image_set_src(img1, LV_SYMBOL_OK)`.
Label as an image
-----------------
Images and labels are sometimes used to convey the same thing. For
example, to describe what a button does. Therefore, images and labels
are somewhat interchangeable, that is the images can display texts by
using :c:macro:`LV_SYMBOL_DUMMY` as the prefix of the text. For example,
:cpp:expr:`lv_image_set_src(img, LV_SYMBOL_DUMMY, "Some text")`.
Transparency
------------
The internal (variable) and external images support 2 transparency
handling methods:
- **Alpha byte**: An alpha byte is added to every pixel that contains
the pixel's opacity
Palette and Alpha index
-----------------------
Besides the *True color* (RGB) color format, the following formats are
supported:
- **Indexed**: Image has a palette.
- **Alpha indexed**: Only alpha values are stored.
These options can be selected in the image converter. To learn more
about the color formats, read the :ref:`Images <overview_image>` section.
Recolor
-------
A color can be mixed with every pixel of an image with a given
intensity. This can be useful to show different states (checked,
inactive, pressed, etc.) of an image without storing more versions of
the same image. This feature can be enabled in the style by setting
``img_recolor_opa`` between :cpp:enumerator:`LV_OPA_TRANSP` (no recolor, value: 0) and
:cpp:enumerator:`LV_OPA_COVER` (full recolor, value: 255). The default value is
:cpp:enumerator:`LV_OPA_TRANSP` so this feature is disabled.
The color to mix is set by ``img_recolor``.
Offset
------
With :cpp:expr:`lv_image_set_offset_x(img, x_ofs)` and
:cpp:expr:`lv_image_set_offset_y(img, y_ofs)`, you can add some offset to the
displayed image. Useful if the Widget size is smaller than the image
source size. Using the offset parameter a `Texture atlas <https://en.wikipedia.org/wiki/Texture_atlas>`__
or a "running image" effect can be created by :ref:`Animating <animation>` the x or y offset.
Transformations
---------------
Using the :cpp:expr:`lv_image_set_scale(img, factor)` the images will be zoomed.
Set ``factor`` to ``256`` or :c:macro:`LV_SCALE_NONE` to disable zooming. A
larger value enlarges the images (e.g. ``512`` double size), a smaller
value shrinks it (e.g. ``128`` half size). Fractional scale works as
well. E.g. ``281`` for 10% enlargement.
:cpp:expr:`lv_image_set_scale_x(img, factor)` and
:cpp:expr:`lv_image_set_scale_y(img, factor)` also can be used to
the scale independently horizontally and vertically (non-uniform scale).
To rotate the image use :cpp:expr:`lv_image_set_rotation(img, angle)`. Angle has 0.1
degree precision, so for 45.8° set 458.
By default, the pivot point of the rotation is the center of the image.
It can be changed with :cpp:expr:`lv_image_set_pivot(img, pivot_x, pivot_y)`.
``0;0`` is the top left corner.
The quality of the transformation can be adjusted with
:cpp:expr:`lv_image_set_antialias(img, true)`. With enabled anti-aliasing
the transformations are higher quality but slower.
The transformations require the whole image to be available. Therefore
indexed images (``LV_COLOR_FORMAT_I1/2/4/8_...``), alpha only images cannot be transformed.
In other words transformations work only on normal (A)RGB or A8 images stored as
C array, or if a custom :ref:`overview_image_decoder`
returns the whole image.
Note that the real coordinates of image Widgets won't change during
transformation. That is :cpp:expr:`lv_obj_get_width/height/x/y()` will return
the original, non-zoomed coordinates.
**IMPORTANT** The transformation of the image is independent of the
transformation properties coming from styles. (See
:ref:`here <styles_opacity_blend_modes_transformations>`). The main
differences are that pure image widget transformation
- doesn't transform the children of the image widget
- image is transformed directly without creating an intermediate layer (buffer) to snapshot the widget
Inner align
-----------
By default the image widget's width and height is :cpp:enumerator:`LV_SIZE_CONTENT`.
It means that the widget will be sized automatically according to the image source.
If the widget's width or height is set the larger value the ``inner_align`` property tells
how to align the image source inside the widget.
The alignment set any of these:
- :cpp:enumerator:`LV_IMAGE_ALIGN_DEFAULT`: Meaning top left
- :cpp:enumerator:`LV_IMAGE_ALIGN_TOP_LEFT`
- :cpp:enumerator:`LV_IMAGE_ALIGN_TOP_MID`
- :cpp:enumerator:`LV_IMAGE_ALIGN_TOP_RIGHT`
- :cpp:enumerator:`LV_IMAGE_ALIGN_BOTTOM_LEFT`
- :cpp:enumerator:`LV_IMAGE_ALIGN_BOTTOM_MID`
- :cpp:enumerator:`LV_IMAGE_ALIGN_BOTTOM_RIGHT`
- :cpp:enumerator:`LV_IMAGE_ALIGN_LEFT_MID`
- :cpp:enumerator:`LV_IMAGE_ALIGN_RIGHT_MID`
- :cpp:enumerator:`LV_IMAGE_ALIGN_CENTER`
- :cpp:enumerator:`LV_IMAGE_ALIGN_STRETCH`
- :cpp:enumerator:`LV_IMAGE_ALIGN_TILE`
The ``offset`` value is applied after the image source is aligned. For example setting an ``y=-10``
and :cpp:enumerator:`LV_IMAGE_ALIGN_CENTER` will move the image source up a little bit
from the center of the widget.
Or to automatically scale or tile the image
- :cpp:enumerator:`LV_IMAGE_ALIGN_STRETCH` Set X and Y scale to fill the widget's area
- :cpp:enumerator:`LV_IMAGE_ALIGN_TILE` Tile the image to will the widget area. Offset is applied to shift the tiling.
The alignment can be set by :cpp:func:`lv_image_set_inner_align`
.. _lv_image_events:
Events
******
No special events are sent by Image Widgets. By default, Image Widgets are created
without the LV_OBJ_FLAG_CLICKABLE flag, but you can add it to make a Label Widget
emit LV_EVENT_CLICKED events if desired.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_image_keys:
Keys
****
No *Keys* are processed by Image Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_image_example:
Example
*******
.. include:: ../../examples/widgets/image/index.rst
.. _lv_image_api:
API
***

110
docs/details/widgets/imagebutton.rst Normal file
View File

@@ -0,0 +1,110 @@
.. _lv_imagebutton:
=============================
Image Button (lv_imagebutton)
=============================
Overview
********
The Image button is very similar to the simple 'Button' Widget. The only
difference is that it displays user-defined images in each state instead
of drawing a rectangle.
You can set a left, right and center image, and the center image will be
repeated to match the width of the Widget.
.. _lv_imagebutton_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` Refers to the image(s). If background style
properties are used, a rectangle will be drawn behind the image
button.
.. _lv_imagebutton_usage:
Usage
*****
Image sources
-------------
To set the image in a state, use the
:cpp:expr:`lv_imagebutton_set_src(imagebutton, LV_IMAGEBUTTON_STATE_..., src_left, src_center, src_right)`.
The image sources work the same as described in the :ref:`Image Widget <lv_image>`
except that "Symbols" are not supported by the Image button. Any of the sources can ``NULL``.
If only ``src_center`` is specified, the width of the widget will be set automatically to the
width of the image. However, if all three sources are set, the width needs to be set by the user
(using e.g. :cpp:expr:`lv_obj_set_width`) and the center image will be tiled to fill the given size.
The possible states are:
- :cpp:enumerator:`LV_IMAGEBUTTON_STATE_RELEASED`
- :cpp:enumerator:`LV_IMAGEBUTTON_STATE_PRESSED`
- :cpp:enumerator:`LV_IMAGEBUTTON_STATE_DISABLED`
- :cpp:enumerator:`LV_IMAGEBUTTON_STATE_CHECKED_RELEASED`
- :cpp:enumerator:`LV_IMAGEBUTTON_STATE_CHECKED_PRESSED`
- :cpp:enumerator:`LV_IMAGEBUTTON_STATE_CHECKED_DISABLED`
If you set sources only in :cpp:enumerator:`LV_IMAGEBUTTON_STATE_RELEASED`, these sources
will be used in other states as well. If you set e.g. :cpp:enumerator:`LV_IMAGEBUTTON_STATE_PRESSED`
they will be used in pressed state instead of the released images.
States
------
Instead of the regular :cpp:func:`lv_obj_add_state` and :cpp:func:`lv_obj_remove_state` functions,
the :cpp:expr:`lv_imagebutton_set_state(imagebutton, LV_IMAGEBUTTON_STATE_...)` function should be
used to manually set a state.
.. _lv_imagebutton_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the button is toggled.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_imagebutton_keys:
Keys
****
- ``LV_KEY_RIGHT/UP`` Go to toggled state if :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE`
is enabled.
- ``LV_KEY_LEFT/DOWN`` Go to non-toggled state if
:cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` is enabled.
- :cpp:enumerator:`LV_KEY_ENTER` Clicks the button
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_imagebutton_example:
Example
*******
.. include:: ../../examples/widgets/imagebutton/index.rst
.. _lv_imagebutton_api:
API
***

42
docs/details/widgets/index.rst Normal file
View File

@@ -0,0 +1,42 @@
.. _widgets:
=======
Widgets
=======
.. toctree::
:maxdepth: 1
animimg
arc
bar
button
buttonmatrix
calendar
canvas
chart
checkbox
dropdown
image
imagebutton
keyboard
label
led
line
list
lottie
menu
msgbox
roller
scale
slider
span
spinbox
spinner
switch
table
tabview
textarea
tileview
win
new_widget

150
docs/details/widgets/keyboard.rst Normal file
View File

@@ -0,0 +1,150 @@
.. _lv_keyboard:
======================
Keyboard (lv_keyboard)
======================
Overview
********
The Keyboard Widget is a special :ref:`Button matrix <lv_buttonmatrix>`
with predefined keymaps and other features to realize a virtual keyboard
to write texts into a :ref:`Text area <lv_textarea>`.
.. _lv_keyboard_parts_and_styles:
Parts and Styles
****************
Similarly to Button matrices Keyboards consist of 2 part:
- :cpp:enumerator:`LV_PART_MAIN` The main part. Uses all the typical background properties
- :cpp:enumerator:`LV_PART_ITEMS` The buttons. Also uses all typical background properties as well as the *text* properties.
.. _lv_keyboard_usage:
Usage
*****
Modes
-----
The Keyboards have the following modes:
- :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_LOWER` Display lower case letters
- :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_UPPER` Display upper case letters
- :cpp:enumerator:`LV_KEYBOARD_MODE_SPECIAL` Display special characters
- :cpp:enumerator:`LV_KEYBOARD_MODE_NUMBER` Display numbers, +/- sign, and decimal dot
- :cpp:enumerator:`LV_KEYBOARD_MODE_USER_1` through :cpp:enumerator:`LV_KEYBOARD_MODE_USER_4` User-defined modes.
The ``TEXT`` modes' layout contains buttons to change mode.
To set the mode manually, use :cpp:expr:`lv_keyboard_set_mode(kb, mode)`. The
default mode is :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_UPPER`.
Assign Text area
----------------
You can assign a :ref:`Text area <lv_textarea>` to the Keyboard to
automatically put the clicked characters there. To assign the text area,
use :cpp:expr:`lv_keyboard_set_textarea(kb, ta)`.
Key Popovers
------------
To enable key popovers on press, like on common Android and iOS
keyboards, use :cpp:expr:`lv_keyboard_set_popovers(kb, true)`. The default
control maps are preconfigured to only show the popovers on keys that
produce a symbol and not on e.g. space. If you use a custom keymap, set
the :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_POPOVER` flag for all keys that you want to
show a popover.
Note that popovers for keys in the top row will draw outside the widget
boundaries. To account for this, reserve extra free space on top of the
keyboard or ensure that the keyboard is added *after* any widgets
adjacent to its top boundary so that the popovers can draw over those.
The popovers currently are merely a visual effect and don't allow
selecting additional characters such as accents yet.
New Keymap
----------
You can specify a new map (layout) for the keyboard with
:cpp:expr:`lv_keyboard_set_map(kb, LV_KEYBOARD_MODE_..., kb_map, kb_ctrl)`. See
the :ref:`Button matrix <lv_buttonmatrix>` for more information about
creating new maps and ctrls.
Keep in mind that using following keywords will have the same effect as
with the original map:
- :c:macro:`LV_SYMBOL_OK` Send :cpp:enumerator:`LV_EVENT_READY` to the assigned Text area.
- :c:macro:`LV_SYMBOL_CLOSE` or :c:macro:`LV_SYMBOL_KEYBOARD` Send :cpp:enumerator:`LV_EVENT_CANCEL` to the assigned Text area.
- :c:macro:`LV_SYMBOL_BACKSPACE` Delete on the left.
- :c:macro:`LV_SYMBOL_LEFT` Move the cursor left.
- :c:macro:`LV_SYMBOL_RIGHT` Move the cursor right.
- :c:macro:`LV_SYMBOL_NEW_LINE` New line.
- ``"ABC"`` Load the uppercase map.
- ``"abc"`` Load the lower case map.
- ``"1#"`` Load the lower case map.
.. _lv_keyboard_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the button is pressed/released
or repeated after long press. The event data is set to the ID of the
pressed/released button.
- :cpp:enumerator:`LV_EVENT_READY`: The *Ok* button is clicked.
- :cpp:enumerator:`LV_EVENT_CANCEL`: The *Close* button is clicked.
The keyboard has a **default event handler** callback called
:cpp:func:`lv_keyboard_def_event_cb`, which handles the button pressing, map
changing, the assigned text area, etc. You can remove it and replace it
with a custom event handler if you wish.
.. note::
In 8.0 and newer, adding an event handler to the keyboard does not remove the
default event handler. This behavior differs from v7, where adding an event
handler would always replace the previous one.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_keyboard_keys:
Keys
****
- ``LV_KEY_RIGHT/UP/LEFT/RIGHT`` To navigate among the buttons and
select one.
- :cpp:enumerator:`LV_KEY_ENTER` To press/release the selected button.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_keyboard_example:
Example
*******
.. include:: ../../examples/widgets/keyboard/index.rst
.. _lv_keyboard_api:
API
***

212
docs/details/widgets/label.rst Normal file
View File

@@ -0,0 +1,212 @@
.. _lv_label:
================
Label (lv_label)
================
Overview
********
A label is the basic Widget type that is used to display text.
.. _lv_label_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` Uses all the typical background properties and the
text properties. The padding values can be used to add space between
the text and the background.
- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is
larger than the widget's size.
- :cpp:enumerator:`LV_PART_SELECTED` Tells the style of the
:ref:`selected text <lv_label_text_selection>`. Only ``text_color`` and ``bg_color`` style
properties can be used.
.. _lv_label_usage:
Usage
*****
Set text
--------
You can set the text on a label at runtime with
:cpp:expr:`lv_label_set_text(label, "New text")`. This will allocate a buffer
dynamically, and the provided string will be copied into that buffer.
Therefore, you don't need to keep the text you pass to
:cpp:func:`lv_label_set_text` in scope after that function returns.
With :cpp:expr:`lv_label_set_text_fmt(label, "Value: %d", 15)` printf formatting
can be used to set the text.
Labels are able to show text from a static character buffer as well. To do so, use
:cpp:expr:`lv_label_set_text_static(label, "Text")`. In this case, the text is not
stored in dynamic memory and the given buffer is used directly instead. This means
that the character buffer *must not* be a local variable that goes out of scope when
the function exits.
``const`` strings are safe to use with :cpp:func:`lv_label_set_text_static` since
they are stored in ROM memory, which is always accessible.
.. danger::
Do not use ``const`` strings with :cpp:func:`lv_label_set_text_static` when the
label is being used in :cpp:enumerator:`LV_LABEL_LONG_DOT` mode since the label
will attempt to do an in-place edit of the string. This will cause an MCU
exception by attempting to modify program memory (ROM).
.. caution::
If your label is updated with new strings rapidly (e.g. > 30X / second, such as
RPM in a dashboard), and the length of those strings changes frequently, it is
advisable to:
- allocate a static string buffer large enough contain the largest possible string,
- update that buffer with the new strings only when they will make a visible
difference for the end user, and
- update the label with :cpp:expr:`lv_label_set_text_static(label, buffer)` using that buffer.
Reason: if you use :cpp:expr:`lv_label_set_text(label, new_text)`, a memory
realloc() will be forced every time the length of the string changes. That
MCU overhead can be avoided by doing the above.
.. _lv_label_newline:
Newline
-------
Newline characters are handled automatically by the label Widget. You
can use ``\n`` to make a line break. For example:
``"line1\nline2\n\nline4"``
.. _lv_label_long_modes:
Long modes
----------
By default, the width and height of the label is set to
:c:macro:`LV_SIZE_CONTENT`. Therefore, the size of the label is automatically
expanded to the text size. Otherwise, if the width or height are
explicitly set (using e.g.\ :cpp:func:`lv_obj_set_width` or a layout), the lines
wider than the label's width can be manipulated according to several
long mode policies. Similarly, the policies can be applied if the height
of the text is greater than the height of the label.
- :cpp:enumerator:`LV_LABEL_LONG_WRAP` Wrap lines that are too long. If the height is :c:macro:`LV_SIZE_CONTENT` the label's
height will be expanded, otherwise the text will be clipped. (Default)
- :cpp:enumerator:`LV_LABEL_LONG_DOT` Replaces the last 3 characters from bottom right corner of the label with dots (``.``)
- :cpp:enumerator:`LV_LABEL_LONG_SCROLL` If the text is wider than the label scroll it horizontally back and forth. If it's
higher, scroll vertically. Only one direction is scrolled and horizontal scrolling has higher precedence.
- :cpp:enumerator:`LV_LABEL_LONG_SCROLL_CIRCULAR` If the text is wider than the label scroll it horizontally continuously. If it's
higher, scroll vertically. Only one direction is scrolled and horizontal scrolling has higher precedence.
- :cpp:enumerator:`LV_LABEL_LONG_CLIP` Simply clip the parts of the text outside the label.
You can specify the long mode with :cpp:expr:`lv_label_set_long_mode(label, LV_LABEL_LONG_...)`
Note that :cpp:enumerator:`LV_LABEL_LONG_DOT` manipulates the text buffer in-place in
order to add/remove the dots. When :cpp:func:`lv_label_set_text` or
:cpp:func:`lv_label_set_array_text` are used, a separate buffer is allocated and
this implementation detail is unnoticed. This is not the case with
:cpp:func:`lv_label_set_text_static`. The buffer you pass to
:cpp:func:`lv_label_set_text_static` must be writable if you plan to use
:cpp:enumerator:`LV_LABEL_LONG_DOT`.
.. _lv_label_text_selection:
Text selection
--------------
If enabled by :c:macro:`LV_LABEL_TEXT_SELECTION` part of the text can be
selected. It's similar to when you use your mouse on a PC to select a
text. The whole mechanism (click and select the text as you drag your
finger/mouse) is implemented in :ref:`Text area <lv_textarea>` and
the Label widget only allows manual text selection with
:cpp:expr:`lv_label_get_text_selection_start(label, start_char_index)` and
:cpp:expr:`lv_label_get_text_selection_start(label, end_char_index)`.
.. _lv_label_text_alignment:
Text alignment
--------------
To horizontally align the lines of a label the `text_align` style property can be used with
:cpp:func:`lv_obj_set_style_text_align` or :cpp:func:`lv_style_set_text_align`
Note that it has a visible effect only if
- the label widget's width is larger than the width of the longest line of the text
- the text has multiple lines with non equal line length
.. _lv_label_very_long_texts:
Very long texts
---------------
LVGL can efficiently handle very long (e.g. > 40k characters) labels by
saving some extra data (~12 bytes) to speed up drawing. To enable this
feature, set ``LV_LABEL_LONG_TXT_HINT 1`` in ``lv_conf.h``.
.. _lv_label_custom_scrolling_animations:
Custom scrolling animations
---------------------------
Some aspects of the scrolling animations in long modes
:cpp:enumerator:`LV_LABEL_LONG_SCROLL` and :cpp:enumerator:`LV_LABEL_LONG_SCROLL_CIRCULAR` can be
customized by setting the animation property of a style, using
:cpp:func:`lv_style_set_anim`.
It will be treated as a template which will be used to create the scroll animations.
.. _lv_label_symbols:
Symbols
-------
The labels can display symbols alongside letters (or on their own). Read
the :ref:`font` section to learn more about the symbols.
.. _lv_label_events:
Events
******
No special events are sent by Label Widgets. By default, Label Widgets are created
without the LV_OBJ_FLAG_CLICKABLE flag, but you can add it to make a Label Widget
emit LV_EVENT_CLICKED events if desired.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_label_keys:
Keys
****
No *Keys* are processed by Label Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_label_example:
Example
*******
.. include:: ../../examples/widgets/label/index.rst
.. _lv_label_api:
API
***

87
docs/details/widgets/led.rst Normal file
View File

@@ -0,0 +1,87 @@
.. _lv_led:
============
LED (lv_led)
============
Overview
********
The LEDs are rectangle-like (or circle) Widget whose brightness can be
adjusted. With lower brightness the colors of the LED become darker.
.. _lv_led_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_LED_PART_MAIN` uses all the typical background style properties.
.. _lv_led_usage:
Usage
*****
Color
-----
You can set the color of the LED with
:cpp:expr:`lv_led_set_color(led, lv_color_hex(0xff0080))`. This will be used as
background color, border color, and shadow color.
Brightness
----------
You can set their brightness with :cpp:expr:`lv_led_set_bright(led, bright)`.
The brightness should be between 0 (darkest) and 255 (lightest).
Toggle
------
Use :cpp:expr:`lv_led_on(led)` and :cpp:expr:`lv_led_off(led)` to set the brightness to
a predefined ON or OFF value. The :cpp:expr:`lv_led_toggle(led)` toggles between
the ON and OFF state.
.. _lv_led_events:
Events
******
No special events are sent by LED Widgets.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_led_keys:
Keys
****
No *Keys* are processed by LED Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_led_example:
Example
*******
.. include:: ../../examples/widgets/led/index.rst
.. _lv_led_api:
API
***

95
docs/details/widgets/line.rst Normal file
View File

@@ -0,0 +1,95 @@
.. _lv_line:
==============
Line (lv_line)
==============
Overview
********
The Line Widget is capable of drawing straight lines between a set of
points.
.. _lv_line_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` uses all the typical background properties and line style properties.
.. _lv_line_usage:
Usage
*****
Set points
----------
The points have to be stored in an :cpp:struct:`lv_point_precise_t` array and passed to
the Widget by the :cpp:expr:`lv_line_set_points(lines, point_array, point_cnt)`
function.
Their coordinates can either be specified as raw pixel coordinates
(e.g. ``{5, 10}``), or as a percentage of the line's bounding box using
:cpp:expr:`lv_pct(x)`. In the latter case, the line's width/height may need to
be set explicitly using ``lv_obj_set_width/height``, as percentage
values do not automatically expand the bounding box.
Auto-size
---------
By default, the Line's width and height are set to :c:macro:`LV_SIZE_CONTENT`.
This means it will automatically set its size to fit all the points. If
the size is set explicitly, parts on the line may not be visible.
Invert y
--------
By default, the *y == 0* point is in the top of the Widget. It might be
counter-intuitive in some cases so the y coordinates can be inverted
with :cpp:expr:`lv_line_set_y_invert(line, true)`. In this case, *y == 0* will
be the bottom of the Widget. *y invert* is disabled by default.
.. _lv_line_events:
Events
******
Only the :ref:`Generic events <events>` are sent by Line Widgets.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_line_keys:
Keys
****
No *Keys* are processed by Line Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_line_example:
Example
*******
.. include:: ../../examples/widgets/line/index.rst
.. _lv_line_api:
API
***

88
docs/details/widgets/list.rst Normal file
View File

@@ -0,0 +1,88 @@
.. _lv_list:
==============
List (lv_list)
==============
Overview
********
The List is basically a rectangle with vertical layout to which Buttons
and Texts can be added
.. _lv_list_parts_and_styles:
Parts and Styles
****************
**Background**
- :cpp:enumerator:`LV_PART_MAIN` The main part of the list that uses all the typical background properties
- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar. See the :ref:`base_widget`
documentation for details.
**Buttons and Texts** See the :ref:`Button <lv_button>`\ 's and :ref:`Label <lv_label>`\ 's documentation.
.. _lv_list_usage:
Usage
*****
Buttons
-------
:cpp:expr:`lv_list_add_button(list, icon, text)` adds a full-width button with an icon
- that can be an image or symbol
- and a text.
The text starts to scroll horizontally if it's too long.
Texts
-----
:cpp:expr:`lv_list_add_text(list, text)` adds a text.
.. _lv_list_events:
Events
******
No special events are sent by List Widgets, but events are sent by Buttons as usual.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_list_keys:
Keys
****
No *Keys* are processed by List Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_list_example:
Example
*******
.. include:: ../../examples/widgets/list/index.rst
.. _lv_list_api:
API
***

128
docs/details/widgets/lottie.rst Normal file
View File

@@ -0,0 +1,128 @@
.. _lv_lottie:
==================
Lottie (lv_lottie)
==================
Overview
********
The Lottie widget is capable of parsing, rasterizing, and playing `Lottie animations <https://lottiefiles.com>`__.
The Lottie animations are vector based animation. Think of it as the modern combination of SVG and GIF.
The animations can be downloaded from various sources, such as `https://lottiefiles.com/ <https://lottiefiles.com/>`__
or you can create your own animations using for example Adobe After Effects.
The Lottie widget is based on :ref:`lv_canvas` because in order to render the animation
the user needs to provide a buffer where the current frame is stored.
.. _lv_lottie_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` The background of the Lottie animation. The typical background style properties apply but usually it is left transparent.
.. _lv_lottie_usage:
Usage
*****
Dependencies
------------
The Lottie widget uses the `ThorVG <https://github.com/thorvg/thorvg>`__ library which is `integrated into LVGL <https://github.com/lvgl/lvgl/tree/master/src/libs/thorvg>`__.
In order to use Lottie animations :c:macro:`LV_USE_THORVG_INTERNAL` (to use the built-in ThorVG) or
:c:macro:`LV_USE_THORVG_EXTERNAL` (to link it externally) needs to enabled. For vector graphics in general
:c:macro:`LV_USE_VECTOR_GRAPHIC` also needs to be enabled.
As ThorVG is written in C++, when using :c:macro:`LV_USE_THORVG_INTERNAL` be sure that you
can compile the cpp files.
Set a buffer
------------
In order to render the animation a buffer needs to assign to the Lottie widget.
The animations are rendered in ARGB8888 format, therefor the buffer's size should be equal to
``target_width x target_height x 4`` bytes.
To keep the buffer size and the animation size consistent,
the size of the widget (i.e. the size of the animation) is set to the dimensions of the buffer internally.
The buffer can be set with either :cpp:expr:`lv_lottie_set_buffer(lottie, w, h, buf)`
or :cpp:expr:`lv_lottie_set_draw_buf(lottie, draw_buf)`.
When a draw buffer is used, it must be already initialized by the user with :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888` color format.
Set a source
------------
``lv_example_lottie_approve.c`` contains an example animation. Instead storing the JSON string, a hex array is stored for the
following reasons:
- avoid escaping ``"`` character in the JSON file
- some compilers don't support very long strings
``lvgl/scripts/filetohex.py`` can be used to convert a Lottie file a hex
array. E.g.:
.. code-block:: shell
./filetohex.py path/to/lottie.json > out.txt
To create an animation from data use
:cpp:expr:`lv_lottie_set_src_data(lottie, data, sizeof(data))`
Lottie animations can be opened from JSON files by using :cpp:expr:`lv_lottie_set_src_file(lottie, "path/to/file.json")`.
Note that the Lottie loader doesn't support LVGL's File System interface but a "normal path" should be used without a driver letter.
Get the animation
-----------------
``lv_anim_t * a = lv_lottie_get_anim(lottie)`` return the LVGL animation which controls the
Lottie animation. By default it is running infinitely at 60FPS however the LVGL animation
can be freely adjusted.
.. _lv_lottie_events:
Events
******
No *Keys* are processed by Lottie Widgets.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_lottie_keys:
Keys
****
No keys are processed by Lottie Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_lottie_example:
Example
*******
.. include:: ../../examples/widgets/lottie/index.rst
.. _lv_lottie_api:
API
***

153
docs/details/widgets/menu.rst Normal file
View File

@@ -0,0 +1,153 @@
.. _lv_menu:
==============
Menu (lv_menu)
==============
Overview
********
The menu widget can be used to easily create multi-level menus. It
handles the traversal between pages automatically.
.. _lv_menu_parts_and_styles:
Parts and Styles
****************
The menu widget is built from the following Widgets:
- Main container: :cpp:type:`lv_menu_main_cont`
- Main header: :cpp:type:`lv_menu_main_header_cont`
- Back button: :ref:`lv_button`
- Back button icon: :ref:`lv_image`
- Main page: :cpp:type:`lv_menu_page`
- Sidebar container: :cpp:type:`lv_menu_sidebar_cont`
- Sidebar header: :cpp:type:`lv_menu_sidebar_header_cont`
- Back button: :ref:`lv_button`
- Back button icon: :ref:`lv_image`
- Sidebar page: :cpp:type:`lv_menu_page`
.. _lv_menu_usage:
Usage
*****
Create a menu
-------------
:cpp:expr:`lv_menu_create(parent)` creates a new empty menu.
Header mode
-----------
The following header modes exist:
- :cpp:enumerator:`LV_MENU_HEADER_TOP_FIXED` Header is positioned at the top.
- :cpp:enumerator:`LV_MENU_HEADER_TOP_UNFIXED` Header is positioned at the top and can be scrolled out of view.
- :cpp:enumerator:`LV_MENU_HEADER_BOTTOM_FIXED` Header is positioned at the bottom.
You can set header modes with :cpp:expr:`lv_menu_set_mode_header(menu, LV_MENU_HEADER...)`.
Root back button mode
---------------------
The following root back button modes exist:
- :cpp:enumerator:`LV_MENU_ROOT_BACK_BTN_DISABLED`
- :cpp:enumerator:`LV_MENU_ROOT_BACK_BTN_ENABLED`
You can set root back button modes with
:cpp:expr:`lv_menu_set_mode_root_back_button(menu, LV_MENU_ROOT_BACK_BTN...)`.
Create a menu page
------------------
:cpp:expr:`lv_menu_page_create(menu, title)` creates a new empty menu page. You
can add any widgets to the page.
Set a menu page in the main area
--------------------------------
Once a menu page has been created, you can set it to the main area with
:cpp:expr:`lv_menu_set_page(menu, page)`. ``NULL`` to clear main and clear menu
history.
Set a menu page in the sidebar
------------------------------
Once a menu page has been created, you can set it to the sidebar with
:cpp:expr:`lv_menu_set_sidebar_page(menu, page)`. ``NULL`` to clear sidebar.
Linking between menu pages
--------------------------
For instance, you have created a button obj in the main page. When you
click the button Widget, you want it to open up a new page, use
:cpp:expr:`lv_menu_set_load_page_event(menu, btn, new page)`.
Create a menu container, section, separator
-------------------------------------------
The following objects can be created so that it is easier to style the
menu:
- :cpp:expr:`lv_menu_cont_create(parent page)` creates a new empty container.
- :cpp:expr:`lv_menu_section_create(parent page)` creates a new empty section.
- :cpp:expr:`lv_menu_separator_create(parent page)` creates a separator.
.. _lv_menu_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a page is shown.
- :cpp:expr:`lv_menu_get_cur_main_page(menu)` returns a pointer to menu page
that is currently displayed in main.
- :cpp:expr:`lv_menu_get_cur_sidebar_page(menu)` returns a pointer to menu
page that is currently displayed in sidebar.
- :cpp:enumerator:`LV_EVENT_CLICKED` Sent when a back button in a header from either
main or sidebar is clicked. :cpp:enumerator:`LV_OBJ_FLAG_EVENT_BUBBLE` is enabled
on the buttons so you can add events to the menu itself.
- :cpp:expr:`lv_menu_back_button_is_root(menu, button)` to check if button is root
back button
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_menu_keys:
Keys
****
No *Keys* are processed by Menu Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_menu_example:
Example
*******
.. include:: ../../examples/widgets/menu/index.rst
.. _lv_menu_api:
API
***

123
docs/details/widgets/msgbox.rst Normal file
View File

@@ -0,0 +1,123 @@
.. _lv_msgbox:
=======================
Message Box (lv_msgbox)
=======================
Overview
********
Message boxes act as pop-ups. They are built from a content area
with a helper to add text, an optional header (which can have
a title, a close button, and other buttons), and an optional footer
with buttons.
The text will be broken into multiple lines and the height
will be set automatically. If the height
is set manually, the content will become scrollable.
The message box can be modal (blocking clicks on the rest of the screen)
or not modal.
.. _lv_msgbox_parts_and_styles:
Parts and Styles
****************
The message box is built from other widgets, so you can check these
widgets' documentation for details.
- Content, header, and footer: :ref:`base_widget`
- Buttons: :ref:`lv_button`
- Title and content text: :ref:`lv_label`
.. _lv_msgbox_usage:
Usage
*****
Create a message box
--------------------
:cpp:expr:`lv_msgbox_create(parent)` creates a message box.
If ``parent`` is ``NULL`` the message box will be modal.
E.g. ``const char * btn_txts[] = {"Ok", "Cancel", NULL}``.
Get the parts
-------------
The building blocks of the message box can be obtained using the
following functions:
.. code-block:: c
lv_obj_t * lv_msgbox_get_content(lv_obj_t * widget);
lv_obj_t * lv_msgbox_get_title(lv_obj_t * widget);
lv_obj_t * lv_msgbox_get_header(lv_obj_t * widget);
lv_obj_t * lv_msgbox_get_footer(lv_obj_t * widget);
Functions that add something to the message box return the newly added Widget:
.. code:: c
lv_obj_t * lv_msgbox_add_text(lv_obj_t * widget, const char * text);
lv_obj_t * lv_msgbox_add_title(lv_obj_t * widget, const char * title);
lv_obj_t * lv_msgbox_add_close_button(lv_obj_t * widget);
lv_obj_t * lv_msgbox_add_header_button(lv_obj_t * widget, const void * icon);
lv_obj_t * lv_msgbox_add_footer_button(lv_obj_t * widget, const char * text);
Close the message box
---------------------
:cpp:expr:`lv_msgbox_close(msgbox)` closes (deletes) the message box.
:cpp:expr:`lv_msgbox_close_async(msgbox)` closes (deletes) the message box
asynchronously. This is useful if you want the message box to close the on
the next call to ``lv_timer_handler`` instead of immediately.
.. _lv_msgbox_events:
Events
******
No special events are sent by this widget.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_msgbox_keys:
Keys
****
No *Keys* are processed by Msgbox Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_msgbox_example:
Example
*******
.. include:: ../../examples/widgets/msgbox/index.rst
.. _lv_msgbox_api:
API
***

5
docs/details/widgets/new_widget.rst Normal file
View File

@@ -0,0 +1,5 @@
.. _new_widget:
==========
New Widget
==========

106
docs/details/widgets/roller.rst Normal file
View File

@@ -0,0 +1,106 @@
.. _lv_roller:
==================
Roller (lv_roller)
==================
Overview
********
Roller allows you to simply select one option from a list by scrolling.
.. _lv_roller_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` The background of the roller uses all the typical
background properties and text style properties.
``style_text_line_space`` adjusts the space between the options. When
the Roller is scrolled and doesn't stop exactly on an option it will
scroll to the nearest valid option automatically in ``anim_time``
milliseconds as specified in the style.
- :cpp:enumerator:`LV_PART_SELECTED` The selected option in the middle. Besides the
typical background properties it uses the text style properties to
change the appearance of the text in the selected area.
.. _lv_roller_usage:
Usage
*****
Set options
-----------
Options are passed to the Roller as a string with
:cpp:expr:`lv_roller_set_options(roller, options, LV_ROLLER_MODE_NORMAL)`.
The options should be separated by ``\n``. For example:
``"First\nSecond\nThird"``.
:cpp:enumerator:`LV_ROLLER_MODE_INFINITE` makes the roller circular.
You can select an option manually with
:cpp:expr:`lv_roller_set_selected(roller, id, LV_ANIM_ON)`,
where *id* is the index of an option.
Get selected option
-------------------
To get the *index* of the currently selected option use :cpp:expr:`lv_roller_get_selected(roller)`.
:cpp:expr:`lv_roller_get_selected_str(roller, buf, buf_size)` will copy the name of the selected option to ``buf``.
Visible rows
------------
The number of visible rows can be adjusted with :cpp:expr:`lv_roller_set_visible_row_count(roller, num)`.
This function calculates the height with the current style. If the font,
line space, border width, etc. of the roller changes this function needs
to be called again.
.. _lv_roller_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new option is selected.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_roller_keys:
Keys
****
- ``LV_KEY_RIGHT/DOWN`` Select the next option
- ``LV_KEY_LEFT/UP`` Select the previous option
- :cpp:enumerator:`LY_KEY_ENTER` Apply the selected option (Send :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` event)
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_roller_example:
Example
*******
.. include:: ../../examples/widgets/roller/index.rst
.. _lv_roller_api:
API
***

156
docs/details/widgets/scale.rst Normal file
View File

@@ -0,0 +1,156 @@
.. _lv_scale:
================
Scale (lv_scale)
================
Overview
********
Scale allows you to have a linear scale with ranges and sections with custom styling.
.. _lv_scale_parts_and_styles:
Parts and Styles
****************
The scale widget is divided in the following three parts:
- :cpp:enumerator:`LV_PART_MAIN` Main line. See blue line in the example image.
- :cpp:enumerator:`LV_PART_ITEMS` Minor ticks. See red minor ticks in the example image.
- :cpp:enumerator:`LV_PART_INDICATOR` Major ticks and its labels (if enabled).
See pink labels and green major ticks in the example image.
.. image:: /misc/scale.png
.. _lv_scale_usage:
Usage
*****
Set ranges
----------
The minor and major range (values of each tick) are configured with :cpp:expr:`lv_scale_set_range(scale, minor_range, major_range)`.
Tick drawing order
------------------
You can set the drawing of the ticks on top of the main line with :cpp:expr:`lv_scale_set_draw_ticks_on_top(scale, true)`. The default
drawing order is below the main line.
This is a scale with the ticks being drawn below of the main line (default):
.. image:: /misc/scale_ticks_below.png
This is an scale with the ticks being drawn at the top of the main line:
.. image:: /misc/scale_ticks_on_top.png
Configure ticks
---------------
Set the number of total ticks with :cpp:expr:`lv_scale_set_total_tick_count(scale, total_tick_count)`
and then configure the major tick being every Nth ticks with :cpp:expr:`lv_scale_set_major_tick_every(scale, nth_tick)`.
Labels on major ticks can be configured with :cpp:expr:`lv_scale_set_label_show(scale, show_label)`,
set `show_label` to true if labels should be drawn, :cpp:expr:`false` to hide them.
If instead of a numerical value in the major ticks a text is required they can be set
with :cpp:expr:`lv_scale_set_text_src(scale, custom_labels)` using ``NULL`` as the last element,
i.e. ``static char * custom_labels[3] = {"One", "Two", NULL}``.
It's possible to have the labels automatically rotated to match the ticks (only for RADIAL scales) using
:cpp:expr:`lv_obj_set_style_transform_rotation(scale, LV_SCALE_LABEL_ROTATE_MATCH_TICKS, LV_PART_INDICATOR);`
Or rotated a fixed amount (on any scale type) - here for 20 degrees:
:cpp:expr:`lv_obj_set_style_transform_rotation(scale, 20, LV_PART_INDICATOR);`
Or both at the same time
:cpp:expr:`lv_obj_set_style_transform_rotation(scale, LV_SCALE_LABEL_ROTATE_MATCH_TICKS + 200, LV_PART_INDICATOR);`
Some labels of the scale might be drawn upside down (to match the tick) if the scale includes a certain angle range.
If you don't want this, to automatically rotate the labels to keep them upright, an additional flag can be used.
Labels that would be upside down are then rotated 180
:cpp:expr:`lv_obj_set_style_transform_rotation(scale, LV_SCALE_LABEL_ROTATE_MATCH_TICKS | LV_SCALE_LABEL_ROTATE_KEEP_UPRIGHT, LV_PART_INDICATOR);`
Labels can also be moved a fixed distance in X and Y using e.g.
:cpp:expr:`lv_obj_set_style_translate_x(scale, 10, LV_PART_INDICATOR);`
.. note::
The major tick value is calculated with the :cpp:expr:`lv_map` API (when not
setting custom labels), this calculation takes into consideration the total
number of ticks and the scale range, so the label drawn can present rounding
errors when the calculated value is a float number.
The length of the ticks can be configured with the length style property on the :cpp:enumerator:`LV_PART_INDICATOR`
for major ticks and :cpp:enumerator:`LV_PART_ITEMS` for minor ticks, for example with local style:
:cpp:expr:`lv_obj_set_style_length(scale, 5, LV_PART_INDICATOR);` for major ticks
and :cpp:expr:`lv_obj_set_style_length(scale, 5, LV_PART_ITEMS);` for minor ticks. The ticks can be
padded in either direction (outwards or inwards) for RADIAL scales only with:
:cpp:expr:`lv_obj_set_style_radial_offset(scale, 5, LV_PART_INDICATOR);` for major ticks and
:cpp:expr:`lv_obj_set_style_radial_offset(scale, 5, LV_PART_ITEMS);` for minor .
Using length and radial offset together allows total control of the tick position.
i.e. :cpp:expr:`static char * custom_labels[3] = {"One", "Two", NULL}`.
It is also possible to offset the labels from the major ticks (either positive or negative) using
:cpp:expr:`lv_obj_set_style_pad_radial(scale, 5, LV_PART_INDICATOR);`
Sections
--------
A section is the space between a minor and a major range. They can be created with :cpp:expr:`lv_scale_add_section(scale)`
and it handles back an :cpp:type:`lv_scale_section_t` pointer.
The range of the section is configured with :cpp:expr:`lv_scale_section_set_range(section, minor_range, major_range)`.
The style of each of the three parts of the scale section can be set with
:cpp:expr:`lv_scale_section_set_style(section, PART, style_pointer)`, where `PART` can be
:cpp:enumerator:`LV_PART_MAIN`, :cpp:enumerator:`LV_PART_ITEMS` or :cpp:enumerator:`LV_PART_INDICATOR`,
:cpp:expr:`style_pointer` should point to a global or static :cpp:type:`lv_style_t` variable.
For labels the following properties can be configured:
:cpp:func:`lv_style_set_text_font`, :cpp:func:`lv_style_set_text_color`,
:cpp:func:`lv_style_set_text_letter_space`, :cpp:func:`lv_style_set_text_opa`.
For lines (main line, major and minor ticks) the following properties can be configured:
:cpp:func:`lv_style_set_line_color`, :cpp:func:`lv_style_set_line_width`.
.. _lv_scale_events:
Events
******
No events supported by this widget.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_scale_keys:
Keys
****
No *Keys* are processed by Scale Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_scale_example:
Example
*******
.. include:: ../../examples/widgets/scale/index.rst
.. _lv_scale_api:
API
***
:ref:`lv_scale`

121
docs/details/widgets/slider.rst Normal file
View File

@@ -0,0 +1,121 @@
.. _lv_slider:
==================
Slider (lv_slider)
==================
Overview
********
The Slider Widget looks like a :ref:`Bar <lv_bar>` supplemented with
a knob. The knob can be dragged to set a value. Just like Bar, Slider
can be vertical or horizontal.
.. _lv_slider_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` The background of the slider. Uses all the typical
background style properties. ``padding`` makes the indicator smaller
in the respective direction.
- :cpp:enumerator:`LV_PART_INDICATOR` The indicator that shows the current state of
the slider. Also uses all the typical background style properties.
- :cpp:enumerator:`LV_PART_KNOB` A rectangle (or circle) drawn at the current value.
Also uses all the typical background properties to describe the
knob(s). By default, the knob is square (with an optional corner
radius) with side length equal to the smaller side of the slider. The
knob can be made larger with the ``padding`` values. Padding values
can be asymmetric as well.
.. _lv_slider_usage:
Usage
*****
Value and range
---------------
To set an initial value use :cpp:expr:`lv_slider_set_value(slider, new_value, LV_ANIM_ON/OFF)`. The
animation time is set by the styles' ``anim_time`` property.
To specify the range (min, max values), :cpp:expr:`lv_slider_set_range(slider, min , max)` can be used.
The default range is 0..100, and the default drawing direction is from left to right in horizontal mode and
bottom to top in vertical mode. If the minimum value is greater than the maximum value, like
100..0, the drawing direction changes to the opposite direction.
Modes
-----
The slider can be one of the following modes:
- :cpp:enumerator:`LV_SLIDER_MODE_NORMAL` A normal slider as described above
- :cpp:enumerator:`LV_SLIDER_SYMMETRICAL` Draw the indicator form the zero value to
current value. Requires negative minimum range and positive maximum range.
- :cpp:enumerator:`LV_SLIDER_RANGE` Allows setting the start value as well by
:cpp:expr:`lv_bar_set_start_value(bar, new_value, LV_ANIM_ON/OFF)`. The start
value has to be always smaller than the end value.
The mode can be changed with :cpp:expr:`lv_slider_set_mode(slider, LV_SLIDER_MODE_...)`
Knob-only mode
--------------
Normally, the slider can be adjusted either by dragging the knob, or by
clicking on the slider bar. In the latter case the knob moves to the
point clicked and slider value changes accordingly. In some cases it is
desirable to set the slider to react on dragging the knob only. This
feature is enabled by adding the :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST`:
:cpp:expr:`lv_obj_add_flag(slider, LV_OBJ_FLAG_ADV_HITTEST)`.
The extended click area (set by :cpp:expr:`lv_obj_set_ext_click_area(slider, value)`) increases to knob's click area.
.. _lv_slider_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent while the slider is being dragged or
changed with keys. The event is sent continuously while the slider is
being dragged.
- :cpp:enumerator:`LV_EVENT_RELEASED` Sent when the slider has just been released.
.. admonition:: Further Reading
:ref:`Bar Events <lv_bar_events>`.
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_slider_keys:
Keys
****
- ``LV_KEY_UP/RIGHT`` Increment the slider's value by 1
- ``LV_KEY_DOWN/LEFT`` Decrement the slider's value by 1
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_slider_example:
Example
*******
.. include:: ../../examples/widgets/slider/index.rst
.. _lv_slider_api:
API
***

155
docs/details/widgets/span.rst Normal file
View File

@@ -0,0 +1,155 @@
.. _lv_span:
==============
Span (lv_span)
==============
Overview
********
A spangroup is the Widget that is used to display rich text. Different
from the label Widget, ``spangroup`` can render text styled with
different fonts, colors, and sizes into the spangroup Widget.
.. _lv_span_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` The spangroup has only one part.
.. _lv_span_usage:
Usage
*****
Set text and style
------------------
The spangroup Widget uses span to describe text and text style. so,
first we need to create ``span`` descriptor using ``lv_span_t * span = lv_spangroup_new_span(spangroup)``.
Then use :cpp:expr:`lv_span_set_text(span, "text")` to set text. The style of the span is
configured as with a normal style Widget by using its ``style`` member,
eg::cpp:expr:`lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_RED))`.
If spangroup Widget ``mode != LV_SPAN_MODE_FIXED`` you must call
:cpp:func:`lv_spangroup_refr_mode` after you have modified ``span``
style(eg:set text, changed the font size, del span).
Retrieving a span child
-----------------------
Spangroups store their children differently from normal Widgets, so
normal functions for getting children won't work.
:cpp:expr:`lv_spangroup_get_child(spangroup, id)` will return a pointer to the
child span at index ``id``. In addition, ``id`` can be negative to index
from the end of the spangroup where ``-1`` is the youngest child, ``-2``
is second youngest, etc.
E.g. ``lv_span_t* span = lv_spangroup_get_child(spangroup, 0)`` will
return the first child of the spangroup.
``lv_span_t* span = lv_spangroup_get_child(spangroup, -1)`` will return
the last (or most recent) child.
Child Count
-----------
Use the function :cpp:expr:`lv_spangroup_get_span_count(spangroup)` to get back
the number of spans the group is maintaining.
E.g. ``uint32_t size = lv_spangroup_get_span_count(spangroup)``
Text align
----------
Like label Widget, the spangroup can be set to one the following modes:
- :cpp:enumerator:`LV_TEXT_ALIGN_LEFT` Align to left.
- :cpp:enumerator:`LV_TEXT_ALIGN_CENTER` Align to center.
- :cpp:enumerator:`LV_TEXT_ALIGN_RIGHT` Align to right.
- :cpp:enumerator:`LV_TEXT_ALIGN_AUTO` Align auto.
Use function :cpp:expr:`lv_spangroup_set_align(spangroup, LV_TEXT_ALIGN_CENTER)`
to set text align.
Modes
-----
The spangroup can be set to one the following modes:
- :cpp:enumerator:`LV_SPAN_MODE_FIXED` Fixes the Widget size.
- :cpp:enumerator:`LV_SPAN_MODE_EXPAND` Expand the Widget size to the text size but stay on a single line.
- :cpp:enumerator:`LV_SPAN_MODE_BREAK` Keep width, break lines that are too long and auto expand height.
Use the function :cpp:expr:`lv_spangroup_set_mode(spangroup, LV_SPAN_MODE_BREAK)` to set
Widget mode.
Overflow
--------
The spangroup can be set to one the following modes:
- :cpp:enumerator:`LV_SPAN_OVERFLOW_CLIP` truncates the text at the limit of the area.
- :cpp:enumerator:`LV_SPAN_OVERFLOW_ELLIPSIS` will display an ellipsis (``...``) when text overflows the area.
Use function :cpp:expr:`lv_spangroup_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP)` to set Widget overflow mode.
First line indent
-----------------
Use function :cpp:expr:`lv_spangroup_set_indent(spangroup, 20)` to set the indent of the
first line. all modes support pixel units, in addition to :cpp:enumerator:`LV_SPAN_MODE_FIXED`
and :cpp:enumerator:`LV_SPAN_MODE_BREAK` mode supports percentage units
as well.
Lines
-----
Use function :cpp:expr:`lv_spangroup_set_max_lines(spangroup, 10)` to set the maximum number
of lines to be displayed in :cpp:enumerator::`LV_SPAN_MODE_BREAK` mode, negative values
indicate no limit.
.. _lv_span_events:
Events
******
No special events are sent by this widget.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_span_keys:
Keys
****
No *Keys* are processed by Span Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_span_example:
Example
*******
.. include:: ../../examples/widgets/span/index.rst
.. _lv_span_api:
API
***

104
docs/details/widgets/spinbox.rst Normal file
View File

@@ -0,0 +1,104 @@
.. _lv_spinbox:
====================
Spinbox (lv_spinbox)
====================
Overview
********
The Spinbox contains a number as text which can be increased or
decreased by *Keys* or API functions. Under the hood the Spinbox is a
modified :ref:`Text area <lv_textarea>`.
.. _lv_spinbox_parts_and_styles:
Parts and Styles
****************
The parts of the Spinbox are identical to the :ref:`Text area <lv_textarea>`.
Value, range and step
---------------------
- :cpp:expr:`lv_spinbox_set_value(spinbox, 1234)` sets a new value on the Spinbox.
- :cpp:expr:`lv_spinbox_increment(spinbox)` and :cpp:expr:`lv_spinbox_decrement(spinbox)`
increments/decrements the value of the Spinbox according to the currently selected digit.
- :cpp:expr:`lv_spinbox_set_range(spinbox, -1000, 2500)` sets a range. If the
value is changed by :cpp:func:`lv_spinbox_set_value`, by
*Keys*,\ ``lv_spinbox_increment/decrement`` this range will be respected.
- :cpp:expr:`lv_spinbox_set_step(spinbox, 100)` sets which digits to change on
increment/decrement. Only multiples of ten can be set, and not for example 3.
- :cpp:expr:`lv_spinbox_set_cursor_pos(spinbox, 1)` sets the cursor to a specific
digit to change on increment/decrement. For example position '0' sets the cursor to the least significant digit.
If an encoder is used as input device, the selected digit is shifted to
the right by default whenever the encoder button is clicked. To change this behaviour to shifting
to the left, the :cpp:expr:`lv_spinbox_set_digit_step_direction(spinbox, LV_DIR_LEFT)` can be used
Format
------
:cpp:expr:`lv_spinbox_set_digit_format(spinbox, digit_count, separator_position)`
sets the number format. ``digit_count`` is the number of digits
excluding the decimal separator and the sign. ``separator_position`` is
the number of digits before the decimal point. If 0, no decimal point is displayed.
Rollover
--------
:cpp:expr:`lv_spinbox_set_rollover(spinbox, true/false)` enables/disabled
rollover mode. If either the minimum or maximum value is reached with
rollover enabled, the value will change to the other limit. If rollover
is disabled the value will remain at the minimum or maximum value.
.. _lv_spinbox_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the value has changed.
.. admonition:: Further Reading
:ref:`Textarea Events <lv_textarea_events>`.
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_spinbox_keys:
Keys
****
- ``LV_KEY_LEFT/RIGHT`` With *Keypad* move the cursor left/right. With
*Encoder* decrement/increment the selected digit.
- ``LV_KEY_UP/DOWN`` With *Keypad* and *Encoder* increment/decrement
the value.
- :cpp:enumerator:`LV_KEY_ENTER` With *Encoder* got the net digit. Jump to the first
after the last.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_spinbox_example:
Example
*******
.. include:: ../../examples/widgets/spinbox/index.rst
.. _lv_spinbox_api:
API
***

77
docs/details/widgets/spinner.rst Normal file
View File

@@ -0,0 +1,77 @@
.. _lv_spinner:
====================
Spinner (lv_spinner)
====================
Overview
********
The Spinner Widget is a spinning arc over a ring.
.. _lv_spinner_parts_and_styles:
Parts and Styles
****************
The parts are identical to the parts of :ref:`lv_arc`.
.. _lv_spinner_usage:
Usage
*****
Create a spinner
----------------
To create a spinner use
:cpp:expr:`lv_spinner_create(parent)`.
Using :cpp:expr:`lv_spinner_set_anim_params(spinner, spin_duration, angle)` the duration
of one revolution and the length of he arc can be customized.
.. _lv_spinner_events:
Events
******
No special events are sent to Spinner Widgets.
.. admonition:: Further Reading
:ref:`Arc Events <lv_arc_events>`
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_spinner_keys:
Keys
****
No *Keys* are processed by Spinner Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_spinner_example:
Example
*******
.. include:: ../../examples/widgets/spinner/index.rst
.. _lv_spinner_api:
API
***

97
docs/details/widgets/switch.rst Normal file
View File

@@ -0,0 +1,97 @@
.. _lv_switch:
==================
Switch (lv_switch)
==================
Overview
********
The Switch looks like a little slider and can be used to turn something
on and off.
Vertical Switch can be created if the width of the Widget is smaller than its height.
.. _lv_switch_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` The background of the switch uses all the typical
background style properties. ``padding`` makes the indicator smaller
in the respective direction.
- :cpp:enumerator:`LV_PART_INDICATOR` The indicator that shows the current state of
the switch. Also uses all the typical background style properties.
- :cpp:enumerator:`LV_PART_KNOB` A rectangle (or circle) drawn at left or right side
of the indicator. Also uses all the typical background properties to
describe the knob(s). By default, the knob is square (with an
optional corner radius) with side length equal to the smaller side of
the slider. The knob can be made larger with the ``padding`` values.
Padding values can be asymmetric as well.
.. _lv_switch_usage:
Usage
*****
Change state
------------
The switch uses the standard :cpp:enumerator:`LV_STATE_CHECKED` state.
To get the current state of the switch (with ``true`` being on), use
:cpp:expr:`lv_obj_has_state(widget, LV_STATE_CHECKED)`.
Call :cpp:expr:`lv_obj_add_state(widget, LV_STATE_CHECKED)` to turn it on, or
:cpp:expr:`lv_obj_remove_state(widget, LV_STATE_CHECKED)` to turn it off.
Change orientation
------------------
:cpp:expr:`lv_switch_set_orientation(widget, LV_SWITCH_ORIENTATION_VERTICAL)` change orientation, default orientation is :cpp:enumerator:`LV_SWITCH_ORIENTATION_AUTO`, adaptive based on the width and height of the Widget.
.. _lv_switch_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the switch changes state.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_switch_keys:
Keys
****
- ``LV_KEY_UP/RIGHT`` Turns on the slider
- ``LV_KEY_DOWN/LEFT`` Turns off the slider
- :cpp:enumerator:`LV_KEY_ENTER` Toggles the switch
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_switch_example:
Example
*******
.. include:: ../../examples/widgets/switch/index.rst
.. _lv_switch_api:
API
***

140
docs/details/widgets/table.rst Normal file
View File

@@ -0,0 +1,140 @@
.. _lv_table:
================
Table (lv_table)
================
Overview
********
Tables, as usual, are built from rows, columns, and cells containing
texts.
The Table Widget is very lightweight because only the texts are stored.
No real Widgets are created for cells but they are just drawn on the
fly.
The Table is added to the default group (if it is set). Besides the
Table is an editable Widget to allow selecting a cell with encoder
navigation as well.
.. _lv_table_parts_and_styles:
Parts and Styles
****************
- :cpp:enumerator:`LV_PART_MAIN` The background of the table uses all the typical
background style properties.
- :cpp:enumerator:`LV_PART_ITEMS` The cells of the table also use all the typical
background style properties and the text properties.
.. _lv_table_usage:
Usage
*****
Set cell value
--------------
The cells can store only text so numbers need to be converted to text
before displaying them in a table.
:cpp:expr:`lv_table_set_cell_value(table, row, col, "Content")`. The text is
saved by the table so it can be even a local variable.
Line breaks can be used in the text like ``"Value\n60.3"``.
New rows and columns are automatically added is required
Rows and Columns
----------------
To explicitly set number of rows and columns use
:cpp:expr:`lv_table_set_row_count(table, row_cnt)` and
:cpp:expr:`lv_table_set_column_count(table, col_cnt)`
Width and Height
----------------
The width of the columns can be set with
:cpp:expr:`lv_table_set_column_width(table, col_id, width)`. The overall width of
the Table Widget will be set to the sum of columns widths.
The height is calculated automatically from the cell styles (font,
padding etc) and the number of rows.
Merge cells
-----------
Cells can be merged horizontally with
:cpp:expr:`lv_table_add_cell_ctrl(table, row, col, LV_TABLE_CELL_CTRL_MERGE_RIGHT)`.
To merge more adjacent cells call this function for each cell.
Scroll
------
If the label's width or height is set to :c:macro:`LV_SIZE_CONTENT` that size
will be used to show the whole table in the respective direction. E.g.
:cpp:expr:`lv_obj_set_size(table, LV_SIZE_CONTENT, LV_SIZE_CONTENT)`
automatically sets the table size to show all the columns and rows.
If the width or height is set to a smaller number than the "intrinsic"
size then the table becomes scrollable.
.. _lv_table_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new cell is selected with
keys.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_table_keys:
Keys
****
The following *Keys* are processed by Table Widgets: -
``LV_KEY_RIGHT/LEFT/UP/DOWN/`` Select a cell.
Note that, as usual, the state of :cpp:enumerator:`LV_KEY_ENTER` is translated to
``LV_EVENT_PRESSED/PRESSING/RELEASED`` etc.
:cpp:expr:`lv_table_get_selected_cell(table, &row, &col)` can be used to get the
currently selected cell. Row and column will be set to
:c:macro:`LV_TABLE_CELL_NONE` no cell is selected.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_table_example:
Example
*******
.. include:: ../../examples/widgets/table/index.rst
MicroPython
-----------
No examples yet.
.. _lv_table_api:
API
***

129
docs/details/widgets/tabview.rst Normal file
View File

@@ -0,0 +1,129 @@
.. _lv_tabview:
====================
Tabview (lv_tabview)
====================
Overview
********
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`
- Container for 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
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.
.. _lv_tabview_usage:
Usage
*****
Create a Tab view
-----------------
:cpp:expr:`lv_tabview_create(parent)` creates a new empty Tab view.
Add 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
-----------
A tab can be renamed with
:cpp:expr:`lv_tabview_rename_tab(tabview, tab_id, "New Name")`.
Change 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
Set 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.
Set 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.
Get 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
.. _lv_tabview_events:
Events
******
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new tab is selected by sliding
or clicking the tab button. :cpp:expr:`lv_tabview_get_tab_active(tabview)`
returns the zero based index of the current tab.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_tabview_keys:
Keys
****
Keys have effect only on the tab buttons.
Add manually to a group if required.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_tabview_example:
Example
*******
.. include:: ../../examples/widgets/tabview/index.rst
.. _lv_tabview_api:
API
***

206
docs/details/widgets/textarea.rst Normal file
View File

@@ -0,0 +1,206 @@
.. _lv_textarea:
=======================
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.
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,
right or center.
- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is
too long.
- :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.
- :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
``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.
.. _lv_textarea_usage:
Usage
*****
Add 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, "á")`.
:cpp:expr:`lv_textarea_set_text(ta, "New text")` changes the whole text.
Placeholder
-----------
A placeholder text can be specified
- which is displayed when the Text area is empty
- with :cpp:expr:`lv_textarea_set_placeholder_text(ta, "Placeholder text")`
Delete character
----------------
To delete a character from 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)`
Move 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
last character"
You can step the cursor 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.
Hide 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.
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.
Password mode
-------------
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
exist in the font, ``*`` will be used. You can override the default
character with :cpp:expr:`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.
The visibility time can be adjusted with :c:macro:`LV_TEXTAREA_DEF_PWD_SHOW_TIME` in ``lv_conf.h``.
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.
Max text length
---------------
The maximum number of characters can be limited with
:cpp:expr:`lv_textarea_set_max_length(textarea, max_char_num)`
Very long texts
---------------
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.
Select text
-----------
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.
.. _lv_textarea_events:
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.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_textarea_keys:
Keys
****
- ``LV_KEY_UP/DOWN/LEFT/RIGHT`` Move the cursor
- ``Any character`` Add the character to the current cursor position
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_textarea_example:
Example
*******
.. include:: ../../examples/widgets/textarea/index.rst
.. _lv_textarea_api:
API
***

95
docs/details/widgets/tileview.rst Normal file
View File

@@ -0,0 +1,95 @@
.. _lv_tileview:
=======================
Tile View (lv_tileview)
=======================
Overview
********
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
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
:ref:`base_widget` tiles.
The parts and styles work the same as for :ref:`base_widget`.
.. _lv_tileview_usage:
Usage
*****
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
``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.
The returned value is an ``lv_obj_t *`` 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)`
.. _lv_tileview_events:
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.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_tileview_keys:
Keys
****
No *Keys* are processed by Tileview Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_tileview_example:
Example
*******
.. include:: ../../examples/widgets/tileview/index.rst
.. _lv_tileview_api:
API
***

107
docs/details/widgets/win.rst Normal file
View File

@@ -0,0 +1,107 @@
.. _lv_win:
===============
Window (lv_win)
===============
Overview
********
The Window is container-like Widget built from a header 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
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`
.. _lv_win_usage:
Usage
*****
Create a Window
---------------
:cpp:expr:`lv_win_create(parent, header_height)` creates a Window with an empty
header.
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")`.
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
*************
: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
to which the content of the window can be added.
.. _lv_win_events:
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`.
.. admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_win_keys:
Keys
****
No *Keys* are processed by Window Widgets.
.. admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_win_example:
Example
*******
.. include:: ../../examples/widgets/win/index.rst
.. _lv_win_api:
API
***