Text area（文本框） (lv_textarea)

Overview（概述）

显示原文

The Text Area is a Base object with a 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.

文本框是一个基础对象，其上面有一个标签(Label) 和一个光标(cursor)。我们可以向文本框中添加文本或字符。长行会被换行，当文本内容变得足够长时(文本框可视区域容纳不下时)，可以滚动文本框。

支持单行输入模式和密码输入模式。

Parts and Styles（部分和样式）

显示原文

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.
LV_PART_SCROLLBAR The scrollbar that is shown when the text is too long.
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. The create line 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.

LV_PART_MAIN 文本框的背景。使用所有组件都有的典型的背景样式属性和与文本相关的样式属性（包括 text_align ）将文本向左、向右或居中对齐。
LV_PART_SCROLLBAR 文本内容过长时显示的滚动条。
LV_PART_SELECTED 确定选定文本 (label)的样式。只能使用 text_color 和 bg_color 样式属性。 bg_color 会直接应用在文本框的标签上。
LV_PART_CURSOR 字符插入位置的光标。光标的区域始终是当前字符的边界框。可以通过 anim_time 样式属性设置光标的闪烁时间。
LV_PART_TEXTAREA_PLACEHOLDER 文本占位符，文本框独有的部分。可以通过这部分设置文本占位符的样式。

Usage（用法）

Add text（添加文本）

显示原文

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")

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

lv_textarea_set_text(ta, "New text") changes the whole text.

您可以使用以下接口在光标的当前位置插入文本或字符：

lv_textarea_add_char(textarea, 'c')
lv_textarea_add_text(textarea, "insert this text")

要添加宽字符，如 'á', 'ß' 或 CJK 字符，请使用接口 lv_textarea_add_text(ta, "á")。

lv_textarea_set_text(ta, "New text") 会改变(清空再覆盖)文本框中的所有内容。

Placeholder（占位符）

显示原文

A placeholder text can be specified

which is displayed when the Text area is empty
with lv_textarea_set_placeholder_text(ta, "Placeholder text")

您可以通过接口 lv_textarea_set_placeholder_text(ta, "Placeholder text") 指定占位符文本，当文本框的内容为空时，所设置的占位符文本将会展示出来。

Delete character（删除字符）

显示原文

To delete a character from the left of the current cursor position use lv_textarea_delete_char(textarea).

To delete from the right use lv_textarea_delete_char_forward(textarea)

要删除光标左侧的字符，请使用 lv_textarea_delete_char(textarea)。

要从光标右侧删除字符，请使用 lv_textarea_delete_char_forward(textarea)。

Move the cursor（移动光标）

显示原文

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"

You can step the cursor 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.

光标的位置可以使用函数 lv_textarea_set_cursor_pos(textarea, 10) 直接修改。第二个参数为你要指定的光标的位置，要注意的是： 0 表示将光标移动到 “第一个字符之前”，LV_TEXTAREA_CURSOR_LAST 表示将光标移动到 “最后一个字符之后”

您可以使用下面这些接口函数修改光标位置：

lv_textarea_cursor_right(textarea) 上
lv_textarea_cursor_left(textarea) 下
lv_textarea_cursor_up(textarea) 左
lv_textarea_cursor_down(textarea) 右

如果设置了 lv_textarea_set_cursor_click_pos(textarea, true) 那光标会跟随触摸跳转位置(在文本框范围内)

Hide the cursor（隐藏光标）

显示原文

The cursor is always visible, however it can be a good idea to style it to be visible only in LV_STATE_FOCUSED state.

一般情况下光标始终可见，但最好将其样式设置为仅在 LV_STATE_FOCUSED 状态下(聚焦状态)可见。

One line mode（单行模式）

显示原文

The Text area can be configured to be 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.

可以使用 lv_textarea_set_one_line(textarea, true) 将文本框配置为单行输入模式。在这个模式下，高度自动设置为仅显示一行，忽略换行符，并禁用自动换行。

Password mode（密码模式）

显示原文

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 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").

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.

文本框支持密码模式，可以通过 lv_textarea_set_password_mode(textarea, true).启用该模式。

如果字体中存在 • (Bullet,U+2022)字符，则将输入的字符会在一定时间后或者输入新字符时自动转换为该字符。如果 • 不存在， * 将被使用。您可以覆盖字符带有 lv_textarea_set_password_bullet（textarea，“x”）的默认值。

在密码模式下 lv_textarea_get_text(textarea) 返回的是输入的实际文本，而不是 • 字符。

密码模式下，实际输入文本的可见时间可以通过 lv_conf.h 中的 LV_TEXTAREA_DEF_PWD_SHOW_TIME 进行调整。

Accepted characters（字符白名单）

显示原文

You can set a list of accepted characters with lv_textarea_set_accepted_chars(textarea, "0123456789.+-"). Other characters will be ignored.

您可以使用 lv_textarea_set_accepted_chars(textarea, "0123456789.+-") 设置可接受字符列表(白名单)。输入其他字符将被忽略。

Max text length（设置文本长度）

显示原文

The maximum number of characters can be limited with lv_textarea_set_max_length(textarea, max_char_num)

可以使用 lv_textarea_set_max_length(textarea, max_char_num) 设置文本框可容纳的最大字符数

Very long texts（超长文本）

显示原文

If there is a very long text in the Text area (e.g. > 20k characters), scrolling and drawing might be slow. However, by enabling LV_LABEL_LONG_TXT_HINT in lv_conf.h the performance can be hugely improved. This will save some additional 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.

如果文本框中有很长的文本（例如 > 20k 个字符），可能会导致滚动和绘制速度很慢。但是，如果在 lv_conf.h 中启用 LV_LABEL_LONG_TXT_HINT 那么这个问题可以得到很好的改善。这将会保存有关标签(label)的一些附加信息以加快其绘制速度。使用 LV_LABEL_LONG_TXT_HINT 后，其滚动和绘制速度将与 “普通” 的短文本一样快。

Select text（选择文本）

显示原文

Any part of the text can be selected if enabled with lv_textarea_set_text_selection(textarea, true). This works much like when you select text on your PC with your mouse.

如果使用函数 lv_textarea_set_text_selection(textarea, true) 启用文本选择功能，则可以选择文本的任何部分。这和我们使用鼠标在电脑上选择文字非常相似。

Events（事件）

显示原文

LV_EVENT_INSERT Sent right before a character or text is inserted. The event parameter is the text about to be inserted. lv_textarea_set_insert_replace(textarea, "New text") replaces the text to insert. The new text cannot 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_READY Sent when LV_KEY_ENTER is pressed (or sent) to a one line text area.

See the events of the Base object too.

Learn more about Events（事件）.

LV_EVENT_INSERT 在插入字符或文本之前发送该事件。事件参数是即将插入的文本。可以通过接口 lv_textarea_set_insert_replace(textarea, "New text") 将要计划插入的文本替换为其他文本。注意替换的新文本不能是局部变量，也就是不能在回调函数中直接创建局部变量保存新文本。 "" 表示不插入任何内容。
LV_EVENT_VALUE_CHANGED 当文本框的内容被改变时发送该事件。
LV_EVENT_READY 在按下 LV_KEY_ENTER 按键时发送到单行文本框。

参见 Base object 的事件。

详细了解更多 Events（事件）。

Keys（按键）

显示原文

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

Learn more about Keys（按键）.

LV_KEY_UP/DOWN/LEFT/RIGHT 移动光标
任意字符 将字符添加到当前光标位置

了解有关 Keys（按键）的更多信息。

Example

[English]

Simple Text area

#include "../../lv_examples.h"
#if LV_USE_TEXTAREA && LV_BUILD_EXAMPLES

static void textarea_event_handler(lv_event_t * e)
{
    lv_obj_t * ta = lv_event_get_target(e);
    LV_UNUSED(ta);
    LV_LOG_USER("Enter was pressed. The current text is: %s", lv_textarea_get_text(ta));
}

static void btnm_event_handler(lv_event_t * e)
{
    lv_obj_t * obj = lv_event_get_target(e);
    lv_obj_t * ta = lv_event_get_user_data(e);
    const char * txt = lv_buttonmatrix_get_button_text(obj, lv_buttonmatrix_get_selected_button(obj));

    if(lv_strcmp(txt, LV_SYMBOL_BACKSPACE) == 0) lv_textarea_delete_char(ta);
    else if(lv_strcmp(txt, LV_SYMBOL_NEW_LINE) == 0) lv_obj_send_event(ta, LV_EVENT_READY, NULL);
    else lv_textarea_add_text(ta, txt);

}

void lv_example_textarea_1(void)
{
    lv_obj_t * ta = lv_textarea_create(lv_screen_active());
    lv_textarea_set_one_line(ta, true);
    lv_obj_align(ta, LV_ALIGN_TOP_MID, 0, 10);
    lv_obj_add_event_cb(ta, textarea_event_handler, LV_EVENT_READY, ta);
    lv_obj_add_state(ta, LV_STATE_FOCUSED); /*To be sure the cursor is visible*/

    static const char * btnm_map[] = {"1", "2", "3", "\n",
                                      "4", "5", "6", "\n",
                                      "7", "8", "9", "\n",
                                      LV_SYMBOL_BACKSPACE, "0", LV_SYMBOL_NEW_LINE, ""
                                     };

    lv_obj_t * btnm = lv_buttonmatrix_create(lv_screen_active());
    lv_obj_set_size(btnm, 200, 150);
    lv_obj_align(btnm, LV_ALIGN_BOTTOM_MID, 0, -10);
    lv_obj_add_event_cb(btnm, btnm_event_handler, LV_EVENT_VALUE_CHANGED, ta);
    lv_obj_remove_flag(btnm, LV_OBJ_FLAG_CLICK_FOCUSABLE); /*To keep the text area focused on button clicks*/
    lv_buttonmatrix_set_map(btnm, btnm_map);
}

#endif

Text area with password field

#include "../../lv_examples.h"
#if LV_USE_TEXTAREA && LV_USE_KEYBOARD && LV_BUILD_EXAMPLES

static void ta_event_cb(lv_event_t * e);

static lv_obj_t * kb;

void lv_example_textarea_2(void)
{
    /*Create the password box*/
    lv_obj_t * pwd_ta = lv_textarea_create(lv_screen_active());
    lv_textarea_set_text(pwd_ta, "");
    lv_textarea_set_password_mode(pwd_ta, true);
    lv_textarea_set_one_line(pwd_ta, true);
    lv_obj_set_width(pwd_ta, lv_pct(40));
    lv_obj_set_pos(pwd_ta, 5, 20);
    lv_obj_add_event_cb(pwd_ta, ta_event_cb, LV_EVENT_ALL, NULL);

    /*Create a label and position it above the text box*/
    lv_obj_t * pwd_label = lv_label_create(lv_screen_active());
    lv_label_set_text(pwd_label, "Password:");
    lv_obj_align_to(pwd_label, pwd_ta, LV_ALIGN_OUT_TOP_LEFT, 0, 0);

    /*Create the one-line mode text area*/
    lv_obj_t * text_ta = lv_textarea_create(lv_screen_active());
    lv_textarea_set_one_line(text_ta, true);
    lv_textarea_set_password_mode(text_ta, false);
    lv_obj_set_width(text_ta, lv_pct(40));
    lv_obj_add_event_cb(text_ta, ta_event_cb, LV_EVENT_ALL, NULL);
    lv_obj_align(text_ta, LV_ALIGN_TOP_RIGHT, -5, 20);

    /*Create a label and position it above the text box*/
    lv_obj_t * oneline_label = lv_label_create(lv_screen_active());
    lv_label_set_text(oneline_label, "Text:");
    lv_obj_align_to(oneline_label, text_ta, LV_ALIGN_OUT_TOP_LEFT, 0, 0);

    /*Create a keyboard*/
    kb = lv_keyboard_create(lv_screen_active());
    lv_obj_set_size(kb,  LV_HOR_RES, LV_VER_RES / 2);

    lv_keyboard_set_textarea(kb, pwd_ta); /*Focus it on one of the text areas to start*/

    /*The keyboard will show Arabic characters if they are enabled */
#if LV_USE_ARABIC_PERSIAN_CHARS && LV_FONT_DEJAVU_16_PERSIAN_HEBREW
    lv_obj_set_style_text_font(kb, &lv_font_dejavu_16_persian_hebrew, 0);
    lv_obj_set_style_text_font(text_ta, &lv_font_dejavu_16_persian_hebrew, 0);
    lv_obj_set_style_text_font(pwd_ta, &lv_font_dejavu_16_persian_hebrew, 0);
#endif

}

static void ta_event_cb(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * ta = lv_event_get_target(e);
    if(code == LV_EVENT_CLICKED || code == LV_EVENT_FOCUSED) {
        /*Focus on the clicked text area*/
        if(kb != NULL) lv_keyboard_set_textarea(kb, ta);
    }

    else if(code == LV_EVENT_READY) {
        LV_LOG_USER("Ready, current text: %s", lv_textarea_get_text(ta));
    }
}

#endif

Text auto-formatting

#include "../../lv_examples.h"
#if LV_USE_TEXTAREA && LV_USE_KEYBOARD && LV_BUILD_EXAMPLES

static void ta_event_cb(lv_event_t * e);

static lv_obj_t * kb;

/**
 * Automatically format text like a clock. E.g. "12:34"
 * Add the ':' automatically.
 */
void lv_example_textarea_3(void)
{
    /*Create the text area*/
    lv_obj_t * ta = lv_textarea_create(lv_screen_active());
    lv_obj_add_event_cb(ta, ta_event_cb, LV_EVENT_VALUE_CHANGED, NULL);
    lv_textarea_set_accepted_chars(ta, "0123456789:");
    lv_textarea_set_max_length(ta, 5);
    lv_textarea_set_one_line(ta, true);
    lv_textarea_set_text(ta, "");

    /*Create a keyboard*/
    kb = lv_keyboard_create(lv_screen_active());
    lv_obj_set_size(kb,  LV_HOR_RES, LV_VER_RES / 2);
    lv_keyboard_set_mode(kb, LV_KEYBOARD_MODE_NUMBER);
    lv_keyboard_set_textarea(kb, ta);
}

static void ta_event_cb(lv_event_t * e)
{
    lv_obj_t * ta = lv_event_get_target(e);
    const char * txt = lv_textarea_get_text(ta);
    if(txt[0] >= '0' && txt[0] <= '9' &&
       txt[1] >= '0' && txt[1] <= '9' &&
       txt[2] != ':') {
        lv_textarea_set_cursor_pos(ta, 2);
        lv_textarea_add_char(ta, ':');
    }
}

#endif

API

lv_textarea.h

lv_types.h