Debian Codegraph @

doc/user/seats.rst

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