From aa866c5a920f47741077d6fac125dc423e671d99 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Thu, 27 Apr 2023 14:24:02 +1000 Subject: [PATCH] Add a few more doxygen comments --- src/libei.h | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++-- src/libeis.h | 2 +- 2 files changed, 98 insertions(+), 3 deletions(-) diff --git a/src/libei.h b/src/libei.h index c838cde..b0403b5 100644 --- a/src/libei.h +++ b/src/libei.h @@ -318,23 +318,93 @@ enum ei_event_type { * logically entered the screen. */ EI_EVENT_DEVICE_START_EMULATING = 200, + /** + * The server stopped emulating events on this device, + * see @ref EIS_EVENT_DEVICE_START_EMULATING. + */ EI_EVENT_DEVICE_STOP_EMULATING, /* These events are only generated on a receiver ei context. */ + + /** + * A relative motion event with delta coordinates in logical pixels or + * mm, depending on the device type. + * + * This event is only generated on a receiver ei context. + */ EI_EVENT_POINTER_MOTION = 300, + + /** + * An absolute motion event with absolute position within the device's + * regions or size, depending on the device type. + * + * This event is only generated on a receiver ei context. + */ EI_EVENT_POINTER_MOTION_ABSOLUTE = 400, + /** + * A button press or release event + * + * This event is only generated on a receiver ei context. + */ EI_EVENT_BUTTON_BUTTON = 500, + /** + * A vertical and/or horizontal scroll event with logical-pixels + * or mm precision, depending on the device type. + * + * This event is only generated on a receiver ei context. + */ EI_EVENT_SCROLL_DELTA = 600, + /** + * An ongoing scroll sequence stopped. + * + * This event is only generated on a receiver ei context. + */ EI_EVENT_SCROLL_STOP, + /** + * An ongoing scroll sequence was cancelled. + * + * This event is only generated on a receiver ei context. + */ EI_EVENT_SCROLL_CANCEL, + /** + * A vertical and/or horizontal scroll event with a discrete range in + * logical scroll steps, like a scroll wheel. + * + * This event is only generated on a receiver ei context. + */ EI_EVENT_SCROLL_DISCRETE, + /** + * A key press or release event + * + * This event is only generated on a receiver ei context. + */ EI_EVENT_KEYBOARD_KEY = 700, + /** + * Event for a single touch set down on the device's logical surface. + * A touch sequence is always down/up with an optional motion event in + * between. On multitouch capable devices, several touchs eqeuences + * may be active at any time. + * + * This event is only generated on a receiver ei context. + */ EI_EVENT_TOUCH_DOWN = 800, + /** + * Event for a single touch released from the device's logical + * surface. + * + * This event is only generated on a receiver ei context. + */ EI_EVENT_TOUCH_UP, + /** + * Event for a single currently-down touch changing position (or other + * properties). + * + * This event is only generated on a receiver ei context. + */ EI_EVENT_TOUCH_MOTION, }; @@ -693,7 +763,7 @@ ei_event_get_device(struct ei_event *event); /** * Return the time for the event of type @ref EI_EVENT_FRAME in microseconds. * - * @note: Only events of type @ref EI_EVENT_FRAME carry a timestamp. For + * @note Only events of type @ref EI_EVENT_FRAME carry a timestamp. For * convenience, the timestamp for other device events is retrofitted by this * library. * @@ -895,7 +965,8 @@ ei_device_get_type(struct ei_device *device); /** * Return true if the device has the requested capability. Device - * capabilities are constant. + * capabilities are constant for the lifetime of the device and always + * a subset of the capabilities bound to by ei_seat_bind_capabilities(). */ bool ei_device_has_capability(struct ei_device *device, @@ -1090,6 +1161,8 @@ ei_device_get_context(struct ei_device *device); * ei_device_start_emulating(). Wraparound must be handled by the EIS * implementation but Callers must ensure that detection of wraparound is * reasonably. + * + * This method is only available on an ei sender context. */ void ei_device_start_emulating(struct ei_device *device, uint32_t sequence); @@ -1097,6 +1170,8 @@ ei_device_start_emulating(struct ei_device *device, uint32_t sequence); /** * Notify the EIS implementation that the given device is no longer sending * events. See ei_device_start_emulating() for details. + * + * This method is only available on an ei sender context. */ void ei_device_stop_emulating(struct ei_device *device); @@ -1112,6 +1187,8 @@ ei_device_stop_emulating(struct ei_device *device); * * @note libei does not prevent a caller from passing in a future time but it * is strongly recommended that this is avoided by the caller. + * + * This method is only available on an ei sender context. */ void ei_device_frame(struct ei_device *device, uint64_t time); @@ -1120,6 +1197,8 @@ ei_device_frame(struct ei_device *device, uint64_t time); * Generate a relative motion event on a device with * the @ref EI_DEVICE_CAP_POINTER capability. * + * This method is only available on an ei sender context. + * * @param device The EI device * @param x The x movement in logical pixels * @param y The y movement in logical pixels @@ -1134,6 +1213,8 @@ ei_device_pointer_motion(struct ei_device *device, double x, double y); * The x/y coordinate must be within the device's regions or the event is * silently discarded. * + * This method is only available on an ei sender context. + * * @param device The EI device * @param x The x position in logical pixels * @param y The y position in logical pixels @@ -1148,6 +1229,8 @@ ei_device_pointer_motion_absolute(struct ei_device *device, * * Button codes must match the defines in ``linux/input-event-codes.h`` * + * This method is only available on an ei sender context. + * * @param device The EI device * @param button The button code * @param is_press true for button press, false for button release @@ -1164,6 +1247,8 @@ ei_device_button_button(struct ei_device *device, * on the pixel value, do not call ei_device_scroll_discrete() for * the same input event. * + * This method is only available on an ei sender context. + * * @param device The EI device * @param x The x scroll distance in logical pixels * @param y The y scroll distance in logical pixels @@ -1185,6 +1270,8 @@ ei_device_scroll_delta(struct ei_device *device, double x, double y); * on the discrete value, do not call ei_device_scroll_delta() for the * same input event. * + * This method is only available on an ei sender context. + * * @param device The EI device * @param x The x scroll distance in fractions or multiples of 120 * @param y The y scroll distance in fractions or multiples of 120 @@ -1218,6 +1305,8 @@ ei_device_scroll_discrete(struct ei_device *device, int32_t x, int32_t y); * ei_device_scroll_stop() for the same axis. A nonzero scroll or * scroll-discrete value is required for the given axis to re-start scrolling * for that axis. + * + * This method is only available on an ei sender context. */ void ei_device_scroll_stop(struct ei_device *device, bool stop_x, bool stop_y); @@ -1245,6 +1334,8 @@ ei_device_scroll_stop(struct ei_device *device, bool stop_x, bool stop_y); * ei_device_scroll_cancel() for the same axis. A nonzero scroll or * scroll-discrete value is required for the given axis to re-start scrolling * for that axis. + * + * This method is only available on an ei sender context. */ void ei_device_scroll_cancel(struct ei_device *device, bool cancel_x, bool cancel_y); @@ -1261,6 +1352,8 @@ ei_device_scroll_cancel(struct ei_device *device, bool cancel_x, bool cancel_y); * client must look at the keymap returned by ei_device_get_keymap() and * generate the appropriate keycodes. * + * This method is only available on an ei sender context. + * * @param device The EI device * @param keycode The key code * @param is_press true for key down, false for key up @@ -1275,6 +1368,8 @@ ei_device_keyboard_key(struct ei_device *device, uint32_t keycode, bool is_press * * The returned touch has a refcount of at least 1, use ei_touch_unref() to * release resources associated with this touch + * + * This method is only available on an ei sender context. */ struct ei_touch * ei_device_touch_new(struct ei_device *device); diff --git a/src/libeis.h b/src/libeis.h index 8a35a1f..0517d13 100644 --- a/src/libeis.h +++ b/src/libeis.h @@ -188,7 +188,7 @@ enum eis_event_type { */ EIS_EVENT_DEVICE_START_EMULATING = 200, /** - * Stop emulating events on this device. + * Stop emulating events on this device, see @ref EIS_EVENT_DEVICE_START_EMULATING. */ EIS_EVENT_DEVICE_STOP_EMULATING,