[wxWidgets.git] / interface / palette.h

/////////////////////////////////////////////////////////////////////////////
// Name:        palette.h
// Purpose:     documentation for wxPalette class
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxPalette
    @wxheader{palette.h}
    
    A palette is a table that maps pixel values to RGB colours. It allows the
    colours of a low-depth bitmap, for example, to be mapped to the available
    colours in a display. The notion of palettes is becoming more and more
    obsolete nowadays and only the MSW port is still using a native palette.
    All other ports use generic code which is basically just an array of
    colours. 
    
    It is likely that in the future the only use for palettes within wxWidgets
    will be for representing colour indeces from images (such as GIF or PNG).
    The image handlers for these formats have been modified to create a palette
    if there is such information in the original image file (usually 256 or less
    colour images). See wxImage for more information.
    
    @library{wxcore}
    @category{gdi}
    
    @stdobjects
    Objects:
    wxNullPalette
    
    @seealso
    wxDC::SetPalette, wxBitmap
*/
class wxPalette : public wxGDIObject
{
public:
    //@{
    /**
        Creates a palette from arrays of size @e n, one for each
        red, blue or green component.
        
        @param palette 
        A pointer or reference to the palette to copy.
        
        @param n 
        The number of indices in the palette.
        
        @param red 
        An array of red values.
        
        @param green 
        An array of green values.
        
        @param blue 
        An array of blue values.
        
        @sa Create()
    */
    wxPalette();
        wxPalette(const wxPalette& palette);
        wxPalette(int n, const unsigned char* red,
                  const unsigned char* green,
                  const unsigned char* blue);
    //@}

    /**
        Destructor.
        See @ref overview_refcountdestruct "reference-counted object destruction" for
        more info.
    */
    ~wxPalette();

    /**
        Creates a palette from arrays of size @e n, one for each
        red, blue or green component.
        
        @param n 
        The number of indices in the palette.
        
        @param red 
        An array of red values.
        
        @param green 
        An array of green values.
        
        @param blue 
        An array of blue values.
        
        @returns @true if the creation was successful, @false otherwise.
        
        @sa wxPalette()
    */
    bool Create(int n, const unsigned char* red,
                const unsigned char* green,
                const unsigned char* blue);

    /**
        Returns number of entries in palette.
    */
    int GetColoursCount();

    /**
        Returns a pixel value (index into the palette) for the given RGB values.
        
        @param red 
        Red value.
        
        @param green 
        Green value.
        
        @param blue 
        Blue value.
        
        @returns The nearest palette index or wxNOT_FOUND for unexpected errors.
        
        @sa GetRGB()
    */
    int GetPixel(unsigned char red, unsigned char green,
                 unsigned char blue);

    /**
        Returns RGB values for a given palette index.
        
        @param pixel 
        The palette index.
        
        @param red 
        Receives the red value.
        
        @param green 
        Receives the green value.
        
        @param blue 
        Receives the blue value.
        
        @returns @true if the operation was successful.
        
        @sa GetPixel()
    */
#define bool GetRGB(int pixel, const unsigned char* red,
                const unsigned char* green,
                const unsigned char* blue)     /* implementation is private */

    /**
        Returns @true if palette data is present.
    */
#define bool IsOk()     /* implementation is private */

    /**
        Assignment operator, using @ref overview_trefcount "reference counting".
    */
    wxPalette operator =(const wxPalette& palette);
};
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: palette.h
	3	// Purpose: documentation for wxPalette class
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	@class wxPalette
	11	@wxheader{palette.h}
	12
	13	A palette is a table that maps pixel values to RGB colours. It allows the
	14	colours of a low-depth bitmap, for example, to be mapped to the available
	15	colours in a display. The notion of palettes is becoming more and more
	16	obsolete nowadays and only the MSW port is still using a native palette.
	17	All other ports use generic code which is basically just an array of
	18	colours.
	19
	20	It is likely that in the future the only use for palettes within wxWidgets
	21	will be for representing colour indeces from images (such as GIF or PNG).
	22	The image handlers for these formats have been modified to create a palette
	23	if there is such information in the original image file (usually 256 or less
	24	colour images). See wxImage for more information.
	25
	26	@library{wxcore}
	27	@category{gdi}
	28
	29	@stdobjects
	30	Objects:
	31	wxNullPalette
	32
	33	@seealso
	34	wxDC::SetPalette, wxBitmap
	35	*/
	36	class wxPalette : public wxGDIObject
	37	{
	38	public:
	39	//@{
	40	/**
	41	Creates a palette from arrays of size @e n, one for each
	42	red, blue or green component.
	43
	44	@param palette
	45	A pointer or reference to the palette to copy.
	46
	47	@param n
	48	The number of indices in the palette.
	49
	50	@param red
	51	An array of red values.
	52
	53	@param green
	54	An array of green values.
	55
	56	@param blue
	57	An array of blue values.
	58
	59	@sa Create()
	60	*/
	61	wxPalette();
	62	wxPalette(const wxPalette& palette);
	63	wxPalette(int n, const unsigned char* red,
	64	const unsigned char* green,
65	const unsigned char* blue);
66	//@}
67
68	/**
69	Destructor.
70	See @ref overview_refcountdestruct "reference-counted object destruction" for
71	more info.
72	*/
73	~wxPalette();
74
75	/**
76	Creates a palette from arrays of size @e n, one for each
77	red, blue or green component.
78
79	@param n
80	The number of indices in the palette.
81
82	@param red
83	An array of red values.
84
85	@param green
86	An array of green values.
87
88	@param blue
89	An array of blue values.
90
91	@returns @true if the creation was successful, @false otherwise.
92
93	@sa wxPalette()
94	*/
95	bool Create(int n, const unsigned char* red,
96	const unsigned char* green,
97	const unsigned char* blue);
98
99	/**
100	Returns number of entries in palette.
101	*/
102	int GetColoursCount();
103
104	/**
105	Returns a pixel value (index into the palette) for the given RGB values.
106
107	@param red
108	Red value.
109
110	@param green
111	Green value.
112
113	@param blue
114	Blue value.
115
116	@returns The nearest palette index or wxNOT_FOUND for unexpected errors.
117
118	@sa GetRGB()
119	*/
120	int GetPixel(unsigned char red, unsigned char green,
121	unsigned char blue);
122
123	/**
124	Returns RGB values for a given palette index.
125
126	@param pixel
127	The palette index.
128
129	@param red
130	Receives the red value.
131
132	@param green
133	Receives the green value.
134
135	@param blue
136	Receives the blue value.
137
138	@returns @true if the operation was successful.
139
140	@sa GetPixel()
141	*/
142	#define bool GetRGB(int pixel, const unsigned char* red,
143	const unsigned char* green,
144	const unsigned char* blue) /* implementation is private */
145
146	/**
147	Returns @true if palette data is present.
148	*/
149	#define bool IsOk() /* implementation is private */
150
151	/**
152	Assignment operator, using @ref overview_trefcount "reference counting".
153	*/
154	wxPalette operator =(const wxPalette& palette);
155	};