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 licence
   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         @param palette
  46             A reference to the palette to copy.
  47     */
  48     wxPalette(const wxPalette& palette);
  49
  50     /**
  51         Creates a palette from arrays of size @a n, one for each red, blue or
  52         green component.
  53
  54         @param n
  55             The number of indices in the palette.
  56         @param red
  57             An array of red values.
  58         @param green
  59             An array of green values.
  60         @param blue
  61             An array of blue values.
  62
  63         @beginWxPerlOnly
  64         In wxPerl this method takes as parameters
  65         3 array references (they must be of the same length).
  66         @endWxPerlOnly
  67
  68         @see Create()
  69     */
  70     wxPalette(int n, const unsigned char* red,
  71               const unsigned char* green,
  72               const unsigned char* blue);
  73
  74     /**
  75         Destructor.
  76
  77         @see @ref overview_refcount_destruct "reference-counted object destruction"
  78     */
  79     virtual ~wxPalette();
  80
  81     /**
  82         Creates a palette from arrays of size @a n, one for each red, blue or
  83         green component.
  84
  85         @param n
  86             The number of indices in the palette.
  87         @param red
  88             An array of red values.
  89         @param green
  90             An array of green values.
  91         @param blue
  92             An array of blue values.
  93
  94         @return @true if the creation was successful, @false otherwise.
  95
  96         @see wxPalette()
  97     */
  98     bool Create(int n, const unsigned char* red,
  99                 const unsigned char* green,
 100                 const unsigned char* blue);
 101
 102     /**
 103         Returns number of entries in palette.
 104     */
 105     virtual int GetColoursCount() const;
 106
 107     /**
 108         Returns a pixel value (index into the palette) for the given RGB values.
 109
 110         @param red
 111             Red value.
 112         @param green
 113             Green value.
 114         @param blue
 115             Blue value.
 116
 117         @return The nearest palette index or @c wxNOT_FOUND for unexpected errors.
 118
 119         @see GetRGB()
 120     */
 121     int GetPixel(unsigned char red, unsigned char green,
 122                  unsigned char blue) const;
 123
 124     /**
 125         Returns RGB values for a given palette index.
 126
 127         @param pixel
 128             The palette index.
 129         @param red
 130             Receives the red value.
 131         @param green
 132             Receives the green value.
 133         @param blue
 134             Receives the blue value.
 135
 136         @return @true if the operation was successful.
 137
 138         @beginWxPerlOnly
 139         In wxPerl this method takes only the @a pixel parameter and
 140         returns a 3-element list (or the empty list upon failure).
 141         @endWxPerlOnly
 142
 143         @see GetPixel()
 144     */
 145     bool GetRGB(int pixel, unsigned char* red, unsigned char* green,
 146                 unsigned char* blue) const;
 147
 148     /**
 149         Returns @true if palette data is present.
 150     */
 151     virtual bool IsOk() const;
 152
 153     /**
 154         Assignment operator, using @ref overview_refcount.
 155     */
 156     wxPalette& operator =(const wxPalette& palette);
 157 };
 158
 159
 160 /**
 161     An empty palette.
 162 */
 163 wxPalette wxNullPalette;
 164
 165