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         @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         @see Create()
  64     */
  65     wxPalette(int n, const unsigned char* red,
  66               const unsigned char* green,
  67               const unsigned char* blue);
  68
  69     /**
  70         Destructor.
  71
  72         @see @ref overview_refcount_destruct "reference-counted object destruction"
  73     */
  74     virtual ~wxPalette();
  75
  76     /**
  77         Creates a palette from arrays of size @a n, one for each red, blue or
  78         green component.
  79
  80         @param n
  81             The number of indices in the palette.
  82         @param red
  83             An array of red values.
  84         @param green
  85             An array of green values.
  86         @param blue
  87             An array of blue values.
  88
  89         @return @true if the creation was successful, @false otherwise.
  90
  91         @see wxPalette()
  92     */
  93     bool Create(int n, const unsigned char* red,
  94                 const unsigned char* green,
  95                 const unsigned char* blue);
  96
  97     /**
  98         Returns number of entries in palette.
  99     */
 100     virtual int GetColoursCount() const;
 101
 102     /**
 103         Returns a pixel value (index into the palette) for the given RGB values.
 104
 105         @param red
 106             Red value.
 107         @param green
 108             Green value.
 109         @param blue
 110             Blue value.
 111
 112         @return The nearest palette index or @c wxNOT_FOUND for unexpected errors.
 113
 114         @see GetRGB()
 115     */
 116     int GetPixel(unsigned char red, unsigned char green,
 117                  unsigned char blue) const;
 118
 119     /**
 120         Returns RGB values for a given palette index.
 121
 122         @param pixel
 123             The palette index.
 124         @param red
 125             Receives the red value.
 126         @param green
 127             Receives the green value.
 128         @param blue
 129             Receives the blue value.
 130
 131         @return @true if the operation was successful.
 132
 133         @see GetPixel()
 134     */
 135     bool GetRGB(int pixel, const unsigned char* red,
 136                 const unsigned char* green,
 137                 const unsigned char* blue) const;
 138
 139     /**
 140         Returns @true if palette data is present.
 141     */
 142     virtual bool IsOk() const;
 143
 144     /**
 145         Assignment operator, using @ref overview_refcount.
 146     */
 147     wxPalette& operator =(const wxPalette& palette);
 148 };
 149
 150
 151 /**
 152     An empty palette.
 153 */
 154 wxPalette wxNullPalette;
 155
 156