mirror of
https://gitlab.freedesktop.org/libinput/libinput.git
synced 2026-02-04 05:50:26 +01:00
Improve the documentation
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
This commit is contained in:
Peter Hutterer
parent
b853ec90d5
commit
f82aa16624
4 changed files with 120 additions and 99 deletions
|
|
@ -1,5 +1,5 @@
|
|||
/**
|
||||
@page absolute_axes Absolute Axes in libinput
|
||||
@page absolute_axes Absolute axes
|
||||
|
||||
Devices with absolute axes are those that send positioning data for an axis in
|
||||
a device-specific coordinate range, defined by a minimum and a maximum value.
|
||||
|
|
@ -12,13 +12,37 @@ libinput supports three types of devices with absolute axes:
|
|||
- single-touch screens
|
||||
- graphics tablets (currently WIP)
|
||||
|
||||
Touchpads are technically absolute devices, but the axis values are converted
|
||||
to directional motion and posted as relative events. Touchpads do not count
|
||||
Touchpads are technically absolute devices but libinput converts the axis values
|
||||
to directional motion and posts events as relative events. Touchpads do not count
|
||||
as absolute devices in libinput.
|
||||
|
||||
For all absolute devices in libinput, the default unit for x/y coordinates is
|
||||
in mm off the top left corner on the device, or more specifically off the
|
||||
device's sensor, see @ref index "the API doc"
|
||||
device's sensor.
|
||||
|
||||
@section absolute_axes_handling Handling of absolute coordinates
|
||||
|
||||
In most use-cases, absolute input devices are mapped to a single screen. For
|
||||
direct input devices such as touchscreens the aspect ratio of the screen and
|
||||
the device match. Mapping the input device position to the output position is
|
||||
thus a simple mapping between two coordinates. libinput provides the API for
|
||||
this with
|
||||
|
||||
- libinput_event_pointer_get_absolute_x_transformed() for pointer events
|
||||
- libinput_event_touch_get_x_transformed() for touch events
|
||||
|
||||
libinput's API only provides the call to map into a single coordinate range.
|
||||
If the coordinate range has an offset, the compositor is responsible for
|
||||
applying that offset after the mapping. For example, if the device is mapped
|
||||
to the right of two outputs, add the output offset to the transformed
|
||||
coordinate.
|
||||
|
||||
@section absolute_axes_nores Devices without x/y resolution
|
||||
|
||||
An absolute device that does not provide a valid resolution is considered
|
||||
buggy and must be fixed in the kernel. Some touchpad devices that do not
|
||||
provide resolution, those devices are correctly handled within libinput
|
||||
(touchpads are not absolute devices, as mentioned above).
|
||||
|
||||
@section absolute_axes_nonorm Why x/y coordinates are not normalized
|
||||
|
||||
|
|
@ -35,30 +59,4 @@ aspect ratio to the caller. Which shifts processing and likely errors into the
|
|||
caller for little benefit. Providing the x/y axes in mm from the outset
|
||||
removes these errors.
|
||||
|
||||
@section absolute_axes_handling Handling of absolute coordinates
|
||||
|
||||
In most use-cases, absolute input devices are mapped to a single screen. For
|
||||
direct input devices such as touchscreens the aspect ratio of the screen and
|
||||
the device match. Mapping the input device position to the output position is
|
||||
thus a simple mapping between two coordinates. libinput provides the API for
|
||||
this with
|
||||
|
||||
- libinput_event_pointer_get_absolute_x_transformed() for pointer events
|
||||
- libinput_event_touch_get_x_transformed() for touch events
|
||||
|
||||
See @ref index "the API doc" for more details.
|
||||
|
||||
libinput's API only provides the call to map into a single coordinate range.
|
||||
If the coordinate range has an offset, the compositor is responsible for
|
||||
applying that offset after the mapping. For example, if the device is mapped
|
||||
to the right of two outputs, add the output offset to the transformed
|
||||
coordinate.
|
||||
|
||||
@section absolute_axes_nores Devices without x/y resolution
|
||||
|
||||
An absolute device that does not provide a valid resolution is considered
|
||||
buggy and must be fixed in the kernel. Some touchpad devices that do not
|
||||
provide resolution, those devices are correctly handled within libinput
|
||||
(touchpads are not absolute devices, as mentioned above).
|
||||
|
||||
*/
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1,41 +1,28 @@
|
|||
/**
|
||||
@page clickpad_softbuttons Clickpad Software Button behavior
|
||||
@page clickpad_softbuttons Clickpad software button behavior
|
||||
|
||||
Clickpad is the name given to touchpads without physical buttons below the
|
||||
touchpad. Instead, the whole touchpad acts as a button and left or right
|
||||
button clicks are distinguished by the location and/or number of fingers on
|
||||
the touchpad. <a href="http://www.synaptics.com/en/clickpad.php">"ClickPad" is
|
||||
a term coined by Synaptics Inc.</a> but for simplicity we refer to any
|
||||
a trademark by Synaptics Inc.</a> but for simplicity we refer to any
|
||||
touchpad with the above feature as Clickpad, regardless of the manufacturer.
|
||||
|
||||
A clickpad is always marked with the INPUT_PROP_BUTTONPAD property. Note that
|
||||
there is a type of clickpads that have the top section marked as software
|
||||
buttons as well. See @ref t440_support "Lenovo *40 series touchpad support"
|
||||
for details on the top software button.
|
||||
A clickpad is always marked with the <a
|
||||
href="https://www.kernel.org/doc/Documentation/input/event-codes.txt">INPUT_PROP_BUTTONPAD</a> property.
|
||||
To perform a right-click on a Clickpad, libinput provides @ref
|
||||
software_buttons and @ref clickfinger.
|
||||
|
||||
To perform a right-click on a Clickpad, two methods are available in libinput:
|
||||
In the page below, the term "click" shall refer to a physical button press
|
||||
and/or release of the touchpad, the term "button event" refers to the events
|
||||
generated by libinput and passed to the caller in response to a click.
|
||||
|
||||
- on Apple touchpads, a right click is performed by two fingers on the
|
||||
touchpad while clicking, a behavior termed "clickfinger"
|
||||
- on non-Apple touchpads, a right click is performed by a finger in a
|
||||
software-defined right button area
|
||||
@section software_buttons Software button areas
|
||||
|
||||
The button behavior depends on the hardware. Some Clickpads, notably some
|
||||
Cypress ones, perform right button detection in firmware and appear to
|
||||
userspace as if the touchpad had physical buttons. While physically clickpads,
|
||||
these are not handled by the software and treated like traditional touchpads.
|
||||
|
||||
The clickfinger behavior is subject to some restrictions:
|
||||
|
||||
- two fingers execute a right click, three fingers a middle click
|
||||
- The Xorg synaptics driver uses 30% of the touchpad dimensions as threshold,
|
||||
libinput does not have this restrictions. If two fingers are on the pad
|
||||
while clicking, that is a two-finger click.
|
||||
- clickfinger behavior is only enabled on Apple touchpads
|
||||
|
||||
The button behavior is subject to some restrictions:
|
||||
|
||||
The button area is usually defined like this:
|
||||
On most clickpads, this is the default behavior. The bottom of the touchpad
|
||||
is split in the middle to generate left or right button events on click. The
|
||||
height of the button area depends on the hardware but is usually around
|
||||
10mm.
|
||||
|
||||
@dot
|
||||
digraph G {
|
||||
|
|
@ -46,22 +33,48 @@ digraph G {
|
|||
}
|
||||
@enddot
|
||||
|
||||
The size of the buttons is hardware dependent.
|
||||
Left, right and middle button events can be triggered as follows:
|
||||
- if a finger is in the main area or the left button area, a click generates
|
||||
left button events.
|
||||
- if a finger is in the right area, a click generates right button events.
|
||||
- if there is a finger in both the left and right button area, a click
|
||||
generates middle button events.
|
||||
|
||||
- if fingers are only down in the main area, a left click is generated
|
||||
- if a finger is in the right area when the physical click happens, a right
|
||||
click is generated
|
||||
- if fingers are in both the left and right area, a middle click is generated
|
||||
- fingers in the main area are not considered for right or middle click
|
||||
generation
|
||||
- if a finger starts in the main area, the software buttons do not apply to
|
||||
that finger
|
||||
- a finger in the software button area does not move the pointer, but once it
|
||||
moves out of the button area it will control the pointer (if it's the first
|
||||
finger to do so)
|
||||
If fingers are down in the main area in addition to fingers in the
|
||||
left or right button area, those fingers are are ignored.
|
||||
A release event always releases the buttons logically down, regardless of
|
||||
the current finger position
|
||||
|
||||
The movement of a finger can alter the button area behavior:
|
||||
- if a finger starts in the main area and moves into the software button
|
||||
area, the software buttons do not apply to that finger
|
||||
- a finger in the software button area does not move the pointer
|
||||
- if a finger moves out out of the button area it will control the pointer
|
||||
if it's the first finger in the main area
|
||||
- once a finger has moved out of the button area, it cannot move back in and
|
||||
trigger a right/middle button click
|
||||
- a release event releases the buttons logically down, regardless of the
|
||||
current finger position
|
||||
trigger a right or middle button event
|
||||
|
||||
*/
|
||||
@section clickfinger Clickfinger behavior
|
||||
|
||||
This is the default behavior on Apple touchpads.
|
||||
Here, a left, right, middle button event is generated when one, two, or
|
||||
three fingers are held down on the touchpad when a physical click is
|
||||
generated. The location of the fingers does not matter and there are no
|
||||
software-defined button areas.
|
||||
|
||||
The Xorg synaptics driver uses 30% of the touchpad dimensions as threshold,
|
||||
libinput does not have this restriction. If two fingers are on the pad
|
||||
while clicking, that is a two-finger click.
|
||||
|
||||
@section special_clickpads Special Clickpads
|
||||
|
||||
The Lenovo *40 series laptops have a clickpad that provides two software button sections, one at
|
||||
the top and one at the bottom. See @ref t440_support "Lenovo *40 series touchpad support"
|
||||
for details on the top software button.
|
||||
|
||||
Some Clickpads, notably some Cypress ones, perform right button detection in
|
||||
firmware and appear to userspace as if the touchpad had physical buttons.
|
||||
While physically clickpads, these are not handled by the software and
|
||||
treated like traditional touchpads.
|
||||
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
/**
|
||||
@page seats Seats
|
||||
|
||||
Each device in libinput is associated with one physical seat and one logical seat.
|
||||
|
||||
@section seats_overview Overview
|
||||
|
||||
@dotfile seats-sketch.gv
|
||||
|
|
|
|||
|
|
@ -1,6 +1,9 @@
|
|||
/**
|
||||
@page t440_support Lenovo *40 series touchpad support
|
||||
|
||||
The Lenovo *40 series emulates trackstick buttons on the top part of the
|
||||
touchpads.
|
||||
|
||||
@section t440_support_overview Overview
|
||||
|
||||
The Lenovo *40 series introduced a new type of touchpad. Previously, all
|
||||
|
|
@ -24,43 +27,48 @@ digraph G {
|
|||
}
|
||||
@enddot
|
||||
|
||||
The below is a list of what is needed for support of these devices. This page
|
||||
only covers the top software buttons, the bottom button behavior is covered in
|
||||
@ref clickpad_softbuttons "Clickpad software buttons".
|
||||
This page only covers the top software buttons, the bottom button behavior
|
||||
is covered in @ref clickpad_softbuttons "Clickpad software buttons".
|
||||
|
||||
Clickpads with a top button area are marked with the <a
|
||||
href="https://www.kernel.org/doc/Documentation/input/event-codes.txt">INPUT_PROP_TOPBUTTONPAD</a>
|
||||
property.
|
||||
|
||||
@section t440_support_btn_size Size of the buttons
|
||||
|
||||
The approximate size of the top software buttons is 8% of the touchpad's
|
||||
announced range, starting from the top. Note that a
|
||||
<a href="https://lkml.org/lkml/2014/3/7/722">kernel patch</a> is required to
|
||||
get the right ranges.
|
||||
The line of the buttons is 5mm from the top edge of the touchpad,
|
||||
measurements of button presses showed that the size of the buttons needs to
|
||||
be approximately 10mm high to work reliable (especially when using the
|
||||
thumb to press the button).
|
||||
|
||||
The size of the left and right buttons is approximately 42%, the middle button
|
||||
is centered and should be assigned approximately 16% of the touchpad width.
|
||||
The width of the left and right buttons is approximately 42% of the
|
||||
touchpad's width, the middle button is centered and should be assigned
|
||||
approximately 16% of the touchpad width.
|
||||
|
||||
@section t440_support_btn_behavior Button behavior
|
||||
|
||||
Movement in the top button area must not generate pointer movement, these
|
||||
buttons are not replacement buttons for the bottom area but have their own
|
||||
behaviour. They do not work for click-and-drag.
|
||||
Movement in the top button area does not generate pointer movement. These
|
||||
buttons are not replacement buttons for the bottom button area but have
|
||||
their own behavior.
|
||||
Semantically attached to the trackstick device, libinput re-routes events
|
||||
from these buttons to appear through the trackstick device. The top button
|
||||
areas work even if the touchpad is disabled but will be disabled when the
|
||||
trackstick device is disabled.
|
||||
|
||||
If the finger starts inside the top area and moves outside the button area
|
||||
without the physical button being down, movement may start.
|
||||
|
||||
Movement into the top button area should not trigger button events, a click
|
||||
the finger is treated as dead and must be lifted to generate future buttons.
|
||||
Likewise, movement into the top button area does not trigger button events, a click
|
||||
has to start inside this area to take effect.
|
||||
|
||||
The top button areas must work, even if the touchpad is otherwise disabled
|
||||
(e.g. by a disable-while-typing feature).
|
||||
@section t440_support_identification Kernel support
|
||||
|
||||
@section t440_support_identification Identification
|
||||
The firmware on touchpads providing top software buttons is buggy and
|
||||
announces wrong ranges. <a href="https://lkml.org/lkml/2014/3/7/722">Kernel
|
||||
patches</a> are required; these fixes are available in kernels
|
||||
3.14.1, 3.15 and later but each touchpad needs a separate fix.
|
||||
|
||||
The touchpads can be identified by the PNPID, or by a DMI match
|
||||
|
||||
- Helix: PnPID: <b>LEN0033</b>, DMI substring match <em>"Helix"</em>
|
||||
- T540: PnPID: <b>LEN0034</b>, DMI substring match <em>"T540?"</em>
|
||||
- x240: PnPID: <b>LEN0035</b>, DMI substring match <em>"X240"</em>
|
||||
- T440: PnPID: <b>LEN0036</b>, DMI substring match <em>"T440?"</em>
|
||||
- Yoga: PnPID: <b>LEN0042</b>, DMI subString match <em>"S1Yoga"</em>
|
||||
For a complete list of supported touchpads check <a
|
||||
href="http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/drivers/input/mouse/synaptics.c">the
|
||||
kernel source</a> (search for "topbuttonpad_pnp_ids").
|
||||
|
||||
*/
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue