clutter-event: Add scroll source enum and axis scroll flags

Those can be used to implement different scrolling behaviors.
The fields have been added to ClutterScrollEvent itself. According
to pahole, this makes the struct as big as ClutterButtonEvent and
ClutterTouchEvent, so already at the limit of the ClutterEvent
union.

https://bugzilla.gnome.org/show_bug.cgi?id=757026

4 files changed, 90 insertions, 0 deletions

diff --git a/clutter/clutter-enums.h b/clutter/clutter-enums.h
index a3fc1c21f..33c8d9005 100644
--- a/clutter/clutter-enums.h
+++ b/clutter/clutter-enums.h
@@ -1445,6 +1445,45 @@ typedef enum {
   CLUTTER_TOUCHPAD_GESTURE_PHASE_CANCEL
 } ClutterTouchpadGesturePhase;
 
+/**
+ * ClutterScrollSource:
+ * @CLUTTER_SCROLL_SOURCE_UNKNOWN: Source of scroll events is unknown.
+ * @CLUTTER_SCROLL_SOURCE_WHEEL: The scroll event is originated by a mouse wheel.
+ * @CLUTTER_SCROLL_SOURCE_FINGER: The scroll event is originated by one or more
+ *   fingers on the device (eg. touchpads).
+ * @CLUTTER_SCROLL_SOURCE_CONTINUOUS: The scroll event is originated by the
+ *   motion of some device (eg. a scroll button is set).
+ *
+ * The scroll source determines the source of the scroll event. Keep in mind
+ * that the source device #ClutterInputDeviceType is not enough to infer
+ * the scroll source.
+ *
+ * Since: 1.26
+ */
+typedef enum {
+  CLUTTER_SCROLL_SOURCE_UNKNOWN,
+  CLUTTER_SCROLL_SOURCE_WHEEL,
+  CLUTTER_SCROLL_SOURCE_FINGER,
+  CLUTTER_SCROLL_SOURCE_CONTINUOUS
+} ClutterScrollSource;
+
+/**
+ * ClutterScrollFinishFlags:
+ * @CLUTTER_SCROLL_FINISHED_NONE: no axis was stopped.
+ * @CLUTTER_SCROLL_FINISHED_HORIZONTAL: The horizontal axis stopped.
+ * @CLUTTER_SCROLL_FINISHED_VERTICAL: The vertical axis stopped.
+ *
+ * Flags used to notify the axes that were stopped in a #ClutterScrollEvent.
+ * These can be used to trigger post-scroll effects like kinetic scrolling.
+ *
+ * Since: 1.26
+ */
+typedef enum {
+  CLUTTER_SCROLL_FINISHED_NONE       = 0,
+  CLUTTER_SCROLL_FINISHED_HORIZONTAL = 1 << 0,
+  CLUTTER_SCROLL_FINISHED_VERTICAL   = 1 << 1
+} ClutterScrollFinishFlags;
+
 G_END_DECLS
 
 #endif /* __CLUTTER_ENUMS_H__ */
diff --git a/clutter/clutter-event.c b/clutter/clutter-event.c
index de1d5a8e2..2d331f82c 100644
--- a/clutter/clutter-event.c
+++ b/clutter/clutter-event.c
@@ -1999,3 +1999,45 @@ clutter_event_get_gesture_motion_delta (const ClutterEvent *event,
         *dy = event->touchpad_swipe.dy;
     }
 }
+
+/**
+ * clutter_event_get_scroll_source:
+ * @event: an scroll event
+ *
+ * Returns the #ClutterScrollSource that applies to an scroll event.
+ *
+ * Returns: The source of scroll events
+ *
+ * Since: 1.26
+ **/
+ClutterScrollSource
+clutter_event_get_scroll_source (const ClutterEvent *event)
+{
+  g_return_val_if_fail (event != NULL, CLUTTER_SCROLL_SOURCE_UNKNOWN);
+  g_return_val_if_fail (event->type == CLUTTER_SCROLL,
+                        CLUTTER_SCROLL_SOURCE_UNKNOWN);
+
+  return event->scroll.scroll_source;
+}
+
+/**
+ * clutter_event_get_scroll_finish_flags:
+ * @event: an scroll event
+ *
+ * Returns the #ClutterScrollFinishFlags of an scroll event. Those
+ * can be used to determine whether post-scroll effects like kinetic
+ * scrolling should be applied.
+ *
+ * Returns: The scroll finish flags
+ *
+ * Since: 1.26
+ **/
+ClutterScrollFinishFlags
+clutter_event_get_scroll_finish_flags (const ClutterEvent *event)
+{
+  g_return_val_if_fail (event != NULL, CLUTTER_SCROLL_SOURCE_UNKNOWN);
+  g_return_val_if_fail (event->type == CLUTTER_SCROLL,
+                        CLUTTER_SCROLL_SOURCE_UNKNOWN);
+
+  return event->scroll.finish_flags;
+}
diff --git a/clutter/clutter-event.h b/clutter/clutter-event.h
index 5b0b26796..b04d32291 100644
--- a/clutter/clutter-event.h
+++ b/clutter/clutter-event.h
@@ -291,6 +291,8 @@ struct _ClutterMotionEvent
  * @axes: reserved for future use
  * @device: the device that originated the event. If you want the physical
  * device the event originated from, use clutter_event_get_source_device()
+ * @scroll_source: the source of scroll events. This field is available since 1.26
+ * @finish_flags: the axes that were stopped in this event. This field is available since 1.26
  *
  * Scroll wheel (or similar device) event
  *
@@ -310,6 +312,8 @@ struct _ClutterScrollEvent
   ClutterModifierType modifier_state;
   gdouble *axes; /* future use */
   ClutterInputDevice *device;
+  ClutterScrollSource scroll_source;
+  ClutterScrollFinishFlags finish_flags;
 };
 
 /**
@@ -682,6 +686,9 @@ void                    clutter_event_get_gesture_motion_delta       (const Clut
                                                                       gdouble                *dx,
                                                                       gdouble                *dy);
 
+ClutterScrollSource      clutter_event_get_scroll_source             (const ClutterEvent     *event);
+ClutterScrollFinishFlags clutter_event_get_scroll_finish_flags       (const ClutterEvent     *event);
+
 G_END_DECLS
 
 #endif /* __CLUTTER_EVENT_H__ */
diff --git a/doc/reference/clutter-sections.txt b/doc/reference/clutter-sections.txt
index 2bff5f022..b907fd715 100644
--- a/doc/reference/clutter-sections.txt
+++ b/doc/reference/clutter-sections.txt
@@ -1140,6 +1140,8 @@ clutter_event_get_gesture_pinch_angle_delta
 clutter_event_get_gesture_pinch_scale
 clutter_event_get_gesture_phase
 clutter_event_get_gesture_motion_delta
+clutter_event_get_scroll_source
+clutter_event_get_scroll_finish_flags
 
 <SUBSECTION>
 clutter_event_get