/*  Inti: Integrated Foundation Classes
 *  Copyright (C) 2002 The Inti Development Team.
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Library General Public License for more details.
 *
 *  You should have received a copy of the GNU Library General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */
 
//! @file inti/gdk/pixmap.h
//! @brief A GdkPixmap C++ wrapper interface.
//!
//! Provides Pixmap, an object that represents an offscreen drawable.

#ifndef INTI_GDK_PIXMAP_H
#define INTI_GDK_PIXMAP_H

#ifndef INTI_GDK_DRAWABLE_H
#include <inti/gdk/drawable.h>
#endif

namespace Inti {

namespace Gdk {
	
class PixmapClass;
class Window;

//! @class Pixmap pixmap.h inti/gdk/pixmap.h
//! @brief A GdkPixmap C++ wrapper class.
//!
//! Pixmaps are offscreen drawables. They can be drawn upon with the standard
//! drawing primitives, then copied to another drawable (such as a Gdk::Window)
//! with draw(). The depth of a pixmap 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).

class Pixmap : public Drawable
{
	friend class G::Object;
	friend class PixmapClass;

	Pixmap(const Pixmap&);
	Pixmap& operator=(const Pixmap&);

protected:
//! @name Constructors
//! @{

	explicit Pixmap(GdkPixmap *pixmap, bool reference = true);
	//!< Construct a new Pixmap from an existing GdkPixmap.
	//!< @param pixmap A pointer to a GdkPixmap.
	//!< @param reference Set false if the initial reference count is floating, set true if it's not.
	//!<
	//!< <BR>The <EM>pixmap</EM> can be a newly created GdkPixmap or an existing
	//!< GdkPixmap. (see G::Object::Object).

//! @}

public:
//! @name Constructors
//! @{

	Pixmap(const Drawable& drawable, int width, int height);
	//!< Construct a new pixmap with the given size, using <EM>window</EM>
	//!< to determine the default values.
	//!< @param drawable The Drawable to use to get the depth.
	//!< @param width The width of the new pixmap in pixels.
	//!< @param height The height of the new pixmap in pixels.
	//!<
	//!< <BR>The depth of the new pixmap will be equal to that of the window.

	Pixmap(int width, int height, int depth);
	//!< Create a new pixmap with the given size and depth.
	//!< @param width The width of the new pixmap in pixels.
	//!< @param height The height of the new pixmap in pixels.
	//!< @param depth The depth (number of bits per pixel) of the new pixmap.

	Pixmap(const Drawable& drawable, const char* data, int width, int height, const Color& fg, const Color& bg);
	//!< Create a two colored pixmap from data in XBM format.
	//!< @param drawable The Drawable to use to get the depth.
	//!< @param data A pointer to the data.
	//!< @param width The width of the new pixmap in pixels.
	//!< @param height The height of the new pixmap in pixels.
	//!< @param fg The foreground color.
	//!< @param bg The background color.

	Pixmap(const char* data, int width, int height, int depth, const Color& fg, const Color& bg);
	//!< Create a two colored pixmap from data in XBM format using the root window
	//!< to determine the default values.
	//! @param data A pointer to the data.
	//! @param width The width of the new pixmap in pixels.
	//! @param height The height of the new pixmap in pixels.
	//! @param depth The depth (number of bits per pixel) of the new pixmap.
	//! @param fg The foreground color.
	//! @param bg The background color.

	Pixmap(const Drawable& drawable, const String& filename, Pointer<Bitmap> *mask = 0, const Color *transparent_color = 0);
	//!< Create a pixmap from a XPM file.
	//!< @param drawable The Drawable whose colormap the pixmap will use.
	//!< @param filename The filename of a file containing XPM data.
	//!< @param mask A smart pointer to a place to store a bitmap representing the transparency mask
	//!<             of the XPM file. Can be null, in which case transparency will be ignored.
	//!< @param transparent_color The color to be used for the pixels that are transparent in the input
	//!<                          file. Can be null, in which case a default color will be used.

	Pixmap(Colormap *colormap, const String& filename, Pointer<Bitmap> *mask = 0, const Color *transparent_color = 0);
	//!< Create a pixmap from a XPM file using a particular colormap.
	//!< @param colormap The Colormap that the new pixmap will be use.
	//!< @param filename The filename of a file containing XPM data.
	//!< @param mask A smart pointer to a place to store a bitmap representing the transparency mask
	//!<             of the XPM file. Can be null, in which case transparency will be ignored.
	//!< @param transparent_color The color to be used for the pixels that are transparent in the input
	//!<                          file. Can be null, in which case a default color will be used.

	Pixmap(const Drawable& drawable, const char * const *data, Pointer<Bitmap> *mask = 0, const Color *transparent_color = 0);
	//!< Create a pixmap from data in XPM format.
	//!< @param drawable The Drawable whose colormap the pixmap will use.
	//!< @param data A pointer to a string containing the XPM data.
	//!< @param mask A smart pointer to a place to store a bitmap representing the transparency mask
	//!<             of the XPM file. Can be null, in which case transparency will be ignored.
	//!< @param transparent_color The color to be used for the pixels that are transparent in the input
	//!<                          file. Can be null, in which case a default color will be used.

	Pixmap(Colormap *colormap, const char * const *data, Pointer<Bitmap> *mask = 0, const Color *transparent_color = 0);
	//!< Create a pixmap from data in XPM format using a particular colormap..
	//!< @param colormap The Colormap that the new pixmap will be use.
	//!< @param data A pointer to a string containing the XPM data.
	//!< @param mask A smart pointer to a place to store a bitmap representing the transparency mask
	//!<             of the XPM file. Can be null, in which case transparency will be ignored.
	//!< @param transparent_color The color to be used for the pixels that are transparent in the input
	//!<                          file. Can be null, in which case a default color will be used.

	virtual ~Pixmap();
	//!< Destructor.
	
//! @}

	static Pointer<Pixmap> create(GdkNativeWindow anid, const Display *display = 0);
	//!< Wraps a native pixmap in a Gdk::Pixmap.
	//!< @param anid A native pixmap handle.
	//!< @param display The Display where <EM>anid</EM> is located, or null for the default display.
	//!< @return A smart pointer to the newly-created Gdk::Pixmap wrapper for the native pixmap,
	//!< or null if the pixmap has been destroyed.
	//!<
	//!< <BR>In the X backend, a native pixmap handle is an Xlib XID. This method
	//!< fail if the pixmap has been destroyed.

	static Pointer<Pixmap> lookup(GdkNativeWindow anid, const Display *display = 0);
	//!< Looks up the Gdk::Pixmap that wraps the given native pixmap handle.
	//!< @param anid A native pixmap handle.
	//!< @param display The Display associated with anid, or null for the default display.
	//!< @return The Gdk::Pixmap wrapper for the native pixmap, or null if there is none.
	//!<
	//!< <BR>In the X backend, a native pixmap handle is an Xlib XID.

//! @name Accessors
//! @{

	GdkPixmap* gdk_pixmap() const { return (GdkPixmap*)instance; }
	//!< Get a pointer to the GdkPixmap structure.

	GdkPixmapObject* gdk_pixmap_object() const;
	//!< Get a pointer to the GdkPixmapObject structure.

	GdkPixmapObjectClass* gdk_pixmap_object_class() const;
	//!< Get a pointer to the GdkPixmapObjectClass structure.

//! @}
//! @name Methods
//! @{

	void clear(GC& gc, const Color& color);
	//!< Clears a pixmap with the color specified.
	//!< @param gc A graphics context.
	//!< @param color The color to clear the pixmap with. 
	
//! @}
};

} // namespace Gdk

} // namespace Inti

#endif // INTI_GDK_PIXMAP_H

