1.. _lv_keyboard:
2
3======================
4Keyboard (lv_keyboard)
5======================
6
7
8Overview
9********
10
11The Keyboard Widget is a special :ref:`lv_buttonmatrix`
12with predefined keymaps and other features to provide an on-screen virtual keyboard
13to write text into a :ref:`lv_textarea`.
14
15
16.. _lv_keyboard_parts_and_styles:
17
18Parts and Styles
19****************
20
21Similar to Button Matrix, the Keyboard Widget consist of 2 part:
22
23- :cpp:enumerator:`LV_PART_MAIN` The main part. Uses the :ref:`typical background
24  style properties <typical bg props>`
25- :cpp:enumerator:`LV_PART_ITEMS` The buttons. Also uses the :ref:`typical background
26  style properties <typical bg props>` as well as *text* properties.
27
28
29.. _lv_keyboard_usage:
30
31Usage
32*****
33
34Modes
35-----
36
37Keyboards have the following modes:
38
39- :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_LOWER` Display lower case letters
40- :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_UPPER` Display upper case letters
41- :cpp:enumerator:`LV_KEYBOARD_MODE_SPECIAL` Display special characters
42- :cpp:enumerator:`LV_KEYBOARD_MODE_NUMBER` Display numbers, +/- sign, and decimal dot
43- :cpp:enumerator:`LV_KEYBOARD_MODE_USER_1` through :cpp:enumerator:`LV_KEYBOARD_MODE_USER_4` User-defined modes.
44
45The layouts of the ``TEXT`` modes contain "keys" to change mode.
46
47To set the mode programmatically, use :cpp:expr:`lv_keyboard_set_mode(kb, mode)`. The
48default mode is :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_UPPER`.
49
50Assign Text Area
51----------------
52
53You can assign a :ref:`Text area <lv_textarea>` to the Keyboard to
54automatically put the clicked characters there. To assign the Text Area,
55use :cpp:expr:`lv_keyboard_set_textarea(kb, text_area)`.
56
57Key Pop-Overs
58-------------
59
60To enable key pop-overs on press, like on common Android and iOS
61keyboards, use :cpp:expr:`lv_keyboard_set_popovers(kb, true)`. Default
62control maps are preconfigured to only show the pop-overs on keys that
63produce a symbol (i.e. not on space). If you use a custom keymap (see below), set
64the :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_POPOVER` flag for each key for which
65a pop-over should be shown.
66
67Note that pop-overs for keys in the top row will draw outside the Widget
68boundaries. To account for this, reserve extra free space on top of the
69Keyboard or ensure that the Keyboard is added *after* any Widgets
70adjacent to its top boundary (placing it "above" those Widgets) so that pop-overs
71will be drawn over them.
72
73Pop-overs currently are merely a visual effect and don't allow
74selecting additional characters such as accented characters yet.
75
76New Keymap
77----------
78
79You can specify a new map (layout) for the Keyboard with
80:cpp:expr:`lv_keyboard_set_map(kb, LV_KEYBOARD_MODE_..., kb_map, kb_ctrl)`. See
81Button Matrix's :ref:`button map` section for more information about
82creating new maps.
83
84Keep in mind that using following keywords in the map will have the same effect as
85with the original map:
86
87- :c:macro:`LV_SYMBOL_OK` Send :cpp:enumerator:`LV_EVENT_READY` to the assigned Text Area.
88- :c:macro:`LV_SYMBOL_CLOSE` or :c:macro:`LV_SYMBOL_KEYBOARD` Send :cpp:enumerator:`LV_EVENT_CANCEL` to the assigned Text Area.
89- :c:macro:`LV_SYMBOL_BACKSPACE` Delete character to the left.
90- :c:macro:`LV_SYMBOL_LEFT` Move cursor left.
91- :c:macro:`LV_SYMBOL_RIGHT` Move cursor right.
92- :c:macro:`LV_SYMBOL_NEW_LINE` New line.
93- ``"ABC"`` Load upper-case map.
94- ``"abc"`` Load lower-case map.
95- ``"1#"`` Load number map.
96
97
98
99.. _lv_keyboard_events:
100
101Events
102******
103
104-  :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the button is pressed/released
105   or repeated after long press. The event data contains the ID of the
106   pressed/released button.
107-  :cpp:enumerator:`LV_EVENT_READY`: The *Ok* button was clicked.
108-  :cpp:enumerator:`LV_EVENT_CANCEL`: The *Close* button was clicked.
109
110The Keyboard has a **default event handler** callback called
111:cpp:func:`lv_keyboard_def_event_cb`, which handles the button pressing, map
112changing, sending events to the assigned text area, etc. You can remove it and replace it
113with a custom event handler if you wish, or add an additional call-back of your own.
114
115.. note::
116
117    In LVGL v8.0 and newer, adding an event handler to the Keyboard does not remove the
118    default event handler. This behavior differs from v7, where adding an event
119    handler would replace the previous one.
120
121.. admonition::  Further Reading
122
123    Learn more about :ref:`lv_obj_events` emitted by all Widgets.
124
125    Learn more about :ref:`events`.
126
127
128
129.. _lv_keyboard_keys:
130
131Keys
132****
133
134-  ``LV_KEY_RIGHT/UP/LEFT/RIGHT`` To navigate among the buttons,
135   selecting the one navigated to.
136-  :cpp:enumerator:`LV_KEY_ENTER` To press/release the selected button.
137
138.. admonition::  Further Reading
139
140    Learn more about :ref:`indev_keys`.
141
142
143
144.. _lv_keyboard_example:
145
146Example
147*******
148
149.. include:: ../../examples/widgets/keyboard/index.rst
150
151
152
153.. _lv_keyboard_api:
154
155API
156***
157