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

docs finish the the core widgets

Browse Source
This commit is contained in:
Gabor Kiss-Vamosi
2021-05-13 15:39:26 +02:00
parent 6aa27cc11b
commit 1ed42a937f
7 changed files with 62 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -8,7 +8,9 @@
A label is the basic object type that is used to display text.
## Parts and Styles
- `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.
- `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.
- `LV_PART_SCROLLBAR` The scrollbar that is shown when the text is larger than the widget's size.
- `LV_PART_SELECTED` Tells the style of the [selected text](#text-selection). Only `text_color` and `bg_color` style properties can be used.
## Usage
@@ -48,6 +50,11 @@ This is not the case with `lv_label_set_text_static`. The buffer you pass to `lv
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.
### Text selection
If enabled by `LV_LABEL_TEXT_SELECTION` part of the text can be selected. It's similar when on PC a you use your mouse to select a text.
The whole mechanzim (click and select the text as you drag your finger/mouse) is implemeted in [Text area](/widgets/core/textarea) and the Label widget allows only to manually make parts of the text selected with
`lv_label_get_text_selection_start(label, start_char_index)` and `lv_label_get_text_selection_start(label, end_char_index)`.
### Very long texts
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`.

78
docs/widgets/core/textarea.md
View File

@@ -6,26 +6,26 @@
## Overview
The Text Area is a Page with a [Label](/widgets/core/label) and a cursor on it.
The Text Area is a [Base object](widgets/obj) with a [Label](/widgets/core/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.
## Parts and Styles
The Text area has the same parts as Page.
Expect `LV_PAGE_PART_SCRL` because it can't be referenced and it's always transparent.
Refer the Page's documentation of details.
Besides the Page parts the virtual `LV_TEXTAREA_PART_CURSOR` part exists to draw the cursor.
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 opa to `LV_TEXTAREA_PART_CURSOR`'s style.
The create line cursor let the cursor transparent and set the *border_side* property.
- `LV_PART_MAIN` The background of the text area and it uses all the typical backgrond style properties and the text related style properties including `text_align` to align the text to the left, right or center.
- `LV_PART_SCROLLBAR` The scrollbar that is shown when the text is too long.
- `LV_PART_SELECTED` Tells the style of the [selected text](#text-selection). Only `text_color` and `bg_color` style properties can be used.
- `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 `LV_PART_CURSOR`'s style. The create line cursor let the cursor transparent and set a left border.
The `anim_time` style property sets the cursors blink time.
- `LV_PART_TEXTAREA_PLACEHOLDER` It's a part related only to the text area and allows styling the placeholder text.
## Usage
### Add text
You can insert text or characters to the current cursor's position with:
You can insert text or characters to the current cursor's position with:
- `lv_textarea_add_char(textarea, 'c')`
- `lv_textarea_add_text(textarea, "insert this text")`
@@ -45,7 +45,7 @@ To delete from the right use `lv_textarea_del_char_forward(textarea)`
### Move the cursor
The cursor position can be modified directly with `lv_textarea_set_cursor_pos(textarea, 10)`.
The cursor position can be modified directly like `lv_textarea_set_cursor_pos(textarea, 10)`.
The `0` position means "before the first characters",
`LV_TA_CURSOR_LAST` means "after the last character"
@@ -55,36 +55,27 @@ You can step the cursor with
- `lv_textarea_cursor_up(textarea)`
- `lv_textarea_cursor_down(textarea)`
If `lv_textarea_set_cursor_click_pos(textarea, true)` is called the cursor will jump to the position where the Text area was clicked.
If `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 can be hidden with `lv_textarea_set_cursor_hidden(textarea, true)`.
### Cursor blink time
The blink time of the cursor can be adjusted with `lv_textarea_set_cursor_blink_time(textarea, time_ms)`.
The cursor is always visible, hiwever it can be good idea to style to be visible only in `LV_STATE_FOCUSED` state.
### One line mode
The Text area can be configures to be one lined with `lv_textarea_set_one_line(ta, true)`.
The Text area can be configures to be one lined with `lv_textarea_set_one_line(textarea, true)`.
In this mode the height is set automatically to show only one line, line break character are ignored, and word wrap is disabled.
### Password mode
The text area supports password mode which can be enabled with `lv_textarea_set_pwd_mode(textarea, true)`.
The text area supports password mode which can be enabled with `lv_textarea_set_password_mode(textarea, true)`.
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 `•` not exists, `*` will be used.
In password mode `lv_textarea_get_text(textarea)` gives the real text, not the bullet characters.
The visibility time can be adjusted with `lv_textarea_set_pwd_show_time(textarea, time_ms)`.
### Text align
The text can be aligned to the left, center or right with `lv_textarea_set_text_align(textarea, LV_LABEL_ALIGN_LET/CENTER/RIGHT)`.
In one line mode, the text can be scrolled horizontally only if the text is left aligned.
The visibility time can be adjusted with `LV_TEXTAREA_DEF_PWD_SHOW_TIME)` in `lv_conf.h`.
### Accepted characters
You can set a list of accepted characters with `lv_textarae_set_accepted_chars(ta, "0123456789.+-")`.
You can set a list of accepted characters with `lv_textarae_set_accepted_chars(textarea, "0123456789.+-")`.
Other characters will be ignored.
### Max text length
@@ -92,35 +83,26 @@ The maximum number of characters can be limited with `lv_textarea_set_max_length
### Very long texts
If there is a very long text in the Text area (e. g. > 20k characters) its scrolling and drawing might be slow.
However, by enabling `LV_LABEL_LONG_TXT_HINT 1` in *lv_conf.h* it can be hugely improved.
It will save some info about the label to speed up its drawing.
However, by enabling `LV_LABEL_LONG_TXT_HINT 1` in `lv_conf.h` the performance can be hugely improved.
It will save some information about the label to speed up its drawing.
Using `LV_LABEL_LONG_TXT_HINT` the scrolling and drawing will as fast as with "normal" short texts.
### Select text
A part of text can be selected if enabled with `lv_textarea_set_text_sel(textarea, true)`.
A part of text can be selected if enabled with `lv_textarea_set_text_selection(textarea, true)`.
It works like when you select a text on your PC with your mouse.
### Scroll propagation
When the Text area is scrolled on an other scrollable object (like a Page) and the scrolling has reached the edge of the Text area, the scrolling can be propagated to the parent.
In other words, when the Text area can be scrolled further, the parent will be scrolled instead.
It can be enabled with `lv_ta_set_scroll_propagation(ta, true)`.
### Edge flash
When the Text area is scrolled to edge a circle like flash animation can be shown if it is enabled with `lv_ta_set_edge_flash(ta, true)`
## Events
Besides the [Generic events](../overview/event.html#generic-events) the following [Special events](../overview/event.html#special-events) are sent by the Slider:
- **LV_EVENT_INSERT** Sent when before a character or text is inserted.
The event data is the text planned to insert. `lv_ta_set_insert_replace(ta, "New text")` replaces the text to insert.
The new text can't be in a local variable which is destroyed when the event callback exists. `""` means do not insert anything.
- **LV_EVENT_VALUE_CHANGED** When the content of the text area has been changed.
- **LV_EVENT_APPLY** When LV_KEY_ENTER is sent to a text area which is in one line mode.
- `LV_EVENT_INSERT` Sent when before a character or text is inserted.
The event paramter is the text planned to be inserted. `lv_textarea_set_insert_replace(textarea, "New text")` replaces the text to insert.
The new text can not be in a local variable which is destroyed when the event callback exists. `""` means do not insert anything.
- `LV_EVENT_VALUE_CHANGED` Sent when the content of the text area has been changed.
- `LV_EVENT_APPLY` Sent when `LV_KEY_ENTER` is pressed (or(sent) to a one line text area.
Learn more about [Events](/overview/event).
## Keys
- **LV_KEY_UP/DOWN/LEFT/RIGHT** Move the cursor
- **Any character** Add the character to the current cursor position
- `LV_KEY_UP/DOWN/LEFT/RIGHT` Move the cursor
- `Any character` Add the character to the current cursor position
Learn more about [Keys](/overview/indev).