1.. _palm_detection: 2 3============================================================================== 4Palm detection 5============================================================================== 6 7Palm detection tries to identify accidental touches while typing, while 8using the trackpoint and/or during general use of the touchpad area. 9 10On most laptops typing on the keyboard generates accidental touches on the 11touchpad with the palm (usually the area below the thumb). This can lead to 12cursor jumps or accidental clicks. On large touchpads, the palm may also 13touch the bottom edges of the touchpad during normal interaction. 14 15Interference from a palm depends on the size of the touchpad and the position 16of the user's hand. Data from touchpads showed that almost all palm events 17during tying on a Lenovo T440 happened in the left-most and right-most 5% of 18the touchpad. The T440 series has one of the largest touchpads, other 19touchpads are less affected by palm touches. 20 21libinput has multiple ways of detecting a palm, each of which depends on 22hardware-specific capabilities. 23 24- :ref:`palm_tool` 25- :ref:`palm_pressure` 26- :ref:`palm_touch_size` 27- :ref:`palm_exclusion_zones` 28- :ref:`trackpoint-disabling` 29- :ref:`disable-while-typing` 30- :ref:`disable-while-trackpointing` 31- :ref:`stylus-touch-arbitration` 32 33Palm detection is always enabled, with the exception of 34disable-while-typing. 35 36.. _palm_tool: 37 38------------------------------------------------------------------------------ 39Palm detection based on firmware labelling 40------------------------------------------------------------------------------ 41 42Some devices provide palm detection in the firmware, forwarded by the kernel 43as the ``EV_ABS/ABS_MT_TOOL`` axis with a value of ``MT_TOOL_PALM`` 44(whenever a palm is detected). libinput honors that value and switches that 45touch to a palm. 46 47.. _palm_pressure: 48 49------------------------------------------------------------------------------ 50Palm detection based on pressure 51------------------------------------------------------------------------------ 52 53The simplest form of palm detection labels a touch as palm when the pressure 54value goes above a certain threshold. This threshold is usually high enough 55that it cannot be triggered by a finger movement. One a touch is labelled as 56palm based on pressure, it will remain so even if the pressure drops below 57the threshold again. This ensures that a palm remains a palm even when the 58pressure changes as the user is typing. 59 60For some information on how to detect pressure on a touch and debug the 61pressure ranges, see :ref:`touchpad_pressure`. 62 63.. _palm_touch_size: 64 65------------------------------------------------------------------------------ 66Palm detection based on touch size 67------------------------------------------------------------------------------ 68 69On touchpads that support the ``ABS_MT_TOUCH_MAJOR`` axes, libinput can perform 70palm detection based on the size of the touch ellipse. This works similar to 71the pressure-based palm detection in that a touch is labelled as palm when 72it exceeds the (device-specific) touch size threshold. 73 74For some information on how to detect the size of a touch and debug the 75touch size ranges, see :ref:`touchpad_pressure`. 76 77.. _palm_exclusion_zones: 78 79------------------------------------------------------------------------------ 80Palm exclusion zones 81------------------------------------------------------------------------------ 82 83libinput enables palm detection on the left, right and top edges of the 84touchpad. Two exclusion zones are defined on the left and right edge of the 85touchpad. If a touch starts in the exclusion zone, it is considered a palm 86and the touch point is ignored. However, for fast cursor movements across 87the screen, it is common for a finger to start inside an exclusion zone and 88move rapidly across the touchpad. libinput detects such movements and avoids 89palm detection on such touch sequences. 90 91Another exclusion zone is defined on the top edge of the touchpad. As with 92the edge zones, libinput detects vertical movements out of the edge zone and 93avoids palm detection on such touch sequences. 94 95A touch starting in the exclusion zone does not trigger a tap (see 96:ref:`tapping`). 97 98In the diagram below, the exclusion zones are painted red. 99Touch 'A' starts inside the exclusion zone and moves 100almost vertically. It is considered a palm and ignored for cursor movement, 101despite moving out of the exclusion zone. 102 103Touch 'B' starts inside the exclusion zone but moves horizontally out of the 104zone. It is considered a valid touch and controls the cursor. 105 106Touch 'C' occurs in the exclusion zone. Despite being a tapping motion, it does 107not generate an emulated button event. 108 109.. figure:: palm-detection.svg 110 :align: center 111 112.. _trackpoint-disabling: 113 114------------------------------------------------------------------------------ 115Palm detection during trackpoint use 116------------------------------------------------------------------------------ 117 118If a device provides a 119`trackpoint <http://en.wikipedia.org/wiki/Pointing_stick>`_, it is 120usually located above the touchpad. This increases the likelihood of 121accidental touches whenever the trackpoint is used. 122 123libinput disables the touchpad whenever it detects trackpoint activity for a 124certain timeout until after trackpoint activity stops. Touches generated 125during this timeout will not move the pointer, and touches started during 126this timeout will likewise not move the pointer (allowing for a user to rest 127the palm on the touchpad while using the trackstick). 128If the touchpad is disabled, the :ref:`top software buttons <t440_support>` 129remain enabled. 130 131.. _disable-while-typing: 132 133------------------------------------------------------------------------------ 134Disable-while-typing 135------------------------------------------------------------------------------ 136 137libinput automatically disables the touchpad for a timeout after a key 138press, a feature traditionally referred to as "disable while typing" and 139previously available through the 140`syndaemon(1) <http://linux.die.net/man/1/syndaemon>`_ command. libinput does 141not require an external command and the feature is currently enabled for all 142touchpads but will be reduced in the future to only apply to touchpads where 143finger width or pressure data is unreliable. 144 145Notable behaviors of libinput's disable-while-typing feature: 146 147- Two different timeouts are used, after a single key press the timeout is 148 short to ensure responsiveness. After multiple key events, the timeout is 149 longer to avoid accidental pointer manipulation while typing. 150- Some keys do not trigger the timeout, specifically some modifier keys 151 (Ctrl, Alt, Shift, and Fn). Actions such as Ctrl + click thus stay 152 responsive. 153- Touches started while typing do not control the cursor even after typing 154 has stopped, it is thus possible to rest the palm on the touchpad while 155 typing. 156- Physical buttons work even while the touchpad is disabled. This includes 157 :ref:`software-emulated buttons <t440_support>`. 158- libinput pairs touchpads and keyboards for the disable-while-typing 159 feature. In the most common case, the internal touchpad is paired only 160 with the internal keyboard. Typing on an external keyboard will thus not 161 disable the touchpad. Some devices require a :ref:`quirk <device-quirks>` 162 to be correctly paired. 163 164Disable-while-typing can be enabled and disabled by calling 165**libinput_device_config_dwt_set_enabled()**. 166 167.. _disable-while-trackpointing: 168 169------------------------------------------------------------------------------ 170Disable-while-trackpointing 171------------------------------------------------------------------------------ 172 173libinput automatically disables the touchpad for a timeout after the trackpoint 174is moved, a feature referred to as "disable while trackpointing". libinput does 175not require an external command and the feature is currently enabled for all 176touchpads. 177 178Disable-while-trackpointing can be enabled and disabled by calling 179**libinput_device_config_dwtp_set_enabled()**. 180 181.. _stylus-touch-arbitration: 182 183------------------------------------------------------------------------------ 184Stylus-touch arbitration 185------------------------------------------------------------------------------ 186 187A special case of palm detection is touch arbitration on devices that 188support styli. When interacting with a stylus on the screen, parts of the 189hand may touch the surface and trigger touches. As the user is currently 190interacting with the stylus, these touches would interfer with the correct 191working of the stylus. 192 193libinput employs a method similar to :ref:`disable-while-typing` to detect 194these touches and disables the touchpad accordingly. 195 196.. _thumb-detection: 197 198------------------------------------------------------------------------------ 199Thumb detection 200------------------------------------------------------------------------------ 201 202Many users rest their thumb on the touchpad while using the index finger to 203move the finger around. For clicks, often the thumb is used rather than the 204finger. The thumb should otherwise be ignored as a touch, i.e. it should not 205count towards :ref:`clickfinger` and it should not cause a single-finger 206movement to trigger :ref:`twofinger_scrolling`. 207 208libinput uses two triggers for thumb detection: pressure and 209location. A touch exceeding a pressure threshold is considered a thumb if it 210is within the thumb detection zone. 211 212.. note:: "Pressure" on touchpads is synonymous with "contact area." A large touch 213 surface area has a higher pressure and thus hints at a thumb or palm 214 touching the surface. 215 216Pressure readings are unreliable at the far bottom of the touchpad as a 217thumb hanging mostly off the touchpad will have a small surface area. 218libinput has a definitive thumb zone where any touch is considered a resting 219thumb. 220 221.. figure:: thumb-detection.svg 222 :align: center 223 224The picture above shows the two detection areas. In the larger (light red) 225area, a touch is labelled as thumb when it exceeds a device-specific 226pressure threshold. In the lower (dark red) area, a touch is labelled as 227thumb if it remains in that area for a time without moving outside. 228
