Labs / LVGL / 03 Quick Start Example - Control Section (Based on Web Simulator and LVGL v9.0)

14. Text Box

Author: Li Zisheng · Source: FreakStudio open documentation, v1.0 · License: CC BY 4.0

Contents
API namePurposeInput parametersReturn value
__init__Construct a Textarea widget, bound to the specified parent containerparent: lv.obj type
(parent container object)
lv.textarea
add_charAdd a single character (the argument is a character code / delay value, actually used for character input)delay_ms: int
(character code / delay in milliseconds)
None
add_textAppend text content to the text boxtext: str (text to add)None
delete_charDelete the character to the left of the cursorNoneNone
set_textSet the complete content of the text box (overwrites the existing content)text: str (target text)None
get_textGet all the current content of the text boxNonestr
set_placeholder_textSet the placeholder hint text displayed when the text box is emptytext: str (placeholder text)None
get_placeholder_textGet the placeholder hint text of the text boxNonestr
set_cursor_posSet the cursor position (by character index, starting from 0)index: int (cursor index position)None
get_cursor_posGet the index position where the cursor is currently locatedNoneint
set_cursor_click_posSet whether the cursor is automatically positioned when the text box is clickedantialias: bool
(True = on, False = off)
None
get_cursor_click_posGet the on/off state of "click to position cursor"Nonebool
cursor_rightMove the cursor one character position to the rightNoneNone
cursor_leftMove the cursor one character position to the leftNoneNone
cursor_downMove the cursor down one line (in multi-line mode)NoneNone
cursor_upMove the cursor up one line (in multi-line mode)NoneNone
set_password_modeTurn password input mode on / off (input content is masked)antialias: bool
(True = on, False = off)
None
set_password_bulletSet the mask character in password mode (e.g., *, ●)text: str
(mask character, a single character recommended)
None
get_password_bulletGet the mask character of the current password modeNonestr
set_password_show_timeSet how long a password character stays visible after input (in milliseconds; becomes masked after the timeout)delay_ms: int
(display duration, in ms)
None
get_password_show_timeGet the visible duration of password charactersNoneint
set_one_lineSet whether the text box displays only a single line (False = multi-line allowed)antialias: bool
(True = single line, False = multi-line)
None
get_one_lineGet the single-line / multi-line display state of the text boxNonebool
set_accepted_charsSet the set of characters the text box allows to be entered (characters outside it cannot be entered)text: str
(allowed characters, e.g., "0-9a-z")
None
get_accepted_charsGet the set of characters currently allowed for inputNonestr
set_max_lengthSet the maximum character length the text box allows to be entereddelay_ms: int (maximum length value)None
set_insert_replaceSet the replacement text in insert mode (replaces the selected content when typing)text: str (replacement text)None
set_text_selectionTurn the text selection function on / off (allows part of the text to be selected)antialias: bool
(True = on, False = off)
None
get_text_selectionGet the on/off state of the text selection functionNonebool
text_is_selectedCheck whether any text is currently selectedNonebool
clear_selectionClear the currently selected text (cancel the selection state)NoneNone
get_current_charGet the ASCII/Unicode code value of the character at the cursor positionNoneint
get_labelGet the Label object (underlying widget) used internally by the text box to render textNonelv.label

14.1 Plain Text Box

import display_driver
import lvgl as lv

# Initialize the environment
lv.init()
scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0x000000), 0)  

# Create a regular text box (multi-line input)
textarea1 = lv.textarea(scr)
textarea1.set_size(lv.pct(90), 100)
textarea1.set_pos(lv.pct(5), lv.pct(5))
textarea1.set_placeholder_text("Multi-line input...")
textarea1.set_max_length(100)  # Maximum 100 characters

# Load the screen
lv.screen_load(scr)
14.1

14.2 Password Box

import display_driver
import lvgl as lv

# Initialize the environment
lv.init()
scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0x000000), 0)  

# Create a password box
password_area = lv.textarea(scr)
password_area.set_size(lv.pct(90), 50)
password_area.set_pos(lv.pct(5), lv.pct(35))
password_area.set_placeholder_text("Please enter the password.")
password_area.set_password_mode(True)
password_area.set_password_bullet("•")  # Password shown as dots
password_area.set_password_show_time(1000)  # Typed characters are shown for 1 second and then change to dots
password_area.set_max_length(20)  # Password maximum 20 characters

# Load the screen
lv.screen_load(scr)
14.2

14.3 Text Box Allowing Numeric Input Only

import display_driver
import lvgl as lv

# Initialize the environment
lv.init()
scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0x000000), 0)  

# Create a text box with a character limit (digits only)
number_area = lv.textarea(scr)
number_area.set_size(lv.pct(90), 50)
number_area.set_pos(lv.pct(5), lv.pct(55))
number_area.set_placeholder_text("Please enter a number")
number_area.set_one_line(True)  # Single-line mode
number_area.set_accepted_chars("0123456789")  # Only digit input allowed
number_area.set_max_length(10)  # Maximum 10 digits

# Load the screen
lv.screen_load(scr)
14. Text Box

Version Record

Version Number

Modifier

Time

Content

v1.0

Li Zisheng

2026/03/23

Initialize the document.