Debian Codegraph @

doc/user/clickpad-softbuttons.rst

raw
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.