1 2 3# Keyboard (lv_keyboard) 4 5## Overview 6 7The Keyboard object is a special [Button matrix](/widgets/core/btnmatrix) with predefined keymaps and other features to realize a virtual keyboard to write texts into a [Text area](/widgets/core/textarea). 8 9## Parts and Styles 10Similarly to Button matrices Keyboards consist of 2 part: 11- `LV_PART_MAIN` The main part. Uses all the typical background properties 12- `LV_PART_ITEMS` The buttons. Also uses all typical background properties as well as the *text* properties. 13 14## Usage 15 16### Modes 17The Keyboards have the following modes: 18- `LV_KEYBOARD_MODE_TEXT_LOWER` Display lower case letters 19- `LV_KEYBOARD_MODE_TEXT_UPPER` Display upper case letters 20- `LV_KEYBOARD_MODE_TEXT_SPECIAL` Display special characters 21- `LV_KEYBOARD_MODE_NUMBER` Display numbers, +/- sign, and decimal dot 22- `LV_KEYBOARD_MODE_USER_1` through `LV_KEYBOARD_MODE_USER_4` User-defined modes. 23 24The `TEXT` modes' layout contains buttons to change mode. 25 26To set the mode manually, use `lv_keyboard_set_mode(kb, mode)`. The default mode is `LV_KEYBOARD_MODE_TEXT_UPPER`. 27 28### Assign Text area 29You can assign a [Text area](/widgets/core/textarea) to the Keyboard to automatically put the clicked characters there. 30To assign the text area, use `lv_keyboard_set_textarea(kb, ta)`. 31 32### Key Popovers 33To 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. 34 35Note 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. 36 37The popovers currently are merely a visual effect and don't allow selecting additional characters such as accents yet. 38 39### New Keymap 40You 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)`. 41Learn more about the [Button matrix](/widgets/core/btnmatrix) object. 42Keep in mind that using following keywords will have the same effect as with the original map: 43- `LV_SYMBOL_OK` Apply. 44- `LV_SYMBOL_CLOSE` or `LV_SYMBOL_KEYBOARD` Close. 45- `LV_SYMBOL_BACKSPACE` Delete on the left. 46- `LV_SYMBOL_LEFT` Move the cursor left. 47- `LV_SYMBOL_RIGHT` Move the cursor right. 48- `LV_SYMBOL_NEW_LINE` New line. 49- *"ABC"* Load the uppercase map. 50- *"abc"* Load the lower case map. 51- *"1#"* Load the lower case map. 52 53## Events 54- `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. 55- `LV_EVENT_READY` - The *Ok* button is clicked. 56- `LV_EVENT_CANCEL` - The *Close* button is clicked. 57 58The 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. 59 60```eval_rst 61.. note:: 62 In 8.0 and newer, adding an event handler to the keyboard does not remove the default event handler. 63 This behavior differs from v7, where adding an event handler would always replace the previous one. 64``` 65 66 67Learn more about [Events](/overview/event). 68 69## Keys 70- `LV_KEY_RIGHT/UP/LEFT/RIGHT` To navigate among the buttons and select one. 71- `LV_KEY_ENTER` To press/release the selected button. 72 73Learn more about [Keys](/overview/indev). 74 75 76## Examples 77 78 79```eval_rst 80 81.. include:: ../../../examples/widgets/keyboard/index.rst 82 83``` 84 85## API 86 87```eval_rst 88 89.. doxygenfile:: lv_keyboard.h 90 :project: lvgl 91 92``` 93
