# Groups (/main-modules/indev/groups)



Overview [#overview]

Groups are a "group of widgets" that can be focused by [Keypad](/main-modules/indev/keypad)
or [Encoder](/main-modules/indev/encoder) input devices.

First, a group needs to be created. After that, the group needs to be assigned to an
input device. Finally, widgets need to be added to the group.

In practice, this means when the input device wants to focus the next or previous
widget (<ApiLink name="LV_KEY_NEXT" /> and <ApiLink name="LV_KEY_PREV" />), it will
search for the widget in the assigned group.

Only the selected widgets will be focusable, and the order of receiving focus will be
the order in which the widgets were added.

The focused object will receive the keys and other related events. For example, if a
[Text Area](/widgets/textarea) has focus and you press a letter on a keyboard, the
key will be sent and inserted into the text area (as <ApiLink name="LV_EVENT_KEY" />).
Similarly, if a [Slider](/widgets/slider) has focus and you press the left or right
arrows, the slider's value will be changed.

Usage [#usage]

To create a group, use <ApiLink name="lv_group_t" display="lv_group_t * g = lv_group_create" />, and to add a
widget to the group, use <ApiLink name="lv_group_add_obj" display="lv_group_add_obj(g, widget)" />.

Once a widget has been added to a group, you can find out what group it belongs to
using <ApiLink name="lv_obj_get_group" display="lv_obj_get_group(widget)" />.

To find out which widget in a group has focus, if any, call
<ApiLink name="lv_group_get_focused" display="lv_group_get_focused(group)" />. If a widget in that group has focus, it will
return a pointer to it; otherwise, it will return NULL.

To associate a group with an input device, use <ApiLink name="lv_indev_set_group" display="lv_indev_set_group(indev, g)" />.

Edit and Navigate Mode [#edit-and-navigate-mode]

Since a [Keypad](/main-modules/indev/keypad) has plenty of keys, it's easy to navigate between
widgets and edit them using the keypad. But [Encoders](/main-modules/indev/encoder) have a
limited number of "keys", making it difficult to navigate and adjust widgets.

*Navigate* and *Edit* modes are used to solve this problem with encoders.

In **Navigate** mode, an encoder's step is translated to
<ApiLink name="LV_KEY_NEXT" /> or <ApiLink name="LV_KEY_PREV" />. Therefore, the next or
previous object will be selected by turning the encoder. Pressing the encoder's button
will switch to *Edit* mode if the widget is "editable".

In *Edit* mode, the encoder's step is usually used to modify the focused widget.
Depending on the widget's type, a short or long press changes back to *Navigate* mode.
Usually, a widget that cannot be pressed (like a [Slider](/widgets/slider)) exits *Edit*
mode upon a short click. But for widgets where a short click has meaning (e.g., a
[Button](/widgets/button)), a long press is required.

Whether a widget is editable is set in the widget's class. See, for example,
[.editable = LV\_OBJ\_CLASS\_EDITABLE\_TRUE`in`lv\_slider.c](https://github.com/lvgl/lvgl/blob/master/src/widgets/slider/lv_slider.c).

Default Group [#default-group]

Interactive widgets (such as Buttons, Checkboxes, Sliders, etc.) can be automatically
added to a default group. Just create a group with
<ApiLink name="lv_group_t" display="lv_group_t * g = lv_group_create" /> and set the default group with
<ApiLink name="lv_group_set_default" display="lv_group_set_default(g)" />.

Don't forget to assign one or more input devices to the default group using
<ApiLink name="lv_indev_set_group" display="lv_indev_set_group(my_indev, g)" />.

Multiple Groups [#multiple-groups]

Multiple groups can also be created. Imagine an instrument (e.g., a power supply) with
4 channels and "left", "right", and "OK" buttons for each channel to adjust them. On
the display, all 4 channels are shown below each other.

To manage the channels separately:

* Create a group for each channel
* Add the UI elements of each channel to its group
* Create 4 input devices for the 4 channels
* Connect each group to its respective input device

This way, the channels can be managed separately in an elegant manner.