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

15. Keyboard

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

Contents
API namePurposeInput parametersReturn valueNotes
__init__Construct a keyboard widget, bound to the specified parent containerparent: lv.obj (e.g., the screen object scr)lv.keyboardBasic creation
set_textareaBind the keyboard to a Textarea to link input (core)obj: lv.textarea (text box to bind)NoneInput content is automatically synchronized to the text box
get_textareaGet the currently bound Textarea objectNonelv.textareaVerify whether the binding is in effect
set_modeSet the keyboard input modemode: int (enum value) 0=TEXT_LOWER (lowercase) 1=TEXT_UPPER (uppercase) 3=NUMBER (numbers)NoneSwitch the input mode as needed
get_modeGet the current keyboard modeNoneintReturn the mode enum value
set_popoversTurn the special character pop-up layer on / off (e.g., punctuation, symbols)antialias: bool (True = on)NoneEnhance special character input
set_mapCustomize the keyboard key layout of the specified mode1. mode: int (mode) 2. map: list [str] (button text) 3. ctrl_map: NoneNoneSimplified: pass None for ctrl_map
get_selected_buttonGet the ID of the currently selected button (returns 65535 if none selected)NoneintAids interaction logic
get_button_textGet the button display text by button IDbtn_id: int (button ID, starting from 0)strVerify that the custom layout takes effect

15.1 General Single Text Box Input Keyboard

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 keyboard
keyboard = lv.keyboard(scr)
#Set the size
keyboard.set_size(400, 200)
#Align to bottom center
keyboard.align(lv.ALIGN.BOTTOM_MID, 0, 0)  
# Create the input target (using textarea as an example)
textarea = lv.textarea(scr)
textarea.set_size(380, 100)
textarea.align(lv.ALIGN.TOP_MID, 0, 20)
textarea.set_placeholder_text("textarea...")  # Placeholder text
# Bind the keyboard to the input target; once bound, keyboard input goes directly into the textarea
keyboard.set_textarea(textarea) 

# Load the screen
lv.screen_load(scr)
1
1 2 3

15.2 Plain Text Numeric Input Box with Keyboard Show/Hide Control

In the following code, we implement a minimal example of numeric input interaction that only retains the core functions of "plaintext numeric input + virtual numeric keypad":

import display_driver
import lvgl as lv

lv.init()
scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0x000000), 0)
scr_h = scr.get_height()  # Get the screen height

# Create a plain-text numeric input box (core)
textarea = lv.textarea(scr)
textarea.set_size(380, 50)  # Fixed size
textarea.set_pos(10, 20)     # Fixed position
textarea.set_placeholder_text("Please enter the number.")
textarea.set_accepted_chars("0123456789")  # Digits only
textarea.set_one_line(True)                # Single line
textarea.set_max_length(6)                 # 6-digit limit

# Create a numeric keyboard (initially moved off screen)
kb = lv.keyboard(scr)
kb.set_size(400, 200)       # Fixed size
kb.set_pos(0, scr_h + 100)  # Initially hidden (off screen)
kb.set_mode(lv.keyboard.MODE.NUMBER)  # Digits-only mode

# Keyboard show/hide logic (minimal)
def show_kb(e):
    """Tap the input box: show the keyboard"""
    kb.set_textarea(textarea)
    # Move to the bottom of the screen
    kb.set_pos(0, scr_h - 350)  

def hide_kb(e):
    """Confirm/Enter: hide the keyboard"""
    if e.get_code() == lv.EVENT.READY:
        # Move back off screen
        kb.set_pos(0, scr_h + 100)  

# 5. Bind events
textarea.add_event_cb(show_kb, lv.EVENT.CLICKED, None)
kb.add_event_cb(hide_kb, lv.EVENT.READY, None)

# 6. Run
lv.screen_load(scr)
15.2 0-9 6

Tap the text box to bring up the keyboard, then tap the [checkmark] to dismiss the keyboard:

158698 0-9

Pull down to view the keyboard:

1 9 0

15.3 Dual Text Boxes (Standard + Numeric) Sharing a Virtual Keyboard

The following code implements the function of sharing one virtual keyboard for both a regular text box and a numeric text box, with automatic switching of keyboard input modes:

The code is as follows:

import display_driver
import lvgl as lv

# 1. Initialize the environment
lv.init()
scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0x000000), 0)
scr_h = scr.get_height()  # Get the screen height

# 2. Create two text boxes
# 2.1 Plain text box (no character limit)
text_normal = lv.textarea(scr)
text_normal.set_size(380, 50)
text_normal.set_pos(10, 20)
text_normal.set_placeholder_text("Normal text...")
text_normal.set_one_line(True)

# 2.2 Numeric text box (digits only, 6-character limit)
text_number = lv.textarea(scr)
text_number.set_size(380, 50)
text_number.set_pos(10, 90)
text_number.set_placeholder_text("Number only...")
text_number.set_accepted_chars("0123456789")
text_number.set_one_line(True)
text_number.set_max_length(6)

# 3. Create a shared virtual keyboard (initially hidden off-screen)
kb = lv.keyboard(scr)
kb.set_size(400, 200)
kb.set_pos(0, scr_h + 100)  # Initially off-screen

# 4. Keyboard show/hide + binding logic (core: switch the bound text box)
def show_kb_normal(e):
    """Tap the plain text box: bind + show the keyboard (default text mode)"""
    kb.set_textarea(text_normal)
    kb.set_mode(lv.keyboard.MODE.TEXT_LOWER)  # Plain text mode
    kb.set_pos(0, scr_h - 350)  # Move to the bottom of the screen

def show_kb_number(e):
    """Tap the numeric text box: bind + show the keyboard (numeric mode)"""
    kb.set_textarea(text_number)
    kb.set_mode(lv.keyboard.MODE.NUMBER)  # Digits-only mode
    kb.set_pos(0, scr_h - 300)  # Move to the bottom of the screen

def hide_kb(e):
    """Confirm/Enter: hide the keyboard"""
    if e.get_code() == lv.EVENT.READY:
        kb.set_pos(0, scr_h + 100)  # Move back off-screen

# 5. Bind events
text_normal.add_event_cb(show_kb_normal, lv.EVENT.CLICKED, None)
text_number.add_event_cb(show_kb_number, lv.EVENT.CLICKED, None)
kb.add_event_cb(hide_kb, lv.EVENT.READY, None)

# 6. Run
lv.screen_load(scr)
1

Tap the generic text box to bring up the full keyboard; tap the checkmark to dismiss the keyboard.

0

Tap the number box, and the number box will appear; tap the checkmark, and the keyboard will disappear.

Version Record

Version Number

Modifier

Time

Content

v1.0

Li Zisheng

2026/03/23

Initialize the document.