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 text.

Parts and Styles¶

Similarly to Button matices Keyboards consist of 2 part:

LV_KEYBOARD_PART_BG which is the main part and uses all the typical background properties
LV_KEYBOARD_PART_BTN which is virtual part for the buttons. It also uses all typical backround proeprties and the text properties.

Usage¶

Modes¶

The Keyboards have thefollowing 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 more 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).

The assigned text area's cursor can be managed by the keyboard: when the keyboard is assigned, the previous text area's cursor will be hidden and the new one will be shown. When the keyboard is closed by the Ok or Close buttons, the cursor also will be hidden. The cursor manager feature is enabled by lv_keyboard_set_cursor_manage(kb, true). The default is not managed.

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 - Close.
LV_SYMBOL_BACKSPACE - Delete on the left.
LV_SYMBOL_LEFT - Move the cursor left.
LV_SYMBOL_RIGHT - Move the cursor right.
"ABC" - Load the uppercase map.
"abc" - Load the lower case map.
"Enter" - New line.

Events¶

Besides the Generic events, the following Special events are sent by the keyboards:

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_APPLY - 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. It handles the button pressing, map changing, the assigned text area, etc. You can completely replace it with your custom event handler however, you can call lv_keyboard_def_event_cb at the beginning of your event handler to handle the same things as before.

Learn more about Events.

Keys¶

The following Keys are processed by the buttons:

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¶

#include "../../../lv_examples.h"
#if LV_USE_KEYBOARD

static lv_obj_t * kb;
static lv_obj_t * ta;


static void kb_event_cb(lv_obj_t * keyboard, lv_event_t e)
{
    lv_keyboard_def_event_cb(kb, e);
    if(e == LV_EVENT_CANCEL) {
        lv_keyboard_set_textarea(kb, NULL);
        lv_obj_del(kb);
        kb = NULL;
    }
}

static void kb_create(void)
{
    kb = lv_keyboard_create(lv_scr_act(), NULL);
    lv_keyboard_set_cursor_manage(kb, true);
    lv_obj_set_event_cb(kb, kb_event_cb);
    lv_keyboard_set_textarea(kb, ta);

}

static void ta_event_cb(lv_obj_t * ta_local, lv_event_t e)
{
    if(e == LV_EVENT_CLICKED && kb == NULL) {
        kb_create();
    }
}

void lv_ex_keyboard_1(void)
{

    /*Create a text area. The keyboard will write here*/
    ta  = lv_textarea_create(lv_scr_act(), NULL);
    lv_obj_align(ta, NULL, LV_ALIGN_IN_TOP_MID, 0, LV_DPI / 16);
    lv_obj_set_event_cb(ta, ta_event_cb);
    lv_textarea_set_text(ta, "");
    lv_coord_t max_h = LV_VER_RES / 2 - LV_DPI / 8;
    if(lv_obj_get_height(ta) > max_h) lv_obj_set_height(ta, max_h);

    kb_create();
}
#endif

MicroPython¶

Keyboard with text area¶

Click to try in the simulator!

LV_DPI=130
LV_VER_RES=240

def event_handler(source,evt):
    if  evt == lv.EVENT.VALUE_CHANGED:
        print("Value:",textarea.get_text())
            
# create a keyboard and apply the styles
keyb = lv.keyboard(lv.scr_act(),None)
keyb.set_cursor_manage(True)

#Create a text area. The keyboard will write here
ta=lv.textarea(lv.scr_act(),None)
ta.align(None,lv.ALIGN.IN_TOP_MID,0,LV_DPI//16)
ta.set_text("")
max_h = LV_VER_RES // 2 - LV_DPI // 8
if ta.get_height() > max_h:
    ta.set_height(max_h)

# Assign the text area to the keyboard*/
keyb.set_textarea(ta)    

API¶

Typedefs

typedef uint8_t lv_keyboard_mode_t¶

typedef uint8_t lv_keyboard_style_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_NUM¶

enumerator LV_KEYBOARD_MODE_TEXT_ARABIC¶

enum [anonymous]¶

Values:

enumerator LV_KEYBOARD_PART_BG¶

enumerator LV_KEYBOARD_PART_BTN¶

Functions

lv_obj_t *lv_keyboard_create(lv_obj_t *par, const lv_obj_t *copy)¶

Create a keyboard objects

Parameters

par -- pointer to an object, it will be the parent of the new keyboard
copy -- pointer to a keyboard object, if not NULL then the new object will be copied from it

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_cursor_manage(lv_obj_t *kb, bool en)¶

Automatically hide or show the cursor of the current Text Area

Parameters

kb -- pointer to a Keyboard object
en -- true: show cursor on the current text area, false: hide cursor

void lv_keyboard_set_map(lv_obj_t *kb, lv_keyboard_mode_t mode, const char *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.

void lv_keyboard_set_ctrl_map(lv_obj_t *kb, lv_keyboard_mode_t mode, const lv_btnmatrix_ctrl_t ctrl_map[])¶

Set the button control map (hidden, disabled etc.) for the keyboard. The control map array will be copied and so may be deallocated after this function returns.

Parameters

kb -- pointer to a keyboard object
mode -- keyboard ctrl map to alter 'lv_keyboard_mode_t'
ctrl_map -- pointer to an array of lv_btn_ctrl_t control bytes. See: lv_btnmatrix_set_ctrl_map for more details.

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'

bool lv_keyboard_get_cursor_manage(const lv_obj_t *kb)¶

Get the current cursor manage mode.

Parameters: kb -- pointer to a Keyboard object
Returns: true: show cursor on the current text area, false: hide cursor

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_obj_t *kb, lv_event_t event)¶

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

struct lv_keyboard_ext_t¶

Public Members

lv_btnmatrix_ext_t btnm¶

lv_obj_t *ta¶

lv_keyboard_mode_t mode¶

uint8_t cursor_mng¶