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     @ingroup group_class_gdi
  12     @wxheader{palette.h}
  13
  14     A palette is a table that maps pixel values to RGB colours. It allows the
  15     colours of a low-depth bitmap, for example, to be mapped to the available
  16     colours in a display. The notion of palettes is becoming more and more
  17     obsolete nowadays and only the MSW port is still using a native palette.
  18     All other ports use generic code which is basically just an array of
  19     colours.
  20
  21     It is likely that in the future the only use for palettes within wxWidgets
  22     will be for representing colour indeces from images (such as GIF or PNG).
  23     The image handlers for these formats have been modified to create a palette
  24     if there is such information in the original image file (usually 256 or less
  25     colour images). See wxImage for more information.
  26
  27     @library{wxcore}
  28     @category{gdi}
  29
  30     @stdobjects
  31     ::Objects:, ::wxNullPalette,
  32
  33     @see wxDC::SetPalette, wxBitmap
  34 */
  35 class wxPalette : public wxGDIObject
  36 {
  37 public:
  38     //@{
  39     /**
  40         Creates a palette from arrays of size @e n, one for each
  41         red, blue or green component.
  42
  43         @param palette
  44             A pointer or reference to the palette to copy.
  45         @param n
  46             The number of indices in the palette.
  47         @param red
  48             An array of red values.
  49         @param green
  50             An array of green values.
  51         @param blue
  52             An array of blue values.
  53
  54         @see Create()
  55     */
  56     wxPalette();
  57     wxPalette(const wxPalette& palette);
  58     wxPalette(int n, const unsigned char* red,
  59               const unsigned char* green,
  60               const unsigned char* blue);
  61     //@}
  62
  63     /**
  64         Destructor.
  65         See @ref overview_refcountdestruct "reference-counted object destruction" for
  66         more info.
  67     */
  68     ~wxPalette();
  69
  70     /**
  71         Creates a palette from arrays of size @e n, one for each
  72         red, blue or green component.
  73
  74         @param n
  75             The number of indices in the palette.
  76         @param red
  77             An array of red values.
  78         @param green
  79             An array of green values.
  80         @param blue
  81             An array of blue values.
  82
  83         @returns @true if the creation was successful, @false otherwise.
  84
  85         @see wxPalette()
  86     */
  87     bool Create(int n, const unsigned char* red,
  88                 const unsigned char* green,
  89                 const unsigned char* blue);
  90
  91     /**
  92         Returns number of entries in palette.
  93     */
  94     int GetColoursCount() const;
  95
  96     /**
  97         Returns a pixel value (index into the palette) for the given RGB values.
  98
  99         @param red
 100             Red value.
 101         @param green
 102             Green value.
 103         @param blue
 104             Blue value.
 105
 106         @returns The nearest palette index or wxNOT_FOUND for unexpected errors.
 107
 108         @see GetRGB()
 109     */
 110     int GetPixel(unsigned char red, unsigned char green,
 111                  unsigned char blue) const;
 112
 113     /**
 114         Returns RGB values for a given palette index.
 115
 116         @param pixel
 117             The palette index.
 118         @param red
 119             Receives the red value.
 120         @param green
 121             Receives the green value.
 122         @param blue
 123             Receives the blue value.
 124
 125         @returns @true if the operation was successful.
 126
 127         @see GetPixel()
 128     */
 129     bool GetRGB(int pixel, const unsigned char* red,
 130                 const unsigned char* green,
 131                 const unsigned char* blue) const;
 132
 133     /**
 134         Returns @true if palette data is present.
 135     */
 136     bool IsOk() const;
 137
 138     /**
 139         Assignment operator, using @ref overview_trefcount "reference counting".
 140     */
 141     wxPalette operator =(const wxPalette& palette);
 142 };
 143
 144
 145 /**
 146     FIXME
 147 */
 148 wxPalette Objects:
 149 ;
 150
 151 /**
 152     FIXME
 153 */
 154 wxPalette wxNullPalette;
 155
 156