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     /**
  44         Copy constructor, uses @ref overview_refcount.
  45     */
  46     wxPalette(const wxPalette& palette);
  47
  48     /**
  49         Creates a palette from arrays of size @a n, one for each red, blue or
  50         green component.
  51
  52         @param palette
  53             A pointer or reference to the palette to copy.
  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     ~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     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     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