[gtk+] Improve CSW docs

[Matthias Clasen <matthiasc src gnome org>]

commit 5e5ab90a5708d6c2bcd8b073dda0ae509dd62464
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Aug 31 00:55:32 2009 -0400

    Improve CSW docs

 docs/reference/gdk/tmpl/windows.sgml |   41 +++++++++++++++++++++++-----
 gdk/gdkoffscreenwindow.c             |    7 +++++
 gdk/gdkwindow.c                      |   49 +++++++++++++++++++++------------
 3 files changed, 71 insertions(+), 26 deletions(-)
---
diff --git a/docs/reference/gdk/tmpl/windows.sgml b/docs/reference/gdk/tmpl/windows.sgml
index 06d9f92..82cf5eb 100644
--- a/docs/reference/gdk/tmpl/windows.sgml
+++ b/docs/reference/gdk/tmpl/windows.sgml
@@ -8,10 +8,18 @@ Onscreen display areas in the target window system
 <para>
 A #GdkWindow is a rectangular region on the screen. It's a low-level object,
 used to implement high-level objects such as #GtkWidget and #GtkWindow on the
-GTK+ level. A #GtkWindow is a toplevel window, the thing a user might think of 
-as a "window" with a titlebar and so on; a #GtkWindow may contain many #GdkWindow. 
+GTK+ level. A #GtkWindow is a toplevel window, the thing a user might think of
+as a "window" with a titlebar and so on; a #GtkWindow may contain many #GdkWindow.
 For example, each #GtkButton has a #GdkWindow associated with it.
 </para>
+<refsect2 id="COMPOSITED-WINDOWS"><title>Composited Windows</title>
+<para>
+Normally, the windowing system takes care of rendering the contents of a child
+window onto its parent window. This mechanism can be intercepted by calling
+gdk_window_set_composited() on the child window. For a
+<firstterm>composited</firstterm> window it is the responsibility of the
+application to render the window contents at the right spot.
+</para>
 <example id="composited-window-example"><title>Composited windows</title>
 <programlisting><![CDATA[
 #include <gtk/gtk.h>
@@ -54,7 +62,7 @@ transparent_expose (GtkWidget      *widget,
  * this handler is called after the red has been drawn. If it was
  * called before then GTK would just blindly paint over our work.
  *
- * Note: if the child window has children, then you need a cairo 1.16
+ * Note: if the child window has children, then you need a cairo 1.6
  * feature to make this work correctly.
  */
 static gboolean
@@ -153,10 +161,10 @@ main (int argc, char **argv)
 ]]>
 </programlisting></example>
 <para>
-In the example <xref linkend="composited-window-example"/>, a button is 
-placed inside of an event box inside of a window. The event box is 
-set as composited and therefore is no longer automatically drawn to 
-the screen. 
+In the example <xref linkend="composited-window-example"/>, a button is
+placed inside of an event box inside of a window. The event box is
+set as composited and therefore is no longer automatically drawn to
+the screen.
 </para>
 <para>
 When the contents of the event box change, an expose event is
@@ -168,8 +176,25 @@ that it wishes.
 <para>
 In our case, we merge the contents with a 50% transparency. We
 also set the background colour of the window to red. The effect is
-that the background shows through the button. 
+that the background shows through the button.
+</para>
+</refsect2>
+<refsect2 id="OFFSCREEN-WINDOWS"><title>Offscreen Windows</title>
+<para>
+Offscreen windows are more general than composited windows, since they
+allow not only to modify the rendering of the child window onto its parent,
+but also to apply coordinate transformations.
+</para>
+<para>
+To integrate an offscreen window into a window hierarchy, one has to call
+gdk_window_set_embedder() and handle a number of signals. The
+gdk_offscreen_window_set_embedder() and handle a number of signals. The
+#GdkWindow::pick-embedded-child signal on the embedder window is used to
+select an offscreen child at given coordinates, and the #GdkWindow::to-embedder
+and #GdkWindow::from-embedder signals on the offscreen window are used to
+translate coordinates between the embedder and the offscreen window.
 </para>
+</refsect2>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
diff --git a/gdk/gdkoffscreenwindow.c b/gdk/gdkoffscreenwindow.c
index 0029708..9a3942c 100644
--- a/gdk/gdkoffscreenwindow.c
+++ b/gdk/gdkoffscreenwindow.c
@@ -1161,6 +1161,13 @@ gdk_offscreen_window_queue_translation (GdkWindow *window,
  * @window: a #GdkWindow
  * @embedder: the #GdkWindow that @window gets embedded in
  *
+ * Sets @window to be embedded in @embedder.
+ *
+ * To fully embed an offscreen window, in addition to calling this
+ * function, it is also necessary to handle the #GdkWindow::pick-embedded-child
+ * signal on the @embedder and the #GdkWindow::to-embedder and
+ * #GdkWindow::from-embedder signals on @window.
+ *
  * Since: 2.18
  */
 void
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index 3acf0ff..d2dacf2 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -480,7 +480,7 @@ gdk_window_class_init (GdkWindowObjectClass *klass)
    * The ::pick-embedded-child signal is emitted to find an embedded
    * child at the given position.
    *
-   * Returns: the GdkWindow of the embedded child at @x, @y, or %NULL
+   * Returns: the #GdkWindow of the embedded child at @x, @y, or %NULL
    *
    * Since: 2.18
    */
@@ -507,6 +507,8 @@ gdk_window_class_init (GdkWindowObjectClass *klass)
    * The ::to-embedder signal is emitted to translate coordinates
    * in an offscreen window to its embedder.
    *
+   * See also #GtkWindow::from-embedder.
+   *
    * Since: 2.18
    */
   signals[TO_EMBEDDER] =
@@ -534,6 +536,8 @@ gdk_window_class_init (GdkWindowObjectClass *klass)
    * The ::from-embedder signal is emitted to translate coordinates
    * in the embedder of an offscreen window to the offscreen window.
    *
+   * See also #GtkWindow::to-embedder.
+   *
    * Since: 2.18
    */
   signals[FROM_EMBEDDER] =
@@ -2307,7 +2311,7 @@ gdk_screen_get_toplevel_windows (GdkScreen *screen)
  * Return value: list of toplevel windows, free with g_list_free()
  *
  * Deprecated: 2.16: Use gdk_screen_get_toplevel_windows() instead.
- **/
+ */
 GList *
 gdk_window_get_toplevels (void)
 {
@@ -7238,7 +7242,6 @@ gdk_window_set_back_pixmap (GdkWindow *window,
 /**
  * gdk_window_get_cursor:
  * @window: a #GdkWindow
- * @cursor: a cursor
  *
  * Retrieves a #GdkCursor pointer for the cursor currently set on the
  * specified #GdkWindow, or %NULL.  If the return value is %NULL then
@@ -8074,8 +8077,8 @@ apply_redirect_to_children (GdkWindowObject   *private,
  * @src_y: y position in @window
  * @dest_x: x position in @drawable
  * @dest_y: y position in @drawable
- * @width: width of redirection
- * @height: height of redirection
+ * @width: width of redirection, or -1 to use the width of @window
+ * @height: height of redirection or -1 to use the height of @window
  *
  * Redirects drawing into @window so that drawing to the
  * window in the rectangle specified by @src_x, @src_y,
@@ -8351,8 +8354,10 @@ update_cursor (GdkDisplay *display)
 
 static void
 from_embedder (GdkWindowObject *window,
-	       double embedder_x, double embedder_y,
-	       double *offscreen_x, double *offscreen_y)
+	       gdouble          embedder_x,
+               gdouble          embedder_y,
+	       gdouble         *offscreen_x,
+               gdouble         *offscreen_y)
 {
   g_signal_emit (window,
 		 signals[FROM_EMBEDDER], 0,
@@ -8363,8 +8368,10 @@ from_embedder (GdkWindowObject *window,
 
 static void
 convert_coords_to_child (GdkWindowObject *child,
-			 double x, double y,
-			 double *child_x, double *child_y)
+			 gdouble          x,
+                         gdouble          y,
+			 gdouble         *child_x,
+                         gdouble         *child_y)
 {
   if (gdk_window_is_offscreen (child))
     {
@@ -8380,7 +8387,8 @@ convert_coords_to_child (GdkWindowObject *child,
 
 static gboolean
 point_in_window (GdkWindowObject *window,
-		 double x, double y)
+		 gdouble          x,
+                 gdouble          y)
 {
   return
     x >= 0 && x < window->width &&
@@ -8395,8 +8403,10 @@ point_in_window (GdkWindowObject *window,
 
 static GdkWindow *
 convert_native_coords_to_toplevel (GdkWindow *window,
-				   double child_x, double child_y,
-				   double *toplevel_x, double *toplevel_y)
+				   gdouble    child_x,
+                                   gdouble    child_y,
+				   gdouble   *toplevel_x,
+                                   gdouble   *toplevel_y)
 {
   GdkWindowObject *private = (GdkWindowObject *)window;
   gdouble x, y;
@@ -8454,7 +8464,8 @@ convert_toplevel_coords_to_window (GdkWindow *window,
 
 static GdkWindowObject *
 pick_embedded_child (GdkWindowObject *window,
-		      double x, double y)
+		     gdouble          x,
+                     gdouble          y)
 {
   GdkWindowObject *res;
 
@@ -8468,7 +8479,8 @@ pick_embedded_child (GdkWindowObject *window,
 
 GdkWindow *
 _gdk_window_find_child_at (GdkWindow *window,
-			   int x, int y)
+			   int        x,
+                           int        y)
 {
   GdkWindowObject *private, *sub;
   double child_x, child_y;
@@ -8507,12 +8519,13 @@ _gdk_window_find_child_at (GdkWindow *window,
 
 GdkWindow *
 _gdk_window_find_descendant_at (GdkWindow *toplevel,
-				double x, double y,
-				double *found_x,
-				double *found_y)
+				gdouble    x,
+                                gdouble    y,
+				gdouble   *found_x,
+				gdouble   *found_y)
 {
   GdkWindowObject *private, *sub;
-  double child_x, child_y;
+  gdouble child_x, child_y;
   GList *l;
   gboolean found;