interface/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     @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     ::wxNullPalette
  31
  32     @see wxDC::SetPalette(), wxBitmap
  33 */
  34 class wxPalette : public wxGDIObject
  35 {
  36 public:
  37
  38     /**
  39         Default constructor.
  40     */
  41     wxPalette();
  42     /**
  43         Copy constructor, uses @ref overview_refcount.
  44     */
  45     wxPalette(const wxPalette& palette);
  46     /**
  47         Creates a palette from arrays of size @e n, one for each red, blue or
  48         green component.
  49
  50         @param palette
  51             A pointer or reference to the palette to copy.
  52         @param n
  53             The number of indices in the palette.
  54         @param red
  55             An array of red values.
  56         @param green
  57             An array of green values.
  58         @param blue
  59             An array of blue values.
  60
  61         @see Create()
  62     */
  63     wxPalette(int n, const unsigned char* red,
  64               const unsigned char* green,
  65               const unsigned char* blue);
  66
  67     /**
  68         Destructor.
  69
  70         @see @ref overview_refcount_destruct "reference-counted object destruction"
  71     */
  72     ~wxPalette();
  73
  74     /**
  75         Creates a palette from arrays of size @e n, one for each red, blue or
  76         green component.
  77
  78         @param n
  79             The number of indices in the palette.
  80         @param red
  81             An array of red values.
  82         @param green
  83             An array of green values.
  84         @param blue
  85             An array of blue values.
  86
  87         @returns @true if the creation was successful, @false otherwise.
  88
  89         @see wxPalette()
  90     */
  91     bool Create(int n, const unsigned char* red,
  92                 const unsigned char* green,
  93                 const unsigned char* blue);
  94
  95     /**
  96         Returns number of entries in palette.
  97     */
  98     int GetColoursCount() const;
  99
 100     /**
 101         Returns a pixel value (index into the palette) for the given RGB values.
 102
 103         @param red
 104             Red value.
 105         @param green
 106             Green value.
 107         @param blue
 108             Blue value.
 109
 110         @returns The nearest palette index or @c wxNOT_FOUND for unexpected errors.
 111
 112         @see GetRGB()
 113     */
 114     int GetPixel(unsigned char red, unsigned char green,
 115                  unsigned char blue) const;
 116
 117     /**
 118         Returns RGB values for a given palette index.
 119
 120         @param pixel
 121             The palette index.
 122         @param red
 123             Receives the red value.
 124         @param green
 125             Receives the green value.
 126         @param blue
 127             Receives the blue value.
 128
 129         @returns @true if the operation was successful.
 130
 131         @see GetPixel()
 132     */
 133     bool GetRGB(int pixel, const unsigned char* red,
 134                 const unsigned char* green,
 135                 const unsigned char* blue) const;
 136
 137     /**
 138         Returns @true if palette data is present.
 139     */
 140     bool IsOk() const;
 141
 142     /**
 143         Assignment operator, using @ref overview_refcount.
 144     */
 145     wxPalette& operator =(const wxPalette& palette);
 146 };
 147
 148
 149 /**
 150     FIXME
 151 */
 152 wxPalette wxNullPalette;
 153
 154