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