[pygtk] reference: pygtk-gtkoffscreenwindow.xml: add purpose, interfaces, properties and signals + update me

[John Stowers <jstowers src gnome org>]

commit 87da282b140cf3a9012cef6c8500b16e39492343
Author: Dieter Verfaillie <dieterv optionexplicit be>
Date:   Tue Mar 15 17:35:13 2011 +0100

    reference: pygtk-gtkoffscreenwindow.xml: add purpose, interfaces, properties and signals + update methods

 docs/reference/pygtk-gtkoffscreenwindow.xml |   87 +++++++++++++++++++++++---
 1 files changed, 77 insertions(+), 10 deletions(-)
---
diff --git a/docs/reference/pygtk-gtkoffscreenwindow.xml b/docs/reference/pygtk-gtkoffscreenwindow.xml
index e8ec025..850141f 100644
--- a/docs/reference/pygtk-gtkoffscreenwindow.xml
+++ b/docs/reference/pygtk-gtkoffscreenwindow.xml
@@ -5,7 +5,7 @@
 <refentry id="class-gtkoffscreenwindow">
   <refnamediv>
     <refname>gtk.OffscreenWindow</refname>
-    <refpurpose></refpurpose>
+    <refpurpose>a toplevel container widget used to manage offscreen rendering of child widgets (new in PyGTK 2.22)</refpurpose>
   </refnamediv>
 
   <refsect1>
@@ -45,6 +45,76 @@
   </refsect1>
 
   <refsect1>
+    <title>Implemented Interfaces</title>
+    <para>
+      <link linkend="class-gtkoffscreenwindow"><classname>gtk.OffscreenWindow</classname></link>
+      implements
+      <link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>
+      <link linkend="class-atkimplementor"><classname>atk.ImplementorIFace</classname></link>
+    </para>
+  </refsect1>
+
+  <refsect1 id="properties-gtkoffscreenwindow">
+    <title>gtk.OffscreenWindow Properties</title>
+
+    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
+    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>
+    <para><link linkend="properties-gtkcontainer">gtk.Container Properties</link></para>
+    <para><link linkend="properties-gtkwindow">gtk.Window Properties</link></para>
+
+  </refsect1>
+
+  <refsect1 id="style-properties-gtkoffscreenwindow">
+    <title>gtk.OffscreenWindow Style Properties</title>
+
+    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>
+
+  </refsect1>
+
+  <refsect1 id="signal-prototypes-gtkoffscreenwindow">
+    <title>gtk.OffscreenWindow Signal Prototypes</title>
+
+    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
+    <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para>
+    <para><link linkend="signal-prototypes-gtkwidget">gtk.Widget Signal Prototypes</link></para>
+    <para><link linkend="signal-prototypes-gtkcontainer">gtk.Container Signal Prototypes</link></para>
+    <para><link linkend="signal-prototypes-gtkwindow">gtk.Window Signal Prototypes</link></para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Description</title>
+
+    <note>
+      <para>This widget is available in PyGTK 2.22 and above.</para>
+    </note>
+
+    <para><link linkend="class-gtkoffscreenwindow"><classname>gtk.OffscreenWindow</classname></link> is strictly
+    intended to be used for obtaining snapshots of widgets that are not part of a normal widget hierarchy.
+    It differs from <link linkend="method-gtkwidget--get-snapshot"><methodname>gtk.Widget.get_snapshot</methodname></link>()
+    in that the widget you want to get a snapshot of need not be displayed on the user's screen as a part
+    of a widget hierarchy. However, since <link linkend="class-gtkoffscreenwindow"><classname>gtk.OffscreenWindow</classname></link>
+    is a toplevel widget you cannot obtain snapshots of a full window with it since you cannot pack a
+    toplevel widget in another toplevel.</para>
+
+    <para>The idea is to take a widget and manually set the state of it, add it to a
+    <link linkend="class-gtkoffscreenwindow"><classname>gtk.OffscreenWindow</classname></link> and then retrieve
+    the snapshot as a <link linkend="class-gdkpixmap"><classname>gtk.gdk.Pixmap</classname></link> or
+    <link linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>.</para>
+
+    <para><link linkend="class-gtkoffscreenwindow"><classname>gtk.OffscreenWindow</classname></link> derives
+    from <link linkend="class-gtkwindow"><classname>gtk.Window</classname></link> only as an implementation
+    detail. Applications should not use any API specific to <link linkend="class-gtkwindow"><classname>gtk.Window</classname></link>
+    to operate on this object. It should be treated as a <link linkend="class-gtkbin"><classname>gtk.Bin</classname></link>
+    that has no parent widget.</para>
+
+    <para>When contained offscreen widgets are redrawn,
+    <link linkend="class-gtkoffscreenwindow"><classname>gtk.OffscreenWindow</classname></link> will emit a
+    "<link linkend="signal-gtkwidget--damage-event">damage-event</link>" signal.</para>
+
+  </refsect1>
+
+  <refsect1>
     <title>Constructor</title>
 
     <programlisting>
@@ -86,16 +156,15 @@ hierarchy, <link linkend="method-gtkwidget--get-snapshot"><methodname>gtk.Widget
       <variablelist>
         <varlistentry>
           <term><emphasis>Returns</emphasis>&nbsp;:</term>
-          <listitem><simpara>A <literal>GdkPixmap</literal> pointer to the offscreen pixmap, or <literal>NULL</literal>.</simpara></listitem>
+          <listitem><simpara>A <link linkend="class-gdkpixmap"><classname>gtk.gdk.Pixmap</classname></link>, or <literal>None</literal>.</simpara></listitem>
         </varlistentry>
       </variablelist>
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
-      <para>Retrieves a snapshot of the contained widget in the form of
-a <literal>GdkPixmap</literal>.  If you need to keep this around over window
-resizes then you should add a reference to it.</para>
+      <para>Retrieves a snapshot of the contained widget in the form of a
+      <link linkend="class-gdkpixmap"><classname>gtk.gdk.Pixmap</classname></link>.</para>
     </refsect2>
 
     <refsect2 id="method-gtkoffscreenwindow--get-pixbuf">
@@ -110,17 +179,15 @@ resizes then you should add a reference to it.</para>
       <variablelist>
         <varlistentry>
           <term><emphasis>Returns</emphasis>&nbsp;:</term>
-          <listitem><simpara>A <literal>GdkPixbuf</literal> pointer, or <literal>NULL</literal>.</simpara></listitem>
+          <listitem><simpara>A <link linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>, or <literal>None</literal>.</simpara></listitem>
         </varlistentry>
       </variablelist>
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
-      <para>Retrieves a snapshot of the contained widget in the form of
-a <literal>GdkPixbuf</literal>.  This is a new pixbuf with a reference count of 1,
-and the application should unreference it once it is no longer
-needed.</para>
+      <para>Retrieves a snapshot of the contained widget in the form of a
+      <link linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>.</para>
     </refsect2>
 
   </refsect1>