acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware

git clone git://git.acid.vegas/acid-drop.git

textarea.md (5550B)

1 ```eval_rst
2 .. include:: /header.rst
3 :github_url: |github_link_base|/widgets/core/textarea.md
4 ```
5 # Text area (lv_textarea)
6
7 ## Overview
8
9 The Text Area is a [Base object](widgets/obj) with a [Label](/widgets/core/label) and a cursor on it.
10 Texts or characters can be added to it.
11 Long lines are wrapped and when the text becomes long enough the Text area can be scrolled.
12
13 One line mode and password modes are supported.
14
15 ## Parts and Styles
16 - `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.
17 - `LV_PART_SCROLLBAR` The scrollbar that is shown when the text is too long.
18 - `LV_PART_SELECTED` Determines the style of the [selected text](/widgets/core/label.html#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.
19 - `LV_PART_CURSOR` Marks the position where the characters are inserted. The cursor's area is always the bounding box of the current character.
20 A block cursor can be created by adding a background color and background opacity to `LV_PART_CURSOR`'s style. The create line cursor leave the cursor transparent and set a left border.
21 The `anim_time` style property sets the cursor's blink time.
22 - `LV_PART_TEXTAREA_PLACEHOLDER` Unique to Text Area, allows styling the placeholder text.
23
24 ## Usage
25
26 ### Add text
27
28 You can insert text or characters to the current cursor's position with:
29
30 - `lv_textarea_add_char(textarea, 'c')`
31 - `lv_textarea_add_text(textarea, "insert this text")`
32
33 To add wide characters like `'á'`, `'ß'` or CJK characters use `lv_textarea_add_text(ta, "á")`.
34
35 `lv_textarea_set_text(ta, "New text")` changes the whole text.
36
37 ### Placeholder
38
39 A placeholder text can be specified - which is displayed when the Text area is empty - with `lv_textarea_set_placeholder_text(ta, "Placeholder text")`
40
41 ### Delete character
42
43 To delete a character from the left of the current cursor position use `lv_textarea_del_char(textarea)`.
44 To delete from the right use `lv_textarea_del_char_forward(textarea)`
45
46 ### Move the cursor
47
48 The cursor position can be modified directly like `lv_textarea_set_cursor_pos(textarea, 10)`.
49 The `0` position means "before the first characters",
50 `LV_TA_CURSOR_LAST` means "after the last character"
51
52 You can step the cursor with
53 - `lv_textarea_cursor_right(textarea)`
54 - `lv_textarea_cursor_left(textarea)`
55 - `lv_textarea_cursor_up(textarea)`
56 - `lv_textarea_cursor_down(textarea)`
57
58 If `lv_textarea_set_cursor_click_pos(textarea, true)` is applied the cursor will jump to the position where the Text area was clicked.
59
60 ### Hide the cursor
61 The cursor is always visible, however it can be a good idea to style it to be visible only in `LV_STATE_FOCUSED` state.
62
63 ### One line mode
64 The Text area can be configured to be on a single line with `lv_textarea_set_one_line(textarea, true)`.
65 In this mode the height is set automatically to show only one line, line break characters are ignored, and word wrap is disabled.
66
67 ### Password mode
68 The text area supports password mode which can be enabled with `lv_textarea_set_password_mode(textarea, true)`.
69
70 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.
71 If `•` not exists, `*` will be used.
72
73 In password mode `lv_textarea_get_text(textarea)` returns the actual text entered, not the bullet characters.
74
75 The visibility time can be adjusted with `LV_TEXTAREA_DEF_PWD_SHOW_TIME)` in `lv_conf.h`.
76
77 ### Accepted characters
78 You can set a list of accepted characters with `lv_textarea_set_accepted_chars(textarea, "0123456789.+-")`.
79 Other characters will be ignored.
80
81 ### Max text length
82 The maximum number of characters can be limited with `lv_textarea_set_max_length(textarea, max_char_num)`
83
84
85 ### Very long texts
86 If there is a very long text in the Text area (e.g. > 20k characters), scrolling and drawing might be slow.
87 However, by enabling `LV_LABEL_LONG_TXT_HINT 1` in `lv_conf.h` the performance can be hugely improved.
88 This will save some additional information about the label to speed up its drawing.
89 Using `LV_LABEL_LONG_TXT_HINT` the scrolling and drawing will as fast as with "normal" short texts.
90
91 ### Select text
92 Any part of the text can be selected if enabled with `lv_textarea_set_text_selection(textarea, true)`.
93 This works much like when you select text on your PC with your mouse.
94
95 ## Events
96 - `LV_EVENT_INSERT` Sent right before a character or text is inserted.
97 The event parameter is the text about to be inserted. `lv_textarea_set_insert_replace(textarea, "New text")` replaces the text to insert.
98 The new text cannot be in a local variable which is destroyed when the event callback exists. `""` means do not insert anything.
99 - `LV_EVENT_VALUE_CHANGED` Sent when the content of the text area has been changed.
100 - `LV_EVENT_READY` Sent when `LV_KEY_ENTER` is pressed (or sent) to a one line text area.
101
102 See the events of the [Base object](/widgets/obj) too.
103
104 Learn more about [Events](/overview/event).
105
106 ## Keys
107 - `LV_KEY_UP/DOWN/LEFT/RIGHT` Move the cursor
108 - `Any character` Add the character to the current cursor position
109
110 Learn more about [Keys](/overview/indev).
111
112 ## Example
113
114 ```eval_rst
115
116 .. include:: ../../../examples/widgets/textarea/index.rst
117
118 ```
119
120 ## API
121
122 ```eval_rst
123
124 .. doxygenfile:: lv_textarea.h
125 :project: lvgl
126
127 ```