Overview

The Text Area is a page with a label and a cursor on it. You can insert text or characters to the current cursor position with:

  • lv_ta_add_char(ta, 'c');
  • lv_ta_add_text(ta, "insret this text");

The lv_ta_set_text(ta, "New text") changes the whole text.

To delete a character from the left of the current cursor position use lv_ta_del()

The cursor position can be modified directly like lv_ta_set_cursor_pos(ta, 10) or by stepping it:

  • lv_ta_cursor_right(ta)
  • lv_ta_cursor_left(ta)
  • lv_ta_cursor_up(ta)
  • lv_ta_cursor_down(ta)

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

  • LV_CURSOR_NONE
  • LV_CURSOR_LINE
  • LV_CURSOR_BLOCK
  • LV_CURSOR_OUTLINE
  • LV_CURSOR_UNDERLINE

You can 'OR' LV_CURSOR_HIDDEN to any type to hide the cursor.

The Text area can be configures to be one lined with lv_ta_set_one_line(ta, true)

The text area supports password mode. It can be enabled with lv_ta_set_pwd_mode(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 also uses this 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_transp)
  • LV_TA_STYLE_CURSOR cursor style. If NULL then the library sets us a style automatically according to the label color and font
    • LV_CURSOR_LINE: a style.line.width wide line but drawn as a rectangle as style.body. Hor. and ver. padding makes an offset on the cursor
    • LV_CURSOR_BLOCK: a rectangle as style.body Hor. and ver. padding makes the rectangle larger
    • LV_CURSOR_OUTLINE: an empty rectangle (just a border) as style.body Hor. and ver. padding makes the rectangle larger
    • LV_CURSOR_UNDERLINE: a style.line.width wide line but drawn as a rectangle as style.body. Hor. and ver. padding makes an offset on the cursor

Notes

  • In password mode lv_ta_get_text(ta) gives the real text and not the asterisk characters
Example of Text area in Littlev Graphics Library

						/*Create a scroll bar style*/
static lv_style_t style_sb;
lv_style_copy(&style_sb, &lv_style_plain);
style_sb.body.main_color = LV_COLOR_BLACK;
style_sb.body.grad_color = LV_COLOR_BLACK;
style_sb.body.border.color = LV_COLOR_WHITE;
style_sb.body.border.width = 1;
style_sb.body.border.opa = LV_OPA_70;
style_sb.body.radius = LV_RADIUS_CIRCLE;
style_sb.body.opa = LV_OPA_60;

/*Create a normal Text area*/
lv_obj_t * ta1 = lv_ta_create(lv_scr_act(), NULL);
lv_obj_set_size(ta1, 200, 100);
lv_obj_align(ta1, NULL, LV_ALIGN_CENTER, 0, - LV_DPI / 2);
lv_ta_set_style(ta1,LV_TA_STYLE_SB, &style_sb);                     /*Apply the scroll bar style*/
lv_ta_set_cursor_type(ta1, LV_CURSOR_BLOCK);
lv_ta_set_text(ta1, "A text in a Text Area\n"
               "You can scroll it if the text is long enough.");    /*Set an initial text*/
lv_ta_set_cursor_pos(ta1, 2);                                       /*Set the cursor position*/
lv_ta_add_text(ta1, "long ");                                       /*Insert a word at the current cursor position*/

static lv_style_t style_bg;
lv_style_copy(&style_bg, &lv_style_pretty);
style_bg.body.shadow.width = 8;
style_bg.text.color = LV_COLOR_MAKE(0x30, 0x60, 0xd0);              /*Blue label*/

/*Create a one lined test are with password mode*/
lv_obj_t * ta2 = lv_ta_create(lv_scr_act(), ta1);
lv_obj_align(ta2, ta1, LV_ALIGN_OUT_BOTTOM_MID, 0, 50);
lv_ta_set_style(ta2,LV_TA_STYLE_BG, &style_bg);                     /*Apply the background style*/
lv_ta_set_one_line(ta2, true);
lv_ta_set_cursor_type(ta2, LV_CURSOR_LINE);
lv_ta_set_pwd_mode(ta2, true);
lv_ta_set_text(ta2, "Password");

lv_obj_t *

lv_ta_create

(lv_obj_t * par, lv_obj_t * copy);

Create a text area objects

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

return pointer to the created text area

void

lv_ta_add_char

(lv_obj_t * ta, char c);

Insert a character to the current cursor position

ta pointer to a text area object

c a character

void

lv_ta_add_text

(lv_obj_t * ta, const char * txt);

Insert a text to the current cursor position

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

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

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

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.

ta pointer to a text area object

cur_type: element of 'lv_cursor_type_t'

void

lv_ta_set_pwd_mode

(lv_obj_t * ta, bool pwd_en);

Enable/Disable password mode

ta pointer to a text area object

pwd_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

ta pointer to a Text area object

en true: one line, false: normal

void

lv_ta_set_sb_mode

(lv_obj_t * ta, lv_sb_mode_t mode);

Set the scroll bar mode of a text area

ta pointer to a text area object

sb_mode the new mode from 'lv_page_sb_mode_t' enum

void

lv_ta_set_style

(lv_obj_t *ta, lv_ta_style_t type, lv_style_t *style);

Set a style of a text area

ta pointer to a text area object

type which style should be set

style pointer to a style

const

char

* lv_ta_get_text(lv_obj_t * ta);

Get the text of a text area

ta pointer to a text area object

return pointer to the text

lv_obj_t *

lv_ta_get_label

(lv_obj_t * ta);

Get the label of a text area

ta pointer to a text area object

return pointer to the label object

uint16_t

lv_ta_get_cursor_pos

(lv_obj_t * ta);

Get the current cursor position in character index

ta pointer to a text area object

return the cursor position

bool

lv_ta_get_cursor_show

(lv_obj_t * ta);

Get the current cursor visibility.

ta pointer to a text area object

return true: the cursor is drawn, false: the cursor is hidden

lv_cursor_type_t

lv_ta_get_cursor_type

(lv_obj_t * ta);

Get the current cursor type.

ta pointer to a text area object

return element of 'lv_cursor_type_t'

bool

lv_ta_get_pwd_mode

(lv_obj_t * ta);

Get the password mode attribute

ta pointer to a text area object

return true: password mode is enabled, false: disabled

bool

lv_ta_get_one_line

(lv_obj_t * ta);

Get the one line configuration attribute

ta pointer to a text area object

return true: one line configuration is enabled, false: disabled

lv_sb_mode_t

lv_ta_get_sb_mode

(lv_obj_t * ta);

Get the scroll bar mode of a text area

ta pointer to a text area object

return scrollbar mode from 'lv_page_sb_mode_t' enum

lv_style_t *

lv_ta_get_style

(lv_obj_t *ta, lv_ta_style_t type);

Get a style of a text area

ta pointer to a text area object

type which style should be get

return style pointer to a style

void

lv_ta_cursor_right

(lv_obj_t * ta);

Move the cursor one character right

ta pointer to a text area object

void

lv_ta_cursor_left

(lv_obj_t * ta);

Move the cursor one character left

ta pointer to a text area object

void

lv_ta_cursor_down

(lv_obj_t * ta);

Move the cursor one line down

ta pointer to a text area object

void

lv_ta_cursor_up

(lv_obj_t * ta);

Move the cursor one line up

ta pointer to a text area object

LittlevGL - Open-source Embedded GUI Library

LittlevGL is a free and open-source graphics library providing everything you need to create embedded GUI with easy-to-use graphical elements, beautiful visual effects and low memory footprint.

If you like LittlevGL, please
support its deveopment!


The founder of Littlev Graphics Library (LittlevGL) and related software modules is:
Gábor Kiss-Vámosi
All Rights Reserved ©  2018 Hungary