Embedded/lvgl
1
0
Fork 0
mirror of https://github.com/lvgl/lvgl.git synced 2025-01-28 07:03:00 +08:00
Code Issues Projects Releases Wiki Activity

docs(examples) fix some examples

Browse Source
This commit is contained in:
Gabor Kiss-Vamosi 2021-05-07 21:23:09 +02:00
parent 77b098db9d
commit f5c70a06db
14 changed files with 134 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
docs/widgets/core/label.md
View File

@ -1,6 +1,6 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/label.md
:github_url: |github_link_base|/widgets/core/label.md
```
# Label (lv_label)
@ -8,8 +8,7 @@
A label is the basic object type that is used to display text.
## Parts and Styles
The label has only a main part, called `LV_LABEL_PART_MAIN`. It uses all the typical background properties and the *text* properties.
The padding values can be used to make the area for the text small in the related direction.
- `LV_PART_MAIN` ut 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.
## Usage
@ -18,61 +17,45 @@ You can set the text on a label at runtime with `lv_label_set_text(label, "New t
It 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 `lv_label_set_text` in scope after that function returns.
With `lv_label_set_text_fmt(label, "Value: %d", 15)` **printf formatting** can be used to set the text.
With `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** which is `\0`-terminated.
To do so, use `lv_label_set_text_static(label, "Text")`.
Labels are able to show text from a static character buffer. To do so, use `lv_label_set_text_static(label, "Text")`.
In this case, the text is not stored in the dynamic memory and the given buffer is used directly instead.
This means that the array can't be a local variable which goes out of scope when the function exits.
Constant strings are safe to use with `lv_label_set_text_static` (except when used with `LV_LABEL_LONG_DOT`, as it modifies the buffer in-place), as they are stored in ROM memory, which is always accessible.
### New line
### Line break
Line breaks are handled automatically by the label object. You can use `\n` to make a line break. For example: `"line1\nline2\n\nline4"`
New line characters are handled automatically by the label object. You can use `\n` to make a line break. For example: `"line1\nline2\n\nline4"`
### Long modes
By default, the width of the label object automatically expands to the text size. Otherwise, the text can be manipulated according to several long mode policies:
* **LV_LABEL_LONG_EXPAND** - Expand the object size to the text size (Default)
* **LV_LABEL_LONG_BREAK** - Keep the object width, break (wrap) the too long lines and expand the object height
* **LV_LABEL_LONG_DOT** - Keep the object size, break the text and write dots in the last line (**not supported when using `lv_label_set_text_static`**)
* **LV_LABEL_LONG_SROLL** - Keep the size and scroll the label back and forth
* **LV_LABEL_LONG_SROLL_CIRC** - Keep the size and scroll the label circularly
* **LV_LABEL_LONG_CROP** - Keep the size and crop the text out of it
By default, the width and height of the label is set to `LV_SIZE_CONTENT`therefore the size of the label is automatically expands to the text size.
Otherwise, if the width or height is explicitly set (useing e.g.`lv_obj_set_width` or a layout), the lines wider than the label's width can be manipulated according to several long mode policies.
Similary, the policies can be applied if the height of the text is greater than the height of the label.
- `LV_LABEL_LONG_WRAP` Wrap too long lines. If the height is `LV_SIZE_CONTENT` the label's height will be expanded, elst the text will be clipped. (Default)
- `LV_LABEL_LONG_DOT` Replaces the last 3 characters from bottom right corner of the label with dots (`.`)
- `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.
- `LV_LABEL_LONG_SCROLL_CIRCULAR` If the text is wider than the label scroll it horizontally continously. If it's higher, scroll vertically. Only one direction is scrolled and horizontal scrolling has higher precedence.
- `LV_LABEL_LONG_CLIP` Simply clip the parts of the text outside of the label.
You can specify the long mode with `lv_label_set_long_mode(label, LV_LABEL_LONG_...)`
It's important to note that, when a label is created and its text is set, the label's size already expanded to the text size.
In addition with the default `LV_LABEL_LONG_EXPAND`, *long mode* `lv_obj_set_width/height/size()` has no effect.
So you need to change the *long mode* first set the new *long mode* and then set the size with `lv_obj_set_width/height/size()`.
Another important note is that **`LV_LABEL_LONG_DOT` manipulates the text buffer in-place** in order to add/remove the dots.
Note that `LV_LABEL_LONG_DOT` manipulates the text buffer in-place in order to add/remove the dots.
When `lv_label_set_text` or `lv_label_set_array_text` are used, a separate buffer is allocated and this implementation detail is unnoticed.
This is not the case with `lv_label_set_text_static`! **The buffer you pass to `lv_label_set_text_static` must be writable if you plan to use `LV_LABEL_LONG_DOT`.**
### Text align
The lines of the text can be aligned to the left, right or center with `lv_label_set_align(label, LV_LABEL_ALIGN_LEFT/RIGHT/CENTER)`. Note that, it will align only the lines, not the label object itself.
Vertical alignment is not supported by the label itself; you should place the label inside a larger container and align the whole label object instead.
This is not the case with `lv_label_set_text_static`. The buffer you pass to `lv_label_set_text_static` must be writable if you plan to use `LV_LABEL_LONG_DOT`.
### Text recolor
In the text, you can use commands to recolor parts of the text. For example: `"Write a #ff0000 red# word"`.
This feature can be enabled individually for each label by `lv_label_set_recolor()` function.
Note that, recoloring work only in a single line. Therefore, `\n` should not use in a recolored text or it should be wrapped by `LV_LABEL_LONG_BREAK` else, the text in the new line won't be recolored.
### Very long texts
Lvgl can efficiently handle very long (> 40k characters) 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*.
LVGL can efficiently handle very long (e.g. > 40k characters) 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`.
### Symbols
The labels can display symbols alongside letters (or on their own). Read the [Font](/overview/font) section to learn more about the symbols.
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
No special event's are send by the Label.
Learn more about [Events](/overview/event).
@ -85,7 +68,7 @@ Learn more about [Keys](/overview/indev).
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_label/index.rst
.. include:: ../../../examples/widgets/label/index.rst
```

7
docs/widgets/core/line.md
View File

@ -8,7 +8,7 @@
The Line object is capable of drawing straight lines between a set of points.
## Parts and Styles
The Line has only a main part, called `LV_LABEL_PART_MAIN`. It uses all the *line* style properties.
- `LV_PART_MAIN` It uses all the typical backgrund properties and the line style properties.
## Usage
@ -16,7 +16,8 @@ The Line has only a main part, called `LV_LABEL_PART_MAIN`. It uses all the *lin
The points has to be stored in an `lv_point_t` array and passed to the object by the `lv_line_set_points(lines, point_array, point_cnt)` function.
### Auto-size
It is possible to automatically set the size of the line object according to its points.
By default the Line's width and height is set to `LV_SIZE_CONTENT` to automatically set its size to involve all the points.
If the size if set explicitly the point out of the object
It can be enable with the `lv_line_set_auto_size(line, true)` function.
If enabled then when the points are set the object's width and height will be changed according to the maximal x and y coordinates among the points. The *auto size* is enabled by default.
@ -38,7 +39,7 @@ Learn more about [Keys](/overview/indev).
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_line/index.rst
.. include:: ../../../examples/widgets/line/index.rst
```

32
examples/widgets/bar/index.rst
View File

@ -3,9 +3,39 @@ C
Simple Bar
""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_bar/lv_ex_bar_1
.. lv_example:: widgets/bar/lv_example_bar_1
:language: c
Styling a bar
""""""""""""""""
.. lv_example:: widgets/bar/lv_example_bar_2
:language: c
Temperature meter
""""""""""""""""""
.. lv_example:: widgets/bar/lv_example_bar_3
:language: c
Stripe pattern and range value
""""""""""""""""""""""""""""""""
.. lv_example:: widgets/bar/lv_example_bar_4
:language: c
Bar with RTL and RTL base direction
""""""""""""""""""""""""""""""""""""
.. lv_example:: widgets/bar/lv_example_bar_5
:language: c
Custom drawr to show the current value
"""""""""""""""""""""""""""""""""""""""
.. lv_example:: widgets/bar/lv_example_bar_6
:language: c
MicroPython
^^^^^^^^^^^

14
examples/widgets/btn/index.rst
View File

@ -4,10 +4,20 @@ C
Simple Buttons
""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_btn/lv_ex_btn_1
.. lv_example:: widgets/btn/lv_example_btn_1
:language: c
.. lv_example:: lv_ex_widgets/lv_ex_btn/lv_ex_btn_2
Styling buttons
""""""""""""""""
.. lv_example:: widgets/btn/lv_example_btn_2
:language: c
Gummy button
""""""""""""""""
.. lv_example:: widgets/btn/lv_example_btn_3
:language: c
MicroPython

16
examples/widgets/btnmatrix/index.rst
View File

@ -4,7 +4,21 @@ C
Simple Button matrix
""""""""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_btnmatrix/lv_ex_btnmatrix_1
.. lv_example:: widgets/btnmatrix/lv_example_btnmatrix_1
:language: c
Custom buttons
""""""""""""""""""""""
.. lv_example:: widgets/btnmatrix/lv_example_btnmatrix_1
:language: c
Pagination
""""""""""""""""""""""
.. lv_example:: widgets/btnmatrix/lv_example_btnmatrix_1
:language: c

2
examples/widgets/btnmatrix/lv_example_btnmatrix_2.c
View File

@ -60,7 +60,7 @@ static void event_cb(lv_event_t * e)
}
/**
* Add custom drawer to the button matrix to c
* Add custom drawer to the button matrix to customize butons one by one
*/
void lv_example_btnmatrix_2(void)
{

2
examples/widgets/btnmatrix/lv_example_btnmatrix_3.c
View File

@ -22,7 +22,7 @@ static void event_cb(lv_event_t * e)
}
/**
* Make a button group
* Make a button group (pagination)
*/
void lv_example_btnmatrix_3(void)
{

13
examples/widgets/calendar/index.rst Normal file
View File

@ -0,0 +1,13 @@
C
^
Calendar with header
""""""""""""""""""""""
.. lv_example:: widgets/calendar/lv_example_calendar_1
:language: c
MicroPython
^^^^^^^^^^^
No examples yet.

4
examples/widgets/canvas/index.rst
View File

@ -4,13 +4,13 @@ C
Drawing on the Canvas and rotate
""""""""""""""""""""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_canvas/lv_ex_canvas_1
.. lv_example:: widgets/canvas/lv_example_canvas_1
:language: c
Transparent Canvas with chroma keying
""""""""""""""""""""""""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_canvas/lv_ex_canvas_2
.. lv_example:: widgets/canvas/lv_example_canvas_2
:language: c
MicroPython

7
examples/widgets/checkbox/index.rst
View File

@ -1,9 +1,10 @@
C
^
Simple Checkbox
""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_checkbox/lv_ex_checkbox_1
Simple Checkboxes
"""""""""""""""""
.. lv_example:: widgets/checkbox/lv_example_checkbox_1
:language: c
MicroPython

15
examples/widgets/dropdown/index.rst
View File

@ -4,13 +4,20 @@ C
Simple Drop down list
""""""""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_dropdown/lv_ex_dropdown_1
.. lv_example:: widgets/dropdown/lv_example_dropdown_1
:language: c
Drop "up" list
""""""""""""""""""""""
Drop down in four directions
""""""""""""""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_dropdown/lv_ex_dropdown_2
.. lv_example:: widgets/dropdown/lv_example_dropdown_2
:language: c
Menu
""""""""""""
.. lv_example:: widgets/dropdown/lv_example_dropdown_3
:language: c
MicroPython

17
examples/widgets/img/index.rst
View File

@ -4,14 +4,27 @@ C
Image from variable and symbol
"""""""""""""""""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_img/lv_ex_img_1
.. lv_example:: widgets/img/lv_example_img_1
:language: c
Image recoloring
""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_img/lv_ex_img_2
.. lv_example:: widgets/img/lv_example_img_2
:language: c
Rotate and zoom
""""""""""""""""
.. lv_example:: widgets/img/lv_example_img_3
:language: c
Image offset and styling
""""""""""""""""""""""""
.. lv_example:: widgets/img/lv_example_img_4
:language: c

16
examples/widgets/label/index.rst
View File

@ -1,22 +1,16 @@
C
^
Line wrap, recoloring and scrolling
"""""""""""""""""""""""""""""""""""
Label recoloring and scrolling
"""""""""""""""""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_label/lv_ex_label_1
.. lv_example:: widgets/label/lv_example_label_1
:language: c
Text shadow
""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_label/lv_ex_label_2
:language: c
Align labels
""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_label/lv_ex_label_3
.. lv_example:: widgets/label/lv_example_label_2
:language: c
MicroPython

2
examples/widgets/line/index.rst
View File

@ -4,7 +4,7 @@ C
Simple Line
""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_line/lv_ex_line_1
.. lv_example:: widgets/line/lv_example_line_1
:language: c
MicroPython