[gtk+] Add an migration chapter for CSW

[Matthias Clasen <matthiasc src gnome org>]

commit b6b64353a188275c0ee4e5f267080a881304769e
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Aug 31 01:26:11 2009 -0400

    Add an migration chapter for CSW

 docs/reference/gtk/Makefile.am                     |    1 +
 docs/reference/gtk/gtk-docs.sgml                   |    1 +
 .../reference/gtk/migrating-ClientSideWindows.sgml |   39 ++++++++++++++++++++
 3 files changed, 41 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index 30cce0c..21eed24 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -129,6 +129,7 @@ content_files =					\
 	drawing-model.xml			\
 	glossary.xml				\
 	migrating-checklist.sgml		\
+        migrating-ClientSideWindows.sgml	\
 	migrating-GtkAboutDialog.sgml		\
 	migrating-GtkAction.sgml		\
 	migrating-GtkAssistant.sgml		\
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 9b65c5e..e6e2fe4 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -435,6 +435,7 @@ that is, GUI components such as #GtkButton or #GtkTextView.
     <xi:include href="xml/migrating-GtkTooltip.sgml" />
     <xi:include href="xml/migrating-GtkEntry-icons.sgml" />
     <xi:include href="xml/migrating-GtkLabel-links.sgml" />
+    <xi:include href="xml/migrating-ClientSideWindows.sgml" />
   </part>
 
   <part>
diff --git a/docs/reference/gtk/migrating-ClientSideWindows.sgml b/docs/reference/gtk/migrating-ClientSideWindows.sgml
new file mode 100644
index 0000000..4880134
--- /dev/null
+++ b/docs/reference/gtk/migrating-ClientSideWindows.sgml
@@ -0,0 +1,39 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"; [
+]>
+<chapter id="gtk-migrating-ClientSideWindows">
+
+  <title>Migrating to client-side windows</title>
+
+  <para>
+    In version 2.18, GDK has been changed to use client-side windows. This
+    means that there is no longer a 1-1 correspondence between #GdkWindows
+    and windows in the underlying window system. In particular, it is no
+    longer correct to assume that each window has an associated XID.
+    Code that makes this assumption can sometimes be fixed by calling
+    gdk_window_ensure_native() on the windows in question.
+  </para>
+
+  <para>
+    GDK looks for the <envvar>GDK_NATIVE_WINDOWS</envvar> environment variable
+    and makes all windows native if it is set. It also tries to be more
+    compatible with the way prior versions worked in some other ways.
+  </para>
+
+  <para>
+    Some applications assume that they can just operate on the X windows
+    corresponding to their GDK windows without ever telling GDK. One
+    example that we've seen is changing the child window stacking order
+    using XRestackWindows(). Fixing this properly requires to fix the code
+    to use GDK functions to achieve whatever it is trying to achieve.
+  </para>
+
+  <para>
+    One change that can cause problems for some applications is that GDK
+    is more aggressive about optimizing away expose events. Code that does
+    more than just repainting exposed areas in response to expose events
+    may be affected by this.
+  </para>
+
+</chapter>