Function input_sys::libinput_device_get_device_group

pub unsafe extern "C" fn libinput_device_get_device_group(
    device: *mut libinput_device
) -> *mut libinput_device_group

@ingroup device

Get the device group this device is assigned to. Some physical devices like graphics tablets are represented by multiple kernel devices and thus by multiple struct @ref libinput_device.

libinput assigns these devices to the same @ref libinput_device_group allowing the caller to identify such devices and adjust configuration settings accordingly. For example, setting a tablet to left-handed often means turning it upside down. A touch device on the same tablet would need to be turned upside down too to work correctly.

All devices are part of a device group though for most devices the group will be a singleton. A device is assigned to a device group on @ref LIBINPUT_EVENT_DEVICE_ADDED and removed from that group on @ref LIBINPUT_EVENT_DEVICE_REMOVED. It is up to the caller to track how many devices are in each device group.

@dot digraph groups_libinput { rankdir="TB"; node [ shape="box"; ]

mouse [ label="mouse"; URL="\ref libinput_device"]; kbd [ label="keyboard"; URL="\ref libinput_device"];

pen [ label="tablet pen"; URL="\ref libinput_device"]; touch [ label="tablet touch"; URL="\ref libinput_device"]; pad [ label="tablet pad"; URL="\ref libinput_device"];

group1 [ label="group 1"; URL="\ref libinput_device_group"]; group2 [ label="group 2"; URL="\ref libinput_device_group"]; group3 [ label="group 3"; URL="\ref libinput_device_group"];

mouse -> group1 kbd -> group2

pen -> group3; touch -> group3; pad -> group3; } @enddot

Device groups do not get re-used once the last device in the group was removed, i.e. unplugging and re-plugging a physical device with grouped devices will return a different device group after every unplug.

The returned device group is not refcounted and may become invalid after the next call to libinput. Use libinput_device_group_ref() and libinput_device_group_unref() to continue using the handle outside of the immediate scope.

Device groups are assigned based on the LIBINPUT_DEVICE_GROUP udev property, see @ref udev_config.

@return The device group this device belongs to