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. This uses reference counting so is a cheap operation.
  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
  90 \membersection{wxPalette::Create}\label{wxpalettecreate}
  91
  92 \func{bool}{Create}{\param{int}{ n}, \param{const unsigned char* }{red},\rtfsp
  93  \param{const unsigned char* }{green}, \param{const unsigned char* }{blue}}
  94
  95 Creates a palette from arrays of size {\it n}, one for each
  96 red, blue or green component.
  97
  98 \wxheading{Parameters}
  99
 100 \docparam{n}{The number of indices in the palette.}
 101
 102 \docparam{red}{An array of red values.}
 103
 104 \docparam{green}{An array of green values.}
 105
 106 \docparam{blue}{An array of blue values.}
 107
 108 \wxheading{Return value}
 109
 110 true if the creation was successful, false otherwise.
 111
 112 \wxheading{See also}
 113
 114 \helpref{wxPalette::wxPalette}{wxpalettector}
 115
 116 \membersection{wxPalette::GetColoursCount}\label{wxpalettegetcolourscount}
 117
 118 \constfunc{int}{GetColoursCount}{\void}
 119
 120 Returns number of entries in palette.
 121
 122 \membersection{wxPalette::GetPixel}\label{wxpalettegetpixel}
 123
 124 \constfunc{int}{GetPixel}{\param{unsigned char }{red}, \param{unsigned char }{green},\rtfsp
 125  \param{unsigned char }{blue}}
 126
 127 Returns a pixel value (index into the palette) for the given RGB values.
 128
 129 \wxheading{Parameters}
 130
 131 \docparam{red}{Red value.}
 132
 133 \docparam{green}{Green value.}
 134
 135 \docparam{blue}{Blue value.}
 136
 137 \wxheading{Return value}
 138
 139 The nearest palette index or {\tt wxNOT\_FOUND} for unexpected errors.
 140
 141 \wxheading{See also}
 142
 143 \helpref{wxPalette::GetRGB}{wxpalettegetrgb}
 144
 145 \membersection{wxPalette::GetRGB}\label{wxpalettegetrgb}
 146
 147 \constfunc{bool}{GetRGB}{\param{int}{ pixel}, \param{const unsigned char* }{red}, \param{const unsigned char* }{green},\rtfsp
 148  \param{const unsigned char* }{blue}}
 149
 150 Returns RGB values for a given palette index.
 151
 152 \wxheading{Parameters}
 153
 154 \docparam{pixel}{The palette index.}
 155
 156 \docparam{red}{Receives the red value.}
 157
 158 \docparam{green}{Receives the green value.}
 159
 160 \docparam{blue}{Receives the blue value.}
 161
 162 \wxheading{Return value}
 163
 164 true if the operation was successful.
 165
 166 \wxheading{See also}
 167
 168 \helpref{wxPalette::GetPixel}{wxpalettegetpixel}
 169
 170 \perlnote{In wxPerl this method takes only the {\tt pixel} parameter and
 171   returns a 3-element list ( or the empty list upon failure ).}
 172
 173 \membersection{wxPalette::IsOk}\label{wxpaletteisok}
 174
 175 \constfunc{bool}{IsOk}{\void}
 176
 177 Returns true if palette data is present.
 178
 179 \membersection{wxPalette::operator $=$}\label{wxpaletteassignment}
 180
 181 \func{wxPalette\&}{operator $=$}{\param{const wxPalette\& }{palette}}
 182
 183 Assignment operator, using reference counting. Returns a reference
 184 to `this'.
 185
 186 \membersection{wxPalette::operator $==$}\label{wxpaletteequals}
 187
 188 \func{bool}{operator $==$}{\param{const wxPalette\& }{palette}}
 189
 190 Equality operator. Two palettes are equal if they contain pointers
 191 to the same underlying palette data. It does not compare each attribute,
 192 so two independently-created palettes using the same parameters will
 193 fail the test.
 194
 195 \membersection{wxPalette::operator $!=$}\label{wxpalettenotequals}
 196
 197 \func{bool}{operator $!=$}{\param{const wxPalette\& }{palette}}
 198
 199 Inequality operator. Two palettes are not equal if they contain pointers
 200 to different underlying palette data. It does not compare each attribute.
 201