Text area (lv_ta)¶

Overview¶

The Text Area is a Page 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-

Add text¶

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

lv_ta_add_char(ta, 'c')
lv_ta_add_text(ta, "insert this text")

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

lv_ta_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_ta_set_placeholder_text(ta, "Placeholder text")

Delete character¶

To delete a character from the left of the current cursor position use lv_ta_del_char(ta). The delete from teh right use lv_ta_del_char_forward(ta)

Move the cursor¶

The cursor position can be modified directly with lv_ta_set_cursor_pos(ta, 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_ta_cursor_right(ta)
lv_ta_cursor_left(ta)
lv_ta_cursor_up(ta)
lv_ta_cursor_down(ta)

If lv_ta_set_cursor_click_pos(ta, true) is called the cursor will jump to the position where the Text area was clicked.

Cursor types¶

There are several cursor types. You can set one of them with: lv_ta_set_cursor_type(ta, LV_CURSOR_...)

LV_CURSOR_NONE No cursor
LV_CURSOR_LINE A simple vertical line
LV_CURSOR_BLOCK A filled rectangle on the current character
LV_CURSOR_OUTLINE A rectangle border around the current character
LV_CURSOR_UNDERLINE Underline the current character

You can ‘OR’ LV_CURSOR_HIDDEN to any type to temporarily hide the cursor.

The blink time of the cursor can be adjusted with lv_ta_set_cursor_blink_time(ta, time_ms).

One line mode¶

The Text area can be configures to be one lined with lv_ta_set_one_line(ta, true). In this mode the height is set automatically to show only one line, line break character are ignored, and word wrap is disabled.

Password mode¶

The text area supports password mode which can be enabled with lv_ta_set_pwd_mode(ta, true). In password mode, the enters characters are converted to * after some time or when a new character is entered.

In password mode lv_ta_get_text(ta) gives the real text and not the asterisk characters

The visibility time can be adjusted with lv_ta_set_pwd_show_time(ta, time_ms).

Text align¶

The text can be aligned to the left, center or right with lv_ta_set_text_align(ta, LV_LABEL_ALIGN_LET/CENTER/RIGHT).

In one line mode, the text can be scrolled horizontally only if the text is left aligned.

Accepted characters¶

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

Max text length¶

The maximum number of characters can be limited with lv_ta_set_max_length(ta, max_char_num)

Very long texts¶

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

A part of text can be selected if enabled with lv_ta_set_text_sel(ta, true). It works like when you select a text on your PC with your mouse.

Scrollbars¶

The scrollbars can shown according to different policies set by lv_ta_set_sb_mode(ta, LV_SB_MODE_...). Learn more at the Page object.

Scroll propagation¶

When the Text area is scrolled on an other scrollable object (like a Page) and the scrolling has reached the edge of the Text area, the scrolling can be propagated to the parent. In other words, when the Text area can be scrolled further, the parent will be scrolled instead.

It can be enabled with lv_ta_set_scroll_propagation(ta, true).

Learn more at the Page object.

Edge flash¶

When the Text area is scrolled to edge a circle like flash animation can be shown if it is enabled with lv_ta_set_edge_flash(ta, true)

Style usage¶

Use lv_ta_set_style(page, LV_TA_STYLE_..., &style) to set a new style for an element of the text area:

LV_TA_STYLE_BG background’s style which uses all style.body properties. The label uses style.label from this style. (default: lv_style_pretty)
LV_TA_STYLE_SB scrollbar’s style which uses all style.body properties (default: lv_style_pretty_color)
LV_TA_STYLE_CURSOR cursor style. If NULL then the library sets a style automatically according to the label’s color and font
- LV_CURSOR_LINE: a style.line.width wide line but drawn as a rectangle as style.body. padding.top/left makes an offset on the cursor
- LV_CURSOR_BLOCK: a rectangle as style.body padding makes the rectangle larger
- LV_CURSOR_OUTLINE: an empty rectangle (just a border) as style.body padding makes the rectangle larger
- LV_CURSOR_UNDERLINE: a style.line.width wide line but drawn as a rectangle as style.body. padding.top/left makes an offset on the cursor

Events¶

Besides the Generic events the following Special events are sent by the Slider:

LV_EVENT_INSERT Sent when a character before a character is inserted. The evnet data is the text planned to insert. lv_ta_set_insert_replace(ta, "New text") replaces the text to insert. The new text can’t be in a local variable which is destroyed when the event callback exists. "" means do not insert anything.
LV_EVENT_VALUE_CHANGED When the content of the text area has been changed.

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¶

C¶

Simple Text area¶

#include "lvgl/lvgl.h"
#include <stdio.h>

lv_obj_t * ta1;

static void event_handler(lv_obj_t * obj, lv_event_t event)
{
    if(event == LV_EVENT_VALUE_CHANGED) {
        printf("Value: %s\n", lv_ta_get_text(obj));
    }
    else if(event == LV_EVENT_LONG_PRESSED_REPEAT) {
        /*For simple test: Long press the Text are to add the text below*/
        const char  * txt = "\n\nYou can scroll it if the text is long enough.\n";
        static uint16_t i = 0;
        if(txt[i] != '\0') {
            lv_ta_add_char(ta1, txt[i]);
            i++;
        }
    }
}


void lv_ex_ta_1(void)
{
    ta1 = lv_ta_create(lv_scr_act(), NULL);
    lv_obj_set_size(ta1, 200, 100);
    lv_obj_align(ta1, NULL, LV_ALIGN_CENTER, 0, 0);
    lv_ta_set_cursor_type(ta1, LV_CURSOR_BLOCK);
    lv_ta_set_text(ta1, "A text in a Text Area");    /*Set an initial text*/
    lv_obj_set_event_cb(ta1, event_handler);
}

Text are with password field¶

/**
 * @file lv_ex_templ.c
 *
 */

/*********************
 *      INCLUDES
 *********************/
#include "lvgl/lvgl.h"
#include <stdio.h>

/*********************
 *      DEFINES
 *********************/

/**********************
 *      TYPEDEFS
 **********************/

/**********************
 *  STATIC PROTOTYPES
 **********************/
static void kb_event_cb(lv_obj_t * event_kb, lv_event_t event);
static void ta_event_cb(lv_obj_t * ta, lv_event_t event);

/**********************
 *  STATIC VARIABLES
 **********************/

static lv_obj_t * kb;
/**********************
 *      MACROS
 **********************/

/**********************
 *   GLOBAL FUNCTIONS
 **********************/

void lv_ex_ta_2(void)
{
    /* Create the password box */
    lv_obj_t * pwd_ta = lv_ta_create(lv_scr_act(), NULL);
    lv_ta_set_text(pwd_ta, "");
    lv_ta_set_pwd_mode(pwd_ta, true);
    lv_ta_set_one_line(pwd_ta, true);
    lv_obj_set_width(pwd_ta, LV_HOR_RES / 2 - 20);
    lv_obj_set_pos(pwd_ta, 5, 20);
    lv_obj_set_event_cb(pwd_ta, ta_event_cb);
    
    /* Create a label and position it above the text box */
    lv_obj_t * pwd_label = lv_label_create(lv_scr_act(), NULL);
    lv_label_set_text(pwd_label, "Password:");
    lv_obj_align(pwd_label, pwd_ta, LV_ALIGN_OUT_TOP_LEFT, 0, 0);
    
    
    /* Create the one-line mode text area */
    lv_obj_t * oneline_ta = lv_ta_create(lv_scr_act(), pwd_ta);
    lv_ta_set_pwd_mode(oneline_ta, false);
    lv_ta_set_cursor_type(oneline_ta, LV_CURSOR_LINE | LV_CURSOR_HIDDEN);
    lv_obj_align(oneline_ta, NULL, LV_ALIGN_IN_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(), NULL);
    lv_label_set_text(oneline_label, "Text:");
    lv_obj_align(oneline_label, oneline_ta, LV_ALIGN_OUT_TOP_LEFT, 0, 0);

    /* Create a keyboard and make it fill the width of the above text areas */
    kb = lv_kb_create(lv_scr_act(), NULL);
    lv_obj_set_pos(kb, 5, 90);
    lv_obj_set_event_cb(kb, kb_event_cb); /* Setting a custom event handler stops the keyboard from closing automatically */
    lv_obj_set_size(kb,  LV_HOR_RES - 10, 140);
    
    lv_kb_set_ta(kb, pwd_ta); /* Focus it on one of the text areas to start */
    lv_kb_set_cursor_manage(kb, true); /* Automatically show/hide cursors on text areas */
}

/**********************
 *   STATIC FUNCTIONS
 **********************/

static void kb_event_cb(lv_obj_t * event_kb, lv_event_t event)
{
    /* Just call the regular event handler */
    lv_kb_def_event_cb(event_kb, event);

}
static void ta_event_cb(lv_obj_t * ta, lv_event_t event)
{
    if(event == LV_EVENT_CLICKED) {
        /* Focus on the clicked text area */
        if(kb != NULL)
            lv_kb_set_ta(kb, ta);
    }

    else if(event == LV_EVENT_INSERT) {
        const char * str = lv_event_get_data();
        if(str[0] == '\n') {
            printf("Ready\n");
        }
    }
}

MicroPython¶

Simple Text area¶

def event_handler(obj, event):
    if event == lv.EVENT.VALUE_CHANGED:
        print("Value: %s" % obj.get_text())
    elif event == lv.EVENT.LONG_PRESSED_REPEAT:
        # For simple test: Long press the Text are to add the text below
        ta1.add_text("\n\nYou can scroll it if the text is long enough.\n")

ta1 = lv.ta(lv.scr_act())
ta1.set_size(200, 100)
ta1.align(None, lv.ALIGN.CENTER, 0, 0)
ta1.set_cursor_type(lv.CURSOR.BLOCK)
ta1.set_text("A text in a Text Area")     # Set an initial text
ta1.set_event_cb(event_handler)

Text are with password field¶

Form with password field in LittlevGL with MicroPython

HOR_RES = lv.disp_get_hor_res(lv.disp_get_default())

def kb_event_cb(event_kb, event):
    # Just call the regular event handler
    event_kb.def_event_cb(event)

def ta_event_cb(ta, event):
    if event == lv.EVENT.INSERT:
        # get inserted value
        ptr = lv.C_Pointer()
        ptr.ptr_val = lv.event_get_data()
        if ptr.str_val == "\n":
            print("Ready")
    elif event == lv.EVENT.CLICKED:
        # Focus on the clicked text area
        kb.set_ta(ta)

# Create the password box
pwd_ta = lv.ta(lv.scr_act())
pwd_ta.set_text("");
pwd_ta.set_pwd_mode(True)
pwd_ta.set_one_line(True)
pwd_ta.set_width(HOR_RES // 2 - 20)
pwd_ta.set_pos(5, 20)
pwd_ta.set_event_cb(ta_event_cb)

# 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(pwd_ta, lv.ALIGN.OUT_TOP_LEFT, 0, 0)

# Create the one-line mode text area
oneline_ta = lv.ta(lv.scr_act(), pwd_ta)
oneline_ta.set_pwd_mode(False)
oneline_ta.set_cursor_type(lv.CURSOR.LINE | lv.CURSOR.HIDDEN)
oneline_ta.align(None, lv.ALIGN.IN_TOP_RIGHT, -5, 20)
oneline_ta.set_event_cb(ta_event_cb)

# 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(oneline_ta, lv.ALIGN.OUT_TOP_LEFT, 0, 0)

# Create a keyboard and make it fill the width of the above text areas
kb = lv.kb(lv.scr_act())
kb.set_pos(5, 90)
kb.set_event_cb(kb_event_cb) # Setting a custom event handler stops the keyboard from closing automatically
kb.set_size(HOR_RES - 10, 140)

kb.set_ta(pwd_ta) # Focus it on one of the text areas to start
kb.set_cursor_manage(True) # Automatically show/hide cursors on text areas

API¶

Typedefs

typedef uint8_t lv_cursor_type_t¶

typedef uint8_t lv_ta_style_t¶

Enums

enum [anonymous]¶

Style of text area’s cursor.

Values:

enumerator LV_CURSOR_NONE¶: No cursor

enumerator LV_CURSOR_LINE¶: Vertical line

enumerator LV_CURSOR_BLOCK¶: Rectangle

enumerator LV_CURSOR_OUTLINE¶: Outline around character

enumerator LV_CURSOR_UNDERLINE¶: Horizontal line under character

enumerator LV_CURSOR_HIDDEN = 0x08¶: This flag can be ORed to any of the other values to temporarily hide the cursor

enum [anonymous]¶

Possible text areas tyles.

Values:

enumerator LV_TA_STYLE_BG¶: Text area background style

enumerator LV_TA_STYLE_SB¶: Scrollbar style

enumerator LV_TA_STYLE_CURSOR¶: Cursor style

enumerator LV_TA_STYLE_EDGE_FLASH¶: Edge flash style

enumerator LV_TA_STYLE_PLACEHOLDER¶: Placeholder style

Functions

LV_EXPORT_CONST_INT(LV_TA_CURSOR_LAST)¶

lv_obj_t *lv_ta_create(lv_obj_t *par, const lv_obj_t *copy)¶

Create a text area objects

Return

pointer to the created text area

Parameters

par: pointer to an object, it will be the parent of the new text area
copy: pointer to a text area object, if not NULL then the new object will be copied from it

void lv_ta_add_char(lv_obj_t *ta, 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

ta: pointer to a text area object
c: a character (e.g. ‘a’)

void lv_ta_add_text(lv_obj_t *ta, const char *txt)¶

Insert a text to the current cursor position

Parameters

ta: pointer to a text area object
txt: a ‘\0’ terminated string to insert

void lv_ta_del_char(lv_obj_t *ta)¶

Delete a the left character from the current cursor position

Parameters

ta: pointer to a text area object

void lv_ta_del_char_forward(lv_obj_t *ta)¶

Delete the right character from the current cursor position

Parameters

ta: pointer to a text area object

void lv_ta_set_text(lv_obj_t *ta, const char *txt)¶

Set the text of a text area

Parameters

ta: pointer to a text area
txt: pointer to the text

void lv_ta_set_placeholder_text(lv_obj_t *ta, const char *txt)¶

Set the placeholder text of a text area

Parameters

ta: pointer to a text area
txt: pointer to the text

void lv_ta_set_cursor_pos(lv_obj_t *ta, int16_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_TA_CURSOR_LAST: go after the last character

void lv_ta_set_cursor_type(lv_obj_t *ta, lv_cursor_type_t cur_type)¶

Set the cursor type.

Parameters

ta: pointer to a text area object
cur_type: element of ‘lv_cursor_type_t’

void lv_ta_set_cursor_click_pos(lv_obj_t *ta, bool en)¶

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

Parameters

ta: pointer to a text area object
en: true: enable click positions; false: disable

void lv_ta_set_pwd_mode(lv_obj_t *ta, bool en)¶

Enable/Disable password mode

Parameters

ta: pointer to a text area object
en: true: enable, false: disable

void lv_ta_set_one_line(lv_obj_t *ta, bool en)¶

Configure the text area to one line or back to normal

Parameters

ta: pointer to a Text area object
en: true: one line, false: normal

void lv_ta_set_text_align(lv_obj_t *ta, lv_label_align_t align)¶

Set the alignment of the text area. In one line mode the text can be scrolled only with LV_LABEL_ALIGN_LEFT. This function should be called if the size of text area changes.

Parameters

ta: pointer to a text are object
align: the desired alignment from lv_label_align_t. (LV_LABEL_ALIGN_LEFT/CENTER/RIGHT)

void lv_ta_set_accepted_chars(lv_obj_t *ta, const char *list)¶

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

Parameters

ta: pointer to Text Area
list: list of characters. Only the pointer is saved. E.g. “+-.,0123456789”

void lv_ta_set_max_length(lv_obj_t *ta, uint16_t num)¶

Set max length of a Text Area.

Parameters

ta: pointer to Text Area
num: the maximal number of characters can be added (lv_ta_set_text ignores it)

void lv_ta_set_insert_replace(lv_obj_t *ta, 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

ta: pointer to a text area.
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_ta_set_sb_mode(lv_obj_t *ta, lv_sb_mode_t mode)¶

Set the scroll bar mode of a text area

Parameters

ta: pointer to a text area object
sb_mode: the new mode from ‘lv_page_sb_mode_t’ enum

void lv_ta_set_scroll_propagation(lv_obj_t *ta, bool en)¶

Enable the scroll propagation feature. If enabled then the Text area will move its parent if there is no more space to scroll.

Parameters

ta: pointer to a Text area
en: true or false to enable/disable scroll propagation

void lv_ta_set_edge_flash(lv_obj_t *ta, bool en)¶

Enable the edge flash effect. (Show an arc when the an edge is reached)

Parameters

page: pointer to a Text Area
en: true or false to enable/disable end flash

void lv_ta_set_style(lv_obj_t *ta, lv_ta_style_t type, const lv_style_t *style)¶

Set a style of a text area

Parameters

ta: pointer to a text area object
type: which style should be set
style: pointer to a style

void lv_ta_set_text_sel(lv_obj_t *ta, bool en)¶

Enable/disable selection mode.

Parameters

ta: pointer to a text area object
en: true or false to enable/disable selection mode

void lv_ta_set_pwd_show_time(lv_obj_t *ta, uint16_t time)¶

Set how long show the password before changing it to ‘*’

Parameters

ta: pointer to Text area
time: show time in milliseconds. 0: hide immediately.

void lv_ta_set_cursor_blink_time(lv_obj_t *ta, uint16_t time)¶

Set cursor blink animation time

Parameters

ta: pointer to Text area
time: blink period. 0: disable blinking

const char *lv_ta_get_text(const lv_obj_t *ta)¶

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

Return

pointer to the text

Parameters

ta: pointer to a text area object

const char *lv_ta_get_placeholder_text(lv_obj_t *ta)¶

Get the placeholder text of a text area

Return

pointer to the text

Parameters

ta: pointer to a text area object

lv_obj_t *lv_ta_get_label(const lv_obj_t *ta)¶

Get the label of a text area

Return

pointer to the label object

Parameters

ta: pointer to a text area object

uint16_t lv_ta_get_cursor_pos(const lv_obj_t *ta)¶

Get the current cursor position in character index

Return

the cursor position

Parameters

ta: pointer to a text area object

lv_cursor_type_t lv_ta_get_cursor_type(const lv_obj_t *ta)¶

Get the current cursor type.

Return

element of ‘lv_cursor_type_t’

Parameters

ta: pointer to a text area object

bool lv_ta_get_cursor_click_pos(lv_obj_t *ta)¶

Get whether the cursor click positioning is enabled or not.

Return

true: enable click positions; false: disable

Parameters

ta: pointer to a text area object

bool lv_ta_get_pwd_mode(const lv_obj_t *ta)¶

Get the password mode attribute

Return

true: password mode is enabled, false: disabled

Parameters

ta: pointer to a text area object

bool lv_ta_get_one_line(const lv_obj_t *ta)¶

Get the one line configuration attribute

Return

true: one line configuration is enabled, false: disabled

Parameters

ta: pointer to a text area object

const char *lv_ta_get_accepted_chars(lv_obj_t *ta)¶

Get a list of accepted characters.

Return

list of accented characters.

Parameters

ta: pointer to Text Area

uint16_t lv_ta_get_max_length(lv_obj_t *ta)¶

Set max length of a Text Area.

Return

the maximal number of characters to be add

Parameters

ta: pointer to Text Area

lv_sb_mode_t lv_ta_get_sb_mode(const lv_obj_t *ta)¶

Get the scroll bar mode of a text area

Return

scrollbar mode from ‘lv_page_sb_mode_t’ enum

Parameters

ta: pointer to a text area object

bool lv_ta_get_scroll_propagation(lv_obj_t *ta)¶

Get the scroll propagation property

Return

true or false

Parameters

ta: pointer to a Text area

bool lv_ta_get_edge_flash(lv_obj_t *ta)¶

Get the scroll propagation property

Return

true or false

Parameters

ta: pointer to a Text area

const lv_style_t *lv_ta_get_style(const lv_obj_t *ta, lv_ta_style_t type)¶

Get a style of a text area

Return

style pointer to a style

Parameters

ta: pointer to a text area object
type: which style should be get

bool lv_ta_text_is_selected(const lv_obj_t *ta)¶

Find whether text is selected or not.

Return

whether text is selected or not

Parameters

ta: Text area object

bool lv_ta_get_text_sel_en(lv_obj_t *ta)¶

Find whether selection mode is enabled.

Return

true: selection mode is enabled, false: disabled

Parameters

ta: pointer to a text area object

uint16_t lv_ta_get_pwd_show_time(lv_obj_t *ta)¶

Set how long show the password before changing it to ‘*’

Return

show time in milliseconds. 0: hide immediately.

Parameters

ta: pointer to Text area

uint16_t lv_ta_get_cursor_blink_time(lv_obj_t *ta)¶

Set cursor blink animation time

Return

time blink period. 0: disable blinking

Parameters

ta: pointer to Text area

void lv_ta_clear_selection(lv_obj_t *ta)¶

Clear the selection on the text area.

Parameters

ta: Text area object

void lv_ta_cursor_right(lv_obj_t *ta)¶

Move the cursor one character right

Parameters

ta: pointer to a text area object

void lv_ta_cursor_left(lv_obj_t *ta)¶

Move the cursor one character left

Parameters

ta: pointer to a text area object

void lv_ta_cursor_down(lv_obj_t *ta)¶

Move the cursor one line down

Parameters

ta: pointer to a text area object

void lv_ta_cursor_up(lv_obj_t *ta)¶

Move the cursor one line up

Parameters

ta: pointer to a text area object

struct lv_ta_ext_t¶

Public Members

lv_page_ext_t page¶

lv_obj_t *label¶

lv_obj_t *placeholder¶

char *pwd_tmp¶

const char *accapted_chars¶

uint16_t max_length¶

uint16_t pwd_show_time¶

const lv_style_t *style¶

lv_coord_t valid_x¶

uint16_t pos¶

uint16_t blink_time¶

lv_area_t area¶

uint16_t txt_byte_pos¶

lv_cursor_type_t type¶

uint8_t state¶

uint8_t click_pos¶

struct lv_ta_ext_t::[anonymous] cursor¶

lv_draw_label_txt_sel_t sel¶

uint8_t text_sel_in_prog¶

uint8_t text_sel_en¶

uint8_t pwd_mode¶

uint8_t one_line¶