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

[Marge Bot <marge-bot src gnome org>]

commit bbc95c1688983f10781ac0b5c93d07479c84dbab
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.
    
    Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/2068>

 clutter/clutter/clutter-grab.h  | 38 +++++++++++++++++++++++++
 clutter/clutter/clutter-stage.c | 62 +++++++++++++++++++++++++++++++++++++++++
 clutter/clutter/clutter-stage.h |  5 ++++
 clutter/clutter/clutter.h       |  1 +
 clutter/clutter/meson.build     |  1 +
 5 files changed, 107 insertions(+)
---
diff --git a/clutter/clutter/clutter-grab.h b/clutter/clutter/clutter-grab.h
new file mode 100644
index 0000000000..8c87046496
--- /dev/null
+++ b/clutter/clutter/clutter-grab.h
@@ -0,0 +1,38 @@
+/*
+ * 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
+void clutter_grab_dismiss (ClutterGrab *grab);
+
+#endif /* CLUTTER_GRAB_H */
diff --git a/clutter/clutter/clutter-stage.c b/clutter/clutter/clutter-stage.c
index 03a957065b..e9354c4887 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"
@@ -113,6 +114,8 @@ struct _ClutterStagePrivate
   gchar *title;
   ClutterActor *key_focused_actor;
 
+  ClutterGrab *topmost_grab;
+
   GQueue *event_queue;
 
   GArray *paint_volume_stack;
@@ -133,6 +136,14 @@ struct _ClutterStagePrivate
   guint actor_needs_immediate_relayout : 1;
 };
 
+struct _ClutterGrab
+{
+  ClutterStage *stage;
+  ClutterActor *actor;
+  ClutterGrab *prev;
+  ClutterGrab *next;
+};
+
 enum
 {
   PROP_0,
@@ -3625,3 +3636,54 @@ clutter_stage_pick_and_update_device (ClutterStage             *stage,
 
   return new_actor;
 }
+
+ClutterGrab *
+clutter_stage_grab (ClutterStage *stage,
+                    ClutterActor *actor)
+{
+  ClutterStagePrivate *priv = stage->priv;
+  ClutterGrab *grab;
+
+  g_return_val_if_fail (CLUTTER_IS_STAGE (stage), NULL);
+  g_return_val_if_fail (CLUTTER_IS_ACTOR (actor), NULL);
+
+  grab = g_new0 (ClutterGrab, 1);
+  grab->stage = stage;
+  grab->actor = actor;
+  grab->prev = NULL;
+  grab->next = priv->topmost_grab;
+
+  if (priv->topmost_grab)
+    priv->topmost_grab->prev = grab;
+
+  priv->topmost_grab = grab;
+
+  return grab;
+}
+
+void
+clutter_grab_dismiss (ClutterGrab *grab)
+{
+  ClutterStagePrivate *priv;
+  ClutterGrab *prev, *next;
+
+  g_return_if_fail (grab != NULL);
+
+  priv = grab->stage->priv;
+  prev = grab->prev;
+  next = grab->next;
+
+  if (prev)
+    prev->next = next;
+  if (next)
+    next->prev = prev;
+
+  if (priv->topmost_grab == grab)
+    {
+      /* This is the active grab */
+      g_assert (prev == NULL);
+      priv->topmost_grab = next;
+    }
+
+  g_free (grab);
+}
diff --git a/clutter/clutter/clutter-stage.h b/clutter/clutter/clutter-stage.h
index efb788e70a..b45c50ccd7 100644
--- a/clutter/clutter/clutter-stage.h
+++ b/clutter/clutter/clutter-stage.h
@@ -29,6 +29,7 @@
 #endif
 
 #include <clutter/clutter-actor.h>
+#include <clutter/clutter-grab.h>
 #include <clutter/clutter-types.h>
 #include <clutter/clutter-stage-view.h>
 
@@ -269,6 +270,10 @@ ClutterActor * clutter_stage_get_device_actor (ClutterStage         *stage,
                                                ClutterInputDevice   *device,
                                                ClutterEventSequence *sequence);
 
+CLUTTER_EXPORT
+ClutterGrab * clutter_stage_grab (ClutterStage *stage,
+                                  ClutterActor *actor);
+
 G_END_DECLS
 
 #endif /* __CLUTTER_STAGE_H__ */
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 cd2c897a77..2b8764a0f1 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',