mirror of
https://gitlab.freedesktop.org/libinput/libinput.git
synced 2025-12-25 08:10:05 +01:00
doc: improve seat documentation
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
This commit is contained in:
Peter Hutterer
parent
e537d84305
commit
d04d0c19dd
5 changed files with 113 additions and 29 deletions
|
|
@ -15,7 +15,8 @@ header_files = \
|
|||
$(srcdir)/t440-support.dox
|
||||
|
||||
diagram_files = \
|
||||
$(srcdir)/dot/seats-sketch.gv
|
||||
$(srcdir)/dot/seats-sketch.gv \
|
||||
$(srcdir)/dot/seats-sketch-libinput.gv
|
||||
|
||||
html/index.html: libinput.doxygen $(header_files) $(diagram_files)
|
||||
$(AM_V_GEN)(cat $<; \
|
||||
|
|
|
|||
29
doc/dot/seats-sketch-libinput.gv
Normal file
29
doc/dot/seats-sketch-libinput.gv
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
digraph seats_libinput
|
||||
{
|
||||
rankdir="BT";
|
||||
node [
|
||||
shape="box";
|
||||
]
|
||||
|
||||
ctx1 [label="libinput context 1"; URL="\ref libinput"];
|
||||
ctx2 [label="libinput context 2"; URL="\ref libinput"];
|
||||
|
||||
seat0 [ label="seat phys 0 logical A"];
|
||||
seat1 [ label="seat phys 0 logical B"];
|
||||
seat2 [ label="seat phys 1 logical C"];
|
||||
|
||||
dev1 [label="device 'Foo'"];
|
||||
dev2 [label="device 'Bar'"];
|
||||
dev3 [label="device 'Spam'"];
|
||||
dev4 [label="device 'Egg'"];
|
||||
|
||||
ctx1 -> dev1
|
||||
ctx1 -> dev2
|
||||
ctx1 -> dev3
|
||||
ctx2 -> dev4
|
||||
|
||||
dev1 -> seat0
|
||||
dev2 -> seat0
|
||||
dev3 -> seat1
|
||||
dev4 -> seat2
|
||||
}
|
||||
|
|
@ -15,13 +15,18 @@ digraph seats
|
|||
pseat0 [label="phys seat0"; URL="\ref libinput_seat_get_physical_name"];
|
||||
pseat1 [label="phys seat1"; URL="\ref libinput_seat_get_physical_name"];
|
||||
|
||||
lseatA [label="log seat A"; URL="\ref libinput_seat_get_logical_name"];
|
||||
lseatB [label="log seat B"; URL="\ref libinput_seat_get_logical_name"];
|
||||
lseatC [label="log seat C"; URL="\ref libinput_seat_get_logical_name"];
|
||||
lseatA [label="logical seat A"; URL="\ref libinput_seat_get_logical_name"];
|
||||
lseatB [label="logical seat B"; URL="\ref libinput_seat_get_logical_name"];
|
||||
lseatC [label="logical seat C"; URL="\ref libinput_seat_get_logical_name"];
|
||||
|
||||
ctx1 [label="libinput context 1"; URL="\ref libinput"];
|
||||
ctx2 [label="libinput context 2"; URL="\ref libinput"];
|
||||
|
||||
dev1 [label="device 'Foo'"];
|
||||
dev2 [label="device 'Bar'"];
|
||||
dev3 [label="device 'Spam'"];
|
||||
dev4 [label="device 'Egg'"];
|
||||
|
||||
kernel -> event0
|
||||
kernel -> event1
|
||||
kernel -> event2
|
||||
|
|
@ -38,4 +43,9 @@ digraph seats
|
|||
ctx1 -> lseatA
|
||||
ctx1 -> lseatB
|
||||
ctx2 -> lseatC
|
||||
}
|
||||
|
||||
lseatA -> dev1
|
||||
lseatA -> dev2
|
||||
lseatB -> dev3
|
||||
lseatC -> dev4
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,12 +1,73 @@
|
|||
/**
|
||||
@page seats Seats
|
||||
|
||||
Each device in libinput is associated with one physical seat and one logical seat.
|
||||
Each device in libinput is assigned to one seat.
|
||||
A seat has two identifiers, the physical name and the logical name. The
|
||||
physical name is summarized as the list of devices a process on the same
|
||||
physical seat has access to. The logical seat name is the seat name for a
|
||||
logical group of devices. A compositor may use that to create additonal
|
||||
seats as independent device sets. Alternatively, a compositor may limit
|
||||
itself to a single logical seat, leaving a second compositor to manage
|
||||
devices on the other logical seats.
|
||||
|
||||
@section seats_overview Overview
|
||||
@section Overview
|
||||
|
||||
Below is an illustration of how physical seats and logical seats interact:
|
||||
|
||||
@dotfile seats-sketch.gv
|
||||
|
||||
Details pending.
|
||||
The devices "Foo", "Bar" and "Spam" share the same physical seat and are
|
||||
thus available in the same libinput context. Only "Foo" and "Bar" share the
|
||||
same logical seat. The device "Egg" is not available in the libinput context
|
||||
associated with the physical seat 0.
|
||||
|
||||
The above graph is for illustration purposes only. In libinput, a struct
|
||||
@ref libinput_seat comprises both physical seat and logical seat. From a
|
||||
caller's point-of-view the above device layout is presented as:
|
||||
|
||||
@dotfile seats-sketch-libinput.gv
|
||||
|
||||
Thus, devices "Foo" and "Bar" both reference the same struct @ref
|
||||
libinput_seat, all other devices reference their own respective seats.
|
||||
|
||||
@section seats_and_features The effect of seat assignment
|
||||
|
||||
A logical set is interprested as a group of devices that usually belong to a
|
||||
single user that interacts with a computer. Thus, the devices are
|
||||
semantically related. This means for devices within the same logical seat:
|
||||
|
||||
- if the same button is pressed on different devices, the button should only
|
||||
be considered logically pressed once.
|
||||
- if the same button is released on one device, the button should be
|
||||
considered logically down if still down on another device.
|
||||
- if two different buttons or keys are pressed on different devices, the
|
||||
logical state is that of both buttons/keys down.
|
||||
- if a button is pressed on one device and another device moves, this should
|
||||
count as dragging.
|
||||
- if two touches are down on different devices, the logical state is that of
|
||||
two touches down.
|
||||
|
||||
libinput provides functions to aid with the above:
|
||||
libinput_event_pointer_get_seat_button_count(),
|
||||
libinput_event_keyboard_get_seat_key_count(), and
|
||||
libinput_event_touch_get_seat_slot().
|
||||
|
||||
Internally, libinput counts devices within the same logical seat as related.
|
||||
Cross-device features only activate if all required devices are in the same
|
||||
logical seat. For example, libinput will only activate the top software
|
||||
buttons (see @ref t440_support) if both trackstick and touchpad are assigned
|
||||
to the same logical seat.
|
||||
|
||||
|
||||
@section changing_seats Changing seats
|
||||
|
||||
A device may change the logical seat it is assigned to at runtime with
|
||||
libinput_device_set_seat_logical_name(). The physical seat is immutable and
|
||||
may not be changed.
|
||||
|
||||
Changing the logical seat for a device is equivalent to unplugging the
|
||||
device and plugging it back in with the new logical seat. No device state
|
||||
carries over across a logical seat change.
|
||||
|
||||
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1139,27 +1139,10 @@ libinput_log_set_handler(struct libinput *libinput,
|
|||
/**
|
||||
* @defgroup seat Initialization and manipulation of seats
|
||||
*
|
||||
* A seat has two identifiers, the physical name and the logical name. The
|
||||
* physical name is summarized as the list of devices a process on the same
|
||||
* physical seat has access to.
|
||||
*
|
||||
* The logical seat name is the seat name for a logical group of devices. A
|
||||
* compositor may use that to create additonal seats as independent device
|
||||
* sets. Alternatively, a compositor may limit itself to a single logical
|
||||
* seat, leaving a second compositor to manage devices on the other logical
|
||||
* seats.
|
||||
*
|
||||
* @code
|
||||
* +---+--------+------------+------------------------+------------+
|
||||
* | | event0 | | | log seat A |
|
||||
* | K +--------+ | +------------+
|
||||
* | e | event1 | phys seat0 | libinput context 1 | |
|
||||
* | r +--------+ | | log seat B |
|
||||
* | n | event2 | | | |
|
||||
* | e +--------+------------+------------------------+------------+
|
||||
* | l | event3 | phys seat1 | libinput context 2 | log seat C |
|
||||
* +---+--------+------------+------------------------+------------+
|
||||
* @endcode
|
||||
* A seat has two identifiers, the physical name and the logical name. A
|
||||
* device is always assigned to exactly one seat. It may change to a
|
||||
* different logical seat but it cannot change physical seats. See @ref
|
||||
* seats for details.
|
||||
*/
|
||||
|
||||
/**
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue