acid-drop

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