From a3102a777ead15f7ba4b671bd25fd642762fec57 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Tue, 18 Jan 2011 14:09:04 +0000 Subject: [PATCH] docs: Fill out documentation for new symbols --- clutter/clutter-event.c | 82 ++++++++++++++++++++++ clutter/clutter-event.h | 1 + clutter/clutter-input-device.c | 37 ++++++++++ clutter/clutter-input-device.h | 29 ++++++++ clutter/clutter-private.h | 4 ++ clutter/x11/clutter-device-manager-xi2.c | 39 +++++++--- doc/reference/clutter/Makefile.am | 1 + doc/reference/clutter/clutter-sections.txt | 12 +++- 8 files changed, 194 insertions(+), 11 deletions(-) diff --git a/clutter/clutter-event.c b/clutter/clutter-event.c index df823dc1d..40629d6ed 100644 --- a/clutter/clutter-event.c +++ b/clutter/clutter-event.c @@ -47,6 +47,8 @@ typedef struct _ClutterEventPrivate { ClutterEvent base; + ClutterInputDevice *source_device; + gpointer platform_data; } ClutterEventPrivate; @@ -907,3 +909,83 @@ clutter_get_current_event (void) return context->current_event; } + +/** + * clutter_event_get_source_device: + * @event: a #ClutterEvent + * + * Retrieves the hardware device that originated the event. + * + * If you need the virtual device, use clutter_event_get_device(). + * + * If no hardware device originated this event, this function will + * return the same device as clutter_event_get_device(). + * + * Return value: (transfer none): a pointer to a #ClutterInputDevice + * or %NULL + * + * Since: 1.6 + */ +ClutterInputDevice * +clutter_event_get_source_device (const ClutterEvent *event) +{ + ClutterEventPrivate *real_event; + + if (!is_event_allocated (event)) + return NULL; + + real_event = (ClutterEventPrivate *) event; + + if (real_event->source_device != NULL) + return real_event->source_device; + + return clutter_event_get_device (event); +} + +void +_clutter_event_set_device (ClutterEvent *event, + ClutterInputDevice *device) +{ + switch (event->type) + { + case CLUTTER_NOTHING: + case CLUTTER_STAGE_STATE: + case CLUTTER_DESTROY_NOTIFY: + case CLUTTER_CLIENT_MESSAGE: + case CLUTTER_DELETE: + case CLUTTER_ENTER: + case CLUTTER_LEAVE: + break; + + case CLUTTER_BUTTON_PRESS: + case CLUTTER_BUTTON_RELEASE: + event->button.device = device; + break; + + case CLUTTER_MOTION: + event->motion.device = device; + break; + + case CLUTTER_SCROLL: + event->scroll.device = device; + break; + + case CLUTTER_KEY_PRESS: + case CLUTTER_KEY_RELEASE: + event->key.device = device; + break; + } +} + +void +_clutter_event_set_source_device (ClutterEvent *event, + ClutterInputDevice *device) +{ + ClutterEventPrivate *real_event; + + if (!is_event_allocated (event)) + return; + + real_event = (ClutterEventPrivate *) event; + real_event->source_device = device; +} diff --git a/clutter/clutter-event.h b/clutter/clutter-event.h index 38bcd97b6..e7d20eb5e 100644 --- a/clutter/clutter-event.h +++ b/clutter/clutter-event.h @@ -403,6 +403,7 @@ ClutterModifierType clutter_event_get_state (const ClutterEvent gint clutter_event_get_device_id (const ClutterEvent *event); ClutterInputDeviceType clutter_event_get_device_type (const ClutterEvent *event); ClutterInputDevice * clutter_event_get_device (const ClutterEvent *event); +ClutterInputDevice * clutter_event_get_source_device (const ClutterEvent *event); ClutterActor * clutter_event_get_source (const ClutterEvent *event); ClutterStage * clutter_event_get_stage (const ClutterEvent *event); diff --git a/clutter/clutter-input-device.c b/clutter/clutter-input-device.c index 8d9cbeb4a..013ce437b 100644 --- a/clutter/clutter-input-device.c +++ b/clutter/clutter-input-device.c @@ -924,6 +924,16 @@ _clutter_input_device_get_axis (ClutterInputDevice *device, return info->axis; } +/** + * clutter_input_device_get_n_axes: + * @device: a #ClutterInputDevice + * + * Retrieves the number of axes available on @device. + * + * Return value: the number of axes on the device + * + * Since: 1.6 + */ guint clutter_input_device_get_n_axes (ClutterInputDevice *device) { @@ -964,6 +974,20 @@ clutter_input_device_get_n_keys (ClutterInputDevice *device) return 0; } +/** + * clutter_input_device_set_key: + * @device: a #ClutterInputDevice + * @index_: the index of the key + * @keyval: the keyval + * @modifiers: a bitmask of modifiers + * + * Sets the keyval and modifiers at the given @index_ for @device. + * + * Clutter will use the keyval and modifiers set when filling out + * an event coming from the same input device. + * + * Since: 1.6 + */ void clutter_input_device_set_key (ClutterInputDevice *device, guint index_, @@ -982,6 +1006,19 @@ clutter_input_device_set_key (ClutterInputDevice *device, key_info->modifiers = modifiers; } +/** + * clutter_input_device_get_key: + * @device: a #ClutterInputDevice + * @index_: the index of the key + * @keyval: (out): return location for the keyval at @index_ + * @modifiers: (out): return location for the modifiers at @index_ + * + * Retrieves the key set using clutter_input_device_set_key() + * + * Return value: %TRUE if a key was set at the given index + * + * Since: 1.6 + */ gboolean clutter_input_device_get_key (ClutterInputDevice *device, guint index_, diff --git a/clutter/clutter-input-device.h b/clutter/clutter-input-device.h index 232554f13..86621b51f 100644 --- a/clutter/clutter-input-device.h +++ b/clutter/clutter-input-device.h @@ -57,6 +57,9 @@ typedef struct _ClutterInputDeviceClass ClutterInputDeviceClass; * @CLUTTER_TABLET_DEVICE: A tablet device * @CLUTTER_TOUCHPAD_DEVICE: A touchpad device * @CLUTTER_TOUCHSCREEN_DEVICE: A touch screen device + * @CLUTTER_PEN_DEVICE: A pen device + * @CLUTTER_ERASER_DEVICE: An eraser device + * @CLUTTER_CURSOR_DEVICE: A cursor device * @CLUTTER_N_DEVICE_TYPES: The number of device types * * The types of input devices available. @@ -81,12 +84,38 @@ typedef enum { CLUTTER_N_DEVICE_TYPES } ClutterInputDeviceType; +/** + * ClutterInputMode: + * @CLUTTER_INPUT_MODE_MASTER: A master, virtual device + * @CLUTTER_INPUT_MODE_SLAVE: A slave, physical device, attached to + * a master device + * @CLUTTER_INPUT_MODE_FLOATING: A slave, physical device, not attached + * to a master device + * + * The mode for input devices available. + * + * Since: 1.6 + */ typedef enum { CLUTTER_INPUT_MODE_MASTER, CLUTTER_INPUT_MODE_SLAVE, CLUTTER_INPUT_MODE_FLOATING } ClutterInputMode; +/** + * ClutterInputAxis: + * @CLUTTER_INPUT_AXIS_IGNORE: Unused axis + * @CLUTTER_INPUT_AXIS_X: The position on the X axis + * @CLUTTER_INPUT_AXIS_Y: The position of the Y axis + * @CLUTTER_INPUT_AXIS_PRESSURE: The pressure information + * @CLUTTER_INPUT_AXIS_XTILT: The tilt on the X axis + * @CLUTTER_INPUT_AXIS_YTILT: The tile on the Y axis + * @CLUTTER_INPUT_AXIS_WHEEL: A wheel + * + * The type of axes Clutter recognizes on a #ClutterInputDevice + * + * Since: 1.6 + */ typedef enum { CLUTTER_INPUT_AXIS_IGNORE, CLUTTER_INPUT_AXIS_X, diff --git a/clutter/clutter-private.h b/clutter/clutter-private.h index 79b6dcba9..931020e06 100644 --- a/clutter/clutter-private.h +++ b/clutter/clutter-private.h @@ -230,6 +230,10 @@ gpointer _clutter_event_get_platform_data (const ClutterEvent *event); void _clutter_event_push (const ClutterEvent *event, gboolean do_copy); +void _clutter_event_set_device (ClutterEvent *event, + ClutterInputDevice *device); +void _clutter_event_set_source_device (ClutterEvent *event, + ClutterInputDevice *device); void _clutter_util_fully_transform_vertices (const CoglMatrix *modelview, const CoglMatrix *projection, diff --git a/clutter/x11/clutter-device-manager-xi2.c b/clutter/x11/clutter-device-manager-xi2.c index dbdf67024..7641e37b6 100644 --- a/clutter/x11/clutter-device-manager-xi2.c +++ b/clutter/x11/clutter-device-manager-xi2.c @@ -632,9 +632,13 @@ clutter_device_manager_xi2_translate_event (ClutterEventTranslator *translator, event_x11->caps_lock_set = _clutter_keymap_x11_get_caps_lock_state (backend_x11->keymap); + device = g_hash_table_lookup (manager_xi2->devices_by_id, + GINT_TO_POINTER (xev->sourceid)); + _clutter_event_set_source_device (event, device); + device = g_hash_table_lookup (manager_xi2->devices_by_id, GINT_TO_POINTER (xev->deviceid)); - event->key.device = device; + _clutter_event_set_device (event, device); /* XXX keep this in sync with the evdev device manager */ n = print_keysym (event->key.keyval, buffer, sizeof (buffer)); @@ -693,9 +697,6 @@ clutter_device_manager_xi2_translate_event (ClutterEventTranslator *translator, event->scroll.time = xev->time; event->scroll.x = xev->event_x; event->scroll.y = xev->event_y; - event->scroll.device = - g_hash_table_lookup (manager_xi2->devices_by_id, - GINT_TO_POINTER (xev->deviceid)); event->scroll.modifier_state = _clutter_input_device_xi2_translate_state (&xev->mods, &xev->buttons); @@ -704,6 +705,14 @@ clutter_device_manager_xi2_translate_event (ClutterEventTranslator *translator, event->scroll.y, stage_x11, &xev->valuators); + + device = g_hash_table_lookup (manager_xi2->devices_by_id, + GINT_TO_POINTER (xev->sourceid)); + _clutter_event_set_source_device (event, device); + + device = g_hash_table_lookup (manager_xi2->devices_by_id, + GINT_TO_POINTER (xev->deviceid)); + _clutter_event_set_device (event, device); break; default: @@ -717,9 +726,6 @@ clutter_device_manager_xi2_translate_event (ClutterEventTranslator *translator, event->button.x = xev->event_x; event->button.y = xev->event_y; event->button.button = xev->detail; - event->button.device = - g_hash_table_lookup (manager_xi2->devices_by_id, - GINT_TO_POINTER (xev->deviceid)); event->button.modifier_state = _clutter_input_device_xi2_translate_state (&xev->mods, &xev->buttons); @@ -728,6 +734,14 @@ clutter_device_manager_xi2_translate_event (ClutterEventTranslator *translator, event->button.y, stage_x11, &xev->valuators); + + device = g_hash_table_lookup (manager_xi2->devices_by_id, + GINT_TO_POINTER (xev->sourceid)); + _clutter_event_set_source_device (event, device); + + device = g_hash_table_lookup (manager_xi2->devices_by_id, + GINT_TO_POINTER (xev->deviceid)); + _clutter_event_set_device (event, device); break; } @@ -760,13 +774,18 @@ clutter_device_manager_xi2_translate_event (ClutterEventTranslator *translator, event->motion.time = xev->time; event->motion.x = xev->event_x; event->motion.y = xev->event_y; - event->motion.device = - g_hash_table_lookup (manager_xi2->devices_by_id, - GINT_TO_POINTER (xev->deviceid)); event->motion.modifier_state = _clutter_input_device_xi2_translate_state (&xev->mods, &xev->buttons); + device = g_hash_table_lookup (manager_xi2->devices_by_id, + GINT_TO_POINTER (xev->sourceid)); + _clutter_event_set_source_device (event, device); + + device = g_hash_table_lookup (manager_xi2->devices_by_id, + GINT_TO_POINTER (xev->deviceid)); + _clutter_event_set_device (event, device); + CLUTTER_NOTE (EVENT, "motion: win:0x%x device:%s (x:%.2f, y:%.2f)", (unsigned int) stage_x11->xwin, event->motion.device->device_name, diff --git a/doc/reference/clutter/Makefile.am b/doc/reference/clutter/Makefile.am index fe52cac02..adc47850d 100644 --- a/doc/reference/clutter/Makefile.am +++ b/doc/reference/clutter/Makefile.am @@ -75,6 +75,7 @@ IGNORE_HFILES=\ clutter-deprecated.h \ clutter-device-manager-private.h \ clutter-enum-types.h \ + clutter-event-translator.h \ clutter-id-pool.h \ clutter-keysyms.h \ clutter-keysyms-compat.h \ diff --git a/doc/reference/clutter/clutter-sections.txt b/doc/reference/clutter/clutter-sections.txt index b147c52b5..3dbadb375 100644 --- a/doc/reference/clutter/clutter-sections.txt +++ b/doc/reference/clutter/clutter-sections.txt @@ -1056,6 +1056,7 @@ clutter_event_get_scroll_direction clutter_event_get_device clutter_event_get_device_id clutter_event_get_device_type +clutter_event_get_source_device clutter_get_current_event_time @@ -1072,14 +1073,22 @@ clutter_event_get_type clutter-input-device ClutterInputDevice ClutterInputDeviceType +ClutterInputAxis +ClutterInputMode ClutterInputDevice -ClutterInputDeviceClass clutter_input_device_get_device_id clutter_input_device_get_device_type clutter_input_device_get_device_name clutter_input_device_get_device_coords clutter_input_device_get_pointer_actor clutter_input_device_get_pointer_stage +clutter_input_device_set_key +clutter_input_device_get_key +clutter_input_device_get_n_axes +clutter_input_device_get_associated_device +clutter_input_device_get_slave_devices + + clutter_input_device_update_from_event @@ -1091,6 +1100,7 @@ CLUTTER_IS_INPUT_DEVICE_CLASS CLUTTER_INPUT_DEVICE_GET_CLASS +ClutterInputDeviceClass clutter_input_device_get_type