Input device interface¶
Types of input devices¶
To register an input device an lv_indev_drv_t
variable has to be initialized. Be sure to register at least one display before you register any input devices.
lv_disp_drv_register(&disp_drv);
static lv_indev_drv_t indev_drv;
lv_indev_drv_init(&indev_drv); /*Basic initialization*/
indev_drv.type =... /*See below.*/
indev_drv.read_cb =... /*See below.*/
/*Register the driver in LVGL and save the created input device object*/
lv_indev_t * my_indev = lv_indev_drv_register(&indev_drv);
The type
member can be:
LV_INDEV_TYPE_POINTER
touchpad or mouseLV_INDEV_TYPE_KEYPAD
keyboard or keypadLV_INDEV_TYPE_ENCODER
encoder with left/right turn and push optionsLV_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 to learn more about input devices in general.
Touchpad, mouse or any pointer¶
Input devices that can click points on the screen belong to this category.
indev_drv.type = LV_INDEV_TYPE_POINTER;
indev_drv.read_cb = my_input_read;
...
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_PRESSED;
} else {
data->state = LV_INDEV_STATE_RELEASED;
}
}
To set a mouse cursor use lv_indev_set_cursor(my_indev, &img_cursor)
. (my_indev
is the return value of lv_indev_drv_register
)
Keypad or keyboard¶
Full keyboards with all the letters or simple keypads with a few navigation buttons belong here.
To use a keyboard/keypad:
Register a
read_cb
function withLV_INDEV_TYPE_KEYPAD
type.An object group has to be created:
lv_group_t * g = lv_group_create()
and objects have to be added to it withlv_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 oflv_indev_drv_register
)Use
LV_KEY_...
to navigate among the objects in the group. Seelv_core/lv_group.h
for the available keys.
indev_drv.type = LV_INDEV_TYPE_KEYPAD;
indev_drv.read_cb = keyboard_read;
...
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_PRESSED;
else data->state = LV_INDEV_STATE_RELEASED;
}
Encoder¶
With an encoder you can do the following:
Press its button
Long-press its button
Turn left
Turn right
In short, the Encoder input devices work like this:
By turning the encoder you can focus on the next/previous object.
When you press the encoder on a simple object (like a button), it will be clicked.
If you press the encoder on a complex object (like a list, message box, etc.) the object will go to edit mode whereby you can navigate inside the object by turning the encoder.
To leave edit mode, long press the button.
To use an Encoder (similarly to the Keypads) the objects should be added to groups.
indev_drv.type = LV_INDEV_TYPE_ENCODER;
indev_drv.read_cb = encoder_read;
...
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_PRESSED;
else data->state = LV_INDEV_STATE_RELEASED;
}
Using buttons with Encoder logic¶
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 available:
LV_KEY_ENTER
will simulate press or pushing of the encoder buttonLV_KEY_LEFT
will simulate turning encoder leftLV_KEY_RIGHT
will simulate turning encoder rightother keys will be passed to the focused widget
If you hold the keys it will simulate an encoder advance with period specified in indev_drv.long_press_rep_time
.
indev_drv.type = LV_INDEV_TYPE_ENCODER;
indev_drv.read_cb = encoder_with_keys_read;
...
void 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_PRESSED;
else {
data->state = LV_INDEV_STATE_RELEASED;
/* Optionally you can also use enc_diff, if you have encoder*/
data->enc_diff = enc_get_new_moves();
}
}
Button¶
Buttons mean external "hardware" buttons next to the screen which are assigned to specific coordinates of the screen. If a button is pressed it will simulate the pressing on the assigned coordinate. (Similarly to a touchpad)
To assign buttons to coordinates use lv_indev_set_button_points(my_indev, points_array)
.points_array
should look like const lv_point_t points_array[] = { {12,30},{60,90}, ...}
Important
The points_array can't go out of scope. Either declare it as a global variable or as a static variable inside a function.
indev_drv.type = LV_INDEV_TYPE_BUTTON;
indev_drv.read_cb = button_read;
...
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_PRESSED; /*Set the pressed state*/
} else {
data->state = LV_INDEV_STATE_RELEASED; /*Set the released state*/
}
data->btn = last_btn; /*Save the last button*/
}
Other features¶
Parameters¶
The default value of the following parameters can be 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 sendLV_EVENT_LONG_PRESSED
(in milliseconds)long_press_rep_time
Interval of sendingLV_EVENT_LONG_PRESSED_REPEAT
(in milliseconds)read_timer
pointer to thelv_timer
which reads the input device. Its parameters can be changed bylv_timer_...()
functions.LV_INDEV_DEF_READ_PERIOD
inlv_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 of its type). This allows generating 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 last display created or explicitly selected (using lv_disp_set_default()
).
The associated display is stored and can be changed in disp
field of the driver.
Buffered reading¶
By default, LVGL calls read_cb
periodically. Because of this intermittent polling there is a chance that some user gestures are missed.
To solve this you can write an event driven driver for your input device that buffers measured data. In read_cb
you can report the buffered data instead of directly reading the input device.
Setting the data->continue_reading
flag will tell LVGL there is more data to read and it should call read_cb
again.
Further reading¶
lv_port_indev_template.c for a template for your own driver.
INdev features to learn more about higher level input device features.
API¶
@description Input Device HAL interface layer header file
Typedefs
-
typedef struct _lv_indev_drv_t lv_indev_drv_t¶
Initialized by the user and registered by 'lv_indev_add()'
-
typedef struct _lv_indev_proc_t _lv_indev_proc_t¶
Run time data of input devices Internally used by the library, you should not need to touch it.
-
typedef struct _lv_indev_t lv_indev_t¶
The main input device descriptor with driver, runtime data ('proc') and some additional information
Enums
-
enum lv_indev_type_t¶
Possible input device types
Values:
-
enumerator LV_INDEV_TYPE_NONE¶
Uninitialized state
-
enumerator LV_INDEV_TYPE_POINTER¶
Touch pad, mouse, external button
-
enumerator LV_INDEV_TYPE_KEYPAD¶
Keypad or keyboard
-
enumerator LV_INDEV_TYPE_BUTTON¶
External (hardware button) which is assigned to a specific point of the screen
-
enumerator LV_INDEV_TYPE_ENCODER¶
Encoder with only Left, Right turn and a Button
-
enumerator LV_INDEV_TYPE_NONE¶
Functions
-
void lv_indev_drv_init(struct _lv_indev_drv_t *driver)¶
Initialize an input device driver with default values. It is used to surely have known values in the fields and not memory junk. After it you can set the fields.
- Parameters
driver -- pointer to driver variable to initialize
-
lv_indev_t *lv_indev_drv_register(struct _lv_indev_drv_t *driver)¶
Register an initialized input device driver.
- Parameters
driver -- pointer to an initialized 'lv_indev_drv_t' variable (can be local variable)
- Returns
pointer to the new input device or NULL on error
-
void lv_indev_drv_update(lv_indev_t *indev, struct _lv_indev_drv_t *new_drv)¶
Update the driver in run time.
- Parameters
indev -- pointer to an input device. (return value of
lv_indev_drv_register
)new_drv -- pointer to the new driver
-
void lv_indev_delete(lv_indev_t *indev)¶
Remove the provided input device. Make sure not to use the provided input device afterwards anymore.
- Parameters
indev -- pointer to delete
-
lv_indev_t *lv_indev_get_next(lv_indev_t *indev)¶
Get the next input device.
- Parameters
indev -- pointer to the current input device. NULL to initialize.
- Returns
the next input device or NULL if there are no more. Provide the first input device when the parameter is NULL
-
void _lv_indev_read(lv_indev_t *indev, lv_indev_data_t *data)¶
Read data from an input device.
- Parameters
indev -- pointer to an input device
data -- input device will write its data here
-
struct lv_indev_data_t¶
- #include <lv_hal_indev.h>
Data structure passed to an input driver to fill
Public Members
-
lv_point_t point¶
For LV_INDEV_TYPE_POINTER the currently pressed point
-
uint32_t key¶
For LV_INDEV_TYPE_KEYPAD the currently pressed key
-
uint32_t btn_id¶
For LV_INDEV_TYPE_BUTTON the currently pressed button
-
int16_t enc_diff¶
For LV_INDEV_TYPE_ENCODER number of steps since the previous read
-
lv_indev_state_t state¶
LV_INDEV_STATE_REL or LV_INDEV_STATE_PR
-
bool continue_reading¶
If set to true, the read callback is invoked again
-
lv_point_t point¶
-
struct _lv_indev_drv_t¶
- #include <lv_hal_indev.h>
Initialized by the user and registered by 'lv_indev_add()'
Public Members
-
lv_indev_type_t type¶
< Input device type Function pointer to read input device data.
-
void (*read_cb)(struct _lv_indev_drv_t *indev_drv, lv_indev_data_t *data)¶
-
void (*feedback_cb)(struct _lv_indev_drv_t*, uint8_t)¶
Called when an action happened on the input device. The second parameter is the event from
lv_event_t
-
void *user_data¶
-
struct _lv_disp_t *disp¶
< Pointer to the assigned display Timer to periodically read the input device
-
lv_timer_t *read_timer¶
Number of pixels to slide before actually drag the object
-
uint8_t scroll_limit¶
Drag throw slow-down in [%]. Greater value means faster slow-down
-
uint8_t scroll_throw¶
At least this difference should be between two points to evaluate as gesture
-
uint8_t gesture_min_velocity¶
At least this difference should be to send a gesture
-
uint8_t gesture_limit¶
Long press time in milliseconds
-
uint16_t long_press_time¶
Repeated trigger period in long press [ms]
-
uint16_t long_press_repeat_time¶
-
lv_indev_type_t type¶
-
struct _lv_indev_proc_t
- #include <lv_hal_indev.h>
Run time data of input devices Internally used by the library, you should not need to touch it.
Public Members
-
lv_indev_state_t state¶
Current state of the input device.
-
uint8_t long_pr_sent¶
-
uint8_t reset_query¶
-
uint8_t disabled¶
-
uint8_t wait_until_release¶
-
lv_point_t act_point¶
Current point of input device.
-
lv_point_t last_point¶
Last point of input device.
-
lv_point_t last_raw_point¶
Last point read from read_cb.
-
lv_point_t vect¶
Difference between
act_point
andlast_point
.
-
lv_point_t scroll_sum¶
-
lv_point_t scroll_throw_vect¶
-
lv_point_t scroll_throw_vect_ori¶
-
lv_area_t scroll_area¶
-
lv_point_t gesture_sum¶
-
lv_dir_t scroll_dir¶
-
lv_dir_t gesture_dir¶
-
uint8_t gesture_sent¶
-
struct _lv_indev_proc_t::[anonymous]::[anonymous] pointer¶
-
lv_indev_state_t last_state¶
-
uint32_t last_key¶
-
struct _lv_indev_proc_t::[anonymous]::[anonymous] keypad¶
-
union _lv_indev_proc_t::[anonymous] types¶
-
uint32_t pr_timestamp¶
Pressed time stamp
-
uint32_t longpr_rep_timestamp¶
Long press repeat time stamp
-
lv_indev_state_t state¶
-
struct _lv_indev_t¶
- #include <lv_hal_indev.h>
The main input device descriptor with driver, runtime data ('proc') and some additional information
Public Members
-
struct _lv_indev_drv_t *driver¶
-
_lv_indev_proc_t proc¶
-
struct _lv_group_t *group¶
Keypad destination group
-
const lv_point_t *btn_points¶
Array points assigned to the button ()screen will be pressed here by the buttons
-
struct _lv_indev_drv_t *driver¶