Keyboard (lv_keyboard)

Overview

The Keyboard object is a special Button matrix with predefined keymaps and other features to realize a virtual keyboard to write texts into a Text area.

Parts and Styles

Similarly to Button matrices Keyboards consist of 2 part:

  • LV_PART_MAIN The main part. Uses all the typical background properties

  • LV_PART_ITEMS The buttons. Also uses all typical background properties as well as the text properties.

Usage

Modes

The 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_TEXT_SPECIAL Display special characters

  • LV_KEYBOARD_MODE_NUM Display numbers, +/- sign, and decimal dot.

The TEXT modes' layout contains buttons to change mode.

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

Assign Text area

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, ta).

New Keymap

You can specify a new map (layout) for the keyboard with lv_keyboard_set_map(kb, map) and lv_keyboard_set_ctrl_map(kb, ctrl_map). Learn more about the Button matrix object. Keep in mind that using following keywords will have the same effect as with the original map:

  • LV_SYMBOL_OK Apply.

  • LV_SYMBOL_CLOSE or LV_SYMBOL_KEYBOARD Close.

  • LV_SYMBOL_BACKSPACE Delete on the left.

  • LV_SYMBOL_LEFT Move the cursor left.

  • LV_SYMBOL_RIGHT Move the cursor right.

  • LV_SYMBOL_NEW_LINE New line.

  • "ABC" Load the uppercase map.

  • "abc" Load the lower case map.

  • "1#" Load the lower case map.

Events

  • LV_EVENT_VALUE_CHANGED Sent when the button is pressed/released or repeated after long press. The event data is set to the ID of the pressed/released button.

  • LV_EVENT_READY - The Ok button is clicked.

  • LV_EVENT_CANCEL - The Close button is clicked.

The keyboard has a default event handler callback called lv_keyboard_def_event_cb, which handles the button pressing, map changing, the assigned text area, etc. You can remove it and replace it with a custom event handler if you wish.

Learn more about Events.

Keys

  • LV_KEY_RIGHT/UP/LEFT/RIGHT To navigate among the buttons and select one.

  • LV_KEY_ENTER To press/release the selected button.

Learn more about Keys.

Examples

C

Keyboard with text area

code     view on GitHub

Error encountered while trying to open /home/runner/work/lvgl/lvgl/examples/_widgets/keyboard/lv_example_keyboard_1.c

MicroPython

Keyboard with text area

No examples yet.

API

Typedefs

typedef uint8_t lv_keyboard_mode_t

Enums

enum [anonymous]

Current keyboard mode.

Values:

enumerator LV_KEYBOARD_MODE_TEXT_LOWER
enumerator LV_KEYBOARD_MODE_TEXT_UPPER
enumerator LV_KEYBOARD_MODE_SPECIAL
enumerator LV_KEYBOARD_MODE_NUMBER

Functions

lv_obj_t *lv_keyboard_create(lv_obj_t *parent)

Create a keyboard objects

Parameters

par -- pointer to an object, it will be the parent of the new keyboard

Returns

pointer to the created keyboard

void lv_keyboard_set_textarea(lv_obj_t *kb, lv_obj_t *ta)

Assign a Text Area to the Keyboard. The pressed characters will be put there.

Parameters

  • kb -- pointer to a Keyboard object

  • ta -- pointer to a Text Area object to write there

void lv_keyboard_set_mode(lv_obj_t *kb, lv_keyboard_mode_t mode)

Set a new a mode (text or number map)

Parameters

  • kb -- pointer to a Keyboard object

  • mode -- the mode from 'lv_keyboard_mode_t'

void lv_keyboard_set_map(lv_obj_t *kb, lv_keyboard_mode_t mode, const char *map[], const lv_btnmatrix_ctrl_t ctrl_map[])

Set a new map for the keyboard

Parameters

  • kb -- pointer to a Keyboard object

  • mode -- keyboard map to alter 'lv_keyboard_mode_t'

  • map -- pointer to a string array to describe the map. See 'lv_btnmatrix_set_map()' for more info.

lv_obj_t *lv_keyboard_get_textarea(const lv_obj_t *kb)

Assign a Text Area to the Keyboard. The pressed characters will be put there.

Parameters

kb -- pointer to a Keyboard object

Returns

pointer to the assigned Text Area object

lv_keyboard_mode_t lv_keyboard_get_mode(const lv_obj_t *kb)

Set a new a mode (text or number map)

Parameters

kb -- pointer to a Keyboard object

Returns

the current mode from 'lv_keyboard_mode_t'

static inline const char **lv_keyboard_get_map_array(const lv_obj_t *kb)

Get the current map of a keyboard

Parameters

kb -- pointer to a keyboard object

Returns

the current map

void lv_keyboard_def_event_cb(lv_event_t *e)

Default keyboard event to add characters to the Text area and change the map. If a custom event_cb is added to the keyboard this function be called from it to handle the button clicks

Parameters

  • kb -- pointer to a keyboard

  • event -- the triggering event

Variables

const lv_obj_class_t lv_keyboard_class
struct lv_keyboard_t

Public Members

lv_btnmatrix_t btnm
lv_obj_t *ta
lv_keyboard_mode_t mode