interface/palette.h

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