| 1 |
.. _clickpad_softbuttons: |
| 2 |
|
| 3 |
============================================================================== |
| 4 |
Clickpad software button behavior |
| 5 |
============================================================================== |
| 6 |
|
| 7 |
"Clickpads" are touchpads without separate physical buttons. Instead, the |
| 8 |
whole touchpad acts as a button and left or right button clicks are |
| 9 |
distinguished by :ref:`the location of the fingers <software_buttons>` or |
| 10 |
the :ref:`number of fingers on the touchpad <clickfinger>`. |
| 11 |
"ClickPad" is a trademark by `Synaptics Inc. <http://www.synaptics.com/en/clickpad.php>`_ |
| 12 |
but for simplicity we refer to any touchpad with the above feature as Clickpad, |
| 13 |
regardless of the manufacturer. |
| 14 |
|
| 15 |
The kernel marks clickpads with the |
| 16 |
`INPUT_PROP_BUTTONPAD <https://www.kernel.org/doc/Documentation/input/event-codes.txt>`_ |
| 17 |
property. Without this property, libinput would not know whether a touchpad |
| 18 |
is a clickpad or not. To perform a right-click on a Clickpad, libinput |
| 19 |
provides :ref:`software_buttons` and :ref:`clickfinger`. |
| 20 |
|
| 21 |
.. note:: The term "click" refers refer to a physical button press |
| 22 |
and/or release of the touchpad, the term "button event" refers to |
| 23 |
the events generated by libinput in response to a click. |
| 24 |
|
| 25 |
.. _software_buttons: |
| 26 |
|
| 27 |
------------------------------------------------------------------------------ |
| 28 |
Software button areas |
| 29 |
------------------------------------------------------------------------------ |
| 30 |
|
| 31 |
The bottom of the touchpad is split into three distinct areas generate left, |
| 32 |
middle or right button events on click. The height of the button area |
| 33 |
depends on the hardware but is usually around 10mm. |
| 34 |
|
| 35 |
.. figure :: software-buttons-visualized.svg |
| 36 |
:align: center |
| 37 |
|
| 38 |
The locations of the virtual button areas. |
| 39 |
|
| 40 |
|
| 41 |
Left, right and middle button events can be triggered as follows: |
| 42 |
|
| 43 |
- if a finger is in the main area or the left button area, a click generates |
| 44 |
left button events. |
| 45 |
- if a finger is in the right area, a click generates right button events. |
| 46 |
- if a finger is in the middle area, a click generates middle button events. |
| 47 |
|
| 48 |
.. figure:: software-buttons.svg |
| 49 |
:align: center |
| 50 |
|
| 51 |
Left, right and middle-button click with software button areas |
| 52 |
|
| 53 |
The middle button is always centered on the touchpad and smaller in size |
| 54 |
than the left or right button. The actual size is device-dependent. Many |
| 55 |
touchpads do not have visible markings so the exact location of the button |
| 56 |
is unfortunately not visibly obvious. |
| 57 |
|
| 58 |
.. note:: If :ref:`middle button emulation <middle_button_emulation>` is |
| 59 |
enabled on a clickpad, only left and right button areas are |
| 60 |
available. |
| 61 |
|
| 62 |
If fingers are down in the main area in addition to fingers in the |
| 63 |
left or right button area, those fingers are are ignored. |
| 64 |
A release event always releases the buttons logically down, regardless of |
| 65 |
the current finger position |
| 66 |
|
| 67 |
.. figure:: software-buttons-thumbpress.svg |
| 68 |
:align: center |
| 69 |
|
| 70 |
Only the location of the thumb determines whether it is a left, right or |
| 71 |
middle click. |
| 72 |
|
| 73 |
The movement of a finger can alter the button area behavior: |
| 74 |
|
| 75 |
- if a finger starts in the main area and moves into the software button |
| 76 |
area, the software buttons do not apply to that finger |
| 77 |
- once a finger has moved out of the button area, it cannot move back in and |
| 78 |
trigger a right or middle button event |
| 79 |
- a finger moving within the software button area does not move the pointer |
| 80 |
- once a finger moves out out of the button area it will control the |
| 81 |
pointer (this only applies if there is no other finger down on the |
| 82 |
touchpad) |
| 83 |
|
| 84 |
.. figure:: software-buttons-conditions.svg |
| 85 |
:align: center |
| 86 |
|
| 87 |
**Left:** moving a finger into the right button area does not trigger a |
| 88 |
right-button click. |
| 89 |
**Right:** moving within the button areas does not generate pointer |
| 90 |
motion. |
| 91 |
|
| 92 |
On some touchpads, notably the 2015 Lenovo X1 Carbon 3rd series, the very |
| 93 |
bottom end of the touchpad is outside of the sensor range but it is possible |
| 94 |
to trigger a physical click there. To libinput, the click merely shows up as |
| 95 |
a left button click without any positional finger data and it is |
| 96 |
impossible to determine whether it is a left or a right click. libinput |
| 97 |
ignores such button clicks, this behavior is intentional. |
| 98 |
|
| 99 |
.. _clickfinger: |
| 100 |
|
| 101 |
------------------------------------------------------------------------------ |
| 102 |
Clickfinger behavior |
| 103 |
------------------------------------------------------------------------------ |
| 104 |
|
| 105 |
This is the default behavior on Apple touchpads. Here, a left, right, middle |
| 106 |
button event is generated when one, two, or three fingers are held down on the |
| 107 |
touchpad when a physical click is generated, given the default mapping. The |
| 108 |
location of the fingers does not matter and there are no software-defined |
| 109 |
button areas. It is possible to swap right and middle buttons, the same way as |
| 110 |
with :ref:`tapping <tapping>`. |
| 111 |
|
| 112 |
.. figure:: clickfinger.svg |
| 113 |
:align: center |
| 114 |
|
| 115 |
One, two and three-finger click with Clickfinger behavior |
| 116 |
|
| 117 |
On some touchpads, libinput imposes a limit on how the fingers may be placed |
| 118 |
on the touchpad. In the most common use-case this allows for a user to |
| 119 |
trigger a click with the thumb while leaving the pointer-moving finger on |
| 120 |
the touchpad. |
| 121 |
|
| 122 |
.. figure:: clickfinger-distance.svg |
| 123 |
:align: center |
| 124 |
|
| 125 |
Illustration of the distance detection algorithm |
| 126 |
|
| 127 |
In the illustration above the red area marks the proximity area around the |
| 128 |
first finger. Since the thumb is outside of that area libinput considers the |
| 129 |
click a single-finger click rather than a two-finger click. |
| 130 |
|
| 131 |
.. _special_clickpads: |
| 132 |
|
| 133 |
------------------------------------------------------------------------------ |
| 134 |
Special Clickpads |
| 135 |
------------------------------------------------------------------------------ |
| 136 |
|
| 137 |
The Lenovo \*40 series laptops have a clickpad that provides two software button sections, one at |
| 138 |
the top and one at the bottom. See :ref:`Lenovo \*40 series touchpad support <t440_support>` |
| 139 |
for details on the top software button. |
| 140 |
|
| 141 |
Some Clickpads, notably some Cypress ones, perform right button detection in |
| 142 |
firmware and appear to userspace as if the touchpad had physical buttons. |
| 143 |
While physically clickpads, these are not handled by the software and |
| 144 |
treated like traditional touchpads. |