If any of the above is set, libinput initializes the device as the given
-type, see @ref udev_device_type.
+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 seat for this device. See
libinput_seat_get_logical_name()
@@ -57,6 +60,13 @@ See @ref motion_normalization for details.
The angle in degrees for each click on a mouse wheel. See
libinput_pointer_get_axis_source() for details.
+
POINTINGSTICK_CONST_ACCEL
+
A constant (linear) acceleration factor to apply to pointingstick deltas
+to normalize them.
+
LIBINPUT_MODEL_*
+
This prefix is reserved as private API, do not use.. See @ref
+model_specific_configuration for details.
+
Below is an example udev rule to assign "seat1" to a device from vendor
@@ -91,4 +101,16 @@ 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 model_specific_configuration Model-specific configuration
+
+libinput reserves the property prefix LIBINPUT_MODEL_ for
+model-specific configuration. This prefix is reserved as private API, do
+not use.
+
+The effect of this property may be to enable or disable certain
+features on a specific device or set of devices, to change configuration
+defaults or any other reason. The effects of setting this property, the
+format of the property and the value of the property are subject to change
+at any time.
+
*/
diff --git a/doc/middle-button-emulation.svg b/doc/middle-button-emulation.svg
new file mode 100644
index 00000000..338af386
--- /dev/null
+++ b/doc/middle-button-emulation.svg
@@ -0,0 +1,1315 @@
+
+
+
diff --git a/doc/palm-detection.dox b/doc/palm-detection.dox
index 4e839e62..a03f9c14 100644
--- a/doc/palm-detection.dox
+++ b/doc/palm-detection.dox
@@ -23,6 +23,10 @@ screen, it is common for a finger to start inside an exclusion zone and move
rapidly across the touchpad. libinput detects such movements and avoids palm
detection on such touch sequences.
+Each 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).
+
In the diagram below, the exclusion zones are painted red.
Touch 'A' starts inside the exclusion zone and moves
almost vertically. It is considered a palm and ignored for cursor movement,
@@ -31,6 +35,11 @@ despite moving out of the exclusion zone.
Touch 'B' starts inside the exclusion zone but moves horizontally out of the
zone. It is considered a valid touch and controls the cursor.
+Touch 'C' occurs in the top part of the exclusion zone. Despite being a
+tapping motion, it does not generate an emulated button event. Touch 'D'
+likewise occurs within the exclusion zone but in the bottom half. libinput
+will generate a button event for this touch.
+
@image html palm-detection.svg
@section trackpoint-disabling Palm detection during trackpoint use
@@ -48,5 +57,26 @@ the palm on the touchpad while using the trackstick).
If the touchpad is disabled, the @ref t440_support "top software buttons"
remain enabled.
+@section 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
+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
+ (Ctrl, Alt, Shift, and Fn). Actions such as Ctrl + click thus stay
+ responsive.
+- Touches started while the touchpad is disabled do not control the cursor,
+ it is thus possible to rest the palm on the touchpad while typing.
+- Physical buttons work even while the touchpad is disabled. This includes
+ software-emulated buttons.
*/
diff --git a/doc/scrolling.dox b/doc/scrolling.dox
index 3ded909d..b5a01cf8 100644
--- a/doc/scrolling.dox
+++ b/doc/scrolling.dox
@@ -1,7 +1,20 @@
/**
@page scrolling Scrolling
-libinput supports three different types of scrolling behavior.
+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. See
+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.
+
+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
+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
@@ -16,7 +29,6 @@ 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
sufficiently large movement is required, once scrolling tiny amounts of
movements will translate into tiny scroll movements.
-
Scrolling in both directions at once is possible by meeting the required
distance thresholds to enable each direction separately.
@@ -28,23 +40,27 @@ scroll).
@image html edge-scrolling.svg "Vertical and horizontal edge scrolling"
-Due to the layout of the edges, diagonal scrolling is not possible.
+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 conflicts with @ref clickpad_softbuttons and is
-not usually available on clickpads.
+not usually available on clickpads. See
+http://who-t.blogspot.com.au/2015/03/why-libinput-doesnt-support-edge.html
+for details.
@section button_scrolling On-Button scrolling
-Scrolling when a button is held down is available on selected devices. The
-motion of a device is converted into scrolling motion.
-
-For example, Lenovo devices provide a
+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 that emulates
scroll events when the trackstick's middle mouse button is held down.
@image html button-scrolling.svg "Button scrolling"
-Note that libinput's @ref t440_support enables the use of the middle
+The button may be changed with
+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
button for button scrolling (even when the touchpad is disabled).
*/
diff --git a/doc/svg/palm-detection.svg b/doc/svg/palm-detection.svg
index 9fb6077d..c3e45f44 100644
--- a/doc/svg/palm-detection.svg
+++ b/doc/svg/palm-detection.svg
@@ -2,14 +2,66 @@
diff --git a/doc/tapping.dox b/doc/tapping.dox
index f603b7d5..7eb81e62 100644
--- a/doc/tapping.dox
+++ b/doc/tapping.dox
@@ -33,6 +33,10 @@ continue the dragging process, so that multiple touchpad-widths of distance
can be covered easily. If two-fingers are supported by the hardware, a
second finger can be used to drag while the first is held in-place.
+An alternative method to end a drag process is to tap immediately after
+lifting the finger. The full sequence is thus: tap, finger down, drag,
+finger up, tap.
+
@section tap_constraints Constraints while tapping
A couple of constraints apply to the contact to be converted into a press, the most common ones are:
diff --git a/doc/test-suite.dox b/doc/test-suite.dox
new file mode 100644
index 00000000..30dd1579
--- /dev/null
+++ b/doc/test-suite.dox
@@ -0,0 +1,92 @@
+/**
+@page test-suite libinput test suite
+
+The libinput test suite is based on
+[Check](http://check.sourceforge.net/doc/check_html/) and runs automatically
+during `make check`. Check itself is wrapped into a libinput-specific test
+suite called *litest*. Tests are found in `$srcdir/test/`, the test binaries are
+prefixed with `test-` and can be run individually.
+
+@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.
+This usually requires the tests to be run as root.
+
+@section test-filtering Selective running of tests
+
+litest's tests are grouped by test groups 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.
+@code
+$ ./test/test-device --list
+device:wheel:
+ wheel only
+ blackwidow
+device:invalid devices:
+ no device
+device:group:
+ no device
+ logitech trackball
+ MS surface cover
+ mouse_roccat
+ wheel only
+ blackwidow
+...
+@endcode
+
+In the above example, the "device:wheel" suite is run for the "wheel only" and
+the "blackwidow" device. Both devices are automatically instantiated through
+uinput by litest. 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:
+
+@code
+$ ./test/test-touchpad --filter-test="*1fg_tap*"
+@endcode
+
+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:
+
+@code
+$ ./test/test-touchpad --filter-device="synaptics*"
+@endcode
+
+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:
+
+@code
+$ ./test/test-touchpad --filter-group="touchpad:*hover*"
+@endcode
+
+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.
+
+@code
+$ ./test/test-device --verbose
+$ LITEST_VERBOSE=1 make check
+@endcode
+
+*/
diff --git a/doc/touchpad-tap-state-machine.svg b/doc/touchpad-tap-state-machine.svg
index 7aecefc1..39b0b86b 100644
--- a/doc/touchpad-tap-state-machine.svg
+++ b/doc/touchpad-tap-state-machine.svg
@@ -1,756 +1,1141 @@
-
-