improve docs for multitouch features

9 files changed, 184 insertions, 27 deletions

diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt
index 24b83c89a2..d8d8551dee 100644
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/docs/reference/gtk/gtk3-sections.txt
@@ -5076,6 +5076,7 @@ GtkAllocation
 GtkSelectionData
 GtkWidgetAuxInfo
 GtkWidgetHelpType
+GtkCapturedEventFlags
 gtk_widget_new
 gtk_widget_destroy
 gtk_widget_in_destruction
@@ -5261,6 +5262,7 @@ gtk_widget_get_mapped
 gtk_widget_get_requisition
 gtk_widget_device_is_shadowed
 gtk_widget_get_modifier_mask
+gtk_widget_release_captured_events
 
 <SUBSECTION>
 gtk_widget_get_path
diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c
index d11518bdfe..c05d732812 100644
--- a/gdk/gdkevents.c
+++ b/gdk/gdkevents.c
@@ -1806,6 +1806,8 @@ gdk_event_get_screen (const GdkEvent *event)
  * else it returns %FALSE.
  *
  * Returns: %TRUE if the touch ID can be extracted from @event.
+ *
+ * Since: 3.4
  **/
 gboolean
 gdk_event_get_touch_id (const GdkEvent *event,
@@ -1852,6 +1854,8 @@ gdk_event_get_touch_id (const GdkEvent *event,
  * to react to touch events.</warning></note>
  *
  * Returns: (transfer full): the touch region, or %NULL if unavailable
+ *
+ * Since: 3.4
  **/
 cairo_region_t *
 gdk_event_get_touch_area (GdkEvent *event)
diff --git a/gdk/gdkevents.h b/gdk/gdkevents.h
index 2fa72bff80..2ddaafb586 100644
--- a/gdk/gdkevents.h
+++ b/gdk/gdkevents.h
@@ -265,12 +265,18 @@ typedef GdkFilterReturn (*GdkFilterFunc) (GdkXEvent *xevent,
  *   was added in 2.8.
  * @GDK_DAMAGE: the content of the window has been changed. This event type
  *   was added in 2.14.
- * @GDK_TOUCH_MOTION: A touch device has been updated.
- * @GDK_TOUCH_PRESS: A new touch stream has just started.
- * @GDK_TOUCH_RELEASE: A touch stream has finished.
- * @GDK_MULTITOUCH_ADDED: A touch ID was added to a #GdkTouchCluster
+ * @GDK_TOUCH_MOTION: A touch device has been updated. This event type was
+ *   added in 3.4.
+ * @GDK_TOUCH_PRESS: A new touch stream has just started. This event type was
+ *   added in 3.4.
+ * @GDK_TOUCH_RELEASE: A touch stream has finished. This event type was
+ *   added in 3.4.
+ * @GDK_MULTITOUCH_ADDED: A touch ID was added to a #GdkTouchCluster. This
+ *   event type was added in 3.4.
  * @GDK_MULTITOUCH_UPDATED: A touch within a #GdkTouchCluster has been updated.
- * @GDK_MULTITOUCH_REMOVED: A touch ID was removed from a #GdkTouchCluster.
+ *   This event type was added in 3.4.
+ * @GDK_MULTITOUCH_REMOVED: A touch ID was removed from a #GdkTouchCluster. This
+ *   event type was added in 3.4.
  * @GDK_EVENT_LAST: marks the end of the GdkEventType enumeration. Added in 2.18
  *
  * Specifies the type of the event.
@@ -581,6 +587,10 @@ struct _GdkEventVisibility
  * @touch_id: touch ID, only meaningful if event is of type %GDK_TOUCH_MOTION.
  *
  * Generated when the pointer/touch moves.
+ *
+ * If the event has a type of %GDK_TOUCH_MOTION, this event will
+ * pertain to a sequence identified by gdk_event_get_touch_id().
+ * With multitouch devices, there may be several ongoing sequences.
  */
 struct _GdkEventMotion
 {
@@ -650,7 +660,8 @@ struct _GdkEventMultiTouch
 /**
  * GdkEventButton:
  * @type: the type of the event (%GDK_BUTTON_PRESS, %GDK_2BUTTON_PRESS,
- *   %GDK_3BUTTON_PRESS or %GDK_BUTTON_RELEASE).
+ *   %GDK_3BUTTON_PRESS, %GDK_BUTTON_RELEASE, %GDK_TOUCH_PRESS or
+ *   %GDK_TOUCH_RELEASE).
  * @window: the window which received the event.
  * @send_event: %TRUE if the event was sent explicitly (e.g. using
  *   <function>XSendEvent</function>).
@@ -676,7 +687,8 @@ struct _GdkEventMultiTouch
  *
  * Used for button press and button release events. The
  * @type field will be one of %GDK_BUTTON_PRESS,
- * %GDK_2BUTTON_PRESS, %GDK_3BUTTON_PRESS, and %GDK_BUTTON_RELEASE.
+ * %GDK_2BUTTON_PRESS, %GDK_3BUTTON_PRESS, %GDK_BUTTON_RELEASE,
+ * %GDK_TOUCH_PRESS and %GDK_TOUCH_RELEASE.
  *
  * Double and triple-clicks result in a sequence of events being received.
  * For double-clicks the order of events will be:
@@ -708,6 +720,11 @@ struct _GdkEventMultiTouch
  * For a double click to occur, the second button press must occur within
  * 1/4 of a second of the first. For a triple click to occur, the third
  * button press must also occur within 1/2 second of the first button press.
+ *
+ * If the event has a type of %GDK_TOUCH_PRESS or %GDK_TOUCH_RELEASE,
+ * this event will pertain to a sequence identified by
+ * gdk_event_get_touch_id(). With multitouch devices, there may be
+ * several ongoing sequences.
  */
 struct _GdkEventButton
 {
diff --git a/gdk/gdktouchcluster.c b/gdk/gdktouchcluster.c
index 9bc0474eb3..8232fc20c5 100644
--- a/gdk/gdktouchcluster.c
+++ b/gdk/gdktouchcluster.c
@@ -29,9 +29,9 @@
  * @See_also: #GdkEventMultiTouch
  *
  * #GdkTouchCluster is an object that gathers touch IDs from a
- * touch-enabled slave #GdkDevice, in order to send
- * #GdkEventMultiTouch<!-- --> events whenever a contained touch ID
- * is updated.
+ * #GdkDevice, in order to send #GdkEventMultiTouch events
+ * whenever a touch ID that is contained in the cluster sends
+ * an event.
  *
  * #GdkTouchCluster<!-- -->s are always associated to a window,
  * you need to create them through gdk_window_create_touch_cluster(),
@@ -41,9 +41,34 @@
  * %GDK_TOUCH_MOTION or %GDK_TOUCH_RELEASE events through
  * gdk_event_get_touch_id(), and then be added via
  * gdk_touch_cluster_add_touch(). Note that touch IDs are
- * highly transitive, even be an incrementable number only
- * identifying the current touch event stream, so touch IDs
- * should always be gotten from these events.
+ * highly transitive, and they must be dealt with as such.
+ * touch IDs must not be stored after a GDK_TOUCH_RELEASE,
+ * and should always be retrieved from the events being
+ * currently received.
+ *
+ * <example>
+ * <title>Adding touch IDs to a cluster in a GTK+ widget</title>
+ * <programlisting>
+ * static gboolean
+ * widget_button_press (GtkWidget *widget,
+ *                      GdkEvent  *event)
+ * {
+ *   guint touch_id;
+ *
+ *   if (gdk_event_get_touch_id (event, &touch_id))
+ *     {
+ *       /<!-- -->* It is a touch event, delegate processing
+ *        * to the  multitouch event handler
+ *        *<!-- -->/
+ *       gdk_touch_cluster_add_touch (priv->touch_cluster, touch_id);
+ *       return TRUE;
+ *     }
+ *
+ *   /<!-- -->* Normal button processing *<!-- -->/
+ *   ...
+ * }
+ * </programlisting>
+ * </example>
  *
  * Anytime a touch ID is within a cluster, no %GDK_TOUCH_PRESS,
  * %GDK_TOUCH_MOTION or %GDK_TOUCH_RELEASE events will happen
@@ -53,6 +78,37 @@
  * called for it. Note that GTK+ will automatically take a
  * touch ID out of any cluster if %GDK_TOUCH_RELEASE is gotten
  * internally.
+ *
+ * <example>
+ * <title>Typical multitouch event handler</title>
+ * <programlisting>
+ * static gboolean
+ * widget_multitouch_event (GtkWidget *widget,
+ *                          GdkEvent  *event)
+ * {
+ *   if (event->type == GDK_MULTITOUCH_ADDED ||
+ *       event->type == GDK_MULTITOUCH_REMOVED)
+ *     {
+ *       /<!-- -->* Update control mode based
+ *        * on the current number of touches
+ *        *<!-- -->/
+ *       priv->control_mode = update_control_mode (event->multitouch.n_events);
+ *     }
+ *   else
+ *     {
+ *       /<!-- -->* A touch ID in the cluster has updated
+ *        * its coordinates, update widget based on the
+ *        * current control mode.
+ *        *<!-- -->/
+ *       update_view (widget, priv->control_mode,
+ *                    event->multitouch.events,
+ *                    event->multitouch.n_events);
+ *     }
+ *
+ *   return TRUE;
+ * }
+ * </programlisting>
+ * </example>
  */
 
 typedef struct GdkTouchClusterPrivate GdkTouchClusterPrivate;
@@ -197,6 +253,8 @@ gdk_touch_cluster_get_property (GObject      *object,
  * If @touch_id already pertained to another #GdkTouchCluster, it
  * will be removed from it, generating a %GDK_MULTITOUCH_REMOVED
  * for that another cluster.
+ *
+ * Since: 3.4
  **/
 void
 gdk_touch_cluster_add_touch (GdkTouchCluster *cluster,
@@ -228,6 +286,8 @@ gdk_touch_cluster_add_touch (GdkTouchCluster *cluster,
  * Note that GTK+ automatically removes a touch ID from any cluster
  * if a %GDK_TOUCH_RELEASE event is gotten internally.
  * </para></note>
+ *
+ * Since: 3.4
  **/
 void
 gdk_touch_cluster_remove_touch (GdkTouchCluster *cluster,
@@ -255,6 +315,8 @@ gdk_touch_cluster_remove_touch (GdkTouchCluster *cluster,
  * @cluster: a #GdkTouchCluster
  *
  * Removes all touch IDs from @cluster.
+ *
+ * Since: 3.4
  **/
 void
 gdk_touch_cluster_remove_all (GdkTouchCluster *cluster)
@@ -284,7 +346,9 @@ gdk_touch_cluster_remove_all (GdkTouchCluster *cluster)
  *
  * Returns a const list of touch IDs as #guint.
  *
- * Returns: (transfer none): A list of touch IDs.
+ * Returns: (transfer none) (element-type uint): A list of touch IDs.
+ *
+ * Since: 3.4
  **/
 GList *
 gdk_touch_cluster_get_touches (GdkTouchCluster *cluster)
@@ -306,6 +370,8 @@ gdk_touch_cluster_get_touches (GdkTouchCluster *cluster)
  * touch IDs must pertain to this device. As a consequence,
  * gdk_touch_cluster_remove_all() will be called on @cluster
  * if the current device changes.
+ *
+ * Since: 3.4
  **/
 void
 gdk_touch_cluster_set_device (GdkTouchCluster *cluster,
@@ -333,6 +399,8 @@ gdk_touch_cluster_set_device (GdkTouchCluster *cluster,
  * the #GdkDevice will typically have the %GDK_SOURCE_TOUCH input source.
  *
  * Returns: (transfer none): The #GdkDevice generating the contained touch IDs
+ *
+ * Since: 3.4
  **/
 GdkDevice *
 gdk_touch_cluster_get_device (GdkTouchCluster *cluster)
diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h
index d8712b6b20..bab9978f3d 100644
--- a/gdk/gdktypes.h
+++ b/gdk/gdktypes.h
@@ -366,6 +366,13 @@ typedef enum
  * some of which are marked as a hint (the is_hint member is %TRUE).
  * To receive more motion events after a motion hint event, the application
  * needs to asks for more, by calling gdk_event_request_motions().
+ *
+ * If %GDK_TOUCH_MASK is enabled, the window will receive (multi)touch events
+ * from touch-enabled devices. Those will come as sequences #GdkEventMotion
+ * with type %GDK_TOUCH_MOTION, enclosed by 2 #GdkEventButton events with
+ * type %GDK_TOUCH_PRESS / %GDK_TOUCH_RELEASE. gdk_event_get_touch_id() will
+ * return the touch ID on those events, so different sequences may be
+ * distinguished.
  */
 typedef enum
 {
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index 5103d44db7..ce340844dc 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -11625,6 +11625,8 @@ touch_cluster_touch_removed (GdkTouchCluster *cluster,
  * Returns: (transfer none): a newly created @GdkTouchCluster. This
  *          object is owned by @window and must be freed through
  *          gdk_window_remove_touch_cluster().
+ *
+ * Since: 3.4
  **/
 GdkTouchCluster *
 gdk_window_create_touch_cluster (GdkWindow *window,
@@ -11656,6 +11658,8 @@ gdk_window_create_touch_cluster (GdkWindow *window,
  * Removes @cluster from @window. All contained touches will be
  * removed one by one, causing %GDK_MULTITOUCH_REMOVED events
  * for these before destroying @cluster.
+ *
+ * Since: 3.4
  **/
 void
 gdk_window_remove_touch_cluster (GdkWindow       *window,
diff --git a/gtk/gtkenums.h b/gtk/gtkenums.h
index 4a2bb58959..c4857756d2 100644
--- a/gtk/gtkenums.h
+++ b/gtk/gtkenums.h
@@ -933,15 +933,14 @@ typedef enum {
 } GtkBorderStyle;
 
 /**
- * GtkGestureType:
- * @GTK_GESTURE_SWIPE_RIGHT: A swipe from left to right
- * @GTK_GESTURE_SWIPE_LEFT: A swipe from right to left
- * @GTK_GESTURE_SWIPE_UP: A swipe from bottom to top
- * @GTK_GESTURE_SWIPE_DOWN: A swipe from top to bottom
- * @GTK_GESTURE_CIRCULAR_CLOCKWISE: A circular clockwise movement
- * @GTK_GESTURE_CIRCULAR_COUNTERCLOCKWISE: A circular counterclockwise movement
+ * GtkCapturedEventFlags:
+ * @GTK_CAPTURED_EVENT_NONE: Event goes uncaptured
+ * @GTK_CAPTURED_EVENT_HANDLED: The event was handled
+ * @GTK_CAPTURED_EVENT_STORE: Store for later propagation, see
+ *   gtk_widget_release_captured_events()
  *
- * Describes the stock gestures handled by GTK+.
+ * Describes how an event in the #GtkWidget::captured-event handler
+ * is handled.
  */
 typedef enum {
   GTK_CAPTURED_EVENT_NONE    = 0,
@@ -970,6 +969,17 @@ typedef enum {
   GTK_KINETIC_SCROLLING_CAPTURE_BUTTON_PRESS = 1 << 1
 } GtkKineticScrollingFlags;
 
+/**
+ * GtkGestureType:
+ * @GTK_GESTURE_SWIPE_RIGHT: A swipe from left to right
+ * @GTK_GESTURE_SWIPE_LEFT: A swipe from right to left
+ * @GTK_GESTURE_SWIPE_UP: A swipe from bottom to top
+ * @GTK_GESTURE_SWIPE_DOWN: A swipe from top to bottom
+ * @GTK_GESTURE_CIRCULAR_CLOCKWISE: A circular clockwise movement
+ * @GTK_GESTURE_CIRCULAR_COUNTERCLOCKWISE: A circular counterclockwise movement
+ *
+ * Describes the stock gestures handled by GTK+.
+ */
 typedef enum {
   GTK_GESTURE_SWIPE_RIGHT = 1,
   GTK_GESTURE_SWIPE_LEFT,
diff --git a/gtk/gtkgesturesinterpreter.c b/gtk/gtkgesturesinterpreter.c
index 6d278e3a59..a479933964 100644
--- a/gtk/gtkgesturesinterpreter.c
+++ b/gtk/gtkgesturesinterpreter.c
@@ -435,6 +435,8 @@ gtk_gestures_interpreter_init (GtkGesturesInterpreter *interpreter)
  * Creates a new, empty stroke to be used in a gesture.
  *
  * Returns: (transfer full): a newly created #GtkGestureStroke
+ *
+ * Since: 3.4
  **/
 GtkGestureStroke *
 gtk_gesture_stroke_new (void)
@@ -454,6 +456,8 @@ gtk_gesture_stroke_new (void)
  * Copies a #GtkGestureStroke
  *
  * Returns: (transfer full): A copy of @stroke
+ *
+ * Since: 3.4
  **/
 GtkGestureStroke *
 gtk_gesture_stroke_copy (const GtkGestureStroke *stroke)
@@ -476,6 +480,8 @@ gtk_gesture_stroke_copy (const GtkGestureStroke *stroke)
  * @stroke: a #GtkGestureStroke
  *
  * Frees a #GtkGestureStroke and all its contained data
+ *
+ * Since: 3.4
  **/
 void
 gtk_gesture_stroke_free (GtkGestureStroke *stroke)
@@ -493,6 +499,8 @@ gtk_gesture_stroke_free (GtkGestureStroke *stroke)
  * @length: vector length
  *
  * Appends a vector to stroke.
+ *
+ * Since: 3.4
  **/
 void
 gtk_gesture_stroke_append_vector (GtkGestureStroke *stroke,
@@ -518,6 +526,8 @@ gtk_gesture_stroke_append_vector (GtkGestureStroke *stroke,
  * contains.
  *
  * Returns: The number of vectors in @stroke
+ *
+ * Since: 3.4
  **/
 guint
 gtk_gesture_stroke_get_n_vectors (const GtkGestureStroke *stroke)
@@ -546,6 +556,8 @@ gtk_gesture_stroke_get_n_vectors (const GtkGestureStroke *stroke)
  * returned.
  *
  * Returns: %TRUE if @n_vector is a valid vector
+ *
+ * Since: 3.4
  **/
 gboolean
 gtk_gesture_stroke_get_vector (const GtkGestureStroke *stroke,
@@ -596,6 +608,8 @@ gtk_gesture_stroke_get_vector (const GtkGestureStroke *stroke,
  * circular gestures).
  *
  * Returns: (transfer full): A newly created #GtkGesture
+ *
+ * Since: 3.4
  **/
 GtkGesture *
 gtk_gesture_new (const GtkGestureStroke *stroke,
@@ -626,6 +640,8 @@ gtk_gesture_new (const GtkGestureStroke *stroke,
  * Adds a further stroke to @gesture, @dx and @dy represent
  * the offset with the initial coordinates of the stroke
  * that was added through gtk_gesture_new().
+ *
+ * Since: 3.4
  **/
 void
 gtk_gesture_add_stroke (GtkGesture             *gesture,
@@ -654,6 +670,8 @@ gtk_gesture_add_stroke (GtkGesture             *gesture,
  *
  * Returns: (transfer full): a copy of @gesture. gtk_gesture_free() must be
  *          called on it when done.
+ *
+ * Since: 3.4
  **/
 GtkGesture *
 gtk_gesture_copy (const GtkGesture *gesture)
@@ -685,6 +703,8 @@ gtk_gesture_copy (const GtkGesture *gesture)
  * @gesture: a #GtkGesture
  *
  * Frees a #GtkGesture
+ *
+ * Since: 3.4
  **/
 void
 gtk_gesture_free (GtkGesture *gesture)
@@ -702,6 +722,8 @@ gtk_gesture_free (GtkGesture *gesture)
  * Returns the #GtkGestureFlags applying to @gesture
  *
  * Returns: the gesture flags
+ *
+ * Since: 3.4
  **/
 GtkGestureFlags
 gtk_gesture_get_flags (const GtkGesture *gesture)
@@ -718,6 +740,8 @@ gtk_gesture_get_flags (const GtkGesture *gesture)
  * Returns the number of strokes that compose @gesture
  *
  * Returns: the number of strokes
+ *
+ * Since: 3.4
  **/
 guint
 gtk_gesture_get_n_strokes (const GtkGesture *gesture)
@@ -740,6 +764,8 @@ gtk_gesture_get_n_strokes (const GtkGesture *gesture)
  * offset with respect to the first stroke.
  *
  * Returns: (transfer none): the @GtkGestureStroke, or %NULL
+ *
+ * Since: 3.4
  **/
 const GtkGestureStroke *
 gtk_gesture_get_stroke (const GtkGesture *gesture,
@@ -774,6 +800,8 @@ gtk_gesture_get_stroke (const GtkGesture *gesture,
  * This function creates an internal copy of @gesture
  *
  * Returns: the ID of the just registered gesture
+ *
+ * Since: 3.4
  **/
 guint
 gtk_gesture_register (const GtkGesture *gesture)
@@ -792,6 +820,8 @@ gtk_gesture_register (const GtkGesture *gesture)
  * create a copy of it.
  *
  * Returns: the ID of the just registered gesture
+ *
+ * Since: 3.4
  **/
 guint
 gtk_gesture_register_static (const GtkGesture *gesture)
@@ -817,6 +847,8 @@ gtk_gesture_register_static (const GtkGesture *gesture)
  * or %NULL if there is no gesture registered with such ID.
  *
  * Returns: (transfer none): the #GtkGesture, or %NULL
+ *
+ * Since: 3.4
  **/
 const GtkGesture *
 gtk_gesture_lookup (guint gesture_id)
@@ -836,6 +868,8 @@ gtk_gesture_lookup (guint gesture_id)
  * Creates a new #GtkGesturesInterpreter
  *
  * Returns: (transfer full): the newly created #GtkGesturesInterpreter
+ *
+ * Since: 3.4
  **/
 GtkGesturesInterpreter *
 gtk_gestures_interpreter_new (void)
@@ -857,6 +891,8 @@ gtk_gestures_interpreter_new (void)
  * handled by @interpreter, %FALSE will be returned
  *
  * Returns: %TRUE if the gesture is now handled
+ *
+ * Since: 3.4
  **/
 gboolean
 gtk_gestures_interpreter_add_gesture (GtkGesturesInterpreter *interpreter,
@@ -887,6 +923,8 @@ gtk_gestures_interpreter_add_gesture (GtkGesturesInterpreter *interpreter,
  * @gesture_id: gesture ID to stop handling
  *
  * Removes @gesture_id from being handled by @interpreter.
+ *
+ * Since: 3.4
  **/
 void
 gtk_gestures_interpreter_remove_gesture (GtkGesturesInterpreter *interpreter,
@@ -962,6 +1000,8 @@ gtk_gestures_interpreter_get_n_active_strokes (GtkGesturesInterpreter *interpret
  * returns %FALSE), %FALSE will be returned
  *
  * Returns: %TRUE if the event was useful to build the user gesture
+ *
+ * Since: 3.4
  **/
 gboolean
 gtk_gestures_interpreter_feed_event (GtkGesturesInterpreter *interpreter,
@@ -1393,6 +1433,8 @@ compare_gestures (const GtkGesture *gesture,
  * If %FALSE is returned, no gesture was recognized.
  *
  * Returns: %TRUE if the gesture matched
+ *
+ * Since: 3.4
  **/
 gboolean
 gtk_gestures_interpreter_finish (GtkGesturesInterpreter *interpreter,
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 073e64d2a1..7b10a06613 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -1878,10 +1878,11 @@ gtk_widget_class_init (GtkWidgetClass *klass)
    * @widget: the object which received the signal.
    * @event: the #GdkEvent which triggered this signal
    *
-   * The ::captured-event signal is emitted before the ::event signal to
-   * allow capturing an event before the specialized events are emitted.
-   * The event is propagated starting from the top-level container to
-   * the widget that received the event going down the hierarchy.
+   * The #GtkWidget::captured-event signal is emitted before the
+   * #GtkWidget::event signal to allow capturing an event before the
+   * specialized events are emitted. The event is propagated starting
+   * from the top-level container to the widget that received the event
+   * going down the hierarchy.
    *
    * This signal returns a #GtkCapturedEventFlags with the handling
    * status of the event, if %GTK_CAPTURED_EVENT_HANDLED is enabled,
@@ -3166,8 +3167,10 @@ gtk_widget_class_init (GtkWidgetClass *klass)
    * @gesture_id: gesture recognized
    *
    * This signal is emitted whenever a device with source
-   * #GDK_SOURCE_TOUCHSCREEN finishes a gesture that resembles
+   * #GDK_SOURCE_TOUCH finishes a gesture that resembles
    * one of those added through gtk_widget_enable_gesture().
+   *
+   * Since: 3.4
    */
   widget_signals[GESTURE] =
     g_signal_new (I_("gesture"),