Keyboard (lv_keyboard)

Overview

The Keyboard Widget is a special Button Matrix (lv_buttonmatrix) with predefined keymaps and other features to provide an on-screen virtual keyboard to write text into a Text Area (lv_textarea).

Parts and Styles

Similar to Button Matrix, the Keyboard Widget 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 text properties.

Usage

Modes

Keyboards have the following 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

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

Key Pop-Overs

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

You can specify a new map (layout) for the Keyboard with lv_keyboard_set_map(kb, LV_KEYBOARD_MODE_..., kb_map, kb_ctrl). See Button Matrix's Button map section for more information about creating new maps.

Keep in mind that using following keywords in the map will have the same effect as with the original map:

Events

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.

Note

In LVGL v8.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 replace the previous one.

Further Reading

Learn more about Base-Widget Events emitted by all Widgets.

Learn more about Events.

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.

Further Reading

Learn more about Keys.

Example

Keyboard with text area

#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_remove_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_screen_active());

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

    lv_obj_t * ta2;
    ta2 = lv_textarea_create(lv_screen_active());
    lv_obj_align(ta2, LV_ALIGN_TOP_RIGHT, -10, 10);
    lv_obj_add_event_cb(ta2, ta_event_cb, LV_EVENT_ALL, kb);
    lv_obj_set_size(ta2, 140, 80);

    lv_keyboard_set_textarea(kb, ta1);

    /*The keyboard will show Arabic characters if they are enabled */
#if LV_USE_ARABIC_PERSIAN_CHARS && LV_FONT_DEJAVU_16_PERSIAN_HEBREW
    lv_obj_set_style_text_font(kb, &lv_font_dejavu_16_persian_hebrew, 0);
    lv_obj_set_style_text_font(ta1, &lv_font_dejavu_16_persian_hebrew, 0);
    lv_obj_set_style_text_font(ta2, &lv_font_dejavu_16_persian_hebrew, 0);
#endif
}
#endif

Keyboard with custom map

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

void lv_example_keyboard_2(void)
{
    /*Create an AZERTY keyboard map*/
    static const char * kb_map[] = {"A", "Z", "E", "R", "T", "Y", "U", "I", "O", "P", LV_SYMBOL_BACKSPACE, "\n",
                                    "Q", "S", "D", "F", "G", "J", "K", "L", "M",  LV_SYMBOL_NEW_LINE, "\n",
                                    "W", "X", "C", "V", "B", "N", ",", ".", ":", "!", "?", "\n",
                                    LV_SYMBOL_CLOSE, " ",  " ", " ", LV_SYMBOL_OK, NULL
                                   };

    /*Set the relative width of the buttons and other controls*/
    static const lv_buttonmatrix_ctrl_t kb_ctrl[] = {4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 6,
                                                     4, 4, 4, 4, 4, 4, 4, 4, 4, 6,
                                                     4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4,
                                                     2, LV_BUTTONMATRIX_CTRL_HIDDEN | 2, 6, LV_BUTTONMATRIX_CTRL_HIDDEN | 2, 2
                                                    };

    /*Create a keyboard and add the new map as USER_1 mode*/
    lv_obj_t * kb = lv_keyboard_create(lv_screen_active());

    lv_keyboard_set_map(kb, LV_KEYBOARD_MODE_USER_1, kb_map, kb_ctrl);
    lv_keyboard_set_mode(kb, LV_KEYBOARD_MODE_USER_1);

    /*Create a text area. The keyboard will write here*/
    lv_obj_t * ta;
    ta = lv_textarea_create(lv_screen_active());
    lv_obj_align(ta, LV_ALIGN_TOP_MID, 0, 10);
    lv_obj_set_size(ta, lv_pct(90), 80);
    lv_obj_add_state(ta, LV_STATE_FOCUSED);

    lv_keyboard_set_textarea(kb, ta);
}
#endif

API

lv_keyboard.h

lv_obj_property_names.h

lv_api_map_v8.h

lv_types.h