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 includingtext_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. Onlytext_color
andbg_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 toLV_PART_CURSOR
's style. The create line cursor leave the cursor transparent and set a left border. Theanim_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_del_char(textarea)
.
To delete from the right use lv_textarea_del_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)
.
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 •
not exists, *
will be used.
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 1
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 whenLV_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 cursorAny character
Add the character to the current cursor position
Learn more about Keys.
Example¶
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
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
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
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¶
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_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 theevent_cb
exists. (Should beglobal
orstatic
)
-
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
-
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
Variables
-
const lv_obj_class_t lv_textarea_class¶
-
struct lv_textarea_t¶
Public Members
-
char *placeholder_txt¶
-
char *pwd_tmp¶
-
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::[anonymous] 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¶
-
char *placeholder_txt¶