diff options
Diffstat (limited to 'docs/porting/indev.md')
| -rw-r--r-- | docs/porting/indev.md | 94 |
1 files changed, 49 insertions, 45 deletions
diff --git a/docs/porting/indev.md b/docs/porting/indev.md index c90dbbc43..fbe8ffc43 100644 --- a/docs/porting/indev.md +++ b/docs/porting/indev.md @@ -17,21 +17,18 @@ indev_drv.read_cb =... /*See below.*/ lv_indev_t * my_indev = lv_indev_drv_register(&indev_drv); ``` -**type** can be -- **LV_INDEV_TYPE_POINTER** touchpad or mouse -- **LV_INDEV_TYPE_KEYPAD** keyboard or keypad -- **LV_INDEV_TYPE_ENCODER** encoder with left, right, push options -- **LV_INDEV_TYPE_BUTTON** external buttons pressing the screen - -**read_cb** is a function pointer which will be called periodically to report the current state of an input device. -It can also buffer data and return `false` when no more data to be read or `true` when the buffer is not empty. +`type` can be +- `LV_INDEV_TYPE_POINTER` touchpad or mouse +- `LV_INDEV_TYPE_KEYPAD` keyboard or keypad +- `LV_INDEV_TYPE_ENCODER` encoder with left/right turn and push options +- `LV_INDEV_TYPE_BUTTON` external buttons virtually pressing the screen +`read_cb` is a function pointer which will be called periodically to report the current state of an input device. Visit [Input devices](/overview/indev) to learn more about input devices in general. - ### Touchpad, mouse or any pointer -Input devices which can click points of the screen belong to this category. +Input devices that can click points of the screen belong to this category. ```c indev_drv.type = LV_INDEV_TYPE_POINTER; @@ -39,12 +36,15 @@ indev_drv.read_cb = my_input_read; ... -bool my_input_read(lv_indev_drv_t * drv, lv_indev_data_t*data) +void my_input_read(lv_indev_drv_t * drv, lv_indev_data_t*data) { + if(touchpad_pressed) { data->point.x = touchpad_x; data->point.y = touchpad_y; - data->state = LV_INDEV_STATE_PR or LV_INDEV_STATE_REL; - return false; /*No buffering now so no more data read*/ + data->state = LV_INDEV_STATE_PRESSED; + } else { + data->state = LV_INDEV_STATE_RELEASED; + } } ``` @@ -59,7 +59,6 @@ Full keyboards with all the letters or simple keypads with a few navigation butt To use a keyboard/keypad: - Register a `read_cb` function with `LV_INDEV_TYPE_KEYPAD` type. -- Enable `LV_USE_GROUP` in *lv_conf.h* - An object group has to be created: `lv_group_t * g = lv_group_create()` and objects have to be added to it with `lv_group_add_obj(g, obj)` - The created group has to be assigned to an input device: `lv_indev_set_group(my_indev, g)` (`my_indev` is the return value of `lv_indev_drv_register`) - Use `LV_KEY_...` to navigate among the objects in the group. See `lv_core/lv_group.h` for the available keys. @@ -70,13 +69,11 @@ indev_drv.read_cb = keyboard_read; ... -bool keyboard_read(lv_indev_drv_t * drv, lv_indev_data_t*data){ +void keyboard_read(lv_indev_drv_t * drv, lv_indev_data_t*data){ data->key = last_key(); /*Get the last pressed or released key*/ - if(key_pressed()) data->state = LV_INDEV_STATE_PR; - else data->state = LV_INDEV_STATE_REL; - - return false; /*No buffering now so no more data read*/ + if(key_pressed()) data->state = LV_INDEV_STATE_PRESSED; + else data->state = LV_INDEV_STATE_RELEASED; } ``` @@ -103,23 +100,22 @@ indev_drv.read_cb = encoder_read; ... -bool encoder_read(lv_indev_drv_t * drv, lv_indev_data_t*data){ +void encoder_read(lv_indev_drv_t * drv, lv_indev_data_t*data){ data->enc_diff = enc_get_new_moves(); - if(enc_pressed()) data->state = LV_INDEV_STATE_PR; - else data->state = LV_INDEV_STATE_REL; - - return false; /*No buffering now so no more data read*/ + if(enc_pressed()) data->state = LV_INDEV_STATE_PRESSED; + else data->state = LV_INDEV_STATE_RELEASED; } ``` + #### Using buttons with Encoder logic -In addition to standard encoder behavior, you can also utilise its logic to navigate(focus) and edit widgets using buttons. -This is especially handy if you have only few buttons avalible, or you want to use other buttons in addition to encoder wheel. +In addition to standard encoder behavior, you can also utilize its logic to navigate(focus) and edit widgets using buttons. +This is especially handy if you have only few buttons available, or you want to use other buttons in addition to encoder wheel. -You need to have 3 buttons avalible: -- **LV_KEY_ENTER** will simulate press or pushing of the encoder button -- **LV_KEY_LEFT** will simulate turnuing encoder left -- **LV_KEY_RIGHT** will simulate turnuing encoder right +You need to have 3 buttons available: +- `LV_KEY_ENTER` will simulate press or pushing of the encoder button +- `LV_KEY_LEFT` will simulate turning encoder left +- `LV_KEY_RIGHT` will simulate turning encoder right - other keys will be passed to the focused widget If you hold the keys it will simulate encoder click with period specified in `indev_drv.long_press_rep_time`. @@ -133,9 +129,9 @@ indev_drv.read_cb = encoder_with_keys_read; bool encoder_with_keys_read(lv_indev_drv_t * drv, lv_indev_data_t*data){ data->key = last_key(); /*Get the last pressed or released key*/ /* use LV_KEY_ENTER for encoder press */ - if(key_pressed()) data->state = LV_INDEV_STATE_PR; + if(key_pressed()) data->state = LV_INDEV_STATE_PRESSED; else { - data->state = LV_INDEV_STATE_REL; + data->state = LV_INDEV_STATE_RELEASED; /* Optionally you can also use enc_diff, if you have encoder*/ data->enc_diff = enc_get_new_moves(); } @@ -160,38 +156,46 @@ indev_drv.read_cb = button_read; ... -bool button_read(lv_indev_drv_t * drv, lv_indev_data_t*data){ +void button_read(lv_indev_drv_t * drv, lv_indev_data_t*data){ static uint32_t last_btn = 0; /*Store the last pressed button*/ int btn_pr = my_btn_read(); /*Get the ID (0,1,2...) of the pressed button*/ if(btn_pr >= 0) { /*Is there a button press? (E.g. -1 indicated no button was pressed)*/ last_btn = btn_pr; /*Save the ID of the pressed button*/ - data->state = LV_INDEV_STATE_PR; /*Set the pressed state*/ + data->state = LV_INDEV_STATE_PRESSED; /*Set the pressed state*/ } else { - data->state = LV_INDEV_STATE_REL; /*Set the released state*/ + data->state = LV_INDEV_STATE_RELEASED; /*Set the released state*/ } data->btn = last_btn; /*Save the last button*/ - - return false; /*No buffering now so no more data read*/ } ``` ## Other features -Besides `read_cb` a `feedback_cb` callback can be also specified in `lv_indev_drv_t`. -`feedback_cb` is called when any type of event is sent by the input devices. (independently from its type). It allows making feedback for the user e.g. to play a sound on `LV_EVENT_CLICK`. +### Parameters -The default value of the following parameters can be set in *lv_conf.h* but the default value can be overwritten in `lv_indev_drv_t`: -- **drag_limit** Number of pixels to slide before actually drag the object -- **drag_throw** Drag throw slow-down in [%]. Greater value means faster slow-down -- **long_press_time** Press time to send `LV_EVENT_LONG_PRESSED` (in milliseconds) -- **long_press_rep_time** Interval of sending `LV_EVENT_LONG_PRESSED_REPEAT` (in milliseconds) -- **read_task** pointer to the `lv_task` which reads the input device. Its parameters can be changed by `lv_task_...()` functions +The default value of the following parameters can changed in `lv_indev_drv_t`: +- `scroll_limit` Number of pixels to slide before actually scrolling the object. +- `scroll_throw` Scroll throw (momentum) slow-down in [%]. Greater value means faster slow-down. +- `long_press_time` Press time to send `LV_EVENT_LONG_PRESSED` (in milliseconds) +- `long_press_rep_time` Interval of sending `LV_EVENT_LONG_PRESSED_REPEAT` (in milliseconds) +- `read_timer` pointer to the `lv_rimer` which reads the input device. Its parameters can be changed by `lv_timer_...()` functions. `LV_INDEV_DEF_READ_PERIOD` in `lv_conf.h` sets the default read period. +### Feedback +Besides `read_cb` a `feedback_cb` callback can be also specified in `lv_indev_drv_t`. +`feedback_cb` is called when any type of event is sent by the input devices. (independently from its type). It allows making feedback for the user e.g. to play a sound on `LV_EVENT_CLICKED`. + + +### Associating with a display Every Input device is associated with a display. By default, a new input device is added to the lastly created or the explicitly selected (using `lv_disp_set_default()`) display. The associated display is stored and can be changed in `disp` field of the driver. +### Event driven reading +By default LVGL calls `read_cb` periodically. This way there is a chance that some user gestures are missed. + +To solve this you write an event driven driver for your input device that buffers measured data. In `read_cb` you can set the buffered data instead of reading the input device. +You can set the `data->continue_reding` flag to LVGL there is more data to read and call `read_cb` again. ## API |