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

Note

In 8.0 and newer, adding an event handler to the keyboard does not remove the default event handler. This behavior differs from v7, where adding an event handler would always replace the previous one.

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

Keyboard with text area

C code  

 GitHub
#include "../../lv_examples.h"
#if LV_USE_KEYBOARD && LV_BUILD_EXAMPLES

static void ta_event_cb(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * ta = lv_event_get_target(e);
    lv_obj_t * kb = lv_event_get_user_data(e);
    if(code == LV_EVENT_FOCUSED) {
        lv_keyboard_set_textarea(kb, ta);
        lv_obj_clear_flag(kb, LV_OBJ_FLAG_HIDDEN);
    }

    if(code == LV_EVENT_DEFOCUSED) {
        lv_keyboard_set_textarea(kb, NULL);
        lv_obj_add_flag(kb, LV_OBJ_FLAG_HIDDEN);
    }
}

void lv_example_keyboard_1(void)
{
    /*Create a keyboard to use it with an of the text areas*/
    lv_obj_t *kb = lv_keyboard_create(lv_scr_act());

    /*Create a text area. The keyboard will write here*/
    lv_obj_t * ta;
    ta = lv_textarea_create(lv_scr_act());
    lv_obj_align(ta, LV_ALIGN_TOP_LEFT, 10, 10);
    lv_obj_add_event_cb(ta, ta_event_cb, LV_EVENT_ALL, kb);
    lv_textarea_set_placeholder_text(ta, "Hello");
    lv_obj_set_size(ta, 140, 80);

    ta = lv_textarea_create(lv_scr_act());
    lv_obj_align(ta, LV_ALIGN_TOP_RIGHT, -10, 10);
    lv_obj_add_event_cb(ta, ta_event_cb, LV_EVENT_ALL, kb);
    lv_obj_set_size(ta, 140, 80);

    lv_keyboard_set_textarea(kb, ta);
}
#endif

MicroPython code  

 GitHub Simulator
def ta_event_cb(e,kb):
    code = e.get_code()
    ta = e.get_target()
    if code == lv.EVENT.FOCUSED:
        kb.set_textarea(ta)
        kb.clear_flag(lv.obj.FLAG.HIDDEN)

    if code == lv.EVENT.DEFOCUSED:
        kb.set_textarea(None)
        kb.add_flag(lv.obj.FLAG.HIDDEN)
        
# Create a keyboard to use it with an of the text areas
kb = lv.keyboard(lv.scr_act())

# Create a text area. The keyboard will write here
ta = lv.textarea(lv.scr_act())
ta.set_width(200)
ta.align(lv.ALIGN.TOP_LEFT, 10, 10)
ta.add_event_cb(lambda e: ta_event_cb(e,kb), lv.EVENT.ALL, None)
ta.set_placeholder_text("Hello")

ta = lv.textarea(lv.scr_act())
ta.set_width(200)
ta.align(lv.ALIGN.TOP_RIGHT, -10, 10)
ta.add_event_cb(lambda e: ta_event_cb(e,kb), lv.EVENT.ALL, None)

kb.set_textarea(ta)


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 can 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