docs: removes non ascii characters (#4175)
This commit is contained in:
Kevin Schlosser
@@ -132,7 +132,7 @@ Timeline
|
||||
A timeline is a collection of multiple animations which makes it easy to
|
||||
create complex composite animations.
|
||||
|
||||
Firstly, create an animation element but don’t call :cpp:func:`lv_anim_start`.
|
||||
Firstly, create an animation element but don't call :cpp:func:`lv_anim_start`.
|
||||
|
||||
Secondly, create an animation timeline object by calling
|
||||
:cpp:func:`lv_anim_timeline_create`.
|
||||
|
||||
@@ -29,7 +29,7 @@ Why would you want multi-display support? Here are some examples:
|
||||
Using only one display
|
||||
----------------------
|
||||
|
||||
Using more displays can be useful but in most cases it’s not required.
|
||||
Using more displays can be useful but in most cases it's not required.
|
||||
Therefore, the whole concept of multi-display handling is completely
|
||||
hidden if you register only one display. By default, the last created
|
||||
(and only) display is used.
|
||||
@@ -44,7 +44,7 @@ user activity on the default display. (See below in `Inactivity <#Inactivity>`__
|
||||
Mirror display
|
||||
--------------
|
||||
|
||||
To mirror the image of a display to another display, you don’t need to
|
||||
To mirror the image of a display to another display, you don't need to
|
||||
use multi-display support. Just transfer the buffer received in
|
||||
``flush_cb`` to the other display too.
|
||||
|
||||
@@ -53,8 +53,8 @@ Split image
|
||||
|
||||
You can create a larger virtual display from an array of smaller ones.
|
||||
You can create it as below: 1. Set the resolution of the displays to the
|
||||
large display’s resolution. 2. In ``flush_cb``, truncate and modify the
|
||||
``area`` parameter for each display. 3. Send the buffer’s content to
|
||||
large display's resolution. 2. In ``flush_cb``, truncate and modify the
|
||||
``area`` parameter for each display. 3. Send the buffer's content to
|
||||
each real display with the truncated area.
|
||||
|
||||
Screens
|
||||
@@ -71,10 +71,10 @@ Be sure not to confuse displays and screens:
|
||||
with it, but not vice versa.
|
||||
|
||||
Screens can be considered the highest level containers which have no
|
||||
parent. A screen’s size is always equal to its display and their origin
|
||||
is (0;0). Therefore, a screen’s coordinates can’t be changed,
|
||||
parent. A screen's size is always equal to its display and their origin
|
||||
is (0;0). Therefore, a screen's coordinates can't be changed,
|
||||
i.e. :cpp:expr:`lv_obj_set_pos()`, :cpp:expr:`lv_obj_set_size()` or similar functions
|
||||
can’t be used on screens.
|
||||
can't be used on screens.
|
||||
|
||||
A screen can be created from any object type but the two most typical
|
||||
types are `Base object </widgets/obj>`__ and `Image </widgets/img>`__
|
||||
@@ -99,7 +99,7 @@ Transparent screens
|
||||
|
||||
Usually, the opacity of the screen is :cpp:enumerator:`LV_OPA_COVER` to provide a
|
||||
solid background for its children. If this is not the case (opacity <
|
||||
100%) the display’s ``bottom_layer`` be visible. If the bottom layer’s
|
||||
100%) the display's ``bottom_layer`` be visible. If the bottom layer's
|
||||
opacity is also not :cpp:enumerator:`LV_OPA_COVER` LVGL has no solid background to
|
||||
draw.
|
||||
|
||||
@@ -107,17 +107,17 @@ This configuration (transparent screen and display) could be used to
|
||||
create for example OSD menus where a video is played on a lower layer,
|
||||
and a menu is overlaid on an upper layer.
|
||||
|
||||
To properly render the screen the display’s color format needs to be set
|
||||
To properly render the screen the display's color format needs to be set
|
||||
to one with alpha channel.
|
||||
|
||||
In summary, to enable transparent screens and displays for OSD menu-like
|
||||
UIs:
|
||||
|
||||
- Set the screen’s ``bg_opa`` to transparent:
|
||||
- Set the screen's ``bg_opa`` to transparent:
|
||||
:cpp:expr:`lv_obj_set_style_bg_opa(lv_scr_act(), LV_OPA_TRANSP, 0)`
|
||||
- Set the bottom layer’s ``bg_opa`` to transparent:
|
||||
- Set the bottom layer's ``bg_opa`` to transparent:
|
||||
:cpp:expr:`lv_obj_set_style_bg_opa(lv_scr_act(), LV_OPA_TRANSP, 0)`
|
||||
- Set the screen’s bg_opa to 0:
|
||||
- Set the screen's bg_opa to 0:
|
||||
:cpp:expr:`lv_obj_set_style_bg_opa(lv_layer_bottom(), LV_OPA_TRANSP, 0)`
|
||||
- Set a color format with alpha channel. E.g.
|
||||
:cpp:expr:`lv_disp_set_color_format(disp, LV_COLOR_FORMAT_NATIVE_ALPHA)`
|
||||
@@ -128,11 +128,11 @@ Features of displays
|
||||
Inactivity
|
||||
----------
|
||||
|
||||
A user’s inactivity time is measured on each display. Every use of an
|
||||
A user's inactivity time is measured on each display. Every use of an
|
||||
`Input device </overview/indev>`__ (if `associated with the display </porting/indev#other-features>`__) counts as an activity. To
|
||||
get time elapsed since the last activity, use
|
||||
:cpp:expr:`lv_disp_get_inactive_time(disp)`. If ``NULL`` is passed, the lowest
|
||||
inactivity time among all displays will be returned (**NULL isn’t just
|
||||
inactivity time among all displays will be returned (**NULL isn't just
|
||||
the default display**).
|
||||
|
||||
You can manually trigger an activity using
|
||||
@@ -152,7 +152,7 @@ adjusted with :cpp:expr:`lv_obj_set_style_bg_color(obj, color)`;
|
||||
The display background image is a path to a file or a pointer to an
|
||||
:cpp:struct:`lv_img_dsc_t` variable (converted image data) to be used as
|
||||
wallpaper. It can be set with :cpp:expr:`lv_obj_set_style_bg_img_src(obj, &my_img)`;
|
||||
If a background image is configured the background won’t be filled with
|
||||
If a background image is configured the background won't be filled with
|
||||
``bg_color``.
|
||||
|
||||
The opacity of the background color or image can be adjusted with
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
Drawing
|
||||
=======
|
||||
|
||||
With LVGL, you don’t need to draw anything manually. Just create objects
|
||||
With LVGL, you don't need to draw anything manually. Just create objects
|
||||
(like buttons, labels, arc, etc.), move and change them, and LVGL will
|
||||
refresh and redraw what is required.
|
||||
|
||||
@@ -16,7 +16,7 @@ The basic concept is to not draw directly onto the display but rather to
|
||||
first draw on an internal draw buffer. When a drawing (rendering) is
|
||||
ready that buffer is copied to the display.
|
||||
|
||||
The draw buffer can be smaller than a display’s size. LVGL will simply
|
||||
The draw buffer can be smaller than a display's size. LVGL will simply
|
||||
render in "tiles" that fit into the given draw buffer.
|
||||
|
||||
This approach has two main advantages compared to directly drawing to
|
||||
@@ -25,7 +25,7 @@ the display:
|
||||
1. It avoids flickering while the layers of the UI are
|
||||
drawn. For example, if LVGL drew directly onto the display, when drawing
|
||||
a *background + button + text*, each "stage" would be visible for a short time.
|
||||
2. It’s faster to modify a buffer in internal RAM and
|
||||
2. It's faster to modify a buffer in internal RAM and
|
||||
finally write one pixel only once than reading/writing the display
|
||||
directly on each pixel access. (e.g. via a display controller with SPI interface).
|
||||
|
||||
@@ -33,7 +33,7 @@ Note that this concept is different from "traditional" double buffering
|
||||
where there are two display sized frame buffers: one holds the current
|
||||
image to show on the display, and rendering happens to the other
|
||||
(inactive) frame buffer, and they are swapped when the rendering is
|
||||
finished. The main difference is that with LVGL you don’t have to store
|
||||
finished. The main difference is that with LVGL you don't have to store
|
||||
two frame buffers (which usually requires external RAM) but only smaller
|
||||
draw buffer(s) that can easily fit into internal RAM.
|
||||
|
||||
@@ -48,28 +48,28 @@ LVGL refreshes the screen in the following steps:
|
||||
in the UI which requires redrawing. For example, a button is pressed, a
|
||||
chart is changed, an animation happened, etc.
|
||||
|
||||
2. LVGL saves the changed object’s old and new area into a buffer, called an *Invalid area
|
||||
2. LVGL saves the changed object's old and new area into a buffer, called an *Invalid area
|
||||
buffer*. For optimization, in some cases, objects are not added to the buffer:
|
||||
|
||||
- Hidden objects are not added.
|
||||
- Objects completely out of their parent are not added.
|
||||
- Areas partially out of the parent are cropped to the parent’s area.
|
||||
- Areas partially out of the parent are cropped to the parent's area.
|
||||
- Objects on other screens are not added.
|
||||
|
||||
3. In every :c:macro:`LV_DEF_REFR_PERIOD` (set in ``lv_hal_disp.h``) the
|
||||
following happens:
|
||||
|
||||
- LVGL checks the invalid areas and joins those that are adjacent or intersecting.
|
||||
- Takes the first joined area, if it’s smaller than the *draw buffer*, then simply renders the area’s content
|
||||
into the *draw buffer*. If the area doesn’t fit into the buffer, draw as many lines as possible to the *draw buffer*.
|
||||
- Takes the first joined area, if it's smaller than the *draw buffer*, then simply renders the area's content
|
||||
into the *draw buffer*. If the area doesn't fit into the buffer, draw as many lines as possible to the *draw buffer*.
|
||||
- When the area is rendered, call ``flush_cb`` from the display driver to refresh the display.
|
||||
- If the area was larger than the buffer, render the remaining parts too.
|
||||
- Repeat the same with remaining joined areas.
|
||||
|
||||
When an area is redrawn the library searches the top-most object which
|
||||
covers that area and starts drawing from that object. For example, if a
|
||||
button’s label has changed, the library will see that it’s enough to
|
||||
draw the button under the text and it’s not necessary to redraw the
|
||||
button's label has changed, the library will see that it's enough to
|
||||
draw the button under the text and it's not necessary to redraw the
|
||||
display under the rest of the button too.
|
||||
|
||||
The difference between buffering modes regarding the drawing mechanism
|
||||
@@ -83,23 +83,23 @@ is the following:
|
||||
Masking
|
||||
*******
|
||||
|
||||
*Masking* is the basic concept of LVGL’s draw engine. To use LVGL it’s
|
||||
*Masking* is the basic concept of LVGL's draw engine. To use LVGL it's
|
||||
not required to know about the mechanisms described here but you might
|
||||
find interesting to know how drawing works under hood. Knowing about
|
||||
masking comes in handy if you want to customize drawing.
|
||||
|
||||
To learn about masking let’s see the steps of drawing first. LVGL
|
||||
To learn about masking let's see the steps of drawing first. LVGL
|
||||
performs the following steps to render any shape, image or text. It can
|
||||
be considered as a drawing pipeline.
|
||||
|
||||
1. **Prepare the draw descriptors** Create a draw descriptor from an
|
||||
object’s styles (e.g. :cpp:struct:`lv_draw_rect_dsc_t`). This gives us the
|
||||
object's styles (e.g. :cpp:struct:`lv_draw_rect_dsc_t`). This gives us the
|
||||
parameters for drawing, for example colors, widths, opacity, fonts,
|
||||
radius, etc.
|
||||
2. **Call the draw function** Call the draw function with the draw
|
||||
descriptor and some other parameters (e.g. :cpp:func:`lv_draw_rect`). It
|
||||
will render the primitive shape to the current draw buffer.
|
||||
3. **Create masks** If the shape is very simple and doesn’t require
|
||||
3. **Create masks** If the shape is very simple and doesn't require
|
||||
masks, go to #5. Otherwise, create the required masks in the draw
|
||||
function. (e.g. a rounded rectangle mask)
|
||||
4. **Calculate all the added mask** It composites opacity values into a
|
||||
@@ -119,7 +119,7 @@ applied real-time:
|
||||
of it. Essentially, every (skew) line is bounded with four line masks
|
||||
forming a rectangle.
|
||||
- :cpp:enumerator:`LV_DRAW_MASK_TYPE_RADIUS`: Removes the inner or
|
||||
outer corners of a rectangle with a radiused transition. It’s also used
|
||||
outer corners of a rectangle with a radiused transition. It's also used
|
||||
to create circles by setting the radius to large value
|
||||
(:c:macro:`LV_RADIUS_CIRCLE`)
|
||||
- :cpp:enumerator:`LV_DRAW_MASK_TYPE_ANGLE`: Removes a circular
|
||||
@@ -130,7 +130,7 @@ applied real-time:
|
||||
|
||||
Masks are used to create almost every basic primitive:
|
||||
|
||||
- **letters**: Create a mask from the letter and draw a rectangle with the letter’s color using the mask.
|
||||
- **letters**: Create a mask from the letter and draw a rectangle with the letter's color using the mask.
|
||||
- **line**: Created from four "line masks" to mask out the left, right, top and bottom part of the line to get a perfectly perpendicular perimeter.
|
||||
- **rounded rectangle**: A mask is created real-time to add a radius to the corners.
|
||||
- **clip corner**: To clip overflowing content (usually children) on rounded corners, a rounded rectangle mask is also applied.
|
||||
@@ -141,7 +141,7 @@ Masks are used to create almost every basic primitive:
|
||||
Using masks
|
||||
-----------
|
||||
|
||||
Every mask type has a related parameter structure to describe the mask’s
|
||||
Every mask type has a related parameter structure to describe the mask's
|
||||
data. The following parameter types exist:
|
||||
|
||||
- :cpp:type:`lv_draw_mask_line_param_t`
|
||||
@@ -179,7 +179,7 @@ can be added manually.
|
||||
|
||||
A good use case for this is the `Button matrix </widgets/btnmatrix>`__
|
||||
widget. By default, its buttons can be styled in different states, but
|
||||
you can’t style the buttons one by one. However, an event is sent for
|
||||
you can't style the buttons one by one. However, an event is sent for
|
||||
every button and you can, for example, tell LVGL to use different colors
|
||||
on a specific button or to manually draw an image on some buttons.
|
||||
|
||||
@@ -208,7 +208,7 @@ LV_EVENT_DRAW_MAIN
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The actual drawing of an object happens in this event. E.g. a rectangle
|
||||
for a button is drawn here. First, the widgets’ internal events are
|
||||
for a button is drawn here. First, the widgets' internal events are
|
||||
called to perform drawing and after that you can draw anything on top of
|
||||
them. For example you can add a custom text or an image.
|
||||
|
||||
@@ -216,7 +216,7 @@ LV_EVENT_DRAW_MAIN_END
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Called when the main drawing is finished. You can draw anything here as
|
||||
well and it’s also a good place to remove any masks created in
|
||||
well and it's also a good place to remove any masks created in
|
||||
:cpp:enumerator:`LV_EVENT_DRAW_MAIN_BEGIN`.
|
||||
|
||||
Post drawing
|
||||
@@ -250,15 +250,15 @@ Called when post drawing has finished. If masks were not removed in
|
||||
Part drawing
|
||||
------------
|
||||
|
||||
When LVGL draws a part of an object (e.g. a slider’s indicator, a
|
||||
table’s cell or a button matrix’s button) it sends events before and
|
||||
When LVGL draws a part of an object (e.g. a slider's indicator, a
|
||||
table's cell or a button matrix's button) it sends events before and
|
||||
after drawing that part with some context of the drawing. This allows
|
||||
changing the parts on a very low level with masks, extra drawing, or
|
||||
changing the parameters that LVGL is planning to use for drawing.
|
||||
|
||||
In these events an :cpp:struct:`lv_obj_draw_part_dsc_t` structure is used to describe
|
||||
the context of the drawing. Not all fields are set for every part and
|
||||
widget. To see which fields are set for a widget refer to the widget’s
|
||||
widget. To see which fields are set for a widget refer to the widget's
|
||||
documentation.
|
||||
|
||||
:cpp:struct:`lv_obj_draw_part_dsc_t` has the following fields:
|
||||
@@ -327,33 +327,33 @@ these results:
|
||||
Here are some reasons why an object would be unable to fully cover an
|
||||
area:
|
||||
|
||||
- It’s simply not fully in area
|
||||
- It's simply not fully in area
|
||||
- It has a radius
|
||||
- It doesn’t have 100% background opacity
|
||||
- It’s an ARGB or chroma keyed image
|
||||
- It doesn't have 100% background opacity
|
||||
- It's an ARGB or chroma keyed image
|
||||
- It does not have normal blending mode. In this case LVGL needs to know the
|
||||
colors under the object to apply blending properly
|
||||
- It’s a text, etc
|
||||
- It's a text, etc
|
||||
|
||||
In short if for any reason the area below an object is visible than the
|
||||
object doesn’t cover that area.
|
||||
object doesn't cover that area.
|
||||
|
||||
Before sending this event LVGL checks if at least the widget’s
|
||||
Before sending this event LVGL checks if at least the widget's
|
||||
coordinates fully cover the area or not. If not the event is not called.
|
||||
|
||||
You need to check only the drawing you have added. The existing
|
||||
properties known by a widget are handled in its internal events. E.g. if
|
||||
a widget has > 0 radius it might not cover an area, but you need to
|
||||
handle ``radius`` only if you will modify it and the widget won’t know
|
||||
handle ``radius`` only if you will modify it and the widget won't know
|
||||
about it.
|
||||
|
||||
LV_EVENT_REFR_EXT_DRAW_SIZE
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you need to draw outside a widget, LVGL needs to know about it to
|
||||
provide extra space for drawing. Let’s say you create an event which
|
||||
provide extra space for drawing. Let's say you create an event which
|
||||
writes the current value of a slider above its knob. In this case LVGL
|
||||
needs to know that the slider’s draw area should be larger with the size
|
||||
needs to know that the slider's draw area should be larger with the size
|
||||
required for the text.
|
||||
|
||||
You can simply set the required draw area with
|
||||
|
||||
@@ -73,7 +73,7 @@ acts as a modal.
|
||||
lv_obj_add_flag(lv_layer_top(), LV_OBJ_FLAG_CLICKABLE);
|
||||
|
||||
The ``layer_sys`` is also used for similar purposes in LVGL. For
|
||||
example, it places the mouse cursor above all layers to be sure it’s
|
||||
example, it places the mouse cursor above all layers to be sure it's
|
||||
always visible.
|
||||
|
||||
API
|
||||
|
||||
@@ -17,7 +17,7 @@ In general, you can set the macro :c:macro:`LV_USE_GPU_ARM2D` to ``1`` in
|
||||
|
||||
If you are using
|
||||
`CMSIS-Pack <https://github.com/lvgl/lvgl/tree/master/env_support/cmsis-pack>`__
|
||||
to deploy the LVGL. You don’t have to define the macro
|
||||
to deploy the LVGL. You don't have to define the macro
|
||||
:c:macro:`LV_USE_GPU_ARM2D` manually, instead, please select the component
|
||||
``GPU Arm-2D`` in the **RTE** dialog. This step will define the macro for us.
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ width
|
||||
|
||||
Sets the width of object. Pixel, percentage and :c:macro:`LV_SIZE_CONTENT`
|
||||
values can be used. Percentage values are relative to the width of the
|
||||
parent’s content area.
|
||||
parent's content area.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
@@ -67,7 +67,7 @@ min_width
|
||||
~~~~~~~~~
|
||||
|
||||
Sets a minimal width. Pixel and percentage values can be used.
|
||||
Percentage values are relative to the width of the parent’s content
|
||||
Percentage values are relative to the width of the parent's content
|
||||
area.
|
||||
|
||||
.. raw:: html
|
||||
@@ -122,7 +122,7 @@ max_width
|
||||
~~~~~~~~~
|
||||
|
||||
Sets a maximal width. Pixel and percentage values can be used.
|
||||
Percentage values are relative to the width of the parent’s content
|
||||
Percentage values are relative to the width of the parent's content
|
||||
area.
|
||||
|
||||
.. raw:: html
|
||||
@@ -177,7 +177,7 @@ height
|
||||
~~~~~~
|
||||
|
||||
Sets the height of object. Pixel, percentage and :c:macro:`LV_SIZE_CONTENT` can
|
||||
be used. Percentage values are relative to the height of the parent’s
|
||||
be used. Percentage values are relative to the height of the parent's
|
||||
content area.
|
||||
|
||||
.. raw:: html
|
||||
@@ -232,7 +232,7 @@ min_height
|
||||
~~~~~~~~~~
|
||||
|
||||
Sets a minimal height. Pixel and percentage values can be used.
|
||||
Percentage values are relative to the width of the parent’s content
|
||||
Percentage values are relative to the width of the parent's content
|
||||
area.
|
||||
|
||||
.. raw:: html
|
||||
@@ -287,7 +287,7 @@ max_height
|
||||
~~~~~~~~~~
|
||||
|
||||
Sets a maximal height. Pixel and percentage values can be used.
|
||||
Percentage values are relative to the height of the parent’s content
|
||||
Percentage values are relative to the height of the parent's content
|
||||
area.
|
||||
|
||||
.. raw:: html
|
||||
@@ -343,7 +343,7 @@ x
|
||||
|
||||
Set the X coordinate of the object considering the set ``align``. Pixel
|
||||
and percentage values can be used. Percentage values are relative to the
|
||||
width of the parent’s content area.
|
||||
width of the parent's content area.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
@@ -398,7 +398,7 @@ y
|
||||
|
||||
Set the Y coordinate of the object considering the set ``align``. Pixel
|
||||
and percentage values can be used. Percentage values are relative to the
|
||||
height of the parent’s content area.
|
||||
height of the parent's content area.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
@@ -523,7 +523,7 @@ transform_width
|
||||
|
||||
Make the object wider on both sides with this value. Pixel and
|
||||
percentage (with :cpp:expr:`lv_pct(x)`) values can be used. Percentage values
|
||||
are relative to the object’s width.
|
||||
are relative to the object's width.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
@@ -578,7 +578,7 @@ transform_height
|
||||
|
||||
Make the object higher on both sides with this value. Pixel and
|
||||
percentage (with :cpp:expr:`lv_pct(x)`) values can be used. Percentage values
|
||||
are relative to the object’s height.
|
||||
are relative to the object's height.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
@@ -633,7 +633,7 @@ translate_x
|
||||
|
||||
Move the object with this value in X direction. Applied after layouts,
|
||||
aligns and other positioning. Pixel and percentage (with :cpp:expr:`lv_pct(x)`)
|
||||
values can be used. Percentage values are relative to the object’s
|
||||
values can be used. Percentage values are relative to the object's
|
||||
width.
|
||||
|
||||
.. raw:: html
|
||||
@@ -689,7 +689,7 @@ translate_y
|
||||
|
||||
Move the object with this value in Y direction. Applied after layouts,
|
||||
aligns and other positioning. Pixel and percentage (with :cpp:expr:`lv_pct(x)`)
|
||||
values can be used. Percentage values are relative to the object’s
|
||||
values can be used. Percentage values are relative to the object's
|
||||
height.
|
||||
|
||||
.. raw:: html
|
||||
@@ -851,8 +851,8 @@ Ext. draw Yes
|
||||
transform_pivot_x
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Set the pivot point’s X coordinate for transformations. Relative to the
|
||||
object’s top left corner’
|
||||
Set the pivot point's X coordinate for transformations. Relative to the
|
||||
object's top left corner'
|
||||
|
||||
.. raw:: html
|
||||
|
||||
@@ -905,8 +905,8 @@ Ext. draw No
|
||||
transform_pivot_y
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Set the pivot point’s Y coordinate for transformations. Relative to the
|
||||
object’s top left corner’
|
||||
Set the pivot point's Y coordinate for transformations. Relative to the
|
||||
object's top left corner'
|
||||
|
||||
.. raw:: html
|
||||
|
||||
@@ -959,7 +959,7 @@ Ext. draw No
|
||||
Padding
|
||||
-------
|
||||
|
||||
Properties to describe spacing between the parent’s sides and the
|
||||
Properties to describe spacing between the parent's sides and the
|
||||
children and among the children. Very similar to the padding properties
|
||||
in HTML.
|
||||
|
||||
@@ -1791,7 +1791,7 @@ Ext. draw No
|
||||
bg_grad_stop
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Set the point from which the background’s gradient color should start. 0
|
||||
Set the point from which the background's gradient color should start. 0
|
||||
means to top/left side, 255 the bottom/right side, 128 the center, and
|
||||
so on
|
||||
|
||||
@@ -2517,7 +2517,7 @@ Ext. draw No
|
||||
Outline
|
||||
-------
|
||||
|
||||
Properties to describe the outline. It’s like a border but drawn outside
|
||||
Properties to describe the outline. It's like a border but drawn outside
|
||||
of the rectangles.
|
||||
|
||||
outline_width
|
||||
@@ -3780,7 +3780,7 @@ Ext. draw No
|
||||
arc_img_src
|
||||
~~~~~~~~~~~
|
||||
|
||||
Set an image from which the arc will be masked out. It’s useful to
|
||||
Set an image from which the arc will be masked out. It's useful to
|
||||
display complex effects on the arcs. Can be a pointer to
|
||||
:cpp:struct:`lv_img_dsc_t` or a path to a file
|
||||
|
||||
@@ -4168,7 +4168,7 @@ Ext. draw No
|
||||
text_align
|
||||
~~~~~~~~~~
|
||||
|
||||
Set how to align the lines of the text. Note that it doesn’t align the
|
||||
Set how to align the lines of the text. Note that it doesn't align the
|
||||
object itself, only the lines inside the object. The possible values are:
|
||||
|
||||
- :cpp:enumerator:`LV_TEXT_ALIGN_LEFT`
|
||||
@@ -4504,10 +4504,10 @@ Ext. draw No
|
||||
anim
|
||||
~~~~
|
||||
|
||||
The animation template for the object’s animation. Should be a pointer
|
||||
The animation template for the object's animation. Should be a pointer
|
||||
to :cpp:type:`lv_anim_t`. The animation parameters are widget specific,
|
||||
e.g. animation time could be the E.g. blink time of the cursor on the
|
||||
text area or scroll time of a roller. See the widgets’ documentation to
|
||||
text area or scroll time of a roller. See the widgets' documentation to
|
||||
learn more.
|
||||
|
||||
.. raw:: html
|
||||
@@ -4563,7 +4563,7 @@ anim_time
|
||||
|
||||
The animation time in milliseconds. Its meaning is widget specific. E.g.
|
||||
blink time of the cursor on the text area or scroll time of a roller.
|
||||
See the widgets’ documentation to learn more.
|
||||
See the widgets' documentation to learn more.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
@@ -4617,7 +4617,7 @@ anim_speed
|
||||
~~~~~~~~~~
|
||||
|
||||
The animation speed in pixel/sec. Its meaning is widget specific. E.g.
|
||||
scroll speed of label. See the widgets’ documentation to learn more.
|
||||
scroll speed of label. See the widgets' documentation to learn more.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
|
||||
@@ -7,24 +7,24 @@ Styles
|
||||
*Styles* are used to set the appearance of objects. Styles in lvgl are
|
||||
heavily inspired by CSS. The concept in a nutshell is as follows: - A
|
||||
style is an :cpp:type:`lv_style_t` variable which can hold properties like
|
||||
border width, text color and so on. It’s similar to a ``class`` in CSS.
|
||||
border width, text color and so on. It's similar to a ``class`` in CSS.
|
||||
|
||||
- Styles can be assigned to objects to change their appearance. Upon
|
||||
assignment, the target part (*pseudo-element* in CSS) and target state
|
||||
(*pseudo class*) can be specified. For example one can add
|
||||
``style_blue`` to the knob of a slider when it’s in pressed state.
|
||||
``style_blue`` to the knob of a slider when it's in pressed state.
|
||||
- The same style can be used by any number of objects.
|
||||
- Styles can be cascaded which means multiple styles may be assigned to an object and
|
||||
each style can have different properties. Therefore, not all properties
|
||||
have to be specified in a style. LVGL will search for a property until a
|
||||
style defines it or use a default if it’s not specified by any of the
|
||||
style defines it or use a default if it's not specified by any of the
|
||||
styles. For example ``style_btn`` can result in a default gray button
|
||||
and ``style_btn_red`` can add only a ``background-color=red`` to
|
||||
overwrite the background color.
|
||||
- The most recently added style has higher precedence. This means if a property
|
||||
is specified in two styles the newest style in the object will be used.
|
||||
- Some properties (e.g. text color) can be inherited from a parent(s) if it’s not specified in an object.
|
||||
- Objects can also have local styles with higher precedence than “normal” styles.
|
||||
- Some properties (e.g. text color) can be inherited from a parent(s) if it's not specified in an object.
|
||||
- Objects can also have local styles with higher precedence than "normal" styles.
|
||||
- Unlike CSS (where pseudo-classes describe different states, e.g. ``:focus``),
|
||||
in LVGL a property is assigned to a given state.
|
||||
- Transitions can be applied when the object changes state.
|
||||
@@ -53,51 +53,51 @@ pressed at the same time. This is represented as :cpp:expr:`LV_STATE_FOCUSED | L
|
||||
|
||||
A style can be added to any state or state combination. For example,
|
||||
setting a different background color for the default and pressed states.
|
||||
If a property is not defined in a state the best matching state’s
|
||||
If a property is not defined in a state the best matching state's
|
||||
property will be used. Typically this means the property with
|
||||
:cpp:enumerator:`LV_STATE_DEFAULT` is used.˛ If the property is not set even for the
|
||||
default state the default value will be used. (See later)
|
||||
|
||||
But what does the “best matching state’s property” really mean? States
|
||||
But what does the "best matching state's property" really mean? States
|
||||
have a precedence which is shown by their value (see in the above list).
|
||||
A higher value means higher precedence. To determine which state’s
|
||||
property to use let’s take an example. Imagine the background color is
|
||||
A higher value means higher precedence. To determine which state's
|
||||
property to use let's take an example. Imagine the background color is
|
||||
defined like this:
|
||||
|
||||
- :cpp:enumerator:`LV_STATE_DEFAULT`: white
|
||||
- :cpp:enumerator:`LV_STATE_PRESSED`: gray
|
||||
- :cpp:enumerator:`LV_STATE_FOCUSED`: red
|
||||
|
||||
1. Initially the object is in the default state, so it’s a simple case:
|
||||
the property is perfectly defined in the object’s current state as
|
||||
1. Initially the object is in the default state, so it's a simple case:
|
||||
the property is perfectly defined in the object's current state as
|
||||
white.
|
||||
2. When the object is pressed there are 2 related properties: default
|
||||
with white (default is related to every state) and pressed with gray.
|
||||
The pressed state has 0x0020 precedence which is higher than the
|
||||
default state’s 0x0000 precedence, so gray color will be used.
|
||||
default state's 0x0000 precedence, so gray color will be used.
|
||||
3. When the object is focused the same thing happens as in pressed state
|
||||
and red color will be used. (Focused state has higher precedence than
|
||||
default state).
|
||||
4. When the object is focused and pressed both gray and red would work,
|
||||
but the pressed state has higher precedence than focused so gray
|
||||
color will be used.
|
||||
5. It’s possible to set e.g. rose color for :cpp:expr:`LV_STATE_PRESSED | LV_STATE_FOCUSED`.
|
||||
5. It's possible to set e.g. rose color for :cpp:expr:`LV_STATE_PRESSED | LV_STATE_FOCUSED`.
|
||||
In this case, this combined state has 0x0020 + 0x0002 = 0x0022 precedence, which is higher than
|
||||
the pressed state’s precedence so rose color would be used.
|
||||
the pressed state's precedence so rose color would be used.
|
||||
6. When the object is in the checked state there is no property to set
|
||||
the background color for this state. So for lack of a better option,
|
||||
the object remains white from the default state’s property.
|
||||
the object remains white from the default state's property.
|
||||
|
||||
Some practical notes:
|
||||
|
||||
- The precedence (value) of states is quite intuitive, and it’s something the
|
||||
- The precedence (value) of states is quite intuitive, and it's something the
|
||||
user would expect naturally. E.g. if an object is focused the user will still
|
||||
want to see if it’s pressed, therefore the pressed state has a higher
|
||||
want to see if it's pressed, therefore the pressed state has a higher
|
||||
precedence. If the focused state had a higher precedence it would overwrite
|
||||
the pressed color.
|
||||
- If you want to set a property for all states (e.g. red background color)
|
||||
just set it for the default state. If the object can’t find a property
|
||||
for its current state it will fall back to the default state’s property.
|
||||
just set it for the default state. If the object can't find a property
|
||||
for its current state it will fall back to the default state's property.
|
||||
- Use ORed states to describe the properties for complex cases. (E.g.
|
||||
pressed + checked + focused)
|
||||
- It might be a good idea to use different
|
||||
@@ -110,7 +110,7 @@ Some practical notes:
|
||||
Cascading styles
|
||||
****************
|
||||
|
||||
It’s not required to set all the properties in one style. It’s possible
|
||||
It's not required to set all the properties in one style. It's possible
|
||||
to add more styles to an object and have the latter added style modify
|
||||
or extend appearance. For example, create a general gray button style
|
||||
and create a new one for red buttons where only the new background color
|
||||
@@ -122,13 +122,13 @@ This is much like in CSS when used classes are listed like
|
||||
Styles added later have precedence over ones set earlier. So in the
|
||||
gray/red button example above, the normal button style should be added
|
||||
first and the red style second. However, the precedence of the states
|
||||
are still taken into account. So let’s examine the following case:
|
||||
are still taken into account. So let's examine the following case:
|
||||
|
||||
- the basic button style defines dark-gray color for the default state and
|
||||
light-gray color for the pressed state
|
||||
- the red button style defines the background color as red only in the default state
|
||||
|
||||
In this case, when the button is released (it’s in default state) it
|
||||
In this case, when the button is released (it's in default state) it
|
||||
will be red because a perfect match is found in the most recently added
|
||||
style (red). When the button is pressed the light-gray color is a better
|
||||
match because it describes the current state perfectly, so the button
|
||||
@@ -138,9 +138,9 @@ Inheritance
|
||||
***********
|
||||
|
||||
Some properties (typically those related to text) can be inherited from
|
||||
the parent object’s styles. Inheritance is applied only if the given
|
||||
property is not set in the object’s styles (even in default state). In
|
||||
this case, if the property is inheritable, the property’s value will be
|
||||
the parent object's styles. Inheritance is applied only if the given
|
||||
property is not set in the object's styles (even in default state). In
|
||||
this case, if the property is inheritable, the property's value will be
|
||||
searched in the parents until an object specifies a value for the
|
||||
property. The parents will use their own state to determine the value.
|
||||
So if a button is pressed, and the text color comes from here, the
|
||||
@@ -149,9 +149,9 @@ pressed text color will be used.
|
||||
Forced value inheritance/default value
|
||||
**************************************
|
||||
|
||||
Sometimes you may want to force a child object to use the parent’s value
|
||||
Sometimes you may want to force a child object to use the parent's value
|
||||
for a given style property. To do this you can use one of the following
|
||||
(depending on what type of style you’re using):
|
||||
(depending on what type of style you're using):
|
||||
|
||||
.. code:: c
|
||||
|
||||
@@ -184,7 +184,7 @@ The following predefined parts exist in LVGL:
|
||||
- :cpp:enumerator:`LV_PART_SELECTED`: Indicate the currently selected option or section
|
||||
- :cpp:enumerator:`LV_PART_ITEMS`: Used if the widget has multiple similar elements (e.g. table cells)
|
||||
- :cpp:enumerator:`LV_PART_TICKS`: Ticks on scales e.g. for a chart or meter
|
||||
- :cpp:enumerator:`LV_PART_CURSOR`: Mark a specific place e.g. text area’s or chart’s cursor
|
||||
- :cpp:enumerator:`LV_PART_CURSOR`: Mark a specific place e.g. text area's or chart's cursor
|
||||
- :cpp:enumerator:`LV_PART_CUSTOM_FIRST`: Custom part identifiers can be added starting from here.
|
||||
|
||||
For example a `Slider </widgets/slider.html>`__ has three parts:
|
||||
@@ -229,7 +229,7 @@ To remove a property use:
|
||||
|
||||
lv_style_remove_prop(&style, LV_STYLE_BG_COLOR);
|
||||
|
||||
To get a property’s value from a style:
|
||||
To get a property's value from a style:
|
||||
|
||||
.. code:: c
|
||||
|
||||
@@ -302,7 +302,7 @@ function will only replace ``old_style`` with ``new_style`` if the
|
||||
``selector`` matches the ``selector`` used in ``lv_obj_add_style``. Both
|
||||
styles, i.e. ``old_style`` and ``new_style``, must not be ``NULL`` (for
|
||||
adding and removing separate functions exist). If the combination of
|
||||
``old_style`` and ``selector`` exists multiple times in ``obj``\ ’s
|
||||
``old_style`` and ``selector`` exists multiple times in ``obj``\ 's
|
||||
styles, all occurrences will be replaced. The return value of the
|
||||
function indicates whether at least one successful replacement took
|
||||
place.
|
||||
@@ -344,14 +344,14 @@ notified. There are 3 options to do this:
|
||||
when needed, call :cpp:expr:`lv_obj_report_style_change(&style)`. If ``style``
|
||||
is ``NULL`` all objects will be notified about a style change.
|
||||
|
||||
Get a property’s value on an object
|
||||
Get a property's value on an object
|
||||
-----------------------------------
|
||||
|
||||
To get a final value of property
|
||||
|
||||
- considering cascading, inheritance, local styles and transitions (see below)
|
||||
- property get functions like this can be used: ``lv_obj_get_style_<property_name>(obj, <part>)``.
|
||||
These functions use the object’s current state and if no better candidate exists they return a default value.
|
||||
These functions use the object's current state and if no better candidate exists they return a default value.
|
||||
For example:
|
||||
|
||||
.. code:: c
|
||||
@@ -361,11 +361,11 @@ To get a final value of property
|
||||
Local styles
|
||||
************
|
||||
|
||||
In addition to “normal” styles, objects can also store local styles.
|
||||
In addition to "normal" styles, objects can also store local styles.
|
||||
This concept is similar to inline styles in CSS
|
||||
(e.g. ``<div style="color:red">``) with some modification.
|
||||
|
||||
Local styles are like normal styles, but they can’t be shared among
|
||||
Local styles are like normal styles, but they can't be shared among
|
||||
other objects. If used, local styles are allocated automatically, and
|
||||
freed when the object is deleted. They are useful to add local
|
||||
customization to an object.
|
||||
@@ -391,9 +391,9 @@ For the full list of style properties click
|
||||
Typical background properties
|
||||
-----------------------------
|
||||
|
||||
In the documentation of the widgets you will see sentences like “The
|
||||
widget uses the typical background properties”. These “typical
|
||||
background properties” are the ones related to:
|
||||
In the documentation of the widgets you will see sentences like "The
|
||||
widget uses the typical background properties". These "typical
|
||||
background properties" are the ones related to:
|
||||
|
||||
- Background
|
||||
- Border
|
||||
@@ -406,13 +406,13 @@ background properties” are the ones related to:
|
||||
Transitions
|
||||
***********
|
||||
|
||||
By default, when an object changes state (e.g. it’s pressed) the new
|
||||
By default, when an object changes state (e.g. it's pressed) the new
|
||||
properties from the new state are set immediately. However, with
|
||||
transitions it’s possible to play an animation on state change. For
|
||||
transitions it's possible to play an animation on state change. For
|
||||
example, on pressing a button its background color can be animated to
|
||||
the pressed color over 300 ms.
|
||||
|
||||
The parameters of the transitions are stored in the styles. It’s
|
||||
The parameters of the transitions are stored in the styles. It's
|
||||
possible to set
|
||||
|
||||
- the time of the transition
|
||||
@@ -456,18 +456,18 @@ transformation properties.
|
||||
These properties have this effect only on the ``MAIN`` part of the
|
||||
widget.
|
||||
|
||||
The created snapshot is called “intermediate layer” or simply “layer”.
|
||||
The created snapshot is called "intermediate layer" or simply "layer".
|
||||
If only ``opa`` and/or ``blend_mode`` is set to a non-default value LVGL
|
||||
can build the layer from smaller chunks. The size of these chunks can be
|
||||
configured by the following properties in ``lv_conf.h``:
|
||||
|
||||
- :cpp:enumerator:`LV_LAYER_SIMPLE_BUF_SIZE`: [bytes] the optimal target buffer size. LVGL will try to allocate this size of memory.
|
||||
- :cpp:enumerator:`LV_LAYER_SIMPLE_FALLBACK_BUF_SIZE`: [bytes] used if :cpp:enumerator:`LV_LAYER_SIMPLE_BUF_SIZE` couldn’t be allocated.
|
||||
- :cpp:enumerator:`LV_LAYER_SIMPLE_FALLBACK_BUF_SIZE`: [bytes] used if :cpp:enumerator:`LV_LAYER_SIMPLE_BUF_SIZE` couldn't be allocated.
|
||||
|
||||
If transformation properties were also used the layer can not be
|
||||
rendered in chunks, but one larger memory needs to be allocated. The
|
||||
required memory depends on the angle, zoom and pivot parameters, and the
|
||||
size of the area to redraw, but it’s never larger than the size of the
|
||||
size of the area to redraw, but it's never larger than the size of the
|
||||
widget (including the extra draw size used for shadow, outline, etc).
|
||||
|
||||
If the widget can fully cover the area to redraw, LVGL creates an RGB
|
||||
@@ -499,7 +499,7 @@ To set a theme for a display, two steps are required:
|
||||
2. Assign the initialized theme to a display.
|
||||
|
||||
Theme initialization functions can have different prototypes. This
|
||||
example shows how to set the “default” theme:
|
||||
example shows how to set the "default" theme:
|
||||
|
||||
.. code:: c
|
||||
|
||||
@@ -518,8 +518,8 @@ Extending themes
|
||||
----------------
|
||||
|
||||
Built-in themes can be extended. If a custom theme is created, a parent
|
||||
theme can be selected. The parent theme’s styles will be added before
|
||||
the custom theme’s styles. Any number of themes can be chained this way.
|
||||
theme can be selected. The parent theme's styles will be added before
|
||||
the custom theme's styles. Any number of themes can be chained this way.
|
||||
E.g. default theme -> custom theme -> dark theme.
|
||||
|
||||
:cpp:expr:`lv_theme_set_parent(new_theme, base_theme)` extends the
|
||||
|
||||
@@ -66,29 +66,29 @@ Repeat count
|
||||
|
||||
You can make a timer repeat only a given number of times with
|
||||
:cpp:expr:`lv_timer_set_repeat_count(timer, count)`. The timer will
|
||||
automatically be deleted after it’s called the defined number of times.
|
||||
automatically be deleted after it's called the defined number of times.
|
||||
Set the count to ``-1`` to repeat indefinitely.
|
||||
|
||||
Measure idle time
|
||||
*****************
|
||||
|
||||
You can get the idle percentage time of :cpp:func:`lv_timer_handler` with
|
||||
:cpp:func:`lv_timer_get_idle`. Note that, it doesn’t measure the idle time of
|
||||
:cpp:func:`lv_timer_get_idle`. Note that, it doesn't measure the idle time of
|
||||
the overall system, only :cpp:func:`lv_timer_handler`. It can be misleading if
|
||||
you use an operating system and call :cpp:func:`lv_timer_handler` in a timer, as
|
||||
it won’t actually measure the time the OS spends in an idle thread.
|
||||
it won't actually measure the time the OS spends in an idle thread.
|
||||
|
||||
Asynchronous calls
|
||||
******************
|
||||
|
||||
In some cases, you can’t perform an action immediately. For example, you
|
||||
can’t delete an object because something else is still using it, or you
|
||||
don’t want to block the execution now. For these cases,
|
||||
In some cases, you can't perform an action immediately. For example, you
|
||||
can't delete an object because something else is still using it, or you
|
||||
don't want to block the execution now. For these cases,
|
||||
:cpp:expr:`lv_async_call(my_function, data_p)` can be used to call
|
||||
``my_function`` on the next invocation of :cpp:func:`lv_timer_handler`.
|
||||
``data_p`` will be passed to the function when it’s called. Note that
|
||||
``data_p`` will be passed to the function when it's called. Note that
|
||||
only the data pointer is saved, so you need to ensure that the variable
|
||||
will be “alive” while the function is called. It can be *static*, global
|
||||
will be "alive" while the function is called. It can be *static*, global
|
||||
or dynamically allocated data. If you want to cancel an asynchronous
|
||||
call, call :cpp:expr:`lv_async_call_cancel(my_function, data_p)`, which will
|
||||
clear all asynchronous calls matching ``my_function`` and ``data_p``.
|
||||
@@ -114,7 +114,7 @@ For example:
|
||||
|
||||
/*The screen is still valid so you can do other things with it*/
|
||||
|
||||
If you just want to delete an object and don’t need to clean anything up
|
||||
If you just want to delete an object and don't need to clean anything up
|
||||
in ``my_screen_cleanup`` you could just use :cpp:func:`lv_obj_del_async` which
|
||||
will delete the object on the next call to :cpp:func:`lv_timer_handler`.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user