Text Area (lv_textarea)

Editable text field with a cursor. Supports wrapping, scrolling, one-line and password modes.

Overview

A Text Area is a base widget holding a Label and a cursor. You can add or remove text and characters. Long lines wrap, and when the text gets too long the area becomes scrollable.

One-line mode and password mode are also supported.

Adding text

lv_example_textarea_buttonmatrix.c

You can insert text or characters to the current cursor's position with:

To add wide characters like 'á', 'ß' or CJK characters, use lv_textarea_add_text(textarea, "á").

lv_textarea_set_text(textarea, "New text") replaces all existing text with "New text".

Placeholder text

lv_example_textarea_placeholder.c

Placeholder text is text that is displayed when the Text Area is empty. This can be a handy way to provide the end user with a hint about what to type there.

Specify placeholder text using lv_textarea_set_placeholder_text(textarea, "Placeholder text").

Delete character

To delete the character to the left of the current cursor position, use lv_textarea_delete_char(textarea).

To delete to the right, use lv_textarea_delete_char_forward(textarea)

The cursor position can be modified programmatically using lv_textarea_set_cursor_pos(textarea, cursor_pos) where cursor_pos is the zero-based index of the character the cursor should be placed in front of. LV_TEXTAREA_CURSOR_LAST can be passed to mean "after the last character"

You can move the cursor one character-position (or line) at a time with

If lv_textarea_set_cursor_click_pos(textarea, true) is applied, the cursor will jump to the position where the Text Area was clicked.

Hiding the cursor

The cursor is normally always visible. It can be a good idea to style it to be visible only in LV_STATE_FOCUSED state. See Styles for more information about how to do this.

One-line mode

The Text Area can be configured to keep all text on a single line with lv_textarea_set_one_line(textarea, true). In this mode:

the height is set automatically to show only one line,
line break characters are ignored, and
word wrap is disabled.

Password mode

lv_example_textarea_password.c

The Text Area supports password mode which can be enabled with lv_textarea_set_password_mode(textarea, true).

By default, if the • (Bullet, U+2022) character exists in the font, the entered characters are converted to it after a configurable delay after each new character is entered. If • does not exist in the font, * will be used. You can override the default "masking" character with lv_textarea_set_password_bullet(textarea, str) where str is a NUL-terminated C string. Example:

lv_textarea_set_password_bullet(textarea, "x");

In password mode lv_textarea_get_text(textarea) returns the actual text entered, not the bullet characters.

The visibility time can be adjusted with LV_TEXTAREA_DEF_PWD_SHOW_TIME in lv_conf.h.

Accepted characters

lv_example_textarea_format.c

You can set a list of accepted characters with lv_textarea_set_accepted_chars(textarea, list) or lv_textarea_set_accepted_chars_static(textarea, list) where list is a pointer to a NUL-terminated string, or NULL to accept all characters. Characters entered not in this list will be ignored.

lv_textarea_set_accepted_chars(textarea, "0123456789.+-");

lv_textarea_get_text_selection(textarea) — whether selection is enabled.
lv_textarea_text_is_selected(textarea) — whether text is currently selected.
lv_textarea_clear_selection(textarea) — clears the selection.
lv_label_set_text_selection_start(ta_label, index) — start index; pass LV_DRAW_LABEL_NO_TXT_SEL for none.
lv_label_set_text_selection_end(ta_label, index) — end index (exclusive); pass LV_DRAW_LABEL_NO_TXT_SEL for none.
lv_label_get_text_selection_start(ta_label) — gets start index.
lv_label_get_text_selection_end(ta_label) — gets end index.

Styling

lv_example_textarea_cursor.c

The Text Area exposes these parts, each styled independently with a named style and a selector:

LV_PART_MAIN The background of the Text Area; uses the typical background 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 longer than its height.
LV_PART_SELECTED Determines the style of the selected text. Only text_color and bg_color style properties can be used. bg_color should be set directly on the label of the Text Area.
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. To create a "bar" cursor leave the cursor transparent and set a left border. The anim_time style property sets the cursor's blink time.
LV_PART_TEXTAREA_PLACEHOLDER Unique to Text Area; allows styling the placeholder text.

Events

LV_EVENT_INSERT Sent just before a character or text is inserted. The event parameter is the text about to be inserted. From the handler you can call lv_textarea_set_insert_replace(textarea, "New text") to replace it, or pass "" to skip the insertion. The buffer must stay valid until the current lv_timer_handler() call returns — don't pass a stack-allocated string.
LV_EVENT_VALUE_CHANGED Sent when the content of the Text Area has changed.
LV_EVENT_READY Sent when LV_KEY_ENTER is pressed (or sent) to a one-line Text Area.

Learn more about Events emitted by all Widgets.

Keys

LV_KEY_UP/DOWN/LEFT/RIGHT Move the cursor
Any character Add the character to the current cursor position

Learn more about Keys.