1 2.. _button_debouncing: 3 4============================================================================== 5Button debouncing 6============================================================================== 7 8Physical buttons experience wear-and-tear with usage. On some devices this 9can result in an effect called "contact bouncing" or "chatter". This effect 10can cause the button to send multiple events within a short time frame, even 11though the user only pressed or clicked the button once. This effect can be 12counteracted by "debouncing" the buttons, usually by ignoring erroneous 13events. 14 15libinput provides two methods of debouncing buttons, referred to as the 16"bounce" and "spurious" methods: 17 18- In the "bounce" method, libinput monitors hardware bouncing on button 19 state changes, i.e. when a user clicks or releases a button. For example, 20 if a user presses a button but the hardware generates a 21 press-release-press sequence in quick succession, libinput ignores the 22 release and second press event. This method is always enabled. 23- in the "spurious" method, libinput detects spurious releases of a button 24 while the button is physically held down by the user. These releases are 25 immediately followed by a press event. libinput monitors for these events 26 and ignores the release and press event. This method is disabled by 27 default and enables once libinput detects the first faulty event sequence. 28 29The "bounce" method guarantees that all press events are delivered 30immediately and most release events are delivered immediately. The 31"spurious" method requires that release events are delayed, libinput thus 32does not enable this method unless a faulty event sequence is detected. A 33message is printed to the log when spurious deboucing was detected. 34 35libinput's debouncing is supposed to correct hardware damage or 36substandard hardware. Debouncing also exists as an accessibility feature 37but the requirements are different. In the accessibility feature, multiple 38physical key presses, usually caused by involuntary muscle movement, must be 39filtered to only one key press. This feature must be implemented higher in 40the stack, libinput is limited to hardware debouncing. 41 42Below is an illustration of the button debouncing modes to show the relation 43of the physical button state and the application state. Where applicable, an 44extra line is added to show the timeouts used by libinput that 45affect the button state handling. The waveform's high and low states 46correspond to the buttons 'pressed' and 'released' states, respectively. 47 48.. figure:: button-debouncing-wave-diagram.svg 49 :align: center 50 51 Diagram illustrating button debouncing 52 53 54Some devices send events in bursts, erroneously triggering the button 55debouncing detection. Please :ref:`file a bug <reporting_bugs>` if that 56occurs for your device. 57
