[gtk+] gtkeventcontrollerscroll: Add some docs

[Carlos Garnacho <carlosg src gnome org>]

commit 645e67231e2bfe09bec5efea59041ef7f28e3bd8
Author: Carlos Garnacho <carlosg gnome org>
Date:   Sat Dec 2 00:18:07 2017 +0100

    gtkeventcontrollerscroll: Add some docs

 docs/reference/gtk/gtk4.types.in |    1 +
 gtk/gtkeventcontrollerscroll.c   |  114 ++++++++++++++++++++++++++++++++++++++
 gtk/gtkeventcontrollerscroll.h   |   14 +++++
 3 files changed, 129 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gtk/gtk4.types.in b/docs/reference/gtk/gtk4.types.in
index 5b496db..b2aefcc 100644
--- a/docs/reference/gtk/gtk4.types.in
+++ b/docs/reference/gtk/gtk4.types.in
@@ -54,6 +54,7 @@ gtk_entry_buffer_get_type
 gtk_entry_completion_get_type
 gtk_entry_get_type
 gtk_event_controller_get_type
+gtk_event_controller_scroll_get_type
 gtk_expander_get_type
 gtk_file_chooser_button_get_type
 gtk_file_chooser_dialog_get_type
diff --git a/gtk/gtkeventcontrollerscroll.c b/gtk/gtkeventcontrollerscroll.c
index 407f254..c9819ef 100644
--- a/gtk/gtkeventcontrollerscroll.c
+++ b/gtk/gtkeventcontrollerscroll.c
@@ -17,6 +17,47 @@
  * Author(s): Carlos Garnacho <carlosg gnome org>
  */
 
+/**
+ * SECTION:gtkeventcontrollerscroll
+ * @Short_description: Event controller for scroll events
+ * @Title: GtkEventControllerScroll
+ * @See_also: #GtkEventController
+ *
+ * #GtkEventControllerScroll is an event controller meant to handle
+ * scroll events from mice and touchpads. It is capable of handling
+ * both discrete and continuous scroll events, abstracting them both
+ * on the #GtkEventControllerScroll::scroll signal (deltas in the
+ * discrete case are multiples of 1).
+ *
+ * In the case of continuous scroll events, #GtkEventControllerScroll
+ * encloses all #GtkEventControllerScroll::scroll events between two
+ * #GtkEventControllerScroll::scroll-begin and #GtkEventControllerScroll::scroll-end
+ * signals.
+ *
+ * The behavior of the event controller can be modified by the
+ * flags given at creation time, or modified at a later point through
+ * gtk_event_controller_scroll_set_flags() (e.g. because the scrolling
+ * conditions of the widget changed).
+ *
+ * The controller can be set up to emit motion for either/both vertical
+ * and horizontal scroll events through #GTK_EVENT_CONTROLLER_SCROLL_VERTICAL,
+ * #GTK_EVENT_CONTROLLER_SCROLL_HORIZONTAL and #GTK_EVENT_CONTROLLER_SCROLL_BOTH.
+ * If any axis is disabled, the respective #GtkEventControllerScroll::scroll
+ * delta will be 0. Vertical scroll events will be translated to horizontal
+ * motion for the devices incapable of horizontal scrolling.
+ *
+ * The event controller can also be forced to emit discrete events on all devices
+ * through #GTK_EVENT_CONTROLLER_SCROLL_DISCRETE. This can be used to implement
+ * discrete actions triggered through scroll events (e.g. switching across
+ * combobox options).
+ *
+ * The #GTK_EVENT_CONTROLLER_SCROLL_KINETIC flag toggles the emission of the
+ * #GtkEventControllerScroll::decelerate signal, emitted at the end of scrolling
+ * with two X/Y velocity arguments that are consistent with the motion that
+ * was received.
+ *
+ * This object was added in 3.93.
+ **/
 #include "config.h"
 
 #include "gtkintl.h"
@@ -319,6 +360,13 @@ gtk_event_controller_scroll_class_init (GtkEventControllerScrollClass *klass)
 
   controller_class->handle_event = gtk_event_controller_scroll_handle_event;
 
+  /**
+   * GtkEventControllerScroll:flags:
+   *
+   * The flags affecting event controller behavior
+   *
+   * Since: 3.93
+   **/
   pspecs[PROP_FLAGS] =
     g_param_spec_flags ("flags",
                         P_("Flags"),
@@ -328,6 +376,13 @@ gtk_event_controller_scroll_class_init (GtkEventControllerScrollClass *klass)
                         G_PARAM_READWRITE |
                         G_PARAM_CONSTRUCT_ONLY);
 
+  /**
+   * GtkEventControllerScroll::scroll-begin:
+   * @controller: The object that received the signal
+   *
+   * Signals that a new scrolling operation has begun. It will
+   * only be emitted on devices capable of it.
+   **/
   signals[SCROLL_BEGIN] =
     g_signal_new (I_("scroll-begin"),
                   GTK_TYPE_EVENT_CONTROLLER_SCROLL,
@@ -335,6 +390,15 @@ gtk_event_controller_scroll_class_init (GtkEventControllerScrollClass *klass)
                   0, NULL, NULL,
                   g_cclosure_marshal_VOID__VOID,
                   G_TYPE_NONE, 0);
+  /**
+   * GtkEventControllerScroll::scroll:
+   * @controller: The object that received the signal
+   * @dx: X delta
+   * @dy: Y delta
+   *
+   * Signals that the widget should scroll by the
+   * amount specified by @dx and @dy.
+   **/
   signals[SCROLL] =
     g_signal_new (I_("scroll"),
                   GTK_TYPE_EVENT_CONTROLLER_SCROLL,
@@ -342,6 +406,13 @@ gtk_event_controller_scroll_class_init (GtkEventControllerScrollClass *klass)
                   0, NULL, NULL,
                  _gtk_marshal_VOID__DOUBLE_DOUBLE,
                   G_TYPE_NONE, 2, G_TYPE_DOUBLE, G_TYPE_DOUBLE);
+  /**
+   * GtkEventControllerScroll::scroll-end:
+   * @controller: The object that received the signal
+   *
+   * Signals that a new scrolling operation has finished. It will
+   * only be emitted on devices capable of it.
+   **/
   signals[SCROLL_END] =
     g_signal_new (I_("scroll-end"),
                   GTK_TYPE_EVENT_CONTROLLER_SCROLL,
@@ -349,6 +420,18 @@ gtk_event_controller_scroll_class_init (GtkEventControllerScrollClass *klass)
                   0, NULL, NULL,
                   g_cclosure_marshal_VOID__VOID,
                   G_TYPE_NONE, 0);
+
+  /**
+   * GtkEventControllerScroll::decelerate:
+   * @controller: The object that received the signal
+   * @vel_x: X velocity
+   * @vel_y: Y velocity
+   *
+   * Emitted after scroll is finished if the #GTK_EVENT_CONTROLLER_SCROLL_KINETIC
+   * flag is set. @vel_x and @vel_y express the initial velocity that was
+   * imprinted by the scroll events. @vel_x and @vel_y are expressed in
+   * pixels/ms.
+   **/
   signals[DECELERATE] =
     g_signal_new (I_("decelerate"),
                   GTK_TYPE_EVENT_CONTROLLER_SCROLL,
@@ -367,6 +450,18 @@ gtk_event_controller_scroll_init (GtkEventControllerScroll *scroll)
                                         sizeof (ScrollHistoryElem));
 }
 
+/**
+ * gtk_event_controller_scroll_new:
+ * @widget: a #GtkWidget
+ * @flags: behavior flags
+ *
+ * Creates a new event controller that will handle scroll events
+ * for the given @widget.
+ *
+ * Returns: a new #GtkEventControllerScroll
+ *
+ * Since: 3.93
+ **/
 GtkEventController *
 gtk_event_controller_scroll_new (GtkWidget                     *widget,
                                  GtkEventControllerScrollFlags  flags)
@@ -379,6 +474,15 @@ gtk_event_controller_scroll_new (GtkWidget                     *widget,
                        NULL);
 }
 
+/**
+ * gtk_event_controller_scroll_set_flags:
+ * @scroll: a #GtkEventControllerScroll
+ * @flags: behavior flags
+ *
+ * Sets the flags conditioning scroll controller behavior.
+ *
+ * Since: 3.93
+ **/
 void
 gtk_event_controller_scroll_set_flags (GtkEventControllerScroll      *scroll,
                                        GtkEventControllerScrollFlags  flags)
@@ -392,6 +496,16 @@ gtk_event_controller_scroll_set_flags (GtkEventControllerScroll      *scroll,
     }
 }
 
+/**
+ * gtk_event_controller_scroll_get_flags:
+ * @scroll: a #GtkEventControllerScroll
+ *
+ * Gets the flags conditioning the scroll controller behavior.
+ *
+ * Returns: the controller flags.
+ *
+ * Since: 3.93
+ **/
 GtkEventControllerScrollFlags
 gtk_event_controller_scroll_get_flags (GtkEventControllerScroll *scroll)
 {
diff --git a/gtk/gtkeventcontrollerscroll.h b/gtk/gtkeventcontrollerscroll.h
index bbbf32e..55295fe 100644
--- a/gtk/gtkeventcontrollerscroll.h
+++ b/gtk/gtkeventcontrollerscroll.h
@@ -39,6 +39,20 @@ G_BEGIN_DECLS
 typedef struct _GtkEventControllerScroll GtkEventControllerScroll;
 typedef struct _GtkEventControllerScrollClass GtkEventControllerScrollClass;
 
+/**
+ * GtkEventControllerScrollFlags:
+ * @GTK_EVENT_CONTROLLER_SCROLL_NONE: Don't emit scroll.
+ * @GTK_EVENT_CONTROLLER_SCROLL_VERTICAL: Emit scroll with vertical deltas.
+ * @GTK_EVENT_CONTROLLER_SCROLL_HORIZONTAL: Emit scroll with horizontal deltas.
+ * @GTK_EVENT_CONTROLLER_SCROLL_DISCRETE: Only emit deltas that are multiples of 1.
+ * @GTK_EVENT_CONTROLLER_SCROLL_KINETIC: Emit #GtkEventControllerScroll::decelerate
+ *   after continuous scroll finishes.
+ * @GTK_EVENT_CONTROLLER_SCROLL_BOTH_AXES: Emit scroll on both axes.
+ *
+ * Describes the behavior of a #GtkEventControllerScroll.
+ *
+ * Since: 3.93
+ **/
 typedef enum {
   GTK_EVENT_CONTROLLER_SCROLL_NONE       = 0,
   GTK_EVENT_CONTROLLER_SCROLL_VERTICAL   = 1 << 0,