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