From 6304dc1b19a393ab888b356ed6a82af3bd372d9b Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Tue, 31 Jul 2018 18:17:48 +1000 Subject: [PATCH] doc/user: more documentation cleanups and fixes Signed-off-by: Peter Hutterer --- doc/user/button_debouncing.rst | 9 +- doc/user/clickpad-softbuttons.rst | 85 ++++---- doc/user/features.rst | 2 +- doc/user/gestures.rst | 72 +++---- doc/user/meson.build | 3 + doc/user/svg/software-buttons-conditions.svg | 210 +++++++++++++++++++ doc/user/svg/software-buttons-thumbpress.svg | 107 ++++++++++ doc/user/svg/software-buttons-visualized.svg | 146 +++++++++++++ doc/user/what-is-libinput.rst | 13 +- src/libinput.h | 13 +- 10 files changed, 571 insertions(+), 89 deletions(-) create mode 100644 doc/user/svg/software-buttons-conditions.svg create mode 100644 doc/user/svg/software-buttons-thumbpress.svg create mode 100644 doc/user/svg/software-buttons-visualized.svg diff --git a/doc/user/button_debouncing.rst b/doc/user/button_debouncing.rst index 3056a0df0..3630423b0 100644 --- a/doc/user/button_debouncing.rst +++ b/doc/user/button_debouncing.rst @@ -32,8 +32,8 @@ immediately and most release events are delivered immediately. The does not enable this method unless a faulty event sequence is detected. A message is printed to the log when spurious deboucing was detected. -Note that libinput's debouncing intended to correct hardware damage or -substandard hardware. Debouncing is also used as an accessibility feature +libinput's debouncing is supposed to correct hardware damage or +substandard hardware. Debouncing also exists as an accessibility feature but the requirements are different. In the accessibility feature, multiple physical key presses, usually caused by involuntary muscle movement, must be filtered to only one key press. This feature must be implemented higher in @@ -49,3 +49,8 @@ correspond to the buttons 'pressed' and 'released' states, respectively. :align: center Diagram illustrating button debouncing" + + +Some devices send events in bursts, erroneously triggering the button +debouncing detection. Please :ref:`file a bug ` if that +occurs for your device. diff --git a/doc/user/clickpad-softbuttons.rst b/doc/user/clickpad-softbuttons.rst index 238e5a330..781aad94a 100644 --- a/doc/user/clickpad-softbuttons.rst +++ b/doc/user/clickpad-softbuttons.rst @@ -4,22 +4,23 @@ Clickpad software button behavior ============================================================================== -Clickpad is the name given to touchpads without physical buttons below the -touchpad. Instead, the whole touchpad acts as a button and left or right -button clicks are distinguished by the location and/or number of fingers on -the touchpad. -("ClickPad" is a trademark by Synaptics Inc.)[http://www.synaptics.com/en/clickpad.php] +"Clickpads" are touchpads without separate physical buttons. Instead, the +whole touchpad acts as a button and left or right button clicks are +distinguished by :ref:`the location of the fingers ` or +the :ref:`number of fingers on the touchpad `. +"ClickPad" is a trademark by `Synaptics Inc. `_ 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 +The kernel marks clickpads with the `INPUT_PROP_BUTTONPAD `_ -property. To perform a right-click on a Clickpad, libinput provides -:ref:`software_buttons` and @ref clickfinger. +property. Without this property, libinput would not know whether a touchpad +is a clickpad or not. 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. +.. note:: The term "click" refers refer to a physical button press + and/or release of the touchpad, the term "button event" refers to + the events generated by libinput in response to a click. .. _software_buttons: @@ -27,10 +28,15 @@ generated by libinput and passed to the caller in response to a click. 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 -events on click. The height of the button area depends on the hardware but -is usually around 10mm. +The bottom of the touchpad is split into three distinct areas generate left, +middle or right button events on click. The height of the button area +depends on the hardware but is usually around 10mm. + +.. figure :: software-buttons-visualized.svg + :align: center + + The locations of the virtual button areas. + Left, right and middle button events can be triggered as follows: @@ -39,34 +45,49 @@ Left, right and middle button events can be triggered as follows: - if a finger is in the right area, a click generates right button events. - if a finger is in the middle area, a click generates middle button events. -The middle button is always centered on the touchpad and smaller in size -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. - .. figure:: software-buttons.svg :align: center - Left, right and middle-button click with software button areas" + Left, right and middle-button click with software button areas + +The middle button is always centered on the touchpad and smaller in size +than the left or right button. The actual size is device-dependent. Many +touchpads do not have visible markings so the exact location of the button +is unfortunately not visibly obvious. -.. 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()**. +.. note:: If :ref:`middle button emulation ` is + enabled on a clickpad, only left and right button areas are + available. If fingers are down in the main area in addition to fingers in the left or right button area, those fingers are are ignored. A release event always releases the buttons logically down, regardless of the current finger position +.. figure:: software-buttons-thumbpress.svg + :align: center + + Only the location of the thumb determines whether it is a left, right or + middle click. + The movement of a finger can alter the button area behavior: - if a finger starts in the main area and moves into the software button area, the software buttons do not apply to that finger -- a finger in the software button area does not move the pointer -- if a finger moves out out of the button area it will control the pointer - if it's the first finger in the main area - once a finger has moved out of the button area, it cannot move back in and trigger a right or middle button event +- a finger moving within the software button area does not move the pointer +- once a finger moves out out of the button area it will control the + pointer (this only applies if there is no other finger down on the + touchpad) + +.. figure:: software-buttons-conditions.svg + :align: center + + **Left:** moving a finger into the right button area does not trigger a + right-button click. + **Right:** moving within the button areas does not generate pointer + motion. On some touchpads, notably the 2015 Lenovo X1 Carbon 3rd series, the very bottom end of the touchpad is outside of the sensor range but it is possible @@ -90,7 +111,7 @@ software-defined button areas. .. figure:: clickfinger.svg :align: center - One, two and three-finger click with Clickfinger behavior" + 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 @@ -100,18 +121,12 @@ the touchpad. .. figure:: clickfinger-distance.svg :align: center - Illustration of the distance detection algorithm" + 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 -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. - .. _special_clickpads: ------------------------------------------------------------------------------ diff --git a/doc/user/features.rst b/doc/user/features.rst index 42f9f5a24..78c9b9682 100644 --- a/doc/user/features.rst +++ b/doc/user/features.rst @@ -6,7 +6,7 @@ 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 +Not all features are user-configurable, some rely on :ref:`device-quirks` to be useful. diff --git a/doc/user/gestures.rst b/doc/user/gestures.rst index 48605af4a..e5dca5289 100644 --- a/doc/user/gestures.rst +++ b/doc/user/gestures.rst @@ -4,42 +4,25 @@ 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 -touchpads support both gestures and any device that may send gesture events -has the **LIBINPUT_DEVICE_CAP_GESTURE** capability set. - -Note that libinput **does not** support gestures on touchscreens, see -:ref:`gestures_touchscreens`. +libinput supports :ref:`gestures_pinch` and :ref:`gestures_swipe` on most +modern touchpads and other indirect touch devices. Note that libinput **does +not** support gestures on touchscreens, see :ref:`gestures_touchscreens`. .. _gestures_lifetime: ------------------------------------------------------------------------------- +----------------------------------------------------------------------------- Lifetime of a gesture ------------------------------------------------------------------------------- +----------------------------------------------------------------------------- + +A gesture starts when the finger position and/or finger motion is +unambiguous as to what gesture to trigger and continues until the first +finger belonging to this gesture is lifted. -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` -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 -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. - -**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** +A single gesture cannot change the finger count. For example, 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 however decide that those gestures are semantically +identical Tand continue the two gestures as one single gesture. .. _gestures_pinch: @@ -59,7 +42,7 @@ to the initial finger position. .. figure:: pinch-gestures.svg :align: center - The pinch and rotate gestures" + 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 @@ -85,7 +68,7 @@ gesture into an action or limit a gesture to specific directions only. .. figure:: swipe-gestures.svg :align: center - The swipe gestures" + 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. @@ -107,14 +90,13 @@ screen as well as the context of those virtual objects: .. figure:: touchscreen-gestures.svg :align: center - Context-sensitivity of touchscreen gestures" + 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 -to zoom. In the right case both fingers are located on a window border, -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. +In the above example, the finger movements are identical but in the left +case both fingers are located within the same window, thus suggesting an +attempt to zoom. In the right case both fingers are located on a window +border, thus suggesting a window movement. libinput has no knowledge of the +window coordinates and thus cannot differentiate the two. .. _gestures_softbuttons: @@ -124,14 +106,14 @@ Gestures with enabled software buttons If the touchpad device is a :ref:`Clickpad `, it is recommended that a caller switches to :ref:`clickfinger`. -Usually fingers placed in a :ref:`software button area ` is not -considered for gestures, resulting in some gestures to be interpreted as -pointer motion or two-finger scroll events. +Usually fingers placed in a :ref:`software button area ` +are not considered for gestures, resulting in some gestures to be +interpreted as pointer motion or two-finger scroll events. .. figure:: pinch-gestures-softbuttons.svg :align: center - Interference of software buttons and pinch gestures" + 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 @@ -161,7 +143,7 @@ determined. .. figure:: gesture-2fg-ambiguity.svg :align: center - Ambiguity of three-finger gestures on two-finger touchpads" + 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. diff --git a/doc/user/meson.build b/doc/user/meson.build index c3403213c..9343201fa 100644 --- a/doc/user/meson.build +++ b/doc/user/meson.build @@ -37,6 +37,9 @@ src_extra = [ 'svg/ptraccel-touchpad.svg', 'svg/ptraccel-trackpoint.svg', 'svg/software-buttons.svg', + 'svg/software-buttons-conditions.svg', + 'svg/software-buttons-thumbpress.svg', + 'svg/software-buttons-visualized.svg', 'svg/swipe-gestures.svg', 'svg/tablet-axes.svg', 'svg/tablet-cintiq24hd-modes.svg', diff --git a/doc/user/svg/software-buttons-conditions.svg b/doc/user/svg/software-buttons-conditions.svg new file mode 100644 index 000000000..9865648ed --- /dev/null +++ b/doc/user/svg/software-buttons-conditions.svg @@ -0,0 +1,210 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/user/svg/software-buttons-thumbpress.svg b/doc/user/svg/software-buttons-thumbpress.svg new file mode 100644 index 000000000..61e546fbe --- /dev/null +++ b/doc/user/svg/software-buttons-thumbpress.svg @@ -0,0 +1,107 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + diff --git a/doc/user/svg/software-buttons-visualized.svg b/doc/user/svg/software-buttons-visualized.svg new file mode 100644 index 000000000..a13f8ca97 --- /dev/null +++ b/doc/user/svg/software-buttons-visualized.svg @@ -0,0 +1,146 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + main area + right button + left button + middle + diff --git a/doc/user/what-is-libinput.rst b/doc/user/what-is-libinput.rst index 20a18d281..ecb97d3ca 100644 --- a/doc/user/what-is-libinput.rst +++ b/doc/user/what-is-libinput.rst @@ -14,11 +14,10 @@ what libinput is **not**. What libinput is ------------------------------------------------------------------------------ -libinput is an input stack for applications that need full input device -processing by commonly used input devices. That includes mice, keyboards, -touchpads, touchscreens and graphics tablets. libinput handles -device-specific quirks and provides an easy-to-use API to receive -events from devices. +libinput is an input stack for processes that need to provide events from +commonly used input devices. That includes mice, keyboards, touchpads, +touchscreens and graphics tablets. libinput handles device-specific quirks +and provides an easy-to-use API to receive events from devices. libinput is designed to handle all input devices available on a system but it is possible to limit which devices libinput has access to. @@ -32,6 +31,10 @@ those features. One example for this are the top software buttons on the touchpad in the Lenovo T440. While there may be use-cases for providing top software buttons on other devices, libinput does not do so. +`This introductory blog post from 2015 +`_ +describes some of the motivations. + .. _what_libinput_is_not: ------------------------------------------------------------------------------ diff --git a/src/libinput.h b/src/libinput.h index 5af3bfc02..4bd90b286 100644 --- a/src/libinput.h +++ b/src/libinput.h @@ -912,6 +912,13 @@ libinput_event_get_touch_event(struct libinput_event *event); * Return the gesture event that is this input event. If the event type does * not match the gesture event types, this function returns NULL. * + * 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 + * LIBINPUT_EVENT_GESTURE_PINCH_BEGIN 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. + * * The inverse of this function is libinput_event_gesture_get_base_event(). * * @return A gesture event, or NULL for other events @@ -1634,7 +1641,11 @@ libinput_event_gesture_get_base_event(struct libinput_event_gesture *event); * to differentiate between 3 or 4 finger swipes. * * This function can be called on all gesture events and the returned finger - * count value will not change during a sequence. + * count value 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. * * @return the number of fingers used for a gesture */