interface/wx/palette.h

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