From: Cody Russell <crussell@canonical.com>
Date: Sat, 19 Dec 2009 12:08:20 +0000 (+0100)
Subject: Add gtk-doc section for GtkOffscreenWindow
X-Git-Url: http://pileus.org/git/?a=commitdiff_plain;h=4c14a043ebc151c132092f0fc569ecdd251dadce;p=~andy%2Fgtk

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
index b52f7b708..000000000
--- 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 953a2012f..dd14159d7 100644
--- 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:
  *