gdk: Document event compression better

Advise against using GDK_POINTER_MOTION_HINT_MASK.
Add pointers to gdk_window_set_event_compression() to the documentation.

2 files changed, 17 insertions, 10 deletions

diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c
index 6355073b2c..d41380430d 100644
--- a/gdk/gdkdevice.c
+++ b/gdk/gdkdevice.c
@@ -593,6 +593,10 @@ gdk_device_get_window_at_position (GdkDevice  *device,
  * be returned. (This is not distinguishable from the case where
  * motion history is supported and no events were found.)
  *
+ * Note that there is also gdk_window_set_event_compression() to get
+ * more motion events delivered directly, independent of the windowing
+ * system.
+ *
  * Return value: %TRUE if the windowing system supports motion history and
  *  at least one event was found.
  **/
diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h
index d821251cac..1ca617e961 100644
--- a/gdk/gdktypes.h
+++ b/gdk/gdktypes.h
@@ -328,7 +328,7 @@ typedef enum
  * GdkEventMask:
  * @GDK_EXPOSURE_MASK: receive expose events
  * @GDK_POINTER_MOTION_MASK: receive all pointer motion events
- * @GDK_POINTER_MOTION_HINT_MASK: see the explanation above
+ * @GDK_POINTER_MOTION_HINT_MASK: deprecated. see the explanation above
  * @GDK_BUTTON_MOTION_MASK: receive pointer motion events while any button is pressed
  * @GDK_BUTTON1_MOTION_MASK: receive pointer motion events while 1 button is pressed
  * @GDK_BUTTON2_MOTION_MASK: receive pointer motion events while 2 button is pressed
@@ -356,15 +356,18 @@ typedef enum
  * Most of these masks map onto one or more of the #GdkEventType event types
  * above.
  *
- * %GDK_POINTER_MOTION_HINT_MASK is a special mask which is used to reduce the
- * number of %GDK_MOTION_NOTIFY events received. Normally a %GDK_MOTION_NOTIFY
- * event is received each time the mouse moves. However, if the application
- * spends a lot of time processing the event (updating the display, for example),
- * it can lag behind the position of the mouse. When using
- * %GDK_POINTER_MOTION_HINT_MASK, fewer %GDK_MOTION_NOTIFY events will be sent,
- * 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().
+ * %GDK_POINTER_MOTION_HINT_MASK is deprecated. It is a special mask
+ * to reduce the number of %GDK_MOTION_NOTIFY events received. When using
+ * %GDK_POINTER_MOTION_HINT_MASK, fewer %GDK_MOTION_NOTIFY events will
+ * be sent, 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().
+ * 
+ * Since GTK 3.8, motion events are already compressed by default, independent
+ * of this mechanism. This compression can be disabled with
+ * gdk_window_set_event_compression(). See the documentation of that function
+ * for details.
  *
  * If %GDK_TOUCH_MASK is enabled, the window will receive touch events
  * from touch-enabled devices. Those will come as sequences of #GdkEventTouch