docs: Fill out documentation for new symbols

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;
+}

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);
 

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_,

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,

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,

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,

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	\

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
 
 <SUBSECTION>
 clutter_get_current_event_time
@@ -1072,14 +1073,22 @@ clutter_event_get_type
 <FILE>clutter-input-device</FILE>
 <TITLE>ClutterInputDevice</TITLE>
 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
+
+<SUBSECTION>
 clutter_input_device_update_from_event
 
 <SUBSECTION Standard>
@@ -1091,6 +1100,7 @@ CLUTTER_IS_INPUT_DEVICE_CLASS
 CLUTTER_INPUT_DEVICE_GET_CLASS
 
 <SUBSECTION Private>
+ClutterInputDeviceClass
 clutter_input_device_get_type
 </SECTION>