App:Library:LVGL:docs:Overview:Input devices
https://docs.lvgl.io/8.2/overview/style.html
英文 | 自動翻訳 |
---|---|
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
Cursor
Pointer input devices (like a mouse) can have a cursor.
... lv_indev_t * mouse_indev = lv_indev_drv_register(&indev_drv); LV_IMG_DECLARE(mouse_cursor_icon); /*Declare the image source.*/ lv_obj_t * cursor_obj = lv_img_create(lv_scr_act()); /*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_clear_flag(cursor_obj, LV_OBJ_FLAG_CLICKABLE)
. For images, clicking is disabled by default.
Gestures
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:
void my_event(lv_event_t * e) { lv_obj_t * screen = lv_event_get_current_target(e); lv_dir_t dir = lv_indev_get_gesture_dir(lv_indev_act()); switch(dir) { case LV_DIR_LEFT: ... break; case LV_DIR_RIGHT: ... break; case LV_DIR_TOP: ... break; case LV_DIR_BOTTOM: ... break; } } ... lv_obj_add_event_cb(screen1, my_event, LV_EVENT_GESTURE, NULL);
To prevent passing the gesture event to the parent from an object use lv_obj_clear_flag(obj, LV_OBJ_FLAG_GESTURE_BUBBLE)
.
Note that, gestures are not triggered if an object is being scrolled.
Keypad and encoder
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.
Groups
Objects you want to control with a keypad or encoder need 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 key events to only one group but a group can receive data from more than one input device.
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)
.
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()
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 to the right
- LV_KEY_LEFT Decrease value or move to 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 support navigation in a group and interact with selected objects.
Usually, it's enough to use only LV_KEY_LEFT/RIGHT
because most objects can be fully controlled with them.
With an encoder you should use only LV_KEY_LEFT
, LV_KEY_RIGHT
, and LV_KEY_ENTER
.
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.
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. Pressing LV_KEY_ENTER
will change to Edit mode.
In Edit mode, LV_KEY_NEXT/PREV
is usually used to modify an 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 cannot be pressed (like a Slider) leaves Edit mode upon a short click. But with objects where a short click has meaning (e.g. Button), a long press is required.
Default group
Interactive widgets - such as buttons, checkboxes, sliders, etc. - can be automatically added to a default group. Just create a group with lv_group_t * g = lv_group_create();
and set the default group with lv_group_set_default(g);
Don't forget to assign one or more input devices to the default group with lv_indev_set_group(my_indev, g);
.
Styling
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.
If an object switches to edit mode it enters the LV_STATE_FOCUSED | LV_STATE_EDITED
states so these style properties will be shown.
For a more detailed description read the Style section.
API
Input device
Functions
- void lv_indev_read_timer_cb(lv_timer_t *timer)[1]
- Called periodically to read the input devi[2]ces
- Parameters
- timer -- pointer to a timer to read
- void lv_indev_enable(lv_indev_t *indev, bool en)[3]
- lv_indev_t *lv_indev_get_act(void)[4]
- Get the currently processed in[6]put device. Can be used in action functions too.
- Returns
- 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)[7]
- Get the type of an input device
- Parameters
- indev[8] -- pointer to an input device
- Returns
- the type of the input device from
lv_hal_indev_type_t
(LV_INDEV_TYPE_...
)
- void lv_indev_reset(lv_indev_t *indev, lv_obj_t *obj)[9]
- Reset one or all input devices
- Parameters
-
- [10] indev -- pointer to an input device to reset or NULL to reset all of them
- obj -- pointer to an object which triggers the reset.
- void lv_indev_reset_long_press(lv_indev_t *indev)[11]
- Reset the long press state of an input device[12]
- Parameters
- indev -- pointer to an input device
- void lv_indev_set_cursor(lv_indev_t *indev, lv_obj_t *cur_obj)[13]
- Set a cursor for a pointer input device (for LV_INPUT_TYPE[14]_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)[15]
- Set a destination group for a keypad input device (for LV[16]_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[])[17]
- Set the an array of points for LV_INDEV_TYPE_BUTTON. These points will be[18] 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)[19]
- Get the last point of an input device (for LV_INDEV_TYPE_POINTE[20]R and LV_INDEV_TYPE_BUTTON)
- Parameters
-
- indev -- pointer to an input device
- point -- pointer to a point to store the result
- lv_dir_t lv_indev_get_gesture_dir(const lv_indev_t *indev)[21]
- Get the current gesture direct
- Parameters
- indev [22]-- pointer to an input device
- Returns
- current gesture direct
- uint32_t lv_indev_get_key(const lv_indev_t *indev)[23]
- Get the last pressed key of an input device (f[24]or LV_INDEV_TYPE_KEYPAD)
- Parameters
- indev -- pointer to an input device
- Returns
- the last pressed key (0 on error)
- lv_dir_t lv_indev_get_scroll_dir(const lv_indev_t *indev)[25]
- Check the current scroll direction of an input device[26] (for LV_INDEV_TYPE_POINTER and LV_INDEV_TYPE_BUTTON)
- Parameters
- indev -- pointer to an input device
- Returns
- LV_DIR_NONE: no scrolling now LV_DIR_HOR/VER
- lv_obj_t *lv_indev_get_scroll_obj(const lv_indev_t *indev)[27]
- Get the currently scrolled object (for LV_INDEV_TYPE_P[28]OINTER and LV_INDEV_TYPE_BUTTON)
- Parameters
- indev -- pointer to an input device
- Returns
- pointer to the currently scrolled object or NULL if no scrolling by this indev
- void lv_indev_get_vect(const lv_indev_t *indev, lv_point_t *point)[29]
- Get the movement vector of an input device (for LV_INDEV_TYPE_[30]POINTER and LV_INDEV_TYPE_BUTTON)
- Parameters
-
- indev -- pointer to an input device
- point -- pointer to a point to store the types.pointer.vector
- void lv_indev_wait_release(lv_indev_t *indev)[31]
- Do nothing until the next release
- Para[32]meters
- indev -- pointer to an input device
- lv_obj_t *lv_indev_get_obj_act(void)[33]
- Gets a pointer to the currently [34]active object in the currently processed input device.
- Returns
- pointer to currently active object or NULL if no active object
- lv_timer_t *lv_indev_get_read_timer(lv_disp_t *indev)[35]
- Get a pointer to the indev read timer to modify i[36]ts parameters with
lv_timer_...
functions.- Parameters
- indev -- pointer to an input device
- Returns
- pointer to the indev read refresher timer. (NULL on error)
- lv_obj_t *lv_indev_search_obj(lv_obj_t *obj, lv_point_t *point)[37]
- Search the most top, clickable object by a point
- Paramet[38]ers
-
- obj -- pointer to a start object, typically the screen
- point -- pointer to a point for searching the most top child
- Returns
- pointer to the found object or NULL if there was no suitable object
Groups
Typedefs
- typedef uint8_t lv_key_t[39]
- typedef struct _lv_group_t lv_group_t[42]
- Gro[43]ups can be used to logically h[44]old objects so that they can be individually focused. They are NOT for laying out objects on a screen (try layouts for that).
Enums
- enum [anonymous][45]
- Values:
- e[46]numerator LV_KEY_UP[47]
- enumerator[48] LV_KEY_DOWN[49]
- enumerator L[50]V_KEY_RIGHT[51]
- enumerator LV[52]_KEY_LEFT[53]
- enumerator L[54]V_KEY_ESC[55]
- enumerator [56]LV_KEY_DEL[57]
- enumerator [58]LV_KEY_BACKSPACE[59]
- enumerator LV_KEY[60]_ENTER[61]
- enumerator LV[62]_KEY_NEXT[63]
- enumerator L[64]V_KEY_PREV[65]
- enumerator L[66]V_KEY_HOME[67]
- enumerator L[68]V_KEY_END[69]
Functions
- void _lv_group_i[76]nit(void)[77]
- Init. the group modul[78]e
- Remark
- Internal function, do not call directly.
- lv_group_t *lv_group_create(void)[79]
- Create a new object group
- [80]Returns
- pointer to the new object group
- void lv_group_del(lv_group_t *group)[81]
- Delete a group object
- Paramet[82]ers
- group -- pointer to a group
- void lv_group_set_default(lv_group_t *group)[83]
- Set a default group. New object are adde[84]d to this group if it's enabled in their class with
add_to_def_group = true
- Parameters
- group -- pointer to a group (can be
NULL
)
- lv_group_t *lv_group_get_default(void)[85]
- Get the default group
- Returns
- pointer to the default group
- void lv_group_add_obj(lv_group_t *group, struct _lv_obj_t *obj)[87]
- Add an object to a group
- Parameters
-
- group -- pointe[88]r to a group
- obj -- pointer to an object to add
- void lv_group_swap_obj(struct _lv_obj_t *obj1, struct _lv_obj_t *obj2)[89]
- Swap 2 object in a group. The object must be in the same group
- [90]Parameters
-
- obj1 -- pointer to an object
- obj2 -- pointer to an other object
- void lv_group_remove_obj(struct _lv_obj_t *obj)[91]
- Remove an object from its group
- Paramete[92]rs
- obj -- pointer to an object to remove
- void lv_group_remove_all_objs(lv_group_t *group)[93]
- Remove all objects from a group
- Parameter[94]s
- group -- pointer to a group
- void lv_group_focus_obj(struct _lv_obj_t *obj)[95]
- Focus on an object (defocus the current)
- [96]
- Parameters
- obj -- pointer to an object to focus on
- void lv_group_focus_next(lv_group_t *group)[97]
- Focus the next object in a group (defoc[98]us the current)
- Parameters
- group -- pointer to a group
- void lv_group_focus_prev(lv_group_t *group)[99]
- Focus the previous object in a group (d[100]efocus the current)
- Parameters
- group -- pointer to a group
- void lv_group_focus_freeze(lv_group_t *group, bool en)[101]
- Do not let to change the focus from the current ob[102]ject
- 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)[103]
- Send a control character to the focuses object of a gr[104]oup
- Parameters
-
- group -- pointer to a group
- c -- a character (use LV_KEY_.. to navigate)
- Returns
- result of focused object in group.
- void lv_group_set_focus_cb(lv_group_t *group, lv_group_focus_cb_t focus_cb)[105]
- Set a function for a group which will be called when a new object is fo[106]cused
- 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)[107]
- Set whether the next or previous item in a group is focused if the currently focu[108]sed obj is deleted.
- Parameters
-
- group -- pointer to a group
- policy -- new refocus policy enum
- void lv_group_set_editing(lv_group_t *group, bool edit)[109]
- Manually set the current mode (edit or navigate).
- [110]
- Parameters
-
- group -- pointer to group
- edit -- true: edit mode; false: navigate mode
- void lv_group_set_wrap(lv_group_t *group, bool en)[111]
- Set whether focus next/prev will allow wrappin[112]g from first->last or last->first object.
- Parameters
-
- group -- pointer to group
- en -- true: wrapping enabled; false: wrapping disabled
- struct _lv_obj_t *lv_group_get_focused(const lv_group_t *group)[113]
- Get the focused object or NULL if there isn't one
- Parame[114]ters
- group -- pointer to a group
- Returns
- pointer to the focused object
- lv_group_focus_cb_t lv_group_get_focus_cb(const lv_group_t *group)[115]
- Get the focus callback function of a group
- Parameters
- gr[116]oup -- pointer to a group
- Returns
- the call back function or NULL if not set
- bool lv_group_get_editing(const lv_group_t *group)[117]
- Get the current mode (edit or navigate).
- Pa[118]rameters
- group -- pointer to group
- Returns
- true: edit mode; false: navigate mode
- bool lv_group_get_wrap(lv_group_t *group)[119]
- Get whether focus next/prev will allo[120]w wrapping from first->last or last->first object.
- Parameters
-
- group -- pointer to group
- en -- true: wrapping enabled; false: wrapping disabled
- uint32_t lv_group_get_obj_count(lv_group_t *group)[121]
- Get the number of object in the group
- Param[122]eters
- group -- pointer to a group
- Returns
- number of objects in the group
- struct _lv_group_t[123]
- #include <lv_g[124]roup.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 layouts for that). Public Members
- lv_ll_t obj_ll[125]
- Linked lis[126]t to store the objects in the group
- struct _lv_obj_t **obj_focus[127]
- The object in focus
- [128]lv_group_focus_cb_t focus_cb[129]
- A function to call when [130]a new object is focused (optional)
- void *user_data[131]
- uint8[132]_t frozen[133]
- 1: can't f[134]ocus to new object
- uint8_t editing[135]
- 1: Edit mod[136]e, 0: Navigate mode
- uint8_t refocus_policy[137]
- 1: Focus prev if f[138]ocused on deletion. 0: Focus next if focused on deletion.
- uint8_t wrap[139]
- 1: Focus[140] next/prev can wrap at end of list. 0: Focus next/prev stops at end of list.