[mutter/wip/carlosg/grabs-pt1: 15/30] clutter: Add yet another grab API

[Carlos Garnacho <carlosg src gnome org>]

commit 740fa916f16cff1d27c5b2a0ad97f5d5d51488a0
Author: Carlos Garnacho <carlosg gnome org>
Date:   Tue Oct 26 11:59:31 2021 +0200

    clutter: Add yet another grab API
    
    Hopefully, the one to make them all converge. This new ClutterGrab
    represents a handle on a created grab. These are stacked, so grabs
    can be overridden and remain inactive until there is a time that
    they become active again, although undoing these early is optional.
    
    These grabs are global, they do apply to all pointer, touchpoint
    and keyboard foci.
    
    At the moment, only the API to create and stack those is added,
    the actual functionality is added in future commits.

 clutter/clutter/clutter-grab.h  | 42 ++++++++++++++++++++++++++++++++++++
 clutter/clutter/clutter-stage.c | 47 +++++++++++++++++++++++++++++++++++++++++
 clutter/clutter/clutter.h       |  1 +
 clutter/clutter/meson.build     |  1 +
 4 files changed, 91 insertions(+)
---
diff --git a/clutter/clutter/clutter-grab.h b/clutter/clutter/clutter-grab.h
new file mode 100644
index 0000000000..37c837fc02
--- /dev/null
+++ b/clutter/clutter/clutter-grab.h
@@ -0,0 +1,42 @@
+/*
+ * Clutter.
+ *
+ * An OpenGL based 'interactive canvas' library.
+ *
+ * Copyright (C) 2021 Red Hat Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Author: Carlos Garnacho <carlosg gnome org>
+ */
+
+#ifndef CLUTTER_GRAB_H
+#define CLUTTER_GRAB_H
+
+#if !defined(__CLUTTER_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
+#error "Only <clutter/clutter.h> can be included directly."
+#endif
+
+#include <glib-object.h>
+
+typedef struct _ClutterGrab ClutterGrab;
+
+CLUTTER_EXPORT
+ClutterGrab * clutter_grab (ClutterStage *stage,
+                            ClutterActor *actor);
+CLUTTER_EXPORT
+void clutter_ungrab (ClutterStage *stage,
+                     ClutterGrab  *grab);
+
+#endif /* CLUTTER_GRAB_H */
diff --git a/clutter/clutter/clutter-stage.c b/clutter/clutter/clutter-stage.c
index 3b39aeca7c..f129a7aebf 100644
--- a/clutter/clutter/clutter-stage.c
+++ b/clutter/clutter/clutter-stage.c
@@ -52,6 +52,7 @@
 #include "clutter-enum-types.h"
 #include "clutter-event-private.h"
 #include "clutter-frame-clock.h"
+#include "clutter-grab.h"
 #include "clutter-id-pool.h"
 #include "clutter-input-device-private.h"
 #include "clutter-main.h"
@@ -112,6 +113,8 @@ struct _ClutterStagePrivate
   gchar *title;
   ClutterActor *key_focused_actor;
 
+  ClutterGrab *grabs;
+
   GQueue *event_queue;
 
   GArray *paint_volume_stack;
@@ -132,6 +135,13 @@ struct _ClutterStagePrivate
   guint actor_needs_immediate_relayout : 1;
 };
 
+struct _ClutterGrab
+{
+  ClutterActor *actor;
+  ClutterGrab *prev;
+  ClutterGrab *next;
+};
+
 enum
 {
   PROP_0,
@@ -3438,3 +3448,40 @@ clutter_stage_get_device_coords (ClutterStage         *stage,
   if (entry && coords)
     *coords = entry->coords;
 }
+
+ClutterGrab *
+clutter_grab (ClutterStage *stage,
+              ClutterActor *actor)
+{
+  ClutterStagePrivate *priv = stage->priv;
+  ClutterGrab *grab = g_new0 (ClutterGrab, 1);
+
+  grab->actor = actor;
+  grab->prev = NULL;
+  grab->next = priv->grabs;
+
+  priv->grabs = grab;
+
+  return grab;
+}
+
+void
+clutter_ungrab (ClutterStage *stage,
+                ClutterGrab  *grab)
+{
+  ClutterStagePrivate *priv = stage->priv;
+  ClutterGrab *prev, *next;
+
+  prev = grab->prev;
+  next = grab->next;
+
+  if (prev)
+    prev->next = next;
+  if (next)
+    next->prev = prev;
+
+  if (!prev)
+    priv->grabs = next;
+
+  g_free (grab);
+}
diff --git a/clutter/clutter/clutter.h b/clutter/clutter/clutter.h
index 8eefead61d..be788b9e56 100644
--- a/clutter/clutter/clutter.h
+++ b/clutter/clutter/clutter.h
@@ -65,6 +65,7 @@
 #include "clutter-frame-clock.h"
 #include "clutter-frame.h"
 #include "clutter-gesture-action.h"
+#include "clutter-grab.h"
 #include "clutter-grid-layout.h"
 #include "clutter-image.h"
 #include "clutter-input-device.h"
diff --git a/clutter/clutter/meson.build b/clutter/clutter/meson.build
index fee76438b3..daf3ced7fa 100644
--- a/clutter/clutter/meson.build
+++ b/clutter/clutter/meson.build
@@ -39,6 +39,7 @@ clutter_headers = [
   'clutter-frame-clock.h',
   'clutter-frame.h',
   'clutter-gesture-action.h',
+  'clutter-grab.h',
   'clutter-grid-layout.h',
   'clutter-image.h',
   'clutter-input-device.h',