[gtk+/gtk-2-22] pixmap: Deprecate create_from_data() constructors

[Benjamin Otte <otte src gnome org>]

commit 0e183fe745843daa67937a940d90e2d29e062429
Author: Benjamin Otte <otte redhat com>
Date:   Thu Aug 12 03:02:38 2010 +0200

    pixmap: Deprecate create_from_data() constructors
    
    And document that GdkPixmap will go away in GTK 3.

 docs/reference/gdk/tmpl/pixmaps.sgml |   18 ++++++++++++++++++
 gdk/gdkpixmap.c                      |   20 ++++++++++++++++++++
 gdk/gdkpixmap.h                      |    2 ++
 3 files changed, 40 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gdk/tmpl/pixmaps.sgml b/docs/reference/gdk/tmpl/pixmaps.sgml
index f7be767..d80490d 100644
--- a/docs/reference/gdk/tmpl/pixmaps.sgml
+++ b/docs/reference/gdk/tmpl/pixmaps.sgml
@@ -13,6 +13,11 @@ is the number of bits per pixels. Bitmaps are simply pixmaps
 with a depth of 1. (That is, they are monochrome bitmaps - each
 pixel can be either on or off).
 </para>
+<para>
+GTK 3 will remove #GdkPixmap and #GdkBitmap. You should use cairo
+surfaces instead. However, because a lot of functions still use these
+types, they are not deprecated.
+</para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
@@ -62,6 +67,14 @@ window is used.
 @height: the height of the new pixmap in pixels.
 @Returns: the #GdkBitmap
 
+ Deprecated: 2.22: You can create a Cairo image surface using
+cairo_image_surface_create_for_data() instead. Specify
+%CAIRO_FORMAT_A1 as the format to get a bitmap. Keep in mind that
+Cairo images must have a rowstride of 4 bytes, so you will need
+to align your data properly. If you must use a pixmap, use
+gdk_pixmap_new() with a depth of 1 to create a bitmap and then use
+gdk_cairo_create(), cairo_set_source_surface() and cairo_paint()
+to draw the image surface to the bitmap.
 
 <!-- ##### FUNCTION gdk_pixmap_create_from_data ##### -->
 <para>
@@ -78,6 +91,11 @@ for the new pixmap. Can be %NULL, if the depth is given.
 @bg: the background color.
 @Returns: the #GdkPixmap
 
+ Deprecated: 2.22: If you must replicate the functionality of this
+function, create a pixmap using gdk_pixmap_new(), cairo_paint() it
+with the background color and then create a Cairo image surface as
+pointed out in the docs to gdk_bitmap_create_from_data() and use
+this surface with cairo_mask_surface() to paint the foreground color.
 
 <!-- ##### FUNCTION gdk_pixmap_create_from_xpm ##### -->
 
diff --git a/gdk/gdkpixmap.c b/gdk/gdkpixmap.c
index 79ebd5c..3e2f2b1 100644
--- a/gdk/gdkpixmap.c
+++ b/gdk/gdkpixmap.c
@@ -689,6 +689,11 @@ gdk_pixmap_colormap_new_from_pixbuf (GdkColormap    *colormap,
  * Create a pixmap from a XPM file using a particular colormap.
  *
  * Returns: (transfer none): the #GdkPixmap.
+ *
+ * Deprecated: 2.22: Use a #GdkPixbuf instead. You can use
+ * gdk_pixbuf_new_from_file() to create it.
+ * If you must use a pixmap, use gdk_pixmap_new() to
+ * create it and Cairo to draw the pixbuf onto it.
  */
 GdkPixmap*
 gdk_pixmap_colormap_create_from_xpm (GdkDrawable    *drawable,
@@ -733,6 +738,11 @@ gdk_pixmap_colormap_create_from_xpm (GdkDrawable    *drawable,
  * Create a pixmap from a XPM file.
  *
  * Returns: (transfer none): the #GdkPixmap
+ *
+ * Deprecated: 2.22: Use a #GdkPixbuf instead. You can use
+ * gdk_pixbuf_new_from_file() to create it.
+ * If you must use a pixmap, use gdk_pixmap_new() to
+ * create it and Cairo to draw the pixbuf onto it.
  */
 GdkPixmap*
 gdk_pixmap_create_from_xpm (GdkDrawable    *drawable,
@@ -762,6 +772,11 @@ gdk_pixmap_create_from_xpm (GdkDrawable    *drawable,
  * colormap.
  *
  * Returns: (transfer none): the #GdkPixmap.
+ *
+ * Deprecated: 2.22: Use a #GdkPixbuf instead. You can use
+ * gdk_pixbuf_new_from_xpm_data() to create it.
+ * If you must use a pixmap, use gdk_pixmap_new() to
+ * create it and Cairo to draw the pixbuf onto it.
  */
 GdkPixmap*
 gdk_pixmap_colormap_create_from_xpm_d (GdkDrawable     *drawable,
@@ -806,6 +821,11 @@ gdk_pixmap_colormap_create_from_xpm_d (GdkDrawable     *drawable,
  * Create a pixmap from data in XPM format.
  *
  * Returns: (transfer none): the #GdkPixmap.
+ *
+ * Deprecated: 2.22: Use a #GdkPixbuf instead. You can use
+ * gdk_pixbuf_new_from_xpm_data() to create it.
+ * If you must use a pixmap, use gdk_pixmap_new() to
+ * create it and Cairo to draw the pixbuf onto it.
  */
 GdkPixmap*
 gdk_pixmap_create_from_xpm_d (GdkDrawable    *drawable,
diff --git a/gdk/gdkpixmap.h b/gdk/gdkpixmap.h
index 62aee11..9d138ec 100644
--- a/gdk/gdkpixmap.h
+++ b/gdk/gdkpixmap.h
@@ -70,6 +70,7 @@ GdkPixmap* gdk_pixmap_new		(GdkDrawable *drawable,
 					 gint	      width,
 					 gint	      height,
 					 gint	      depth);
+#ifndef GDK_DISABLE_DEPRECATED
 GdkBitmap* gdk_bitmap_create_from_data	(GdkDrawable *drawable,
 					 const gchar *data,
 					 gint	      width,
@@ -100,6 +101,7 @@ GdkPixmap* gdk_pixmap_colormap_create_from_xpm_d (GdkDrawable    *drawable,
 						  GdkBitmap     **mask,
 						  const GdkColor *transparent_color,
 						  gchar         **data);
+#endif
 
 /* Functions to create/lookup pixmaps from their native equivalents
  */