Make 3.0 parallel-installable to 2.x

[~andy/gtk] / docs / reference / gdk / tmpl / windows.sgml

diff --git a/docs/reference/gdk/tmpl/windows.sgml b/docs/reference/gdk/tmpl/windows.sgml
index 8498da00c4554c4d1cb00d16dc46c859e673bda4..9f621678a0ad19879608c95ad96c5447e352ace3 100644 (file)
--- 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,9 +176,31 @@ 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_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>
 
+<para>
+For rendering an offscreen window onto its embedder, the contents of the
+offscreen window are available as a pixmap, via
+gdk_offscreen_window_get_pixmap().
+</para>
+</refsect2>
+
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
@@ -179,6 +209,9 @@ that the background shows through the button.
 <!-- ##### SECTION Stability_Level ##### -->
 
 
+<!-- ##### SECTION Image ##### -->
+
+
 <!-- ##### STRUCT GdkWindow ##### -->
 <para>
 An opaque structure representing an onscreen drawable.
@@ -189,6 +222,43 @@ these types.
 </para>
 
 
+<!-- ##### SIGNAL GdkWindow::from-embedder ##### -->
+<para>
+
+</para>
+
+@gdkwindow: the object which received the signal.
+@arg1: 
+@arg2: 
+@arg3: 
+@arg4: 
+
+<!-- ##### SIGNAL GdkWindow::pick-embedded-child ##### -->
+<para>
+
+</para>
+
+@gdkwindow: the object which received the signal.
+@arg1: 
+@arg2: 
+@Returns: 
+
+<!-- ##### SIGNAL GdkWindow::to-embedder ##### -->
+<para>
+
+</para>
+
+@gdkwindow: the object which received the signal.
+@arg1: 
+@arg2: 
+@arg3: 
+@arg4: 
+
+<!-- ##### ARG GdkWindow:cursor ##### -->
+<para>
+
+</para>
+
 <!-- ##### ENUM GdkWindowType ##### -->
 <para>
 Describes the kind of window.
@@ -200,6 +270,7 @@ Describes the kind of window.
 @GDK_WINDOW_DIALOG: useless/deprecated compatibility type
 @GDK_WINDOW_TEMP: override redirect temporary window (used to implement #GtkMenu)
 @GDK_WINDOW_FOREIGN: foreign window (see gdk_window_foreign_new())
+@GDK_WINDOW_OFFSCREEN: offscreen window (see <xref linkend="OFFSCREEN-WINDOWS"/>). Since 2.18
 
 <!-- ##### ENUM GdkWindowClass ##### -->
 <para>
@@ -497,6 +568,15 @@ Deprecated equivalent of g_object_unref()
 @window: 
 
 
+<!-- ##### FUNCTION gdk_window_is_destroyed ##### -->
+<para>
+
+</para>
+
+@window: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gdk_window_is_visible ##### -->
 <para>
 
@@ -685,6 +765,23 @@ Deprecated equivalent of g_object_unref()
 @dy: 
 
 
+<!-- ##### FUNCTION gdk_window_flush ##### -->
+<para>
+
+</para>
+
+@window: 
+
+
+<!-- ##### FUNCTION gdk_window_ensure_native ##### -->
+<para>
+
+</para>
+
+@window: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gdk_window_reparent ##### -->
 <para>
 
@@ -764,6 +861,16 @@ Deprecated equivalent to gdk_draw_drawable(), see that function for docs
 @window: 
 
 
+<!-- ##### FUNCTION gdk_window_restack ##### -->
+<para>
+
+</para>
+
+@window: 
+@sibling: 
+@above: 
+
+
 <!-- ##### FUNCTION gdk_window_focus ##### -->
 <para>
 
@@ -880,7 +987,7 @@ Registers a window as a potential drop destination.
 
 @window: 
 @region: 
-@child_func: 
+@GdkWindow *, gpointer: 
 @user_data: 
 
 
@@ -914,6 +1021,7 @@ Registers a window as a potential drop destination.
 
 </para>
 
+@void: 
 
 
 <!-- ##### FUNCTION gdk_window_process_updates ##### -->
@@ -1200,6 +1308,15 @@ window.
 @cursor: 
 
 
+<!-- ##### FUNCTION gdk_window_get_cursor ##### -->
+<para>
+
+</para>
+
+@window: 
+@Returns: 
+
+
 <!-- ##### MACRO gdk_window_set_colormap ##### -->
 <para>
 Deprecated equivalent to gdk_drawable_set_colormap()
@@ -1384,6 +1501,18 @@ Deprecated equivalent of gdk_drawable_get_type().
 @Returns: 
 
 
+<!-- ##### FUNCTION gdk_window_get_root_coords ##### -->
+<para>
+
+</para>
+
+@window: 
+@x: 
+@y: 
+@root_x: 
+@root_y: 
+
+
 <!-- ##### FUNCTION gdk_window_get_pointer ##### -->
 <para>
 
@@ -1620,6 +1749,7 @@ The hint must be set before mapping the window.
 
 </para>
 
+@void: 
 @Returns: 
 
 
@@ -1628,6 +1758,7 @@ The hint must be set before mapping the window.
 
 </para>
 
+@void: 
 @Returns: 
 
 
@@ -1659,19 +1790,40 @@ Applications should never have any reason to use this facility
 @Returns: 
 
 
-<!--
-Local variables:
-mode: sgml
-sgml-parent-document: ("../gdk-docs.sgml" "book" "refsect2" "")
-End:
--->
+<!-- ##### FUNCTION gdk_offscreen_window_get_pixmap ##### -->
+<para>
+
+</para>
+
+@window: 
+@Returns: 
 
 
-<!-- ##### STRUCT GdkWindowRedirect ##### -->
+<!-- ##### FUNCTION gdk_offscreen_window_set_embedder ##### -->
 <para>
 
 </para>
 
+@window: 
+@embedder: 
+
+
+<!-- ##### FUNCTION gdk_offscreen_window_get_embedder ##### -->
+<para>
+
+</para>
+
+@window: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_window_geometry_changed ##### -->
+<para>
+
+</para>
+
+@window: 
+
 
 <!-- ##### FUNCTION gdk_window_redirect_to_drawable ##### -->
 <para>
@@ -1696,3 +1848,11 @@ End:
 @window: 
 
 
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-docs.sgml" "book" "refsect2" "")
+End:
+-->
+
+