[gtk+] gtkwindow: Document further resize with csd

[Olivier Fourdan <ofourdan src gnome org>]

commit de41389352271c18233601d3fa22de21e31024be
Author: Olivier Fourdan <ofourdan redhat com>
Date:   Wed Dec 2 11:15:39 2015 +0100

    gtkwindow: Document further resize with csd
    
    Applying the client-side decorations in the configure routine greatly
    increases the chances of having the right size for the GtkHEaderBar and
    border shadows.
    
    Yet, it may be possible that these sizes change at a later point in
    time, if for example the GtkHeaderBar grows in height while adding new
    controls.
    
    Mention this possible pitfall in the documentation for
    gtk_window_resize().
    
    https://bugzilla.gnome.org/show_bug.cgi?id=756618

 gtk/gtkwindow.c |    8 ++++++++
 1 files changed, 8 insertions(+), 0 deletions(-)
---
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 5cb743a..7b64cb4 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -5306,6 +5306,14 @@ gtk_window_get_default_size (GtkWindow *window,
  * client side decorations depend on the theme and may not be realized
  * or visible at the time gtk_window_resize() is issued.
  *
+ * Typically, gtk_window_resize() will compensate for the GtkHeaderBar
+ * height only if it's known at the time the resulting GtkWindow
+ * configuration is issued.
+ * For example, if new widgets are added after the GtkWindow configuration
+ * and cause the GtkHeaderBar to grow in height, this will result in a
+ * window content smaller that specified by gtk_window_resize() and not
+ * a larger window.
+ *
  **/
 void
 gtk_window_resize (GtkWindow *window,