device: Add pointer actor getter

ClutterInputDevice should have a getter method for retrieving the
reactive actor underneath the pointer.

clutter/clutter-input-device.c

@@ -391,6 +391,20 @@ clutter_input_device_get_device_coords (ClutterInputDevice *device,
     *y = device->current_y;
 }
 
+/*
+ * _clutter_input_device_update:
+ * @device: a #ClutterInputDevice
+ *
+ * Updates the input @device by determining the #ClutterActor underneath the
+ * pointer's cursor
+ *
+ * This function calls _clutter_input_device_set_actor() if needed.
+ *
+ * This function only works for #ClutterInputDevice of type
+ * %CLUTTER_POINTER_DEVICE.
+ *
+ * Since: 1.2
+ */
 ClutterActor *
 _clutter_input_device_update (ClutterInputDevice *device)
 {
@@ -399,9 +413,12 @@ _clutter_input_device_update (ClutterInputDevice *device)
   ClutterActor *old_cursor_actor;
   gint x, y;
 
+  g_return_val_if_fail (device->device_type == CLUTTER_POINTER_DEVICE, NULL);
+
   clutter_input_device_get_device_coords (device, &x, &y);
 
   stage = device->stage;
+
   old_cursor_actor = device->cursor_actor;
   new_cursor_actor = _clutter_do_pick (stage, x, y, CLUTTER_PICK_REACTIVE);
 
@@ -421,6 +438,7 @@ _clutter_input_device_update (ClutterInputDevice *device)
                   ? clutter_actor_get_name (new_cursor_actor)
                   : G_OBJECT_TYPE_NAME (new_cursor_actor));
 
+  /* short-circuit here */
   if (new_cursor_actor == old_cursor_actor)
     return old_cursor_actor;
 
@@ -428,3 +446,22 @@ _clutter_input_device_update (ClutterInputDevice *device)
 
   return device->cursor_actor;
 }
+
+/**
+ * clutter_input_device_get_pointer_actor:
+ * @device: a #ClutterInputDevice of type %CLUTTER_POINTER_DEVICE
+ *
+ * Retrieves the #ClutterActor underneath the pointer of @device
+ *
+ * Return value: (transfer none): a pointer to the #ClutterActor or %NULL
+ *
+ * Since: 1.2
+ */
+ClutterActor *
+clutter_input_device_get_pointer_actor (ClutterInputDevice *device)
+{
+  g_return_val_if_fail (CLUTTER_IS_INPUT_DEVICE (device), NULL);
+  g_return_val_if_fail (device->device_type == CLUTTER_POINTER_DEVICE, NULL);
+
+  return device->cursor_actor;
+}

clutter/clutter-input-device.h

@@ -28,7 +28,7 @@
 #ifndef __CLUTTER_INPUT_DEVICE_H__
 #define __CLUTTER_INPUT_DEVICE_H__
 
-#include <glib-object.h>
+#include <clutter/clutter-types.h>
 
 G_BEGIN_DECLS
 
@@ -92,6 +92,7 @@ gint                   clutter_input_device_get_device_id     (ClutterInputDevic
 void                   clutter_input_device_get_device_coords (ClutterInputDevice *device,
                                                                gint               *x,
                                                                gint               *y);
+ClutterActor *         clutter_input_device_get_pointer_actor (ClutterInputDevice *device);
 
 G_END_DECLS
 

doc/reference/clutter/clutter-sections.txt

@@ -1003,6 +1003,7 @@ clutter_get_input_device_for_id
 clutter_input_device_get_device_id
 clutter_input_device_get_device_type
 clutter_input_device_get_device_coords
+clutter_input_device_get_pointer_actor
 
 <SUBSECTION Standard>
 CLUTTER_TYPE_INPUT_DEVICE