Commit f6110765 authored by Peter Hutterer's avatar Peter Hutterer
Browse files

doc/user: more fixes including adding a device-types section


Signed-off-by: Peter Hutterer's avatarPeter Hutterer <peter.hutterer@who-t.net>
parent ddc0df6f
......@@ -48,7 +48,7 @@ correspond to the buttons 'pressed' and 'released' states, respectively.
.. figure:: button-debouncing-wave-diagram.svg
:align: center
Diagram illustrating button debouncing"
Diagram illustrating button debouncing
Some devices send events in bursts, erroneously triggering the button
......
......@@ -136,7 +136,8 @@ 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
:ref:`device-quirks` and not in the hwdb anymore. Please see
:ref:`device-quirks` for
details.
.. _model_specific_configuration_x220fw81:
......
......@@ -108,7 +108,8 @@ 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
.. figure:: palm-detection.svg
:align: center
.. _trackpoint-disabling:
......@@ -200,7 +201,8 @@ thumb hanging mostly off the touchpad will have a small surface area.
libinput has a definitive thumb zone where any touch is considered a resting
thumb.
@image html thumb-detection.svg
.. figure:: thumb-detection.svg
:align: center
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
......
......@@ -91,7 +91,7 @@ and after :ref:`motion_normalization` is applied.
.. figure:: ptraccel-linear.svg
:align: center
Linear pointer acceleration"
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
......@@ -117,7 +117,7 @@ coordinates (see :ref:`motion_normalization`).
.. figure:: ptraccel-low-dpi.svg
:align: center
Pointer acceleration for low-dpi devices"
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
......@@ -138,7 +138,7 @@ deceleration factor.
.. figure:: ptraccel-touchpad.svg
:align: center
Pointer acceleration curve for touchpads"
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.
......@@ -171,7 +171,7 @@ consistent behavior across different touchpad devices.
.. figure:: ptraccel-trackpoint.svg
:align: center
Pointer acceleration curves for trackpoints"
Pointer acceleration curves for trackpoints
The image above shows the trackpoint acceleration profile for the speed in
units/ms.
......
......@@ -5,14 +5,14 @@ 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:
: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`
"clickpads") support two-finger scrolling only
- touchpad devices without physical buttons (:ref:`ClickPads <clickpad_softbuttons>`)
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
......@@ -50,7 +50,7 @@ vertically or horizontally.
.. figure:: twofinger-scrolling.svg
:align: center
Vertical and horizontal two-finger scrolling"
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
......@@ -79,7 +79,7 @@ scroll).
.. figure:: edge-scrolling.svg
:align: center
Vertical and horizontal edge scrolling"
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.
......@@ -105,7 +105,7 @@ scroll events when the trackstick's middle mouse button is held down.
.. figure:: button-scrolling.svg
:align: center
Button scrolling"
Button scrolling
The button may be changed with
**libinput_device_config_scroll_set_button()** but must be on the same device as
......
......@@ -24,7 +24,7 @@ the respective area:
.. figure:: top-software-buttons.svg
:align: center
Left, right and middle-button click with top software button areas"
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 software buttons <clickpad_softbuttons>`.
......
......@@ -12,7 +12,7 @@ Apple iPad.
.. figure:: tablet.svg
:align: center
Illustration of a graphics tablet"
Illustration of a graphics tablet
.. _tablet-tools:
......@@ -36,7 +36,7 @@ across multiple kernel devices.
.. figure:: tablet-interfaces.svg
:align: center
Difference between Pad and Tool buttons"
Difference between Pad and Tool buttons
Touch events on the tablet integrated into a screen itself are exposed
through the **LIBINPUT_DEVICE_CAP_TOUCH** capability. Touch events on a
......@@ -118,7 +118,7 @@ additionally provide tilt information along the x and y axis.
.. figure:: tablet-axes.svg
:align: center
Illustration of the distance, pressure and tilt axes"
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.
......@@ -258,7 +258,7 @@ the caller to ignore these events.
.. figure:: tablet-out-of-bounds.svg
:align: center
Illustration of the out-of-bounds area on a tablet"
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
......@@ -321,7 +321,7 @@ point.
.. figure:: tablet-left-handed.svg
:align: center
Tablet axes in right- and left-handed mode"
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
......@@ -377,7 +377,7 @@ device.
.. figure:: tablet-intuos-modes.svg
:align: center
Modes on an Intuos Pro-like tablet"
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
......@@ -392,7 +392,7 @@ and all subsequent events.
.. figure:: tablet-cintiq24hd-modes.svg
:align: center
Modes on an Cintiq 24HD-like tablet"
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
......
......@@ -60,7 +60,7 @@ Note that drag lock only applies if tap-and-drag is be enabled.
.. figure:: tap-n-drag.svg
:align: center
Tap-and-drag process"
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
......
......@@ -49,7 +49,7 @@ 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.
Clickpads are labelled by the kernel with the @c INPUT_PROP_BUTTONPAD input
Clickpads are labelled by the kernel with the **INPUT_PROP_BUTTONPAD** input
property.
.. _touchpads_buttons_forcepads:
......@@ -86,9 +86,9 @@ 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
multiple fingers are detected.
"fake touches". The kernel sends **BTN_TOOL_DOUBLETAP**,
**BTN_TOOL_TRIPLETAP**, **BTN_TOOL_QUADTAP** and **BTN_TOOL_QUINTTAP**
events when multiple fingers are detected.
.. _touchpads_touch_mt:
......@@ -106,10 +106,10 @@ 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`).
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.
Note that the kernel sends **BTN_TOOL_DOUBLETAP**,
**BTN_TOOL_TRIPLETAP**, **BTN_TOOL_QUADTAP** and **BTN_TOOL_QUINTTAP**
events for all touches for backwards compatibility. libinput ignores these
events if the touchpad can track touches correctly.
.. _touchpads_touch_partial_mt:
......@@ -125,8 +125,8 @@ 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
available.
:ref:`thumb-detection` or :ref:`palm_detection` may be limited if only two
slots are available.
.. _touchpads_touch_semi_mt:
......@@ -144,7 +144,7 @@ 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`.
Semi-mt are labelled by the kernel with the @c INPUT_PROP_SEMI_MT input
Semi-mt are labelled by the kernel with the **INPUT_PROP_SEMI_MT** input
property.
.. _touchpads_mis:
......
......@@ -12,7 +12,7 @@ the space bar.
.. figure:: button-scrolling.svg
:align: center
A trackpoint"
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
......
......@@ -106,3 +106,49 @@ 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.
------------------------------------------------------------------------------
Device types
------------------------------------------------------------------------------
libinput handles all common devices used to interact with a desktop system.
This includes mice, keyboards, touchscreens, touchpads and graphics tablets.
libinput does not expose the device type to the caller, it solely provides
capabilities and the attached features (see
`this blog post <https://who-t.blogspot.com/2015/06/libinput-and-lack-of-device-types.html>`_).
For example, a touchpad in libinput is a device that provides pointer
events, gestures and has a number of :ref:`config_options` such as
:ref:`tapping`. A caller may present the device as touchpad to the user, or
simply as device with a config knob to enable or disable tapping.
..............................................................................
Handled device types
..............................................................................
- :ref:`Touchpads`
- Touchscreens
- Mice
- Keyboards
- Virtual absolute pointing devices such as those used by QEMU or VirtualBox
- Switches (Lid Switch and Tablet Mode switch)
- Graphics tablets
- :ref:`Trackpoints`
If a device falls into one of the above categories but does not work as
expected, please :ref:`file a bug <reporting_bugs>`.
..............................................................................
Unhandled device types
..............................................................................
libinput does not handle some devices. The primary reason is that these
device have no clear interaction with a desktop environment.
Joysticks:
Joysticks have one or more axes and one or more buttons. Beyond that it is
difficult to find common ground between joysticks and much of the
interaction is application-specific, not system-specific. libinput does not
provide support for joysticks for that reason, any abstraction libinput
would provide for joysticks would be so generic that libinput would
merely introduce complexity and processing delays for no real benefit.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment