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 | |
| parent | 2b867feab754ff19dc7cdd694ef74d1d63982e62 (diff) | |
doc: document the event timestamps
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
| -rw-r--r-- | doc/Makefile.am | 1 | ||||
| -rw-r--r-- | doc/page-hierarchy.dox | 3 | ||||
| -rw-r--r-- | doc/timestamps.dox | 36 | ||||
| -rw-r--r-- | src/libinput.h | 42 |
4 files changed, 81 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. +*/ diff --git a/src/libinput.h b/src/libinput.h index 430fe18..54bbc7f 100644 --- a/src/libinput.h +++ b/src/libinput.h @@ -972,6 +972,9 @@ libinput_event_device_notify_get_base_event(struct libinput_event_device_notify /** * @ingroup event_keyboard * + * @note Timestamps may not always increase. See @ref event_timestamps for + * details. + * * @return The event time for this event */ uint32_t @@ -980,6 +983,9 @@ libinput_event_keyboard_get_time(struct libinput_event_keyboard *event); /** * @ingroup event_keyboard * + * @note Timestamps may not always increase. See @ref event_timestamps for + * details. + * * @return The event time for this event in microseconds */ uint64_t @@ -1035,6 +1041,9 @@ libinput_event_keyboard_get_seat_key_count( /** * @ingroup event_pointer * + * @note Timestamps may not always increase. See @ref event_timestamps for + * details. + * * @return The event time for this event */ uint32_t @@ -1043,6 +1052,9 @@ libinput_event_pointer_get_time(struct libinput_event_pointer *event); /** * @ingroup event_pointer * + * @note Timestamps may not always increase. See @ref event_timestamps for + * details. + * * @return The event time for this event in microseconds */ uint64_t @@ -1400,6 +1412,9 @@ libinput_event_pointer_get_base_event(struct libinput_event_pointer *event); /** * @ingroup event_touch * + * @note Timestamps may not always increase. See @ref event_timestamps for + * details. + * * @return The event time for this event */ uint32_t @@ -1408,6 +1423,9 @@ libinput_event_touch_get_time(struct libinput_event_touch *event); /** * @ingroup event_touch * + * @note Timestamps may not always increase. See @ref event_timestamps for + * details. + * * @return The event time for this event in microseconds */ uint64_t @@ -1564,6 +1582,9 @@ libinput_event_touch_get_base_event(struct libinput_event_touch *event); /** * @ingroup event_gesture * + * @note Timestamps may not always increase. See @ref event_timestamps for + * details. + * * @return The event time for this event */ uint32_t @@ -1572,6 +1593,9 @@ libinput_event_gesture_get_time(struct libinput_event_gesture *event); /** * @ingroup event_gesture * + * @note Timestamps may not always increase. See @ref event_timestamps for + * details. + * * @return The event time for this event in microseconds */ uint64_t @@ -2300,6 +2324,9 @@ libinput_event_tablet_tool_get_seat_button_count(struct libinput_event_tablet_to /** * @ingroup event_tablet * + * @note Timestamps may not always increase. See @ref event_timestamps for + * details. + * * @param event The libinput tablet tool event * @return The event time for this event */ @@ -2309,6 +2336,9 @@ libinput_event_tablet_tool_get_time(struct libinput_event_tablet_tool *event); /** * @ingroup event_tablet * + * @note Timestamps may not always increase. See @ref event_timestamps for + * details. + * * @param event The libinput tablet tool event * @return The event time for this event in microseconds */ @@ -2735,6 +2765,9 @@ libinput_event_tablet_pad_get_mode_group(struct libinput_event_tablet_pad *event /** * @ingroup event_tablet * + * @note Timestamps may not always increase. See @ref event_timestamps for + * details. + * * @param event The libinput tablet pad event * @return The event time for this event */ @@ -2744,6 +2777,9 @@ libinput_event_tablet_pad_get_time(struct libinput_event_tablet_pad *event); /** * @ingroup event_tablet_pad * + * @note Timestamps may not always increase. See @ref event_timestamps for + * details. + * * @param event The libinput tablet pad event * @return The event time for this event in microseconds */ @@ -2799,6 +2835,9 @@ libinput_event_switch_get_base_event(struct libinput_event_switch *event); /** * @ingroup event_switch * + * @note Timestamps may not always increase. See @ref event_timestamps for + * details. + * * @param event The libinput switch event * @return The event time for this event */ @@ -2808,6 +2847,9 @@ libinput_event_switch_get_time(struct libinput_event_switch *event); /** * @ingroup event_switch * + * @note Timestamps may not always increase. See @ref event_timestamps for + * details. + * * @param event The libinput switch event * @return The event time for this event in microseconds */ |