[gtk+] Add more hints

[Matthias Clasen <matthiasc src gnome org>]

commit d409cf2bf395896e856fe1affe438dd0c041824f
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Sep 10 13:51:02 2009 -0400

    Add more hints
    
    Mention problems related to cairo and clipping.

 .../reference/gtk/migrating-ClientSideWindows.sgml |   13 +++++++++++++
 1 files changed, 13 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gtk/migrating-ClientSideWindows.sgml b/docs/reference/gtk/migrating-ClientSideWindows.sgml
index 5eecd19..3860ee5 100644
--- a/docs/reference/gtk/migrating-ClientSideWindows.sgml
+++ b/docs/reference/gtk/migrating-ClientSideWindows.sgml
@@ -39,4 +39,17 @@
     may be affected by this.
   </para>
 
+  <para>
+    Problems can also occur when using cairo for drawing. One thing that can
+    go wrong is clip handling. If you ever need to reset the clip region on
+    a cairo_t (i.e. use cairo_reset_clip()), you have to to use
+    gdk_cairo_reset_clip() instead. The reason for this is that the cairo_reset_clip() call will remove the initial clip region that limits your drawing to
+    the client-side window at hand, so you will end up drawing over stuff
+    outside the window. You also need to use gdk_cairo_reset_clip() if you
+    use a cairo_t that was not allocated in a double-buffered expose handler
+    and keep it in use after window hierarchy changes (resizing, moving,
+    stacking order changes). The easiest fix for this kind of problem is to
+    simply create a new cairo context for each expose event.
+  </para>
+
 </chapter>