mirror of
https://gitlab.freedesktop.org/libinput/libinput.git
synced 2025-12-20 08:00:08 +01:00
0526044f6d
Expose the middle button emulation on software buttons as proper config option. When enabled, remove the middle button software button area. https://bugs.freedesktop.org/show_bug.cgi?id=96663 Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net> Reviewed-by: Hans de Goede <hdegoede@redhat.com>
103 lines
5 KiB
Text
103 lines
5 KiB
Text
/**
|
|
@page clickpad_softbuttons 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. <a href="http://www.synaptics.com/en/clickpad.php">"ClickPad" is
|
|
a trademark by Synaptics Inc.</a> 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 <a
|
|
href="https://www.kernel.org/doc/Documentation/input/event-codes.txt">INPUT_PROP_BUTTONPAD</a> property.
|
|
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.
|
|
|
|
@section software_buttons 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.
|
|
|
|
Left, right and middle button events can be triggered as follows:
|
|
- if a finger is in the main area or the left button area, a click generates
|
|
left button events.
|
|
- 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.
|
|
|
|
@image html software-buttons.svg "Left, right and middle-button click with software button areas"
|
|
|
|
@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().
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
to trigger a physical click there. To libinput, the click merely shows up as
|
|
a left button click without any positional finger data and it is
|
|
impossible to determine whether it is a left or a right click. libinput
|
|
ignores such button clicks, this behavior is intentional.
|
|
|
|
@section clickfinger Clickfinger behavior
|
|
|
|
This is the default behavior on Apple touchpads.
|
|
Here, a left, right, middle button event is generated when one, two, or
|
|
three fingers are held down on the touchpad when a physical click is
|
|
generated. The location of the fingers does not matter and there are no
|
|
software-defined button areas.
|
|
|
|
@image html clickfinger.svg "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
|
|
trigger a click with the thumb while leaving the pointer-moving finger on
|
|
the touchpad.
|
|
|
|
@image html clickfinger-distance.svg "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.
|
|
|
|
@section special_clickpads Special Clickpads
|
|
|
|
The Lenovo *40 series laptops have a clickpad that provides two software button sections, one at
|
|
the top and one at the bottom. See @ref t440_support "Lenovo *40 series touchpad support"
|
|
for details on the top software button.
|
|
|
|
Some Clickpads, notably some Cypress ones, perform right button detection in
|
|
firmware and appear to userspace as if the touchpad had physical buttons.
|
|
While physically clickpads, these are not handled by the software and
|
|
treated like traditional touchpads.
|
|
|
|
*/
|