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.

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.

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.

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

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)

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

• lv_textarea_cursor_right(textarea)

• lv_textarea_cursor_left(textarea)

• lv_textarea_cursor_up(textarea)

• lv_textarea_cursor_down(textarea)

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

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.

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.

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.

Accepted characters

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

Max text length

The maximum number of characters can be limited with 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.

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.

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.

Keys

• LV_KEY_UP/DOWN/LEFT/RIGHT Move the cursor

• Any character Add the character to the current cursor position

Learn more about Keys.

Example

Simple Text area

C code  

 View on 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_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(strcmp(txt, LV_SYMBOL_BACKSPACE) == 0) lv_textarea_delete_char(ta);
    else if(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(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(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

MicroPython code  

 View on GitHub MicroPython Simulator

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


def buttonm_event_handler(e, ta):
    obj = e.get_target_obj()
    txt = obj.get_button_text(obj.get_selected_button())
    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.screen_active())
ta.set_one_line(True)
ta.align(lv.ALIGN.TOP_MID, 0, 10)
ta.add_event(lambda e: textarea_event_handler(e, ta), lv.EVENT.READY, None)
ta.add_state(lv.STATE.FOCUSED)   # To be sure the cursor is visible

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

buttonm = lv.buttonmatrix(lv.screen_active())
buttonm.set_size(200, 150)
buttonm.align(lv.ALIGN.BOTTOM_MID, 0, -10)
buttonm.add_event(lambda e: buttonm_event_handler(e, ta), lv.EVENT.VALUE_CHANGED, None)
buttonm.remove_flag(lv.obj.FLAG.CLICK_FOCUSABLE)    # To keep the text area focused on button clicks
buttonm.set_map(buttonm_map)

---

Text area with password field

C code  

 View on 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_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(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(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*/
}

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  

 View on GitHub MicroPython Simulator

def ta_event_cb(e):
    code = e.get_code()
    ta = e.get_target_obj()
    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

pwd_ta = lv.textarea(lv.screen_active())
pwd_ta.set_text("")
pwd_ta.set_password_mode(True)
pwd_ta.set_one_line(True)
pwd_ta.set_width(lv.pct(45))
pwd_ta.set_pos(5, 20)
pwd_ta.add_event(ta_event_cb, lv.EVENT.ALL, None)

# Create a label and position it above the text box
pwd_label = lv.label(lv.screen_active())
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.screen_active())
text_ta.set_width(lv.pct(45))
text_ta.set_one_line(True)
text_ta.add_event(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.screen_active())
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.screen_active())
kb.set_size(lv.pct(100), lv.pct(50))

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

---

Text auto-formatting

C code  

 View on 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_screen_active());
    lv_obj_add_event(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

MicroPython code  

 View on GitHub MicroPython Simulator

def ta_event_cb(e):
    ta = e.get_target_obj()
    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

ta = lv.textarea(lv.screen_active())
ta.add_event(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.screen_active())
kb.set_size(lv.pct(100), lv.pct(50))
kb.set_mode(lv.keyboard.MODE.NUMBER)
kb.set_textarea(ta)

---

API

lv_textarea.h