From 8b60578c8f2eec7c4cf0ef7d19792adfa8875468 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Fri, 13 Mar 2015 09:56:36 +1000 Subject: [PATCH] Expand documentation on touch events, listing what is permitted when Signed-off-by: Peter Hutterer Reviewed-by: Hans de Goede --- src/libinput.h | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/src/libinput.h b/src/libinput.h index f978b37f..356c1bf0 100644 --- a/src/libinput.h +++ b/src/libinput.h @@ -839,8 +839,11 @@ libinput_event_touch_get_seat_slot(struct libinput_event_touch *event); * the top left corner of the device. To get the corresponding output screen * coordinate, use libinput_event_touch_get_x_transformed(). * - * @note this function should only be called for @ref - * LIBINPUT_EVENT_TOUCH_DOWN and @ref LIBINPUT_EVENT_TOUCH_MOTION. + * For events not of type @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref + * LIBINPUT_EVENT_TOUCH_MOTION, this function returns 0. + * + * @note It is an application bug to call this function for events of type + * @ref LIBINPUT_EVENT_TOUCH_DOWN or @ref LIBINPUT_EVENT_TOUCH_MOTION. * * @param event The libinput touch event * @return The current absolute x coordinate @@ -855,10 +858,11 @@ libinput_event_touch_get_x(struct libinput_event_touch *event); * the top left corner of the device. To get the corresponding output screen * coordinate, use libinput_event_touch_get_y_transformed(). * - * For @ref LIBINPUT_EVENT_TOUCH_UP 0 is returned. + * For events not of type @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref + * LIBINPUT_EVENT_TOUCH_MOTION, this function returns 0. * - * @note this function should only be called for @ref LIBINPUT_EVENT_TOUCH_DOWN and - * @ref LIBINPUT_EVENT_TOUCH_MOTION. + * @note It is an application bug to call this function for events of type + * @ref LIBINPUT_EVENT_TOUCH_DOWN or @ref LIBINPUT_EVENT_TOUCH_MOTION. * * @param event The libinput touch event * @return The current absolute y coordinate @@ -872,8 +876,11 @@ libinput_event_touch_get_y(struct libinput_event_touch *event); * Return the current absolute x coordinate of the touch event, transformed to * screen coordinates. * - * @note this function should only be called for @ref - * LIBINPUT_EVENT_TOUCH_DOWN and @ref LIBINPUT_EVENT_TOUCH_MOTION. + * For events not of type @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref + * LIBINPUT_EVENT_TOUCH_MOTION, this function returns 0. + * + * @note It is an application bug to call this function for events of type + * @ref LIBINPUT_EVENT_TOUCH_DOWN or @ref LIBINPUT_EVENT_TOUCH_MOTION. * * @param event The libinput touch event * @param width The current output screen width @@ -889,8 +896,11 @@ libinput_event_touch_get_x_transformed(struct libinput_event_touch *event, * Return the current absolute y coordinate of the touch event, transformed to * screen coordinates. * - * @note this function should only be called for @ref - * LIBINPUT_EVENT_TOUCH_DOWN and @ref LIBINPUT_EVENT_TOUCH_MOTION. + * For events not of type @ref LIBINPUT_EVENT_TOUCH_DOWN, @ref + * LIBINPUT_EVENT_TOUCH_MOTION, this function returns 0. + * + * @note It is an application bug to call this function for events of type + * @ref LIBINPUT_EVENT_TOUCH_DOWN or @ref LIBINPUT_EVENT_TOUCH_MOTION. * * @param event The libinput touch event * @param height The current output screen height