clutter/gesture: Add a new ClutterAction for touch and mouse gestures

Introduce ClutterGesture, a new ClutterAction subclass and the successor
of ClutterGestureAction that brings the necessary tools to handle
sequences of events and abstract touch and mouse gestures from those.

The big difference compared to ClutterGestureAction is that ClutterGesture
provides the implementation with point_added/moved/ended and
sequences_cancelled events and expects the implementation to move the
ClutterGesture through the ClutterGestureState state machine. This state
machine is then used internally by ClutterGesture to coordinate with other
gestures.

With the next commits, ClutterGesture will handle relationships between
conflicting gestures completely by itself, allowing the implementation or
the user to specify the details of the relationship between two gestures.

Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/2389>

clutter/clutter/clutter-enums.h

@@ -1230,4 +1230,15 @@ typedef enum
                             CLUTTER_GRAB_STATE_KEYBOARD),
 } ClutterGrabState;
 
+typedef enum /*< prefix=CLUTTER_GESTURE_STATE >*/
+{
+  CLUTTER_GESTURE_STATE_WAITING,
+  CLUTTER_GESTURE_STATE_POSSIBLE,
+  CLUTTER_GESTURE_STATE_RECOGNIZING,
+  CLUTTER_GESTURE_STATE_COMPLETED,
+  CLUTTER_GESTURE_STATE_CANCELLED,
+
+  CLUTTER_N_GESTURE_STATES
+} ClutterGestureState;
+
 G_END_DECLS

clutter/clutter/clutter-gesture.h

@@ -0,0 +1,147 @@
+/*
+ * Copyright (C) 2023 Jonas Dreßler <verdre@v0yd.nl>
+ *
+ * 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/>.
+ */
+
+#pragma once
+
+#if !defined(__CLUTTER_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
+#error "Only <clutter/clutter.h> can be included directly."
+#endif
+
+#include <clutter/clutter-action.h>
+
+G_BEGIN_DECLS
+
+#define CLUTTER_TYPE_GESTURE (clutter_gesture_get_type ())
+
+CLUTTER_EXPORT
+G_DECLARE_DERIVABLE_TYPE (ClutterGesture, clutter_gesture,
+                          CLUTTER, GESTURE, ClutterAction)
+
+struct _ClutterGestureClass
+{
+  ClutterActionClass parent_class;
+
+  /**
+   * ClutterGestureClass::should_handle_sequence: (skip)
+   */
+  gboolean (* should_handle_sequence) (ClutterGesture     *self,
+                                       const ClutterEvent *sequence_begin_event);
+
+  /**
+   * ClutterGestureClass::point_began: (skip)
+   */
+  void (* point_began) (ClutterGesture *self,
+                        unsigned int    sequence_index);
+
+  /**
+   * ClutterGestureClass::point_moved: (skip)
+   */
+  void (* point_moved) (ClutterGesture *self,
+                        unsigned int    sequence_index);
+
+  /**
+   * ClutterGestureClass::point_ended: (skip)
+   */
+  void (* point_ended) (ClutterGesture *self,
+                        unsigned int    sequence_index);
+
+  /**
+   * ClutterGestureClass::sequences_cancelled: (skip)
+   */
+  void (* sequences_cancelled) (ClutterGesture *self,
+                                unsigned int   *sequences,
+                                unsigned int    n_sequences);
+
+  /**
+   * ClutterGestureClass::state_changed: (skip)
+   */
+  void (* state_changed) (ClutterGesture      *self,
+                          ClutterGestureState  old_state,
+                          ClutterGestureState  new_state);
+
+  /**
+   * ClutterGestureClass::crossing_event: (skip)
+   */
+  void (* crossing_event) (ClutterGesture    *self,
+                           unsigned int       sequence_index,
+                           ClutterEventType   type,
+                           uint32_t           time,
+                           ClutterEventFlags  flags,
+                           ClutterActor      *source_actor,
+                           ClutterActor      *related_actor);
+
+  /**
+   * ClutterGestureClass::may_recognize: (skip)
+   */
+  gboolean (* may_recognize) (ClutterGesture *self);
+};
+
+CLUTTER_EXPORT
+void clutter_gesture_set_state (ClutterGesture      *self,
+                                ClutterGestureState  state);
+
+CLUTTER_EXPORT
+ClutterGestureState clutter_gesture_get_state (ClutterGesture *self);
+
+CLUTTER_EXPORT
+void clutter_gesture_cancel (ClutterGesture *self);
+
+CLUTTER_EXPORT
+void clutter_gesture_reset_state_machine (ClutterGesture *self);
+
+CLUTTER_EXPORT
+unsigned int clutter_gesture_get_n_points (ClutterGesture *self);
+
+CLUTTER_EXPORT
+unsigned int * clutter_gesture_get_points (ClutterGesture *self,
+                                           size_t         *n_points);
+
+CLUTTER_EXPORT
+void clutter_gesture_get_point_coords (ClutterGesture   *self,
+                                       int               point_index,
+                                       graphene_point_t *coords_out);
+
+CLUTTER_EXPORT
+void clutter_gesture_get_point_coords_abs (ClutterGesture   *self,
+                                           int               point_index,
+                                           graphene_point_t *coords_out);
+
+CLUTTER_EXPORT
+void clutter_gesture_get_point_begin_coords (ClutterGesture   *self,
+                                             int               point_index,
+                                             graphene_point_t *coords_out);
+
+CLUTTER_EXPORT
+void clutter_gesture_get_point_begin_coords_abs (ClutterGesture   *self,
+                                                 int               point_index,
+                                                 graphene_point_t *coords_out);
+
+CLUTTER_EXPORT
+void clutter_gesture_get_point_previous_coords (ClutterGesture   *self,
+                                                int               point_index,
+                                                graphene_point_t *coords_out);
+
+CLUTTER_EXPORT
+void clutter_gesture_get_point_previous_coords_abs (ClutterGesture   *self,
+                                                    int               point_index,
+                                                    graphene_point_t *coords_out);
+
+CLUTTER_EXPORT
+const ClutterEvent * clutter_gesture_get_point_event (ClutterGesture  *self,
+                                                      int              point_index);
+
+G_END_DECLS

clutter/clutter/clutter-marshal.list

@@ -35,3 +35,4 @@ VOID:STRING,INT
 VOID:UINT,STRING,UINT
 VOID:UINT,UINT
 VOID:STRING,INT,POINTER
+VOID:VOID

clutter/clutter/clutter.h

@@ -59,6 +59,7 @@
 #include "clutter/clutter-frame-clock.h"
 #include "clutter/clutter-frame.h"
 #include "clutter/clutter-gesture-action.h"
+#include "clutter/clutter-gesture.h"
 #include "clutter/clutter-grab.h"
 #include "clutter/clutter-grid-layout.h"
 #include "clutter/clutter-image.h"

clutter/clutter/meson.build

@@ -33,6 +33,7 @@ clutter_headers = [
   'clutter-frame-clock.h',
   'clutter-frame.h',
   'clutter-gesture-action.h',
+  'clutter-gesture.h',
   'clutter-grab.h',
   'clutter-grid-layout.h',
   'clutter-image.h',
@@ -117,6 +118,7 @@ clutter_sources = [
   'clutter-frame-clock.c',
   'clutter-frame.c',
   'clutter-gesture-action.c',
+  'clutter-gesture.c',
   'clutter-grab.c',
   'clutter-graphene.c',
   'clutter-grid-layout.c',