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

Keyboard with text area

Click to try in the MicroPython simulator!
#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     view on GitHub

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