[mutter/wip/carlosg/grabs-pt2: 30/32] clutter: Add docs and introspection annotations to grabs

[Carlos Garnacho <carlosg src gnome org>]

commit c4a43bb6b5519905e8482688e7141943ed57b389
Author: Carlos Garnacho <carlosg gnome org>
Date:   Wed Nov 17 23:17:14 2021 +0100

    clutter: Add docs and introspection annotations to grabs
    
    Since we want these accessed from bindings this must be a boxed
    type. Since we want a explicit start/end lifetime, this cannot be
    refcounted, so make these functions shallow.

 clutter/clutter/clutter-grab.h  | 10 +++++++++
 clutter/clutter/clutter-stage.c | 50 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+)
---
diff --git a/clutter/clutter/clutter-grab.h b/clutter/clutter/clutter-grab.h
index 5cb86baa57..0a883cba9c 100644
--- a/clutter/clutter/clutter-grab.h
+++ b/clutter/clutter/clutter-grab.h
@@ -30,12 +30,22 @@
 
 #include <glib-object.h>
 
+#define CLUTTER_TYPE_GRAB (clutter_grab_get_type ())
 typedef struct _ClutterGrab ClutterGrab;
 
+CLUTTER_EXPORT
+GType clutter_grab_get_type (void) G_GNUC_CONST;
+
 CLUTTER_EXPORT
 void clutter_grab_dismiss (ClutterGrab *grab);
 
 CLUTTER_EXPORT
 ClutterGrabState clutter_grab_get_windowing_state (ClutterGrab *grab);
 
+CLUTTER_EXPORT
+ClutterGrab * clutter_grab_ref (ClutterGrab *grab);
+
+CLUTTER_EXPORT
+void clutter_grab_unref (ClutterGrab *grab);
+
 #endif /* CLUTTER_GRAB_H */
diff --git a/clutter/clutter/clutter-stage.c b/clutter/clutter/clutter-stage.c
index 3bd0ab774d..10f62d9333 100644
--- a/clutter/clutter/clutter-stage.c
+++ b/clutter/clutter/clutter-stage.c
@@ -3633,6 +3633,31 @@ clutter_stage_notify_grab (ClutterStage *stage,
   clutter_stage_notify_grab_on_key_focus (stage, cur_actor, old_actor);
 }
 
+ClutterGrab *
+clutter_grab_ref (ClutterGrab *grab)
+{
+  return grab;
+}
+
+void
+clutter_grab_unref (ClutterGrab *grab)
+{
+}
+
+G_DEFINE_BOXED_TYPE (ClutterGrab, clutter_grab,
+                     clutter_grab_ref, clutter_grab_unref)
+
+/**
+ * clutter_stage_grab:
+ * @stage: The #ClutterStage
+ * @actor: The actor grabbing input
+ *
+ * Grabs input onto a certain actor. Events will be propagated as
+ * usual inside its hierarchy.
+ *
+ * Returns: (transfer none): (nullable): an opaque #ClutterGrab handle, drop
+ *   with clutter_grab_dismiss()
+ **/
 ClutterGrab *
 clutter_stage_grab (ClutterStage *stage,
                     ClutterActor *actor)
@@ -3715,6 +3740,13 @@ clutter_stage_unlink_grab (ClutterStage *stage,
   grab->prev = NULL;
 }
 
+/**
+ * clutter_grab_dismiss:
+ * @grab: Grab to undo
+ *
+ * Removes a grab. If this grab is effective, crossing events
+ * will be generated to indicate the change in event redirection.
+ **/
 void
 clutter_grab_dismiss (ClutterGrab *grab)
 {
@@ -3724,6 +3756,16 @@ clutter_grab_dismiss (ClutterGrab *grab)
   g_free (grab);
 }
 
+/**
+ * clutter_grab_get_windowing_state:
+ * @grab: a Grab handle
+ *
+ * Returns the windowing-level state of the
+ * grab, the devices that are guaranteed to be
+ * grabbed.
+ *
+ * Returns: The state of the grab.
+ **/
 ClutterGrabState
 clutter_grab_get_windowing_state (ClutterGrab *grab)
 {
@@ -3732,6 +3774,14 @@ clutter_grab_get_windowing_state (ClutterGrab *grab)
   return grab->stage->priv->grab_state;
 }
 
+/**
+ * clutter_stage_get_grab_actor:
+ * @stage: a #ClutterStage
+ *
+ * Gets the actor that currently holds a grab.
+ *
+ * Returns: (transfer none): The grabbing actor
+ **/
 ClutterActor *
 clutter_stage_get_grab_actor (ClutterStage *stage)
 {