clickpad-softbuttons.dox 4.99 KB
Newer Older
Peter Hutterer's avatar
Peter Hutterer committed
@page clickpad_softbuttons Clickpad software button behavior
3 4 5 6 7

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="">"ClickPad" is
Peter Hutterer's avatar
Peter Hutterer committed
a trademark by Synaptics Inc.</a> but for simplicity we refer to any
9 10
touchpad with the above feature as Clickpad, regardless of the manufacturer.

Peter Hutterer's avatar
Peter Hutterer committed
11 12 13 14
A clickpad is always marked with the <a
href="">INPUT_PROP_BUTTONPAD</a> property.
To perform a right-click on a Clickpad, libinput provides @ref
software_buttons and @ref clickfinger.

Peter Hutterer's avatar
Peter Hutterer committed
16 17 18
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.

Peter Hutterer's avatar
Peter Hutterer committed
@section software_buttons Software button areas

Peter Hutterer's avatar
Peter Hutterer committed
On most clickpads, this is the default behavior. The bottom of the touchpad
23 24 25
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.

Peter Hutterer's avatar
Peter Hutterer committed
27 28 29 30
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.
31 32 33 34 35 36
- 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.
Peter Hutterer's avatar
Peter Hutterer committed

38 39
@image html software-buttons.svg "Left, right and middle-button click with software button areas"

40 41 42 43
@note If middle button emulation is enabled on a clickpad, only left and right
button areas are available. For more details, see

Peter Hutterer's avatar
Peter Hutterer committed
44 45 46 47 48 49 50 51 52 53 54
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
Peter Hutterer's avatar
Peter Hutterer committed
56 57
  trigger a right or middle button event

58 59 60 61 62 63 64
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.

Peter Hutterer's avatar
Peter Hutterer committed
65 66 67 68 69 70 71 72
@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.

73 74
@image html clickfinger.svg "One, two and three-finger click with Clickfinger behavior"

75 76 77 78 79 80 81 82 83 84
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.
Peter Hutterer's avatar
Peter Hutterer committed

86 87 88 89 90 91
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.

Peter Hutterer's avatar
Peter Hutterer committed
92 93 94 95 96 97 98 99 100 101
@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.

Peter Hutterer's avatar
Peter Hutterer committed