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