stage: Make per-actor motion event delivery accessors public

Complete the quest of commit bc548dc862
by making the ClutterStage methods for controlling the per-actor motion
and crossing event delivery public, and deprecating the global ones.

clutter/clutter-device-manager.c

@@ -422,7 +422,7 @@ _clutter_device_manager_update_devices (ClutterDeviceManager *device_manager)
        * since the source of the events will always be set to be
        * the stage
        */
-      if (!_clutter_stage_get_motion_events_enabled (device->stage))
+      if (!clutter_stage_get_motion_events_enabled (device->stage))
         continue;
 
       _clutter_input_device_update (device, TRUE);

clutter/clutter-drag-action.c

@@ -164,7 +164,7 @@ emit_drag_begin (ClutterDragAction *action,
   ClutterDragActionPrivate *priv = action->priv;
 
   if (priv->stage != NULL)
-    _clutter_stage_set_motion_events_enabled (priv->stage, FALSE);
+    clutter_stage_set_motion_events_enabled (priv->stage, FALSE);
 
   g_signal_emit (action, drag_signals[DRAG_BEGIN], 0,
                  actor,
@@ -262,7 +262,7 @@ emit_drag_end (ClutterDragAction *action,
       priv->capture_id = 0;
     }
 
-  _clutter_stage_set_motion_events_enabled (priv->stage,
+  clutter_stage_set_motion_events_enabled (priv->stage,
                                            priv->motion_events_enabled);
 
   priv->in_drag = FALSE;
@@ -345,7 +345,7 @@ on_button_press (ClutterActor      *actor,
                                        &priv->transformed_press_y);
 
   priv->motion_events_enabled =
-    _clutter_stage_get_motion_events_enabled (priv->stage);
+    clutter_stage_get_motion_events_enabled (priv->stage);
 
   if (priv->x_drag_threshold == 0 || priv->y_drag_threshold == 0)
     emit_drag_begin (action, actor, event);

clutter/clutter-main.c

@@ -247,8 +247,8 @@ clutter_redraw (ClutterStage *stage)
  * clutter_set_motion_events_enabled:
  * @enable: %TRUE to enable per-actor motion events
  *
- * Sets whether per-actor motion events should be enabled or not (the
+ * Sets whether per-actor motion events should be enabled or not on
- * default is to enable them).
+ * all #ClutterStage<!-- -->s managed by Clutter.
  *
  * If @enable is %FALSE the following events will not work:
  * <itemizedlist>
@@ -259,6 +259,8 @@ clutter_redraw (ClutterStage *stage)
  * </itemizedlist>
  *
  * Since: 0.6
+ *
+ * Deprecated: 1.8: Use clutter_stage_set_motion_events_enabled() instead.
  */
 void
 clutter_set_motion_events_enabled (gboolean enable)
@@ -283,7 +285,7 @@ clutter_set_motion_events_enabled (gboolean enable)
        l != NULL;
        l = l->next)
     {
-      _clutter_stage_set_motion_events_enabled (l->data, enable);
+      clutter_stage_set_motion_events_enabled (l->data, enable);
     }
 }
 
@@ -295,6 +297,8 @@ clutter_set_motion_events_enabled (gboolean enable)
  * Return value: %TRUE if the motion events are enabled
  *
  * Since: 0.6
+ *
+ * Deprecated: 1.8: Use clutter_stage_get_motion_events_enabled() instead.
  */
 gboolean
 clutter_get_motion_events_enabled (void)
@@ -2132,7 +2136,7 @@ _clutter_process_event_details (ClutterActor        *stage,
 
       case CLUTTER_MOTION:
         /* only the stage gets motion events if they are enabled */
-        if (!_clutter_stage_get_motion_events_enabled (CLUTTER_STAGE (stage)) &&
+        if (!clutter_stage_get_motion_events_enabled (CLUTTER_STAGE (stage)) &&
             event->any.source == NULL)
           {
             /* Only stage gets motion events */

clutter/clutter-main.h

@@ -143,8 +143,10 @@ guint            clutter_threads_add_repaint_func      (GSourceFunc    func,
                                                         GDestroyNotify notify);
 void             clutter_threads_remove_repaint_func   (guint          handle_id);
 
+#ifndef CLUTTER_DISABLE_DEPRECATED
 void             clutter_set_motion_events_enabled   (gboolean enable);
 gboolean         clutter_get_motion_events_enabled   (void);
+#endif /* CLUTTER_DISABLE_DEPRECATED */
 
 void             clutter_set_default_frame_rate      (guint    frames_per_sec);
 guint            clutter_get_default_frame_rate      (void);
@@ -165,7 +167,6 @@ ClutterInputDevice *clutter_get_input_device_for_id  (gint id_);
 
 void             clutter_grab_pointer_for_device     (ClutterActor  *actor,
                                                       gint           id_);
-
 void             clutter_ungrab_pointer_for_device   (gint id_);
 
 PangoFontMap *   clutter_get_font_map                (void);

clutter/clutter-stage-private.h

@@ -90,10 +90,6 @@ void            _clutter_stage_remove_device    (ClutterStage       *stage,
 gboolean        _clutter_stage_has_device       (ClutterStage       *stage,
                                                  ClutterInputDevice *device);
 
-void     _clutter_stage_set_motion_events_enabled (ClutterStage *stage,
-                                                   gboolean      enabled);
-gboolean _clutter_stage_get_motion_events_enabled (ClutterStage *stage);
-
 CoglFramebuffer *_clutter_stage_get_active_framebuffer (ClutterStage *stage);
 
 gint32          _clutter_stage_acquire_pick_id          (ClutterStage *stage,

clutter/clutter-stage.c

@@ -3974,23 +3974,69 @@ _clutter_stage_has_device (ClutterStage       *stage,
   return g_hash_table_lookup (priv->devices, device) != NULL;
 }
 
+/**
+ * clutter_stage_set_motion_events_enabled:
+ * @stage: a #ClutterStage
+ * @enabled: %TRUE to enable the motion events delivery, and %FALSE
+ *   otherwise
+ *
+ * Sets whether per-actor motion events (and relative crossing
+ * events) should be disabled or not.
+ *
+ * The default is %TRUE.
+ *
+ * If @enable is %FALSE the following events will not be delivered
+ * to the actors children of @stage.
+ *
+ * <itemizedlist>
+ *   <listitem><para>#ClutterActor::motion-event</para></listitem>
+ *   <listitem><para>#ClutterActor::enter-event</para></listitem>
+ *   <listitem><para>#ClutterActor::leave-event</para></listitem>
+ * </itemizedlist>
+ *
+ * The events will still be delivered to the #ClutterStage.
+ *
+ * The main side effect of this function is that disabling the motion
+ * events will disable picking to detect the #ClutterActor underneath
+ * the pointer for each motion event. This is useful, for instance,
+ * when dragging a #ClutterActor across the @stage: the actor underneath
+ * the pointer is not going to change, so it's meaningless to perform
+ * a pick.
+ *
+ * Since: 1.8
+ */
 void
-_clutter_stage_set_motion_events_enabled (ClutterStage *stage,
+clutter_stage_set_motion_events_enabled (ClutterStage *stage,
                                          gboolean      enabled)
 {
-  ClutterStagePrivate *priv = stage->priv;
+  ClutterStagePrivate *priv;
+
+  g_return_if_fail (CLUTTER_IS_STAGE (stage));
+
+  priv = stage->priv;
 
   enabled = !!enabled;
 
   if (priv->motion_events_enabled != enabled)
-    {
     priv->motion_events_enabled = enabled;
 }
-}
 
+/**
+ * clutter_stage_get_motion_events_enabled:
+ * @stage: a #ClutterStage
+ *
+ * Retrieves the value set using clutter_stage_set_motion_events_enabled().
+ *
+ * Return value: %TRUE if the per-actor motion event delivery is enabled
+ *   and %FALSE otherwise
+ *
+ * Since: 1.8
+ */
 gboolean
-_clutter_stage_get_motion_events_enabled (ClutterStage *stage)
+clutter_stage_get_motion_events_enabled (ClutterStage *stage)
 {
+  g_return_val_if_fail (CLUTTER_IS_STAGE (stage), FALSE);
+
   return stage->priv->motion_events_enabled;
 }
 

clutter/clutter-stage.h

@@ -262,6 +262,11 @@ void                  clutter_stage_set_accept_focus  (ClutterStage *stage,
                                                        gboolean      accept_focus);
 gboolean              clutter_stage_get_accept_focus  (ClutterStage *stage);
 
+
+void                  clutter_stage_set_motion_events_enabled (ClutterStage *stage,
+                                                               gboolean      enabled);
+gboolean              clutter_stage_get_motion_events_enabled (ClutterStage *stage);
+
 /* Commodity macro, for mallum only */
 #define clutter_stage_add(stage,actor)                  G_STMT_START {  \
   if (CLUTTER_IS_STAGE ((stage)) && CLUTTER_IS_ACTOR ((actor)))         \

tests/interactive/test-events.c

@@ -74,13 +74,16 @@ red_button_cb (ClutterActor    *actor,
                ClutterEvent *event,
                gpointer      data)
 {
+  ClutterActor *stage;
 
   if (IsMotion)
     IsMotion = FALSE;
   else
     IsMotion = TRUE;
 
-  clutter_set_motion_events_enabled (IsMotion);
+  stage = clutter_actor_get_stage (actor);
+  clutter_stage_set_motion_events_enabled (CLUTTER_STAGE (stage),
+                                           IsMotion);
 
   g_print ("*** Per actor motion events %s ***\n",
            IsMotion ? "enabled" : "disabled");

tests/interactive/test-grab.c

@@ -107,10 +107,16 @@ green_press_cb (ClutterActor    *actor,
                 ClutterEvent    *event,
                 gpointer         data)
 {
-  clutter_set_motion_events_enabled (!clutter_get_motion_events_enabled ());
+  ClutterActor *stage;
+  gboolean enabled;
+
+  stage = clutter_actor_get_stage (actor);
+  enabled = !clutter_stage_get_motion_events_enabled (CLUTTER_STAGE (stage));
+
+  clutter_stage_set_motion_events_enabled (CLUTTER_STAGE (stage), enabled);
 
   g_print ("per actor motion events are now %s\n",
-           clutter_get_motion_events_enabled () ? "enabled" : "disabled");
+           enabled ? "enabled" : "disabled");
 
   return FALSE;
 }