[gtk+] Add gtk_offscreen_window_get_pixmap() and gtk_offscreen_window_get_pixbuf(), some API docs.

[Cody Russell <bratsche src gnome org>]

commit 1c92a54983e590fc4ae17e26e7b51e7a191c4da1
Author: Cody Russell <crussell canonical com>
Date:   Fri Dec 18 20:08:45 2009 +0100

    Add gtk_offscreen_window_get_pixmap() and gtk_offscreen_window_get_pixbuf(), some API docs.

 gtk/gtkoffscreenwindow.c    |   60 +++++++++++++++++++++++++++++++++++++++++++
 gtk/gtkoffscreenwindow.h    |    2 +
 tests/testoffscreenwindow.c |    2 +-
 3 files changed, 63 insertions(+), 1 deletions(-)
---
diff --git a/gtk/gtkoffscreenwindow.c b/gtk/gtkoffscreenwindow.c
index 22f32b2..953a201 100644
--- a/gtk/gtkoffscreenwindow.c
+++ b/gtk/gtkoffscreenwindow.c
@@ -210,12 +210,72 @@ gtk_offscreen_window_init (GtkOffscreenWindow *window)
 {
 }
 
+/**
+ * gtk_offscreen_window_new:
+ *
+ * Creates a toplevel container widget that is used to retrieve
+ * snapshots of widgets without showing them on the screen.  For
+ * widgets that are on the screen and part of a normal widget
+ * hierarchy, gtk_widget_get_snapshot() can be used instead.
+ *
+ * Return value: A pointer to a #GtkWidget
+ **/
 GtkWidget *
 gtk_offscreen_window_new (void)
 {
   return g_object_new (gtk_offscreen_window_get_type (), NULL);
 }
 
+/**
+ * gtk_offscreen_window_get_pixmap:
+ *
+ * Retrieves a snapshot of the contained widget in the form of
+ * a #GdkPixmap.  If you need to keep this around over window
+ * resizes then you should add a reference to it.
+ *
+ * Returns: A #GdkPixmap pointer to the offscreen pixmap, or %NULL.
+ **/
+GdkPixmap *
+gtk_offscreen_window_get_pixmap (GtkOffscreenWindow *offscreen)
+{
+  g_return_val_if_fail (GTK_IS_OFFSCREEN_WINDOW (offscreen), NULL);
+
+  return gdk_offscreen_window_get_pixmap (GTK_WIDGET (offscreen)->window);
+}
+
+/**
+ * gtk_offscreen_window_get_pixbuf:
+ *
+ * Retrieves a snapshot of the contained widget in the form of
+ * a #GdkPixbuf.  This is a new pixbuf with a reference count of 1,
+ * and the application should unreference it once it is no longer
+ * needed.
+ *
+ * Returns: A #GdkPixbuf pointer, or %NULL.
+ **/
+GdkPixbuf *
+gtk_offscreen_window_get_pixbuf (GtkOffscreenWindow *offscreen)
+{
+  GdkPixmap *pixmap = NULL;
+  GdkPixbuf *pixbuf = NULL;
+
+  g_return_val_if_fail (GTK_IS_OFFSCREEN_WINDOW (offscreen), NULL);
+
+  pixmap = gdk_offscreen_window_get_pixmap (GTK_WIDGET (offscreen)->window);
+
+  if (pixmap != NULL)
+    {
+      gint width, height;
+
+      gdk_drawable_get_size (pixmap, &width, &height);
+
+      pixbuf = gdk_pixbuf_get_from_drawable (NULL, pixmap, NULL,
+                                             0, 0, 0, 0,
+                                             width, height);
+    }
+
+  return pixbuf;
+}
 
 #define __GTK_OFFSCREEN_WINDOW_C__
 #include "gtkaliasdef.c"
diff --git a/gtk/gtkoffscreenwindow.h b/gtk/gtkoffscreenwindow.h
index 75486f6..518b8df 100644
--- a/gtk/gtkoffscreenwindow.h
+++ b/gtk/gtkoffscreenwindow.h
@@ -52,6 +52,8 @@ struct _GtkOffscreenWindowClass
 GType      gtk_offscreen_window_get_type () G_GNUC_CONST;
 
 GtkWidget *gtk_offscreen_window_new ();
+GdkPixmap *gtk_offscreen_window_get_pixmap (GtkOffscreenWindow *offscreen);
+GdkPixbuf *gtk_offscreen_window_get_pixbuf (GtkOffscreenWindow *offscreen);
 
 G_END_DECLS
 
diff --git a/tests/testoffscreenwindow.c b/tests/testoffscreenwindow.c
index 161c9c5..7358188 100644
--- a/tests/testoffscreenwindow.c
+++ b/tests/testoffscreenwindow.c
@@ -11,7 +11,7 @@ da_expose (GtkWidget *widget,
 
   if (GTK_WIDGET_DRAWABLE (widget))
     {
-      pixmap = gdk_offscreen_window_get_pixmap (GTK_WIDGET (offscreen)->window);
+      pixmap = gtk_offscreen_window_get_pixmap (offscreen);
 
       cr = gdk_cairo_create (widget->window);
       gdk_cairo_set_source_pixmap (cr, pixmap, 50, 50);