docs/latex/wx/palette.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        palette.tex
   3 %% Purpose:     wxPalette docs
   4 %% Author:
   5 %% Modified by:
   6 %% Created:
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) wxWidgets
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxPalette}}\label{wxpalette}
  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 \helpref{wxImage}{wximage} for more information.
  26
  27 %TODO: topic overview for wxPalette.
  28 \wxheading{Derived from}
  29
  30 \helpref{wxGDIObject}{wxgdiobject}\\
  31 \helpref{wxObject}{wxobject}
  32
  33 \wxheading{Include files}
  34
  35 <wx/palette.h>
  36
  37 \wxheading{Predefined objects}
  38
  39 Objects:
  40
  41 {\bf wxNullPalette}
  42
  43 \wxheading{See also}
  44
  45 \helpref{wxDC::SetPalette}{wxdcsetpalette}, \helpref{wxBitmap}{wxbitmap}
  46
  47 \latexignore{\rtfignore{\wxheading{Members}}}
  48
  49 \membersection{wxPalette::wxPalette}\label{wxpalettector}
  50
  51 \func{}{wxPalette}{\void}
  52
  53 Default constructor.
  54
  55 \func{}{wxPalette}{\param{const wxPalette\&}{ palette}}
  56
  57 Copy constructor, uses \helpref{reference counting}{trefcount}.
  58
  59 \func{}{wxPalette}{\param{int}{ n}, \param{const unsigned char* }{red},\\
  60  \param{const unsigned char* }{green}, \param{const unsigned char* }{blue}}
  61
  62 Creates a palette from arrays of size {\it n}, one for each
  63 red, blue or green component.
  64
  65 \wxheading{Parameters}
  66
  67 \docparam{palette}{A pointer or reference to the palette to copy.}
  68
  69 \docparam{n}{The number of indices in the palette.}
  70
  71 \docparam{red}{An array of red values.}
  72
  73 \docparam{green}{An array of green values.}
  74
  75 \docparam{blue}{An array of blue values.}
  76
  77 \wxheading{See also}
  78
  79 \helpref{wxPalette::Create}{wxpalettecreate}
  80
  81 \perlnote{In wxPerl the third constructor form takes as parameters
  82   3 array references ( they must be of the same length ).}
  83
  84 \membersection{wxPalette::\destruct{wxPalette}}\label{wxpalettedtor}
  85
  86 \func{}{\destruct{wxPalette}}{\void}
  87
  88 Destructor.
  89 See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
  90
  91 \membersection{wxPalette::Create}\label{wxpalettecreate}
  92
  93 \func{bool}{Create}{\param{int}{ n}, \param{const unsigned char* }{red},\rtfsp
  94  \param{const unsigned char* }{green}, \param{const unsigned char* }{blue}}
  95
  96 Creates a palette from arrays of size {\it n}, one for each
  97 red, blue or green component.
  98
  99 \wxheading{Parameters}
 100
 101 \docparam{n}{The number of indices in the palette.}
 102
 103 \docparam{red}{An array of red values.}
 104
 105 \docparam{green}{An array of green values.}
 106
 107 \docparam{blue}{An array of blue values.}
 108
 109 \wxheading{Return value}
 110
 111 true if the creation was successful, false otherwise.
 112
 113 \wxheading{See also}
 114
 115 \helpref{wxPalette::wxPalette}{wxpalettector}
 116
 117 \membersection{wxPalette::GetColoursCount}\label{wxpalettegetcolourscount}
 118
 119 \constfunc{int}{GetColoursCount}{\void}
 120
 121 Returns number of entries in palette.
 122
 123 \membersection{wxPalette::GetPixel}\label{wxpalettegetpixel}
 124
 125 \constfunc{int}{GetPixel}{\param{unsigned char }{red}, \param{unsigned char }{green},\rtfsp
 126  \param{unsigned char }{blue}}
 127
 128 Returns a pixel value (index into the palette) for the given RGB values.
 129
 130 \wxheading{Parameters}
 131
 132 \docparam{red}{Red value.}
 133
 134 \docparam{green}{Green value.}
 135
 136 \docparam{blue}{Blue value.}
 137
 138 \wxheading{Return value}
 139
 140 The nearest palette index or {\tt wxNOT\_FOUND} for unexpected errors.
 141
 142 \wxheading{See also}
 143
 144 \helpref{wxPalette::GetRGB}{wxpalettegetrgb}
 145
 146 \membersection{wxPalette::GetRGB}\label{wxpalettegetrgb}
 147
 148 \constfunc{bool}{GetRGB}{\param{int}{ pixel}, \param{const unsigned char* }{red}, \param{const unsigned char* }{green},\rtfsp
 149  \param{const unsigned char* }{blue}}
 150
 151 Returns RGB values for a given palette index.
 152
 153 \wxheading{Parameters}
 154
 155 \docparam{pixel}{The palette index.}
 156
 157 \docparam{red}{Receives the red value.}
 158
 159 \docparam{green}{Receives the green value.}
 160
 161 \docparam{blue}{Receives the blue value.}
 162
 163 \wxheading{Return value}
 164
 165 true if the operation was successful.
 166
 167 \wxheading{See also}
 168
 169 \helpref{wxPalette::GetPixel}{wxpalettegetpixel}
 170
 171 \perlnote{In wxPerl this method takes only the {\tt pixel} parameter and
 172   returns a 3-element list ( or the empty list upon failure ).}
 173
 174 \membersection{wxPalette::IsOk}\label{wxpaletteisok}
 175
 176 \constfunc{bool}{IsOk}{\void}
 177
 178 Returns true if palette data is present.
 179
 180 \membersection{wxPalette::operator $=$}\label{wxpaletteassignment}
 181
 182 \func{wxPalette\&}{operator $=$}{\param{const wxPalette\& }{palette}}
 183
 184 Assignment operator, using \helpref{reference counting}{trefcount}.
 185