文本区域 (lv_textarea)

概述

文本区域是一个带有标签和光标的基础对象。 可以向其添加文本或字符。 长行会自动换行，当文本足够长时，文本区域可以滚动。

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

部件和样式

• LV_PART_MAIN 文本区域的背景。使用所有典型的背景样式属性以及与文本相关的样式属性，包括 text_align 用于将文本对齐到左侧、右侧或居中。

• LV_PART_SCROLLBAR 当文本过长时显示的滚动条。

• LV_PART_SELECTED 决定选中文本的样式。仅支持 text_color 和 bg_color 样式属性。bg_color 应直接设置在文本区域的标签上。

• LV_PART_CURSOR 标记字符插入的位置。光标的区域始终是当前字符的边界框。 可以通过为 LV_PART_CURSOR 的样式添加背景颜色和背景不透明度来创建块光标。创建线光标时，将光标设置为透明并设置左边框。 anim_time 样式属性设置光标的闪烁时间。

• LV_PART_TEXTAREA_PLACEHOLDER 文本区域独有，允许设置占位符文本的样式。

用法

添加文本

可以通过以下方式在当前光标位置插入文本或字符：

• lv_textarea_add_char(textarea, 'c')

• lv_textarea_add_text(textarea, "插入此文本")

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

lv_textarea_set_text(ta, "新文本") 会更改整个文本。

占位符

可以通过 lv_textarea_set_placeholder_text(ta, "占位符文本") 指定占位符文本，当文本区域为空时显示。

删除字符

使用 lv_textarea_del_char(textarea) 删除当前光标位置左侧的字符。 使用 lv_textarea_del_char_forward(textarea) 删除右侧的字符。

移动光标

可以直接修改光标位置，例如 lv_textarea_set_cursor_pos(textarea, 10)。 位置 0 表示“第一个字符之前”，LV_TA_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)，光标会跳转到点击文本区域的位置。

隐藏光标

光标始终可见，但可以通过样式设置仅在 LV_STATE_FOCUSED 状态下可见。

单行模式

可以通过 lv_textarea_set_one_line(textarea, true) 将文本区域配置为单行模式。 在此模式下，高度会自动设置为仅显示一行，换行符会被忽略，且禁用单词换行。

密码模式

文本区域支持密码模式，可以通过 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 调整显示时间。

接受的字符

可以通过 lv_textarea_set_accepted_chars(textarea, "0123456789.+-") 设置接受的字符列表。 其他字符将被忽略。

最大文本长度

可以通过 lv_textarea_set_max_length(textarea, max_char_num) 限制最大字符数。

超长文本

如果文本区域中有非常长的文本（例如 > 20k 字符），滚动和绘制可能会变慢。 但是，通过在 lv_conf.h 中启用 LV_LABEL_LONG_TXT_HINT   1，性能可以大幅提升。 这会保存一些额外的信息以加速标签的绘制。 启用 LV_LABEL_LONG_TXT_HINT 后，滚动和绘制速度与“普通”短文本一样快。

选择文本

如果通过 lv_textarea_set_text_selection(textarea, true) 启用，可以选择文本的任意部分。 这类似于在 PC 上用鼠标选择文本。

事件

• LV_EVENT_INSERT 在插入字符或文本之前发送。 事件参数是即将插入的文本。lv_textarea_set_insert_replace(textarea, "新文本") 替换要插入的文本。 新文本不能是事件回调退出时销毁的局部变量。"" 表示不插入任何内容。

• LV_EVENT_VALUE_CHANGED 当文本区域的内容发生更改时发送。

• LV_EVENT_READY 当对单行文本区域按下（或发送）LV_KEY_ENTER 时发送。

请参阅基础对象的事件。

了解更多关于事件的信息。

按键

• LV_KEY_UP/DOWN/LEFT/RIGHT 移动光标

• 任意字符 将字符添加到当前光标位置

了解更多关于按键的信息。

示例

Simple Text area

C code  

 GitHub

#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_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_btnmatrix_get_btn_text(obj, lv_btnmatrix_get_selected_btn(obj));

    if(strcmp(txt, LV_SYMBOL_BACKSPACE) == 0) lv_textarea_del_char(ta);
    else if(strcmp(txt, LV_SYMBOL_NEW_LINE) == 0) lv_event_send(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_scr_act());
    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_btnmatrix_create(lv_scr_act());
    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_clear_flag(btnm, LV_OBJ_FLAG_CLICK_FOCUSABLE); /*To keep the text area focused on button clicks*/
    lv_btnmatrix_set_map(btnm, btnm_map);
}

#endif

MicroPython code  

 GitHub Simulator

def textarea_event_handler(e, ta):
    print("Enter was pressed. The current text is: " + ta.get_text())


def btnm_event_handler(e, ta):
    obj = e.get_target()
    txt = obj.get_btn_text(obj.get_selected_btn())
    if txt == lv.SYMBOL.BACKSPACE:
        ta.del_char()
    elif txt == lv.SYMBOL.NEW_LINE:
        lv.event_send(ta, lv.EVENT.READY, None)
    elif txt:
        ta.add_text(txt)


ta = lv.textarea(lv.scr_act())
ta.set_one_line(True)
ta.align(lv.ALIGN.TOP_MID, 0, 10)
ta.add_event_cb(lambda e: textarea_event_handler(e, ta), lv.EVENT.READY, None)
ta.add_state(lv.STATE.FOCUSED)   # To be sure the cursor is visible

btnm_map = ["1", "2", "3", "\n",
            "4", "5", "6", "\n",
            "7", "8", "9", "\n",
            lv.SYMBOL.BACKSPACE, "0", lv.SYMBOL.NEW_LINE, ""]

btnm = lv.btnmatrix(lv.scr_act())
btnm.set_size(200, 150)
btnm.align(lv.ALIGN.BOTTOM_MID, 0, -10)
btnm.add_event_cb(lambda e: btnm_event_handler(e, ta), lv.EVENT.VALUE_CHANGED, None)
btnm.clear_flag(lv.obj.FLAG.CLICK_FOCUSABLE)    # To keep the text area focused on button clicks
btnm.set_map(btnm_map)

---

Text area with password field

C code  

 GitHub

#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_scr_act());
    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_scr_act());
    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_scr_act());
    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_scr_act());
    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_scr_act());
    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*/
}

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

MicroPython code  

 GitHub Simulator

def ta_event_cb(e):
    code = e.get_code()
    ta = e.get_target()
    if code == lv.EVENT.CLICKED or code == lv.EVENT.FOCUSED:
        # Focus on the clicked text area
        if kb != None:
            kb.set_textarea(ta)

    elif code == lv.EVENT.READY:
        print("Ready, current text: " + ta.get_text())


# Create the password box
LV_HOR_RES = lv.scr_act().get_disp().driver.hor_res
LV_VER_RES = lv.scr_act().get_disp().driver.ver_res

pwd_ta = lv.textarea(lv.scr_act())
pwd_ta.set_text("")
pwd_ta.set_password_mode(True)
pwd_ta.set_one_line(True)
pwd_ta.set_width(LV_HOR_RES // 2 - 20)
pwd_ta.set_pos(5, 20)
pwd_ta.add_event_cb(ta_event_cb, lv.EVENT.ALL, None)

# Create a label and position it above the text box
pwd_label = lv.label(lv.scr_act())
pwd_label.set_text("Password:")
pwd_label.align_to(pwd_ta, lv.ALIGN.OUT_TOP_LEFT, 0, 0)

# Create the one-line mode text area
text_ta = lv.textarea(lv.scr_act())
text_ta.set_width(LV_HOR_RES // 2 - 20)
text_ta.set_one_line(True)
text_ta.add_event_cb(ta_event_cb, lv.EVENT.ALL, None)
text_ta.set_password_mode(False)

text_ta.align(lv.ALIGN.TOP_RIGHT, -5, 20)

# Create a label and position it above the text box
oneline_label = lv.label(lv.scr_act())
oneline_label.set_text("Text:")
oneline_label.align_to(text_ta, lv.ALIGN.OUT_TOP_LEFT, 0, 0)

# Create a keyboard
kb = lv.keyboard(lv.scr_act())
kb.set_size(LV_HOR_RES, LV_VER_RES // 2)

kb.set_textarea(pwd_ta)  # Focus it on one of the text areas to start

---

Text auto-formatting

C code  

 GitHub

#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_scr_act());
    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_scr_act());
    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

MicroPython code  

 GitHub Simulator

def ta_event_cb(e):
    ta = e.get_target()
    txt = ta.get_text()
    # print(txt)
    pos = ta.get_cursor_pos()
    # print("cursor pos: ",pos)
    # find position of ":" in text
    colon_pos= txt.find(":")
    # if there are more than 2 digits before the colon, remove the last one entered
    if colon_pos == 3:
        ta.del_char()
    if colon_pos != -1:
        # if there are more than 3 digits after the ":" remove the last one entered
        rest = txt[colon_pos:]
        if len(rest) > 3:
            ta.del_char()

    if len(txt) < 2:
        return
    if ":" in txt:
        return
    if  txt[0] >= '0' and txt[0] <= '9' and \
        txt[1] >= '0' and txt[1] <= '9':
        if len(txt) == 2 or txt[2] != ':' :
            ta.set_cursor_pos(2)
            ta.add_char(ord(':'))
#
# Automatically format text like a clock. E.g. "12:34"
# Add the ':' automatically
#
# Create the text area

LV_HOR_RES = lv.scr_act().get_disp().driver.hor_res
LV_VER_RES = lv.scr_act().get_disp().driver.ver_res

ta = lv.textarea(lv.scr_act())
ta.add_event_cb(ta_event_cb, lv.EVENT.VALUE_CHANGED, None)
ta.set_accepted_chars("0123456789:")
ta.set_max_length(5)
ta.set_one_line(True)
ta.set_text("")
ta.add_state(lv.STATE.FOCUSED)

# Create a keyboard
kb = lv.keyboard(lv.scr_act())
kb.set_size(LV_HOR_RES, LV_VER_RES // 2)
kb.set_mode(lv.keyboard.MODE.NUMBER)
kb.set_textarea(ta)

---

API

Enums

Values:

enumerator LV_PART_TEXTAREA_PLACEHOLDER

Functions

LV_EXPORT_CONST_INT(LV_TEXTAREA_CURSOR_LAST)

lv_obj_t *lv_textarea_create(lv_obj_t *parent)

Create a text area object

Parameters

parent -- pointer to an object, it will be the parent of the new text area

Returns

pointer to the created text area

void lv_textarea_add_char(lv_obj_t *obj, uint32_t c)

Insert a character to the current cursor position. To add a wide char, e.g. 'Á' use _lv_txt_encoded_conv_wc('Á)

Parameters

• obj -- pointer to a text area object

• c -- a character (e.g. 'a)

void lv_textarea_add_text(lv_obj_t *obj, const char *txt)

Insert a text to the current cursor position

Parameters

• obj -- pointer to a text area object

• txt -- a '\0' terminated string to insert

void lv_textarea_del_char(lv_obj_t *obj)

Delete a the left character from the current cursor position

Parameters

obj -- pointer to a text area object

void lv_textarea_del_char_forward(lv_obj_t *obj)

Delete the right character from the current cursor position

Parameters

obj -- pointer to a text area object

void lv_textarea_set_text(lv_obj_t *obj, const char *txt)

Set the text of a text area

Parameters

• obj -- pointer to a text area object

• txt -- pointer to the text

void lv_textarea_set_placeholder_text(lv_obj_t *obj, const char *txt)

Set the placeholder text of a text area

Parameters

• obj -- pointer to a text area object

• txt -- pointer to the text

void lv_textarea_set_cursor_pos(lv_obj_t *obj, int32_t pos)

Set the cursor position

Parameters

• obj -- pointer to a text area object

• pos -- the new cursor position in character index < 0 : index from the end of the text LV_TEXTAREA_CURSOR_LAST: go after the last character

void lv_textarea_set_cursor_click_pos(lv_obj_t *obj, bool en)

Enable/Disable the positioning of the cursor by clicking the text on the text area.

Parameters

• obj -- pointer to a text area object

• en -- true: enable click positions; false: disable

void lv_textarea_set_password_mode(lv_obj_t *obj, bool en)

Enable/Disable password mode

Parameters

• obj -- pointer to a text area object

• en -- true: enable, false: disable

void lv_textarea_set_password_bullet(lv_obj_t *obj, const char *bullet)

Set the replacement characters to show in password mode

Parameters

• obj -- pointer to a text area object

• bullet -- pointer to the replacement text

void lv_textarea_set_one_line(lv_obj_t *obj, bool en)

Configure the text area to one line or back to normal

Parameters

• obj -- pointer to a text area object

• en -- true: one line, false: normal

void lv_textarea_set_accepted_chars(lv_obj_t *obj, const char *list)

Set a list of characters. Only these characters will be accepted by the text area

Parameters

• obj -- pointer to a text area object

• list -- list of characters. Only the pointer is saved. E.g. "+-.,0123456789"

void lv_textarea_set_max_length(lv_obj_t *obj, uint32_t num)

Set max length of a Text Area.

Parameters

• obj -- pointer to a text area object

• num -- the maximal number of characters can be added (lv_textarea_set_text ignores it)

void lv_textarea_set_insert_replace(lv_obj_t *obj, const char *txt)

In LV_EVENT_INSERT the text which planned to be inserted can be replaced by an other text. It can be used to add automatic formatting to the text area.

Parameters

• obj -- pointer to a text area object

• txt -- pointer to a new string to insert. If "" no text will be added. The variable must be live after the event_cb exists. (Should be global or static)

void lv_textarea_set_text_selection(lv_obj_t *obj, bool en)

Enable/disable selection mode.

Parameters

• obj -- pointer to a text area object

• en -- true or false to enable/disable selection mode

void lv_textarea_set_password_show_time(lv_obj_t *obj, uint16_t time)

Set how long show the password before changing it to '*'

Parameters

• obj -- pointer to a text area object

• time -- show time in milliseconds. 0: hide immediately.

void lv_textarea_set_align(lv_obj_t *obj, lv_text_align_t align)

Deprecated: use the normal text_align style property instead Set the label's alignment. It sets where the label is aligned (in one line mode it can be smaller than the text area) and how the lines of the area align in case of multiline text area

Parameters

• obj -- pointer to a text area object

• align -- the align mode from lv_text_align_t

const char *lv_textarea_get_text(const lv_obj_t *obj)

Get the text of a text area. In password mode it gives the real text (not '*'s).

Parameters

obj -- pointer to a text area object

Returns

pointer to the text

const char *lv_textarea_get_placeholder_text(lv_obj_t *obj)

Get the placeholder text of a text area

Parameters

obj -- pointer to a text area object

Returns

pointer to the text

lv_obj_t *lv_textarea_get_label(const lv_obj_t *obj)

Get the label of a text area

Parameters

obj -- pointer to a text area object

Returns

pointer to the label object

uint32_t lv_textarea_get_cursor_pos(const lv_obj_t *obj)

Get the current cursor position in character index

Parameters

obj -- pointer to a text area object

Returns

the cursor position

bool lv_textarea_get_cursor_click_pos(lv_obj_t *obj)

Get whether the cursor click positioning is enabled or not.

Parameters

obj -- pointer to a text area object

Returns

true: enable click positions; false: disable

bool lv_textarea_get_password_mode(const lv_obj_t *obj)

Get the password mode attribute

Parameters

obj -- pointer to a text area object

Returns

true: password mode is enabled, false: disabled

const char *lv_textarea_get_password_bullet(lv_obj_t *obj)

Get the replacement characters to show in password mode

Parameters

obj -- pointer to a text area object

Returns

pointer to the replacement text

bool lv_textarea_get_one_line(const lv_obj_t *obj)

Get the one line configuration attribute

Parameters

obj -- pointer to a text area object

Returns

true: one line configuration is enabled, false: disabled

const char *lv_textarea_get_accepted_chars(lv_obj_t *obj)

Get a list of accepted characters.

Parameters

obj -- pointer to a text area object

Returns

list of accented characters.

uint32_t lv_textarea_get_max_length(lv_obj_t *obj)

Get max length of a Text Area.

Parameters

obj -- pointer to a text area object

Returns

the maximal number of characters to be add

bool lv_textarea_text_is_selected(const lv_obj_t *obj)

Find whether text is selected or not.

Parameters

obj -- pointer to a text area object

Returns

whether text is selected or not

bool lv_textarea_get_text_selection(lv_obj_t *obj)

Find whether selection mode is enabled.

Parameters

obj -- pointer to a text area object

Returns

true: selection mode is enabled, false: disabled

uint16_t lv_textarea_get_password_show_time(lv_obj_t *obj)

Set how long show the password before changing it to '*'

Parameters

obj -- pointer to a text area object

Returns

show time in milliseconds. 0: hide immediately.

void lv_textarea_clear_selection(lv_obj_t *obj)

Clear the selection on the text area.

Parameters

obj -- pointer to a text area object

void lv_textarea_cursor_right(lv_obj_t *obj)

Move the cursor one character right

Parameters

obj -- pointer to a text area object

void lv_textarea_cursor_left(lv_obj_t *obj)

Move the cursor one character left

Parameters

obj -- pointer to a text area object

void lv_textarea_cursor_down(lv_obj_t *obj)

Move the cursor one line down

Parameters

obj -- pointer to a text area object

void lv_textarea_cursor_up(lv_obj_t *obj)

Move the cursor one line up

Parameters

obj -- pointer to a text area object

Variables

const lv_obj_class_t lv_textarea_class

struct lv_textarea_t

Public Members

lv_obj_t obj

lv_obj_t *label

char *placeholder_txt

char *pwd_tmp

char *pwd_bullet

const char *accepted_chars

uint32_t max_length

uint16_t pwd_show_time

lv_coord_t valid_x

uint32_t pos

lv_area_t area

uint32_t txt_byte_pos

uint8_t show

uint8_t click_pos

struct lv_textarea_t cursor

uint32_t sel_start

uint32_t sel_end

uint8_t text_sel_in_prog

uint8_t text_sel_en

uint8_t pwd_mode

uint8_t one_line