[clutter/wip/touchpad-gestures: 10/12] event: Add pinch/swipe gesture event types and structs

[Carlos Garnacho <carlosg src gnome org>]

commit 0cff3d212562168a2770baa2bd2d0040b3e01f2e
Author: Carlos Garnacho <carlosg gnome org>
Date:   Fri May 22 18:30:09 2015 +0200

    event: Add pinch/swipe gesture event types and structs
    
    We now have ClutterTouchpadPinchEvent and ClutterTouchpadSwipeEvent,
    each bringing the necessary info for the specific gesture. Each
    of these events is accompanied with begin/update/end/cancel event
    types.
    
    These events have been also made to propagate down/up the pointer
    position, just like scroll and button events do.

 clutter/clutter-enums.h            |   43 +++++++++++++++++++
 clutter/clutter-event.c            |   34 +++++++++++++++
 clutter/clutter-event.h            |   82 ++++++++++++++++++++++++++++++++++++
 clutter/clutter-main.c             |    2 +
 doc/reference/clutter-sections.txt |    3 +
 5 files changed, 164 insertions(+), 0 deletions(-)
---
diff --git a/clutter/clutter-enums.h b/clutter/clutter-enums.h
index d2c8974..a3fc1c2 100644
--- a/clutter/clutter-enums.h
+++ b/clutter/clutter-enums.h
@@ -757,6 +757,10 @@ typedef enum { /*< flags prefix=CLUTTER_EVENT >*/
  *   event added in 1.10
  * @CLUTTER_TOUCH_CANCEL: A touch event sequence has been canceled;
  *   event added in 1.10
+ * @CLUTTER_TOUCHPAD_PINCH: A pinch gesture event, the current state is
+ *   determined by its phase field; event added in 1.24
+ * @CLUTTER_TOUCHPAD_SWIPE: A swipe gesture event, the current state is
+ *   determined by its phase field; event added in 1.24
  * @CLUTTER_EVENT_LAST: Marks the end of the #ClutterEventType enumeration;
  *   added in 1.10
  *
@@ -782,6 +786,8 @@ typedef enum { /*< prefix=CLUTTER >*/
   CLUTTER_TOUCH_UPDATE,
   CLUTTER_TOUCH_END,
   CLUTTER_TOUCH_CANCEL,
+  CLUTTER_TOUCHPAD_PINCH,
+  CLUTTER_TOUCHPAD_SWIPE,
 
   CLUTTER_EVENT_LAST            /* helper */
 } ClutterEventType;
@@ -1402,6 +1408,43 @@ typedef enum {
   CLUTTER_GESTURE_TRIGGER_EDGE_BEFORE
 } ClutterGestureTriggerEdge;
 
+/**
+ * ClutterTouchpadGesturePhase:
+ * @CLUTTER_TOUCHPAD_GESTURE_PHASE_BEGIN: The gesture has begun.
+ * @CLUTTER_TOUCHPAD_GESTURE_PHASE_UPDATE: The gesture has been updated.
+ * @CLUTTER_TOUCHPAD_GESTURE_PHASE_END: The gesture was finished, changes
+ *   should be permanently applied.
+ * @CLUTTER_TOUCHPAD_GESTURE_PHASE_CANCEL: The gesture was cancelled, all
+ *   changes should be undone.
+ *
+ * The phase of a touchpad gesture event. All gestures are guaranteed to
+ * begin with an event of type %CLUTTER_TOUCHPAD_GESTURE_PHASE_BEGIN,
+ * followed by a number of %CLUTTER_TOUCHPAD_GESTURE_PHASE_UPDATE (possibly 0).
+ *
+ * A finished gesture may have 2 possible outcomes, an event with phase
+ * %CLUTTER_TOUCHPAD_GESTURE_PHASE_END will be emitted when the gesture is
+ * considered successful, this should be used as the hint to perform any
+ * permanent changes.
+
+ * Cancelled gestures may be so for a variety of reasons, due to hardware,
+ * or due to the gesture recognition layers hinting the gesture did not
+ * finish resolutely (eg. a 3rd finger being added during a pinch gesture).
+ * In these cases, the last event with report the phase
+ * %CLUTTER_TOUCHPAD_GESTURE_PHASE_CANCEL, this should be used as a hint
+ * to undo any visible/permanent changes that were done throughout the
+ * progress of the gesture.
+ *
+ * See also #ClutterTouchpadPinchEvent and #ClutterTouchpadPinchEvent.
+ *
+ * Since: 1.24
+ */
+typedef enum {
+  CLUTTER_TOUCHPAD_GESTURE_PHASE_BEGIN,
+  CLUTTER_TOUCHPAD_GESTURE_PHASE_UPDATE,
+  CLUTTER_TOUCHPAD_GESTURE_PHASE_END,
+  CLUTTER_TOUCHPAD_GESTURE_PHASE_CANCEL
+} ClutterTouchpadGesturePhase;
+
 G_END_DECLS
 
 #endif /* __CLUTTER_ENUMS_H__ */
diff --git a/clutter/clutter-event.c b/clutter/clutter-event.c
index 26d5611..3170b9d 100644
--- a/clutter/clutter-event.c
+++ b/clutter/clutter-event.c
@@ -436,6 +436,16 @@ clutter_event_get_position (const ClutterEvent *event,
     case CLUTTER_SCROLL:
       clutter_point_init (position, event->scroll.x, event->scroll.y);
       break;
+
+    case CLUTTER_TOUCHPAD_PINCH:
+      clutter_point_init (position, event->touchpad_pinch.x,
+                          event->touchpad_pinch.y);
+      break;
+
+    case CLUTTER_TOUCHPAD_SWIPE:
+      clutter_point_init (position, event->touchpad_swipe.x,
+                          event->touchpad_swipe.y);
+      break;
     }
 
 }
@@ -498,6 +508,16 @@ clutter_event_set_coords (ClutterEvent *event,
       event->scroll.x = x;
       event->scroll.y = y;
       break;
+
+    case CLUTTER_TOUCHPAD_PINCH:
+      event->touchpad_pinch.x = x;
+      event->touchpad_pinch.y = y;
+      break;
+
+    case CLUTTER_TOUCHPAD_SWIPE:
+      event->touchpad_swipe.x = x;
+      event->touchpad_swipe.y = y;
+      break;
     }
 }
 
@@ -1097,6 +1117,11 @@ clutter_event_set_device (ClutterEvent       *event,
     case CLUTTER_KEY_RELEASE:
       event->key.device = device;
       break;
+
+    case CLUTTER_TOUCHPAD_PINCH:
+    case CLUTTER_TOUCHPAD_SWIPE:
+      /* Rely on priv data for these */
+      break;
     }
 }
 
@@ -1171,6 +1196,11 @@ clutter_event_get_device (const ClutterEvent *event)
     case CLUTTER_KEY_RELEASE:
       device = event->key.device;
       break;
+
+    case CLUTTER_TOUCHPAD_PINCH:
+    case CLUTTER_TOUCHPAD_SWIPE:
+      /* Rely on priv data for these */
+      break;
     }
 
   return device;
@@ -1608,6 +1638,10 @@ clutter_event_get_axes (const ClutterEvent *event,
     case CLUTTER_MOTION:
       retval = event->motion.axes;
       break;
+
+    case CLUTTER_TOUCHPAD_PINCH:
+    case CLUTTER_TOUCHPAD_SWIPE:
+      break;
     }
 
   if (retval != NULL)
diff --git a/clutter/clutter-event.h b/clutter/clutter-event.h
index 5df8dff..9c60b96 100644
--- a/clutter/clutter-event.h
+++ b/clutter/clutter-event.h
@@ -115,6 +115,8 @@ typedef struct _ClutterScrollEvent      ClutterScrollEvent;
 typedef struct _ClutterStageStateEvent  ClutterStageStateEvent;
 typedef struct _ClutterCrossingEvent    ClutterCrossingEvent;
 typedef struct _ClutterTouchEvent       ClutterTouchEvent;
+typedef struct _ClutterTouchpadPinchEvent ClutterTouchpadPinchEvent;
+typedef struct _ClutterTouchpadSwipeEvent ClutterTouchpadSwipeEvent;
 
 /**
  * ClutterAnyEvent:
@@ -385,6 +387,84 @@ struct _ClutterTouchEvent
 };
 
 /**
+ * ClutterTouchpadPinchEvent:
+ * @type: event type
+ * @time: event time
+ * @flags: event flags
+ * @stage: event source stage
+ * @source: event source actor (unused)
+ * @phase: the current phase of the gesture
+ * @x: the X coordinate of the pointer, relative to the stage
+ * @y: the Y coordinate of the pointer, relative to the stage
+ * @dx: movement delta of the pinch focal point in the X axis
+ * @dx: movement delta of the pinch focal point in the Y axis
+ * @angle_delta: angle delta in degrees, clockwise rotations are
+ *   represented by positive deltas
+ * @scale: the current scale
+ *
+ * Used for touchpad pinch gesture events. The current state of the
+ * gesture will be determined by the @phase field.
+ *
+ * Each event with phase %CLUTTER_TOUCHPAD_GESTURE_PHASE_BEGIN
+ * will report a @scale of 1.0, all later phases in the gesture
+ * report the current scale relative to the initial 1.0 value
+ * (eg. 0.5 being half the size, 2.0 twice as big).
+ *
+ * Since: 1.24
+ */
+struct _ClutterTouchpadPinchEvent
+{
+  ClutterEventType type;
+  guint32 time;
+  ClutterEventFlags flags;
+  ClutterStage *stage;
+  ClutterActor *source;
+
+  ClutterTouchpadGesturePhase phase;
+  gfloat x;
+  gfloat y;
+  gfloat dx;
+  gfloat dy;
+  gfloat angle_delta;
+  gfloat scale;
+};
+
+/**
+ * ClutterTouchpadSwipeEvent
+ * @type: event type
+ * @time: event time
+ * @flags: event flags
+ * @stage: event source stage
+ * @source: event source actor (unused)
+ * @phase: the current phase of the gesture
+ * @n_fingers: the number of fingers triggering the swipe
+ * @x: the X coordinate of the pointer, relative to the stage
+ * @y: the Y coordinate of the pointer, relative to the stage
+ * @dx: movement delta of the pinch focal point in the X axis
+ * @dx: movement delta of the pinch focal point in the Y axis
+ *
+ * Used for touchpad swipe gesture events. The current state of the
+ * gesture will be determined by the @phase field.
+ *
+ * Since: 1.24
+ */
+struct _ClutterTouchpadSwipeEvent
+{
+  ClutterEventType type;
+  guint32 time;
+  ClutterEventFlags flags;
+  ClutterStage *stage;
+  ClutterActor *source;
+
+  ClutterTouchpadGesturePhase phase;
+  guint n_fingers;
+  gfloat x;
+  gfloat y;
+  gfloat dx;
+  gfloat dy;
+};
+
+/**
  * ClutterEvent:
  *
  * Generic event wrapper.
@@ -404,6 +484,8 @@ union _ClutterEvent
   ClutterStageStateEvent stage_state;
   ClutterCrossingEvent crossing;
   ClutterTouchEvent touch;
+  ClutterTouchpadPinchEvent touchpad_pinch;
+  ClutterTouchpadSwipeEvent touchpad_swipe;
 };
 
 /**
diff --git a/clutter/clutter-main.c b/clutter/clutter-main.c
index 5fc12c9..3d2130c 100644
--- a/clutter/clutter-main.c
+++ b/clutter/clutter-main.c
@@ -2290,6 +2290,8 @@ _clutter_process_event_details (ClutterActor        *stage,
       case CLUTTER_BUTTON_PRESS:
       case CLUTTER_BUTTON_RELEASE:
       case CLUTTER_SCROLL:
+      case CLUTTER_TOUCHPAD_PINCH:
+      case CLUTTER_TOUCHPAD_SWIPE:
         {
           ClutterActor *actor;
           gfloat x, y;
diff --git a/doc/reference/clutter-sections.txt b/doc/reference/clutter-sections.txt
index 3880923..ccca66b 100644
--- a/doc/reference/clutter-sections.txt
+++ b/doc/reference/clutter-sections.txt
@@ -1105,6 +1105,9 @@ ClutterStageStateEvent
 ClutterCrossingEvent
 ClutterTouchEvent
 ClutterEventSequence
+ClutterTouchpadPinchEvent
+ClutterTouchpadSwipeEvent
+ClutterTouchpadGesturePhase
 clutter_event_new
 clutter_event_copy
 clutter_event_free