acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
indev.md (6670B)
      1 ```eval_rst
      2 .. include:: /header.rst
      3 :github_url: |github_link_base|/overview/indev.md
      4 ```
      5 # Input devices
      6 
      7 An input device usually means:
      8 - Pointer-like input device like touchpad or mouse
      9 - Keypads like a normal keyboard or simple numeric keypad
     10 - Encoders with left/right turn and push options
     11 - External hardware buttons which are assigned to specific points on the screen
     12 
     13 
     14 ``` important:: Before reading further, please read the [Porting](/porting/indev) section of Input devices
     15 ```
     16 
     17 ## Pointers
     18 
     19 ### Cursor
     20 
     21 Pointer input devices (like a mouse) can have a cursor.
     22 
     23 ```c
     24 ...
     25 lv_indev_t * mouse_indev = lv_indev_drv_register(&indev_drv);
     26 
     27 LV_IMG_DECLARE(mouse_cursor_icon);                          /*Declare the image source.*/
     28 lv_obj_t * cursor_obj = lv_img_create(lv_scr_act());       /*Create an image object for the cursor */
     29 lv_img_set_src(cursor_obj, &mouse_cursor_icon);             /*Set the image source*/
     30 lv_indev_set_cursor(mouse_indev, cursor_obj);               /*Connect the image  object to the driver*/
     31 ```
     32 
     33 Note that the cursor object should have `lv_obj_clear_flag(cursor_obj, LV_OBJ_FLAG_CLICKABLE)`.
     34 For images, *clicking* is disabled by default.
     35 
     36 ### Gestures
     37 Pointer input devices can detect basic gestures. By default, most of the widgets send the gestures to its parent, so finally the gestures can be detected on the screen object in a form of an `LV_EVENT_GESTURE` event. For example:
     38 
     39 ```c
     40 void my_event(lv_event_t * e)
     41 {
     42   lv_obj_t * screen = lv_event_get_current_target(e);
     43   lv_dir_t dir = lv_indev_get_gesture_dir(lv_indev_act());
     44   switch(dir) {
     45     case LV_DIR_LEFT:
     46       ...
     47       break;
     48     case LV_DIR_RIGHT:
     49       ...
     50       break;
     51     case LV_DIR_TOP:
     52       ...
     53       break;
     54     case LV_DIR_BOTTOM:
     55       ...
     56       break;
     57   }
     58 }
     59 
     60 ...
     61 
     62 lv_obj_add_event_cb(screen1, my_event, LV_EVENT_GESTURE, NULL);
     63 ```
     64 
     65 To prevent passing the gesture event to the parent from an object use `lv_obj_clear_flag(obj, LV_OBJ_FLAG_GESTURE_BUBBLE)`.
     66 
     67 Note that, gestures are not triggered if an object is being scrolled.
     68 
     69 If you did some action on a gesture you can call `lv_indev_wait_release(lv_indev_act())` in the event handler to prevent LVGL sending further input device related events. 
     70 
     71 ## Keypad and encoder
     72 
     73 You can fully control the user interface without a touchpad or mouse by using a keypad or encoder(s). It works similar to the *TAB* key on the PC to select an element in an application or a web page.
     74 
     75 ### Groups
     76 
     77 Objects you want to control with a keypad or encoder need to be added to a *Group*.
     78 In every group there is exactly one focused object which receives the pressed keys or the encoder actions.
     79 For example, if a [Text area](/widgets/core/textarea) is focused and you press some letter on a keyboard, the keys will be sent and inserted into the text area.
     80 Similarly, if a [Slider](/widgets/core/slider) is focused and you press the left or right arrows, the slider's value will be changed.
     81 
     82 You need to associate an input device with a group. An input device can send key events to only one group but a group can receive data from more than one input device.
     83 
     84 To create a group use `lv_group_t * g = lv_group_create()` and to add an object to the group use `lv_group_add_obj(g, obj)`.
     85 
     86 To associate a group with an input device use `lv_indev_set_group(indev, g)`, where `indev` is the return value of `lv_indev_drv_register()`
     87 
     88 #### Keys
     89 There are some predefined keys which have special meaning:
     90 - **LV_KEY_NEXT** Focus on the next object
     91 - **LV_KEY_PREV** Focus on the previous object
     92 - **LV_KEY_ENTER** Triggers `LV_EVENT_PRESSED/CLICKED/LONG_PRESSED` etc. events
     93 - **LV_KEY_UP** Increase value or move upwards
     94 - **LV_KEY_DOWN** Decrease value or move downwards
     95 - **LV_KEY_RIGHT** Increase value or move to the right
     96 - **LV_KEY_LEFT** Decrease value or move to the left
     97 - **LV_KEY_ESC**  Close or exit (E.g. close a [Drop down list](/widgets/core/dropdown))
     98 - **LV_KEY_DEL**  Delete (E.g. a character on the right in a [Text area](/widgets/core/textarea))
     99 - **LV_KEY_BACKSPACE** Delete a character on the left (E.g. in a [Text area](/widgets/core/textarea))
    100 - **LV_KEY_HOME** Go to the beginning/top (E.g. in a [Text area](/widgets/core/textarea))
    101 - **LV_KEY_END** Go to the end (E.g. in a [Text area](/widgets/core/textarea))
    102 
    103 The most important special keys are `LV_KEY_NEXT/PREV`, `LV_KEY_ENTER` and `LV_KEY_UP/DOWN/LEFT/RIGHT`.
    104 In your `read_cb` function, you should translate some of your keys to these special keys to support navigation in a group and interact with selected objects.
    105 
    106 Usually, it's enough to use only `LV_KEY_LEFT/RIGHT` because most objects can be fully controlled with them.
    107 
    108 With an encoder you should use only `LV_KEY_LEFT`, `LV_KEY_RIGHT`, and `LV_KEY_ENTER`.
    109 
    110 #### Edit and navigate mode
    111 
    112 Since a keypad has plenty of keys, it's easy to navigate between objects and edit them using the keypad. But encoders have a limited number of "keys" and hence it is difficult to navigate using the default options. *Navigate* and *Edit* modes are used to avoid this problem with encoders.
    113 
    114 In *Navigate* mode, an encoder's `LV_KEY_LEFT/RIGHT` is translated to `LV_KEY_NEXT/PREV`. Therefore, the next or previous object will be selected by turning the encoder.
    115 Pressing `LV_KEY_ENTER` will change to *Edit* mode.
    116 
    117 In *Edit* mode, `LV_KEY_NEXT/PREV` is usually used to modify an object.
    118 Depending on the object's type, a short or long press of `LV_KEY_ENTER` changes back to *Navigate* mode.
    119 Usually, an object which cannot be pressed (like a [Slider](/widgets/core/slider)) leaves *Edit* mode upon a short click. But with objects where a short click has meaning (e.g. [Button](/widgets/core/btn)), a long press is required.
    120 
    121 #### Default group
    122 Interactive widgets - such as buttons, checkboxes, sliders, etc. - can be automatically added to a default group.
    123 Just create a group with `lv_group_t * g = lv_group_create();` and set the default group with `lv_group_set_default(g);`
    124 
    125 Don't forget to assign one or more input devices to the default group with ` lv_indev_set_group(my_indev, g);`.
    126 
    127 ### Styling
    128 
    129 If an object is focused either by clicking it via touchpad or focused via an encoder or keypad it goes to the `LV_STATE_FOCUSED` state. Hence, focused styles will be applied to it.
    130 
    131 If an object switches to edit mode it enters the `LV_STATE_FOCUSED | LV_STATE_EDITED` states so these style properties will be shown.
    132 
    133 For a more detailed description read the [Style](https://docs.lvgl.io/v7/en/html/overview/style.html) section.
    134 
    135 ## API
    136 
    137 
    138 ### Input device
    139 
    140 ```eval_rst
    141 
    142 .. doxygenfile:: lv_indev.h
    143   :project: lvgl
    144 
    145 ```
    146 
    147 ### Groups
    148 
    149 ```eval_rst
    150 
    151 .. doxygenfile:: lv_group.h
    152   :project: lvgl
    153 
    154 ```