diff --git a/ChangeLog b/ChangeLog index 44466a66d..5f093548f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2008-06-27 Emmanuele Bassi + + * clutter/clutter-event.h: + * clutter/clutter-main.c: + * clutter/x11/clutter-backend-x11.c: Add further documentation, + and increase the coverage to 94%. + 2008-06-27 Emmanuele Bassi * configure.ac: Post release bump to 0.7.7. diff --git a/clutter/clutter-event.h b/clutter/clutter-event.h index 32675be1c..ee12e5561 100644 --- a/clutter/clutter-event.h +++ b/clutter/clutter-event.h @@ -269,6 +269,21 @@ struct _ClutterButtonEvent ClutterInputDevice *device; /* Future use */ }; +/** + * ClutterCrossingEvent: + * @type: event type + * @time: event time + * @flags: event flags + * @stage: event source stage + * @source: event source actor + * @x: event X coordinate + * @y: event Y coordinate + * @related: actor related to the crossing + * + * Event for the movement of the pointer across different actors + * + * Since: 0.2 + */ struct _ClutterCrossingEvent { ClutterEventType type; @@ -281,7 +296,23 @@ struct _ClutterCrossingEvent ClutterActor *related; }; - +/** + * ClutterMotionEvent: + * @type: event type + * @time: event time + * @flags: event flags + * @stage: event source stage + * @source: event source actor + * @x: event X coordinate + * @y: event Y coordinate + * @modifier_state: button modifiers + * @axes: reserved for future use + * @device: reserved for future use + * + * Event for the pointer motion + * + * Since: 0.2 + */ struct _ClutterMotionEvent { ClutterEventType type; @@ -296,6 +327,24 @@ struct _ClutterMotionEvent ClutterInputDevice *device; /* Future use */ }; +/** + * ClutterScrollEvent: + * @type: event type + * @time: event time + * @flags: event flags + * @stage: event source stage + * @source: event source actor + * @x: event X coordinate + * @y: event Y coordinate + * @direction: direction of the scrolling + * @modifier_state: button modifiers + * @axes: reserved for future use + * @device: reserved for future use + * + * Scroll wheel (or similar device) event + * + * Since: 0.2 + */ struct _ClutterScrollEvent { ClutterEventType type; @@ -311,6 +360,20 @@ struct _ClutterScrollEvent ClutterInputDevice *device; /* future use */ }; +/** + * ClutterStageStateEvent: + * @type: event type + * @time: event time + * @flags: event flags + * @stage: event source stage + * @source: event source actor (unused) + * @changed_mask: bitwise OR of the changed flags + * @new_state: bitwise OR of the current state flags + * + * Event signalling a change in the #ClutterStage state. + * + * Since: 0.2 + */ struct _ClutterStageStateEvent { ClutterEventType type; @@ -322,10 +385,18 @@ struct _ClutterStageStateEvent ClutterStageState new_state; }; +/** + * ClutterEvent: + * @type: event type + * + * Generic event wrapper. + * + * Since: 0.2 + */ union _ClutterEvent { ClutterEventType type; - + ClutterAnyEvent any; ClutterButtonEvent button; ClutterKeyEvent key; diff --git a/clutter/clutter-main.c b/clutter/clutter-main.c index bc3cbd461..7c69ac750 100644 --- a/clutter/clutter-main.c +++ b/clutter/clutter-main.c @@ -1997,6 +1997,9 @@ on_pointer_grab_weak_notify (gpointer data, * actor directly. The source set in the event will be the actor that would * have received the event if the pointer grab was not in effect. * + * If you wish to grab all the pointer events for a specific input device, + * you should use clutter_grab_pointer_for_device(). + * * Since: 0.6 */ void @@ -2029,9 +2032,20 @@ clutter_grab_pointer (ClutterActor *actor) } } +/** + * clutter_grab_pointer_for_device: + * @actor: a #ClutterActor + * @id: a device id, or -1 + * + * Grabs all the pointer events coming from the device @id for @actor. + * + * If @id is -1 then this function is equivalent to clutter_grab_pointer(). + * + * Since: 0.8 + */ void -clutter_grab_pointer_for_device (ClutterActor *actor, - gint id) +clutter_grab_pointer_for_device (ClutterActor *actor, + gint id) { ClutterInputDevice *dev; @@ -2084,6 +2098,14 @@ clutter_ungrab_pointer (void) clutter_grab_pointer (NULL); } +/** + * clutter_ungrab_pointer_for_device: + * @id: a device id + * + * Removes an existing grab of the pointer events for device @id. + * + * Since: 0.8 + */ void clutter_ungrab_pointer_for_device (gint id) { @@ -2308,7 +2330,17 @@ clutter_get_use_mipmapped_text (void) return FALSE; } -ClutterInputDevice* +/** + * clutter_get_input_device_for_id: + * @id: a device id + * + * Retrieves the #ClutterInputDevice from its id. + * + * Return value: a #ClutterInputDevice, or %NULL + * + * Since: 0.8 + */ +ClutterInputDevice * clutter_get_input_device_for_id (gint id) { GSList *item; @@ -2321,7 +2353,7 @@ clutter_get_input_device_for_id (gint id) item != NULL; item = item->next) { - device = (ClutterInputDevice *)item->data; + device = item->data; if (device->id == id) return device; diff --git a/clutter/x11/clutter-backend-x11.c b/clutter/x11/clutter-backend-x11.c index 5c5e96bb9..52b7ec902 100644 --- a/clutter/x11/clutter-backend-x11.c +++ b/clutter/x11/clutter-backend-x11.c @@ -756,7 +756,7 @@ _clutter_x11_select_events (Window xwin) } } -ClutterX11XInputDevice* +ClutterX11XInputDevice * _clutter_x11_get_device_for_xid (XID id) { GSList *list_it; @@ -806,12 +806,32 @@ clutter_x11_get_input_devices (void) #endif } +/** + * clutter_x11_get_input_device_type: + * @device: a #ClutterX11XInputDevice + * + * Retrieves the type of @device. + * + * Return value: the type of the device + * + * Since: 0.8 + */ ClutterX11InputDeviceType clutter_x11_get_input_device_type (ClutterX11XInputDevice *device) { return device->type; } +/** + * clutter_x11_has_xinput: + * + * Gets whether Clutter has XInput support. + * + * Return value: %TRUE if Clutter was compiled with XInput support + * and XInput support is available at run time. + * + * Since: 0.8 + */ gboolean clutter_x11_has_xinput (void) {