Keyboard (lv_keyboard)

On-screen virtual keyboard that writes into a Text Area. Built on top of Button Matrix with preset keymaps.

Overview

The Keyboard is an on-screen virtual keyboard built on top of Button Matrix. It ships with preset keymaps and writes the typed characters into a Text Area.

Styling

Similar to Button Matrix, the Keyboard Widget consists of 2 parts:

LV_PART_MAIN The main part. Uses the typical background style properties
LV_PART_ITEMS The buttons. Also uses the typical background style properties as well as text properties.

Modes

lv_example_keyboard_modes.c

Keyboards have the following modes:

LV_KEYBOARD_MODE_TEXT_LOWER Display lower case letters
LV_KEYBOARD_MODE_TEXT_UPPER Display upper case letters
LV_KEYBOARD_MODE_SPECIAL Display special characters
LV_KEYBOARD_MODE_NUMBER Display numbers, +/- sign, and decimal dot
LV_KEYBOARD_MODE_USER_1 through LV_KEYBOARD_MODE_USER_4 User-defined modes.

The layouts of the TEXT modes contain "keys" to change mode.

To set the mode programmatically, use lv_keyboard_set_mode(kb, mode). The default mode is LV_KEYBOARD_MODE_TEXT_UPPER.

Assign Text Area

lv_example_keyboard_textarea.c

You can assign a Text area to the Keyboard to automatically put the clicked characters there. To assign the Text Area, use lv_keyboard_set_textarea(kb, text_area).

To enable key pop-overs on press, like on common Android and iOS keyboards, use lv_keyboard_set_popovers(kb, true). Default control maps are preconfigured to only show the pop-overs on keys that produce a symbol (i.e. not on space). If you use a custom keymap (see below), set the LV_BUTTONMATRIX_CTRL_POPOVER flag for each key for which a pop-over should be shown.

Note that pop-overs for keys in the top row will draw outside the Widget boundaries. To account for this, reserve extra free space on top of the Keyboard or ensure that the Keyboard is added after any Widgets adjacent to its top boundary (placing it "above" those Widgets) so that pop-overs will be drawn over them.

Pop-overs currently are merely a visual effect and don't allow selecting additional characters such as accented characters yet.

New Keymap

lv_keyboard_set_map(kb, LV_KEYBOARD_MODE_…, kb_map, kb_ctrl) replaces a layout. The two arrays share the shape of a button matrix map (\n for row breaks, terminated with "").

lv_example_keyboard_custom_map.c

Reserved key strings get the same built-in behaviour as in the default maps:

Key string	Behaviour
`LV_SYMBOL_OK`	Send `LV_EVENT_READY` to the textarea.
`LV_SYMBOL_CLOSE` / `LV_SYMBOL_KEYBOARD`	Send `LV_EVENT_CANCEL`.
`LV_SYMBOL_BACKSPACE`	Delete the character before the cursor.
`LV_SYMBOL_LEFT` / `LV_SYMBOL_RIGHT`	Move the cursor.
`LV_SYMBOL_NEW_LINE`	Insert a newline.
`"ABC"` / `"abc"` / `"1#"`	Switch to upper / lower / number map.

Key customization

Each key can be customized by using draw events such as LV_EVENT_DRAW_TASK_ADDED.

The handler receives every draw task the keyboard emits; mutating the fill descriptor recolours the key, and swapping in an image draw lets you replace text glyphs with bitmaps. This example colours each key and substitutes the OK glyph with a star image:

lv_example_keyboard_custom_draw.c

Events

LV_EVENT_VALUE_CHANGED Sent when the button is pressed/released or repeated after long press. The event data contains the ID of the pressed/released button.
LV_EVENT_READY: The Ok button was clicked.
LV_EVENT_CANCEL: The Close button was clicked.

The Keyboard has a default event handler callback called lv_keyboard_def_event_cb, which handles the button pressing, map changing, sending events to the assigned text area, etc. You can remove it and replace it with a custom event handler if you wish, or add an additional call-back of your own.

Learn more about Events emitted by all Widgets.

Keys

LV_KEY_RIGHT/UP/LEFT/RIGHT To navigate among the buttons, selecting the one navigated to.
LV_KEY_ENTER To press/release the selected button.

Learn more about Keys.