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