# Keyboard (lv_keyboard) (/widgets/keyboard)



Overview [#overview]

The Keyboard Widget is a special [Button Matrix (lv\_buttonmatrix)](/widgets/buttonmatrix)
with predefined keymaps and other features to provide an on-screen virtual keyboard
to write text into a [Text Area (lv\_textarea)](/widgets/textarea).

Parts and Styles [#parts-and-styles]

Similar to Button Matrix, the Keyboard Widget consists of 2 parts:

* <ApiLink name="LV_PART_MAIN" /> The main part. Uses the [typical background
  style properties](/common-widget-features/styles/overview)
* <ApiLink name="LV_PART_ITEMS" /> The buttons. Also uses the [typical background
  style properties](/common-widget-features/styles/overview) as well as *text* properties.

Usage [#usage]

Modes [#modes]

Keyboards have the following modes:

* <ApiLink name="LV_KEYBOARD_MODE_TEXT_LOWER" /> Display lower case letters
* <ApiLink name="LV_KEYBOARD_MODE_TEXT_UPPER" /> Display upper case letters
* <ApiLink name="LV_KEYBOARD_MODE_SPECIAL" /> Display special characters
* <ApiLink name="LV_KEYBOARD_MODE_NUMBER" /> Display numbers, +/- sign, and decimal dot
* <ApiLink name="LV_KEYBOARD_MODE_USER_1" /> through <ApiLink name="LV_KEYBOARD_MODE_USER_4" /> User-defined modes.

The layouts of the `TEXT` modes contain "keys" to change mode.

To set the mode programmatically, use <ApiLink name="lv_keyboard_set_mode" display="lv_keyboard_set_mode(kb, mode)" />. The
default mode is <ApiLink name="LV_KEYBOARD_MODE_TEXT_UPPER" />.

Assign Text Area [#assign-text-area]

You can assign a [Text area](/widgets/textarea) to the Keyboard to
automatically put the clicked characters there. To assign the Text Area,
use <ApiLink name="lv_keyboard_set_textarea" display="lv_keyboard_set_textarea(kb, text_area)" />.

Key Pop-Overs [#key-pop-overs]

To enable key pop-overs on press, like on common Android and iOS
keyboards, use <ApiLink name="lv_keyboard_set_popovers" display="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 <ApiLink name="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 [#new-keymap]

You can specify a new map (layout) for the Keyboard with
<ApiLink name="lv_keyboard_set_map" display="lv_keyboard_set_map(kb, LV_KEYBOARD_MODE_..., kb_map, kb_ctrl)" />. See
Button Matrix's [Button map](/widgets/buttonmatrix) 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:

* <ApiLink name="LV_SYMBOL_OK" /> Send <ApiLink name="LV_EVENT_READY" /> to the assigned Text Area.
* <ApiLink name="LV_SYMBOL_CLOSE" /> or <ApiLink name="LV_SYMBOL_KEYBOARD" /> Send <ApiLink name="LV_EVENT_CANCEL" /> to the assigned Text Area.
* <ApiLink name="LV_SYMBOL_BACKSPACE" /> Delete character to the left.
* <ApiLink name="LV_SYMBOL_LEFT" /> Move cursor left.
* <ApiLink name="LV_SYMBOL_RIGHT" /> Move cursor right.
* <ApiLink name="LV_SYMBOL_NEW_LINE" /> New line.
* `"ABC"` Load upper-case map.
* `"abc"` Load lower-case map.
* `"1#"` Load number map.

Key customization [#key-customization]

Each key can be customized by using draw events such as <ApiLink name="LV_EVENT_DRAW_TASK_ADDED" />.

Check out the examples to see how it can be used in the practice.

Events [#events]

* <ApiLink name="LV_EVENT_VALUE_CHANGED" /> Sent when the button is pressed/released
  or repeated after long press. The event data contains the ID of the
  pressed/released button.
* <ApiLink name="LV_EVENT_READY" />: The *Ok* button was clicked.
* <ApiLink name="LV_EVENT_CANCEL" />: The *Close* button was clicked.

The Keyboard has a **default event handler** callback called
<ApiLink name="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.

<Callout type="info">
  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.
</Callout>

<Callout type="info" title="Further Reading">
  Learn more about [Events](/common-widget-features/events) emitted by all Widgets.

  Learn more about [events](/common-widget-features/events).
</Callout>

Keys [#keys]

* `LV_KEY_RIGHT/UP/LEFT/RIGHT` To navigate among the buttons,
  selecting the one navigated to.
* <ApiLink name="LV_KEY_ENTER" /> To press/release the selected button.

<Callout type="info" title="Further Reading">
  Learn more about [Keys](/main-modules/indev/keypad).
</Callout>

Examples [#examples]

Keyboard with text area [#keyboard-with-text-area]

<LvglExample name="lv_example_keyboard_1" path="widgets/keyboard/lv_example_keyboard_1" />

Keyboard with custom map [#keyboard-with-custom-map]

<LvglExample name="lv_example_keyboard_2" path="widgets/keyboard/lv_example_keyboard_2" />

Keyboard with drawing [#keyboard-with-drawing]

<LvglExample name="lv_example_keyboard_3" path="widgets/keyboard/lv_example_keyboard_3" />

API [#api]