Input devices¶

An input device usually means:

Pointer-like input device like touchpad or mouse
Keypads like a normal keyboard or simple numeric keypad
Encoders with left/right turn and push options
External hardware buttons which are assigned to specific points on the screen

Important

Before reading further, please read the [Porting](/porting/indev) section of Input devices

Pointers¶

Pointer input devices can have a cursor. (typically for mouses)

...
lv_indev_t * mouse_indev = lv_indev_drv_register(&indev_drv);

LV_IMG_DECLARE(mouse_cursor_icon);                          /*Declare the image file.*/
lv_obj_t * cursor_obj =  lv_img_create(lv_scr_act(), NULL); /*Create an image object for the cursor */
lv_img_set_src(cursor_obj, &mouse_cursor_icon);             /*Set the image source*/
lv_indev_set_cursor(mouse_indev, cursor_obj);               /*Connect the image  object to the driver*/

Note that the cursor object should have lv_obj_set_click(cursor_obj, false). For images, clicking is disabled by default.

Keypad and encoder¶

You can fully control the user interface without touchpad or mouse using a keypad or encoder(s). It works similar to the TAB key on the PC to select the element in an application or a web page.

Groups¶

The objects, you want to control with keypad or encoder, needs to be added to a Group. In every group, there is exactly one focused object which receives the pressed keys or the encoder actions. For example, if a Text area is focused and you press some letter on a keyboard, the keys will be sent and inserted into the text area. Similarly, if a Slider is focused and you press the left or right arrows, the slider’s value will be changed.

You need to associate an input device with a group. An input device can send the keys to only one group but, a group can receive data from more than one input device too.

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).

The 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()

Keys¶

There are some predefined keys which have special meaning:

LV_KEY_NEXT Focus on the next object
LV_KEY_PREV Focus on the previous object
LV_KEY_ENTER Triggers LV_EVENT_PRESSED/CLICKED/LONG_PRESSED etc. events
LV_KEY_UP Increase value or move upwards
LV_KEY_DOWN Decrease value or move downwards
LV_KEY_RIGHT Increase value or move the the right
LV_KEY_LEFT Decrease value or move the the left
LV_KEY_ESC Close or exit (E.g. close a Drop down list)
LV_KEY_DEL Delete (E.g. a character on the right in a Text area)
LV_KEY_BACKSPACE Delete a character on the left (E.g. in a Text area)
LV_KEY_HOME Go to the beginning/top (E.g. in a Text area)
LV_KEY_END Go to the end (E.g. in a Text area))

The most important special keys are LV_KEY_NEXT/PREV, LV_KEY_ENTER and LV_KEY_UP/DOWN/LEFT/RIGHT. In your read_cb function, you should translate some of your keys to these special keys to navigate in the group and interact with the selected object.

Usually, it’s enough to use only LV_KEY_LEFT/RIGHT because most of the objects can be fully controlled with them.

With an encoder, you should use only LV_KEY_LEFT, LV_KEY_RIGHT, and LV_KEY_ENTER.

Edit and navigate mode¶

Since keypad has plenty of keys, it’s easy to navigate between the objects and edit them using the keypad. But, the encoders have a limited number of “keys” hence, difficult to navigate using the default options. Navigate and Edit are created to avoid this problem with the encoders.

In Navigate mode, the encoders LV_KEY_LEFT/RIGHT is translated to LV_KEY_NEXT/PREV. Therefore the next or previous object will be selected by turning the encoder. Pressing LV_KEY_ENTER will change to Edit mode.

In Edit mode, LV_KEY_NEXT/PREV is usually used to edit the object. Depending on the object’s type, a short or long press of LV_KEY_ENTER changes back to Navigate mode. Usually, an object which can not be pressed (like a Slider) leaves Edit mode on short click. But with object where short click has meaning (e.g. Button), long press is required.

Styling the focused object¶

To visually highlight the focused element, its Main style will be updated. By default, some orange color is mixed with the original colors of the style. A new style modifier callback be set by lv_group_set_style_mod_cb(g, my_style_mod_cb). A style modifier callback receives a pointer to a caller group and a pointer to a style to modify. The default style modifier looks like this (slightly simplified):

static void default_style_mod_cb(lv_group_t * group, lv_style_t * style)
{
    /*Make the bodies a little bit orange*/
    style->body.border.opa   = LV_OPA_COVER;
    style->body.border.color = LV_COLOR_ORANGE;
    style->body.border.width = LV_DPI / 20;

    style->body.main_color   = lv_color_mix(style->body.main_color, LV_COLOR_ORANGE, LV_OPA_70);
    style->body.grad_color   = lv_color_mix(style->body.grad_color, LV_COLOR_ORANGE, LV_OPA_70);
    style->body.shadow.color = lv_color_mix(style->body.shadow.color, LV_COLOR_ORANGE, LV_OPA_60);

    /*Recolor text*/
    style->text.color = lv_color_mix(style->text.color, LV_COLOR_ORANGE, LV_OPA_70);

    /*Add some recolor to the images*/
    if(style->image.intense < LV_OPA_MIN) {
        style->image.color = LV_COLOR_ORANGE;
        style->image.intense = LV_OPA_40;
    }
}

This style modifier callback is used for keypads and encoder in Navigate mode. For the Edit mode and other callback is used which can be set with lv_group_set_style_mod_edit_cb(). By default, it has a greenish color.

Complete example¶

You can try the lv_test_group demo for a practical example of how to work with group navigation.

API¶

Input device¶

Functions

void lv_indev_init(void)¶: Initialize the display input device subsystem

void lv_indev_read_task(lv_task_t *task)¶

Called periodically to read the input devices

Parameters

task: pointer to the task itself

lv_indev_t *lv_indev_get_act(void)¶

Get the currently processed input device. Can be used in action functions too.

Return: pointer to the currently processed input device or NULL if no input device processing right now

lv_indev_type_t lv_indev_get_type(const lv_indev_t *indev)¶

Get the type of an input device

Return

the type of the input device from lv_hal_indev_type_t (LV_INDEV_TYPE_...)

Parameters

indev: pointer to an input device

void lv_indev_reset(lv_indev_t *indev)¶

Reset one or all input devices

Parameters

indev: pointer to an input device to reset or NULL to reset all of them

void lv_indev_reset_long_press(lv_indev_t *indev)¶

Reset the long press state of an input device

Parameters

indev_proc: pointer to an input device

void lv_indev_enable(lv_indev_t *indev, bool en)¶

Enable or disable an input devices

Parameters

indev: pointer to an input device
en: true: enable; false: disable

void lv_indev_set_cursor(lv_indev_t *indev, lv_obj_t *cur_obj)¶

Set a cursor for a pointer input device (for LV_INPUT_TYPE_POINTER and LV_INPUT_TYPE_BUTTON)

Parameters

indev: pointer to an input device
cur_obj: pointer to an object to be used as cursor

void lv_indev_set_group(lv_indev_t *indev, lv_group_t *group)¶

Set a destination group for a keypad input device (for LV_INDEV_TYPE_KEYPAD)

Parameters

indev: pointer to an input device
group: point to a group

void lv_indev_set_button_points(lv_indev_t *indev, const lv_point_t *points)¶

Set the an array of points for LV_INDEV_TYPE_BUTTON. These points will be assigned to the buttons to press a specific point on the screen

Parameters

indev: pointer to an input device
group: point to a group

void lv_indev_get_point(const lv_indev_t *indev, lv_point_t *point)¶

Get the last point of an input device (for LV_INDEV_TYPE_POINTER and LV_INDEV_TYPE_BUTTON)

Parameters

indev: pointer to an input device
point: pointer to a point to store the result

uint32_t lv_indev_get_key(const lv_indev_t *indev)¶

Get the last pressed key of an input device (for LV_INDEV_TYPE_KEYPAD)

Return

the last pressed key (0 on error)

Parameters

indev: pointer to an input device

bool lv_indev_is_dragging(const lv_indev_t *indev)¶

Check if there is dragging with an input device or not (for LV_INDEV_TYPE_POINTER and LV_INDEV_TYPE_BUTTON)

Return

true: drag is in progress

Parameters

indev: pointer to an input device

void lv_indev_get_vect(const lv_indev_t *indev, lv_point_t *point)¶

Get the vector of dragging of an input device (for LV_INDEV_TYPE_POINTER and LV_INDEV_TYPE_BUTTON)

Parameters

indev: pointer to an input device
point: pointer to a point to store the vector

void lv_indev_wait_release(lv_indev_t *indev)¶

Do nothing until the next release

Parameters

indev: pointer to an input device

lv_task_t *lv_indev_get_read_task(lv_disp_t *indev)¶

Get a pointer to the indev read task to modify its parameters with lv_task_... functions.

Return

pointer to the indev read refresher task. (NULL on error)

Parameters

indev: pointer to an inout device

lv_obj_t *lv_indev_get_obj_act(void)¶

Gets a pointer to the currently active object in indev proc functions. NULL if no object is currently being handled or if groups aren’t used.

Return: pointer to currently active object

Groups¶

Typedefs

typedef uint8_t lv_key_t¶

typedef void (*lv_group_style_mod_cb_t)(struct _lv_group_t*, lv_style_t*)¶

typedef void (*lv_group_focus_cb_t)(struct _lv_group_t*)¶

typedef struct _lv_group_t lv_group_t¶: Groups can be used to logically hold objects so that they can be individually focused. They are NOT for laying out objects on a screen (try lv_cont for that).

typedef uint8_t lv_group_refocus_policy_t¶

Enums

enum [anonymous]¶

Values:

enumerator LV_KEY_UP = 17¶

enumerator LV_KEY_DOWN = 18¶

enumerator LV_KEY_RIGHT = 19¶

enumerator LV_KEY_LEFT = 20¶

enumerator LV_KEY_ESC = 27¶

enumerator LV_KEY_DEL = 127¶

enumerator LV_KEY_BACKSPACE = 8¶

enumerator LV_KEY_ENTER = 10¶

enumerator LV_KEY_NEXT = 9¶

enumerator LV_KEY_PREV = 11¶

enumerator LV_KEY_HOME = 2¶

enumerator LV_KEY_END = 3¶

enum [anonymous]¶

Values:

enumerator LV_GROUP_REFOCUS_POLICY_NEXT = 0¶

enumerator LV_GROUP_REFOCUS_POLICY_PREV = 1¶

Functions

void lv_group_init(void)¶

Init. the group module

Remark: Internal function, do not call directly.

lv_group_t *lv_group_create(void)¶

Create a new object group

Return: pointer to the new object group

void lv_group_del(lv_group_t *group)¶

Delete a group object

Parameters

group: pointer to a group

void lv_group_add_obj(lv_group_t *group, lv_obj_t *obj)¶

Add an object to a group

Parameters

group: pointer to a group
obj: pointer to an object to add

void lv_group_remove_obj(lv_obj_t *obj)¶

Remove an object from its group

Parameters

obj: pointer to an object to remove

void lv_group_remove_all_objs(lv_group_t *group)¶

Remove all objects from a group

Parameters

group: pointer to a group

void lv_group_focus_obj(lv_obj_t *obj)¶

Focus on an object (defocus the current)

Parameters

obj: pointer to an object to focus on

void lv_group_focus_next(lv_group_t *group)¶

Focus the next object in a group (defocus the current)

Parameters

group: pointer to a group

void lv_group_focus_prev(lv_group_t *group)¶

Focus the previous object in a group (defocus the current)

Parameters

group: pointer to a group

void lv_group_focus_freeze(lv_group_t *group, bool en)¶

Do not let to change the focus from the current object

Parameters

group: pointer to a group
en: true: freeze, false: release freezing (normal mode)

lv_res_t lv_group_send_data(lv_group_t *group, uint32_t c)¶

Send a control character to the focuses object of a group

Return

result of focused object in group.

Parameters

group: pointer to a group
c: a character (use LV_KEY_.. to navigate)

void lv_group_set_style_mod_cb(lv_group_t *group, lv_group_style_mod_cb_t style_mod_cb)¶

Set a function for a group which will modify the object’s style if it is in focus

Parameters

group: pointer to a group
style_mod_cb: the style modifier function pointer

void lv_group_set_style_mod_edit_cb(lv_group_t *group, lv_group_style_mod_cb_t style_mod_edit_cb)¶

Set a function for a group which will modify the object’s style if it is in focus in edit mode

Parameters

group: pointer to a group
style_mod_edit_cb: the style modifier function pointer

void lv_group_set_focus_cb(lv_group_t *group, lv_group_focus_cb_t focus_cb)¶

Set a function for a group which will be called when a new object is focused

Parameters

group: pointer to a group
focus_cb: the call back function or NULL if unused

void lv_group_set_refocus_policy(lv_group_t *group, lv_group_refocus_policy_t policy)¶

Set whether the next or previous item in a group is focused if the currently focussed obj is deleted.

Parameters

group: pointer to a group
new: refocus policy enum

void lv_group_set_editing(lv_group_t *group, bool edit)¶

Manually set the current mode (edit or navigate).

Parameters

group: pointer to group
edit: true: edit mode; false: navigate mode

void lv_group_set_click_focus(lv_group_t *group, bool en)¶

Set the click_focus attribute. If enabled then the object will be focused then it is clicked.

Parameters

group: pointer to group
en: true: enable click_focus

void lv_group_set_wrap(lv_group_t *group, bool en)¶

Set whether focus next/prev will allow wrapping from first->last or last->first object.

Parameters

group: pointer to group
en: true: wrapping enabled; false: wrapping disabled

lv_style_t *lv_group_mod_style(lv_group_t *group, const lv_style_t *style)¶

Modify a style with the set ‘style_mod’ function. The input style remains unchanged.

Return

a copy of the input style but modified with the ‘style_mod’ function

Parameters

group: pointer to group
style: pointer to a style to modify

lv_obj_t *lv_group_get_focused(const lv_group_t *group)¶

Get the focused object or NULL if there isn’t one

Return

pointer to the focused object

Parameters

group: pointer to a group

lv_group_user_data_t *lv_group_get_user_data(lv_group_t *group)¶

Get a pointer to the group’s user data

Return

pointer to the user data

Parameters

group: pointer to an group

lv_group_style_mod_cb_t lv_group_get_style_mod_cb(const lv_group_t *group)¶

Get a the style modifier function of a group

Return

pointer to the style modifier function

Parameters

group: pointer to a group

lv_group_style_mod_cb_t lv_group_get_style_mod_edit_cb(const lv_group_t *group)¶

Get a the style modifier function of a group in edit mode

Return

pointer to the style modifier function

Parameters

group: pointer to a group

lv_group_focus_cb_t lv_group_get_focus_cb(const lv_group_t *group)¶

Get the focus callback function of a group

Return

the call back function or NULL if not set

Parameters

group: pointer to a group

bool lv_group_get_editing(const lv_group_t *group)¶

Get the current mode (edit or navigate).

Return

true: edit mode; false: navigate mode

Parameters

group: pointer to group

bool lv_group_get_click_focus(const lv_group_t *group)¶

Get the click_focus attribute.

Return

true: click_focus is enabled; false: disabled

Parameters

group: pointer to group

bool lv_group_get_wrap(lv_group_t *group)¶

Get whether focus next/prev will allow wrapping from first->last or last->first object.

Parameters

group: pointer to group
en: true: wrapping enabled; false: wrapping disabled

void lv_group_report_style_mod(lv_group_t *group)¶

Notify the group that current theme changed and style modification callbacks need to be refreshed.

Parameters

group: pointer to group. If NULL then all groups are notified.

struct _lv_group_t¶

#include <lv_group.h>

Groups can be used to logically hold objects so that they can be individually focused. They are NOT for laying out objects on a screen (try lv_cont for that).

Public Members

lv_ll_t obj_ll¶: Linked list to store the objects in the group

lv_obj_t **obj_focus¶: The object in focus

lv_group_style_mod_cb_t style_mod_cb¶: A function to modifies the style of the focused object

lv_group_style_mod_cb_t style_mod_edit_cb¶: A function which modifies the style of the edited object

lv_group_focus_cb_t focus_cb¶: A function to call when a new object is focused (optional)

lv_style_t style_tmp¶: Stores the modified style of the focused object

lv_group_user_data_t user_data¶

uint8_t frozen¶: 1: can’t focus to new object

uint8_t editing¶: 1: Edit mode, 0: Navigate mode

uint8_t click_focus¶: 1: If an object in a group is clicked by an indev then it will be focused

uint8_t refocus_policy¶: 1: Focus prev if focused on deletion. 0: Focus next if focused on deletion.

uint8_t wrap¶: 1: Focus next/prev can wrap at end of list. 0: Focus next/prev stops at end of list.