mirror of
https://gitlab.freedesktop.org/libinput/libinput.git
synced 2025-12-20 05:40:04 +01:00
de994d135e
The current debouncing code monitors events and switches on when events are too close together. From then on, any event can be delayed. Vicente Bergas provided an algorithm that avoids most of these delays: on a button state change we now forward the change without delay but start a timer. If the button changes state during that timer, the changes are ignored. On timer expiry, events are sent to match the hardware state with the client's view of the device. This is only done if needed. Thus, a press-release sequence of: PRP sends a single press event, a sequence of PRPR sends press and then the release at the end of the timeout. The timeout is short enough that the delay should not be noticeable. This new mode is called the 'bounce' mode. The old mode is now referred to as 'spurious' mode and only covers the case of a button held down that loses contact. It works as before, monitoring a button for these spurious contact losses and switching on. When on, button release events are delayed as before. The whole button debouncing moves to a state machine which makes debugging a lot easier. See the accompanying SVG for the diagram. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
47 lines
2.4 KiB
Text
47 lines
2.4 KiB
Text
/**
|
|
|
|
@page button_debouncing Button debouncing
|
|
|
|
Physical buttons experience wear-and-tear with usage. On some devices this
|
|
can result in an effect called "contact bouncing" or "chatter". This effect
|
|
can cause the button to send multiple events within a short time frame, even
|
|
though the user only pressed or clicked the button once. This effect can be
|
|
counteracted by "debouncing" the buttons, usually by ignoring erroneous
|
|
events.
|
|
|
|
libinput provides two methods of debouncing buttons, referred to as the
|
|
"bounce" and "spurious" methods:
|
|
|
|
- In the "bounce" method, libinput monitors hardware bouncing on button
|
|
state changes, i.e. when a user clicks or releases a button. For example,
|
|
if a user presses a button but the hardware generates a
|
|
press-release-press sequence in quick succession, libinput ignores the
|
|
release and second press event. This method is always enabled.
|
|
- in the "spurious" method, libinput detects spurious releases of a button
|
|
while the button is physically held down by the user. These releases are
|
|
immediately followed by a press event. libinput monitors for these events
|
|
and ignores the release and press event. This method is disabled by
|
|
default and enables once libinput detects the first faulty event sequence.
|
|
|
|
The "bounce" method guarantees that all press events are delivered
|
|
immediately and most release events are delivered immediately. The
|
|
"spurious" method requires that release events are delayed, libinput thus
|
|
does not enable this method unless a faulty event sequence is detected. A
|
|
message is printed to the log when spurious deboucing was detected.
|
|
|
|
Note that libinput's debouncing intended to correct hardware damage or
|
|
substandard hardware. Debouncing is also used as an accessibility feature
|
|
but the requirements are different. In the accessibility feature, multiple
|
|
physical key presses, usually caused by involuntary muscle movement, must be
|
|
filtered to only one key press. This feature must be implemented higher in
|
|
the stack, libinput is limited to hardware debouncing.
|
|
|
|
Below is an illustration of the button debouncing modes to show the relation
|
|
of the physical button state and the application state. Where applicable, an
|
|
extra line is added to show the timeouts used by libinput that
|
|
affect the button state handling. The waveform's high and low states
|
|
correspond to the buttons 'pressed' and 'released' states, respectively.
|
|
|
|
@image html button-debouncing-wave-diagram.svg "Diagram illustrating button debouncing"
|
|
|
|
*/
|