diff options
| author | Peter Hutterer <peter.hutterer@who-t.net> | 2017-05-01 19:58:13 +1000 |
|---|---|---|
| committer | Peter Hutterer <peter.hutterer@who-t.net> | 2017-05-02 15:32:19 +1000 |
| commit | 2d032019b6a46ae0ce837137a4890fc2f6409c7c (patch) | |
| tree | 8a00392cd3d8aef31163d567a41180ae7ada789b /doc | |
| parent | 2b867feab754ff19dc7cdd694ef74d1d63982e62 (diff) | |
doc: document the event timestamps
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 1 | ||||
| -rw-r--r-- | doc/page-hierarchy.dox | 3 | ||||
| -rw-r--r-- | doc/timestamps.dox | 36 |
3 files changed, 39 insertions, 1 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 5391f22..382f64d 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -27,6 +27,7 @@ header_files = \ $(srcdir)/tablet-support.dox \ $(srcdir)/tapping.dox \ $(srcdir)/test-suite.dox \ + $(srcdir)/timestamps.dox \ $(srcdir)/tools.dox \ $(srcdir)/touchpad-jumping-cursors.dox \ $(srcdir)/touchpad-pressure.dox \ diff --git a/doc/page-hierarchy.dox b/doc/page-hierarchy.dox index 65749fe..1f0b735 100644 --- a/doc/page-hierarchy.dox +++ b/doc/page-hierarchy.dox @@ -24,10 +24,11 @@ - @subpage tablet-support -@page general General setup +@page general General - @subpage udev_config - @subpage seats +- @subpage timestamps @page misc Users diff --git a/doc/timestamps.dox b/doc/timestamps.dox new file mode 100644 index 0000000..a823c00 --- /dev/null +++ b/doc/timestamps.dox @@ -0,0 +1,36 @@ +/** + +@page timestamps Timestamps + +@section event_timestamps Event timestamps + +Most libinput events provide a timestamp in millisecond and/or microsecond +resolution. These timestamp usually increase monotonically, but libinput +does not guarantee that this always the case. In other words, it is possible +to receive an event with a timestamp earlier than the previous event. + +For example, if a touchpad has @ref tapping enabled, a button event may have a +lower timestamp than an event from a different device. Tapping requires the +use of timeouts to detect multi-finger taps and/or @ref tapndrag. + +Consider the following event sequences from a touchpad and a mouse: + +<pre> +Time Touchpad Mouse +--------------------------------- +t1 finger down +t2 finger up +t3 movement +t4 tap timeout +</pre> + +For this event sequence, the first event to be sent to a caller is in +response to the mouse movement: an event of type @ref +LIBINPUT_EVENT_POINTER_MOTION with the timestamp t3. +Once the timeout expires at t4, libinput generates an event of +@ref LIBINPUT_EVENT_POINTER_BUTTON (press) with a timestamp t1 and an event +@ref LIBINPUT_EVENT_POINTER_BUTTON (release) with a timestamp t2. + +Thus, the caller gets events with timestamps in the order t3, t1, t2, +despite t3 > t2 > t1. +*/ |