[gtk+] docs: Update gtk_window_get_size()

[Emmanuele Bassi <ebassi src gnome org>]

commit 08e443e0db6f74ade5836f8028073aeac14aab38
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Sat Sep 17 12:47:39 2016 +0100

    docs: Update gtk_window_get_size()
    
    The main corpus of the documentation for gtk_window_get_size() is still
    full of X11-isms, so we should port it to something that is more
    backend-agnostic. Additionally, having some examples would be nice for
    application authors looking at a way to appropriately use this function.

 gtk/gtkwindow.c |  133 +++++++++++++++++++++++++++++++-----------------------
 1 files changed, 76 insertions(+), 57 deletions(-)
---
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index d8b3c21..fc1e050 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -5400,63 +5400,82 @@ gtk_window_resize_to_geometry (GtkWindow *window,
 /**
  * gtk_window_get_size:
  * @window: a #GtkWindow
- * @width: (out) (allow-none): return location for width, or %NULL
- * @height: (out) (allow-none): return location for height, or %NULL
- *
- * Obtains the current size of @window. If @window is not onscreen,
- * it returns the size GTK+ will suggest to the
- * [window manager][gtk-X11-arch]
- * for the initial window
- * size (but this is not reliably the same as the size the window
- * manager will actually select). The size obtained by
- * gtk_window_get_size() is the last size received in a
- * #GdkEventConfigure, that is, GTK+ uses its locally-stored size,
- * rather than querying the X server for the size. As a result, if you
- * call gtk_window_resize() then immediately call
- * gtk_window_get_size(), the size won’t have taken effect yet. After
- * the window manager processes the resize request, GTK+ receives
- * notification that the size has changed via a configure event, and
- * the size of the window gets updated.
- *
- * Note 1: Nearly any use of this function creates a race condition,
- * because the size of the window may change between the time that you
- * get the size and the time that you perform some action assuming
- * that size is the current size. To avoid race conditions, connect to
- * “configure-event” on the window and adjust your size-dependent
- * state to match the size delivered in the #GdkEventConfigure.
- *
- * Note 2: The returned size does not include the
- * size of the window manager decorations (aka the window frame or
- * border). Those are not drawn by GTK+ and GTK+ has no reliable
- * method of determining their size.
- *
- * Note 3: If you are getting a window size in order to position
- * the window onscreen, there may be a better way. The preferred
- * way is to simply set the window’s semantic type with
- * gtk_window_set_type_hint(), which allows the window manager to
- * e.g. center dialogs. Also, if you set the transient parent of
- * dialogs with gtk_window_set_transient_for() window managers
- * will often center the dialog over its parent window. It's
- * much preferred to let the window manager handle these
- * things rather than doing it yourself, because all apps will
- * behave consistently and according to user prefs if the window
- * manager handles it. Also, the window manager can take the size
- * of the window decorations/border into account, while your
- * application cannot.
- *
- * Note 4: When using client side decorations, GTK+ will do its best to
- * adjust the returned values to match the logical size of the window
- * excluding the widgets added for client side decorations, but there
- * is no garantee that the result will be totally accurate because
- * these widgets depend on the theme and may not be realized or
- * visible at the time gtk_window_get_size() is invoked.
- *
- * In any case, if you insist on application-specified window
- * positioning, there’s still a better way than
- * doing it yourself - gtk_window_set_position() will frequently
- * handle the details for you.
- * 
- **/
+ * @width: (out) (nullable): return location for width, or %NULL
+ * @height: (out) (nullable): return location for height, or %NULL
+ *
+ * Obtains the current size of @window.
+ *
+ * If @window is not visible on screen, this function return the size GTK+
+ * will suggest to the [window manager][gtk-X11-arch] for the initial window
+ * size (but this is not reliably the same as the size the window manager
+ * will actually select). See: gtk_window_set_default_size().
+ *
+ * Depending on the windowing system and the window manager constraints,
+ * the size returned by this function may not match the size set using
+ * gtk_window_resize(); additionally, since gtk_window_resize() may be
+ * implemented as an asynchronous operation, GTK+ cannot guarantee in any
+ * way that this code:
+ *
+ * |[<!-- language="C" -->
+ *   // width and height are set elsewhere
+ *   gtk_window_resize (window, width, height);
+ *
+ *   int new_width, new_height;
+ *   gtk_window_get_size (window, &new_width, &new_height);
+ * ]|
+ *
+ * will result in `new_width` and `new_height` matching `width` and
+ * `height`, respectively.
+ *
+ * This function will return the logical size of the #GtkWindow,
+ * excluding the widgets used in client side decorations; there is,
+ * however, no guarantee that the result will be completely accurate
+ * because client side decoration may include widgets that depend on
+ * the user preferences and that may not be visibile at the time you
+ * call this function.
+ *
+ * The dimensions returned by this function are suitable for being
+ * stored across sessions; use gtk_window_set_default_size() to
+ * restore them when before showing the window.
+ *
+ * To avoid potential race conditions, you should only call this
+ * function in response to a size change notification, for instance
+ * inside a handler for the #GtkWidget::size-allocate signal, or
+ * inside a handler for the #GtkWidget::configure-event signal:
+ *
+ * |[<!-- language="C" -->
+ * static void
+ * on_size_allocate (GtkWidget *widget, GtkAllocation *allocation)
+ * {
+ *   int new_width, new_height;
+ *
+ *   gtk_window_get_size (GTK_WINDOW (widget), &new_width, &new_height);
+ *
+ *   ...
+ * }
+ * ]|
+ *
+ * Note that, if you connect to the #GtkWidget::size-allocate signal,
+ * you should not use the dimensions of the #GtkAllocation passed to
+ * the signal handler, as the allocation may contain client side
+ * decorations added by GTK+, depending on the windowing system in
+ * use.
+ *
+ * If you are getting a window size in order to position the window
+ * on the screen, you should, instead, simply set the window’s semantic
+ * type with gtk_window_set_type_hint(), which allows the window manager
+ * to e.g. center dialogs. Also, if you set the transient parent of
+ * dialogs with gtk_window_set_transient_for() window managers will
+ * often center the dialog over its parent window. It's much preferred
+ * to let the window manager handle these cases rather than doing it
+ * yourself, because all apps will behave consistently and according to
+ * user or system preferences, if the window manager handles it. Also,
+ * the window manager can take into account the size of the window
+ * decorations and border that it may add, and of which GTK+ has no
+ * knowledge. Additionally, positioning windows in global screen coordinates
+ * may not be allowed by the windowing system. For more information,
+ * see: gtk_window_set_position().
+ */
 void
 gtk_window_get_size (GtkWindow *window,
                      gint      *width,