Add gtk-doc section for GtkOffscreenWindow

diff --git a/docs/reference/gtk/tmpl/gtkoffscreenwindow.sgml b/docs/reference/gtk/tmpl/gtkoffscreenwindow.sgml
deleted file mode 100644 (file)
index b52f7b7..0000000
--- a/docs/reference/gtk/tmpl/gtkoffscreenwindow.sgml
+++ /dev/null
@@ -1,49 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkOffscreenWindow
-
-<!-- ##### SECTION Short_Description ##### -->
-A toplevel container widget for doing offscreen rendering of children
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-The #GtkOffscreenWindow container is a top-level container that is used
-to manage offscreen rendering and snapshot retrieval of the widget that
-is contained inside it.
-
-</para>
-<para>
-GtkOffscreenWindow was introduced in GTK+ 2.20.
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GtkOffscreenWindow ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### FUNCTION gtk_offscreen_window_get_pixmap ##### -->
-<para>
-
-</para>
-
-@offscreen:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_offscreen_window_get_pixbuf ##### -->
-<para>
-
-</para>
-
-@offscreen:
-@Returns:
-
-

diff --git a/gtk/gtkoffscreenwindow.c b/gtk/gtkoffscreenwindow.c
index 953a2012fe24972d9ad537afd0b0b4b39b407e21..dd14159d7622224f9a9d18854f2343560681d8a4 100644 (file)
--- a/gtk/gtkoffscreenwindow.c
+++ b/gtk/gtkoffscreenwindow.c
@@ -21,6 +21,30 @@
 #include "gtkoffscreenwindow.h"
 #include "gtkalias.h"
 
+/**
+ * SECTION:offscreen_windows
+ * @short description: A toplevel container widget used to manage offscreen
+ *    rendering of child widgets.
+ * @title: Offscreen windows
+ *
+ * #GtkOffscreenWindow is strictly intended to be used for obtaining
+ * snapshots of widgets that are not part of a normal widget hierarchy.
+ * It differs from gtk_widget_get_snapshot() 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 #GtkOffscreenWindow
+ * is a toplevel widget you cannot obtain snapshots of a full window
+ * with it since you cannot pack a toplevel widget in another toplevel.
+ *
+ * The idea is to take a widget and manually set the size and state of
+ * it, add it to a #GtkOffscreenWindow and then retrieve the snapshot
+ * as a #GdkPixmap or #GdkPixbuf.
+ *
+ * #GtkOffscreenWindow derives from #GtkWindow only as an implementation
+ * detail.  Applications should not use any API specific to #GtkWindow
+ * to operate on this object.  It should be treated as a #GtkBin that
+ * has no parent widget.
+ */
+
 G_DEFINE_TYPE (GtkOffscreenWindow, gtk_offscreen_window, GTK_TYPE_WINDOW);
 
 static void
@@ -210,6 +234,7 @@ gtk_offscreen_window_init (GtkOffscreenWindow *window)
 {
 }
 
+/* --- functions --- */
 /**
  * gtk_offscreen_window_new:
  *