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 propertiesLV_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 lettersLV_KEYBOARD_MODE_TEXT_UPPER
Display upper case lettersLV_KEYBOARD_MODE_TEXT_SPECIAL
Display special charactersLV_KEYBOARD_MODE_NUMBER
Display numbers, +/- sign, and decimal dotLV_KEYBOARD_MODE_USER_1
throughLV_KEYBOARD_MODE_USER_4
User-defined modes.
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)
.
Key Popovers¶
To enable key popovers on press, like on common Android and iOS keyboards, use lv_keyboard_set_popovers(kb, true)
. The default control maps are preconfigured to only show the popovers on keys that produce a symbol and not on e.g. space. If you use a custom keymap, set the LV_BTNMATRIX_CTRL_POPOVER
flag for all keys that you want to show a popover.
Note that popovers 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 so that the popovers can draw over those.
The popovers currently are merely a visual effect and don't allow selecting additional characters such as accents yet.
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
orLV_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
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 one 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¶
-
enumerator LV_KEYBOARD_MODE_USER_1¶
-
enumerator LV_KEYBOARD_MODE_USER_2¶
-
enumerator LV_KEYBOARD_MODE_USER_3¶
-
enumerator LV_KEYBOARD_MODE_USER_4¶
-
enumerator LV_KEYBOARD_MODE_TEXT_LOWER¶
Functions
-
lv_obj_t *lv_keyboard_create(lv_obj_t *parent)¶
Create a Keyboard object
- Parameters
parent -- 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_popovers(lv_obj_t *kb, bool en)¶
Show the button title in a popover when pressed.
- Parameters
kb -- pointer to a Keyboard object
en -- whether "popovers" mode is enabled
-
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'
-
bool lv_btnmatrix_get_popovers(const lv_obj_t *obj)¶
Tell whether "popovers" mode is enabled or not.
- Parameters
kb -- pointer to a Keyboard object
- Returns
true: "popovers" mode is enabled; false: disabled
-
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
-
static inline uint16_t lv_keyboard_get_selected_btn(const lv_obj_t *obj)¶
Get the index of the lastly "activated" button by the user (pressed, released, focused etc) Useful in the
event_cb
to get the text of the button, check if hidden etc.- Parameters
obj -- pointer to button matrix object
- Returns
index of the last released button (LV_BTNMATRIX_BTN_NONE: if unset)
-
static inline const char *lv_keyboard_get_btn_text(const lv_obj_t *obj, uint16_t btn_id)¶
Get the button's text
- Parameters
obj -- pointer to button matrix object
btn_id -- the index a button not counting new line characters.
- Returns
text of btn_index` button
-
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¶