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




commit 5c1b9d7be1a6f1201cb545e38e1cf5bfdca570db
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 | 40 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+)
---
diff --git a/clutter/clutter/clutter-grab.h b/clutter/clutter/clutter-grab.h
index 8c87046496..3a6f3c8568 100644
--- a/clutter/clutter/clutter-grab.h
+++ b/clutter/clutter/clutter-grab.h
@@ -30,9 +30,19 @@
 
 #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
+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 38f6c26ec9..d52da60d36 100644
--- a/clutter/clutter/clutter-stage.c
+++ b/clutter/clutter/clutter-stage.c
@@ -3632,6 +3632,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)
@@ -3713,6 +3738,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)
 {
@@ -3722,6 +3754,14 @@ clutter_grab_dismiss (ClutterGrab *grab)
   g_free (grab);
 }
 
+/**
+ * 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)
 {


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]