interface/wx/palette.h

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