[gtk+/multitouch-for-3.4: 80/89] improve docs for multitouch features

[Carlos Garnacho <carlosg src gnome org>]

commit 2a1437c3e9c9db06ee6d36b774ee2398d584326a
Author: Carlos Garnacho <carlosg gnome org>
Date:   Fri Jan 13 02:38:44 2012 +0100

    improve docs for multitouch features

 docs/reference/gtk/gtk3-sections.txt |    2 ++
 gdk/gdkevents.c                      |    4 ++++
 gdk/gdkevents.h                      |   24 +++++++++++++++++++-----
 gdk/gdktypes.h                       |    7 +++++++
 gtk/gtkwidget.c                      |    9 +++++----
 5 files changed, 37 insertions(+), 9 deletions(-)
---
diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt
index a6d8361..66cc247 100644
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/docs/reference/gtk/gtk3-sections.txt
@@ -5031,6 +5031,7 @@ GtkAllocation
 GtkSelectionData
 GtkWidgetAuxInfo
 GtkWidgetHelpType
+GtkCapturedEventFlags
 gtk_widget_new
 gtk_widget_destroy
 gtk_widget_in_destruction
@@ -5216,6 +5217,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 6f20735..f78f459 100644
--- a/gdk/gdkevents.c
+++ b/gdk/gdkevents.c
@@ -1756,6 +1756,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,
@@ -1802,6 +1804,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 8208fb3..60437c1 100644
--- a/gdk/gdkevents.h
+++ b/gdk/gdkevents.h
@@ -263,9 +263,12 @@ 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_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_EVENT_LAST: marks the end of the GdkEventType enumeration. Added in 2.18
  *
  * Specifies the type of the event.
@@ -573,6 +576,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
 {
@@ -593,7 +600,8 @@ struct _GdkEventMotion
 /**
  * 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>).
@@ -619,7 +627,8 @@ struct _GdkEventMotion
  *
  * 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:
@@ -651,6 +660,11 @@ struct _GdkEventMotion
  * 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/gdktypes.h b/gdk/gdktypes.h
index d8712b6..bab9978 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/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 3e73512..77a9b80 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -1844,10 +1844,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.
    *
    * Returns: %TRUE to stop other handlers from being invoked for the event
    * and to cancel the emission of the ::event signal.