| 1 |
.. _seats: |
| 2 |
|
| 3 |
============================================================================== |
| 4 |
Seats |
| 5 |
============================================================================== |
| 6 |
|
| 7 |
Each device in libinput is assigned to one seat. |
| 8 |
A seat has two identifiers, the physical name and the logical name. The |
| 9 |
physical name is summarized as the list of devices a process on the same |
| 10 |
physical seat has access to. The logical seat name is the seat name for a |
| 11 |
logical group of devices. A compositor may use that to create additional |
| 12 |
seats as independent device sets. Alternatively, a compositor may limit |
| 13 |
itself to a single logical seat, leaving a second compositor to manage |
| 14 |
devices on the other logical seats. |
| 15 |
|
| 16 |
.. _seats_overview: |
| 17 |
|
| 18 |
------------------------------------------------------------------------------ |
| 19 |
Overview |
| 20 |
------------------------------------------------------------------------------ |
| 21 |
|
| 22 |
Below is an illustration of how physical seats and logical seats interact: |
| 23 |
|
| 24 |
.. graphviz:: seats-sketch.gv |
| 25 |
|
| 26 |
The devices "Foo", "Bar" and "Spam" share the same physical seat and are |
| 27 |
thus available in the same libinput context. Only "Foo" and "Bar" share the |
| 28 |
same logical seat. The device "Egg" is not available in the libinput context |
| 29 |
associated with the physical seat 0. |
| 30 |
|
| 31 |
The above graph is for illustration purposes only. In libinput, a struct |
| 32 |
**libinput_seat** comprises both physical seat and logical seat. From a |
| 33 |
caller's point-of-view the above device layout is presented as: |
| 34 |
|
| 35 |
.. graphviz:: seats-sketch-libinput.gv |
| 36 |
|
| 37 |
Thus, devices "Foo" and "Bar" both reference the same struct |
| 38 |
**libinput_seat**, all other devices reference their own respective seats. |
| 39 |
|
| 40 |
.. _seats_and_features: |
| 41 |
|
| 42 |
------------------------------------------------------------------------------ |
| 43 |
The effect of seat assignment |
| 44 |
------------------------------------------------------------------------------ |
| 45 |
|
| 46 |
A logical set is interpreted as a group of devices that usually belong to a |
| 47 |
single user that interacts with a computer. Thus, the devices are |
| 48 |
semantically related. This means for devices within the same logical seat: |
| 49 |
|
| 50 |
- if the same button is pressed on different devices, the button should only |
| 51 |
be considered logically pressed once. |
| 52 |
- if the same button is released on one device, the button should be |
| 53 |
considered logically down if still down on another device. |
| 54 |
- if two different buttons or keys are pressed on different devices, the |
| 55 |
logical state is that of both buttons/keys down. |
| 56 |
- if a button is pressed on one device and another device moves, this should |
| 57 |
count as dragging. |
| 58 |
- if two touches are down on different devices, the logical state is that of |
| 59 |
two touches down. |
| 60 |
|
| 61 |
libinput provides functions to aid with the above: |
| 62 |
**libinput_event_pointer_get_seat_button_count()**, |
| 63 |
**libinput_event_keyboard_get_seat_key_count()**, and |
| 64 |
**libinput_event_touch_get_seat_slot()**. |
| 65 |
|
| 66 |
Internally, libinput counts devices within the same logical seat as related. |
| 67 |
Cross-device features only activate if all required devices are in the same |
| 68 |
logical seat. For example, libinput will only activate the top software |
| 69 |
buttons (see :ref:`t440_support`) if both trackstick and touchpad are assigned |
| 70 |
to the same logical seat. |
| 71 |
|
| 72 |
|
| 73 |
.. _changing_seats: |
| 74 |
|
| 75 |
------------------------------------------------------------------------------ |
| 76 |
Changing seats |
| 77 |
------------------------------------------------------------------------------ |
| 78 |
|
| 79 |
A device may change the logical seat it is assigned to at runtime with |
| 80 |
**libinput_device_set_seat_logical_name()**. The physical seat is immutable and |
| 81 |
may not be changed. |
| 82 |
|
| 83 |
Changing the logical seat for a device is equivalent to unplugging the |
| 84 |
device and plugging it back in with the new logical seat. No device state |
| 85 |
carries over across a logical seat change. |