From ab66ac50cf5328612b537b0e9aba425584e31ddd Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Sat, 5 Feb 2011 01:56:19 -0500
Subject: [PATCH] Migration guide additions

Some information about plugs and sockets, and event filters.
---
 docs/reference/gtk/migrating-2to3.xml | 78 +++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)

diff --git a/docs/reference/gtk/migrating-2to3.xml b/docs/reference/gtk/migrating-2to3.xml
index 622d61b5e9..2b2f4728e2 100644
--- a/docs/reference/gtk/migrating-2to3.xml
+++ b/docs/reference/gtk/migrating-2to3.xml
@@ -779,6 +779,73 @@ on_alpha_screen_changed (GtkWindow *window,
     </para>
   </section>
 
+  <section>
+    <title>Event filtering</title>
+
+    <para>
+      If your application uses the low-level event filtering facilities in GDK,
+      there are some changes you need to be aware of.
+    </para>
+
+    <para>
+      The special-purpose GdkEventClient events and the gdk_add_client_message_filter() and gdk_display_add_client_message_filter() functions have been
+      removed. Receiving X11 ClientMessage events is still possible, using
+      the general gdk_window_add_filter() API. A client message filter like
+<informalexample><programlisting>
+static GdkFilterReturn
+message_filter (GdkXEvent *xevent, GdkEvent *event, gpointer data)
+{
+  XClientMessageEvent *evt = (XClientMessageEvent *)xevent;
+
+  /* do something with evt ... */
+}
+
+ ...
+
+message_type = gdk_atom_intern ("MANAGER", FALSE);
+gdk_display_add_client_message_filter (display, message_type, message_filter, NULL);
+</programlisting></informalexample>
+    then looks like this:
+    <informalexample><programlisting>
+static GdkFilterReturn
+event_filter (GdkXEvent *xevent, GdkEvent *event, gpointer data)
+{
+  XClientMessageEvent *evt;
+  GdkAtom message_type;
+
+  if (((XEvent *)xevent)->type != ClientMessage)
+    return GDK_FILTER_CONTINUE;
+
+  evt = (XClientMessageEvent *)xevent;
+  message_type = XInternAtom (evt->display, "MANAGER", FALSE);
+
+  if (evt->message_type != message_type)
+    return GDK_FILTER_CONTINUE;
+
+  /* do something with evt ... */
+}
+
+ ...
+
+gdk_window_add_filter (NULL, message_filter, NULL);
+</programlisting></informalexample>
+      One advantage of using an event filter is that you can actually
+      remove the filter when you don't need it anymore, using
+      gdk_window_remove_filter().
+    </para>
+
+    <para>
+      The other difference to be aware of when working with event filters
+      in GTK+ 3 is that GDK now uses XI2 by default when available. That
+      means that your application does not receive core X11 key or button
+      events. Instead, all input events are delivered as XIDeviceEvents.
+      As a short-term workaround for this, you can force your application
+      to not use XI2, with gdk_disable_multidevice(). In the long term,
+      you probably want to rewrite your event filter to deal with
+      XIDeviceEvents.
+    </para>
+  </section>
+
   <section>
     <title>Backend-specific code</title>
     <para>
@@ -822,6 +889,17 @@ on_alpha_screen_changed (GtkWindow *window,
     </para>
   </section>
 
+  <section>
+    <title>GtkPlug and GtkSocket</title>
+
+    <para>
+      The #GtkPlug and #GtkSocket widgets are now X11-specific, and you
+      have to include the <filename>&lt;gtk/gtkx.h&gt;</filename> header
+      to use them. The previous section about proper handling of
+      backend-specific code applies, if you care about other backends.
+    </para>
+  </section>
+
   <section>
     <title>The GtkWidget::draw signal</title>
     <para>