Improve CSW docs

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 
+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. 
+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 
+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 
+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 
+set as composited and therefore is no longer automatically drawn to
-the screen. 
+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>

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

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
+ * @width: width of redirection, or -1 to use the width of @window
- * @height: height of redirection
+ * @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,
+	       gdouble          embedder_x,
-	       double *offscreen_x, double *offscreen_y)
+               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,
+			 gdouble          x,
-			 double *child_x, double *child_y)
+                         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,
+				   gdouble    child_x,
-				   double *toplevel_x, double *toplevel_y)
+                                   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,
+				gdouble    x,
-				double *found_x,
+                                gdouble    y,
-				double *found_y)
+				gdouble   *found_x,
+				gdouble   *found_y)
 {
   GdkWindowObject *private, *sub;
-  double child_x, child_y;
+  gdouble child_x, child_y;
   GList *l;
   gboolean found;