diff --git a/docs/reference/gdk/tmpl/windows.sgml b/docs/reference/gdk/tmpl/windows.sgml
index 06d9f927f9..82cf5eb26c 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
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.
+Composited Windows
+
+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
+composited window it is the responsibility of the
+application to render the window contents at the right spot.
+
Composited windows
@@ -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)
]]>
-In the 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 , 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.
When the contents of the event box change, an expose event is
@@ -168,8 +176,25 @@ that it wishes.
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.
+
+Offscreen Windows
+
+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.
+
+
+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.
+
+
diff --git a/gdk/gdkoffscreenwindow.c b/gdk/gdkoffscreenwindow.c
index 0029708591..9a3942c6a3 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 3acf0ff4af..d2dacf23e1 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;