fdo-mirrors/libinput
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/libinput/libinput.git synced 2025-12-25 17:30:06 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

dox: switch to sphinx for the user-visible documentation

Browse source 
This is a large commit because it's difficult to split this up and we don't
care about bisecting here anyway.

doxygen is going to produce the API documentation only
sphinx is going to produce the prose user (and a bit of developer) documentation.

The source split is doc/api and doc/user.

Steps performed:
- run the doxygen-to-sphinx.sh script to convert all .dox sources to .rst
- manually fixed the .rst to render correctly
- add a few extra .rst documents to generate the right hierarchy
- hook up sphinx-build in meson
- add a new @mainpage for doxygen more aimed at developers

For the build directory:
- sphinx produces /Documentation
- doxygen now produces /api/

These need to be manually combined in the wayland-web repo, meson doesn't
support subdirectories as output paths within the build dir and the
documentation doesn't need to be installed anywhere.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
This commit is contained in:
Peter Hutterer 2018-07-10 17:32:35 +10:00
parent 581fbbea64
commit cbd4f35442
98 changed files with 4271 additions and 2824 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

0
doc/git-version.dox → doc/api/git-version.dox
View file

3
doc/libinput.doxygen.in → doc/api/libinput.doxygen.in
View file

@ -13,7 +13,7 @@ INPUT = "@builddir@"
FILTER_PATTERNS = *.h *.dox
IMAGE_PATH = "@builddir@"
GENERATE_HTML = YES
HTML_OUTPUT = Documentation
HTML_OUTPUT = api
SEARCHENGINE = NO
USE_MATHJAX = YES
MATHJAX_RELPATH = https://cdn.mathjax.org/mathjax/latest
@ -31,4 +31,3 @@ HTML_FOOTER = "@builddir@/footer.html"
HTML_EXTRA_STYLESHEET = "@builddir@/bootstrap.css" \
"@builddir@/customdoxygen.css" \
"@builddir@/libinputdoxygen.css"
USE_MDFILE_AS_MAINPAGE = "README.md"

135
doc/api/mainpage.dox Normal file
View file

@ -0,0 +1,135 @@
/**
@mainpage
This is the libinput API reference.
This documentation is aimed at developers of Wayland compositors. User
documentation is available
[here](https://wayland.freedesktop.org/libinput/doc/latest).
@section concepts Concepts
@subsection concepts_initialization Initialization of a libinput context
libinput provides two different backends:
- a @ref libinput_udev_create_context "udev backend" where notifications
about new and removed devices are provided by udev, and
- a @ref libinput_path_create_context "path backend" where
@ref libinput_path_add_device "device addition" and
@ref libinput_path_remove_device "device removal" need to be handled by
the caller.
See section @ref base for information about initializing a libinput context.
@subsection concepts_events Monitoring for events
libinput exposes a single @ref libinput_get_fd "file descriptor" to the
caller. This file descriptor should be monitored by the caller, whenever
data is available the caller **must** immediately call libinput_dispatch().
Failure to do so will result in erroneous behavior.
libinput_dispatch() may result in one or more events being available to the
caller. After libinput_dispatch() a caller **should** call
libinput_get_event() to retrieve and process this event. Whenever
libinput_get_event() returns `NULL`, no further events are available.
See section @ref event for more information about events.
@subsection concepts_seats Device grouping into seats
All devices are grouped into physical and logical seats. Button and key
states are available per-device and per-seat. See @ref seat for more
information.
@subsection concepts_devices Device capabilities
libinput does not use device types. All devices have @ref
libinput_device_has_capability "capabilities" that define which events may
be generated. See @ref device for more information about devices.
Specific event types include:
- @ref event_keyboard
- @ref event_pointer
- @ref event_touch
- @ref event_gesture
- @ref event_tablet
- @ref event_tablet_pad
- @ref event_switch
@subsection concepts_configuration Device configuration
libinput relies on the caller for device configuration. See
@ref config for more information.
@subsection example An example libinput program
The simplest libinput program looks like this:
@code
static int open_restricted(const char *path, int flags, void *user_data)
{
int fd = open(path, flags);
return fd < 0 ? -errno : fd;
}
static void close_restricted(int fd, void *user_data)
{
close(fd);
}
const static struct libinput_interface interface = {
.open_restricted = open_restricted,
.close_restricted = close_restricted,
};
int main(void) {
struct libinput *li;
struct libinput_event *event;
li = libinput_udev_create_context(&interface, NULL, udev);
libinput_udev_assign_seat(li, "seat0");
libinput_dispatch(li);
while ((event = libinput_get_event(li)) != NULL) {
// handle the event here
libinput_event_destroy(li);
libinput_dispatch(li);
}
libinput_unref(li);
return 0;
}
@endcode
@section building_against Building against libinput
libinput provides a
[pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) file.
Software that uses libinput should use pkg-config and the
`PKG_CHECK_MODULES` autoconf macro.
Otherwise, the most rudimentary way to compile and link a program against
libinput is:
@verbatim
gcc -o myprogram myprogram.c `pkg-config --cflags --libs libinput`
@endverbatim
For further information on using pkgconfig see the pkg-config documentation.
@section stability Backwards-compatibility
libinput promises backwards-compatibility across all the 1.x.y version. An
application built against libinput 1.x.y will work with any future 1.*.*
release.
@section About
Documentation generated by from git commit [__GIT_VERSION__](https://gitlab.freedesktop.org/libinput/libinput/commit/__GIT_VERSION__)
*/

88
doc/meson.build → doc/api/meson.build
View file

@ -35,98 +35,26 @@ doc_git_version = vcs_tag(command : ['git', 'log', '-1', '--format=%h'],
output : 'git-version.dox',
replace_string: '__GIT_VERSION__')
readme = vcs_tag(command : ['git', 'log', '-1', '--format=%h'],
mainpage = vcs_tag(command : ['git', 'log', '-1', '--format=%h'],
fallback : 'unknown',
input : '../README.md',
output : 'README.md',
input : 'mainpage.dox',
output : 'mainpage.dox',
replace_string: '__GIT_VERSION__')
src_extra = [
# dot drawings
'dot/seats-sketch.gv',
'dot/seats-sketch-libinput.gv',
'dot/libinput-stack-wayland.gv',
'dot/libinput-stack-xorg.gv',
'dot/libinput-stack-gnome.gv',
'dot/evemu.gv',
# svgs
'svg/button-debouncing-wave-diagram.svg',
'svg/button-scrolling.svg',
'svg/clickfinger.svg',
'svg/clickfinger-distance.svg',
'svg/edge-scrolling.svg',
'svg/gesture-2fg-ambiguity.svg',
'svg/palm-detection.svg',
'svg/pinch-gestures.svg',
'svg/pinch-gestures-softbuttons.svg',
'svg/ptraccel-linear.svg',
'svg/ptraccel-low-dpi.svg',
'svg/ptraccel-touchpad.svg',
'svg/ptraccel-trackpoint.svg',
'svg/software-buttons.svg',
'svg/swipe-gestures.svg',
'svg/tablet-axes.svg',
'svg/tablet-cintiq24hd-modes.svg',
'svg/tablet-interfaces.svg',
'svg/tablet-intuos-modes.svg',
'svg/tablet-left-handed.svg',
'svg/tablet-out-of-bounds.svg',
'svg/tablet.svg',
'svg/tap-n-drag.svg',
'svg/thumb-detection.svg',
'svg/top-software-buttons.svg',
'svg/touchscreen-gestures.svg',
'svg/trackpoint-delta-illustration.svg',
'svg/twofinger-scrolling.svg',
]
src_doxygen = files(
# source files
'../src/libinput.h',
# written docs
'absolute-axes.dox',
'absolute-coordinate-ranges.dox',
'architecture.dox',
'building.dox',
'button_debouncing.dox',
'clickpad-softbuttons.dox',
'contributing.dox',
'device-configuration-via-udev.dox',
'device-quirks.dox',
'faqs.dox',
'gestures.dox',
'middle-button-emulation.dox',
'normalization-of-relative-motion.dox',
'palm-detection.dox',
'page-hierarchy.dox',
'pointer-acceleration.dox',
'reporting-bugs.dox',
'scrolling.dox',
'seats.dox',
'switches.dox',
't440-support.dox',
'tablet-support.dox',
'tapping.dox',
'test-suite.dox',
'timestamps.dox',
'tools.dox',
'touchpad-jumping-cursors.dox',
'touchpad-pressure.dox',
'touchpad-jitter.dox',
'touchpads.dox',
'trackpoints.dox',
'what-is-libinput.dox',
join_paths(meson.source_root(), 'src', 'libinput.h'),
# style files
'style/header.html',
'style/footer.html',
'style/customdoxygen.css',
'style/bootstrap.css',
'style/libinputdoxygen.css',
src_extra,
)
doxyfiles = custom_target('doxyfiles',
input : src_doxygen,
output : '.',
output : 'doxyfiles',
command : [prg_install, '-t', '@OUTDIR@', '@INPUT@'],
build_by_default: true)
@ -141,9 +69,9 @@ doxyfile = configure_file(input : 'libinput.doxygen.in',
install : false)
custom_target('doxygen',
input : [ doxyfile, readme, doc_git_version] + src_doxygen + src_extra,
output : [ 'Documentation' ],
input : [ doxyfile, mainpage, doc_git_version] + src_doxygen,
output : [ '.' ],
command : [ doxygen, doxyfile ],
install : false,
depends: [doxyfiles, readme, doc_git_version],
depends: [doxyfiles, mainpage, doc_git_version],
build_by_default : true)

7
doc/api/page-hierarchy.dox Normal file
View file

@ -0,0 +1,7 @@
/**
@page Tablets
- @subpage tablet serial numbers
*/

0
doc/style/LICENSE → doc/api/style/LICENSE
View file

0
doc/style/bootstrap.css → doc/api/style/bootstrap.css vendored
View file

1
doc/style/customdoxygen.css → doc/api/style/customdoxygen.css
View file

@ -252,4 +252,3 @@ blockquote {
margin: 0 24px 0 4px;
padding: 0 12px 0 16px;
}

0
doc/style/footer.html → doc/api/style/footer.html
View file

2
doc/style/header.html → doc/api/style/header.html
View file

@ -8,7 +8,7 @@
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta name="generator" content="Doxygen $doxygenversion"/>
<script type="text/javascript" src="https://code.jquery.com/jquery-2.1.1.min.js"></script>
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->

0
doc/style/libinputdoxygen.css → doc/api/style/libinputdoxygen.css
View file

282
doc/architecture.dox
View file

@ -1,282 +0,0 @@
/**
@page architecture libinput's internal architecture
This page provides an outline of libinput's internal architecture. The goal
here is to get the high-level picture across and point out the components
and their interplay to new developers.
The public facing API is in `libinput.c`, this file is thus the entry point
for almost all API calls. General device handling is in `evdev.c` with the
device-type-specific implementations in `evdev-<type>.c`. It is not
necessary to understand all of libinput to contribute a patch.
@ref architecture-contexts is the only user-visible implementation detail,
everything else is purely internal implementation and may change when
required.
@section architecture-contexts The udev and path contexts
The first building block is the "context" which can be one of
two types, "path" and "udev". See libinput_path_create_context() and
libinput_udev_create_context(). The path/udev specific bits are in
`path-seat.c` and `udev-seat.c`. This includes the functions that add new
devices to a context.
@dot
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
libudev [label="libudev 'add' event"]
udev [label="libinput_udev_create_context()"];
udev_backend [label="udev-specific backend"];
context [label="libinput context"]
udev -> udev_backend;
libudev -> udev_backend;
udev_backend -> context;
}
@enddot
The udev context provides automatic device hotplugging as udev's "add"
events are handled directly by libinput. The path context requires that the
caller adds devices.
@dot
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
path [label="libinput_path_create_context()"];
path_backend [label="path-specific backend"];
xdriver [label="libinput_path_add_device()"]
context [label="libinput context"]
path -> path_backend;
xdriver -> path_backend;
path_backend -> context;
}
@enddot
As a general rule: all Wayland compositors use a udev context, the X.org
stack uses a path context.
Which context was initialized only matters for creating/destroying a context
and adding devices. The device handling itself is the same for both types of
context.
@section architecture-device Device initialization
libinput only supports evdev devices, all the device initialization is done
in `evdev.c`. Much of the libinput public API is also a thin wrapper around
the matching implementation in the evdev device.
There is a 1:1 mapping between libinput devices and `/dev/input/eventX`
device nodes.
@dot
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
devnode [label="/dev/input/event0"]
libudev [label="libudev 'add' event"]
xdriver [label="libinput_path_add_device()"]
context [label="libinput context"]
evdev [label="evdev_device_create()"]
devnode -> xdriver;
devnode -> libudev;
xdriver -> context;
libudev -> context;
context->evdev;
}
@enddot
Entry point for all devices is `evdev_device_create()`, this function
decides to create a `struct evdev_device` for the given device node.
Based on the udev tags (e.g. `ID_INPUT_TOUCHPAD`), a @ref
architecture-dispatch is initialized. All event handling is then in this
dispatch.
Rejection of devices and the application of quirks is generally handled in
`evdev.c` as well. Common functionality shared across multiple device types
(like button-scrolling) is also handled here.
@section architecture-dispatch Device-type specific event dispatch
Depending on the device type, `evdev_configure_device` creates the matching
`struct evdev_dispatch`. This dispatch interface contains the function
pointers to handle events. Four such dispatch methods are currently
implemented: touchpad, tablet, tablet pad, and the fallback dispatch which
handles mice, keyboards and touchscreens.
@dot
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
evdev [label="evdev_device_create()"]
fallback [label="evdev-fallback.c"]
touchpad [label="evdev-mt-touchpad.c"]
tablet [label="evdev-tablet.c"]
pad [label="evdev-tablet-pad.c"]
evdev -> fallback;
evdev -> touchpad;
evdev -> tablet;
evdev -> pad;
}
@enddot
While `evdev.c` pulls the event out of libevdev, the actual handling of the
events is performed within the dispatch method.
@dot
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
evdev [label="evdev_device_dispatch()"]
fallback [label="fallback_interface_process()"];
touchpad [label="tp_interface_process()"]
tablet [label="tablet_process()"]
pad [label="pad_process()"]
evdev -> fallback;
evdev -> touchpad;
evdev -> tablet;
evdev -> pad;
}
@enddot
The dispatch methods then look at the `struct input_event` and proceed to
update the state. Note: the serialized nature of the kernel evdev protocol
requires that the device updates the state with each event but to delay
processing until the `SYN_REPORT` event is received.
@section architecture-configuration Device configuration
All device-specific configuration is handled through `struct
libinput_device_config_FOO` instances. These are set up during device init
and provide the function pointers for the `get`, `set`, `get_default`
triplet of configuration queries (or more, where applicable).
For example, the `struct tablet_dispatch` for tablet devices has a
`struct libinput_device_config_accel`. This struct is set up with the
required function pointers to change the profiles.
@dot
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
tablet [label="struct tablet_dispatch"]
config [label="struct libinput_device_config_accel"];
tablet_config [label="tablet_accel_config_set_profile()"];
tablet->config;
config->tablet_config;
}
@enddot
When the matching `libinput_device_config_set_FOO()` is called, this goes
through to the config struct and invokes the function there. Thus, it is
possible to have different configuration functions for a mouse vs a
touchpad, even though the interface is the same.
@dot
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
libinput [label="libinput_device_config_accel_set_profile()"];
tablet_config [label="tablet_accel_config_set_profile()"];
libinput->tablet_config;
}
@enddot
@section architecture-filter Pointer acceleration filters
All pointer acceleration is handled in the `filter.c` file and its
associated files.
The `struct motion_filter` is initialized during device init, whenever
deltas are available they are passed to `filter_dispatch()`. This function
returns a set of @ref motion_normalization_customization "normalized coordinates".
All actual acceleration is handled within the filter, the device itself has
no further knowledge. Thus it is possible to have different acceleration
filters for the same device types (e.g. the Lenovo X230 touchpad has a
custom filter).
@dot
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
fallback [label="fallback deltas"];
touchpad [label="touchpad deltas"];
tablet [label="tablet deltas"];
filter [label="filter_dispatch"];
fallback->filter;
touchpad->filter;
tablet->filter;
flat [label="accelerator_interface_flat()"];
x230 [label="accelerator_filter_x230()"];
pen [label="tablet_accelerator_filter_flat_pen()"];
filter->flat;
filter->x230;
filter->pen;
}
@enddot
Most filters convert the deltas (incl. timestamps) to a motion speed and
then apply a so-called profile function. This function returns a factor that
is then applied to the current delta, converting it into an accelerated
delta. See @ref pointer-acceleration for more details.
the current
*/

244
doc/building.dox
View file

@ -1,244 +0,0 @@
/**
@page building_libinput libinput build instructions
@tableofcontents
Instructions on how to build libinput and its tools and how to build against
libinput.
The build instruction on this page detail how to overwrite your
system-provided libinput with one from the git repository, see
see @ref reverting_install to revert to the previous state.
@section building Building libinput
libinput uses [meson](https://www.mesonbuild.com) and
[ninja](https://www.ninja-build.org). A build is usually the three-step
process below. A successful build requires the @ref
building_dependencies to be installed before running meson.
@verbatim
$> git clone https://gitlab.freedesktop.org/libinput/libinput
$> cd libinput
$> meson --prefix=/usr builddir/
$> ninja -C builddir/
$> sudo ninja -C builddir/ install
@endverbatim
When running libinput versions 1.11.x or earlier, you must run
@verbatim
$> sudo udevadm hwdb --update
@endverbatim
Additional options may also be specified. For example:
@verbatim
$> meson --prefix=/usr -Ddocumentation=false builddir/
@endverbatim
We recommend that users disable the documentation, it's not usually required
for testing and reduces the number of dependencies needed.
The `prefix` or other options can be changed later with the
`mesonconf` command. For example:
@verbatim
$> mesonconf builddir/ -Dprefix=/some/other/prefix -Ddocumentation=true
$> ninja -C builddir
$> sudo ninja -C builddir/ install
@endverbatim
Running ``mesonconf builddir/`` with no other arguments lists all
configurable options meson provides.
To rebuild from scratch, simply remove the build directory and run meson
again:
@verbatim
$> rm -r builddir/
$> meson --prefix=....
@endverbatim
@subsection verifying_install Verifying the install
To verify the install worked correctly, check that libinput.so.x.x.x is in
the library path and that all symlinks point to the new library.
@verbatim
$> ls -l /usr/lib64/libinput.*
-rwxr-xr-x 1 root root 946 Apr 28 2015 /usr/lib64/libinput.la
lrwxrwxrwx 1 root root 19 Feb 1 15:12 /usr/lib64/libinput.so -> libinput.so.10.13.0
lrwxrwxrwx 1 root root 19 Feb 1 15:12 /usr/lib64/libinput.so.10 -> libinput.so.10.13.0
-rwxr-xr-x 1 root root 204992 Feb 1 15:12 /usr/lib64/libinput.so.10.13.0
@endverbatim
@subsection reverting_install Reverting to the system-provided libinput package
The recommended way to revert to the system install is to use the package
manager to reinstall the libinput package. In some cases, this may leave
files in the system (e.g. `/usr/lib/libinput.la`) but these files are
usually harmless. To definitely remove all files, run the following command
from the libinput source directory:
@verbatim
$> sudo ninja -C builddir/ uninstall
# WARNING: Do not restart the computer/X/the Wayland compositor after
# uninstall, reinstall the system package immediately!
@endverbatim
The following commands reinstall the current system package for libinput,
overwriting manually installed files.
- **Debian/Ubuntu** based distributions: `sudo apt-get install --reinstall libinput`
- **Fedora 22** and later: `sudo dnf reinstall libinput`
- **RHEL/CentOS/Fedora 21** and earlier: `sudo yum reinstall libinput`
- **openSUSE**: `sudo zypper install --force libinput10`
- **Arch**: `sudo packman -S libinput`
@subsection building_selinux SELinux adjustments
On systems with SELinux, overwriting the distribution-provided package with
a manually built libinput may cause SELinux denials. This usually manifests
when gdm does not start because it is denied access to libinput. The journal
shows a log message in the form of:
@verbatim
May 25 15:28:42 localhost.localdomain audit[23268]: AVC avc: denied { execute } for pid=23268 comm="gnome-shell" path="/usr/lib64/libinput.so.10.12.2" dev="dm-0" ino=1709093 scontext=system_u:system_r:xdm_t:s0-s0:c0.c1023 tcontext=unconfined_u:object_r:user_home_t:s0 tclass=file permissive=0
May 25 15:28:42 localhost.localdomain org.gnome.Shell.desktop[23270]: /usr/bin/gnome-shell: error while loading shared libraries: libinput.so.10: failed to map segment from shared object
@endverbatim
The summary of this error message is that gdm's gnome-shell runs in the
`system_u:system_r:xdm_t` context but libinput is installed with the
context `unconfined_u:object_r:user_home_t`.
To avoid this issue, restore the SELinux context for any system files.
@verbatim
$> sudo restorecon /usr/lib*/libinput.so.*
@endverbatim
This issue is tracked in https://github.com/mesonbuild/meson/issues/1967.
@subsection building_dependencies Build dependencies
libinput has a few build-time dependencies that must be installed prior to
running configure.
@note The build dependencies for some distributions can be found in the
[GitLab Continuous Integration file](https://gitlab.freedesktop.org/libinput/libinput/blob/master/.gitlab-ci.yml).
Search for **FEDORA_RPMS** in the **variables:** definition
and check the list for an entry for your distribution.
In most cases, it is sufficient to install the dependencies that your
distribution uses to build the libinput package. These can be installed
with one of the following commands:
- **Debian/Ubuntu** based distributions: `sudo apt-get build-dep libinput`
- **Fedora 22** and later: `sudo dnf builddep libinput`
- **RHEL/CentOS/Fedora 21** and earlier: `sudo yum-builddep libinput`
- **openSUSE**: @verbatim
$> sudo zypper modifyrepo --enable `zypper repos | grep source | awk '{print $5}'`
$> sudo zypper source-install -d libinput10
$> sudo zypper install autoconf automake libtool
$> sudo zypper modifyrepo --disable `zypper repos | grep source | awk '{print $5}'`
@endverbatim
- **Arch**: @verbatim
$> sudo pacman -S asp
$> cd $(mktemp -d)
$> asp export libinput
$> cd libinput
$> makepkg --syncdeps --nobuild --noextract
@endverbatim
If dependencies are missing, a message `No package 'foo' found` will be
shown during the configure stage. See
[this blog post here](https://who-t.blogspot.com.au/2014/05/configure-fails-with-no-package-foo.html)
for instructions on how to fix it.
@subsection building_libwacom Building without libwacom
libwacom is required by libinput's tablet code to gather additional
information about tablets that is not available from the kernel device
itself. libwacom is required by default but can be skipped when @ref
building.
@verbatim
$> meson --prefix=/usr -Dlibwacom=false builddir
@endverbatim
It is not recommended to disable libwacom unless libinput is used in an
environment where tablet support is not required. libinput provides tablet
support even without libwacom, but some features may be missing or working
differently.
@subsection building_debug_gui Building without the graphical helper tool
The @ref tools provide commandline features as well as graphical debugging
features. To keep dependencies in check on some builds, the graphical
features of the @ref tools can be disabled. By default, the `debug-gui`
feature of the `libinput` tool is enabled and if the required libraries are
not available, the build will fail. If the feature is not required, use the
``--disable-debug-gui`` argument when @ref building.
@verbatim
$> meson --prefix=/usr -Ddebug-gui=false builddir
@endverbatim
@subsection building_autotools Building with autotools
<b>libinput no longer supports building with autotools.</b> These
instructions are kept for users for libinput versions up to 1.8.x.
A build with automake is usually the process below. A successful build
requires the @ref building_dependencies to be installed at configure
time.
@verbatim
$> git clone https://gitlab.freedesktop.org/libinput/libinput
$> cd libinput
$> ./autogen.sh --prefix=/usr --libdir=/usr/lib64
$> make
$> sudo make install
$> sudo udevadm hwdb --update
@endverbatim
@note On Debian-based distributions including Ubuntu and its derivatives skip the
`--libdir=/usr/lib64` argument.
To uninstall libinput as detailed in section @ref reverting_install, run
@verbatim
$> sudo make uninstall
# WARNING: Do not restart the computer/X/the Wayland compositor after make
# uninstall, reinstall the system package immediately!
@endverbatim
To disable libwacom as detailed in section @ref building_libwacom, run
@verbatim
$> ./autogen.sh --disable-libwacom --prefix=/usr --libdir=/usr/lib64
@endverbatim
To disable the graphical helper tool as detailed in section @ref
building_debug_gui, run
@verbatim
$> ./autogen.sh --disable-debug-gui --prefix=/usr --libdir=/usr/lib64
@endverbatim
@section building_against Building against libinput
libinput provides a
[pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) file.
Software that uses libinput should use pkg-config and the
`PKG_CHECK_MODULES` autoconf macro.
Otherwise, the most rudimentary way to compile and link a program against
libinput is:
@verbatim
gcc -o myprogram myprogram.c `pkg-config --cflags --libs libinput`
@endverbatim
For further information on using pkgconfig see the pkg-config documentation.
*/

18
doc/contributing.dox
View file

@ -1,18 +0,0 @@
/**
@page contributing Contributing to libinput
Contributions to libinput are always welcome. Any patches should be sent to
the
[wayland-devel](https://lists.freedesktop.org/mailman/listinfo/wayland-devel)
email list with a subject prefix of `[PATCH libinput]`. The easiest
way to achieve that is to run the following command in the libinput
repository:
git config --add format.subjectprefix "PATCH libinput"
Likewise, any new features should also be discussed publicly on the
wayland-devel list.
*/

229
doc/device-configuration-via-udev.dox
View file

@ -1,229 +0,0 @@
/**
@page udev_config Static device configuration via udev
libinput supports some static configuration through udev properties.
These properties are read when the device is initially added
to libinput's device list, i.e. before the @ref
LIBINPUT_EVENT_DEVICE_ADDED event is generated.
The following udev properties are supported:
<dl>
<dt>LIBINPUT_CALIBRATION_MATRIX</dt>
<dd>Sets the calibration matrix, see
libinput_device_config_calibration_get_default_matrix(). If unset,
defaults to the identity matrix.
The udev property is parsed as 6 floating point numbers separated by a
single space each (scanf(3) format "%f %f %f %f %f %f").
The 6 values represent the first two rows of the calibration matrix as
described in libinput_device_config_calibration_set_matrix().
Example values are:
@code
ENV{LIBINPUT_CALIBRATION_MATRIX}="1 0 0 0 1 0" # default
ENV{LIBINPUT_CALIBRATION_MATRIX}="0 -1 1 1 0 0" # 90 degree clockwise
ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 -1 1" # 180 degree clockwise
ENV{LIBINPUT_CALIBRATION_MATRIX}="0 1 0 -1 0 1" # 270 degree clockwise
ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 1 0" # reflect along y axis
@endcode
</dd>
<dt>LIBINPUT_DEVICE_GROUP</dt>
<dd>A string identifying the @ref libinput_device_group for this device. Two
devices with the same property value are grouped into the same device group,
the value itself is irrelevant otherwise.
</dd>
<dt>LIBINPUT_IGNORE_DEVICE</dt>
<dd>If set to anything other than "0", the device is ignored by libinput.
See @ref ignoring_devices for more details.
</dd>
<dt>ID_SEAT</dt>
<dd>Assigns the physical @ref seats "seat" for this device. See
libinput_seat_get_physical_name(). Defaults to "seat0".</dd>
<dt>ID_INPUT</dt>
<dd>If this property is set, the device is considered an input device. Any
device with this property missing will be ignored, see @ref udev_device_type.
</dd>
<dt>ID_INPUT_KEYBOARD, ID_INPUT_KEY, ID_INPUT_MOUSE, ID_INPUT_TOUCHPAD,
ID_INPUT_TOUCHSCREEN, ID_INPUT_TABLET, ID_INPUT_JOYSTICK,
ID_INPUT_ACCELEROMETER</dt>
<dd>If any of the above is set, libinput initializes the device as the given
type, see @ref udev_device_type. Note that for historical reasons more than
one of these may be set at any time, libinput will select only one of these
to determine the device type. To ensure libinput selects the correct device
type, only set one of them.</dd>
<dt>WL_SEAT</dt>
<dd>Assigns the logical @ref seats "seat" for this device. See
libinput_seat_get_logical_name()
context. Defaults to "default".</dd>
<dt>MOUSE_DPI</dt>
<dd>HW resolution and sampling frequency of a relative pointer device.
See @ref motion_normalization for details.
</dd>
<dt>MOUSE_WHEEL_CLICK_ANGLE</dt>
<dd>The angle in degrees for each click on a mouse wheel. See
libinput_pointer_get_axis_source() for details.
</dd>
</dl>
Below is an example udev rule to assign "seat1" to a device from vendor
0x012a with the model ID of 0x034b.
@code
ACTION=="add|change", KERNEL=="event[0-9]*", ENV{ID_VENDOR_ID}=="012a", \
ENV{ID_MODEL_ID}=="034b", ENV{ID_SEAT}="seat1"
@endcode
@section udev_device_type Device type assignment via udev
libinput requires the <b>ID_INPUT</b> property to be set on a device,
otherwise the device will be ignored. In addition, one of <b>
ID_INPUT_KEYBOARD, ID_INPUT_KEY, ID_INPUT_MOUSE, ID_INPUT_TOUCHPAD,
ID_INPUT_TOUCHSCREEN, ID_INPUT_TABLET, ID_INPUT_JOYSTICK,
ID_INPUT_ACCELEROMETER</b> must be set on the device to determine the
device type. The usual error handling applies within libinput and a device
type label does not guarantee that the device is initialized by libinput.
If a device fails to meet the requirements for a device type (e.g. a keyboard
labelled as touchpad) the device will not be available through libinput.
Only one device type should be set per device at a type, though libinput can
handle some combinations for historical reasons.
Below is an example udev rule to remove an <b>ID_INPUT_TOUCHPAD</b> setting
and change it into an <b>ID_INPUT_TABLET</b> setting. This rule would apply
for a device with the vendor/model ID of 012a/034b.
@code
ACTION=="add|change", KERNEL=="event[0-9]*", ENV{ID_VENDOR_ID}=="012a", \
ENV{ID_MODEL_ID}=="034b", ENV{ID_INPUT_TOUCHPAD}="", ENV{ID_INPUT_TABLET}="1"
@endcode
@section ignoring_devices Ignoring specific devices
If a device has the <b>LIBINPUT_IGNORE_DEVICE</b> udev property set to any
value but "0", that device is not initialized by libinput. For a context
created with libinput_udev_create_context(), the device is silently ignored
and never shows up. If the device is added with libinput_path_add_device()
to a context created with libinput_path_create_context(), adding the device
will fail and return NULL (see that function's documentation for more
information).
If the property value is exactly "0", then the property is considered unset
and libinput initializes the device normally.
This property should be used for devices that are correctly detected as
input devices (see @ref udev_device_type) but that should not be used by
libinput. It is recommended that devices that should not be handled as input
devices at all unset the <b>ID_INPUT</b> and related properties instead. The
<b>LIBINPUT_IGNORE_DEVICE</b> property signals that only libinput should
ignore this property but other parts of the stack (if any) should continue
treating this device normally.
@section model_specific_configuration Model-specific configuration
As of libinput 1.12, model-specific configuration is stored in the @ref
device-quirks and not in the hwdb anymore. Please see @ref device-quirks for
details.
@subsection model_specific_configuration_x220fw81 Lenovo x220 with touchpad firmware v8.1
The property <b>LIBINPUT_MODEL_LENOVO_X220_TOUCHPAD_FW81</b> may be set by a
user in a local hwdb file. This property designates the touchpad on a Lenovo
x220 with a touchpad firmware version 8.1. When this firmware version is
installed, the touchpad is imprecise. The touchpad device does not send
continuos x/y axis position updates, a behavior also observed on its
successor model, the Lenovo x230 which has the same firmware version. If the
above property is set, libinput adjusts its behavior to better suit this
particular model.
The touchpad firmware version cannot be detected automatically by libinput,
local configuration is required to set this property. Refer to the libinput
model quirks hwdb for instructions.
This property must not be used for any other purpose, no specific behavior
is guaranteed.
@section hwdb Configuring the hwdb
This section outlines how to query the
[udev hwdb](https://www.freedesktop.org/software/systemd/man/hwdb.html)
and reload properties so they are available to libinput.
The hwdb contains a set of match rules that assign udev properties that are
available to libinput when the device is connected and/or libinput is
initialized. This section only describes the hwdb in relation to libinput,
it is not a full documentation on how the hwdb works.
libinput's use of the hwdb is limited to properties systemd and custom
rules files (where available) provide. Hardware-specific quirks as used by
libinput are in the @ref device-quirks system.
@subsection hwdb_querying Querying the hwdb
libinput only uses device nodes in the form of `/dev/input/eventX` where X
is the number of the specific device. Running `libinput debug-events` lists
all devices currently available to libinput and their event node name:
$> sudo libinput debug-events
-event2 DEVICE_ADDED Power Button seat0 default group1 cap:k
-event5 DEVICE_ADDED Video Bus seat0 default group2 cap:k
-event0 DEVICE_ADDED Lid Switch seat0 default group3 cap:S
...
Note the event node name for your device and translate it into a syspath in
the form of `/sys/class/input/eventX`. This path can be supplied to `udevadm
info`
$> udevadm info
P: /devices/LNXSYSTM:00/LNXSYBUS:00/PNP0C0D:00/input/input0/event0
N: input/event0
E: DEVNAME=/dev/input/event0
E: DEVPATH=/devices/LNXSYSTM:00/LNXSYBUS:00/PNP0C0D:00/input/input0/event0
E: ID_INPUT=1
E: ID_INPUT_SWITCH=1
E: MAJOR=13
E: MINOR=64
E: SUBSYSTEM=input
E: TAGS=:power-switch:
E: USEC_INITIALIZED=7167898
Lines starting with `E:` are udev properties available to libinput. For
example, the above device's `ID_INPUT_SWITCH` property will cause libinput
to treat this device as switch device.
@subsection hwdb_reloading Reloading the hwdb
The actual hwdb is stored in binary file on-disk and must be updated
manually whenever a `.hwdb` file changes. This is required both when a user
manually edits the `.hwdb` file but also when the git tree is updated (and
that update causes a hwdb change).
To update the binary file on-disk, run:
sudo udevadm hwdb --update
Then, to trigger a reload of all properties on your device, run:
sudo udevadm trigger /sys/class/input/eventX
Then check with `udevadm info` whether the properties were updated, see @ref
hwdb_querying. If a new property does not appear on the device, use `udevadm
test` to check for error messages by udev and the hwdb (e.g. syntax errors
in the udev rules files).
sudo udevadm test /sys/class/input/eventX
@subsection hwdb_modifying Modifying the hwdb
***This section has been removed as it no longer applies in libinput 1.12
and later.*** libinput users should not need to modify the hwdb, any
device-specific quirks must go in to the @ref device-quirks system.
For information about older libinput versions, please see the documentation
for your version avaialable in: https://wayland.freedesktop.org/libinput/doc/
*/

178
doc/device-quirks.dox
View file

@ -1,178 +0,0 @@
/**
@page device-quirks Device quirks
libinput requires extra information from devices that is not always readily
available. For example, some touchpads are known to have jumping cursors
under specific conditions. libinput ships a set of files containting the
so-called model quirks to provide that information. Model quirks are usually
installed under `/usr/share/libinput/<filename>.quirks` and are standard
`.ini` files. A file may contain multiple section headers (`[some
identifier]`) followed by one or more `MatchFoo=Bar` directives, followed by
at least one of `ModelFoo=1` or `AttrFoo=bar` directive. See the
`quirks/README.md` file in the libinput source repository for more details on
their contents.
@note Model quirks are internal API and may change at any time. No
backwards-compatibility is guaranteed.
For example, a quirks file may have this content to label all keyboards on
the serial bus (PS/2) as internal keyboards:
@verbatim
[Serial Keyboards]
MatchUdevType=keyboard
MatchBus=serial
AttrKeyboardIntegration=internal
@endverbatim
The model quirks are part of the source distribution and should never be
modified locally. Updates to libinput may overwrite modifications or even
stop parsing any property. For temporary local workarounds, see @ref
device-quirks-local.
Device quirks are parsed on libinput initialization. A parsing error in the
device quirks disables **all** device quirks and may negatively impact
device behavior on the host. If the quirks cannot be loaded, an error
message is posted to the log and users should use the information in @ref
device-quirks-debugging to verify their quirks files.
@section device-quirks-local Installing temporary local device quirks
The model quirks are part of the source distribution and should never be
modified. For temporary local workarounds, libinput reads the
`/etc/libinput/local-overrides.quirks` file. Users may add a sections to
this file to add a device quirk for a local device but beware that **any
modification must be upstreamed** or it may cease to work at any time.
@note Model quirks are internal API and may change at any time. No
backwards-compatibility is guaranteed. Local overrides should only
be used until the distribution updates the libinput packages.
The `local-overrides.quirks` file usually needs to be created by the user.
Once the required section has been added, use the information from section
@ref device-quirks-debugging to validate and test the quirks.
@section device-quirks-debugging Debugging device quirks
libinput provides the `libinput quirks` tool to debug the quirks database.
This tool takes an action as first argument, the most common invocation is
`libinput quirks list` to list model quirks that apply to one or more local
devices.
@verbatim
$ libinput quirks list /dev/input/event19
Device has no quirks defined
$ libinput quirks list /dev/input/event0
AttrLidSwitchReliability
@endverbatim
When called with the `--verbose` argument, `libinput quirks list` prints
information about all files and its attempts to match the device:
@verbatim
$ libinput quirks list --verbose /dev/input/event0
quirks debug: /usr/share/share/libinput is data root
quirks debug: /usr/share/share/libinput/10-generic-keyboard.quirks
quirks debug: /usr/share/share/libinput/10-generic-lid.quirks
[...]
quirks debug: /usr/share/etc/libinput/local-overrides.quirks
quirks debug: /dev/input/event0: fetching quirks
quirks debug: [Serial Keyboards] (10-generic-keyboard.quirks) wants MatchBus but we don't have that
quirks debug: [Lid Switch Ct9] (10-generic-lid.quirks) matches for MatchName
quirks debug: [Lid Switch Ct10] (10-generic-lid.quirks) matches for MatchName
quirks debug: [Lid Switch Ct10] (10-generic-lid.quirks) matches for MatchDMIModalias
quirks debug: [Lid Switch Ct10] (10-generic-lid.quirks) is full match
quirks debug: property added: AttrLidSwitchReliability from [Lid Switch Ct10] (10-generic-lid.quirks)
quirks debug: [Aiptek No Tilt Tablet] (30-vendor-aiptek.quirks) wants MatchBus but we don't have that
[...]
quirks debug: [HUION PenTablet] (30-vendor-huion.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech Marble Mouse Trackball] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech K400] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech K400r] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech K830] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech K400Plus] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech Wireless Touchpad] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Microsoft Surface 3 Lid Switch] (30-vendor-microsoft.quirks) matches for MatchName
[...]
AttrLidSwitchReliability
@endverbatim
Note that this is an example only, the output may change over time. The tool
uses the same parser as libinput and any parsing errors will show up in the
output.
@section device-quirks-list List of supported device quirks
This list is a guide for developers to ease the process of submitting
patches upstream. This section shows device quirks supported in git
commit @includedoc git-version.dox
@note <b>Quirks are internal API and may change at any time for any reason.
No guarantee is given that any quirk below works on your version of
libinput.</b>
In the documentation below, the letters N, M, O, P refer to arbitrary integer
values.
Quirks starting with <b>Model*</b> triggers implementation-defined behaviour
for this device not needed for any other device. Only the more
general-purpose <b>Model*</b> flags are listed here.
<dl>
<dt>ModelALPSTouchpad, ModelAppleTouchpad, ModelWacomTouchpad, ModelChromebook</dt>
<dd>Reserved for touchpads made by the respective vendors</dd>
<dt>ModelTabletNoTilt</dt>
<dd>Indicates that the tablet stylus does not provide tilt axis
information, even if the kernel exposes that axis.</dd>
<dt>ModelTabletNoProximityOut</dt>
<dd>Indicates that the tablet stylus does not send correct proximity out
events.</dd>
<dt>ModelTouchpadVisibleMarker</dt>
<dd>Indicates the touchpad has a drawn-on visible marker between the software
buttons.</dd>
<dt>ModelTabletModeNoSuspend</dt>
<dd>Indicates that the device does not need to be
suspended in @ref switches_tablet_mode.</dd>
<dt>ModelTrackball</dt>
<dd>Reserved for trackballs</dd>
<dt>ModelBouncingKeys</dt>
<dd>Indicates that the device may send fake bouncing key events and
timestamps can not be relied upon.</dd>
<dt>ModelSynapticsSerialTouchpad</dt>
<dd>Reserved for touchpads made by Synaptics on the serial bus</dd>
</dd>
<dt>AttrSizeHint=NxM, AttrResolutionHint=N</dt>
<dd>Hints at the width x height of the device in mm, or the resolution
of the x/y axis in units/mm. These may only be used where they apply to
a large proportion of matching devices. They should not be used for any
specific device, override `EVDEV_ABS_*` instead, see @ref
absolute_coordinate_ranges_fix.
</dd>
<dt>AttrTouchSizeRange=N:M, AttrPalmSizeThreshold=O</dt>
<dd>Specifies the touch size required to
trigger a press (N) and to trigger a release (M). O > N > M. See
@ref touchpad_touch_size_hwdb for more details.
</dd>
<dt>AttrTouchPressureRange=N:M, AttrPalmPressureThreshold=O, AttrThumbPressureThreshold=P</dt>
<dd>Specifies the touch pressure required to
trigger a press (N) and to trigger a release (M), when a palm touch is
triggered (O) and when a thumb touch is triggered (P). O > P > N > M. See
@ref touchpad_pressure_hwdb for more details.
</dd>
<dt>AttrLidSwitchReliability=reliable|write_open</dt>
<dd>Indicates the reliability of the lid switch. This is a string enum. Do not
use "reliable" for any specific device. Very few devices need this, if in
doubt do not set. See @ref switches_lid for details.
</dd>
<dt>AttrKeyboardIntegration=internal|external</dt>
<dd>Indicates the integration of the keyboard. This is a string enum.
Generally only needed for USB keyboards.
</dd>
<dt>AttrTPKComboLayout=below</dt>
<dd>Indicates the position of the touchpad on an external touchpad+keyboard
combination device. This is a string enum. Don't specify it unless the
touchpad is below.
</dd>
</dl>
*/

83
doc/doxygen-to-sphinx.sh Executable file
View file

@ -0,0 +1,83 @@
#!/bin/bash -e
#
# Helper script to convert doxygenisms to sphinx-isms
outdir=$1
fname=$2
! test -z "$outdir" || exit 1
! test -z "$fname" || exit 1
file="$fname"
outfile="$(basename --suffix='.dox' $fname).rst"
# awk commands:
# indent anything between the verbatim tags
# indent anything between the code tags
# add a empty line before the first list item (line starting with -)
cat "$file" | \
awk \
'$0 ~ /.*@verbatim$/ { inside=1; print $0 "\n"; next; }
$0 ~ /@endverbatim/ { inside=0; }
inside == 1 { print " " $0 }
inside == 0 { print }' | \
awk \
'$0 ~ /@code$/ { inside=1; print $0 "\n"; next; }
$0 ~ /@endcode/ { inside=0; }
inside == 1 { print " " $0 }
inside == 0 { print }' | \
awk \
'$0 ~ /@dot$/ { inside=1; print $0 "\n"; next; }
$0 ~ /@enddot/ { inside=0; }
inside == 1 { print " " $0 }
inside == 0 { print }' | \
awk \
'$0 ~ /<dd>/ { inside=1; print $0 "\n"; next; }
$0 ~ /<\/dd>/ { inside=0; }
inside == 1 { print " " $0 }
inside == 0 { print }' | \
awk \
'/^-/{
if (!in_list && a != "") print ""; in_list=1
}
/^$/ {in_list=0}
{a=$0; print}' | \
sed \
-e 's|@page \([^ ]*\) \(.*\)|.. _\1:\n\n==============================================================================\n\2\n==============================================================================|' \
-e 's|@section \([^ ]*\) \(.*\)|.. _\1:\n\n------------------------------------------------------------------------------\n\2\n------------------------------------------------------------------------------|' \
-e 's|@subsection \([^ ]*\) \(.*\)|.. _\1:\n\n..............................................................................\n\2\n..............................................................................|' \
-e ':a;/@[[:alpha:]]\+$/{N;s/\(@[[:alpha:]]\+\)\n/\n\1 /;ba}' \
-e 's|@see \(LIBINPUT_[_[:alpha:]]\+\)|**\1**|' \
-e 's|@ref \(LIBINPUT_[_[:alpha:]]\+\)|**\1**|' \
-e 's|@ref \(libinput_[_[:alpha:]]\+\)|**\1**|' \
-e 's|\(libinput_[_[:alpha:]]\+()\)|**\1**|' \
-e 's|[ ]*<dt>||' \
-e 's|</dt>||' \
-e 's|[ ]*<dd>| |' \
-e 's|</dd>||' \
-e '/<\/\?dl>/d' \
-e 's|<b>|**|' \
-e 's|</b>|**|' \
-e 's|\*40|\\*40|' \
-e 's|\*50|\\*50|' \
-e 's|@note|.. note::|' \
-e 's|@warning|.. warning::|' \
-e 's|@dotfile \(.*\)|.. graphviz:: \1|' \
-e 's|@dot[ ]*|.. graphviz::\n\n|' \
-e 's|@enddot||' \
-e 's|@code[ ]*|::\n\n|' \
-e 's|`[^`]\+|`\0|g' \
-e 's|[^`]\+`$|\0`|g' \
-e 's|@ref \([-[:alnum:]_]*\) "\(.*\)"|:ref:`\2 <\1>`|' \
-e 's|@ref \([-[:alnum:]_]*\)|:ref:`\1`|' \
-e 's|@endcode||' \
-e 's|@tableofcontents[ ]*|.. contents::\n :local:\n :backlinks: entry\n|' \
-e 's|@verbatim[ ]*|::\n|' \
-e 's|@endverbatim[ ]*||' \
-e 's|@image html \([^ ]*\) "\?\(.*\)"\?|.. figure:: \1\n :align: center\n\n \2|' \
-e 's|<a href="\(.*\)">\(.*\)</a>|`\2 <\1>`_|' \
-e 's|\[\(.*\)\](\(.*\))|`\1 <\2>`_|' \
-e 's|^ \+$||' \
-e '/^\*\//d' \
-e '/^\/\*\*$/d' \
> "$outdir/$outfile"

59
doc/page-hierarchy.dox
View file

@ -1,59 +0,0 @@
/**
@page misc Users
- @subpage what_is_libinput
- @subpage faq
- @subpage tools
- @subpage reporting_bugs
@page touchpads Touchpads
- @subpage scrolling
- @subpage clickpad_softbuttons
- @subpage tapping
- @subpage gestures
- @subpage touchpad_pressure
- @subpage palm_detection
- @subpage t440_support
- @subpage touchpad_jumping_cursor
- @subpage absolute_coordinate_ranges
- @subpage touchpad_jitter
@page touchscreens Touchscreens
- @subpage absolute_axes
@page pointers Mice, Trackballs, etc.
- @subpage motion_normalization
- @subpage middle_button_emulation
- @subpage button_debouncing
- @subpage trackpoints
@page tablets Graphics Tablets
- @subpage tablet-support
@page other_devices Other devices
- @subpage switches
@page developers Developers
Contributions to libinput are always welcome. See the links below for
specific documentation.
- @subpage what_is_libinput
- @subpage contributing
- @subpage architecture
- @subpage building_libinput
- @subpage test-suite
- @subpage tools
- @subpage pointer-acceleration
- @subpage device-quirks
- @subpage udev_config
- @subpage seats
- @subpage timestamps
*/

299
doc/reporting-bugs.dox
View file

@ -1,299 +0,0 @@
/**
@page reporting_bugs Reporting bugs
A new bug can be filed here:
https://gitlab.freedesktop.org/libinput/libinput/issues/new
@note libinput has lots of users but very few developers. It is in your own
interested to follow these steps precisely to ensure your bug can be
dealt with efficiently.
When reporting bugs against libinput, please follow the instructions below
and provide the required data. You will need:
- a reliable @ref reporting_bugs_reproducer "reproducer" for the bug
- an @ref evemu "evemu recording" of the device while the bug is reproduced
- device-specific information, see
- @ref reporting_bugs_touchpad
- @ref reporting_bugs_mouse
- @ref reporting_bugs_keyboard
- @ref reporting_bugs_trackpoint
- @ref reporting_bugs_other
- the @ref reporting_bugs_version "libinput version" you are on.
- the @ref reporting_bugs_options "configuration options" you have set
- a [gitlab account](https://gitlab.freedesktop.org/users/sign_in)
Stay technical, on-topic, and keep the description concise.
@section reporting_bugs_version Obtaining the libinput version
If your libinput version is older than the current stable branch, you will
get asked to try the latest version. If you run a distribution-provided
libinput, use the package manager to get the **full** package name and
version of libinput, e.g.
- `rpm -q libinput`
- `dpkg -s libinput10`
If you run a self-compiled version of libinput provide the git commit you
have built or the tarball name.
As a last resort, use `libinput --version`
@section reporting_bugs_reproducer Reproducing bugs
Try to identify the bug by reproducing it reliably. Bugs without a
reliable reproducer will have lowest priority. The more specific a bug
description and reproducer is, the easier it is to fix.
Try to replicate the series of events that lead to the bug being triggered.
Narrow it down until you have a reliable sequence that can trigger the bug.
For the vast majority of bugs you should not take longer than 5 seconds or
three interactions (clicks, touches, taps, ...) with the device to
reproduce. If it takes longer than that, you can narrow it down further.
Once you can reproduce it, use the @ref libinput-debug-events helper tool.
The output is textual and can help identify whether the bug is in libinput
at all. Note that any configuration options you have set must be specified
on the commandline, see the @ref libinput-debug-events
"libinput-debug-events" man page. Use the `--verbose` flag to get more
information about how libinput processes events.
If the bug cannot be reproduced with the @ref libinput-debug-events helper,
even with the correct configuration options set, it is likely not a bug in
libinput.
@section reporting_bugs_options libinput configuration settings
libinput has a number of device-specific default configuration settings that
may differ from the ones your desktop environment picks by default. You may
have changed some options in a settings panel or in an the xorg.conf snippet
yourself.
You must provide these options in the bug report, otherwise a developer
reproducing the issue may not be able to do so.
If you are on X11, the current settings can be can be obtained with
`xinput list-props "your device name"`. Use `xinput list` to
obtain the device name.
If you are on Wayland, provide a manual summary of the options you have
changed from the default (e.g. "I enabled tap-to-click").
@section reporting_bugs_touchpad Reporting touchpad bugs
When you file a bug, please attach the following information:
- a virtual description of your input device, see @ref evemu. This is the
most important piece of information, do not forget it!
- the output from udevadm info, see @ref udev_info.
- the vendor model number of your laptop (e.g. "Lenovo Thinkpad T440s")
- and the content of `/sys/class/dmi/id/modalias`.
- run the `touchpad-edge-detectior` tool (provided by libevdev) and verify
that the ranges and sizes it prints match the touchpad (up to 5mm
difference is ok)
If you are reporting a bug related to button event generation:
- does your touchpad have (separate) physical hardware buttons or is the
whole touchpad clickable?
- Are you using software buttons or clickfinger? See @ref
clickpad_softbuttons.
- Do you have @ref tapping enabled?
@section reporting_bugs_mouse Reporting mouse bugs
When you file a bug, please attach the following information:
- a virtual description of your input device, see @ref evemu. This is the
most important piece of information, do not forget it!
- the vendor model number of the device (e.g. "Logitech M325")
- the output from udevadm info, see @ref udev_info.
If the bug is related to the @ref motion_normalization_customization "speed of the mouse":
- the resolution of the mouse as specified by the vendor (in DPI)
- the output of the `mouse-dpi-tool` (provided by libevdev)
@section reporting_bugs_keyboard Reporting keyboard bugs
Is your bug related to a keyboard layout? libinput does not handle keyboard
layouts and merely forwards the physical key events. File the bug with your
desktop environment instead (e.g. GNOME, KDE, ...), that's most likely where
the issue is.
When you file a bug, please attach the following information:
- a virtual description of your input device, see @ref evemu. This is the
most important piece of information, do not forget it!
@section reporting_bugs_trackpoint Reporting trackpoint bugs
When you file a bug, please attach the following information:
- a virtual description of your input device, see @ref evemu. This is the
most important piece of information, do not forget it!
- the vendor model number of the device (e.g. "Logitech M325")
- the output from udevadm info, see @ref udev_info.
- the output of `libinput measure trackpoint-range`
- the sensitivity of the trackpoint (adjust the event node number as needed):
@verbatim
$ cat /sys/class/input/event17/device/device/sensitivity
@endverbatim
@section reporting_bugs_other All other devices
When you file a bug, please attach the following information:
- a virtual description of your input device, see @ref evemu. This is the
most important piece of information, do not forget it!
- the vendor model number of the device (e.g. "Sony Plastation3 controller")
@section udev_info udev information for the device
In many cases, we require the udev properties assigned to the device to
verify whether device-specific quirks were applied. This can be obtained
with `udevadm info /sys/class/input/eventX`, with the correct event
node for your device. An example output is below:
@verbatim
$ udevadm info /sys/class/input/event4
P: /devices/platform/i8042/serio1/input/input5/event4
N: input/event4
E: DEVNAME=/dev/input/event4
E: DEVPATH=/devices/platform/i8042/serio1/input/input5/event4
E: EVDEV_ABS_00=::41
E: EVDEV_ABS_01=::37
E: EVDEV_ABS_35=::41
E: EVDEV_ABS_36=::37
E: ID_INPUT=1
E: ID_INPUT_HEIGHT_MM=66
E: ID_INPUT_TOUCHPAD=1
E: ID_INPUT_WIDTH_MM=97
E: MAJOR=13
E: MINOR=68
E: SUBSYSTEM=input
E: USEC_INITIALIZED=5463031
@endverbatim
@section evemu Recording devices with evemu
@note Where available, the @ref libinput-record tools should be used instead
of evemu
[evemu-record](https://www.freedesktop.org/wiki/Evemu/) records the
device capabilities together with the event stream from the kernel. On our
side, this allows us to recreate a virtual device identical to your device
and re-play the event sequence, hopefully triggering the same bug.
evemu-record takes a <tt>/dev/input/eventX</tt> event node, but without arguments
it will simply show the list of devices and let you select:
@verbatim
$ sudo evemu-record > scroll.evemu
Available devices:
/dev/input/event0: Lid Switch
/dev/input/event1: Sleep Button
/dev/input/event2: Power Button
/dev/input/event3: AT Translated Set 2 keyboard
/dev/input/event4: SynPS/2 Synaptics TouchPad
/dev/input/event5: Video Bus
/dev/input/event6: ELAN Touchscreen
/dev/input/event10: ThinkPad Extra Buttons
/dev/input/event11: HDA Intel HDMI HDMI/DP,pcm=3
/dev/input/event12: HDA Intel HDMI HDMI/DP,pcm=7
/dev/input/event13: HDA Intel HDMI HDMI/DP,pcm=8
/dev/input/event14: HDA Intel PCH Dock Mic
/dev/input/event15: HDA Intel PCH Mic
/dev/input/event16: HDA Intel PCH Dock Headphone
/dev/input/event17: HDA Intel PCH Headphone
/dev/input/event18: Integrated Camera
/dev/input/event19: TPPS/2 IBM TrackPoint
Select the device event number [0-19]:
@endverbatim
Select the device that triggers the issue, then reproduce the bug and Ctrl+C
the process. The resulting recording, ("scroll.evemu" in this example) will
contain the sequence required to reproduce the bug. If the bug fails to
reproduce during recording, simply Ctrl+C and restart evemu-record.
Always start the recording from a neutral state, i.e. without any buttons or
keys down, with the position of the device in the neutral position, without
touching the screen/touchpad.
@note The longer the recording, the harder it is to identify the event
sequence triggering the bug. Please keep the event sequence as short
as possible.
To verify that the recording contains the bug, you can replay it on your
device. For example, to replay the sequence recorded in the example above:
@verbatim
$ sudo evemu-play /dev/input/event4 < scroll.evemu
@endverbatim
If the bug is triggered by replaying on your device, attach the recording to
the bug report.
@note libinput does not affect the evemu recording. libinput and evemu talk
directly to the kernel's device nodes. An evemu recording is not
influenced by the libinput version or whether a libinput context is
currently active.
@dotfile evemu.gv
@section fixed_bugs My bug was closed as fixed, what now?
libinput's policy on closing bugs is: once the fix for a given bug is on git
master, the bug is considered fixed and the bugzilla entry will be closed
accordingly.
Of course, unless you actually run git master, the bug will continue to
affect you on your local machine. You are most likely running the
distribution's package and you will need to wait until the distribution has
updated its package accordingly.
<b>Do not re-open a bug just because it hasn't trickled down to your
distribution's package version yet.</b>
Whether the bug fix ends up in your distribution depends on a number of
things. Any given bug fix **may** be cherry-picked into the current stable
branch, depending on its severity, impact, and likelyhood to cause
regressions. Once cherry-picked it will land in the next stable branch
release. These are usually a few weeks apart.
<b>Do not re-open a bug because it wasn't picked into a stable branch
release or because your distribution didn't update to the latest stable
branch release.</b>
Stable branches are usually discontinued when the next release comes out.
Your distribution may pick a patch up immediately and ship the fix
even before the next stable branch update is released. For example, Fedora
does this frequently.
<b>If a bug needs to be fixed urgently, file a bug in your distribution's
bug tracker.</b>
Patches on git master will end up in the next libinput release. Once your
distribution updates to that release, your local libinput version will
contain the fix.
<b>Do not re-open a bug because your distribution didn't update to the
release.</b>
You can always run libinput from git master (see @ref building_libinput).
Even while in development, libinput is very stable so this option isn't as
scary as it may sounds.
@subsection reporting_bugs_reopen When is it ok to re-open a fixed bug?
Any time the bug was considered fixed but it turns out that the fix is
insufficient and/or causes a regression.
However, if the regression is in behavior unrelated to the fix itself it is
usually better to file a new bug to reduce the noise. For example, if a fix
to improve tapping breaks two-finger scrolling behavior, you should file a
new bug but reference the original bug.
*/

134
doc/test-suite.dox
View file

@ -1,134 +0,0 @@
/**
@page test-suite libinput test suite
libinput ships with a number of tests all run automatically on `ninja test`.
The primary test suite is the `libinput-test-suite-runner`. When testing,
the `libinput-test-suite-runner` should always be invoked to check for
behavior changes.
The test suite runner uses
[Check](http://check.sourceforge.net/doc/check_html/) underneath the hood
but most of the functionality is abstracted into *litest* wrappers.
The test suite runner has a make-like job control enabled by the `-j` or
`--jobs` flag and will fork off as many parallel processes as given by this
flag. The default if unspecified is 8. When debugging a specific test case
failure it is recommended to employ test filtures (see @ref test-filtering)
and disable parallel tests. The test suite automatically disables parallel
make when run in gdb.
@section test-config X.Org config to avoid interference
uinput devices created by the test suite are usually recognised by X as
input devices. All events sent through these devices will generate X events
and interfere with your desktop.
Copy the file `$srcdir/test/50-litest.conf` into your `/etc/X11/xorg.conf.d`
and restart X. This will ignore any litest devices and thus not interfere
with your desktop.
@section test-root Permissions required to run tests
Most tests require the creation of uinput devices and access to the
resulting `/dev/input/eventX` nodes. Some tests require temporary udev rules.
<b>This usually requires the tests to be run as root</b>. If not run as
root, the test suite runner will exit with status 77, interpreted as
"skipped" by ninja.
@section test-filtering Selective running of tests
litest's tests are grouped into test groups, test names and devices. A test
group is e.g. "touchpad:tap" and incorporates all tapping-related tests for
touchpads. Each test function is (usually) run with one or more specific
devices. The `--list` commandline argument shows the list of suites and
tests. This is useful when trying to figure out if a specific test is
run for a device.
@verbatim
$ ./test/libinput-test-suite-runner --list
...
pointer:left-handed:
pointer_left_handed_during_click_multiple_buttons:
trackpoint
ms-surface-cover
mouse-wheelclickcount
mouse-wheelclickangle
low-dpi-mouse
mouse-roccat
mouse-wheel-tilt
mouse
logitech-trackball
cyborg-rat
magicmouse
pointer_left_handed_during_click:
trackpoint
ms-surface-cover
mouse-wheelclickcount
mouse-wheelclickangle
low-dpi-mouse
mouse-roccat
mouse-wheel-tilt
mouse
logitech-trackball
cyborg-rat
litest-magicmouse-device
pointer_left_handed:
trackpoint
ms-surface-cover
mouse-wheelclickcount
mouse-wheelclickangle
low-dpi-mouse
mouse-roccat
mouse-wheel-tilt
mouse
...
@endverbatim
In the above example, the "pointer:left-handed" suite contains multiple
tests, e.g. "pointer_left_handed_during_click" (this is also the function
name of the test, making it easy to grep for). This particular test is run
for various devices including the trackpoint device and the magic mouse
device.
The "no device" entry signals that litest does not instantiate a uinput
device for a specific test (though the test itself may
instantiate one).
The `--filter-test` argument enables selective running of tests through
basic shell-style function name matching. For example:
@verbatim
$ ./test/libinput-test-suite-runner --filter-test="*1fg_tap*"
@endverbatim
The `--filter-device` argument enables selective running of tests through
basic shell-style device name matching. The device names matched are the
litest-specific shortnames, see the output of `--list`. For example:
@verbatim
$ ./test/libinput-test-suite-runner --filter-device="synaptics*"
@endverbatim
The `--filter-group` argument enables selective running of test groups
through basic shell-style test group matching. The test groups matched are
litest-specific test groups, see the output of `--list`. For example:
@verbatim
$ ./test/libinput-test-suite-runner --filter-group="touchpad:*hover*"
@endverbatim
The `--filter-device` and `--filter-group` arguments can be combined with
`--list` to show which groups and devices will be affected.
@section test-verbosity Controlling test output
Each test supports the `--verbose` commandline option to enable debugging
output, see libinput_log_set_priority() for details. The `LITEST_VERBOSE`
environment variable, if set, also enables verbose mode.
@verbatim
$ ./test/libinput-test-suite-runner --verbose
$ LITEST_VERBOSE=1 ninja test
@endverbatim
*/

36
doc/timestamps.dox
View file

@ -1,36 +0,0 @@
/**
@page timestamps Timestamps
@section event_timestamps Event timestamps
Most libinput events provide a timestamp in millisecond and/or microsecond
resolution. These timestamp usually increase monotonically, but libinput
does not guarantee that this always the case. In other words, it is possible
to receive an event with a timestamp earlier than the previous event.
For example, if a touchpad has @ref tapping enabled, a button event may have a
lower timestamp than an event from a different device. Tapping requires the
use of timeouts to detect multi-finger taps and/or @ref tapndrag.
Consider the following event sequences from a touchpad and a mouse:
@verbatim
Time Touchpad Mouse
---------------------------------
t1 finger down
t2 finger up
t3 movement
t4 tap timeout
@endverbatim
For this event sequence, the first event to be sent to a caller is in
response to the mouse movement: an event of type @ref
LIBINPUT_EVENT_POINTER_MOTION with the timestamp t3.
Once the timeout expires at t4, libinput generates an event of
@ref LIBINPUT_EVENT_POINTER_BUTTON (press) with a timestamp t1 and an event
@ref LIBINPUT_EVENT_POINTER_BUTTON (release) with a timestamp t2.
Thus, the caller gets events with timestamps in the order t3, t1, t2,
despite t3 > t2 > t1.
*/

267
doc/tools.dox
View file

@ -1,267 +0,0 @@
/**
@page tools Helper tools
libinput provides a `libinput` tool to query state and events. This tool
takes a subcommand as argument, similar to the **git** command. A full
explanation of the various commands available in the libinput tool is
available in the **libinput(1)** man page.
The most common tools used are:
- `libinput list-devices`: to list locally available devices, see @ref
libinput-list-devices "here"
- `libinput debug-events`: to monitor and debug events, see @ref
libinput-debug-events "here"
- `libinput debug-gui`: to visualize events, see @ref libinput-debug-gui
"here"
- `libinput record`: to record an event sequence for replaying, see @ref
libinput-record "here"
- `libinput measure`: measure properties on a kernel device, see @ref
libinput-measure "here"
Most the tools must be run as root to have access to the kernel's @c
/dev/input/event* device files.
@section libinput-list-devices libinput list-devices
The `libinput list-devices` command shows information about devices
recognized by libinput and can help identifying why a device behaves
different than expected. For example, if a device does not show up in the
output, it is not a supported input device.
@note This tool does **not** show your desktop's configuration, just the
libinput built-in defaults.
@verbatim
$ sudo libinput list-devices
[...]
Device: SynPS/2 Synaptics TouchPad
Kernel: /dev/input/event4
Group: 9
Seat: seat0, default
Size: 97.33x66.86mm
Capabilities: pointer
Tap-to-click: disabled
Tap drag lock: disabled
Left-handed: disabled
Nat.scrolling: disabled
Middle emulation: n/a
Calibration: n/a
Scroll methods: *two-finger
Click methods: *button-areas clickfinger
[...]
@endverbatim
The above listing shows example output for a touchpad. The
`libinput list-devices` command lists general information about the device
(the kernel event node) but also the configuration options. If an option is
"n/a" it does not exist on this device. Otherwise, the tool will show the
default configuration for this device, for options that have more than a
binary state all available options are listed, with the default one prefixed
with an asterisk (*). In the example above, the default click method is
button-areas but clickinger is available.
@note This tool is intended to be human-readable and may change its output
at any time.
@section libinput-debug-events libinput debug-events
The `libinput debug-events` command prints events from devices and can help
to identify why a device behaves different than expected.
@verbatim
$ sudo libinput debug-events --enable-tapping --set-click-method=clickfinger
@endverbatim
All configuration options (enable/disable tapping,
etc.) are available as commandline arguments. To reproduce the event
sequence as your desktop session sees it, ensure that all options are turned
on or off as required. See the **libinput-debug-events(1)** man page or the
`--help` output for information about the available options.
@note When submitting a bug report, always use the `--verbose` flag to get
additional information: `libinput debug-events --verbose <other options>`
An example output from this tool may look like the snippet below.
@verbatim
$ sudo libinput debug-events --enable-tapping --set-click-method=clickfinger
-event2 DEVICE_ADDED Power Button seat0 default group1 cap:k
-event5 DEVICE_ADDED Video Bus seat0 default group2 cap:k
-event0 DEVICE_ADDED Lid Switch seat0 default group3 cap:S
-event1 DEVICE_ADDED Sleep Button seat0 default group4 cap:k
-event4 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=3 seat0 default group5 cap:
-event11 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=7 seat0 default group6 cap:
-event12 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=8 seat0 default group7 cap:
-event13 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=9 seat0 default group8 cap:
-event14 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=10 seat0 default group9 cap:
-event19 DEVICE_ADDED Integrated Camera: Integrated C seat0 default group10 cap:k
-event15 DEVICE_ADDED HDA Intel PCH Dock Mic seat0 default group11 cap:
-event16 DEVICE_ADDED HDA Intel PCH Mic seat0 default group12 cap:
-event17 DEVICE_ADDED HDA Intel PCH Dock Headphone seat0 default group13 cap:
-event18 DEVICE_ADDED HDA Intel PCH Headphone seat0 default group14 cap:
-event6 DEVICE_ADDED ELAN Touchscreen seat0 default group15 cap:t size 305x172mm ntouches 10 calib
-event3 DEVICE_ADDED AT Translated Set 2 keyboard seat0 default group16 cap:k
-event20 DEVICE_ADDED SynPS/2 Synaptics TouchPad seat0 default group17 cap:pg size 100x76mm tap(dl off) left scroll-nat scroll-2fg-edge click-buttonareas-clickfinger dwt-on
-event21 DEVICE_ADDED TPPS/2 IBM TrackPoint seat0 default group18 cap:p left scroll-nat scroll-button
-event7 DEVICE_ADDED ThinkPad Extra Buttons seat0 default group19 cap:k
-event20 POINTER_MOTION +3.62s 2.72/ -0.93
event20 POINTER_MOTION +3.63s 1.80/ -1.42
event20 POINTER_MOTION +3.65s 6.16/ -2.28
event20 POINTER_MOTION +3.66s 6.42/ -1.99
event20 POINTER_MOTION +3.67s 8.99/ -1.42
event20 POINTER_MOTION +3.68s 11.30/ 0.00
event20 POINTER_MOTION +3.69s 21.32/ 1.42
@endverbatim
@section libinput-debug-gui libinput debug-gui
A simple GTK-based graphical tool that shows the behavior and location of
touch events, pointer motion, scroll axes and gestures. Since this tool
gathers data directly from libinput, it is thus suitable for
pointer-acceleration testing.
@note This tool does **not** use your desktop's configuration, just the
libinput built-in defaults.
@verbatim
$ sudo libinput debug-gui --enable-tapping
@endverbatim
As with @ref libinput-debug-events, all options must be specified on the
commandline to emulate the correct behavior.
See the **libinput-debug-gui(1)** man page or the `--help` output for information about
the available options.
@section libinput-record libinput record and libinput replay
The `libinput record` command records the **kernel** events from a specific
device node. The recorded sequence can be replayed with the `libinput
replay` command. This pair of tools is crucial to capturing bugs and
reproducing them on a developer's machine.
@note These tools are shipped with libinput, but the recorded events
are **kernel events** and independent of the libinput context. libinput
does not need to be running, it does not matter whether a user is
running X.Org or Wayland or even what version of libinput is currently
running.
The use of the tools is straightforward, just run without arguments, piping
the output into a file:
@verbatim
$ sudo libinput record > touchpad.yml
Available devices:
/dev/input/event0: Lid Switch
/dev/input/event1: Sleep Button
/dev/input/event2: Power Button
/dev/input/event3: AT Translated Set 2 keyboard
/dev/input/event4: ThinkPad Extra Buttons
/dev/input/event5: ELAN Touchscreen
/dev/input/event6: Video Bus
/dev/input/event7: HDA Intel HDMI HDMI/DP,pcm=3
/dev/input/event8: HDA Intel HDMI HDMI/DP,pcm=7
/dev/input/event9: HDA Intel HDMI HDMI/DP,pcm=8
/dev/input/event10: HDA Intel HDMI HDMI/DP,pcm=9
/dev/input/event11: HDA Intel HDMI HDMI/DP,pcm=10
/dev/input/event12: HDA Intel PCH Dock Mic
/dev/input/event13: HDA Intel PCH Mic
/dev/input/event14: HDA Intel PCH Dock Headphone
/dev/input/event15: HDA Intel PCH Headphone
/dev/input/event16: Integrated Camera: Integrated C
/dev/input/event17: SynPS/2 Synaptics TouchPad
/dev/input/event18: TPPS/2 IBM TrackPoint
Select the device event number: 17
/dev/input/event17 recording to stdout
@endverbatim
Without arguments, `libinput record` displays the available devices and lets
the user select one. Supply the number (17 in this case for
`/dev/input/event17`) and the tool will print the device information and
events to the file it is redirected to. More arguments are available, see
the **libinput-record(1)** man page.
Reproduce the bug, ctrl+c and attach the output file to a bug report.
For data protection, `libinput record` obscures key codes by default, any
alphanumeric key shows up as letter "a".
@note When reproducing a bug that crashes libinput, run inside `screen` or
`tmux`.
The recording can be replayed with the `libinput replay` command:
@verbatim
$ sudo libinput replay touchpad.yml
SynPS/2 Synaptics TouchPad: /dev/input/event19
Hit enter to start replaying
@endverbatim
`libinput replay` creates a new virtual device based on the description in
the log file. Hitting enter replays the event sequence once and the tool
stops once all events have been replayed. Hitting enter again replays the
sequence again, Ctrl+C stops it and removes the virtual device.
Users are advised to always replay a recorded event sequence to ensure they
have captured the bug.
More arguments are available, see the **libinput-record(1)** and
**libinput-replay(1)** man pages.
@subsection libinput-record-autorestart libinput record's autorestart feature
`libinput record` often collects thousands of events per minute. However,
the output of `libinput record` usually needs to be visually inspected
or replayed in realtime on a developer machine. It is thus imperative that
the event log is kept as short as possible.
For bugs that are difficult to reproduce use
`libinput record --autorestart=2 --output-file=recording.yml`.
All events will be recorded to a file named
`recording.yml.<current-date-and-time>` and whenever the device does not
send events for 2 seconds, a new file is created. This helps to keep
individual recordings short.
To use the `--autorestart` option correctly:
- run `libinput record --autorestart=2 --output-file=<somefilename>.yml`.
You may provide a timeout other than 2 if needed.
- use the device to reproduce the bug, pausing frequently for 2s and longer
to rotate the logs
- when the bug triggers, **immediately stop using the device** and wait
several seconds for the log to rotate
- Ctrl+C the `libinput record` process without using the device
again. Attach the **last recording** to the bug report.
If you have to use the recorded device to stop `libinput record` (e.g. to
switch windows), remember that this will cause a new recording to be
created. Thus, attach the **second-to-last recording** to the bug report
because this one contains the bug trigger.
@subsection libinput-record-multiple Recording multiple devices at once
In some cases, an interaction between multiple devices is the cause for a
specific bug. For example, a touchpad may not work in response to keyboard
events. To accurately reproduce this sequence, the timing between multiple
devices must be correct and we need to record the events in one go.
`libinput record` has a `--multiple` argument to record multiple devices at
once. Unlike the normal invocation, this one requires a number of arguments:
@verbatim
$ sudo libinput record --multiple --output-file=touchpad-bug.yml /dev/input/event17 /dev/input/event3
recording to 'touchpad-bug.yml'
@endverbatim
As seen above, a user must specify `--multiple` and the `--output-file`.
Finally, all devices to be recorded must be specified on the commandline as
well.
Replaying events is the same as for a single recording:
@verbatim
$ sudo libinput replay touchpad-bug.yml
@endverbatim
@section libinput-measure Measuring device properties with libinput measure
The `libinput measure` tool is a multiplexer for various sub-tools that can
measure specific properties on the device. These tools generally measure one
thing and one thing only and their usage is highly specific to the tool.
Please see the **libinput-measure(1)** man page for information about what
tools are available and the man page for each respective tool.
*/

90
doc/touchpad-jitter.dox
View file

@ -1,90 +0,0 @@
/**
@page touchpad_jitter Touchpad jitter
Touchpad jitter describes random movement by a few pixels even when the
user's finger is unmoving.
libinput has a mechanism called a **hysteresis** to avoid that jitter. When
active, movement with in the **hysteresis margin** is discarded. If the
movement delta is larger than the margin, the movement is passed on as
pointer movement. This is a simplified summary, developers should
read the implementation of the hysteresis in `src/evdev.c`.
libinput uses the kernel `fuzz` value to determine the size of the
hysteresis. Users should override this with a udev hwdb entry where the
device itself does not provide the correct value.
@section touchpad_jitter_fuzz_override Overriding the hysteresis margins
libinput provides the debugging tool `libinput measure fuzz` to help edit or
test a fuzz value. This tool is interactive and provides a udev hwdb entry
that matches the device. To check if a fuzz is currently present, simply run
without arguments or with the touchpad's device node:
@verbatim
$ sudo libinput measure fuzz
Using Synaptics TM2668-002: /dev/input/event17
Checking udev property... not set
Checking axes... x=16 y=16
@endverbatim
In the above output, the axis fuzz is set to 16. To set a specific fuzz, run
with the `--fuzz=<value>` argument.
@verbatim
$ sudo libinput measure fuzz --fuzz=8
@endverbatim
The tool will attempt to construct a hwdb file that matches your touchpad
device. Follow the printed prompts.
In the ideal case, the tool will provide you with a file that can be
submitted to the systemd repo for inclusion.
However, hwdb entry creation is difficult to automate and it's likely
that the tools fails in doing so, especially if an existing entry is already
present.
Below is the outline of what a user needs to do to override a device's fuzz
value in case the `libinput measure fuzz` tool fails.
Check with `udevadm info /sys/class/input/eventX` (replace your device node
number) whether an existing hwdb override exists. If the `EVDEV_ABS_`
properties are present, the hwdb overried exists. Find the file that
contains that entry, most likely in `/etc/udev/hwdb.d` or
`/usr/lib/udev/hwdb.d`.
The content of the property is a set of values in the format
`EVDEV_ABS_00=min:max:resolution:fuzz`. You need to set the `fuzz` part,
leaving the remainder of the property as-is. Values may be empty, e.g. a
property that only sets resolution and fuzz reads as `EVDEV_ABS_00=::32:8`.
If no properties exist, your hwdb.entry should look approximately like this:
@verbatim
evdev:name:Synaptics TM2668-002:dmi:*:svnLENOVO*:pvrThinkPadT440s*:
EVDEV_ABS_00=:::8
EVDEV_ABS_01=:::8
EVDEV_ABS_35=:::8
EVDEV_ABS_36=:::8
@endverbatim
Substitute the `name` field with the device name (see the output of
`libinput measure fuzz` and the DMI match content with your hardware. See
@ref hwdb_modifying for details.
Once the hwdb entry has been modified, added, or created, @ref
hwdb_reloading "reload the hwdb". Once reloaded, @ref libinput-record
"libinput record" should show the new fuzz value for the axes.
Restart the host and libinput should pick up the revised fuzz values.
@section kernel_fuzz Kernel fuzz
A fuzz set on an absolute axis in the kernel causes the kernel to apply
hysteresis-like behavior to the axis. Unfortunately, this behavior leads to
inconsistent deltas. To avoid this, libinput sets the kernel fuzz on the
device to 0 to disable this kernel behavior but remembers what the fuzz was
on startup. The fuzz is stored in the `LIBINPUT_FUZZ_XX` udev property, on
startup libinput will check that property as well as the axis itself.
*/

54
doc/touchpad-jumping-cursors.dox
View file

@ -1,54 +0,0 @@
/**
@page touchpad_jumping_cursor Touchpad jumping cursor bugs
A common bug encountered on touchpads is a cursor jump when alternating
between fingers on a multi-touch-capable touchpad. For example, after moving
the cursor a user may use a second finger in the software button area to
physically click the touchpad. Upon setting the finger down, the cursor
exhibits a jump towards the bottom left or right, depending on the finger
position.
When libinput detects a cursor jump it prints a bug warning to the log with
the text <b>"Touch jump detected and discarded."</b> and a link to this page.
In most cases, this is a bug in the kernel driver and to libinput it appears
that the touch point moves from its previous position. The pointer jump can
usually be seen in the evemu-record output for the device:
@verbatim
E: 249.206319 0000 0000 0000 # ------------ SYN_REPORT (0) ----------
E: 249.218008 0003 0035 3764 # EV_ABS / ABS_MT_POSITION_X 3764
E: 249.218008 0003 0036 2221 # EV_ABS / ABS_MT_POSITION_Y 2221
E: 249.218008 0003 003a 0065 # EV_ABS / ABS_MT_PRESSURE 65
E: 249.218008 0003 0000 3764 # EV_ABS / ABS_X 3764
E: 249.218008 0003 0001 2216 # EV_ABS / ABS_Y 2216
E: 249.218008 0003 0018 0065 # EV_ABS / ABS_PRESSURE 65
E: 249.218008 0000 0000 0000 # ------------ SYN_REPORT (0) ----------
E: 249.230881 0003 0035 3752 # EV_ABS / ABS_MT_POSITION_X 3752
E: 249.230881 0003 003a 0046 # EV_ABS / ABS_MT_PRESSURE 46
E: 249.230881 0003 0000 3758 # EV_ABS / ABS_X 3758
E: 249.230881 0003 0018 0046 # EV_ABS / ABS_PRESSURE 46
E: 249.230881 0000 0000 0000 # ------------ SYN_REPORT (0) ----------
E: 249.242648 0003 0035 1640 # EV_ABS / ABS_MT_POSITION_X 1640
E: 249.242648 0003 0036 4681 # EV_ABS / ABS_MT_POSITION_Y 4681
E: 249.242648 0003 003a 0025 # EV_ABS / ABS_MT_PRESSURE 25
E: 249.242648 0003 0000 1640 # EV_ABS / ABS_X 1640
E: 249.242648 0003 0001 4681 # EV_ABS / ABS_Y 4681
E: 249.242648 0003 0018 0025 # EV_ABS / ABS_PRESSURE 25
E: 249.242648 0000 0000 0000 # ------------ SYN_REPORT (0) ----------
E: 249.254568 0003 0035 1648 # EV_ABS / ABS_MT_POSITION_X 1648
E: 249.254568 0003 003a 0027 # EV_ABS / ABS_MT_PRESSURE 27
E: 249.254568 0003 0000 1644 # EV_ABS / ABS_X 1644
E: 249.254568 0003 0018 0027 # EV_ABS / ABS_PRESSURE 27
@endverbatim
In this recording, the pointer jumps from its position 3752/2216 to
1640/4681 within a single frame. On this particular touchpad, this would
represent a physical move of almost 50mm. libinput detects some of these
jumps and discards the movement but otherwise continues as usual. However,
the bug should be fixed at the kernel level.
When you encounter the warning in the log, please generate an evemu
recording of your touchpad and file a bug. See @ref reporting_bugs for more
details.
*/

232
doc/touchpad-pressure.dox
View file

@ -1,232 +0,0 @@
/**
@page touchpad_pressure Touchpad pressure-based touch detection
libinput uses the touchpad pressure values and/or touch size values to
detect wether a finger has been placed on the touchpad. This is @ref
kernel_pressure_information and combines with a libinput-specific hardware
database to adjust the thresholds on a per-device basis. libinput uses
these thresholds primarily to filter out accidental light touches but
the information is also used for some @ref palm_detection.
Pressure and touch size thresholds are **not** directly configurable by the
user. Instead, libinput provides these thresholds for each device where
necessary. See @ref touchpad_pressure_hwdb for instructions on how to adjust
the pressure ranges and @ref touchpad_touch_size_hwdb for instructions on
how to adjust the touch size ranges.
@section kernel_pressure_information Information provided by the kernel
The kernel sends multiple values to inform userspace about a finger touching
the touchpad. The most basic is the `EV_KEY/BTN_TOUCH` boolean event
that simply announces physical contact with the touchpad. The decision when
this event is sent is usually made by the kernel driver and may depend on
device-specific thresholds. These thresholds are transparent to userspace
and cannot be modified. On touchpads where pressure or touch size is not
available, libinput uses `BTN_TOUCH` to determine when a finger is
logically down.
Many contemporary touchpad devices provide an absolute pressure axis in
addition to `BTN_TOUCH`. This pressure generally increases as the pressure
increases, however few touchpads are capable of detecting true pressure. The
pressure value is usually related to the covered area - as the pressure
increases a finger flattens and thus covers a larger area. The range
provided by the kernel is not mapped to a specific physical range and
often requires adjustment. Pressure is sent by the `ABS_PRESSURE` axis
for single-touch touchpads or `ABS_MT_PRESSURE` on multi-touch capable
touchpads. Some devices can detect multiple fingers but only provide
`ABS_PRESSURE`.
Some devices provide additional touch size information through
the `ABS_MT_TOUCH_MAJOR/ABS_MT_TOUCH_MINOR` axes and/or
the `ABS_MT_WIDTH_MAJOR/ABS_MT_WIDTH_MINOR` axes. These axes specifcy
the size of the touch ellipse. While the kernel documentation specifies how
these axes are supposed to be mapped, few devices forward reliable
information. libinput uses these values together with a device-specific
@ref device-quirks entry. In other words, touch size detection does not work
unless a device quirk is present for the device.
@section touchpad_pressure_hwdb Debugging touchpad pressure ranges
This section describes how to determine the touchpad pressure ranges
required for a touchpad device and how to add the required @ref
device-quirks locally. Note that the quirk is **not public API** and **may
change at any time**. Users are advised to @ref reporting_bugs "report a bug"
with the updated pressure ranges when testing has completed.
Use the `libinput measure touchpad-pressure` tool provided by libinput.
This tool will search for your touchpad device and print some pressure
statistics, including whether a touch is/was considered logically down.
@note This tool will only work on touchpads with pressure.
Example output of the tool is below:
@verbatim
$ sudo libinput measure touchpad-pressure
Ready for recording data.
Pressure range used: 8:10
Palm pressure range used: 65535
Place a single finger on the touchpad to measure pressure values.
Ctrl+C to exit
&nbsp;
Sequence 1190 pressure: min: 39 max: 48 avg: 43 median: 44 tags: down
Sequence 1191 pressure: min: 49 max: 65 avg: 62 median: 64 tags: down
Sequence 1192 pressure: min: 40 max: 78 avg: 64 median: 66 tags: down
Sequence 1193 pressure: min: 36 max: 83 avg: 70 median: 73 tags: down
Sequence 1194 pressure: min: 43 max: 76 avg: 72 median: 74 tags: down
Touchpad pressure: 47 min: 47 max: 86 tags: down
@endverbatim
The example output shows five completed touch sequences and one ongoing one.
For each, the respective minimum and maximum pressure values are printed as
well as some statistics. The `tags` show that sequence was considered
logically down at some point. This is an interactive tool and its output may
change frequently. Refer to the <i>libinput-measure-touchpad-pressure(1)</i> man
page for more details.
By default, this tool uses the @ref device-quirks for the pressure range. To
narrow down on the best values for your device, specify the 'logically down'
and 'logically up' pressure thresholds with the `--touch-thresholds`
argument:
@verbatim
$ sudo libinput measure touchpad-pressure --touch-thresholds=10:8 --palm-threshold=20
@endverbatim
Interact with the touchpad and check if the output of this tool matches your
expectations.
@note **This is an interactive process. You will need to re-run the
tool with varying thresholds until you find the right range for your
touchpad. Attaching output logs to a bug will not help, only you with access
to the hardware can figure out the correct ranges.**
Once the thresholds are decided on (e.g. 10 and 8), they can be enabled with
@ref device-quirks entry similar to this:
@verbatim
$> cat /etc/libinput/local-overrides.quirks
[Touchpad pressure override]
MatchUdevType=touchpad
MatchName=*SynPS/2 Synaptics TouchPad
MatchDMIModalias=dmi:*svnLENOVO:*:pvrThinkPadX230*
AttrPressureRange=10:8
@endverbatim
The file name **must** be `/etc/libinput/local-overrides.quirks`. The
The first line is the section name and can be free-form. The `Match`
directives limit the quirk to your touchpad, make sure the device name
matches your device's name (see `libinput record`'s output). The dmi
modalias match should be based on the information in
`/sys/class/dmi/id/modalias`. This modalias should be shortened to the
specific system's information, usually system vendor (svn)
and product name (pn).
Once in place, run the following command to verify the quirk is valid and
works for your device:
@verbatim
$ sudo libinput list-quirks /dev/input/event10
AttrPressureRange=10:8
@endverbatim
Replace the event node with the one from your device. If the
`AttrPressureRange` quirk does not show up, re-run with `--verbose` and
check the output for any error messages.
If the pressure range quirk shows up correctly, restart X or the
Wayland compositor and libinput should now use the correct pressure
thresholds. The @ref tools can be used to verify the correct
functionality first without the need for a restart.
Once the pressure ranges are deemed correct,
@ref reporting_bugs "report a bug" to get the pressure ranges into the
repository.
@section touchpad_touch_size_hwdb Debugging touch size ranges
This section describes how to determine the touchpad size ranges
required for a touchpad device and how to add the required @ref
device-quirks locally. Note that the quirk is **not public API** and **may
change at any time**. Users are advised to @ref reporting_bugs "report a bug"
with the updated pressure ranges when testing has completed.
Use the `libinput measure touch-size` tool provided by libinput.
This tool will search for your touchpad device and print some touch size
statistics, including whether a touch is/was considered logically down.
@note This tool will only work on touchpads with the `ABS_MT_MAJOR` axis.
Example output of the tool is below:
@verbatim
$ sudo libinput measure touch-size --touch-thresholds 10:8 --palm-threshold 14
Using ELAN Touchscreen: /dev/input/event5
&nbsp;
Ready for recording data.
Touch sizes used: 10:8
Palm size used: 14
Place a single finger on the device to measure touch size.
Ctrl+C to exit
&nbsp;
Sequence: major: [ 9.. 11] minor: [ 7.. 9]
Sequence: major: [ 9.. 10] minor: [ 7.. 7]
Sequence: major: [ 9.. 14] minor: [ 6.. 9] down
Sequence: major: [ 11.. 11] minor: [ 9.. 9] down
Sequence: major: [ 4.. 33] minor: [ 1.. 5] down palm
@endverbatim
The example output shows five completed touch sequences. For each, the
respective minimum and maximum pressure values are printed as well as some
statistics. The `down` and `palm` tags show that sequence was considered
logically down or a palm at some point. This is an interactive tool and its
output may change frequently. Refer to the <i>libinput-measure-touch-size(1)</i> man
page for more details.
By default, this tool uses the @ref device-quirks for the touch size range. To
narrow down on the best values for your device, specify the 'logically down'
and 'logically up' pressure thresholds with the `--touch-thresholds`
arguments as in the example above.
Interact with the touchpad and check if the output of this tool matches your
expectations.
@note **This is an interactive process. You will need to re-run the
tool with varying thresholds until you find the right range for your
touchpad. Attaching output logs to a bug will not help, only you with access
to the hardware can figure out the correct ranges.**
Once the thresholds are decided on (e.g. 10 and 8), they can be enabled with
@ref device-quirks entry similar to this:
@verbatim
$> cat /etc/libinput/local-overrides.quirks
[Touchpad touch size override]
MatchUdevType=touchpad
MatchName=*SynPS/2 Synaptics TouchPad
MatchDMIModalias=dmi:*svnLENOVO:*:pvrThinkPadX230*
AttrTouchSizeRange=10:8
@endverbatim
The first line is the match line and should be adjusted for the device name
(see evemu-record's output) and for the local system, based on the
information in `/sys/class/dmi/id/modalias`. The modalias should be
shortened to the specific system's information, usually system vendor (svn)
and product name (pn).
Once in place, run the following command to verify the quirk is valid and
works for your device:
@verbatim
$ sudo libinput list-quirks /dev/input/event10
AttrTouchSizeRange=10:8
@endverbatim
Replace the event node with the one from your device. If the
`AttrTouchSizeRange` quirk does not show up, re-run with `--verbose` and
check the output for any error messages.
If the touch size range property shows up correctly, restart X or the
Wayland compositor and libinput should now use the correct thresholds.
The @ref tools can be used to verify the correct functionality first without
the need for a restart.
Once the touch size ranges are deemed correct, @ref reporting_bugs "report a
bug" to get the thresholds into the repository.
*/

134
doc/absolute-axes.dox → doc/user/absolute-axes.rst
View file

@ -1,5 +1,8 @@
/**
@page absolute_axes Absolute axes
.. _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.
@ -10,7 +13,7 @@ libinput supports three types of devices with absolute axes:
- multi-touch screens
- single-touch screens
- @ref tablet-support "graphics tablets"
- :ref:`graphics tablets <tablet-support>`
Touchpads are technically absolute devices but libinput converts the axis values
to directional motion and posts events as relative events. Touchpads do not count
@ -19,11 +22,15 @@ 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. If the device is physically rotated from its natural
position and this rotation was communicated to libinput (e.g.
@ref libinput_device_config_left_handed_set "by setting the device left-handed"),
the coordinate origin is the top left corner of in the current rotation.
position and this rotation was communicated to libinput (e.g. by setting
the device left-handed),
the coordinate origin is the top left corner in the current rotation.
@section absolute_axes_handling Handling of absolute coordinates
.. _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
@ -31,8 +38,8 @@ 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_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
@ -40,87 +47,90 @@ 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
.. _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 do not
provide resolution, those devices are correctly handled within libinput
(touchpads are not absolute devices, as mentioned above).
@section calibration Calibration of absolute devices
.. _calibration:
------------------------------------------------------------------------------
Calibration of absolute devices
------------------------------------------------------------------------------
Absolute devices may require calibration to map precisely into the output
range required. This is done by setting a transformation matrix, see
libinput_device_config_calibration_set_matrix() which is applied to
**libinput_device_config_calibration_set_matrix()** which is applied to
each input coordinate.
@f[
\begin{pmatrix}
cos\theta & -sin\theta & xoff \\
sin\theta & cos\theta & yoff \\
0 & 0 & 1
\end{pmatrix} \begin{pmatrix}
x \\ y \\ 1
\end{pmatrix}
@f]
.. math::
\begin{pmatrix}
cos\theta & -sin\theta & xoff \\
sin\theta & cos\theta & yoff \\
0 & 0 & 1
\end{pmatrix} \begin{pmatrix}
x \\ y \\ 1
\end{pmatrix}
@f$\theta@f$ is the rotation angle. The offsets @f$xoff@f$ and @f$yoff@f$ are
specified in device dimensions, i.e. a value of 1 equals one device width
or height. Note that rotation applies to the device's origin, rotation
usually requires an offset to move the coordinates back into the original
range.
:math:`\theta` is the rotation angle. The offsets :math:`xoff` and :math:`yoff` are
specified in device dimensions, i.e. a value of 1 equals one device width or
height. Note that rotation applies to the device's origin, rotation usually
requires an offset to move the coordinates back into the original range.
The most common matrices are:
- 90 degree clockwise:
@f$
\begin{pmatrix}
0 & -1 & 1 \\
1 & 0 & 0 \\
0 & 0 & 1
\end{pmatrix}
@f$
.. math::
\begin{pmatrix}
0 & -1 & 1 \\
1 & 0 & 0 \\
0 & 0 & 1
\end{pmatrix}
- 180 degree clockwise:
@f$
\begin{pmatrix}
-1 & 0 & 1 \\
0 & -1 & 1 \\
0 & 0 & 1
\end{pmatrix}
@f$
.. math::
\begin{pmatrix}
-1 & 0 & 1 \\
0 & -1 & 1 \\
0 & 0 & 1
\end{pmatrix}
- 270 degree clockwise:
@f$
\begin{pmatrix}
0 & 1 & 0 \\
-1 & 0 & 1 \\
0 & 0 & 1
\end{pmatrix}
@f$
.. math::
\begin{pmatrix}
0 & 1 & 0 \\
-1 & 0 & 1 \\
0 & 0 & 1
\end{pmatrix}
- reflection along y axis:
@f$
\begin{pmatrix}
-1 & 0 & 1 \\
1 & 0 & 0 \\
0 & 0 & 1
\end{pmatrix}
@f$
.. math::
\begin{pmatrix}
-1 & 0 & 1 \\
1 & 0 & 0 \\
0 & 0 & 1
\end{pmatrix}
See Wikipedia's
[Transformation Matrix article](http://en.wikipedia.org/wiki/Transformation_matrix)
`Transformation Matrix article <http://en.wikipedia.org/wiki/Transformation_matrix>`_
for more information on the matrix maths. See
libinput_device_config_calibration_get_default_matrix() for how these
**libinput_device_config_calibration_get_default_matrix()** for how these
matrices must be supplied to libinput.
Once applied, any x and y axis value has the calibration applied before it
is made available to the caller. libinput does not provide access to the
raw coordinates before the calibration is applied.
@section absolute_axes_nonorm Why x/y coordinates are not normalized
.. _absolute_axes_nonorm:
x/y are not given in @ref motion_normalization "normalized coordinates"
------------------------------------------------------------------------------
Why x/y coordinates are not normalized
------------------------------------------------------------------------------
x/y are not given in :ref:`normalized coordinates <motion_normalization>`
([0..1]) for one simple reason: the aspect ratio of virtually all current
devices is something other than 1:1. A normalized axes thus is only useful to
determine that the stylus is e.g. at 78% from the left, 34% from the top of
@ -132,5 +142,3 @@ This could be alleviated by providing resolution and information about the
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.
*/

112
doc/absolute-coordinate-ranges.dox → doc/user/absolute-coordinate-ranges.rst
View file

@ -1,5 +1,8 @@
/**
@page absolute_coordinate_ranges Coordinate ranges for absolute axes
.. _absolute_coordinate_ranges:
==============================================================================
Coordinate ranges for absolute axes
==============================================================================
libinput requires that all touchpads provide a correct axis range and
resolution. These are used to enable or disable certain features or adapt
@ -21,98 +24,111 @@ This discrepancy between the coordinate range the kernels advertises vs.
what the touchpad sends can be the source of a number of perceived
bugs in libinput.
@section absolute_coordinate_ranges_fix Measuring and fixing touchpad ranges
.. _absolute_coordinate_ranges_fix:
------------------------------------------------------------------------------
Measuring and fixing touchpad ranges
------------------------------------------------------------------------------
To fix the touchpad you need to:
-# measure the physical size of your touchpad in mm
-# run touchpad-edge-detector
-# trim the udev match rule to something sensible
-# replace the resolution with the calculated resolution based on physical
settings
-# test locally
-# send a patch to the systemd project
#. measure the physical size of your touchpad in mm
#. run touchpad-edge-detector
#. trim the udev match rule to something sensible
#. replace the resolution with the calculated resolution based on physical settings
#. test locally
#. send a patch to the systemd project
Detailed explanations are below.
[libevdev](http://freedesktop.org/wiki/Software/libevdev/) provides a tool
`libevdev <http://freedesktop.org/wiki/Software/libevdev/>`_ provides a tool
called **touchpad-edge-detector** that allows measuring the touchpad's input
ranges. Run the tool as root against the device node of your touchpad device
and repeatedly move a finger around the whole outside area of the
touchpad. Then control+c the process and note the output.
An example output is below:
@verbatim
$> sudo touchpad-edge-detector /dev/input/event4
Touchpad SynPS/2 Synaptics TouchPad on /dev/input/event4
Move one finger around the touchpad to detect the actual edges
Kernel says: x [1024..3112], y [2024..4832]
Touchpad sends: x [2445..4252], y [3464..4071]
Touchpad size as listed by the kernel: 49x66mm
Calculate resolution as:
::
$> sudo touchpad-edge-detector /dev/input/event4
Touchpad SynPS/2 Synaptics TouchPad on /dev/input/event4
Move one finger around the touchpad to detect the actual edges
Kernel says: x [1024..3112], y [2024..4832]
Touchpad sends: x [2445..4252], y [3464..4071]
Touchpad size as listed by the kernel: 49x66mm
Calculate resolution as:
x axis: 2088/<width in mm>
y axis: 2808/<height in mm>
Suggested udev rule:
# <Laptop model description goes here>
evdev:name:SynPS/2 Synaptics TouchPad:dmi:bvnLENOVO:bvrGJET72WW(2.22):bd02/21/2014:svnLENOVO:pn20ARS25701:pvrThinkPadT440s:rvnLENOVO:rn20ARS25701:rvrSDK0E50512STD:cvnLENOVO:ct10:cvrNotAvailable:*
EVDEV_ABS_00=2445:4252:<x resolution>
EVDEV_ABS_01=3464:4071:<y resolution>
EVDEV_ABS_35=2445:4252:<x resolution>
EVDEV_ABS_36=3464:4071:<y resolution>
Suggested udev rule:
# <Laptop model description goes here>
evdev:name:SynPS/2 Synaptics TouchPad:dmi:bvnLENOVO:bvrGJET72WW(2.22):bd02/21/2014:svnLENOVO:pn20ARS25701:pvrThinkPadT440s:rvnLENOVO:rn20ARS25701:rvrSDK0E50512STD:cvnLENOVO:ct10:cvrNotAvailable:*
EVDEV_ABS_00=2445:4252:<x resolution>
EVDEV_ABS_01=3464:4071:<y resolution>
EVDEV_ABS_35=2445:4252:<x resolution>
EVDEV_ABS_36=3464:4071:<y resolution>
@endverbatim
Note the discrepancy between the coordinate range the kernels advertises vs.
what the touchpad sends.
To fix the advertised ranges, the udev rule should be taken and trimmed
before being sent to the [systemd project](https://github.com/systemd/systemd).
before being sent to the `systemd project <https://github.com/systemd/systemd>`_.
An example commit can be found
[here](https://github.com/systemd/systemd/commit/26f667eac1c5e89b689aa0a1daef6a80f473e045).
`here <https://github.com/systemd/systemd/commit/26f667eac1c5e89b689aa0a1daef6a80f473e045>`_.
In most cases the match can and should be trimmed to the system vendor (svn)
and the product version (pvr), with everything else replaced by a wildcard
(*). In this case, a Lenovo T440s, a suitable match string would be: @verbatim
evdev:name:SynPS/2 Synaptics TouchPad:dmi:*svnLENOVO:*pvrThinkPadT440s*
@endverbatim
(*). In this case, a Lenovo T440s, a suitable match string would be:
::
@note hwdb match strings only allow for alphanumeric ascii characters. Use a
evdev:name:SynPS/2 Synaptics TouchPad:dmi:*svnLENOVO:*pvrThinkPadT440s*
.. note:: hwdb match strings only allow for alphanumeric ascii characters. Use a
wildcard (* or ?, whichever appropriate) for special characters.
The actual axis overrides are in the form:
@verbatim
# axis number=min:max:resolution
EVDEV_ABS_00=2445:4252:42
@endverbatim
::
# axis number=min:max:resolution
EVDEV_ABS_00=2445:4252:42
or, if the range is correct but the resolution is wrong
@verbatim
# axis number=::resolution
EVDEV_ABS_00=::42
@endverbatim
::
# axis number=::resolution
EVDEV_ABS_00=::42
Note the leading single space. The axis numbers are in hex and can be found
in *linux/input-event-codes.h*. For touchpads ABS_X, ABS_Y,
ABS_MT_POSITION_X and ABS_MT_POSITION_Y are required.
@note The touchpad's ranges and/or resolution should only be fixed when
.. note:: The touchpad's ranges and/or resolution should only be fixed when
there is a significant discrepancy. A few units do not make a
difference and a resolution that is off by 2 or less usually does
not matter either.
Once a match and override rule has been found, follow the instructions at
the top of the
[60-evdev.hwdb](https://github.com/systemd/systemd/blob/master/hwdb/60-evdev.hwdb)
`60-evdev.hwdb <https://github.com/systemd/systemd/blob/master/hwdb/60-evdev.hwdb>`_
file to save it locally and trigger the udev hwdb reload. Rebooting is
always a good idea. If the match string is correct, the new properties will
show up in the
output of
@verbatim
udevadm info /sys/class/input/event4
@endverbatim
::
udevadm info /sys/class/input/event4
Adjust the command for the event node of your touchpad.
A udev builtin will apply the new axis ranges automatically.
When the axis override is confirmed to work, please submit it as a pull
request to the [systemd project](https://github.com/systemd/systemd).
*/
request to the `systemd project <https://github.com/systemd/systemd>`_.

327
doc/user/architecture.rst Normal file
View file

@ -0,0 +1,327 @@
.. _architecture:
==============================================================================
libinput's internal architecture
==============================================================================
This page provides an outline of libinput's internal architecture. The goal
here is to get the high-level picture across and point out the components
and their interplay to new developers.
The public facing API is in ``libinput.c``, this file is thus the entry point
for almost all API calls. General device handling is in ``evdev.c`` with the
device-type-specific implementations in ``evdev-<type>.c``. It is not
necessary to understand all of libinput to contribute a patch.
:ref:`architecture-contexts` is the only user-visible implementation detail,
everything else is purely internal implementation and may change when
required.
.. _architecture-contexts:
------------------------------------------------------------------------------
The udev and path contexts
------------------------------------------------------------------------------
The first building block is the "context" which can be one of
two types, "path" and "udev". See **libinput_path_create_context()** and
**libinput_udev_create_context()**. The path/udev specific bits are in
``path-seat.c`` and ``udev-seat.c``. This includes the functions that add new
devices to a context.
.. graphviz::
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
libudev [label="libudev 'add' event"]
udev [label="**libinput_udev_create_context()**"];
udev_backend [label="udev-specific backend"];
context [label="libinput context"]
udev -> udev_backend;
libudev -> udev_backend;
udev_backend -> context;
}
The udev context provides automatic device hotplugging as udev's "add"
events are handled directly by libinput. The path context requires that the
caller adds devices.
.. graphviz::
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
path [label="**libinput_path_create_context()**"];
path_backend [label="path-specific backend"];
xdriver [label="**libinput_path_add_device()**"]
context [label="libinput context"]
path -> path_backend;
xdriver -> path_backend;
path_backend -> context;
}
As a general rule: all Wayland compositors use a udev context, the X.org
stack uses a path context.
Which context was initialized only matters for creating/destroying a context
and adding devices. The device handling itself is the same for both types of
context.
.. _architecture-device:
------------------------------------------------------------------------------
Device initialization
------------------------------------------------------------------------------
libinput only supports evdev devices, all the device initialization is done
in ``evdev.c``. Much of the libinput public API is also a thin wrapper around
the matching implementation in the evdev device.
There is a 1:1 mapping between libinput devices and ``/dev/input/eventX``
device nodes.
.. graphviz::
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
devnode [label="/dev/input/event0"]
libudev [label="libudev 'add' event"]
xdriver [label="**libinput_path_add_device()**"]
context [label="libinput context"]
evdev [label="evdev_device_create()"]
devnode -> xdriver;
devnode -> libudev;
xdriver -> context;
libudev -> context;
context->evdev;
}
Entry point for all devices is ``evdev_device_create()``, this function
decides to create a ``struct evdev_device`` for the given device node.
Based on the udev tags (e.g. ``ID_INPUT_TOUCHPAD``), a
:ref:`architecture-dispatch` is initialized. All event handling is then in this
dispatch.
Rejection of devices and the application of quirks is generally handled in
``evdev.c`` as well. Common functionality shared across multiple device types
(like button-scrolling) is also handled here.
.. _architecture-dispatch:
------------------------------------------------------------------------------
Device-type specific event dispatch
------------------------------------------------------------------------------
Depending on the device type, ``evdev_configure_device`` creates the matching
``struct evdev_dispatch``. This dispatch interface contains the function
pointers to handle events. Four such dispatch methods are currently
implemented: touchpad, tablet, tablet pad, and the fallback dispatch which
handles mice, keyboards and touchscreens.
.. graphviz::
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
evdev [label="evdev_device_create()"]
fallback [label="evdev-fallback.c"]
touchpad [label="evdev-mt-touchpad.c"]
tablet [label="evdev-tablet.c"]
pad [label="evdev-tablet-pad.c"]
evdev -> fallback;
evdev -> touchpad;
evdev -> tablet;
evdev -> pad;
}
While ``evdev.c`` pulls the event out of libevdev, the actual handling of the
events is performed within the dispatch method.
.. graphviz::
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
evdev [label="evdev_device_dispatch()"]
fallback [label="fallback_interface_process()"];
touchpad [label="tp_interface_process()"]
tablet [label="tablet_process()"]
pad [label="pad_process()"]
evdev -> fallback;
evdev -> touchpad;
evdev -> tablet;
evdev -> pad;
}
The dispatch methods then look at the ``struct input_event`` and proceed to
update the state. Note: the serialized nature of the kernel evdev protocol
requires that the device updates the state with each event but to delay
processing until the ``SYN_REPORT`` event is received.
.. _architecture-configuration:
------------------------------------------------------------------------------
Device configuration
------------------------------------------------------------------------------
All device-specific configuration is handled through ``struct
libinput_device_config_FOO`` instances. These are set up during device init
and provide the function pointers for the ``get``, ``set``, ``get_default``
triplet of configuration queries (or more, where applicable).
For example, the ``struct tablet_dispatch`` for tablet devices has a
``struct libinput_device_config_accel``. This struct is set up with the
required function pointers to change the profiles.
.. graphviz::
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
tablet [label="struct tablet_dispatch"]
config [label="struct libinput_device_config_accel"];
tablet_config [label="tablet_accel_config_set_profile()"];
tablet->config;
config->tablet_config;
}
When the matching ``**libinput_device_config_set_FOO()**`` is called, this goes
through to the config struct and invokes the function there. Thus, it is
possible to have different configuration functions for a mouse vs a
touchpad, even though the interface is the same.
.. graphviz::
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
libinput [label="**libinput_device_config_accel_set_profile()**"];
tablet_config [label="tablet_accel_config_set_profile()"];
libinput->tablet_config;
}
.. _architecture-filter:
------------------------------------------------------------------------------
Pointer acceleration filters
------------------------------------------------------------------------------
All pointer acceleration is handled in the ``filter.c`` file and its
associated files.
The ``struct motion_filter`` is initialized during device init, whenever
deltas are available they are passed to ``filter_dispatch()``. This function
returns a set of :ref:`normalized coordinates <motion_normalization_customization>`.
All actual acceleration is handled within the filter, the device itself has
no further knowledge. Thus it is possible to have different acceleration
filters for the same device types (e.g. the Lenovo X230 touchpad has a
custom filter).
.. graphviz::
digraph context
{
compound=true;
rankdir="LR";
node [
shape="box";
]
fallback [label="fallback deltas"];
touchpad [label="touchpad deltas"];
tablet [label="tablet deltas"];
filter [label="filter_dispatch"];
fallback->filter;
touchpad->filter;
tablet->filter;
flat [label="accelerator_interface_flat()"];
x230 [label="accelerator_filter_x230()"];
pen [label="tablet_accelerator_filter_flat_pen()"];
filter->flat;
filter->x230;
filter->pen;
}
Most filters convert the deltas (incl. timestamps) to a motion speed and
then apply a so-called profile function. This function returns a factor that
is then applied to the current delta, converting it into an accelerated
delta. See :ref:`pointer-acceleration` for more details.
the current

317
doc/user/building.rst Normal file
View file

@ -0,0 +1,317 @@
.. _building_libinput:
==============================================================================
libinput build instructions
==============================================================================
.. contents::
:local:
:backlinks: entry
Instructions on how to build libinput and its tools and how to build against
libinput.
The build instruction on this page detail how to overwrite your
system-provided libinput with one from the git repository, see
see :ref:`reverting_install` to revert to the previous state.
.. _building:
------------------------------------------------------------------------------
Building libinput
------------------------------------------------------------------------------
libinput uses `meson <https://www.mesonbuild.com>`_ and
`ninja <https://www.ninja-build.org>`_. A build is usually the three-step
process below. A successful build requires the
:ref:`building_dependencies` to be installed before running meson.
::
$> git clone https://gitlab.freedesktop.org/libinput/libinput
$> cd libinput
$> meson --prefix=/usr builddir/
$> ninja -C builddir/
$> sudo ninja -C builddir/ install
When running libinput versions 1.11.x or earlier, you must run
::
$> sudo udevadm hwdb --update
Additional options may also be specified. For example:
::
$> meson --prefix=/usr -Ddocumentation=false builddir/
We recommend that users disable the documentation, it's not usually required
for testing and reduces the number of dependencies needed.
The ``prefix`` or other options can be changed later with the
``mesonconf`` command. For example:
::
$> mesonconf builddir/ -Dprefix=/some/other/prefix -Ddocumentation=true
$> ninja -C builddir
$> sudo ninja -C builddir/ install
Running ``mesonconf builddir/`` with no other arguments lists all
configurable options meson provides.
To rebuild from scratch, simply remove the build directory and run meson
again:
::
$> rm -r builddir/
$> meson --prefix=....
.. _verifying_install:
..............................................................................
Verifying the install
..............................................................................
To verify the install worked correctly, check that libinput.so.x.x.x is in
the library path and that all symlinks point to the new library.
::
$> ls -l /usr/lib64/libinput.*
-rwxr-xr-x 1 root root 946 Apr 28 2015 /usr/lib64/libinput.la
lrwxrwxrwx 1 root root 19 Feb 1 15:12 /usr/lib64/libinput.so -> libinput.so.10.13.0
lrwxrwxrwx 1 root root 19 Feb 1 15:12 /usr/lib64/libinput.so.10 -> libinput.so.10.13.0
-rwxr-xr-x 1 root root 204992 Feb 1 15:12 /usr/lib64/libinput.so.10.13.0
.. _reverting_install:
..............................................................................
Reverting to the system-provided libinput package
..............................................................................
The recommended way to revert to the system install is to use the package
manager to reinstall the libinput package. In some cases, this may leave
files in the system (e.g. ``/usr/lib/libinput.la``) but these files are
usually harmless. To definitely remove all files, run the following command
from the libinput source directory:
::
$> sudo ninja -C builddir/ uninstall
# WARNING: Do not restart the computer/X/the Wayland compositor after
# uninstall, reinstall the system package immediately!
The following commands reinstall the current system package for libinput,
overwriting manually installed files.
- **Debian/Ubuntu** based distributions: ``sudo apt-get install --reinstall libinput``
- **Fedora 22** and later: ``sudo dnf reinstall libinput``
- **RHEL/CentOS/Fedora 21** and earlier: ``sudo yum reinstall libinput``
- **openSUSE**: ``sudo zypper install --force libinput10``
- **Arch**: ``sudo packman -S libinput``
.. _building_selinux:
..............................................................................
SELinux adjustments
..............................................................................
On systems with SELinux, overwriting the distribution-provided package with
a manually built libinput may cause SELinux denials. This usually manifests
when gdm does not start because it is denied access to libinput. The journal
shows a log message in the form of:
::
May 25 15:28:42 localhost.localdomain audit[23268]: AVC avc: denied { execute } for pid=23268 comm="gnome-shell" path="/usr/lib64/libinput.so.10.12.2" dev="dm-0" ino=1709093 scontext=system_u:system_r:xdm_t:s0-s0:c0.c1023 tcontext=unconfined_u:object_r:user_home_t:s0 tclass=file permissive=0
May 25 15:28:42 localhost.localdomain org.gnome.Shell.desktop[23270]: /usr/bin/gnome-shell: error while loading shared libraries: libinput.so.10: failed to map segment from shared object
The summary of this error message is that gdm's gnome-shell runs in the
``system_u:system_r:xdm_t`` context but libinput is installed with the
context ``unconfined_u:object_r:user_home_t``.
To avoid this issue, restore the SELinux context for any system files.
::
$> sudo restorecon /usr/lib*/libinput.so.*
This issue is tracked in https://github.com/mesonbuild/meson/issues/1967.
.. _building_dependencies:
..............................................................................
Build dependencies
..............................................................................
libinput has a few build-time dependencies that must be installed prior to
running configure.
.. note:: The build dependencies for some distributions can be found in the
`GitLab Continuous Integration file <https://gitlab.freedesktop.org/libinput/libinput/blob/master/.gitlab-ci.yml>`_.
Search for **FEDORA_RPMS** in the **variables:** definition
and check the list for an entry for your distribution.
In most cases, it is sufficient to install the dependencies that your
distribution uses to build the libinput package. These can be installed
with one of the following commands:
- **Debian/Ubuntu** based distributions: ``sudo apt-get build-dep libinput``
- **Fedora 22** and later: ``sudo dnf builddep libinput``
- **RHEL/CentOS/Fedora 21** and earlier: ``sudo yum-builddep libinput``
- **openSUSE**: ::
$> sudo zypper modifyrepo --enable ``zypper repos | grep source | awk '{print $5}'``
$> sudo zypper source-install -d libinput10
$> sudo zypper install autoconf automake libtool
$> sudo zypper modifyrepo --disable ``zypper repos | grep source | awk '{print $5}'``
- **Arch**: ::
$> sudo pacman -S asp
$> cd $(mktemp -d)
$> asp export libinput
$> cd libinput
$> makepkg --syncdeps --nobuild --noextract
If dependencies are missing, a message ``No package 'foo' found`` will be
shown during the configure stage. See
`this blog post here <https://who-t.blogspot.com.au/2014/05/configure-fails-with-no-package-foo.html>`_
for instructions on how to fix it.
.. _building_libwacom:
..............................................................................
Building without libwacom
..............................................................................
libwacom is required by libinput's tablet code to gather additional
information about tablets that is not available from the kernel device
itself. libwacom is required by default but can be skipped when
:ref:`building`.
::
$> meson --prefix=/usr -Dlibwacom=false builddir
It is not recommended to disable libwacom unless libinput is used in an
environment where tablet support is not required. libinput provides tablet
support even without libwacom, but some features may be missing or working
differently.
.. _building_debug_gui:
..............................................................................
Building without the graphical helper tool
..............................................................................
The :ref:`tools` provide commandline features as well as graphical debugging
features. To keep dependencies in check on some builds, the graphical
features of the :ref:`tools` can be disabled. By default, the ``debug-gui``
feature of the ``libinput`` tool is enabled and if the required libraries are
not available, the build will fail. If the feature is not required, use the
```--disable-debug-gui``` argument when :ref:`building`.
::
$> meson --prefix=/usr -Ddebug-gui=false builddir
.. _building_autotools:
..............................................................................
Building with autotools
..............................................................................
**libinput no longer supports building with autotools.** These
instructions are kept for users for libinput versions up to 1.8.x.
A build with automake is usually the process below. A successful build
requires the :ref:`building_dependencies` to be installed at configure
time.
::
$> git clone https://gitlab.freedesktop.org/libinput/libinput
$> cd libinput
$> ./autogen.sh --prefix=/usr --libdir=/usr/lib64
$> make
$> sudo make install
$> sudo udevadm hwdb --update
.. note:: On Debian-based distributions including Ubuntu and its derivatives skip the
``--libdir=/usr/lib64`` argument.
To uninstall libinput as detailed in section :ref:`reverting_install`, run
::
$> sudo make uninstall
# WARNING: Do not restart the computer/X/the Wayland compositor after make
# uninstall, reinstall the system package immediately!
To disable libwacom as detailed in section :ref:`building_libwacom`, run
::
$> ./autogen.sh --disable-libwacom --prefix=/usr --libdir=/usr/lib64
To disable the graphical helper tool as detailed in section
:ref:`building_debug_gui`, run
::
$> ./autogen.sh --disable-debug-gui --prefix=/usr --libdir=/usr/lib64
.. _building_against:
------------------------------------------------------------------------------
Building against libinput
------------------------------------------------------------------------------
libinput provides a
`pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`_ file.
Software that uses libinput should use pkg-config and the
``PKG_CHECK_MODULES`` autoconf macro.
Otherwise, the most rudimentary way to compile and link a program against
libinput is:
::
gcc -o myprogram myprogram.c ``pkg-config --cflags --libs libinput``
For further information on using pkgconfig see the pkg-config documentation.

12
doc/button_debouncing.dox → doc/user/button_debouncing.rst
View file

@ -1,6 +1,9 @@
/**
@page button_debouncing Button debouncing
.. _button_debouncing:
==============================================================================
Button debouncing
==============================================================================
Physical buttons experience wear-and-tear with usage. On some devices this
can result in an effect called "contact bouncing" or "chatter". This effect
@ -42,6 +45,7 @@ extra line is added to show the timeouts used by libinput that
affect the button state handling. The waveform's high and low states
correspond to the buttons 'pressed' and 'released' states, respectively.
@image html button-debouncing-wave-diagram.svg "Diagram illustrating button debouncing"
.. figure:: button-debouncing-wave-diagram.svg
:align: center
*/
Diagram illustrating button debouncing"

58
doc/clickpad-softbuttons.dox → doc/user/clickpad-softbuttons.rst
View file

@ -1,5 +1,8 @@
/**
@page clickpad_softbuttons Clickpad software button behavior
.. _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
@ -10,15 +13,19 @@ 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](https://www.kernel.org/doc/Documentation/input/event-codes.txt)
property. To perform a right-click on a Clickpad, libinput provides @ref
software_buttons and @ref clickfinger.
`INPUT_PROP_BUTTONPAD <https://www.kernel.org/doc/Documentation/input/event-codes.txt>`_
property. To perform a right-click on a Clickpad, libinput provides
:ref:`software_buttons` and @ref clickfinger.
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.
@section software_buttons Software button areas
.. _software_buttons:
------------------------------------------------------------------------------
Software button areas
------------------------------------------------------------------------------
On most clickpads, this is the default behavior. The bottom of the touchpad
is split into three distinct areas generate left, middle or right button
@ -37,11 +44,14 @@ than the left or right button. The actual size is device-dependent though as
many touchpads do not have visible markings for the middle button the exact
location of the button is not visibly obvious.
@image html software-buttons.svg "Left, right and middle-button click with software button areas"
.. figure:: software-buttons.svg
:align: center
@note If middle button emulation is enabled on a clickpad, only left and right
Left, right and middle-button click with software button areas"
.. note:: If middle button emulation is enabled on a clickpad, only left and right
button areas are available. For more details, see
libinput_device_config_middle_emulation_set_enabled().
**libinput_device_config_middle_emulation_set_enabled()**.
If fingers are down in the main area in addition to fingers in the
left or right button area, those fingers are are ignored.
@ -65,7 +75,11 @@ a left button click without any positional finger data and it is
impossible to determine whether it is a left or a right click. libinput
ignores such button clicks, this behavior is intentional.
@section clickfinger Clickfinger behavior
.. _clickfinger:
------------------------------------------------------------------------------
Clickfinger behavior
------------------------------------------------------------------------------
This is the default behavior on Apple touchpads.
Here, a left, right, middle button event is generated when one, two, or
@ -73,34 +87,42 @@ 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.
@image html clickfinger.svg "One, two and three-finger click with Clickfinger behavior"
.. figure:: clickfinger.svg
:align: center
One, two and three-finger click with Clickfinger behavior"
On some touchpads, libinput imposes a limit on how the fingers may be placed
on the touchpad. In the most common use-case this allows for a user to
trigger a click with the thumb while leaving the pointer-moving finger on
the touchpad.
@image html clickfinger-distance.svg "Illustration of the distance detection algorithm"
.. figure:: clickfinger-distance.svg
:align: center
Illustration of the distance detection algorithm"
In the illustration above the red area marks the proximity area around the
first finger. Since the thumb is outside of that area libinput considers the
click a single-finger click rather than a two-finger click.
Clickfinger configuration can be enabled through the
libinput_device_config_click_set_method() call. If clickfingers are
**libinput_device_config_click_set_method()** call. If clickfingers are
enabled on a touchpad with top software buttons, the top area will keep
acting as softbuttons for use with the trackpoint. Clickfingers will be used
everywhere else on the touchpad.
@section special_clickpads 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"
------------------------------------------------------------------------------
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:`Lenovo \*40 series touchpad support <t440_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.
*/

170
doc/user/conf.py.in Normal file
View file

@ -0,0 +1,170 @@
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/stable/config
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = '@PROJECT_NAME@'
copyright = '2018, the libinput authors'
author = 'the libinput authors'
# The short X.Y version
version = '@PROJECT_VERSION@'
# The full version, including alpha/beta/rc tags
release = '@PROJECT_VERSION@'
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.mathjax',
'sphinx.ext.graphviz',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path .
exclude_patterns = []
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
highlight_language = 'none'
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
html_theme_options = {
'collapse_navigation': False,
'navigation_depth': 3,
}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
# html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = '@PROJECT_NAME@doc'
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, '@PROJECT_NAME@.tex', '@PROJECT_NAME@ Documentation',
'Peter Hutterer', 'manual'),
]
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, '@PROJECT_NAME@', '@PROJECT_NAME@ Documentation',
[author], 1)
]
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, '@PROJECT_NAME@', '@PROJECT_NAME@ Documentation',
author, '@PROJECT_NAME@', 'One line description of project.',
'Miscellaneous'),
]
# -- Extension configuration -------------------------------------------------
from recommonmark.parser import CommonMarkParser
source_parsers = {
'.md': CommonMarkParser,
}

18
doc/user/contributing.rst Normal file
View file

@ -0,0 +1,18 @@
.. _contributing:
==============================================================================
Contributing to libinput
==============================================================================
Contributions to libinput are always welcome. Any patches should be sent to
the
`wayland-devel <https://lists.freedesktop.org/mailman/listinfo/wayland-devel>`_
email list with a subject prefix of ``[PATCH libinput]``. The easiest
way to achieve that is to run the following command in the libinput
repository: ::
git config --add format.subjectprefix "PATCH libinput"
Likewise, any new features should also be discussed publicly on the
wayland-devel list.

49
doc/user/development.rst Normal file
View file

@ -0,0 +1,49 @@
.. _development:
==============================================================================
Information for developers
==============================================================================
Below is a list of topics of interest to developers, divided into
information for those **using** libinput as library in a Wayland compositor
or other project. The :ref:`hacking_on_libinput` section applies to developers working on
libinput itself.
.. _using_libinput_as_library:
*************************
Using libinput as library
*************************
.. note:: If you use libinput you should get in touch with the libinput
developers on the wayland-devel@lists.freedesktop.org mailing
lists
The API documentation is available here:
http://wayland.freedesktop.org/libinput/doc/latest/api/
Topics below explain some behaviors of libinput.
.. toctree::
:maxdepth: 1
absolute-axes.rst
absolute-coordinate-ranges.rst
normalization-of-relative-motion.rst
seats.rst
timestamps.rst
.. _hacking_on_libinput:
*******************
Hacking on libinput
*******************
.. toctree::
:maxdepth: 1
contributing.rst
architecture
test-suite.rst
pointer-acceleration.rst
device-configuration-via-udev.rst

260
doc/user/device-configuration-via-udev.rst Normal file
View file

@ -0,0 +1,260 @@
.. _udev_config:
==============================================================================
Static device configuration via udev
==============================================================================
libinput supports some static configuration through udev properties.
These properties are read when the device is initially added
to libinput's device list, i.e. before the
**LIBINPUT_EVENT_DEVICE_ADDED** event is generated.
The following udev properties are supported:
LIBINPUT_CALIBRATION_MATRIX
Sets the calibration matrix, see
**libinput_device_config_calibration_get_default_matrix()**. If unset,
defaults to the identity matrix.
The udev property is parsed as 6 floating point numbers separated by a
single space each (scanf(3) format ``"%f %f %f %f %f %f"``).
The 6 values represent the first two rows of the calibration matrix as
described in **libinput_device_config_calibration_set_matrix()**.
Example values are: ::
ENV{LIBINPUT_CALIBRATION_MATRIX}="1 0 0 0 1 0" # default
ENV{LIBINPUT_CALIBRATION_MATRIX}="0 -1 1 1 0 0" # 90 degree clockwise
ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 -1 1" # 180 degree clockwise
ENV{LIBINPUT_CALIBRATION_MATRIX}="0 1 0 -1 0 1" # 270 degree clockwise
ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 1 0" # reflect along y axis
LIBINPUT_DEVICE_GROUP
A string identifying the **libinput_device_group** for this device. Two
devices with the same property value are grouped into the same device group,
the value itself is irrelevant otherwise.
LIBINPUT_IGNORE_DEVICE
If set to anything other than "0", the device is ignored by libinput.
See :ref:`ignoring_devices` for more details.
ID_SEAT
Assigns the physical :ref:`seat <seats>` for this device. See
**libinput_seat_get_physical_name()**. Defaults to "seat0".
ID_INPUT
If this property is set, the device is considered an input device. Any
device with this property missing will be ignored, see :ref:`udev_device_type`.
ID_INPUT_KEYBOARD, ID_INPUT_KEY, ID_INPUT_MOUSE, ID_INPUT_TOUCHPAD, ID_INPUT_TOUCHSCREEN, ID_INPUT_TABLET, ID_INPUT_JOYSTICK, ID_INPUT_ACCELEROMETER
If any of the above is set, libinput initializes the device as the given
type, see :ref:`udev_device_type`. Note that for historical reasons more than
one of these may be set at any time, libinput will select only one of these
to determine the device type. To ensure libinput selects the correct device
type, only set one of them.
WL_SEAT
Assigns the logical :ref:`seat <seats>` for this device. See
**libinput_seat_get_logical_name()** context. Defaults to "default".
MOUSE_DPI
HW resolution and sampling frequency of a relative pointer device.
See :ref:`motion_normalization` for details.
MOUSE_WHEEL_CLICK_ANGLE
The angle in degrees for each click on a mouse wheel. See
**libinput_pointer_get_axis_source()** for details.
Below is an example udev rule to assign "seat1" to a device from vendor
0x012a with the model ID of 0x034b. ::
ACTION=="add|change", KERNEL=="event[0-9]*", ENV{ID_VENDOR_ID}=="012a", \
ENV{ID_MODEL_ID}=="034b", ENV{ID_SEAT}="seat1"
.. _udev_device_type:
------------------------------------------------------------------------------
Device type assignment via udev
------------------------------------------------------------------------------
libinput requires the **ID_INPUT** property to be set on a device,
otherwise the device will be ignored. In addition, one of
**ID_INPUT_KEYBOARD, ID_INPUT_KEY, ID_INPUT_MOUSE, ID_INPUT_TOUCHPAD,
ID_INPUT_TOUCHSCREEN, ID_INPUT_TABLET, ID_INPUT_JOYSTICK,
ID_INPUT_ACCELEROMETER** must be set on the device to determine the
device type. The usual error handling applies within libinput and a device
type label does not guarantee that the device is initialized by libinput.
If a device fails to meet the requirements for a device type (e.g. a keyboard
labelled as touchpad) the device will not be available through libinput.
Only one device type should be set per device at a type, though libinput can
handle some combinations for historical reasons.
Below is an example udev rule to remove an **ID_INPUT_TOUCHPAD** setting
and change it into an **ID_INPUT_TABLET** setting. This rule would apply
for a device with the vendor/model ID of 012a/034b. ::
ACTION=="add|change", KERNEL=="event[0-9]*", ENV{ID_VENDOR_ID}=="012a", \
ENV{ID_MODEL_ID}=="034b", ENV{ID_INPUT_TOUCHPAD}="", ENV{ID_INPUT_TABLET}="1"
.. _ignoring_devices:
------------------------------------------------------------------------------
Ignoring specific devices
------------------------------------------------------------------------------
If a device has the **LIBINPUT_IGNORE_DEVICE** udev property set to any
value but "0", that device is not initialized by libinput. For a context
created with **libinput_udev_create_context()**, the device is silently ignored
and never shows up. If the device is added with **libinput_path_add_device()**
to a context created with **libinput_path_create_context()**, adding the device
will fail and return NULL (see that function's documentation for more
information).
If the property value is exactly "0", then the property is considered unset
and libinput initializes the device normally.
This property should be used for devices that are correctly detected as
input devices (see :ref:`udev_device_type`) but that should not be used by
libinput. It is recommended that devices that should not be handled as input
devices at all unset the **ID_INPUT** and related properties instead. The
**LIBINPUT_IGNORE_DEVICE** property signals that only libinput should
ignore this property but other parts of the stack (if any) should continue
treating this device normally.
.. _model_specific_configuration:
------------------------------------------------------------------------------
Model-specific configuration
------------------------------------------------------------------------------
As of libinput 1.12, model-specific configuration is stored in the
:ref:`device-quirks` and not in the hwdb anymore. Please see @ref device-quirks for
details.
.. _model_specific_configuration_x220fw81:
..............................................................................
Lenovo x220 with touchpad firmware v8.1
..............................................................................
The property **LIBINPUT_MODEL_LENOVO_X220_TOUCHPAD_FW81** may be set by a
user in a local hwdb file. This property designates the touchpad on a Lenovo
x220 with a touchpad firmware version 8.1. When this firmware version is
installed, the touchpad is imprecise. The touchpad device does not send
continuos x/y axis position updates, a behavior also observed on its
successor model, the Lenovo x230 which has the same firmware version. If the
above property is set, libinput adjusts its behavior to better suit this
particular model.
The touchpad firmware version cannot be detected automatically by libinput,
local configuration is required to set this property. Refer to the libinput
model quirks hwdb for instructions.
This property must not be used for any other purpose, no specific behavior
is guaranteed.
.. _hwdb:
------------------------------------------------------------------------------
Configuring the hwdb
------------------------------------------------------------------------------
This section outlines how to query the
`udev hwdb <https://www.freedesktop.org/software/systemd/man/hwdb.html>`_
and reload properties so they are available to libinput.
The hwdb contains a set of match rules that assign udev properties that are
available to libinput when the device is connected and/or libinput is
initialized. This section only describes the hwdb in relation to libinput,
it is not a full documentation on how the hwdb works.
libinput's use of the hwdb is limited to properties systemd and custom
rules files (where available) provide. Hardware-specific quirks as used by
libinput are in the :ref:`device-quirks` system.
.. _hwdb_querying:
..............................................................................
Querying the hwdb
..............................................................................
libinput only uses device nodes in the form of ``/dev/input/eventX`` where X
is the number of the specific device. Running ``libinput debug-events`` lists
all devices currently available to libinput and their event node name: ::
$> sudo libinput debug-events
-event2 DEVICE_ADDED Power Button seat0 default group1 cap:k
-event5 DEVICE_ADDED Video Bus seat0 default group2 cap:k
-event0 DEVICE_ADDED Lid Switch seat0 default group3 cap:S
...
Note the event node name for your device and translate it into a syspath in
the form of ``/sys/class/input/eventX``. This path can be supplied to ``udevadm
info`` ::
$> udevadm info
P: /devices/LNXSYSTM:00/LNXSYBUS:00/PNP0C0D:00/input/input0/event0
N: input/event0
E: DEVNAME=/dev/input/event0
E: DEVPATH=/devices/LNXSYSTM:00/LNXSYBUS:00/PNP0C0D:00/input/input0/event0
E: ID_INPUT=1
E: ID_INPUT_SWITCH=1
E: MAJOR=13
E: MINOR=64
E: SUBSYSTEM=input
E: TAGS=:power-switch:
E: USEC_INITIALIZED=7167898
Lines starting with ``E:`` are udev properties available to libinput. For
example, the above device's ``ID_INPUT_SWITCH`` property will cause libinput
to treat this device as switch device.
.. _hwdb_reloading:
..............................................................................
Reloading the hwdb
..............................................................................
The actual hwdb is stored in binary file on-disk and must be updated
manually whenever a ``.hwdb`` file changes. This is required both when a user
manually edits the ``.hwdb`` file but also when the git tree is updated (and
that update causes a hwdb change).
To update the binary file on-disk, run: ::
sudo udevadm hwdb --update
Then, to trigger a reload of all properties on your device, run: ::
sudo udevadm trigger /sys/class/input/eventX
Then check with ``udevadm info`` whether the properties were updated, see
:ref:`hwdb_querying`. If a new property does not appear on the device, use ``udevadm
test`` to check for error messages by udev and the hwdb (e.g. syntax errors
in the udev rules files). ::
sudo udevadm test /sys/class/input/eventX
.. _hwdb_modifying:
..............................................................................
Modifying the hwdb
..............................................................................
.. warning:: This section has been removed as it no longer applies in libinput 1.12
and later. libinput users should not need to modify the hwdb, any
device-specific quirks must go in to the :ref:`device-quirks` system.
For information about older libinput versions, please see the documentation
for your version avaialable in: https://wayland.freedesktop.org/libinput/doc/

179
doc/user/device-quirks.rst Normal file
View file

@ -0,0 +1,179 @@
.. _device-quirks:
==============================================================================
Device quirks
==============================================================================
libinput requires extra information from devices that is not always readily
available. For example, some touchpads are known to have jumping cursors
under specific conditions. libinput ships a set of files containting the
so-called model quirks to provide that information. Model quirks are usually
installed under ``/usr/share/libinput/<filename>.quirks`` and are standard
``.ini`` files. A file may contain multiple section headers (``[some
identifier]``) followed by one or more ``MatchFoo=Bar`` directives, followed by
at least one of ``ModelFoo=1`` or ``AttrFoo=bar`` directive. See the
``quirks/README.md`` file in the libinput source repository for more details on
their contents.
.. warning:: Model quirks are internal API and may change at any time. No
backwards-compatibility is guaranteed.
For example, a quirks file may have this content to label all keyboards on
the serial bus (PS/2) as internal keyboards: ::
[Serial Keyboards]
MatchUdevType=keyboard
MatchBus=serial
AttrKeyboardIntegration=internal
The model quirks are part of the source distribution and should never be
modified locally. Updates to libinput may overwrite modifications or even
stop parsing any property. For temporary local workarounds, see
:ref:`device-quirks-local`.
Device quirks are parsed on libinput initialization. A parsing error in the
device quirks disables **all** device quirks and may negatively impact
device behavior on the host. If the quirks cannot be loaded, an error
message is posted to the log and users should use the information in
:ref:`device-quirks-debugging` to verify their quirks files.
.. _device-quirks-local:
------------------------------------------------------------------------------
Installing temporary local device quirks
------------------------------------------------------------------------------
The model quirks are part of the source distribution and should never be
modified. For temporary local workarounds, libinput reads the
``/etc/libinput/local-overrides.quirks`` file. Users may add a sections to
this file to add a device quirk for a local device but beware that **any
modification must be upstreamed** or it may cease to work at any time.
.. warning:: Model quirks are internal API and may change at any time. No
backwards-compatibility is guaranteed. Local overrides should only
be used until the distribution updates the libinput packages.
The ``local-overrides.quirks`` file usually needs to be created by the user.
Once the required section has been added, use the information from section
:ref:`device-quirks-debugging` to validate and test the quirks.
.. _device-quirks-debugging:
------------------------------------------------------------------------------
Debugging device quirks
------------------------------------------------------------------------------
libinput provides the ``libinput quirks`` tool to debug the quirks database.
This tool takes an action as first argument, the most common invocation is
``libinput quirks list`` to list model quirks that apply to one or more local
devices. ::
$ libinput quirks list /dev/input/event19
Device has no quirks defined
$ libinput quirks list /dev/input/event0
AttrLidSwitchReliability
When called with the ``--verbose`` argument, ``libinput quirks list`` prints
information about all files and its attempts to match the device: ::
$ libinput quirks list --verbose /dev/input/event0
quirks debug: /usr/share/share/libinput is data root
quirks debug: /usr/share/share/libinput/10-generic-keyboard.quirks
quirks debug: /usr/share/share/libinput/10-generic-lid.quirks
[...]
quirks debug: /usr/share/etc/libinput/local-overrides.quirks
quirks debug: /dev/input/event0: fetching quirks
quirks debug: [Serial Keyboards] (10-generic-keyboard.quirks) wants MatchBus but we don't have that
quirks debug: [Lid Switch Ct9] (10-generic-lid.quirks) matches for MatchName
quirks debug: [Lid Switch Ct10] (10-generic-lid.quirks) matches for MatchName
quirks debug: [Lid Switch Ct10] (10-generic-lid.quirks) matches for MatchDMIModalias
quirks debug: [Lid Switch Ct10] (10-generic-lid.quirks) is full match
quirks debug: property added: AttrLidSwitchReliability from [Lid Switch Ct10] (10-generic-lid.quirks)
quirks debug: [Aiptek No Tilt Tablet] (30-vendor-aiptek.quirks) wants MatchBus but we don't have that
[...]
quirks debug: [HUION PenTablet] (30-vendor-huion.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech Marble Mouse Trackball] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech K400] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech K400r] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech K830] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech K400Plus] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Logitech Wireless Touchpad] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
quirks debug: [Microsoft Surface 3 Lid Switch] (30-vendor-microsoft.quirks) matches for MatchName
[...]
AttrLidSwitchReliability
Note that this is an example only, the output may change over time. The tool
uses the same parser as libinput and any parsing errors will show up in the
output.
.. _device-quirks-list:
------------------------------------------------------------------------------
List of supported device quirks
------------------------------------------------------------------------------
This list is a guide for developers to ease the process of submitting
patches upstream. This section shows device quirks supported in git
commit @includedoc git-version.dox
.. warning:: Quirks are internal API and may change at any time for any reason.
No guarantee is given that any quirk below works on your version of
libinput.
In the documentation below, the letters N, M, O, P refer to arbitrary integer
values.
Quirks starting with **Model*** triggers implementation-defined behaviour
for this device not needed for any other device. Only the more
general-purpose **Model*** flags are listed here.
ModelALPSTouchpad, ModelAppleTouchpad, ModelWacomTouchpad, ModelChromebook
Reserved for touchpads made by the respective vendors
ModelTabletNoTilt
Indicates that the tablet stylus does not provide tilt axis
information, even if the kernel exposes that axis.
ModelTabletNoProximityOut
Indicates that the tablet stylus does not send correct proximity out
events.
ModelTouchpadVisibleMarker
Indicates the touchpad has a drawn-on visible marker between the software
buttons.
ModelTabletModeNoSuspend
Indicates that the device does not need to be
suspended in :ref:`switches_tablet_mode`.
ModelTrackball
Reserved for trackballs
ModelBouncingKeys
Indicates that the device may send fake bouncing key events and
timestamps can not be relied upon.
ModelSynapticsSerialTouchpad
Reserved for touchpads made by Synaptics on the serial bus
AttrSizeHint=NxM, AttrResolutionHint=N
Hints at the width x height of the device in mm, or the resolution
of the x/y axis in units/mm. These may only be used where they apply to
a large proportion of matching devices. They should not be used for any
specific device, override ``EVDEV_ABS_*`` instead, see
:ref:`absolute_coordinate_ranges_fix`.
AttrTouchSizeRange=N:M, AttrPalmSizeThreshold=O
Specifies the touch size required to trigger a press (N) and to trigger
a release (M). O > N > M. See :ref:`touchpad_touch_size_hwdb` for more
details.
AttrTouchPressureRange=N:M, AttrPalmPressureThreshold=O, AttrThumbPressureThreshold=P
Specifies the touch pressure required to trigger a press (N) and to
trigger a release (M), when a palm touch is triggered (O) and when a
thumb touch is triggered (P). O > P > N > M. See
:ref:`touchpad_pressure_hwdb` for more details.
AttrLidSwitchReliability=reliable|write_open
Indicates the reliability of the lid switch. This is a string enum. Do not
use "reliable" for any specific device. Very few devices need this, if in
doubt do not set. See :ref:`switches_lid` for details.
AttrKeyboardIntegration=internal|external
Indicates the integration of the keyboard. This is a string enum.
Generally only needed for USB keyboards.
AttrTPKComboLayout=below
Indicates the position of the touchpad on an external touchpad+keyboard
combination device. This is a string enum. Don't specify it unless the
touchpad is below.

0
doc/dot/evemu.gv → doc/user/dot/evemu.gv
View file

0
doc/dot/libinput-stack-gnome.gv → doc/user/dot/libinput-stack-gnome.gv
View file

0
doc/dot/libinput-stack-wayland.gv → doc/user/dot/libinput-stack-wayland.gv
View file

0
doc/dot/libinput-stack-xorg.gv → doc/user/dot/libinput-stack-xorg.gv
View file

0
doc/dot/seats-sketch-libinput.gv → doc/user/dot/seats-sketch-libinput.gv
View file

0
doc/dot/seats-sketch.gv → doc/user/dot/seats-sketch.gv
View file

228
doc/faqs.dox → doc/user/faqs.rst
View file

@ -1,45 +1,75 @@
/**
@page faq FAQs - Frequently Asked Questions
.. _faq:
==============================================================================
FAQs - Frequently Asked Questions
==============================================================================
Frequently asked questions about libinput.
@tableofcontents
@section faq_feature Why doesn't libinput support ...?
.. contents::
:local:
:backlinks: entry
First, read @ref what_is_libinput If you have a feature that you think
libinput needs to support, please file a bug report. See @ref reporting_bugs
.. _faq_feature:
------------------------------------------------------------------------------
Why doesn't libinput support ...?
------------------------------------------------------------------------------
First, read :ref:`what_is_libinput` If you have a feature that you think
libinput needs to support, please file a bug report. See :ref:`reporting_bugs`
for more details.
@section faq_fast_mouse My mouse moves too fast, even at the slowest setting
.. _faq_fast_mouse:
------------------------------------------------------------------------------
My mouse moves too fast, even at the slowest setting
------------------------------------------------------------------------------
This is a symptom of high-dpi mice (greater than 1000dpi). These devices
need a udev hwdb entry to normalize their motion. See @ref
motion_normalization for a detailed explanation.
need a udev hwdb entry to normalize their motion. See
:ref:`motion_normalization` for a detailed explanation.
@section faq_fast_trackpoint My trackpoint moves too slow or too fast
.. _faq_fast_trackpoint:
------------------------------------------------------------------------------
My trackpoint moves too slow or too fast
------------------------------------------------------------------------------
This is a symptom of an invalid trackpoint multiplier. These devices need
@ref device-quirks to specify the range available so libinput can adjust the
pointer acceleration accordingly. See @ref trackpoint_range for a detailed
:ref:`device-quirks` to specify the range available so libinput can adjust the
pointer acceleration accordingly. See :ref:`trackpoint_range` for a detailed
explanation.
@section faq_enable_tapping Why isn't touchpad tap-to-click enabled by default
.. _faq_enable_tapping:
See @ref tapping_default
------------------------------------------------------------------------------
Why isn't touchpad tap-to-click enabled by default
------------------------------------------------------------------------------
@section faq_touchpad_pressure Why does my touchpad lose track of touches
See :ref:`tapping_default`
.. _faq_touchpad_pressure:
------------------------------------------------------------------------------
Why does my touchpad lose track of touches
------------------------------------------------------------------------------
The most common cause for this is an incorrect pressure threshold range.
See @ref touchpad_pressure for more info.
See :ref:`touchpad_pressure` for more info.
@section faq_kinetic_scrolling Kinetic scrolling does not work
.. _faq_kinetic_scrolling:
------------------------------------------------------------------------------
Kinetic scrolling does not work
------------------------------------------------------------------------------
The X.Org synaptics driver implemented kinetic scrolling in the driver. It
measures the scroll speed and once the finger leaves the touchpad the driver
keeps sending scroll events for a predetermined time. This effectively
provides for kinetic scrolling without client support but triggers an
unfixable [bug](https://bugs.freedesktop.org/show_bug.cgi?id=38909): the
unfixable `bug <https://bugs.freedesktop.org/show_bug.cgi?id=38909>`_: the
client cannot know that the events are from a kinetic scroll source. Scroll
events in X are always sent to the current cursor position, a movement of the
cursor after lifting the finger will send the kinetic scroll events to the
@ -47,17 +77,25 @@ new client, something the user does not usually expect. A key event during
the kinetic scroll procedure causes side-effects such as triggering zoom.
libinput does not implement kinetic scrolling for touchpads. Instead it
provides the libinput_event_pointer_get_axis_source() function that enables
callers to implement kinetic scrolling on a per-widget basis, see @ref
scroll_sources.
provides the **libinput_event_pointer_get_axis_source()** function that enables
callers to implement kinetic scrolling on a per-widget basis, see
:ref:`scroll_sources`.
@section faq_gpl Is libinput GPL-licensed?
.. _faq_gpl:
------------------------------------------------------------------------------
Is libinput GPL-licensed?
------------------------------------------------------------------------------
No, libinput is MIT licensed. The Linux kernel header file linux/input.h in
libinput's tree is provided to ensure the same behavior regardless of which
kernel version libinput is built on. It does not make libinput GPL-licensed.
@section faq_config_options Where is the configuration stored?
.. _faq_config_options:
------------------------------------------------------------------------------
Where is the configuration stored?
------------------------------------------------------------------------------
libinput does not store configuration options, it is up to the caller to
manage these and decide which configuration option to apply to each device.
@ -79,62 +117,78 @@ effect.
In both cases, the selection of available options and how they are exposed
depends on the libinput caller (e.g. mutter or xf86-input-libinput).
@dotfile libinput-stack-gnome.gv
.. graphviz:: libinput-stack-gnome.gv
This has an effect on the availability of configuration options: if an
option is not exposed by the intermediary, it cannot be configured by the
client. Also some configuration options that are provided by the
intermediary may not be libinput-specific configuration options.
@section faq_configure_wayland How do I configure my device on Wayland?
.. _faq_configure_wayland:
See @ref faq_config_options Use the configuration tool provided by your
------------------------------------------------------------------------------
How do I configure my device on Wayland?
------------------------------------------------------------------------------
See :ref:`faq_config_options` Use the configuration tool provided by your
desktop environment (e.g. gnome-control-center) or direct access to your
desktop environment's configuration storage (e.g. gsettings).
@section faq_configure_xorg How do I configure my device on X?
.. _faq_configure_xorg:
See @ref faq_config_options If your desktop environment does not provide a
------------------------------------------------------------------------------
How do I configure my device on X?
------------------------------------------------------------------------------
See :ref:`faq_config_options` If your desktop environment does not provide a
graphical configuration tool you can use an
[xorg.conf.d snippet](https://www.x.org/archive/current/doc/man/man5/xorg.conf.5.xhtml).
`xorg.conf.d snippet <https://www.x.org/archive/current/doc/man/man5/xorg.conf.5.xhtml>`_.
Usually, such a snippet looks like this:
@verbatim
$> cat /etc/X11/xorg.conf.d/99-libinput-custom-config.conf
Section "InputClass"
Identifier "something to identify this snippet"
MatchDriver "libinput"
MatchProduct "substring of the device name"
Option "some option name" "the option value"
EndSection
@endverbatim
::
$> cat /etc/X11/xorg.conf.d/99-libinput-custom-config.conf
Section "InputClass"
Identifier "something to identify this snippet"
MatchDriver "libinput"
MatchProduct "substring of the device name"
Option "some option name" "the option value"
EndSection
The identifier is merely a human-readable string that shows up in the log
file. The MatchProduct line should contain the device name or a substring of
the device name that the snippet should apply to. For a full list of option
names and permitted values, see the
[libinput man page](https://www.mankier.com/4/libinput).
`libinput man page <https://www.mankier.com/4/libinput>`_.
xorg.conf.d snippets like the above apply to hotplugged devices but can be
overwritten at runtime by desktop tools. Multiple snippets may be placed
into the same file.
For run-time configuration and testing, the
[xinput](https://www.x.org/archive/X11R7.5/doc/man/man1/xinput.1.html)
`xinput <https://www.x.org/archive/X11R7.5/doc/man/man1/xinput.1.html>`_
debugging tool can modify a devices' properties. See the
[libinput man page](https://www.mankier.com/4/libinput)
`libinput man page <https://www.mankier.com/4/libinput>`_
for supported property names and values. Usually, an invocation looks like
this:
@verbatim
$> xinput set-prop "the device name" "the property name" value [value2] [value3]
@endverbatim
@note Changes performed by xinput do not persist across device hotplugs. xinput
::
$> xinput set-prop "the device name" "the property name" value [value2] [value3]
.. note:: Changes performed by xinput do not persist across device hotplugs. xinput
is considered a debugging and testing tool only and should not be used
for permanent configurations.
@section faq_configuration Can you add a configuration option for $FEATURE?
.. _faq_configuration:
------------------------------------------------------------------------------
Can you add a configuration option for $FEATURE?
------------------------------------------------------------------------------
No. At least that's going to be the initial answer. Read
[Why libinput doesn't have a lot of configuration options](http://who-t.blogspot.com/2016/04/why-libinput-doesnt-have-lot-of-config.html)
`Why libinput doesn't have a lot of configuration options <http://who-t.blogspot.com/2016/04/why-libinput-doesnt-have-lot-of-config.html>`_
first. Configuration options for most features are a signal that we are incapable
of handling it correctly. To get to that point, we want to be sure we're
truly incapable of doing so. libinput has several features that
@ -144,7 +198,11 @@ configuration options for initially.
So the answer to this question will almost always be 'no'. A configuration
option is, in most cases, a cop-out.
@section faq_synclient Why don't synclient and syndaemon work with libinput?
.. _faq_synclient:
------------------------------------------------------------------------------
Why don't synclient and syndaemon work with libinput?
------------------------------------------------------------------------------
Synclient and syndaemon rely on X input device properties that are specific
to the xf86-input-synaptics X.Org input driver. Both were written when the
@ -155,52 +213,72 @@ driver-specific properties, synclient/syndaemon will thus not detect the
touchpad and refuse to work. Other tools that rely on synclient/syndaemon or
those same properties also do not work with xf86-input-libinput.
Most of syndaemon's functionality is built into libinput, see @ref
disable-while-typing. synclient is merely a configuration tool, see
@ref faq_configure_xorg for similar functionality.
Most of syndaemon's functionality is built into libinput, see
:ref:`disable-while-typing`. synclient is merely a configuration tool, see
:ref:`faq_configure_xorg` for similar functionality.
See also the blog posts
[The definitive guide to synclient](http://who-t.blogspot.com.au/2017/01/the-definitive-guide-to-synclient.html) and
[The future of xinput, xmodmap, setxkbmap, xsetwacom and other tools under Wayland](http://who-t.blogspot.com.au/2016/12/the-future-of-xinput-xmodmap-setxkbmap.html)
`The definitive guide to synclient <http://who-t.blogspot.com.au/2017/01/the-definitive-guide-to-synclient.html>`_ and
`The future of xinput, xmodmap, setxkbmap, xsetwacom and other tools under Wayland <http://who-t.blogspot.com.au/2016/12/the-future-of-xinput-xmodmap-setxkbmap.html>`_
@section faq_tablets Does libinput support non-Wacom tablets?
.. _faq_tablets:
------------------------------------------------------------------------------
Does libinput support non-Wacom tablets?
------------------------------------------------------------------------------
Yes, though unfortunately many non-Wacom tablets suffer from bad firmware
and don't send the required events. But they should all work nonetheless. If
you have a tablet that does not work with libinput, please @ref
reporting_bugs "file a bug".
you have a tablet that does not work with libinput, please
:ref:`file a bug <reporting_bugs>`.
@section faq_tablet_capabilities My tablet doesn't work
.. _faq_tablet_capabilities:
------------------------------------------------------------------------------
My tablet doesn't work
------------------------------------------------------------------------------
If you see the message
@verbatim
libinput bug: device does not meet tablet criteria. Ignoring this device.
@endverbatim
::
libinput bug: device does not meet tablet criteria. Ignoring this device.
or the message
@verbatim
missing tablet capabilities [...] Ignoring this device.
@endverbatim
::
missing tablet capabilities [...] Ignoring this device.
your tablet device does not have the required capabilities to be treated as
a tablet. This is usually a problem with the device and the kernel driver.
See @ref tablet-capabilities for more details.
See :ref:`tablet-capabilities` for more details.
@section faq_hwdb_changes How to apply hwdb changes
.. _faq_hwdb_changes:
------------------------------------------------------------------------------
How to apply hwdb changes
------------------------------------------------------------------------------
Sometimes users are asked to test updates to the
[udev hwdb](https://www.freedesktop.org/software/systemd/man/hwdb.html)
or patches that include a change to the hwdb. See @ref hwdb for
`udev hwdb <https://www.freedesktop.org/software/systemd/man/hwdb.html>`_
or patches that include a change to the hwdb. See :ref:`hwdb` for
details on the hwdb and how to modify it locally.
@note As of libinput 1.12, libinput-specific properties are now stored in
the @ref device-quirks system. There are no libinput-specific hwdb
.. note:: As of libinput 1.12, libinput-specific properties are now stored in
the :ref:`device-quirks` system. There are no libinput-specific hwdb
entries anymore and any changes to the hwdb must be merged into the
systemd repository.
@section faq_timer_offset What causes the "timer offset negative" warning?
.. _faq_timer_offset:
libinput relies on the caller to call libinput_dispatch() whenever data is
------------------------------------------------------------------------------
What causes the "timer offset negative" warning?
------------------------------------------------------------------------------
libinput relies on the caller to call **libinput_dispatch()** whenever data is
available on the epoll-fd. Doing so will process the state of all devices
and can trigger some timers to be set (e.g. palm detection, tap-to-click,
disable-while-typing, etc.). Internally, libinput's time offsets are always
@ -220,7 +298,11 @@ The warning has no immediate effect on libinput's behavior but some of the
functionality that relies on the timer may be impeded (e.g. palms are not
detected as they should be).
@section faq_wayland Is libinput required for Wayland?
.. _faq_wayland:
------------------------------------------------------------------------------
Is libinput required for Wayland?
------------------------------------------------------------------------------
Technically - no. But for your use-case - probably.
@ -242,5 +324,3 @@ are more specialized (e.g. in-vehicle infotainment or IVI) can handle input
devices directly but the compositor you want to use
on your desktop needs an input stack that is more complex. And right now,
libinput is the only input stack that exists for this use-case.
*/

29
doc/user/features.rst Normal file
View file

@ -0,0 +1,29 @@
.. _features:
==============================================================================
libinput Features
==============================================================================
Below is a list of features supported by libinput. The availability of
features usually depends on the device type and a device's capabilties.
Not all features are user-configurable, some rely on @see device-quirks
to be useful.
.. toctree::
:maxdepth: 1
button_debouncing.rst
clickpad-softbuttons.rst
gestures.rst
middle-button-emulation.rst
palm-detection.rst
scrolling.rst
t440-support.rst
tapping.rst
tablet-support.rst
switches.rst
touchpad-jitter.rst
touchpad-jumping-cursors.rst
touchpad-pressure.rst
trackpoints.rst

102
doc/gestures.dox → doc/user/gestures.rst
View file

@ -1,40 +1,51 @@
/**
@page gestures Gestures
.. _gestures:
==============================================================================
Gestures
==============================================================================
libinput supports basic gestures on touchpads and other indirect input
devices. Two types of gestures are supported: @ref gestures_pinch and @ref
gestures_swipe. Support for gestures depends on the hardware device, most
devices. Two types of gestures are supported: :ref:`gestures_pinch` and
@ref gestures_swipe. Support for gestures depends on the hardware device, most
touchpads support both gestures and any device that may send gesture events
has the @ref LIBINPUT_DEVICE_CAP_GESTURE capability set.
has the **LIBINPUT_DEVICE_CAP_GESTURE** capability set.
Note that libinput **does not** support gestures on touchscreens, see
@ref gestures_touchscreens.
:ref:`gestures_touchscreens`.
@section gestures_lifetime Lifetime of a gesture
.. _gestures_lifetime:
------------------------------------------------------------------------------
Lifetime of a gesture
------------------------------------------------------------------------------
A gesture's lifetime has three distinct stages: begin, update and end, each
with their own event types. Begin is sent when the fingers are first set
down or libinput decides that the gesture begins. For @ref gestures_pinch
down or libinput decides that the gesture begins. For :ref:`gestures_pinch`
this sets the initial scale. Any events changing properties of the gesture
are sent as update events. On termination of the gesture, an end event is
sent.
A gesture includes the finger count (see
libinput_event_gesture_get_finger_count()) and that finger count remains the
**libinput_event_gesture_get_finger_count()**) and that finger count remains the
same for the lifetime of a gesture. Thus, if a user puts down a fourth
finger during a three-finger swipe gesture, libinput will end
the three-finger gesture and, if applicable, start a four-finger swipe
gesture. A caller may decide that those gestures are semantically identical
and continue the two gestures as one single gesture.
@see LIBINPUT_EVENT_GESTURE_PINCH_BEGIN
@see LIBINPUT_EVENT_GESTURE_PINCH_UPDATE
@see LIBINPUT_EVENT_GESTURE_PINCH_END
@see LIBINPUT_EVENT_GESTURE_PINCH_BEGIN
@see LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE
@see LIBINPUT_EVENT_GESTURE_SWIPE_END
**LIBINPUT_EVENT_GESTURE_PINCH_BEGIN**
**LIBINPUT_EVENT_GESTURE_PINCH_UPDATE**
**LIBINPUT_EVENT_GESTURE_PINCH_END**
**LIBINPUT_EVENT_GESTURE_PINCH_BEGIN**
**LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE**
**LIBINPUT_EVENT_GESTURE_SWIPE_END**
@section gestures_pinch Pinch gestures
.. _gestures_pinch:
------------------------------------------------------------------------------
Pinch gestures
------------------------------------------------------------------------------
Pinch gestures are executed when two or more fingers are located on the
touchpad and are either changing the relative distance to each other
@ -45,7 +56,10 @@ caller with the delta x/y coordinates of that center, the relative angle of
the fingers compared to the previous event, and the absolute scale compared
to the initial finger position.
@image html pinch-gestures.svg "The pinch and rotate gestures"
.. figure:: pinch-gestures.svg
:align: center
The pinch and rotate gestures"
The illustration above shows a basic pinch in the left image and a rotate in
the right angle. Not shown is a movement of the logical center if the
@ -56,7 +70,11 @@ Note that while position and angle is relative to the previous event, the
scale is always absolute and a multiplier of the initial finger position's
scale.
@section gestures_swipe Swipe gestures
.. _gestures_swipe:
------------------------------------------------------------------------------
Swipe gestures
------------------------------------------------------------------------------
Swipe gestures are executed when three or more fingers are moved
synchronously in the same direction. libinput provides x and y coordinates
@ -64,12 +82,19 @@ in the gesture and thus allows swipe gestures in any direction, including
the tracing of complex paths. It is up to the caller to interpret the
gesture into an action or limit a gesture to specific directions only.
@image html swipe-gestures.svg "The swipe gestures"
.. figure:: swipe-gestures.svg
:align: center
The swipe gestures"
The illustration above shows a vertical three-finger swipe. The coordinates
provided during the gesture are the movements of the logical center.
@section gestures_touchscreens Touchscreen gestures
.. _gestures_touchscreens:
------------------------------------------------------------------------------
Touchscreen gestures
------------------------------------------------------------------------------
Touchscreen gestures are **not** interpreted by libinput. Rather, any touch
point is passed to the caller and any interpretation of gestures is up to
@ -79,7 +104,10 @@ Interpreting gestures on a touchscreen requires context that libinput does
not have, such as the location of windows and other virtual objects on the
screen as well as the context of those virtual objects:
@image html touchscreen-gestures.svg "Context-sensitivity of touchscreen gestures"
.. figure:: touchscreen-gestures.svg
:align: center
Context-sensitivity of touchscreen gestures"
In this example, the finger movements are identical but in the left case
both fingers are located within the same window, thus suggesting an attempt
@ -88,15 +116,22 @@ thus suggesting a window movement. libinput only has knowledge of the finger
coordinates (and even then only in device coordinates, not in screen
coordinates) and thus cannot differentiate the two.
@section gestures_softbuttons Gestures with enabled software buttons
.. _gestures_softbuttons:
If the touchpad device is a @ref touchpads_buttons_clickpads "Clickpad", it
is recommended that a caller switches to @ref clickfinger.
Usually fingers placed in a @ref software_buttons "software button area" is not
------------------------------------------------------------------------------
Gestures with enabled software buttons
------------------------------------------------------------------------------
If the touchpad device is a :ref:`Clickpad <touchpads_buttons_clickpads>`, it
is recommended that a caller switches to :ref:`clickfinger`.
Usually fingers placed in a :ref:`software button area <software_buttons>` is not
considered for gestures, resulting in some gestures to be interpreted as
pointer motion or two-finger scroll events.
@image html pinch-gestures-softbuttons.svg "Interference of software buttons and pinch gestures"
.. figure:: pinch-gestures-softbuttons.svg
:align: center
Interference of software buttons and pinch gestures"
In the example above, the software button area is highlighted in red. The
user executes a three-finger pinch gesture, with the thumb remaining in the
@ -104,9 +139,13 @@ software button area. libinput ignores fingers within the software button
areas, the movement of the remaining fingers is thus interpreted as a
two-finger scroll motion.
@section gestures_twofinger_touchpads Gestures on two-finger touchpads
.. _gestures_twofinger_touchpads:
As of kernel 4.2, many @ref touchpads_touch_partial_mt provide only two
------------------------------------------------------------------------------
Gestures on two-finger touchpads
------------------------------------------------------------------------------
As of kernel 4.2, many :ref:`touchpads_touch_partial_mt` provide only two
slots. This affects how gestures can be interpreted. Touchpads with only two
slots can identify two touches by position but can usually tell that there
is a third (or fourth) finger down on the touchpad - without providing
@ -119,11 +158,12 @@ whenever a user puts the index and middle finger down first. Since the third
finger does not have positional information, it's location cannot be
determined.
@image html gesture-2fg-ambiguity.svg "Ambiguity of three-finger gestures on two-finger touchpads"
.. figure:: gesture-2fg-ambiguity.svg
:align: center
Ambiguity of three-finger gestures on two-finger touchpads"
The image above illustrates this ambiguity. The index and middle finger are
set down first, the data stream from both finger positions looks identical.
In this case, libinput assumes the fingers are in a horizontal arrangement
(the right image above) and use a swipe gesture.
*/

71
doc/user/index.rst Normal file
View file

@ -0,0 +1,71 @@
.. toctree::
:maxdepth: 2
:hidden:
what-is-libinput
features
building
faqs
reporting-bugs
troubleshooting
development
++++++++++++++++++++++++++++++
libinput
++++++++++++++++++++++++++++++
libinput is a library that provides a full input stack for display servers
and other applications that need to handle input devices provided by the
kernel.
libinput provides device detection, event handling and abstraction so
minimize the amount of custom input code the user of libinput need to
provide the common set of functionality that users expect. Input event
processing includes scaling touch coordinates, generating
relative pointer events from touchpads, pointer acceleration, etc.
libinput is not used directly by applications. Think of it more as a device
driver than an application library. See :ref:`what_is_libinput` for more details.
--------------------
Users and Developers
--------------------
Please use the side-bar to nagivate through the various documentation items.
-----------------
API documentation
-----------------
The API documentation is available here:
http://wayland.freedesktop.org/libinput/doc/latest/api/
.. note:: This documentation is generally only needed by authors of Wayland
compositors or other developers dealing with input events directly.
-------
License
-------
libinput is licensed under the MIT license
.. code-block:: none
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions: [...]
See the
`COPYING <https://gitlab.freedesktop.org/libinput/libinput/tree/master/COPYING>`_
file for the full license information.
.....
About
.....
Documentation generated from git commit
`__GIT_VERSION__ <https://gitlab.freedesktop.org/libinput/libinput/commit/__GIT_VERSION__>`_

113
doc/user/meson.build Normal file
View file

@ -0,0 +1,113 @@
# Sphinx build
sphinx = find_program('sphinx-build-3', 'sphinx-build', required : false)
if not sphinx.found()
error('Program "sphinx-build" not found or not executable. Try building with -Ddocumentation=false')
endif
sphinx_config = configuration_data()
sphinx_config.set('PROJECT_NAME', meson.project_name())
sphinx_config.set('PROJECT_VERSION', meson.project_version())
sphinx_conf_py = configure_file(input : 'conf.py.in',
output : 'conf.py',
configuration : sphinx_config,
install : false)
src_extra = [
# dot drawings
'dot/seats-sketch.gv',
'dot/seats-sketch-libinput.gv',
'dot/libinput-stack-wayland.gv',
'dot/libinput-stack-xorg.gv',
'dot/libinput-stack-gnome.gv',
'dot/evemu.gv',
# svgs
'svg/button-debouncing-wave-diagram.svg',
'svg/button-scrolling.svg',
'svg/clickfinger.svg',
'svg/clickfinger-distance.svg',
'svg/edge-scrolling.svg',
'svg/gesture-2fg-ambiguity.svg',
'svg/palm-detection.svg',
'svg/pinch-gestures.svg',
'svg/pinch-gestures-softbuttons.svg',
'svg/ptraccel-linear.svg',
'svg/ptraccel-low-dpi.svg',
'svg/ptraccel-touchpad.svg',
'svg/ptraccel-trackpoint.svg',
'svg/software-buttons.svg',
'svg/swipe-gestures.svg',
'svg/tablet-axes.svg',
'svg/tablet-cintiq24hd-modes.svg',
'svg/tablet-interfaces.svg',
'svg/tablet-intuos-modes.svg',
'svg/tablet-left-handed.svg',
'svg/tablet-out-of-bounds.svg',
'svg/tablet.svg',
'svg/tap-n-drag.svg',
'svg/thumb-detection.svg',
'svg/top-software-buttons.svg',
'svg/touchscreen-gestures.svg',
'svg/trackpoint-delta-illustration.svg',
'svg/twofinger-scrolling.svg',
]
src_rst = files(
'absolute-axes.rst',
'absolute-coordinate-ranges.rst',
'architecture.rst',
'building.rst',
'button_debouncing.rst',
'clickpad-softbuttons.rst',
'contributing.rst',
'device-configuration-via-udev.rst',
'device-quirks.rst',
'faqs.rst',
'gestures.rst',
'middle-button-emulation.rst',
'normalization-of-relative-motion.rst',
'palm-detection.rst',
'pointer-acceleration.rst',
'reporting-bugs.rst',
'scrolling.rst',
'seats.rst',
'switches.rst',
't440-support.rst',
'tablet-support.rst',
'tapping.rst',
'test-suite.rst',
'timestamps.rst',
'tools.rst',
'touchpad-jumping-cursors.rst',
'touchpad-pressure.rst',
'touchpad-jitter.rst',
'touchpads.rst',
'trackpoints.rst',
'what-is-libinput.rst',
'features.rst',
'development.rst',
'troubleshooting.rst',
)
src_sphinx = custom_target('sphinx-sources',
input : [src_rst, src_extra],
output : '.',
command : [prg_install, '-t', '@OUTDIR@', '@INPUT@'],
build_by_default: true)
index_page = vcs_tag(command : ['git', 'log', '-1', '--format=%h'],
fallback : 'unknown',
input : 'index.rst',
output : 'index.rst',
replace_string: '__GIT_VERSION__')
# drop '-a' once we are happy with all this
# do not use -j, it breaks on Ubuntu
sphinx_output_dir = 'Documentation'
custom_target('sphinx',
input : [ sphinx_conf_py, index_page ] + src_rst + src_extra,
output : [ sphinx_output_dir ],
command : [ sphinx, '-q', '-b', 'html', '-a',
meson.current_build_dir(), sphinx_output_dir],
depends: [ src_sphinx ],
build_by_default : true)

17
doc/middle-button-emulation.dox → doc/user/middle-button-emulation.rst
View file

@ -1,5 +1,8 @@
/**
@page middle_button_emulation Middle button emulation
.. _middle_button_emulation:
==============================================================================
Middle button emulation
==============================================================================
Middle button emulation provides users with the ability to generate a middle
click even when the device does not have a physical middle button available.
@ -16,7 +19,7 @@ appropriate to the physical device.
The middle button emulation behavior when combined with other device
buttons, including a physical middle button is device-dependent.
For example, @ref clickpad_softbuttons provides a middle button area when
For example, :ref:`clickpad_softbuttons` provides a middle button area when
middle button emulation is disabled. That middle button area disappears
when middle button emulation is enabled - a middle click can then only be
triggered by a simultaneous left + right click.
@ -26,9 +29,7 @@ enabling/disabling that emulation. Likewise, some devices may allow middle
button emulation but have it disabled by default. This is the case for most
mouse-like devices where a middle button is detected.
libinput provides libinput_device_config_middle_emulation_set_enabled() to
enable or disable middle button emulation. See @ref faq_configure_wayland
and @ref faq_configure_xorg for info on how to enable or disable middle
libinput provides **libinput_device_config_middle_emulation_set_enabled()** to
enable or disable middle button emulation. See :ref:`faq_configure_wayland`
and :ref:`faq_configure_xorg` for info on how to enable or disable middle
button emulation in the Wayland compositor or the X stack.
*/

66
doc/normalization-of-relative-motion.dox → doc/user/normalization-of-relative-motion.rst
View file

@ -1,5 +1,8 @@
/**
@page motion_normalization Normalization of relative motion
.. _motion_normalization:
==============================================================================
Normalization of relative motion
==============================================================================
Most relative input devices generate input in so-called "mickeys". A
mickey is in device-specific units that depend on the resolution
@ -28,7 +31,11 @@ This normalization only applies to accelerated coordinates, unaccelerated
coordinates are left in device-units. It is up to the caller to interpret
those coordinates correctly.
@section motion_normalization_touchpad Normalization of touchpad coordinates
.. _motion_normalization_touchpad:
------------------------------------------------------------------------------
Normalization of touchpad coordinates
------------------------------------------------------------------------------
Touchpads may have a different resolution for the horizontal and vertical
axis. Interpreting coordinates from the touchpad without taking resolution
@ -36,49 +43,50 @@ into account results in uneven motion.
libinput scales unaccelerated touchpad motion to the resolution of the
touchpad's x axis, i.e. the unaccelerated value for the y axis is:
y = (x / resolution_x) * resolution_y
``y = (x / resolution_x) * resolution_y``.
@section motion_normalization_tablet Normalization of tablet coordinates
.. _motion_normalization_tablet:
See @ref tablet-relative-motion
------------------------------------------------------------------------------
Normalization of tablet coordinates
------------------------------------------------------------------------------
@section motion_normalization_customization Setting custom DPI settings
See :ref:`tablet-relative-motion`
.. _motion_normalization_customization:
------------------------------------------------------------------------------
Setting custom DPI settings
------------------------------------------------------------------------------
Devices usually do not advertise their resolution and libinput relies on
the udev property <b>MOUSE_DPI</b> for this information. This property is usually
the udev property **MOUSE_DPI** for this information. This property is usually
set via the
[udev hwdb](http://cgit.freedesktop.org/systemd/systemd/tree/hwdb/70-mouse.hwdb).
The "mouse-dpi-tool" utility provided by
[libevdev](https://freedesktop.org/wiki/Software/libevdev/) should be
`udev hwdb <http://cgit.freedesktop.org/systemd/systemd/tree/hwdb/70-mouse.hwdb>`_.
The ``mouse-dpi-tool`` utility provided by
`libevdev <https://freedesktop.org/wiki/Software/libevdev/>`_ should be
used to measure a device's resolution.
The format of the property for single-resolution mice is:
@code
MOUSE_DPI=resolution@frequency
@endcode
The format of the property for single-resolution mice is: ::
MOUSE_DPI=resolution@frequency
The resolution is in dots per inch, the frequency in Hz.
The format of the property for multi-resolution mice may list multiple
resolutions and frequencies:
@code
MOUSE_DPI=r1@f1 *r2@f2 r3@f3
@endcode
resolutions and frequencies: ::
MOUSE_DPI=r1@f1 *r2@f2 r3@f3
The default frequency must be pre-fixed with an asterisk.
For example, these two properties are valid:
@code
MOUSE_DPI=800@125
MOUSE_DPI=400@125 800@125 *1000@500 5500@500
@endcode
For example, these two properties are valid: ::
The behavior for a malformed property is undefined.
MOUSE_DPI=800@125
MOUSE_DPI=400@125 800@125 *1000@500 5500@500
If the property is unset, libinput assumes the resolution is 1000dpi.
The behavior for a malformed property is undefined. If the property is
unset, libinput assumes the resolution is 1000dpi.
Note that HW does not usually provide information about run-time
resolution changes, libinput will thus not detect when a resolution
changes to the non-default value.
*/

84
doc/user/page-hierarchy.rst Normal file
View file

@ -0,0 +1,84 @@
.. _misc:
==============================================================================
Users
==============================================================================
- @subpage what_is_libinput
- @subpage faq
- @subpage tools
- @subpage reporting_bugs
.. _touchpads:
==============================================================================
Touchpads
==============================================================================
- @subpage scrolling
- @subpage clickpad_softbuttons
- @subpage tapping
- @subpage gestures
- @subpage touchpad_pressure
- @subpage palm_detection
- @subpage t440_support
- @subpage touchpad_jumping_cursor
- @subpage absolute_coordinate_ranges
- @subpage touchpad_jitter
.. _touchscreens:
==============================================================================
Touchscreens
==============================================================================
- @subpage absolute_axes
.. _pointers:
==============================================================================
Mice, Trackballs, etc.
==============================================================================
- @subpage motion_normalization
- @subpage middle_button_emulation
- @subpage button_debouncing
- @subpage trackpoints
.. _tablets:
==============================================================================
Graphics Tablets
==============================================================================
- @subpage tablet-support
.. _other_devices:
==============================================================================
Other devices
==============================================================================
- @subpage switches
.. _developers:
==============================================================================
Developers
==============================================================================
Contributions to libinput are always welcome. See the links below for
specific documentation.
- @subpage what_is_libinput
- @subpage contributing
- @subpage architecture
- @subpage building_libinput
- @subpage test-suite
- @subpage tools
- @subpage pointer-acceleration
- @subpage device-quirks
- @subpage udev_config
- @subpage seats
- @subpage timestamps

102
doc/palm-detection.dox → doc/user/palm-detection.rst
View file

@ -1,5 +1,8 @@
/**
@page palm_detection Palm detection
.. _palm_detection:
==============================================================================
Palm detection
==============================================================================
Palm detection tries to identify accidental touches while typing, while
using the trackpoint and/or during general use of the touchpad area.
@ -18,25 +21,33 @@ touchpads are less affected by palm touches.
libinput has multiple ways of detecting a palm, each of which depends on
hardware-specific capabilities.
- @ref palm_tool
- @ref palm_pressure
- @ref palm_touch_size
- @ref palm_exclusion_zones
- @ref trackpoint-disabling
- @ref disable-while-typing
- @ref stylus-touch-arbitration
- :ref:`palm_tool`
- :ref:`palm_pressure`
- :ref:`palm_touch_size`
- :ref:`palm_exclusion_zones`
- :ref:`trackpoint-disabling`
- :ref:`disable-while-typing`
- :ref:`stylus-touch-arbitration`
Palm detection is always enabled, with the exception of
disable-while-typing.
@section palm_tool Palm detection based on firmware labelling
.. _palm_tool:
------------------------------------------------------------------------------
Palm detection based on firmware labelling
------------------------------------------------------------------------------
Some devices provide palm detection in the firmware, forwarded by the kernel
as the `EV_ABS/ABS_MT_TOOL` axis with a value of `MT_TOOL_PALM`
as the ``EV_ABS/ABS_MT_TOOL`` axis with a value of ``MT_TOOL_PALM``
(whenever a palm is detected). libinput honors that value and switches that
touch to a palm.
@section palm_pressure Palm detection based on pressure
.. _palm_pressure:
------------------------------------------------------------------------------
Palm detection based on pressure
------------------------------------------------------------------------------
The simplest form of palm detection labels a touch as palm when the pressure
value goes above a certain threshold. This threshold is usually high enough
@ -46,19 +57,27 @@ the threshold again. This ensures that a palm remains a palm even when the
pressure changes as the user is typing.
For some information on how to detect pressure on a touch and debug the
pressure ranges, see @ref touchpad_pressure.
pressure ranges, see :ref:`touchpad_pressure`.
@section palm_touch_size Palm detection based on touch size
.. _palm_touch_size:
On touchads that support the `ABS_MT_TOUCH_MAJOR` axes, libinput can perform
------------------------------------------------------------------------------
Palm detection based on touch size
------------------------------------------------------------------------------
On touchads that support the ``ABS_MT_TOUCH_MAJOR`` axes, libinput can perform
palm detection based on the size of the touch ellipse. This works similar to
the pressure-based palm detection in that a touch is labelled as palm when
it exceeds the (device-specific) touch size threshold.
For some information on how to detect the size of a touch and debug the
touch size ranges, see @ref touchpad_pressure.
touch size ranges, see :ref:`touchpad_pressure`.
@section palm_exclusion_zones Palm exclusion zones
.. _palm_exclusion_zones:
------------------------------------------------------------------------------
Palm exclusion zones
------------------------------------------------------------------------------
libinput enables palm detection on the left, right and top edges of the
touchpad. Two exclusion zones are defined on the left and right edge of the
@ -74,7 +93,7 @@ avoids palm detection on such touch sequences.
Each side edge exclusion zone is divided into a top part and a bottom part.
A touch starting in the top part of the exclusion zone does not trigger a
tap (see @ref tapping).
tap (see :ref:`tapping`).
In the diagram below, the exclusion zones are painted red.
Touch 'A' starts inside the exclusion zone and moves
@ -91,10 +110,14 @@ will generate a button event for this touch.
@image html palm-detection.svg
@section trackpoint-disabling Palm detection during trackpoint use
.. _trackpoint-disabling:
------------------------------------------------------------------------------
Palm detection during trackpoint use
------------------------------------------------------------------------------
If a device provides a
[trackpoint](http://en.wikipedia.org/wiki/Pointing_stick), it is
`trackpoint <http://en.wikipedia.org/wiki/Pointing_stick>`_, it is
usually located above the touchpad. This increases the likelihood of
accidental touches whenever the trackpoint is used.
@ -103,36 +126,45 @@ certain timeout until after trackpoint activity stops. Touches generated
during this timeout will not move the pointer, and touches started during
this timeout will likewise not move the pointer (allowing for a user to rest
the palm on the touchpad while using the trackstick).
If the touchpad is disabled, the @ref t440_support "top software buttons"
If the touchpad is disabled, the :ref:`top software buttons <t440_support>`
remain enabled.
@section disable-while-typing Disable-while-typing
.. _disable-while-typing:
------------------------------------------------------------------------------
Disable-while-typing
------------------------------------------------------------------------------
libinput automatically disables the touchpad for a timeout after a key
press, a feature traditionally referred to as "disable while typing" and
previously available through the
[syndaemon(1)](http://linux.die.net/man/1/syndaemon) command. libinput does
`syndaemon(1) <http://linux.die.net/man/1/syndaemon>`_ command. libinput does
not require an external command and the feature is currently enabled for all
touchpads but will be reduced in the future to only apply to touchpads where
finger width or pressure data is unreliable.
Notable behaviors of libinput's disable-while-typing feature:
- Two different timeouts are used, after a single key press the timeout is
short to ensure responsiveness. After multiple key events, the timeout is
longer to avoid accidental pointer manipulation while typing.
- Some keys do not trigger the timeout, specifically some modifier keys
- Some keys do not trigger the timeout, specifically some modifier keys
(Ctrl, Alt, Shift, and Fn). Actions such as Ctrl + click thus stay
responsive.
- Touches started while typing do not control the cursor even after typing
has stopped, it is thus possible to rest the palm on the touchpad while
typing.
- Physical buttons work even while the touchpad is disabled. This includes
@ref t440_support "software-emulated buttons".
:ref:`software-emulated buttons <t440_support>`.
Disable-while-typing can be enabled and disabled by calling
libinput_device_config_dwt_set_enabled().
**libinput_device_config_dwt_set_enabled()**.
@section stylus-touch-arbitration Stylus-touch arbitration
.. _stylus-touch-arbitration:
------------------------------------------------------------------------------
Stylus-touch arbitration
------------------------------------------------------------------------------
A special case of palm detection is touch arbitration on devices that
support styli. When interacting with a stylus on the screen, parts of the
@ -140,22 +172,26 @@ hand may touch the surface and trigger touches. As the user is currently
interacting with the stylus, these touches would interfer with the correct
working of the stylus.
libinput employs a method similar to @ref disable-while-typing to detect
libinput employs a method similar to :ref:`disable-while-typing` to detect
these touches and disables the touchpad accordingly.
@section thumb-detection Thumb detection
.. _thumb-detection:
------------------------------------------------------------------------------
Thumb detection
------------------------------------------------------------------------------
Many users rest their thumb on the touchpad while using the index finger to
move the finger around. For clicks, often the thumb is used rather than the
finger. The thumb should otherwise be ignored as a touch, i.e. it should not
count towards @ref clickfinger and it should not cause a single-finger
movement to trigger @ref twofinger_scrolling.
count towards :ref:`clickfinger` and it should not cause a single-finger
movement to trigger :ref:`twofinger_scrolling`.
libinput uses two triggers for thumb detection: pressure and
location. A touch exceeding a pressure threshold is considered a thumb if it
is within the thumb detection zone.
@note "Pressure" on touchpads is synonymous with "contact area", a large touch
.. note:: "Pressure" on touchpads is synonymous with "contact area", a large touch
surface area has a higher pressure and thus hints at a thumb or palm
touching the surface.
@ -170,5 +206,3 @@ The picture above shows the two detection areas. In the larger (light red)
area, a touch is labelled as thumb when it exceeds a device-specific
pressure threshold. In the lower (dark red) area, a touch is labelled as
thumb if it remains in that area for a time without moving outside.
*/

103
doc/pointer-acceleration.dox → doc/user/pointer-acceleration.rst
View file

@ -1,25 +1,36 @@
/**
@page pointer-acceleration Pointer acceleration
.. _pointer-acceleration:
==============================================================================
Pointer acceleration
==============================================================================
libinput uses device-specific pointer acceleration methods, with the default
being the @ref ptraccel-linear. The methods share common properties, such as
@ref ptraccel-velocity.
being the :ref:`ptraccel-linear`. The methods share common properties, such as
:ref:`ptraccel-velocity`.
This page explains the high-level concepts used in the code. It aims to
provide an overview for developers and is not necessarily useful for
users.
@section ptraccel-profiles Pointer acceleration profiles
.. _ptraccel-profiles:
------------------------------------------------------------------------------
Pointer acceleration profiles
------------------------------------------------------------------------------
The profile decides the general method of pointer acceleration.
libinput currently supports two profiles: "adaptive" and "flat". The adaptive
profile is the default profile for all devices and takes the current speed
of the device into account when deciding on acceleration. The flat profile
is simply a constant factor applied to all device deltas, regardless of the
speed of motion (see @ref ptraccel-profile-flat). Most of this document
speed of motion (see :ref:`ptraccel-profile-flat`). Most of this document
describes the adaptive pointer acceleration.
@section ptraccel-velocity Velocity calculation
.. _ptraccel-velocity:
------------------------------------------------------------------------------
Velocity calculation
------------------------------------------------------------------------------
The device's speed of movement is measured across multiple input events
through so-called "trackers". Each event prepends a the tracker item, each
@ -42,7 +53,11 @@ the last 5 events are used for velocity calculation.
The velocity is then used to calculate the acceleration factor
@section ptraccel-factor Acceleration factor
.. _ptraccel-factor:
------------------------------------------------------------------------------
Acceleration factor
------------------------------------------------------------------------------
The acceleration factor is the final outcome of the pointer acceleration
calculations. It is a unitless factor that is applied to the current delta,
@ -59,7 +74,11 @@ moves. This is acceleration and allows a user to cross the screen quickly
but effectively skips pixels. libinput's current maximum acceleration factor
is 3.5.
@section ptraccel-linear Linear pointer acceleration
.. _ptraccel-linear:
------------------------------------------------------------------------------
Linear pointer acceleration
------------------------------------------------------------------------------
The linear pointer acceleration method is the default for most pointer
devices. It provides deceleration at very slow movements, a 1:1 mapping for
@ -67,9 +86,12 @@ regular movements and a linear increase to the maximum acceleration factor
for fast movements.
Linear pointer acceleration applies to devices with above 1000dpi resolution
and after @ref motion_normalization is applied.
and after :ref:`motion_normalization` is applied.
@image html ptraccel-linear.svg "Linear pointer acceleration"
.. figure:: ptraccel-linear.svg
:align: center
Linear pointer acceleration"
The image above shows the linear pointer acceleration settings at various
speeds. The line for 0.0 is the default acceleration curve, speed settings
@ -80,41 +102,59 @@ maximum acceleration is reached and the maximum acceleration factor.
Extremely low speed settings provide no acceleration and additionally
decelerate all movement by a constant factor.
@section ptraccel-low-dpi Pointer acceleration for low-dpi devices
.. _ptraccel-low-dpi:
------------------------------------------------------------------------------
Pointer acceleration for low-dpi devices
------------------------------------------------------------------------------
Low-dpi devices are those with a physical resolution of less than 1000 dots
per inch (dpi). The pointer acceleration is adjusted to provide roughly the
same feel for all devices at normal to high speeds. At slow speeds, the
pointer acceleration works on device-units rather than normalized
coordinates (see @ref motion_normalization).
coordinates (see :ref:`motion_normalization`).
@image html ptraccel-low-dpi.svg "Pointer acceleration for low-dpi devices"
.. figure:: ptraccel-low-dpi.svg
:align: center
Pointer acceleration for low-dpi devices"
The image above shows the default pointer acceleration curve for a speed of
0.0 at different DPI settings. A device with low DPI has the acceleration
applied sooner and with a stronger acceleration factor.
@section ptraccel-touchpad Pointer acceleration on touchpads
.. _ptraccel-touchpad:
Touchpad pointer acceleration uses the same approach as the @ref
ptraccel-linear profile, with a constant deceleration factor applied. The
------------------------------------------------------------------------------
Pointer acceleration on touchpads
------------------------------------------------------------------------------
Touchpad pointer acceleration uses the same approach as the
:ref:`ptraccel-linear` profile, with a constant deceleration factor applied. The
user expectation of how much a pointer should move in response to finger
movement is different to that of a mouse device, hence the constant
deceleration factor.
@image html ptraccel-touchpad.svg "Pointer acceleration curve for touchpads"
.. figure:: ptraccel-touchpad.svg
:align: center
Pointer acceleration curve for touchpads"
The image above shows the touchpad acceleration profile in comparison to the
@ref ptraccel-linear. The shape of the curve is identical but vertically squashed.
:ref:`ptraccel-linear`. The shape of the curve is identical but vertically squashed.
@section ptraccel-trackpoint Pointer acceleration on trackpoints
.. _ptraccel-trackpoint:
------------------------------------------------------------------------------
Pointer acceleration on trackpoints
------------------------------------------------------------------------------
The main difference between trackpoint hardware and mice or touchpads is
that trackpoint speed is a function of pressure rather than moving speed.
But trackpoint hardware is quite varied in how it reacts to user pressure
and unlike other devices it cannot easily be normalized for physical
properties. Measuring pressure objectively across a variety of hardware is
nontrivial. See @ref trackpoints for more details.
nontrivial. See :ref:`trackpoints` for more details.
The deltas for trackpoints are converted units/ms but there is no common
physical reference point for a unit. Thus, the same pressure on different
@ -125,25 +165,34 @@ higher sensitivity results in higher deltas, thus changing the definition of
what is a unit again.
libinput attempts to normalize unit data to the best of its abilities, see
@ref trackpoint_multiplier. Beyond this, it is not possible to have
:ref:`trackpoint_multiplier`. Beyond this, it is not possible to have
consistent behavior across different touchpad devices.
@image html ptraccel-trackpoint.svg "Pointer acceleration curves for trackpoints"
.. figure:: ptraccel-trackpoint.svg
:align: center
Pointer acceleration curves for trackpoints"
The image above shows the trackpoint acceleration profile for the speed in
units/ms.
@section ptraccel-profile-flat The flat pointer acceleration profile
.. _ptraccel-profile-flat:
------------------------------------------------------------------------------
The flat pointer acceleration profile
------------------------------------------------------------------------------
In a flat profile, the acceleration factor is constant regardless of the
velocity of the pointer and each delta (dx, dy) results in an accelerated delta
(dx * factor, dy * factor). This provides 1:1 movement between the device
and the pointer on-screen.
@section ptraccel-tablet Pointer acceleration on tablets
.. _ptraccel-tablet:
------------------------------------------------------------------------------
Pointer acceleration on tablets
------------------------------------------------------------------------------
Pointer acceleration for relative motion on tablet devices is a flat
acceleration, with the speed setting slowing down or speeding up the pointer
motion by a constant factor. Tablets do not allow for switchable profiles.
*/

345
doc/user/reporting-bugs.rst Normal file
View file

@ -0,0 +1,345 @@
.. _reporting_bugs:
==============================================================================
Reporting bugs
==============================================================================
A new bug can be filed here:
https://gitlab.freedesktop.org/libinput/libinput/issues/new
.. note:: libinput has lots of users but very few developers. It is in your own
interested to follow these steps precisely to ensure your bug can be
dealt with efficiently.
When reporting bugs against libinput, please follow the instructions below
and provide the required data. You will need:
- a reliable :ref:`reproducer <reporting_bugs_reproducer>` for the bug
- an :ref:`evemu recording <evemu>` of the device while the bug is reproduced
- device-specific information, see
- :ref:`reporting_bugs_touchpad`
- :ref:`reporting_bugs_mouse`
- :ref:`reporting_bugs_keyboard`
- :ref:`reporting_bugs_trackpoint`
- :ref:`reporting_bugs_other`
- the :ref:`libinput version <reporting_bugs_version>` you are on.
- the :ref:`configuration options <reporting_bugs_options>` you have set
- a `gitlab account <https://gitlab.freedesktop.org/users/sign_in>`_
Stay technical, on-topic, and keep the description concise.
.. _reporting_bugs_version:
------------------------------------------------------------------------------
Obtaining the libinput version
------------------------------------------------------------------------------
If your libinput version is older than the current stable branch, you will
get asked to try the latest version. If you run a distribution-provided
libinput, use the package manager to get the **full** package name and
version of libinput, e.g.
- ``rpm -q libinput``
- ``dpkg -s libinput10``
If you run a self-compiled version of libinput provide the git commit you
have built or the tarball name.
As a last resort, use ``libinput --version``
.. _reporting_bugs_reproducer:
------------------------------------------------------------------------------
Reproducing bugs
------------------------------------------------------------------------------
Try to identify the bug by reproducing it reliably. Bugs without a
reliable reproducer will have lowest priority. The more specific a bug
description and reproducer is, the easier it is to fix.
Try to replicate the series of events that lead to the bug being triggered.
Narrow it down until you have a reliable sequence that can trigger the bug.
For the vast majority of bugs you should not take longer than 5 seconds or
three interactions (clicks, touches, taps, ...) with the device to
reproduce. If it takes longer than that, you can narrow it down further.
Once you can reproduce it, use the :ref:`libinput-debug-events` helper tool.
The output is textual and can help identify whether the bug is in libinput
at all. Note that any configuration options you have set must be specified
on the commandline, see the :ref:`libinput-debug-events`
"libinput-debug-events" man page. Use the ``--verbose`` flag to get more
information about how libinput processes events.
If the bug cannot be reproduced with the :ref:`libinput-debug-events` helper,
even with the correct configuration options set, it is likely not a bug in
libinput.
.. _reporting_bugs_options:
------------------------------------------------------------------------------
libinput configuration settings
------------------------------------------------------------------------------
libinput has a number of device-specific default configuration settings that
may differ from the ones your desktop environment picks by default. You may
have changed some options in a settings panel or in an the xorg.conf snippet
yourself.
You must provide these options in the bug report, otherwise a developer
reproducing the issue may not be able to do so.
If you are on X11, the current settings can be can be obtained with
``xinput list-props "your device name"``. Use ``xinput list`` to
obtain the device name.
If you are on Wayland, provide a manual summary of the options you have
changed from the default (e.g. "I enabled tap-to-click").
.. _reporting_bugs_touchpad:
------------------------------------------------------------------------------
Reporting touchpad bugs
------------------------------------------------------------------------------
When you file a bug, please attach the following information:
- a virtual description of your input device, see :ref:`evemu`. This is the
most important piece of information, do not forget it!
- the output from udevadm info, see :ref:`udev_info`.
- the vendor model number of your laptop (e.g. "Lenovo Thinkpad T440s")
- and the content of ``/sys/class/dmi/id/modalias``.
- run the ``touchpad-edge-detectior`` tool (provided by libevdev) and verify
that the ranges and sizes it prints match the touchpad (up to 5mm
difference is ok)
If you are reporting a bug related to button event generation:
- does your touchpad have (separate) physical hardware buttons or is the
whole touchpad clickable?
- Are you using software buttons or clickfinger? See :ref:`clickpad_softbuttons`.
- Do you have :ref:`tapping` enabled?
.. _reporting_bugs_mouse:
------------------------------------------------------------------------------
Reporting mouse bugs
------------------------------------------------------------------------------
When you file a bug, please attach the following information:
- a virtual description of your input device, see :ref:`evemu`. This is the
most important piece of information, do not forget it!
- the vendor model number of the device (e.g. "Logitech M325")
- the output from udevadm info, see :ref:`udev_info`.
If the bug is related to the :ref:`speed of the mouse <motion_normalization_customization>`:
- the resolution of the mouse as specified by the vendor (in DPI)
- the output of the ``mouse-dpi-tool`` (provided by libevdev)
.. _reporting_bugs_keyboard:
------------------------------------------------------------------------------
Reporting keyboard bugs
------------------------------------------------------------------------------
Is your bug related to a keyboard layout? libinput does not handle keyboard
layouts and merely forwards the physical key events. File the bug with your
desktop environment instead (e.g. GNOME, KDE, ...), that's most likely where
the issue is.
When you file a bug, please attach the following information:
- a virtual description of your input device, see :ref:`evemu`. This is the
most important piece of information, do not forget it!
.. _reporting_bugs_trackpoint:
------------------------------------------------------------------------------
Reporting trackpoint bugs
------------------------------------------------------------------------------
When you file a bug, please attach the following information:
- a virtual description of your input device, see :ref:`evemu`. This is the
most important piece of information, do not forget it!
- the vendor model number of the device (e.g. "Logitech M325")
- the output from udevadm info, see :ref:`udev_info`.
- the output of ``libinput measure trackpoint-range``
- the sensitivity of the trackpoint (adjust the event node number as needed): ::
$ cat /sys/class/input/event17/device/device/sensitivity
.. _reporting_bugs_other:
------------------------------------------------------------------------------
All other devices
------------------------------------------------------------------------------
When you file a bug, please attach the following information:
- a virtual description of your input device, see :ref:`evemu`. This is the
most important piece of information, do not forget it!
- the vendor model number of the device (e.g. "Sony Plastation3 controller")
.. _udev_info:
------------------------------------------------------------------------------
udev information for the device
------------------------------------------------------------------------------
In many cases, we require the udev properties assigned to the device to
verify whether device-specific quirks were applied. This can be obtained
with ``udevadm info /sys/class/input/eventX``, with the correct event
node for your device. An example output is below: ::
$ udevadm info /sys/class/input/event4
P: /devices/platform/i8042/serio1/input/input5/event4
N: input/event4
E: DEVNAME=/dev/input/event4
E: DEVPATH=/devices/platform/i8042/serio1/input/input5/event4
E: EVDEV_ABS_00=::41
E: EVDEV_ABS_01=::37
E: EVDEV_ABS_35=::41
E: EVDEV_ABS_36=::37
E: ID_INPUT=1
E: ID_INPUT_HEIGHT_MM=66
E: ID_INPUT_TOUCHPAD=1
E: ID_INPUT_WIDTH_MM=97
E: MAJOR=13
E: MINOR=68
E: SUBSYSTEM=input
E: USEC_INITIALIZED=5463031
.. _evemu:
------------------------------------------------------------------------------
Recording devices with evemu
------------------------------------------------------------------------------
.. note:: Where available, the :ref:`libinput-record` tools should be used instead
of evemu
`evemu-record <https://www.freedesktop.org/wiki/Evemu/>`_ records the
device capabilities together with the event stream from the kernel. On our
side, this allows us to recreate a virtual device identical to your device
and re-play the event sequence, hopefully triggering the same bug.
evemu-record takes a <tt>/dev/input/eventX</tt> event node, but without arguments
it will simply show the list of devices and let you select: ::
$ sudo evemu-record > scroll.evemu
Available devices:
/dev/input/event0: Lid Switch
/dev/input/event1: Sleep Button
/dev/input/event2: Power Button
/dev/input/event3: AT Translated Set 2 keyboard
/dev/input/event4: SynPS/2 Synaptics TouchPad
/dev/input/event5: Video Bus
/dev/input/event6: ELAN Touchscreen
/dev/input/event10: ThinkPad Extra Buttons
/dev/input/event11: HDA Intel HDMI HDMI/DP,pcm=3
/dev/input/event12: HDA Intel HDMI HDMI/DP,pcm=7
/dev/input/event13: HDA Intel HDMI HDMI/DP,pcm=8
/dev/input/event14: HDA Intel PCH Dock Mic
/dev/input/event15: HDA Intel PCH Mic
/dev/input/event16: HDA Intel PCH Dock Headphone
/dev/input/event17: HDA Intel PCH Headphone
/dev/input/event18: Integrated Camera
/dev/input/event19: TPPS/2 IBM TrackPoint
Select the device event number [0-19]:
Select the device that triggers the issue, then reproduce the bug and Ctrl+C
the process. The resulting recording, ("scroll.evemu" in this example) will
contain the sequence required to reproduce the bug. If the bug fails to
reproduce during recording, simply Ctrl+C and restart evemu-record.
Always start the recording from a neutral state, i.e. without any buttons or
keys down, with the position of the device in the neutral position, without
touching the screen/touchpad.
.. note:: The longer the recording, the harder it is to identify the event
sequence triggering the bug. Please keep the event sequence as short
as possible.
To verify that the recording contains the bug, you can replay it on your
device. For example, to replay the sequence recorded in the example above: ::
$ sudo evemu-play /dev/input/event4 < scroll.evemu
If the bug is triggered by replaying on your device, attach the recording to
the bug report.
.. note:: libinput does not affect the evemu recording. libinput and evemu talk
directly to the kernel's device nodes. An evemu recording is not
influenced by the libinput version or whether a libinput context is
currently active.
.. graphviz:: evemu.gv
.. _fixed_bugs:
------------------------------------------------------------------------------
My bug was closed as fixed, what now?
------------------------------------------------------------------------------
libinput's policy on closing bugs is: once the fix for a given bug is on git
master, the bug is considered fixed and the bugzilla entry will be closed
accordingly.
Of course, unless you actually run git master, the bug will continue to
affect you on your local machine. You are most likely running the
distribution's package and you will need to wait until the distribution has
updated its package accordingly.
.. warning:: Do not re-open a bug just because it hasn't trickled down to
your distribution's package version yet.
Whether the bug fix ends up in your distribution depends on a number of
things. Any given bug fix **may** be cherry-picked into the current stable
branch, depending on its severity, impact, and likelyhood to cause
regressions. Once cherry-picked it will land in the next stable branch
release. These are usually a few weeks apart.
.. warning:: Do not re-open a bug because it wasn't picked into a stable branch
release or because your distribution didn't update to the latest stable
branch release.
Stable branches are usually discontinued when the next release comes out.
Your distribution may pick a patch up immediately and ship the fix
even before the next stable branch update is released. For example, Fedora
does this frequently.
.. note:: If a bug needs to be fixed urgently, file a bug in your
distribution's bug tracker.
Patches on git master will end up in the next libinput release. Once your
distribution updates to that release, your local libinput version will
contain the fix.
.. warning:: Do not re-open a bug because your distribution didn't update to
the release.
You can always run libinput from git master (see :ref:`building_libinput`).
Even while in development, libinput is very stable so this option isn't as
scary as it may sounds.
.. _reporting_bugs_reopen:
..............................................................................
When is it ok to re-open a fixed bug?
..............................................................................
Any time the bug was considered fixed but it turns out that the fix is
insufficient and/or causes a regression.
However, if the regression is in behavior unrelated to the fix itself it is
usually better to file a new bug to reduce the noise. For example, if a fix
to improve tapping breaks two-finger scrolling behavior, you should file a
new bug but reference the original bug.

80
doc/scrolling.dox → doc/user/scrolling.rst
View file

@ -1,41 +1,56 @@
/**
@page scrolling Scrolling
.. _scrolling:
libinput supports three different types of scrolling methods: @ref
twofinger_scrolling, @ref edge_scrolling and @ref button_scrolling. Some
==============================================================================
Scrolling
==============================================================================
libinput supports three different types of scrolling methods:
:ref:`twofinger_scrolling`, @ref edge_scrolling and @ref button_scrolling. Some
devices support multiple methods, though only one can be enabled at a time.
As a general overview:
- touchpad devices with physical buttons below the touchpad support edge and
two-finger scrolling
- touchpad devices without physical buttons (@ref clickpad_softbuttons
- touchpad devices without physical buttons (:ref:`clickpad_softbuttons`
"clickpads") support two-finger scrolling only
- pointing sticks provide on-button scrolling by default
- mice and other pointing devices support on-button scrolling but it is not
enabled by default
A device may differ from the above based on its capabilities. See
libinput_device_config_scroll_set_method() for documentation on how to
switch methods and libinput_device_config_scroll_get_methods() for
**libinput_device_config_scroll_set_method()** for documentation on how to
switch methods and **libinput_device_config_scroll_get_methods()** for
documentation on how to query a device for available scroll methods.
@section horizontal_scrolling Horizontal scrolling
.. _horizontal_scrolling:
------------------------------------------------------------------------------
Horizontal scrolling
------------------------------------------------------------------------------
Scroll movements provide vertical and horizontal directions, each
scroll event contains both directions where applicable, see
libinput_event_pointer_get_axis_value(). libinput does not provide separate
**libinput_event_pointer_get_axis_value()**. libinput does not provide separate
toggles to enable or disable horizontal scrolling. Instead, horizontal
scrolling is always enabled. This is intentional, libinput does not have
enough context to know when horizontal scrolling is appropriate for a given
widget. The task of filtering horizontal movements is up to the caller.
@section twofinger_scrolling Two-finger scrolling
.. _twofinger_scrolling:
------------------------------------------------------------------------------
Two-finger scrolling
------------------------------------------------------------------------------
The default on two-finger capable touchpads (almost all modern touchpads are
capable of detecting two fingers). Scrolling is triggered by two fingers
being placed on the surface of the touchpad, then moving those fingers
vertically or horizontally.
@image html twofinger-scrolling.svg "Vertical and horizontal two-finger scrolling"
.. figure:: twofinger-scrolling.svg
:align: center
Vertical and horizontal two-finger scrolling"
For scrolling to trigger, a built-in distance threshold has to be met but once
engaged any movement will scroll. In other words, to start scrolling a
@ -51,43 +66,61 @@ position of each finger. In addition, that bounding box usually suffers from
a low resolution, causing jumpy movement during two-finger scrolling.
libinput does not provide two-finger scrolling on those touchpads.
@section edge_scrolling Edge scrolling
.. _edge_scrolling:
------------------------------------------------------------------------------
Edge scrolling
------------------------------------------------------------------------------
On some touchpads, edge scrolling is available, triggered by moving a single
finger along the right edge (vertical scroll) or bottom edge (horizontal
scroll).
@image html edge-scrolling.svg "Vertical and horizontal edge scrolling"
.. figure:: edge-scrolling.svg
:align: center
Vertical and horizontal edge scrolling"
Due to the layout of the edges, diagonal scrolling is not possible. The
behavior of edge scrolling using both edges at the same time is undefined.
Edge scrolling overlaps with @ref clickpad_softbuttons. A physical click on
Edge scrolling overlaps with :ref:`clickpad_softbuttons`. A physical click on
a clickpad ends scrolling.
@section button_scrolling On-Button scrolling
.. _button_scrolling:
------------------------------------------------------------------------------
On-Button scrolling
------------------------------------------------------------------------------
On-button scrolling converts the motion of a device into scroll events while
a designated button is held down. For example, Lenovo devices provide a
[pointing stick](http://en.wikipedia.org/wiki/Pointing_stick) that emulates
`pointing stick <http://en.wikipedia.org/wiki/Pointing_stick>`_ that emulates
scroll events when the trackstick's middle mouse button is held down.
@note On-button scrolling is enabled by default for pointing sticks. This
.. note:: On-button scrolling is enabled by default for pointing sticks. This
prevents middle-button dragging; all motion events while the middle
button is down are converted to scroll events.
@image html button-scrolling.svg "Button scrolling"
.. figure:: button-scrolling.svg
:align: center
Button scrolling"
The button may be changed with
libinput_device_config_scroll_set_button() but must be on the same device as
**libinput_device_config_scroll_set_button()** but must be on the same device as
the motion events. Cross-device scrolling is not supported but
for one exception: libinput's @ref t440_support enables the use of the middle
for one exception: libinput's :ref:`t440_support` enables the use of the middle
button for button scrolling (even when the touchpad is disabled).
@section scroll_sources Scroll sources
.. _scroll_sources:
------------------------------------------------------------------------------
Scroll sources
------------------------------------------------------------------------------
libinput provides a pointer axis *source* for each scroll event. The
source can be obtained with the libinput_event_pointer_get_axis_source()
source can be obtained with the **libinput_event_pointer_get_axis_source()**
function and is one of **wheel**, **finger**, or **continuous**. The source
information lets a caller decide when to implement kinetic scrolling.
Usually, a caller will process events of source wheel as they come in.
@ -99,8 +132,7 @@ information is thus enough to provide kinetic scrolling on a per-widget
basis. A caller should cancel kinetic scrolling when the pointer leaves the
current widget or when a key is pressed.
See the libinput_event_pointer_get_axis_source() for details on the
See the **libinput_event_pointer_get_axis_source()** for details on the
behavior of each scroll source.
See also http://who-t.blogspot.com.au/2015/03/libinput-scroll-sources.html
*/

48
doc/seats.dox → doc/user/seats.rst
View file

@ -1,5 +1,8 @@
/**
@page seats Seats
.. _seats:
==============================================================================
Seats
==============================================================================
Each device in libinput is assigned to one seat.
A seat has two identifiers, the physical name and the logical name. The
@ -10,11 +13,15 @@ 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
.. _seats_overview:
------------------------------------------------------------------------------
Overview
------------------------------------------------------------------------------
Below is an illustration of how physical seats and logical seats interact:
@dotfile seats-sketch.gv
.. graphviz:: seats-sketch.gv
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
@ -22,15 +29,19 @@ 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
**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
.. graphviz:: 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.
Thus, devices "Foo" and "Bar" both reference the same struct
**libinput_seat**, all other devices reference their own respective seats.
@section seats_and_features The effect of seat assignment
.. _seats_and_features:
------------------------------------------------------------------------------
The effect of seat assignment
------------------------------------------------------------------------------
A logical set is interpreted as a group of devices that usually belong to a
single user that interacts with a computer. Thus, the devices are
@ -48,26 +59,27 @@ semantically related. This means for devices within the same logical seat:
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().
**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
buttons (see :ref:`t440_support`) if both trackstick and touchpad are assigned
to the same logical seat.
@section changing_seats Changing seats
.. _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
**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.
*/

0
doc/svg/button-debouncing-wave-diagram.svg → doc/user/svg/button-debouncing-wave-diagram.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 105 KiB

After

Width:  |  Height:  |  Size: 105 KiB

0
doc/svg/button-scrolling.svg → doc/user/svg/button-scrolling.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 17 KiB

After

Width:  |  Height:  |  Size: 17 KiB

0
doc/svg/clickfinger-distance.svg → doc/user/svg/clickfinger-distance.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 5.9 KiB

After

Width:  |  Height:  |  Size: 5.9 KiB

0
doc/svg/clickfinger.svg → doc/user/svg/clickfinger.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 16 KiB

0
doc/svg/edge-scrolling.svg → doc/user/svg/edge-scrolling.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7 KiB

After

Width:  |  Height:  |  Size: 7 KiB

0
doc/svg/gesture-2fg-ambiguity.svg → doc/user/svg/gesture-2fg-ambiguity.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 28 KiB

After

Width:  |  Height:  |  Size: 28 KiB

0
doc/svg/palm-detection.svg → doc/user/svg/palm-detection.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.8 KiB

After

Width:  |  Height:  |  Size: 8.8 KiB

0
doc/svg/pinch-gestures-softbuttons.svg → doc/user/svg/pinch-gestures-softbuttons.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 16 KiB

0
doc/svg/pinch-gestures.svg → doc/user/svg/pinch-gestures.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 34 KiB

After

Width:  |  Height:  |  Size: 34 KiB

3
doc/svg/ptraccel-linear.svg → doc/user/svg/ptraccel-linear.svg
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<svg
<svg
width="600" height="480"
viewBox="0 0 600 480"
xmlns="http://www.w3.org/2000/svg"
@ -516,4 +516,3 @@
</g>
</g>
</svg>
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 45 KiB

After

Width:  |  Height:  |  Size: 45 KiB

3
doc/svg/ptraccel-low-dpi.svg → doc/user/svg/ptraccel-low-dpi.svg
View file

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg
<svg
width="600" height="480"
viewBox="0 0 600 480"
xmlns="http://www.w3.org/2000/svg"
@ -3745,4 +3745,3 @@
</g>
</g>
</svg>
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 377 KiB

After

Width:  |  Height:  |  Size: 377 KiB

3
doc/svg/ptraccel-touchpad.svg → doc/user/svg/ptraccel-touchpad.svg
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<svg
<svg
width="600" height="480"
viewBox="0 0 600 480"
xmlns="http://www.w3.org/2000/svg"
@ -577,4 +577,3 @@
</g>
</g>
</svg>
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 51 KiB

After

Width:  |  Height:  |  Size: 51 KiB

3
doc/svg/ptraccel-trackpoint.svg → doc/user/svg/ptraccel-trackpoint.svg
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<svg
<svg
width="600" height="480"
viewBox="0 0 600 480"
xmlns="http://www.w3.org/2000/svg"
@ -251,4 +251,3 @@
</g>
</g>
</svg>
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 19 KiB

After

Width:  |  Height:  |  Size: 19 KiB

0
doc/svg/software-buttons.svg → doc/user/svg/software-buttons.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9.3 KiB

After

Width:  |  Height:  |  Size: 9.3 KiB

0
doc/svg/swipe-gestures.svg → doc/user/svg/swipe-gestures.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 22 KiB

After

Width:  |  Height:  |  Size: 22 KiB

0
doc/svg/tablet-axes.svg → doc/user/svg/tablet-axes.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 26 KiB

After

Width:  |  Height:  |  Size: 26 KiB

0
doc/svg/tablet-cintiq24hd-modes.svg → doc/user/svg/tablet-cintiq24hd-modes.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 21 KiB

After

Width:  |  Height:  |  Size: 21 KiB

0
doc/svg/tablet-interfaces.svg → doc/user/svg/tablet-interfaces.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 15 KiB

After

Width:  |  Height:  |  Size: 15 KiB

0
doc/svg/tablet-intuos-modes.svg → doc/user/svg/tablet-intuos-modes.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 15 KiB

After

Width:  |  Height:  |  Size: 15 KiB

0
doc/svg/tablet-left-handed.svg → doc/user/svg/tablet-left-handed.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 22 KiB

After

Width:  |  Height:  |  Size: 22 KiB

0
doc/svg/tablet-out-of-bounds.svg → doc/user/svg/tablet-out-of-bounds.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

0
doc/svg/tablet.svg → doc/user/svg/tablet.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.8 KiB

After

Width:  |  Height:  |  Size: 8.8 KiB

0
doc/svg/tap-n-drag.svg → doc/user/svg/tap-n-drag.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 46 KiB

0
doc/svg/thumb-detection.svg → doc/user/svg/thumb-detection.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.3 KiB

After

Width:  |  Height:  |  Size: 6.3 KiB

0
doc/svg/top-software-buttons.svg → doc/user/svg/top-software-buttons.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 13 KiB

0
doc/svg/touchscreen-gestures.svg → doc/user/svg/touchscreen-gestures.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 28 KiB

After

Width:  |  Height:  |  Size: 28 KiB

0
doc/svg/trackpoint-delta-illustration.svg → doc/user/svg/trackpoint-delta-illustration.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.9 KiB

After

Width:  |  Height:  |  Size: 8.9 KiB

0
doc/svg/twofinger-scrolling.svg → doc/user/svg/twofinger-scrolling.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

31
doc/switches.dox → doc/user/switches.rst
View file

@ -1,11 +1,14 @@
/**
@page switches Switches
.. _switches:
==============================================================================
Switches
==============================================================================
libinput supports the lid and tablet-mode switches. Unlike button events
that come in press and release pairs, switches are usually toggled once and
left at the setting for an extended period of time.
Only some switches are handled by libinput, see @ref libinput_switch for a
Only some switches are handled by libinput, see **libinput_switch** for a
list of supported switches. Switch events are exposed to the caller, but
libinput may handle some switch events internally and enable or disable
specific features based on a switch state.
@ -13,11 +16,15 @@ specific features based on a switch state.
The order of switch events is guaranteed to be correct, i.e., a switch will
never send consecutive switch on, or switch off, events.
@section switches_lid Lid switch handling
.. _switches_lid:
------------------------------------------------------------------------------
Lid switch handling
------------------------------------------------------------------------------
Where available, libinput listens to devices providing a lid switch.
The evdev event code `EV_SW` `SW_LID` is provided as @ref
LIBINPUT_SWITCH_LID. If devices with a lid switch have a touchpad device,
The evdev event code ``EV_SW`` ``SW_LID`` is provided as
**LIBINPUT_SWITCH_LID**. If devices with a lid switch have a touchpad device,
the device is disabled while the lid is logically closed. This is to avoid
ghost touches that can be caused by interference with touchpads and the
closed lid. The touchpad is automatically re-enabled whenever the lid is
@ -31,20 +38,22 @@ state and the lid state may report as closed even when the lid is physicall
open. libinput employs some heuristics to detect user input (specificially
typing) to re-enable the touchpad on those devices.
@section switches_tablet_mode Tablet mode switch handling
.. _switches_tablet_mode:
------------------------------------------------------------------------------
Tablet mode switch handling
------------------------------------------------------------------------------
Where available, libinput listens to devices providing a tablet mode switch.
This switch is usually triggered on devices that can switch between a normal
laptop layout and a tablet-like layout. One example for such a device is the
Lenovo Yoga.
The event sent by the kernel is `EV_SW` `SW_TABLET_MODE` and is provided as
@ref LIBINPUT_SWITCH_TABLET_MODE. When the device switches to tablet mode,
The event sent by the kernel is ``EV_SW`` ``SW_TABLET_MODE`` and is provided as
**LIBINPUT_SWITCH_TABLET_MODE**. When the device switches to tablet mode,
the touchpad and internal keyboard are disabled. If a trackpoint exists,
it is disabled too. The input devices are automatically re-enabled whenever
tablet mode is disengaged.
This handling of tablet mode switches is transparent to the user, no
notifications are sent and the device appears as enabled at all times.
*/

67
doc/t440-support.dox → doc/user/t440-support.rst
View file

@ -1,29 +1,43 @@
/**
@page t440_support Lenovo *40 series touchpad support
.. _t440_support:
The Lenovo *40 series emulates trackstick buttons on the top part of the
==============================================================================
Lenovo \*40 series touchpad support
==============================================================================
The Lenovo \*40 series emulates trackstick buttons on the top part of the
touchpads.
@section t440_support_overview Overview
.. _t440_support_overview:
The Lenovo *40 series introduced a new type of touchpad. Previously, all
------------------------------------------------------------------------------
Overview
------------------------------------------------------------------------------
The Lenovo \*40 series introduced a new type of touchpad. Previously, all
laptops had a separate set of physical buttons for the
[trackstick](http://en.wikipedia.org/wiki/Pointing_stick). This
`trackstick <http://en.wikipedia.org/wiki/Pointing_stick>`_. This
series removed these buttons, relying on a software emulation of the top
section of the touchpad. This is visually marked on the trackpad itself,
and clicks can be triggered by pressing the touchpad down with a finger in
the respective area:
@image html top-software-buttons.svg "Left, right and middle-button click with top software button areas"
.. figure:: top-software-buttons.svg
:align: center
Left, right and middle-button click with top software button areas"
This page only covers the top software buttons, the bottom button behavior
is covered in @ref clickpad_softbuttons "Clickpad software buttons".
is covered in :ref:`Clickpad software buttons <clickpad_softbuttons>`.
Clickpads with a top button area are marked with the
[INPUT_PROP_TOPBUTTONPAD](https://www.kernel.org/doc/Documentation/input/event-codes.txt)
`INPUT_PROP_TOPBUTTONPAD <https://www.kernel.org/doc/Documentation/input/event-codes.txt>`_
property.
@section t440_support_btn_size Size of the buttons
.. _t440_support_btn_size:
------------------------------------------------------------------------------
Size of the buttons
------------------------------------------------------------------------------
The size of the buttons matches the visual markings on this touchpad.
The width of the left and right buttons is approximately 42% of the
@ -35,16 +49,23 @@ 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).
@section t440_support_btn_behavior Button behavior
.. _t440_support_btn_behavior:
------------------------------------------------------------------------------
Button behavior
------------------------------------------------------------------------------
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.
@dot
digraph top_button_routing
{
.. graphviz::
digraph top_button_routing
{
rankdir="LR";
node [shape="box";]
@ -74,8 +95,8 @@ digraph top_button_routing
libinput_tp -> events_tp [arrowhead="none"]
libinput_ts -> events_topbutton [color="red4"]
}
@enddot
}
The top button areas work even if the touchpad is disabled but will be
@ -85,21 +106,23 @@ 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.
@section t440_support_identification Kernel support
.. _t440_support_identification:
------------------------------------------------------------------------------
Kernel support
------------------------------------------------------------------------------
The firmware on the first generation of touchpads providing top software
buttons is buggy and announces wrong ranges.
[Kernel patches](https://lkml.org/lkml/2014/3/7/722) are required;
`Kernel patches <https://lkml.org/lkml/2014/3/7/722>`_ are required;
these fixes are available in kernels 3.14.1, 3.15 and later but each
touchpad needs a separate fix.
The October 2014 refresh of these laptops do not have this firmware bug
anymore and should work without per-device patches, though
[this kernel commit](http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=02e07492cdfae9c86e3bd21c0beec88dbcc1e9e8)
`this kernel commit <http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=02e07492cdfae9c86e3bd21c0beec88dbcc1e9e8>`_
is required.
For a complete list of supported touchpads check
[the kernel source](http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/drivers/input/mouse/synaptics.c)
`the kernel source <http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/drivers/input/mouse/synaptics.c>`_
(search for "topbuttonpad_pnp_ids").
*/

220
doc/tablet-support.dox → doc/user/tablet-support.rst
View file

@ -1,43 +1,60 @@
/**
@page tablet-support Tablet support
.. _tablet-support:
==============================================================================
Tablet support
==============================================================================
This page provides details about the graphics tablet
support in libinput. Note that the term "tablet" in libinput refers to
graphics tablets only (e.g. Wacom Intuos), not to tablet devices like the
Apple iPad.
@image html tablet.svg "Illustration of a graphics tablet"
.. figure:: tablet.svg
:align: center
@section tablet-tools Pad buttons vs. tablet tools
Illustration of a graphics tablet"
.. _tablet-tools:
------------------------------------------------------------------------------
Pad buttons vs. tablet tools
------------------------------------------------------------------------------
Most tablets provide two types of devices. The physical tablet often
provides a number of buttons and a touch ring or strip. Interaction on the
drawing surface of the tablet requires a tool, usually in the shape of a
stylus. The libinput interface exposed by devices with the @ref
LIBINPUT_DEVICE_CAP_TABLET_TOOL capability applies only to events generated
stylus. The libinput interface exposed by devices with the
**LIBINPUT_DEVICE_CAP_TABLET_TOOL** capability applies only to events generated
by tools.
Buttons, rings or strips on the physical tablet hardware (the "pad") are
exposed by devices with the @ref LIBINPUT_DEVICE_CAP_TABLET_PAD capability.
exposed by devices with the **LIBINPUT_DEVICE_CAP_TABLET_PAD** capability.
Pad events do not require a tool to be in proximity. Note that both
capabilities may exist on the same device though usually they are split
across multiple kernel devices.
@image html tablet-interfaces.svg "Difference between Pad and Tool buttons"
.. figure:: tablet-interfaces.svg
:align: center
Difference between Pad and Tool buttons"
Touch events on the tablet integrated into a screen itself are exposed
through the @ref LIBINPUT_DEVICE_CAP_TOUCH capability. Touch events on a
standalone tablet are exposed through the @ref LIBINPUT_DEVICE_CAP_POINTER
through the **LIBINPUT_DEVICE_CAP_TOUCH** capability. Touch events on a
standalone tablet are exposed through the **LIBINPUT_DEVICE_CAP_POINTER**
capability. In both cases, the kernel usually provides a separate event
node for the touch device, resulting in a separate libinput device.
See libinput_device_get_device_group() for information on how to associate
See **libinput_device_get_device_group()** for information on how to associate
the touch part with other devices exposed by the same physical hardware.
@section tablet-tip Tool tip events vs. tool button events
.. _tablet-tip:
------------------------------------------------------------------------------
Tool tip events vs. tool button events
------------------------------------------------------------------------------
The primary use of a tablet tool is to draw on the surface of the tablet.
When the tool tip comes into contact with the surface, libinput sends an
event of type @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, and again when the tip
event of type **LIBINPUT_EVENT_TABLET_TOOL_TIP**, and again when the tip
ceases contact with the surface.
Tablet tools may send button events; these are exclusively for extra buttons
@ -51,8 +68,8 @@ tools are capable of detecting 1 gram of pressure.
libinput uses a device-specific pressure threshold to determine when the tip
is considered logically down. As a result, libinput may send a nonzero
pressure value while the tip is logically up. Most application can and
should ignore pressure information until they receive the event of type @ref
LIBINPUT_EVENT_TABLET_TOOL_TIP. Applications that require extremely
should ignore pressure information until they receive the event of type
**LIBINPUT_EVENT_TABLET_TOOL_TIP**. Applications that require extremely
fine-grained pressure sensitivity should use the pressure data instead of
the tip events to determine a logical tip down state and treat the tip
events like axis events otherwise.
@ -61,13 +78,17 @@ Note that the pressure threshold to trigger a logical tip event may be zero
on some devices. On tools without pressure sensitivity, determining when a
tip is down is device-specific.
@section tablet-relative-motion Relative motion for tablet tools
.. _tablet-relative-motion:
------------------------------------------------------------------------------
Relative motion for tablet tools
------------------------------------------------------------------------------
libinput calculates the relative motion vector for each event and converts
it to the same coordinate space that a normal mouse device would use. For
the caller, this means that the delta coordinates returned by
libinput_event_tablet_tool_get_dx() and
libinput_event_tablet_tool_get_dy() can be used identical to the delta
**libinput_event_tablet_tool_get_dx()** and
**libinput_event_tablet_tool_get_dy()** can be used identical to the delta
coordinates from any other pointer event. Any resolution differences between
the x and y axes are accommodated for, a delta of N/N represents a 45 degree
diagonal move on the tablet.
@ -79,18 +100,25 @@ all pen-like tools to absolute mode.
If a tool in relative mode must not use pointer acceleration, callers
should use the absolute coordinates returned by
libinput_event_tablet_tool_get_x() and libinput_event_tablet_tool_get_y()
**libinput_event_tablet_tool_get_x()** and libinput_event_tablet_tool_get_y()
and calculate the delta themselves. Callers that require exact physical
distance should also use these functions to calculate delta movements.
@section tablet-axes Special axes on tablet tools
.. _tablet-axes:
------------------------------------------------------------------------------
Special axes on tablet tools
------------------------------------------------------------------------------
A tablet tool usually provides additional information beyond x/y positional
information and the tip state. A tool may provide the distance to the tablet
surface and the pressure exerted on the tip when in contact. Some tablets
additionally provide tilt information along the x and y axis.
@image html tablet-axes.svg "Illustration of the distance, pressure and tilt axes"
.. figure:: tablet-axes.svg
:align: center
Illustration of the distance, pressure and tilt axes"
The granularity and precision of the distance and pressure axes varies
between tablet devices and cannot usually be mapped into a physical unit.
@ -105,9 +133,13 @@ the tablet and the top of the stylus. The angle is measured along the x and
y axis, respectively, a positive tilt angle thus means that the stylus' top
is tilted towards the logical right and/or bottom of the tablet.
@section tablet-fake-proximity Handling of proximity events
.. _tablet-fake-proximity:
libinput's @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY events notify a caller
------------------------------------------------------------------------------
Handling of proximity events
------------------------------------------------------------------------------
libinput's **LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY** events notify a caller
when a tool comes into sensor range or leaves the sensor range. On some
tools this range does not represent the physical range but a reduced
tool-specific logical range. If the range is reduced, this is done
@ -118,12 +150,16 @@ used in relative mode, lying flat on the tablet. Movement typically follows
the interaction normal mouse movements have, i.e. slightly lift the tool and
place it in a separate location. The proximity detection on Wacom
tablets however extends further than the user may lift the mouse, i.e. the
tool may not be lifted out of physical proximity. For such tools, libinput
provides software-emulated proximity.
tool may not be lifted out of physical proximity. For such tools, libinput
provides software-emulated proximity.
Events from the pad do not require proximity, they may be sent any time.
@section tablet-pressure-offset Pressure offset on worn-out tools
.. _tablet-pressure-offset:
------------------------------------------------------------------------------
Pressure offset on worn-out tools
------------------------------------------------------------------------------
When a tool is used for an extended period it can wear down physically. A
worn-down tool may never return a zero pressure value. Even when hovering
@ -139,6 +175,7 @@ than that offset.
Some limitations apply to avoid misdetection of pressure offsets,
specifically:
- pressure offset is only detected on proximity in, and if a device is
capable of detection distances,
- pressure offset is only detected if the distance between the tool and the
@ -149,22 +186,26 @@ specifically:
- if a pressure value less than the current pressure offset is seen, the
offset resets to that value.
Pressure offsets are not detected on @ref LIBINPUT_TABLET_TOOL_TYPE_MOUSE
and @ref LIBINPUT_TABLET_TOOL_TYPE_LENS tools.
Pressure offsets are not detected on **LIBINPUT_TABLET_TOOL_TYPE_MOUSE**
and **LIBINPUT_TABLET_TOOL_TYPE_LENS** tools.
@section tablet-serial-numbers Tracking unique tools
.. _tablet-serial-numbers:
------------------------------------------------------------------------------
Tracking unique tools
------------------------------------------------------------------------------
Some tools provide hardware information that enables libinput to uniquely
identify the physical device. For example, tools compatible with the Wacom
Intuos 4, Intuos 5, Intuos Pro and Cintiq series are uniquely identifiable
through a serial number. libinput does not specify how a tool can be
identified uniquely, a caller should use libinput_tablet_tool_is_unique() to
identified uniquely, a caller should use **libinput_tablet_tool_is_unique()** to
check if the tool is unique.
libinput creates a struct libinput_tablet_tool on the first proximity in of
this tool. By default, this struct is destroyed on proximity out and
re-initialized on the next proximity in. If a caller keeps a reference to
the tool by using libinput_tablet_tool_ref() libinput re-uses this struct
the tool by using **libinput_tablet_tool_ref()** libinput re-uses this struct
whenever that same physical tool comes into proximity on any tablet
recognized by libinput. It is possible to attach tool-specific virtual state
to the tool. For example, a graphics program such as the GIMP may assign a
@ -176,20 +217,24 @@ If the tool does not have a unique identifier, libinput creates a single
struct libinput_tablet_tool per tool type on each tablet the tool is used
on.
@section tablet-tool-types Vendor-specific tablet tool types
.. _tablet-tool-types:
------------------------------------------------------------------------------
Vendor-specific tablet tool types
------------------------------------------------------------------------------
libinput supports a number of high-level tool types that describe the
general interaction expected with the tool. For example, a user would expect
a tool of type @ref LIBINPUT_TABLET_TOOL_TYPE_PEN to interact with a
a tool of type **LIBINPUT_TABLET_TOOL_TYPE_PEN** to interact with a
graphics application taking pressure and tilt into account. The default
virtual tool assigned should be a drawing tool, e.g. a virtual pen or brush.
A tool of type @ref LIBINPUT_TABLET_TOOL_TYPE_ERASER would normally be
mapped to an eraser-like virtual tool. See @ref libinput_tablet_tool_type
A tool of type **LIBINPUT_TABLET_TOOL_TYPE_ERASER** would normally be
mapped to an eraser-like virtual tool. See **libinput_tablet_tool_type**
for the list of all available tools.
Vendors may provide more fine-grained information about the tool in use by
adding a hardware-specific tool ID. libinput provides this ID to the caller
with libinput_tablet_tool_get_tool_id() but makes no promises about the
with **libinput_tablet_tool_get_tool_id()** but makes no promises about the
content or format of the ID.
libinput currently supports Wacom-style tool IDs as provided on the Wacom
@ -197,7 +242,11 @@ Intuos 3, 4, 5, Wacon Cintiq and Wacom Intuos Pro series. The tool ID can
be used to distinguish between e.g. a Wacom Classic Pen or a Wacom Pro Pen.
It is the caller's responsibility to interpret the tool ID.
@section tablet-bounds Out-of-bounds motion events
.. _tablet-bounds:
------------------------------------------------------------------------------
Out-of-bounds motion events
------------------------------------------------------------------------------
Some tablets integrated into a screen (e.g. Wacom Cintiq 24HD, 27QHD and
13HD series, etc.) have a sensor larger than the display area. libinput uses
@ -206,7 +255,10 @@ quirks are present. Events outside this range will produce coordinates that
may be negative or larger than the tablet's width and/or height. It is up to
the caller to ignore these events.
@image html tablet-out-of-bounds.svg "Illustration of the out-of-bounds area on a tablet"
.. figure:: tablet-out-of-bounds.svg
:align: center
Illustration of the out-of-bounds area on a tablet"
In the image above, the display area is shown in black. The red area around
the display illustrates the sensor area that generates input events. Events
@ -214,17 +266,21 @@ within this area will have negative coordinate or coordinates larger than
the width/height of the tablet.
If events outside the logical bounds of the input area are scaled into a
custom range with libinput_event_tablet_tool_get_x_transformed() and
libinput_event_tablet_tool_get_y_transformed() the resulting value may be
custom range with **libinput_event_tablet_tool_get_x_transformed()** and
**libinput_event_tablet_tool_get_y_transformed()** the resulting value may be
less than 0 or larger than the upper range provided. It is up to the caller
to test for this and handle or ignore these events accordingly.
@section tablet-pad-buttons Tablet pad button numbers
.. _tablet-pad-buttons:
------------------------------------------------------------------------------
Tablet pad button numbers
------------------------------------------------------------------------------
Tablet Pad buttons are numbered sequentially, starting with button 0. Thus
button numbers returned by libinput_event_tablet_pad_get_button_number()
button numbers returned by **libinput_event_tablet_pad_get_button_number()**
have no semantic meaning, a notable difference to the button codes returned
by other libinput interfaces (e.g. libinput_event_tablet_tool_get_button()).
by other libinput interfaces (e.g. **libinput_event_tablet_tool_get_button()**).
The Linux kernel requires all input events to have semantic event codes,
but generic buttons like those on a pad cannot easily be assigned semantic
@ -240,16 +296,20 @@ tablet.
Some buttons may have expected default behaviors. For example, on Wacom
Intuos Pro series tablets, the button inside the touch ring is expected to
switch between modes, see @ref tablet-pad-modes. Callers should use
switch between modes, see :ref:`tablet-pad-modes`. Callers should use
external sources like libwacom to identify which buttons have semantic
behaviors.
@section tablet-left-handed Tablets in left-handed mode
.. _tablet-left-handed:
------------------------------------------------------------------------------
Tablets in left-handed mode
------------------------------------------------------------------------------
Left-handed mode on tablet devices usually means rotating the physical
tablet by 180 degrees to move the tablet pad button area to right side of
the tablet. When left-handed mode is enabled on a tablet device (see
libinput_device_config_left_handed_set()) the tablet tool and tablet pad
**libinput_device_config_left_handed_set()**) the tablet tool and tablet pad
behavior changes. In left-handed mode, the tools' axes are adjusted
so that the origin of each axis remains the logical north-east of
the physical tablet. For example, the x and y axes are inverted and the
@ -258,11 +318,15 @@ in its current orientation. On a tablet pad, the ring and strip are
similarly adjusted. The origin of the ring and strips remain the top-most
point.
@image html tablet-left-handed.svg "Tablet axes in right- and left-handed mode"
.. figure:: tablet-left-handed.svg
:align: center
Tablet axes in right- and left-handed mode"
Pad buttons are not affected by left-handed mode; the number of each button
remains the same even when the perceived physical location of the button
changes. This is a conscious design decision:
- Tablet pad buttons do not have intrinsic semantic meanings. Re-ordering
the button numbers would not change any functionality.
- Button numbers should not be exposed directly to the user but handled in
@ -275,7 +339,11 @@ symmetric and thus do not support left-handed mode. libinput requires
libwacom to determine if a tablet is capable of being switched to
left-handed mode.
@section tablet-pad-modes Tablet pad modes
.. _tablet-pad-modes:
------------------------------------------------------------------------------
Tablet pad modes
------------------------------------------------------------------------------
Tablet pad modes are virtual groupings of button, ring and strip
functionality. A caller may assign different functionalities depending on
@ -306,32 +374,42 @@ libinput handles the mode groups independently and returns the mode for each
button as appropriate. The mode group is static for the lifetime of the
device.
@image html tablet-intuos-modes.svg "Modes on an Intuos Pro-like tablet"
.. figure:: tablet-intuos-modes.svg
:align: center
Modes on an Intuos Pro-like tablet"
In the image above, the Intuos Pro-like tablet provides 4 LEDs to indicate
the currently active modes. The button inside the touch ring cycles through
the modes in a clockwise fashion. The upper-right LED indicates that the
currently active mode is 1, based on 0-indexed mode numbering.
libinput_event_tablet_pad_get_mode() would thus return 1 for all button and
**libinput_event_tablet_pad_get_mode()** would thus return 1 for all button and
ring events on this tablet. When the center button is pressed, the mode
switches to mode 2, the LED changes to the bottom-right and
libinput_event_tablet_pad_get_mode() returns 2 for the center button event
**libinput_event_tablet_pad_get_mode()** returns 2 for the center button event
and all subsequent events.
@image html tablet-cintiq24hd-modes.svg "Modes on an Cintiq 24HD-like tablet"
.. figure:: tablet-cintiq24hd-modes.svg
:align: center
Modes on an Cintiq 24HD-like tablet"
In the image above, the Cintiq 24HD-like tablet provides 3 LEDs on each side
of the tablet to indicate the currently active mode for that group of
buttons and the respective ring. The buttons next to the touch ring select
the mode directly. The two LEDs indicate that the mode for the left set of
buttons is currently 0, the mode for the right set of buttons is currently
1, based on 0-indexed mode numbering. libinput_event_tablet_pad_get_mode()
1, based on 0-indexed mode numbering. **libinput_event_tablet_pad_get_mode()**
would thus return 0 for all button and ring events on the left and 1 for all
button and ring events on the right. When one of the three mode toggle
buttons on the right is pressed, the right mode switches to that button's
mode but the left mode remains unchanged.
@section tablet-touch-arbitration Tablet touch arbitration
.. _tablet-touch-arbitration:
------------------------------------------------------------------------------
Tablet touch arbitration
------------------------------------------------------------------------------
"Touch arbitration" is the terminology used when touch events are suppressed
while the pen is in proximity. Since it is almost impossible to use a stylus
@ -340,35 +418,41 @@ touch arbitration serves to reduce the number of accidental inputs.
The wacom kernel driver currently provides touch arbitration but for other
devices arbitration has to be done in userspace.
libinput uses the @ref libinput_device_group to decide on touch arbitration
libinput uses the **libinput_device_group** to decide on touch arbitration
and automatically discards touch events whenever a tool is in proximity.
The exact behavior is device-dependent.
@section tablet-capabilities Required tablet capabilities
.. _tablet-capabilities:
------------------------------------------------------------------------------
Required tablet capabilities
------------------------------------------------------------------------------
To handle a tablet correctly, libinput requires a set of capabilities
on the device. When these capabilities are missing, libinput ignores the
device and prints an error to the log. This error messages reads
@verbatim
missing tablet capabilities: xy pen btn-stylus resolution. Ignoring this device.
@endverbatim
::
missing tablet capabilities: xy pen btn-stylus resolution. Ignoring this device.
or in older versions of libinput simply:
@verbatim
libinput bug: device does not meet tablet criteria. Ignoring this device.
@endverbatim
::
libinput bug: device does not meet tablet criteria. Ignoring this device.
When a tablet is rejected, it is usually possible to check the issue with
the `evemu-descibe` tool.
the ``evemu-descibe`` tool.
- **xy** indicates that the tablet is missing the `ABS_X` and/or `ABS_Y`
- **xy** indicates that the tablet is missing the ``ABS_X`` and/or ``ABS_Y``
axis. This indicates that the device is mislabelled and the udev tag
`ID_INPUT_TABLET` is applied to a device that is not a tablet.
``ID_INPUT_TABLET`` is applied to a device that is not a tablet.
- **pen** or **btn-stylus** indicates that the tablet does not have the
`BTN_TOOL_PEN` or `BTN_STYLUS` bit set. libinput requires either or both
``BTN_TOOL_PEN`` or ``BTN_STYLUS`` bit set. libinput requires either or both
of them to be present. This usually indicates a bug in the kernel driver
or the HID descriptors of the device.
- **resolution** indicates that the device does not have a resolution set
for the x and y axes. This can be fixed with a hwdb entry, locate and read
the 60-evdev.hwdb file on your machine to address this.
*/

48
doc/tapping.dox → doc/user/tapping.rst
View file

@ -1,5 +1,8 @@
/**
@page tapping Tap-to-click behaviour
.. _tapping:
==============================================================================
Tap-to-click behaviour
==============================================================================
"Tapping" or "tap-to-click" is the name given to the behavior where a short
finger touch down/up sequence maps into a button click. This is most
@ -12,11 +15,16 @@ support tapping up to whatever is supported by the hardware. libinput does
not support four-finger taps or any tapping with more than four fingers,
even though some hardware can distinguish between that many fingers.
@section tapping_default Tap-to-click default setting
.. _tapping_default:
------------------------------------------------------------------------------
Tap-to-click default setting
------------------------------------------------------------------------------
Tapping is **disabled** by default on most devices, see [this
commit](https://gitlab.freedesktop.org/libinput/libinput/commit/2219c12c3aa45b80f235e761e87c17fb9ec70eae)
because:
- if you don't know that tapping is a thing (or enabled by default), you get
spurious button events that make the desktop feel buggy.
- if you do know what tapping is and you want it, you usually know where to
@ -27,25 +35,32 @@ method to trigger button clicks. This includes devices without physical
buttons such as touch-capable graphics tablets.
Tapping can be enabled/disabled on a per-device basis. See
libinput_device_config_tap_set_enabled() for details.
**libinput_device_config_tap_set_enabled()** for details.
@section tapndrag Tap-and-drag
.. _tapndrag:
------------------------------------------------------------------------------
Tap-and-drag
------------------------------------------------------------------------------
libinput also supports "tap-and-drag" where a tap immediately followed by a
finger down and that finger being held down emulates a button press. Moving
the finger around can thus drag the selected item on the screen.
Tap-and-drag is optional and can be enabled or disabled with
libinput_device_config_tap_set_drag_enabled(). Most devices have
**libinput_device_config_tap_set_drag_enabled()**. Most devices have
tap-and-drag enabled by default.
Also optional is a feature called "drag lock". With drag lock disabled, lifting
the finger will stop any drag process. When enabled, libinput will ignore a
finger up event during a drag process, provided the finger is set down again
within a implementation-specific timeout. Drag lock can be enabled and
disabled with libinput_device_config_tap_set_drag_lock_enabled().
disabled with **libinput_device_config_tap_set_drag_lock_enabled()**.
Note that drag lock only applies if tap-and-drag is be enabled.
@image html tap-n-drag.svg "Tap-and-drag process"
.. figure:: tap-n-drag.svg
:align: center
Tap-and-drag process"
The above diagram explains the process, a tap (a) followed by a finger held
down (b) starts the drag process and logically holds the left mouse button
@ -61,16 +76,17 @@ simply tap again (f).
If two fingers are supported by the hardware, a second finger can be used to
drag while the first is held in-place.
@section tap_constraints Constraints while tapping
.. _tap_constraints:
------------------------------------------------------------------------------
Constraints while tapping
------------------------------------------------------------------------------
A couple of constraints apply to the contact to be converted into a press, the most common ones are:
- the touch down and touch up must happen within an implementation-defined timeout
- if a finger moves more than an implementation-defined distance while in contact, it's not a tap
- tapping within @ref clickpad_softbuttons "clickpad software buttons" may not trigger an event
- tapping within :ref:`clickpad software buttons <clickpad_softbuttons>` may not trigger an event
- a tap not meeting required pressure thresholds can be ignored as accidental touch
- a tap exceeding certain pressure thresholds can be ignored (see @ref
palm_detection)
- a tap on the edges of the touchpad can usually be ignored (see @ref
palm_detection)
*/
- a tap exceeding certain pressure thresholds can be ignored (see :ref:`palm_detection`)
- a tap on the edges of the touchpad can usually be ignored (see :ref:`palm_detection`)

160
doc/user/test-suite.rst Normal file
View file

@ -0,0 +1,160 @@
.. _test-suite:
==============================================================================
libinput test suite
==============================================================================
libinput ships with a number of tests all run automatically on ``ninja test``.
The primary test suite is the ``libinput-test-suite-runner``. When testing,
the ``libinput-test-suite-runner`` should always be invoked to check for
behavior changes.
The test suite runner uses
`Check <http://check.sourceforge.net/doc/check_html/>`_ underneath the hood
but most of the functionality is abstracted into *litest* wrappers.
The test suite runner has a make-like job control enabled by the ``-j`` or
``--jobs`` flag and will fork off as many parallel processes as given by this
flag. The default if unspecified is 8. When debugging a specific test case
failure it is recommended to employ test filtures (see :ref:`test-filtering`)
and disable parallel tests. The test suite automatically disables parallel
make when run in gdb.
.. _test-config:
------------------------------------------------------------------------------
X.Org config to avoid interference
------------------------------------------------------------------------------
uinput devices created by the test suite are usually recognised by X as
input devices. All events sent through these devices will generate X events
and interfere with your desktop.
Copy the file ``$srcdir/test/50-litest.conf`` into your ``/etc/X11/xorg.conf.d``
and restart X. This will ignore any litest devices and thus not interfere
with your desktop.
.. _test-root:
------------------------------------------------------------------------------
Permissions required to run tests
------------------------------------------------------------------------------
Most tests require the creation of uinput devices and access to the
resulting ``/dev/input/eventX`` nodes. Some tests require temporary udev rules.
**This usually requires the tests to be run as root**. If not run as
root, the test suite runner will exit with status 77, interpreted as
"skipped" by ninja.
.. _test-filtering:
------------------------------------------------------------------------------
Selective running of tests
------------------------------------------------------------------------------
litest's tests are grouped into test groups, test names and devices. A test
group is e.g. "touchpad:tap" and incorporates all tapping-related tests for
touchpads. Each test function is (usually) run with one or more specific
devices. The ``--list`` commandline argument shows the list of suites and
tests. This is useful when trying to figure out if a specific test is
run for a device.
::
$ ./test/libinput-test-suite-runner --list
...
pointer:left-handed:
pointer_left_handed_during_click_multiple_buttons:
trackpoint
ms-surface-cover
mouse-wheelclickcount
mouse-wheelclickangle
low-dpi-mouse
mouse-roccat
mouse-wheel-tilt
mouse
logitech-trackball
cyborg-rat
magicmouse
pointer_left_handed_during_click:
trackpoint
ms-surface-cover
mouse-wheelclickcount
mouse-wheelclickangle
low-dpi-mouse
mouse-roccat
mouse-wheel-tilt
mouse
logitech-trackball
cyborg-rat
litest-magicmouse-device
pointer_left_handed:
trackpoint
ms-surface-cover
mouse-wheelclickcount
mouse-wheelclickangle
low-dpi-mouse
mouse-roccat
mouse-wheel-tilt
mouse
...
In the above example, the "pointer:left-handed" suite contains multiple
tests, e.g. "pointer_left_handed_during_click" (this is also the function
name of the test, making it easy to grep for). This particular test is run
for various devices including the trackpoint device and the magic mouse
device.
The "no device" entry signals that litest does not instantiate a uinput
device for a specific test (though the test itself may
instantiate one).
The ``--filter-test`` argument enables selective running of tests through
basic shell-style function name matching. For example:
::
$ ./test/libinput-test-suite-runner --filter-test="*1fg_tap*"
The ``--filter-device`` argument enables selective running of tests through
basic shell-style device name matching. The device names matched are the
litest-specific shortnames, see the output of ``--list``. For example:
::
$ ./test/libinput-test-suite-runner --filter-device="synaptics*"
The ``--filter-group`` argument enables selective running of test groups
through basic shell-style test group matching. The test groups matched are
litest-specific test groups, see the output of ``--list``. For example:
::
$ ./test/libinput-test-suite-runner --filter-group="touchpad:*hover*"
The ``--filter-device`` and ``--filter-group`` arguments can be combined with
``--list`` to show which groups and devices will be affected.
.. _test-verbosity:
------------------------------------------------------------------------------
Controlling test output
------------------------------------------------------------------------------
Each test supports the ``--verbose`` commandline option to enable debugging
output, see **libinput_log_set_priority()** for details. The ``LITEST_VERBOSE``
environment variable, if set, also enables verbose mode.
::
$ ./test/libinput-test-suite-runner --verbose
$ LITEST_VERBOSE=1 ninja test

44
doc/user/timestamps.rst Normal file
View file

@ -0,0 +1,44 @@
.. _timestamps:
==============================================================================
Timestamps
==============================================================================
.. _event_timestamps:
------------------------------------------------------------------------------
Event timestamps
------------------------------------------------------------------------------
Most libinput events provide a timestamp in millisecond and/or microsecond
resolution. These timestamp usually increase monotonically, but libinput
does not guarantee that this always the case. In other words, it is possible
to receive an event with a timestamp earlier than the previous event.
For example, if a touchpad has :ref:`tapping` enabled, a button event may have a
lower timestamp than an event from a different device. Tapping requires the
use of timeouts to detect multi-finger taps and/or :ref:`tapndrag`.
Consider the following event sequences from a touchpad and a mouse:
::
Time Touchpad Mouse
---------------------------------
t1 finger down
t2 finger up
t3 movement
t4 tap timeout
For this event sequence, the first event to be sent to a caller is in
response to the mouse movement: an event of type
**LIBINPUT_EVENT_POINTER_MOTION** with the timestamp t3.
Once the timeout expires at t4, libinput generates an event of
**LIBINPUT_EVENT_POINTER_BUTTON** (press) with a timestamp t1 and an event
**LIBINPUT_EVENT_POINTER_BUTTON** (release) with a timestamp t2.
Thus, the caller gets events with timestamps in the order t3, t1, t2,
despite t3 > t2 > t1.

293
doc/user/tools.rst Normal file
View file

@ -0,0 +1,293 @@
.. _tools:
==============================================================================
Helper tools
==============================================================================
libinput provides a ``libinput`` tool to query state and events. This tool
takes a subcommand as argument, similar to the **git** command. A full
explanation of the various commands available in the libinput tool is
available in the **libinput(1)** man page.
The most common tools used are:
- ``libinput list-devices``: to list locally available devices,
see :ref:`here <libinput-list-devices>`
- ``libinput debug-events``: to monitor and debug events,
see :ref:`here <libinput-debug-events>`
- ``libinput debug-gui``: to visualize events,
see :ref:`here <libinput-debug-gui>`
- ``libinput record``: to record an event sequence for replaying,
see :ref:`here <libinput-record>`
- ``libinput measure``: measure properties on a kernel device,
see :ref:`here <libinput-measure>`
Most the tools must be run as root to have access to the kernel's
``/dev/input/event*`` device files.
.. _libinput-list-devices:
------------------------------------------------------------------------------
libinput list-devices
------------------------------------------------------------------------------
The ``libinput list-devices`` command shows information about devices
recognized by libinput and can help identifying why a device behaves
different than expected. For example, if a device does not show up in the
output, it is not a supported input device.
.. note:: This tool does **not** show your desktop's configuration, just the
libinput built-in defaults.
::
$ sudo libinput list-devices
[...]
Device: SynPS/2 Synaptics TouchPad
Kernel: /dev/input/event4
Group: 9
Seat: seat0, default
Size: 97.33x66.86mm
Capabilities: pointer
Tap-to-click: disabled
Tap drag lock: disabled
Left-handed: disabled
Nat.scrolling: disabled
Middle emulation: n/a
Calibration: n/a
Scroll methods: *two-finger
Click methods: *button-areas clickfinger
[...]
The above listing shows example output for a touchpad. The
``libinput list-devices`` command lists general information about the device
(the kernel event node) but also the configuration options. If an option is
``n/a`` it does not exist on this device. Otherwise, the tool will show the
default configuration for this device, for options that have more than a
binary state all available options are listed, with the default one prefixed
with an asterisk (``*``). In the example above, the default click method is
button-areas but clickinger is available.
.. note:: This tool is intended for human-consumption and may change its output
at any time.
.. _libinput-debug-events:
------------------------------------------------------------------------------
libinput debug-events
------------------------------------------------------------------------------
The ``libinput debug-events`` command prints events from devices and can help
to identify why a device behaves different than expected. ::
$ sudo libinput debug-events --enable-tapping --set-click-method=clickfinger
All configuration options (enable/disable tapping,
etc.) are available as commandline arguments. To reproduce the event
sequence as your desktop session sees it, ensure that all options are turned
on or off as required. See the **libinput-debug-events(1)** man page or the
``--help`` output for information about the available options.
.. note:: When submitting a bug report, always use the ``--verbose`` flag to get
additional information: ``libinput debug-events --verbose <other options>``
An example output from this tool may look like the snippet below. ::
$ sudo libinput debug-events --enable-tapping --set-click-method=clickfinger
-event2 DEVICE_ADDED Power Button seat0 default group1 cap:k
-event5 DEVICE_ADDED Video Bus seat0 default group2 cap:k
-event0 DEVICE_ADDED Lid Switch seat0 default group3 cap:S
-event1 DEVICE_ADDED Sleep Button seat0 default group4 cap:k
-event4 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=3 seat0 default group5 cap:
-event11 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=7 seat0 default group6 cap:
-event12 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=8 seat0 default group7 cap:
-event13 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=9 seat0 default group8 cap:
-event14 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=10 seat0 default group9 cap:
-event19 DEVICE_ADDED Integrated Camera: Integrated C seat0 default group10 cap:k
-event15 DEVICE_ADDED HDA Intel PCH Dock Mic seat0 default group11 cap:
-event16 DEVICE_ADDED HDA Intel PCH Mic seat0 default group12 cap:
-event17 DEVICE_ADDED HDA Intel PCH Dock Headphone seat0 default group13 cap:
-event18 DEVICE_ADDED HDA Intel PCH Headphone seat0 default group14 cap:
-event6 DEVICE_ADDED ELAN Touchscreen seat0 default group15 cap:t size 305x172mm ntouches 10 calib
-event3 DEVICE_ADDED AT Translated Set 2 keyboard seat0 default group16 cap:k
-event20 DEVICE_ADDED SynPS/2 Synaptics TouchPad seat0 default group17 cap:pg size 100x76mm tap(dl off) left scroll-nat scroll-2fg-edge click-buttonareas-clickfinger dwt-on
-event21 DEVICE_ADDED TPPS/2 IBM TrackPoint seat0 default group18 cap:p left scroll-nat scroll-button
-event7 DEVICE_ADDED ThinkPad Extra Buttons seat0 default group19 cap:k
-event20 POINTER_MOTION +3.62s 2.72/ -0.93
event20 POINTER_MOTION +3.63s 1.80/ -1.42
event20 POINTER_MOTION +3.65s 6.16/ -2.28
event20 POINTER_MOTION +3.66s 6.42/ -1.99
event20 POINTER_MOTION +3.67s 8.99/ -1.42
event20 POINTER_MOTION +3.68s 11.30/ 0.00
event20 POINTER_MOTION +3.69s 21.32/ 1.42
.. _libinput-debug-gui:
------------------------------------------------------------------------------
libinput debug-gui
------------------------------------------------------------------------------
A simple GTK-based graphical tool that shows the behavior and location of
touch events, pointer motion, scroll axes and gestures. Since this tool
gathers data directly from libinput, it is thus suitable for
pointer-acceleration testing.
.. note:: This tool does **not** use your desktop's configuration, just the
libinput built-in defaults.
::
$ sudo libinput debug-gui --enable-tapping
As with :ref:`libinput-debug-events`, all options must be specified on the
commandline to emulate the correct behavior.
See the **libinput-debug-gui(1)** man page or the ``--help`` output for information about
the available options.
.. _libinput-record:
------------------------------------------------------------------------------
libinput record and libinput replay
------------------------------------------------------------------------------
The ``libinput record`` command records the **kernel** events from a specific
device node. The recorded sequence can be replayed with the ``libinput
replay`` command. This pair of tools is crucial to capturing bugs and
reproducing them on a developer's machine.
.. note:: These tools are shipped with libinput, but the recorded events
are **kernel events** and independent of the libinput context. libinput
does not need to be running, it does not matter whether a user is
running X.Org or Wayland or even what version of libinput is currently
running.
The use of the tools is straightforward, just run without arguments, piping
the output into a file: ::
$ sudo libinput record > touchpad.yml
Available devices:
/dev/input/event0: Lid Switch
/dev/input/event1: Sleep Button
/dev/input/event2: Power Button
/dev/input/event3: AT Translated Set 2 keyboard
/dev/input/event4: ThinkPad Extra Buttons
/dev/input/event5: ELAN Touchscreen
/dev/input/event6: Video Bus
/dev/input/event7: HDA Intel HDMI HDMI/DP,pcm=3
/dev/input/event8: HDA Intel HDMI HDMI/DP,pcm=7
/dev/input/event9: HDA Intel HDMI HDMI/DP,pcm=8
/dev/input/event10: HDA Intel HDMI HDMI/DP,pcm=9
/dev/input/event11: HDA Intel HDMI HDMI/DP,pcm=10
/dev/input/event12: HDA Intel PCH Dock Mic
/dev/input/event13: HDA Intel PCH Mic
/dev/input/event14: HDA Intel PCH Dock Headphone
/dev/input/event15: HDA Intel PCH Headphone
/dev/input/event16: Integrated Camera: Integrated C
/dev/input/event17: SynPS/2 Synaptics TouchPad
/dev/input/event18: TPPS/2 IBM TrackPoint
Select the device event number: 17
/dev/input/event17 recording to stdout
Without arguments, ``libinput record`` displays the available devices and lets
the user select one. Supply the number (17 in this case for
``/dev/input/event17``) and the tool will print the device information and
events to the file it is redirected to. More arguments are available, see
the **libinput-record(1)** man page.
Reproduce the bug, ctrl+c and attach the output file to a bug report.
For data protection, ``libinput record`` obscures key codes by default, any
alphanumeric key shows up as letter "a".
.. note:: When reproducing a bug that crashes libinput, run inside ``screen`` or
``tmux``.
The recording can be replayed with the ``libinput replay`` command: ::
$ sudo libinput replay touchpad.yml
SynPS/2 Synaptics TouchPad: /dev/input/event19
Hit enter to start replaying
``libinput replay`` creates a new virtual device based on the description in
the log file. Hitting enter replays the event sequence once and the tool
stops once all events have been replayed. Hitting enter again replays the
sequence again, Ctrl+C stops it and removes the virtual device.
Users are advised to always replay a recorded event sequence to ensure they
have captured the bug.
More arguments are available, see the **libinput-record(1)** and
**libinput-replay(1)** man pages.
.. _libinput-record-autorestart:
..............................................................................
libinput record's autorestart feature
..............................................................................
``libinput record`` often collects thousands of events per minute. However,
the output of ``libinput record`` usually needs to be visually inspected
or replayed in realtime on a developer machine. It is thus imperative that
the event log is kept as short as possible.
For bugs that are difficult to reproduce use
``libinput record --autorestart=2 --output-file=recording.yml``.
All events will be recorded to a file named
``recording.yml.<current-date-and-time>`` and whenever the device does not
send events for 2 seconds, a new file is created. This helps to keep
individual recordings short.
To use the ``--autorestart`` option correctly:
- run ``libinput record --autorestart=2 --output-file=<somefilename>.yml``.
You may provide a timeout other than 2 if needed.
- use the device to reproduce the bug, pausing frequently for 2s and longer
to rotate the logs
- when the bug triggers, **immediately stop using the device** and wait
several seconds for the log to rotate
- Ctrl+C the ``libinput record`` process without using the device
again. Attach the **last recording** to the bug report.
If you have to use the recorded device to stop ``libinput record`` (e.g. to
switch windows), remember that this will cause a new recording to be
created. Thus, attach the **second-to-last recording** to the bug report
because this one contains the bug trigger.
.. _libinput-record-multiple:
..............................................................................
Recording multiple devices at once
..............................................................................
In some cases, an interaction between multiple devices is the cause for a
specific bug. For example, a touchpad may not work in response to keyboard
events. To accurately reproduce this sequence, the timing between multiple
devices must be correct and we need to record the events in one go.
``libinput record`` has a ``--multiple`` argument to record multiple devices at
once. Unlike the normal invocation, this one requires a number of arguments: ::
$ sudo libinput record --multiple --output-file=touchpad-bug.yml /dev/input/event17 /dev/input/event3
recording to 'touchpad-bug.yml'
As seen above, a user must specify ``--multiple`` and the ``--output-file``.
Finally, all devices to be recorded must be specified on the commandline as
well.
Replaying events is the same as for a single recording: ::
$ sudo libinput replay touchpad-bug.yml
.. _libinput-measure:
------------------------------------------------------------------------------
Measuring device properties with libinput measure
------------------------------------------------------------------------------
The ``libinput measure`` tool is a multiplexer for various sub-tools that can
measure specific properties on the device. These tools generally measure one
thing and one thing only and their usage is highly specific to the tool.
Please see the **libinput-measure(1)** man page for information about what
tools are available and the man page for each respective tool.

105
doc/user/touchpad-jitter.rst Normal file
View file

@ -0,0 +1,105 @@
.. _touchpad_jitter:
==============================================================================
Touchpad jitter
==============================================================================
Touchpad jitter describes random movement by a few pixels even when the
user's finger is unmoving.
libinput has a mechanism called a **hysteresis** to avoid that jitter. When
active, movement with in the **hysteresis margin** is discarded. If the
movement delta is larger than the margin, the movement is passed on as
pointer movement. This is a simplified summary, developers should
read the implementation of the hysteresis in ``src/evdev.c``.
libinput uses the kernel ``fuzz`` value to determine the size of the
hysteresis. Users should override this with a udev hwdb entry where the
device itself does not provide the correct value.
.. _touchpad_jitter_fuzz_override:
------------------------------------------------------------------------------
Overriding the hysteresis margins
------------------------------------------------------------------------------
libinput provides the debugging tool ``libinput measure fuzz`` to help edit or
test a fuzz value. This tool is interactive and provides a udev hwdb entry
that matches the device. To check if a fuzz is currently present, simply run
without arguments or with the touchpad's device node:
::
$ sudo libinput measure fuzz
Using Synaptics TM2668-002: /dev/input/event17
Checking udev property... not set
Checking axes... x=16 y=16
In the above output, the axis fuzz is set to 16. To set a specific fuzz, run
with the ``--fuzz=<value>`` argument.
::
$ sudo libinput measure fuzz --fuzz=8
The tool will attempt to construct a hwdb file that matches your touchpad
device. Follow the printed prompts.
In the ideal case, the tool will provide you with a file that can be
submitted to the systemd repo for inclusion.
However, hwdb entry creation is difficult to automate and it's likely
that the tools fails in doing so, especially if an existing entry is already
present.
Below is the outline of what a user needs to do to override a device's fuzz
value in case the ``libinput measure fuzz`` tool fails.
Check with ``udevadm info /sys/class/input/eventX`` (replace your device node
number) whether an existing hwdb override exists. If the ``EVDEV_ABS_``
properties are present, the hwdb overried exists. Find the file that
contains that entry, most likely in ``/etc/udev/hwdb.d`` or
``/usr/lib/udev/hwdb.d``.
The content of the property is a set of values in the format
``EVDEV_ABS_00=min:max:resolution:fuzz``. You need to set the ``fuzz`` part,
leaving the remainder of the property as-is. Values may be empty, e.g. a
property that only sets resolution and fuzz reads as ``EVDEV_ABS_00=::32:8``.
If no properties exist, your hwdb.entry should look approximately like this:
::
evdev:name:Synaptics TM2668-002:dmi:*:svnLENOVO*:pvrThinkPadT440s*:
EVDEV_ABS_00=:::8
EVDEV_ABS_01=:::8
EVDEV_ABS_35=:::8
EVDEV_ABS_36=:::8
Substitute the ``name`` field with the device name (see the output of
``libinput measure fuzz`` and the DMI match content with your hardware. See
:ref:`hwdb_modifying` for details.
Once the hwdb entry has been modified, added, or created,
:ref:`reload the hwdb <hwdb_reloading>`. Once reloaded, :ref:`libinput-record`
"libinput record" should show the new fuzz value for the axes.
Restart the host and libinput should pick up the revised fuzz values.
.. _kernel_fuzz:
------------------------------------------------------------------------------
Kernel fuzz
------------------------------------------------------------------------------
A fuzz set on an absolute axis in the kernel causes the kernel to apply
hysteresis-like behavior to the axis. Unfortunately, this behavior leads to
inconsistent deltas. To avoid this, libinput sets the kernel fuzz on the
device to 0 to disable this kernel behavior but remembers what the fuzz was
on startup. The fuzz is stored in the ``LIBINPUT_FUZZ_XX`` udev property, on
startup libinput will check that property as well as the axis itself.

58
doc/user/touchpad-jumping-cursors.rst Normal file
View file

@ -0,0 +1,58 @@
.. _touchpad_jumping_cursor:
==============================================================================
Touchpad jumping cursor bugs
==============================================================================
A common bug encountered on touchpads is a cursor jump when alternating
between fingers on a multi-touch-capable touchpad. For example, after moving
the cursor a user may use a second finger in the software button area to
physically click the touchpad. Upon setting the finger down, the cursor
exhibits a jump towards the bottom left or right, depending on the finger
position.
When libinput detects a cursor jump it prints a bug warning to the log with
the text **"Touch jump detected and discarded."** and a link to this page.
In most cases, this is a bug in the kernel driver and to libinput it appears
that the touch point moves from its previous position. The pointer jump can
usually be seen in the evemu-record output for the device:
::
E: 249.206319 0000 0000 0000 # ------------ SYN_REPORT (0) ----------
E: 249.218008 0003 0035 3764 # EV_ABS / ABS_MT_POSITION_X 3764
E: 249.218008 0003 0036 2221 # EV_ABS / ABS_MT_POSITION_Y 2221
E: 249.218008 0003 003a 0065 # EV_ABS / ABS_MT_PRESSURE 65
E: 249.218008 0003 0000 3764 # EV_ABS / ABS_X 3764
E: 249.218008 0003 0001 2216 # EV_ABS / ABS_Y 2216
E: 249.218008 0003 0018 0065 # EV_ABS / ABS_PRESSURE 65
E: 249.218008 0000 0000 0000 # ------------ SYN_REPORT (0) ----------
E: 249.230881 0003 0035 3752 # EV_ABS / ABS_MT_POSITION_X 3752
E: 249.230881 0003 003a 0046 # EV_ABS / ABS_MT_PRESSURE 46
E: 249.230881 0003 0000 3758 # EV_ABS / ABS_X 3758
E: 249.230881 0003 0018 0046 # EV_ABS / ABS_PRESSURE 46
E: 249.230881 0000 0000 0000 # ------------ SYN_REPORT (0) ----------
E: 249.242648 0003 0035 1640 # EV_ABS / ABS_MT_POSITION_X 1640
E: 249.242648 0003 0036 4681 # EV_ABS / ABS_MT_POSITION_Y 4681
E: 249.242648 0003 003a 0025 # EV_ABS / ABS_MT_PRESSURE 25
E: 249.242648 0003 0000 1640 # EV_ABS / ABS_X 1640
E: 249.242648 0003 0001 4681 # EV_ABS / ABS_Y 4681
E: 249.242648 0003 0018 0025 # EV_ABS / ABS_PRESSURE 25
E: 249.242648 0000 0000 0000 # ------------ SYN_REPORT (0) ----------
E: 249.254568 0003 0035 1648 # EV_ABS / ABS_MT_POSITION_X 1648
E: 249.254568 0003 003a 0027 # EV_ABS / ABS_MT_PRESSURE 27
E: 249.254568 0003 0000 1644 # EV_ABS / ABS_X 1644
E: 249.254568 0003 0018 0027 # EV_ABS / ABS_PRESSURE 27
In this recording, the pointer jumps from its position 3752/2216 to
1640/4681 within a single frame. On this particular touchpad, this would
represent a physical move of almost 50mm. libinput detects some of these
jumps and discards the movement but otherwise continues as usual. However,
the bug should be fixed at the kernel level.
When you encounter the warning in the log, please generate an evemu
recording of your touchpad and file a bug. See :ref:`reporting_bugs` for more
details.

240
doc/user/touchpad-pressure.rst Normal file
View file

@ -0,0 +1,240 @@
.. _touchpad_pressure:
==============================================================================
Touchpad pressure-based touch detection
==============================================================================
libinput uses the touchpad pressure values and/or touch size values to
detect wether a finger has been placed on the touchpad. This is
:ref:`kernel_pressure_information` and combines with a libinput-specific hardware
database to adjust the thresholds on a per-device basis. libinput uses
these thresholds primarily to filter out accidental light touches but
the information is also used for some :ref:`palm_detection`.
Pressure and touch size thresholds are **not** directly configurable by the
user. Instead, libinput provides these thresholds for each device where
necessary. See :ref:`touchpad_pressure_hwdb` for instructions on how to adjust
the pressure ranges and :ref:`touchpad_touch_size_hwdb` for instructions on
how to adjust the touch size ranges.
.. _kernel_pressure_information:
------------------------------------------------------------------------------
Information provided by the kernel
------------------------------------------------------------------------------
The kernel sends multiple values to inform userspace about a finger touching
the touchpad. The most basic is the ``EV_KEY/BTN_TOUCH`` boolean event
that simply announces physical contact with the touchpad. The decision when
this event is sent is usually made by the kernel driver and may depend on
device-specific thresholds. These thresholds are transparent to userspace
and cannot be modified. On touchpads where pressure or touch size is not
available, libinput uses ``BTN_TOUCH`` to determine when a finger is
logically down.
Many contemporary touchpad devices provide an absolute pressure axis in
addition to ``BTN_TOUCH``. This pressure generally increases as the pressure
increases, however few touchpads are capable of detecting true pressure. The
pressure value is usually related to the covered area - as the pressure
increases a finger flattens and thus covers a larger area. The range
provided by the kernel is not mapped to a specific physical range and
often requires adjustment. Pressure is sent by the ``ABS_PRESSURE`` axis
for single-touch touchpads or ``ABS_MT_PRESSURE`` on multi-touch capable
touchpads. Some devices can detect multiple fingers but only provide
``ABS_PRESSURE``.
Some devices provide additional touch size information through
the ``ABS_MT_TOUCH_MAJOR/ABS_MT_TOUCH_MINOR`` axes and/or
the ``ABS_MT_WIDTH_MAJOR/ABS_MT_WIDTH_MINOR`` axes. These axes specifcy
the size of the touch ellipse. While the kernel documentation specifies how
these axes are supposed to be mapped, few devices forward reliable
information. libinput uses these values together with a device-specific
:ref:`device-quirks` entry. In other words, touch size detection does not work
unless a device quirk is present for the device.
.. _touchpad_pressure_hwdb:
------------------------------------------------------------------------------
Debugging touchpad pressure ranges
------------------------------------------------------------------------------
This section describes how to determine the touchpad pressure ranges
required for a touchpad device and how to add the required
:ref:`device-quirks` locally. Note that the quirk is **not public API** and **may
change at any time**. Users are advised to :ref:`report a bug <reporting_bugs>`
with the updated pressure ranges when testing has completed.
Use the ``libinput measure touchpad-pressure`` tool provided by libinput.
This tool will search for your touchpad device and print some pressure
statistics, including whether a touch is/was considered logically down.
.. note:: This tool will only work on touchpads with pressure.
Example output of the tool is below: ::
$ sudo libinput measure touchpad-pressure
Ready for recording data.
Pressure range used: 8:10
Palm pressure range used: 65535
Place a single finger on the touchpad to measure pressure values.
Ctrl+C to exit
&nbsp;
Sequence 1190 pressure: min: 39 max: 48 avg: 43 median: 44 tags: down
Sequence 1191 pressure: min: 49 max: 65 avg: 62 median: 64 tags: down
Sequence 1192 pressure: min: 40 max: 78 avg: 64 median: 66 tags: down
Sequence 1193 pressure: min: 36 max: 83 avg: 70 median: 73 tags: down
Sequence 1194 pressure: min: 43 max: 76 avg: 72 median: 74 tags: down
Touchpad pressure: 47 min: 47 max: 86 tags: down
The example output shows five completed touch sequences and one ongoing one.
For each, the respective minimum and maximum pressure values are printed as
well as some statistics. The ``tags`` show that sequence was considered
logically down at some point. This is an interactive tool and its output may
change frequently. Refer to the <i>libinput-measure-touchpad-pressure(1)</i> man
page for more details.
By default, this tool uses the :ref:`device-quirks` for the pressure range. To
narrow down on the best values for your device, specify the 'logically down'
and 'logically up' pressure thresholds with the ``--touch-thresholds``
argument: ::
$ sudo libinput measure touchpad-pressure --touch-thresholds=10:8 --palm-threshold=20
Interact with the touchpad and check if the output of this tool matches your
expectations.
.. note:: This is an interactive process. You will need to re-run the
tool with varying thresholds until you find the right range for
your touchpad. Attaching output logs to a bug will not help, only
you with access to the hardware can figure out the correct
ranges.
Once the thresholds are decided on (e.g. 10 and 8), they can be enabled with
:ref:`device-quirks` entry similar to this: ::
$> cat /etc/libinput/local-overrides.quirks
[Touchpad pressure override]
MatchUdevType=touchpad
MatchName=*SynPS/2 Synaptics TouchPad
MatchDMIModalias=dmi:*svnLENOVO:*:pvrThinkPadX230*
AttrPressureRange=10:8
The file name **must** be ``/etc/libinput/local-overrides.quirks``. The
The first line is the section name and can be free-form. The ``Match``
directives limit the quirk to your touchpad, make sure the device name
matches your device's name (see ``libinput record``'s output). The dmi
modalias match should be based on the information in
``/sys/class/dmi/id/modalias``. This modalias should be shortened to the
specific system's information, usually system vendor (svn)
and product name (pn).
Once in place, run the following command to verify the quirk is valid and
works for your device: ::
$ sudo libinput list-quirks /dev/input/event10
AttrPressureRange=10:8
Replace the event node with the one from your device. If the
``AttrPressureRange`` quirk does not show up, re-run with ``--verbose`` and
check the output for any error messages.
If the pressure range quirk shows up correctly, restart X or the
Wayland compositor and libinput should now use the correct pressure
thresholds. The :ref:`tools` can be used to verify the correct
functionality first without the need for a restart.
Once the pressure ranges are deemed correct,
:ref:`report a bug <reporting_bugs>` to get the pressure ranges into the
repository.
.. _touchpad_touch_size_hwdb:
------------------------------------------------------------------------------
Debugging touch size ranges
------------------------------------------------------------------------------
This section describes how to determine the touchpad size ranges
required for a touchpad device and how to add the required
:ref:`device-quirks` locally. Note that the quirk is **not public API** and **may
change at any time**. Users are advised to :ref:`report a bug <reporting_bugs>`
with the updated pressure ranges when testing has completed.
Use the ``libinput measure touch-size`` tool provided by libinput.
This tool will search for your touchpad device and print some touch size
statistics, including whether a touch is/was considered logically down.
.. note:: This tool will only work on touchpads with the ``ABS_MT_MAJOR`` axis.
Example output of the tool is below: ::
$ sudo libinput measure touch-size --touch-thresholds 10:8 --palm-threshold 14
Using ELAN Touchscreen: /dev/input/event5
&nbsp;
Ready for recording data.
Touch sizes used: 10:8
Palm size used: 14
Place a single finger on the device to measure touch size.
Ctrl+C to exit
&nbsp;
Sequence: major: [ 9.. 11] minor: [ 7.. 9]
Sequence: major: [ 9.. 10] minor: [ 7.. 7]
Sequence: major: [ 9.. 14] minor: [ 6.. 9] down
Sequence: major: [ 11.. 11] minor: [ 9.. 9] down
Sequence: major: [ 4.. 33] minor: [ 1.. 5] down palm
The example output shows five completed touch sequences. For each, the
respective minimum and maximum pressure values are printed as well as some
statistics. The ``down`` and ``palm`` tags show that sequence was considered
logically down or a palm at some point. This is an interactive tool and its
output may change frequently. Refer to the <i>libinput-measure-touch-size(1)</i> man
page for more details.
By default, this tool uses the :ref:`device-quirks` for the touch size range. To
narrow down on the best values for your device, specify the 'logically down'
and 'logically up' pressure thresholds with the ``--touch-thresholds``
arguments as in the example above.
Interact with the touchpad and check if the output of this tool matches your
expectations.
.. note:: This is an interactive process. You will need to re-run the
tool with varying thresholds until you find the right range for
your touchpad. Attaching output logs to a bug will not help, only
you with access to the hardware can figure out the correct
ranges.
Once the thresholds are decided on (e.g. 10 and 8), they can be enabled with
:ref:`device-quirks` entry similar to this: ::
$> cat /etc/libinput/local-overrides.quirks
[Touchpad touch size override]
MatchUdevType=touchpad
MatchName=*SynPS/2 Synaptics TouchPad
MatchDMIModalias=dmi:*svnLENOVO:*:pvrThinkPadX230*
AttrTouchSizeRange=10:8
The first line is the match line and should be adjusted for the device name
(see evemu-record's output) and for the local system, based on the
information in ``/sys/class/dmi/id/modalias``. The modalias should be
shortened to the specific system's information, usually system vendor (svn)
and product name (pn).
Once in place, run the following command to verify the quirk is valid and
works for your device: ::
$ sudo libinput list-quirks /dev/input/event10
AttrTouchSizeRange=10:8
Replace the event node with the one from your device. If the
``AttrTouchSizeRange`` quirk does not show up, re-run with ``--verbose`` and
check the output for any error messages.
If the touch size range property shows up correctly, restart X or the
Wayland compositor and libinput should now use the correct thresholds.
The :ref:`tools` can be used to verify the correct functionality first without
the need for a restart.
Once the touch size ranges are deemed correct, :ref:`reporting_bugs` "report a
bug" to get the thresholds into the repository.

149
doc/touchpads.dox → doc/user/touchpads.rst
View file

@ -1,14 +1,25 @@
/**
@page touchpads Touchpads
.. _touchpads:
==============================================================================
Touchpads
==============================================================================
This page provides an outline of touchpad devices. Touchpads aren't simply
categorised into a single type, instead they have a set of properties, a
combination of number of physical buttons, multitouch support abilities and
other properties.
@section touchpads_buttons Number of buttons
.. _touchpads_buttons:
@subsection touchapds_buttons_phys Physically separate buttons
------------------------------------------------------------------------------
Number of buttons
------------------------------------------------------------------------------
.. _touchapds_buttons_phys:
..............................................................................
Physically separate buttons
..............................................................................
Touchpads with physical buttons usually provide two buttons, left and right.
A few touchpads with three buttons exist, and Apple used to have touchpads
@ -19,25 +30,33 @@ this when both buttons are pressed simultaneously.
Note that many Lenovo laptops provide a pointing stick above the touchpad.
This pointing stick has a set of physical buttons just above the touchpad.
While many users use those as substitute touchpad buttons, they logically
belong to the pointing stick. The *40 and *50 series are an exception here,
belong to the pointing stick. The \*40 and \*50 series are an exception here,
the former had no physical buttons on the touchpad and required the top
section of the pad to emulate pointing stick buttons, the *50 series has
section of the pad to emulate pointing stick buttons, the \*50 series has
physical buttons but they are wired to the touchpads. The kernel re-routes
those buttons through the trackstick device. See @ref t440_support for more
those buttons through the trackstick device. See :ref:`t440_support` for more
information.
@subsection touchpads_buttons_clickpads Clickpads
.. _touchpads_buttons_clickpads:
..............................................................................
Clickpads
..............................................................................
Clickpads are the most common type of touchpads these days. A Clickpad has
no separate physical buttons, instead the touchpad itself is clickable as a
whole, i.e. a user presses down on the touch area and triggers a physical
click. Clickpads thus only provide a single button, everything else needs to
be software-emulated. See @ref clickpad_softbuttons for more information.
be software-emulated. See :ref:`clickpad_softbuttons` for more information.
Clickpads are labelled by the kernel with the @c INPUT_PROP_BUTTONPAD input
property.
@subsection touchpads_buttons_forcepads Forcepads
.. _touchpads_buttons_forcepads:
..............................................................................
Forcepads
..............................................................................
Forcepads are Clickpads without a physical button underneath the hardware.
They provide pressure and may have a vibration element that is
@ -45,25 +64,37 @@ software-controlled. This element can simulate the feel of a physical
click or be co-opted for other tasks.
@section touchpads_touch Touch capabilities
.. _touchpads_touch:
Virtually all touchpads available now can <b>detect</b> multiple fingers on
------------------------------------------------------------------------------
Touch capabilities
------------------------------------------------------------------------------
Virtually all touchpads available now can **detect** multiple fingers on
the touchpad, i.e. provide information on how many fingers are on the
touchpad. The touch capabilities described here specify how many fingers a
device can <b>track</b>, i.e. provide reliable positional information for.
device can **track**, i.e. provide reliable positional information for.
In the kernel each finger is tracked in a so-called "slot", the number of
slots thus equals the number of simultaneous touches a device can track.
@subsection touchapds_touch_st Single-touch touchpads
.. _touchapds_touch_st:
..............................................................................
Single-touch touchpads
..............................................................................
Single-finger touchpads can track a single touchpoint. Most single-touch
touchpads can also detect three fingers on the touchpad, but no positional
information is provided for those. In libinput, these touches are termed
"fake touches". The kernel sends @c BTN_TOOL_DOUBLETAP, @c
BTN_TOOL_TRIPLETAP, @c BTN_TOOL_QUADTAP and @c BTN_TOOL_QUINTTAP events when
"fake touches". The kernel sends @c BTN_TOOL_DOUBLETAP,
@c BTN_TOOL_TRIPLETAP, @c BTN_TOOL_QUADTAP and @c BTN_TOOL_QUINTTAP events when
multiple fingers are detected.
@subsection touchpads_touch_mt Pure multi-touch touchpads
.. _touchpads_touch_mt:
..............................................................................
Pure multi-touch touchpads
..............................................................................
Pure multi-touch touchpads are those that can track, i.e. identify the
location of all fingers on the touchpad. Apple's touchpads support 16
@ -72,15 +103,19 @@ SMBus.
These touchpads usually also provide extra information. Apple touchpads
provide an ellipse and the orientation of the ellipse for each touch point.
Other touchpads provide a pressure value for each touch point (see @ref
touchpads_pressure_handling).
Other touchpads provide a pressure value for each touch point (see
:ref:`touchpads_pressure_handling`).
Note that the kernel sends @c BTN_TOOL_DOUBLETAP, @c
BTN_TOOL_TRIPLETAP, @c BTN_TOOL_QUADTAP and @c BTN_TOOL_QUINTTAP events for
Note that the kernel sends @c BTN_TOOL_DOUBLETAP,
@c BTN_TOOL_TRIPLETAP, @c BTN_TOOL_QUADTAP and @c BTN_TOOL_QUINTTAP events for
all touches for backwards compatibility. libinput ignores these events if
the touchpad can track touches correctly.
@subsection touchpads_touch_partial_mt Partial multi-touch touchpads
.. _touchpads_touch_partial_mt:
..............................................................................
Partial multi-touch touchpads
..............................................................................
The vast majority of touchpads fall into this category, the half-way
point between single-touch and pure multi-touch. These devices can track N
@ -89,11 +124,15 @@ protocol, Synaptics touchpads can track two fingers but may detect up to
five.
The number of slots may limit which features are available in libinput.
Any device with two slots can support two-finger scrolling, but @ref
thumb-detection or @ref palm_detection may be limited if only two slots are
Any device with two slots can support two-finger scrolling, but
:ref:`thumb-detection` or @ref palm_detection may be limited if only two slots are
available.
@subsection touchpads_touch_semi_mt Semi-mt touchpads
.. _touchpads_touch_semi_mt:
..............................................................................
Semi-mt touchpads
..............................................................................
A sub-class of partial multi-touch touchpads. These touchpads can
technically detect two fingers but the location of both is limited to the
@ -102,20 +141,28 @@ touch is the bottom-right one. Coordinates jump around as fingers move past
each other.
Many semi-mt touchpads also have a lower resolution for the second touch, or
both touches. This may limit some features such as @ref gestures or
@ref scrolling.
both touches. This may limit some features such as :ref:`gestures` or
:ref:`scrolling`.
Semi-mt are labelled by the kernel with the @c INPUT_PROP_SEMI_MT input
property.
@section touchpads_mis Other touchpad properties
.. _touchpads_mis:
@subsection touchpads_external External touchpads
------------------------------------------------------------------------------
Other touchpad properties
------------------------------------------------------------------------------
.. _touchpads_external:
..............................................................................
External touchpads
..............................................................................
External touchpads are USB or Bluetooth touchpads not in a laptop chassis,
e.g. Apple Magic Trackpad or the Logitech T650. These are usually @ref
touchpads_buttons_clickpads the biggest difference is that they can be
removed or added at runtime.
e.g. Apple Magic Trackpad or the Logitech T650. These are usually
:ref:`touchpads_buttons_clickpads` the biggest difference is that they can be
removed or added at runtime.
One interaction method that is only possible on external touchpads is a
thumb resting on the very edge/immediately next to the touchpad. On the far
@ -123,10 +170,14 @@ edge, touchpads don't always detect the finger location so clicking with a
thumb barely touching the edge makes it hard or impossible to figure out
which software button area the finger is on.
These touchpads also don't need @ref palm_detection - since they're not
These touchpads also don't need :ref:`palm_detection` - since they're not
located underneath the keyboard, accidental palm touches are a non-issue.
@subsection touchpads_pressure_handling Touchpads pressure handling
.. _touchpads_pressure_handling:
..............................................................................
Touchpads pressure handling
..............................................................................
Pressure is usually directly related to contact area. Human fingers flatten
out as the pressure on the pad increases, resulting in a bigger contact area
@ -135,28 +186,38 @@ and the firmware then calculates that back into a pressure reading.
libinput uses pressure to detect accidental palm contact and thumbs, though
pressure data is often device-specific and unreliable.
@subsection touchpads_circular Circular touchpads
.. _touchpads_circular:
..............................................................................
Circular touchpads
..............................................................................
Only listed for completeness, circular touchpads have not been used in
laptops for a number of years. These touchpad shaped in an ellipse or
straight.
@subsection touchpads_tablets Graphics tablets
.. _touchpads_tablets:
..............................................................................
Graphics tablets
..............................................................................
Touch-capable graphics tablets are effectively external touchpads, with two
differentiators: they are larger than normal touchpads and they have no
regular touchpad buttons. They either work like a @ref
touchpads_buttons_forcepads Forcepad, or rely on interaction methods that
don't require buttons (like @ref tapping). Since the physical device is
regular touchpad buttons. They either work like a
:ref:`touchpads_buttons_forcepads` Forcepad, or rely on interaction methods that
don't require buttons (like :ref:`tapping`). Since the physical device is
shared with the pen input, some touch arbitration is required to avoid touch
input interfering when the pen is in use.
input interfering when the pen is in use.
@subsection touchpads_edge_zone Dedicated edge scroll area
.. _touchpads_edge_zone:
Before @ref twofinger_scrolling became the default scroll method, some
..............................................................................
Dedicated edge scroll area
..............................................................................
Before :ref:`twofinger_scrolling` became the default scroll method, some
touchpads provided a marking on the touch area that designates the
edge to be used for scrolling. A finger movement in that edge zone should
trigger vertical motions. Some touchpads had markers for a horizontal
scroll area too at the bottom of the touchpad.
*/

152
doc/trackpoints.dox → doc/user/trackpoints.rst
View file

@ -1,22 +1,32 @@
/**
@page trackpoints Trackpoints and Pointing Sticks
.. _trackpoints:
==============================================================================
Trackpoints and Pointing Sticks
==============================================================================
This page provides an overview of trackpoint handling in libinput, also
refered to as Pointing Stick or Trackstick. The device itself is usually a
round plastic stick between the G, H and B keys with a set of buttons below
the space bar.
@image html button-scrolling.svg "A trackpoint"
.. figure:: button-scrolling.svg
:align: center
A trackpoint"
libinput always treats the buttons below the space bar as the buttons that
belong to the trackpoint even on the few laptops where the buttons are not
physically wired to the trackpoint device anyway, see @ref t440_support.
physically wired to the trackpoint device anyway, see :ref:`t440_support`.
Trackpoint devices have @ref button_scrolling enabled by default. This may
Trackpoint devices have :ref:`button_scrolling` enabled by default. This may
interfer with middle-button dragging, if middle-button dragging is required
by a user then button scrolling must be disabled.
@section trackpoint_range Motion range on trackpoints
.. _trackpoint_range:
------------------------------------------------------------------------------
Motion range on trackpoints
------------------------------------------------------------------------------
It is difficult to associate motion on a trackpoint with a physical
reference. Unlike mice or touchpads where the motion can be
@ -36,14 +46,21 @@ is hart to generalize, see
<a href="https://who-t.blogspot.com/2018/06/observations-on-trackpoint-input-data.html">
Observations on trackpoint input data</a> for more details.
@image html trackpoint-delta-illustration.svg Illustration of the relationship between reporting rate and delta values on a trackpoint
.. figure:: trackpoint-delta-illustration.svg
:align: center
Illustration of the relationship between reporting rate and delta values on a trackpoint
The delta range itself can vary greatly between laptops, some devices send a
maximum delta value of 30, others can go beyond 100. However, the useful
delta range is a fraction of the maximum range. It is uncomfortable to exert
sufficient pressure to even get close to the maximum ranges.
@section trackpoint_multiplier The magic trackpoint multiplier
.. _trackpoint_multiplier:
------------------------------------------------------------------------------
The magic trackpoint multiplier
------------------------------------------------------------------------------
To accomodate for the wildly different input data on trackpoint, libinput
uses a multiplier that is applied to input deltas. Trackpoints that send
@ -53,16 +70,22 @@ profile is applied to these pre-multiplied deltas.
Given a trackpoint delta (dx, dy), a multiplier M and a pointer acceleration
function f(dx, dy) → (dx', dy'), the algorithm is effectively:
@verbatim
f(M * dx, M * dy) → (dx', dy')
@endverbatim
::
f(M * dx, M * dy) → (dx', dy')
The magic trackpoint multiplier **is not user visible configuration**. It is
part of the @ref device-quirks system and provided once per device.
part of the :ref:`device-quirks` system and provided once per device.
User-specific preferences can be adjusted with the pointer acceleration speed
setting libinput_device_config_accel_set_speed().
setting **libinput_device_config_accel_set_speed()**.
@subsection trackpoint_multiplier_adjustment Adjusting the magic trackpoint multiplier
.. _trackpoint_multiplier_adjustment:
..............................................................................
Adjusting the magic trackpoint multiplier
..............................................................................
This section only applies if:
@ -70,8 +93,8 @@ This section only applies if:
unusably fast, **and**
- the lowest speed setting (-1) is still too fast **or** the highest speed
setting is still too slow, **and**
- the @ref device-quirks for this device do not list a trackpoint multiplier
(see @ref device-quirks-debugging)
- the :ref:`device-quirks` for this device do not list a trackpoint multiplier
(see :ref:`device-quirks-debugging`)
If the only satisfactory speed settings are less than -0.75 or greater than
0.75, a multiplier *may* be required.
@ -87,53 +110,59 @@ error. The default multiplier is always 1.0. A value between 0.0 and 1.0
slows the trackpoint down, a value above 1.0 speeds the trackpoint up.
Values below zero are invalid.
@note The multiplier is not a configuration to adjust to personal
.. note:: The multiplier is not a configuration to adjust to personal
preferences. The multiplier normalizes the input data into a range that
can then be configured with the speed setting.
To adjust the local multiplier, first @ref building_libinput
To adjust the local multiplier, first :ref:`building_libinput`
"build libinput from git master". It is not required to install libinput
from git. The below assumes that all @ref building_dependencies are already
from git. The below assumes that all :ref:`building_dependencies` are already
installed.
@verbatim
$ cd path/to/libinput.git
# Use an approximate multiplier in the quirks file
$ cat > quirks/99-trackpont-override.quirks <<EOF
[Trackpoint Override]
MatchUdevType=pointingstick
AttrTrackpointMultiplier=1.0
EOF
::
# Use your trackpoint's event node. If the Attr does not show up
# then the quirk does not apply to your trackpoint.
$ ./builddir/libinput quirks list /dev/input/event18
AttrTrackpointMultiplier=1.0
$ cd path/to/libinput.git
# Use an approximate multiplier in the quirks file
$ cat > quirks/99-trackpont-override.quirks <<EOF
[Trackpoint Override]
MatchUdevType=pointingstick
AttrTrackpointMultiplier=1.0
EOF
# Use your trackpoint's event node. If the Attr does not show up
# then the quirk does not apply to your trackpoint.
$ ./builddir/libinput quirks list /dev/input/event18
AttrTrackpointMultiplier=1.0
# Now start a GUI program to debug the trackpoint speed.
# ESC closes the debug GUI
$ sudo ./builddir/libinput debug-gui
# Now start a GUI program to debug the trackpoint speed.
# ESC closes the debug GUI
$ sudo ./builddir/libinput debug-gui
@endverbatim
Replace the multiplier with an approximate value and the event node with
your trackpoint's event node. Try to use trackpoint and verify the
multiplier is good enough. If not, adjust the `.quirks` file and re-run the
`libinput debug-gui`. Note that the `libinput debug-gui` always feels
multiplier is good enough. If not, adjust the ``.quirks`` file and re-run the
``libinput debug-gui``. Note that the ``libinput debug-gui`` always feels
less responsive than libinput would behave in a normal install.
Once the trackpoint behaves correctly you are ready to test the system
libinput:
@verbatim
$ sudo cp quirks/99-trackpoint-override.quirks /etc/libinput/local-overrides.quirks
@endverbatim
::
$ sudo cp quirks/99-trackpoint-override.quirks /etc/libinput/local-overrides.quirks
Now verify the override is seen by the system libinput
@verbatim
$ libinput quirks list
AttrTrackpointMultiplier=1.0
@endverbatim
::
$ libinput quirks list
AttrTrackpointMultiplier=1.0
If the multiplier is listed, restart your Wayland session or X server. The
new multiplier is now applied to your trackpoint.
@ -143,27 +172,30 @@ upstream. First, find add a more precise match for the device so it only
applies to the built-in trackpoint on your laptop model. Usually a
variation of the following is sufficient:
@verbatim
[Trackpoint Override]
MatchUdevType=pointingstick
MatchName=*TPPS/2 IBM TrackPoint*
MatchDMIModalias=dmi:*svnLENOVO:*:pvrThinkPadT440p*
AttrTrackpointMultiplier=1.0
@endverbatim
Look at your `/sys/class/dmi/id/modalias` file for the values to add. Verify
that `libinput quirks list` still shows the `AttrTrackpointMultiplier`. If
it does, then you should @ref reporting_bugs "report a bug" with the contents of
::
[Trackpoint Override]
MatchUdevType=pointingstick
MatchName=*TPPS/2 IBM TrackPoint*
MatchDMIModalias=dmi:*svnLENOVO:*:pvrThinkPadT440p*
AttrTrackpointMultiplier=1.0
Look at your ``/sys/class/dmi/id/modalias`` file for the values to add. Verify
that ``libinput quirks list`` still shows the ``AttrTrackpointMultiplier``. If
it does, then you should :ref:`report a bug <reporting_bugs>` with the contents of
the file. Alternatively, file a merge request with the data added.
@section trackpoint_range_measure Measuring the trackpoint range
.. _trackpoint_range_measure:
------------------------------------------------------------------------------
Measuring the trackpoint range
------------------------------------------------------------------------------
This section only applied to libinput version 1.9.x, 1.10.x, and 1.11.x and
has been removed. See @ref trackpoint_multiplier for versions 1.12.x and later.
has been removed. See :ref:`trackpoint_multiplier` for versions 1.12.x and later.
If using libinput version 1.11.x or earlier, please see
[the 1.11.0 documentation](https://wayland.freedesktop.org/libinput/doc/1.11.0/trackpoints.html#trackpoint_range_measure)
*/
`the 1.11.0 documentation <https://wayland.freedesktop.org/libinput/doc/1.11.0/trackpoints.html#trackpoint_range_measure>`_

11
doc/user/troubleshooting.rst Normal file
View file

@ -0,0 +1,11 @@
.. _troubleshooting:
==============================================================================
Troubleshooting
==============================================================================
.. toctree::
:maxdepth: 2
tools.rst
device-quirks.rst

37
doc/what-is-libinput.dox → doc/user/what-is-libinput.rst
View file

@ -1,11 +1,18 @@
/**
@page what_is_libinput What is libinput?
.. _what_is_libinput:
==============================================================================
What is libinput?
==============================================================================
This page describes what libinput is, but more importantly it also describes
what libinput is **not**.
@section what_libinput_is What libinput is
.. _what_libinput_is:
------------------------------------------------------------------------------
What libinput is
------------------------------------------------------------------------------
libinput is an input stack to be used by those applications that need full
input device processing by commonly used input devices. That includes mice,
@ -28,7 +35,11 @@ touchpad in the Lenovo T440 and similar devices. While there may be
use-cases for providing top software buttons on other devices, libinput does
not do so.
@section what_libinput_is_not What libinput is not
.. _what_libinput_is_not:
------------------------------------------------------------------------------
What libinput is not
------------------------------------------------------------------------------
libinput is **not** a project to support experimental devices. Unless a
device is commonly available off-the-shelf, libinput will not support this
@ -55,13 +66,17 @@ are handled. Instead, it takes best practice and the common use-cases and
provides it in an easy-to-consume package for compositors or other processes
that need those interactions typically expected by users.
@section libinput-wayland libinput and Wayland
.. _libinput-wayland:
------------------------------------------------------------------------------
libinput and Wayland
------------------------------------------------------------------------------
libinput is not used directly by Wayland applications, it is an input stack
used by the compositor. The typical software stack for a system running
Wayland is:
@dotfile libinput-stack-wayland.gv
.. graphviz:: libinput-stack-wayland.gv
The Wayland compositor may be Weston, mutter, KWin, etc. Note that
Wayland encourages the use of toolkits, so the Wayland client (your
@ -72,13 +87,17 @@ whether libinput is in use.
libinput is not a requirement for Wayland or even a Wayland compositor.
There are some specialized compositors that do not need or want libinput.
@section libinput-xorg libinput and X.Org
.. _libinput-xorg:
------------------------------------------------------------------------------
libinput and X.Org
------------------------------------------------------------------------------
libinput is not used directly by X applications but rather through the
custom xf86-input-libinput driver. The simplified software stack for a
system running X.Org is:
@dotfile libinput-stack-xorg.gv
.. graphviz:: libinput-stack-xorg.gv
libinput is not employed directly by the X server but by the
xf86-input-libinput driver instead. That driver is loaded by the server
@ -88,5 +107,3 @@ does not know whether libinput is in use.
libinput and xf86-input-libinput are not a requirement, the driver will only
handle those devices explicitly assigned through an xorg.conf.d snippets. It
is possible to mix xf86-input-libinput with other X.Org drivers.
*/

3
meson.build
View file

@ -374,7 +374,8 @@ endif
############ documentation ############
if get_option('documentation')
subdir('doc')
subdir('doc/api')
subdir('doc/user')
endif
############ tools ############