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