mirror of
https://github.com/lvgl/lvgl.git
synced 2025-02-04 07:13:00 +08:00
155 lines
4.7 KiB
ReStructuredText
155 lines
4.7 KiB
ReStructuredText
.. _lv_keyboard:
|
|
|
|
======================
|
|
Keyboard (lv_keyboard)
|
|
======================
|
|
|
|
|
|
Overview
|
|
********
|
|
|
|
The Keyboard Widget is a special :ref:`lv_buttonmatrix`
|
|
with predefined keymaps and other features to provide an on-screen virtual keyboard
|
|
to write text into a :ref:`lv_textarea`.
|
|
|
|
|
|
.. _lv_keyboard_parts_and_styles:
|
|
|
|
Parts and Styles
|
|
****************
|
|
|
|
Similar to Button Matrix, the Keyboard Widget consist of 2 part:
|
|
|
|
- :cpp:enumerator:`LV_PART_MAIN` The main part. Uses all the typical background properties
|
|
- :cpp:enumerator:`LV_PART_ITEMS` The buttons. Also uses all typical background properties as well as *text* properties.
|
|
|
|
|
|
.. _lv_keyboard_usage:
|
|
|
|
Usage
|
|
*****
|
|
|
|
Modes
|
|
-----
|
|
|
|
Keyboards have the following modes:
|
|
|
|
- :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_LOWER` Display lower case letters
|
|
- :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_UPPER` Display upper case letters
|
|
- :cpp:enumerator:`LV_KEYBOARD_MODE_SPECIAL` Display special characters
|
|
- :cpp:enumerator:`LV_KEYBOARD_MODE_NUMBER` Display numbers, +/- sign, and decimal dot
|
|
- :cpp:enumerator:`LV_KEYBOARD_MODE_USER_1` through :cpp:enumerator:`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 :cpp:expr:`lv_keyboard_set_mode(kb, mode)`. The
|
|
default mode is :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_UPPER`.
|
|
|
|
Assign Text Area
|
|
----------------
|
|
|
|
You can assign a :ref:`Text Area <lv_textarea>` Widget to the Keyboard to
|
|
automatically put the clicked characters there. To assign the Text Area,
|
|
use :cpp:expr:`lv_keyboard_set_textarea(kb, text_area)`.
|
|
|
|
Key Pop-Overs
|
|
-------------
|
|
|
|
To enable key pop-overs on press, like on common Android and iOS
|
|
keyboards, use :cpp:expr:`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 :cpp:enumerator:`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
|
|
----------
|
|
|
|
You can specify a new map (layout) for the Keyboard with
|
|
:cpp:expr:`lv_keyboard_set_map(kb, LV_KEYBOARD_MODE_..., kb_map, kb_ctrl)`. See
|
|
Button Matrix's :ref:`button map` 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:
|
|
|
|
- :c:macro:`LV_SYMBOL_OK` Send :cpp:enumerator:`LV_EVENT_READY` to the assigned Text Area.
|
|
- :c:macro:`LV_SYMBOL_CLOSE` or :c:macro:`LV_SYMBOL_KEYBOARD` Send :cpp:enumerator:`LV_EVENT_CANCEL` to the assigned Text Area.
|
|
- :c:macro:`LV_SYMBOL_BACKSPACE` Delete character to the left.
|
|
- :c:macro:`LV_SYMBOL_LEFT` Move cursor left.
|
|
- :c:macro:`LV_SYMBOL_RIGHT` Move cursor right.
|
|
- :c:macro:`LV_SYMBOL_NEW_LINE` New line.
|
|
- ``"ABC"`` Load upper-case map.
|
|
- ``"abc"`` Load lower-case map.
|
|
- ``"1#"`` Load number map.
|
|
|
|
|
|
|
|
.. _lv_keyboard_events:
|
|
|
|
Events
|
|
******
|
|
|
|
- :cpp:enumerator:`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.
|
|
- :cpp:enumerator:`LV_EVENT_READY`: The *Ok* button was clicked.
|
|
- :cpp:enumerator:`LV_EVENT_CANCEL`: The *Close* button was clicked.
|
|
|
|
The Keyboard has a **default event handler** callback called
|
|
:cpp:func:`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.
|
|
|
|
.. note::
|
|
|
|
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.
|
|
|
|
.. admonition:: Further Reading
|
|
|
|
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
|
|
|
|
Learn more about :ref:`events`.
|
|
|
|
|
|
|
|
.. _lv_keyboard_keys:
|
|
|
|
Keys
|
|
****
|
|
|
|
- ``LV_KEY_RIGHT/UP/LEFT/RIGHT`` To navigate among the buttons,
|
|
selecting the one navigated to.
|
|
- :cpp:enumerator:`LV_KEY_ENTER` To press/release the selected button.
|
|
|
|
.. admonition:: Further Reading
|
|
|
|
Learn more about :ref:`indev_keys`.
|
|
|
|
|
|
|
|
.. _lv_keyboard_example:
|
|
|
|
Example
|
|
*******
|
|
|
|
.. include:: ../../examples/widgets/keyboard/index.rst
|
|
|
|
|
|
|
|
.. _lv_keyboard_api:
|
|
|
|
API
|
|
***
|