From 5348eb281e599942d903f023b2aecd87a77792af Mon Sep 17 00:00:00 2001 From: Henrik Rydberg Date: Thu, 19 Aug 2010 20:16:17 +0200 Subject: Add documentation to structs and functions in grail.h Signed-off-by: Henrik Rydberg --- include/grail.h | 143 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 138 insertions(+), 5 deletions(-) diff --git a/include/grail.h b/include/grail.h index c77a6e3..ae3a73f 100644 --- a/include/grail.h +++ b/include/grail.h @@ -37,23 +37,59 @@ #define GRAIL_STATUS_UPDATE 1 #define GRAIL_STATUS_END 2 -typedef float grail_prop_t; -typedef __u64 grail_time_t; - +typedef float grail_prop_t; /* gesture properties */ +typedef __u64 grail_time_t; /* time in milliseconds */ + +/** + * struct grail_coord - coordinate in bounding box units + * @x: the horizontal position (bbox units) + * @y: the vertical position (bbox units) + */ struct grail_coord { float x, y; }; + +/** + * struct grail_client_id - Gesture client information + * @client: Client id + * @root: Root window + * @event: Window to route events to + * @child: Window the event occured in + * + * This struct is treated opaquely, and only has meaning to the gesture + * client. Details are subject to change. + */ struct grail_client_id { int client; int root, event, child; }; +/** + * struct grail_client_info - Gesture request information + * @id: Gesture client id + * @mask: Gestures the client is listening to + */ struct grail_client_info { struct grail_client_id id; grail_mask_t mask[DIM_GRAIL_TYPE_BYTES]; }; +/** + * struct grail_event - Gesture event + * @type: The gesture type + * @id: Unique identifier foof the gesture instance + * @status: Gesture status (begin, update, end) + * @ntouch: Number of current touches + * @nprop: Number of properties in the gesture + * @pos: Focus point of the gesture (bbox coordinates) + * @touch: Array of individual touch information + * @client_id: The gesture client to route the gesture to + * @time: Time of event (milliseconds) + * @prop: Array of properties of the event + * + * Gesture events are passed to the client via the gesture() callback. + */ struct grail_event { int type; int id; @@ -66,6 +102,25 @@ struct grail_event { grail_prop_t prop[DIM_GRAIL_PROP]; }; +/** + * struct grail - Main grail device + * @get_clients: Called at the onset of new gestures to retrieve the list + * of listening clients. + * @event: Callback for kernel events passing through grail. + * @gesture: Main gesture callback. + * @impl: Grail implementation details. + * @gin: Gesture instatiation details. + * @gru: Gesture recognition details. + * @priv: Generic pointer to user-defined content. + * + * The grail device pulls events from the underlying device, detects + * gestures, and passes them on to the client via the gesture() + * callback. Events that are not gesture or for other reasons held back are + * passed on via the event() callback. The user provides information about + * windows and listening clients via the get_clients callback, which is + * called during gesture instantiation. + * + */ struct grail { int (*get_clients)(struct grail *ge, struct grail_client_info *client, int max_clients, @@ -81,18 +136,96 @@ struct grail { void *priv; }; +/** + * grail_open - open a grail device + * @ge: the grail device to open + * @fd: file descriptor of the kernel device + * + * Initialize the internal grail structures and configure it by reading the + * protocol capabilities through the file descriptor. + * + * The callbacks, parameters and priv pointer should be set prior to this + * call. + * + * Returns zero on success, negative error number otherwise. + */ int grail_open(struct grail *ge, int fd); + +/** + * grail_idle - check state of kernel device + * @ge: the grail device in use + * @fd: file descriptor of the kernel device + * @ms: number of milliseconds to wait for activity + * + * Returns true if the device is idle, i.e., there are no fetched + * events in the pipe and there is nothing to fetch from the device. + */ int grail_idle(struct grail *ge, int fd, int ms); + +/** + * grail_pull - pull and process available events from the kernel device + * @ge: the grail device in use + * @fd: file descriptor of the kernel device + * + * Pull all available events and process them. The grail callbacks are + * invoked during this call. + * + * The underlying file descriptor must have O_NONBLOCK set, or this method + * will not return until the file is closed. + * + * On success, returns the number of events read. Otherwise, + * a standard negative error number is returned. + */ int grail_pull(struct grail *ge, int fd); + +/** + * grail_close - close the grail device + * @ge: the grail device to close + * @fd: file descriptor of the kernel device + * + * Deallocates all memory associated with grail, and clears the grail + * structure. + */ void grail_close(struct grail *ge, int fd); +/** + * grail_set_bbox - set the grail unit bounding box + * @ge: the grail device in use + * @min: the minimum (lower-left) corner of the bounding box + * @max: the maximum (upper-right) corner of the bounding box + * + * Sets the box within which the device coordinates should be presented. + */ void grail_set_bbox(struct grail *ge, const struct grail_coord *min, const struct grail_coord *max); +/** + * grail_filter_abs_events - filter kernel motion events + * @ge: the grail device in use + * @usage: When true, filter kernel motion events. + * + * Single-finger pointer events are treated as pointer gestures in + * grail. When filter_motion_events is non-zero, the kernel events + * corresponding to pointer movement are removed from the event + * stream. + * + */ +void grail_filter_abs_events(struct grail *ge, int usage); + +/** + * grail_get_units - get device coordinate ranges + * @ge: the grail device in use + * @min: minimum x and y coordinates + * @max: maximum x and y coordinates + * + * The grail event attributes pos, touch_major, touch_minor, + * width_major, and width_minor are all given in device coordinate + * units, unless specified otherwise using the grail_set_bbox() + * function. This function reports the device coordinate ranges. + * + */ void grail_get_units(const struct grail *ge, struct grail_coord *min, struct grail_coord *max); -void grail_filter_abs_events(struct grail *ge, int usage); - #endif -- cgit v1.2.3