docs/latex/wx/colour.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        colour.tex
   3 %% Purpose:     wxColour 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{wxColour}}\label{wxcolour}
  13
  14 A colour is an object representing a combination of Red, Green, and Blue (RGB) intensity values,
  15 and is used to determine drawing colours. See the
  16 entry for \helpref{wxColourDatabase}{wxcolourdatabase} for how a pointer to a predefined,
  17 named colour may be returned instead of creating a new colour.
  18
  19 Valid RGB values are in the range 0 to 255.
  20
  21 You can retrieve the current system colour settings with \helpref{wxSystemSettings}{wxsystemsettings}.
  22
  23 \wxheading{Derived from}
  24
  25 \helpref{wxObject}{wxobject}
  26
  27 \wxheading{Include files}
  28
  29 <wx/colour.h>
  30
  31 \wxheading{Predefined objects}
  32
  33 Objects:
  34
  35 {\bf wxNullColour}
  36
  37 Pointers:
  38
  39 {\bf wxBLACK\\
  40 wxWHITE\\
  41 wxRED\\
  42 wxBLUE\\
  43 wxGREEN\\
  44 wxCYAN\\
  45 wxLIGHT\_GREY}
  46
  47 \wxheading{See also}
  48
  49 \helpref{wxColourDatabase}{wxcolourdatabase}, \helpref{wxPen}{wxpen}, \helpref{wxBrush}{wxbrush},\rtfsp
  50 \helpref{wxColourDialog}{wxcolourdialog}, \helpref{wxSystemSettings}{wxsystemsettings}
  51
  52 \latexignore{\rtfignore{\wxheading{Members}}}
  53
  54
  55 \membersection{wxColour::wxColour}\label{wxcolourconstr}
  56
  57 \func{}{wxColour}{\void}
  58
  59 Default constructor.
  60
  61 \func{}{wxColour}{\param{unsigned char}{ red}, \param{unsigned char}{ green}, \param{unsigned char}{ blue}}
  62
  63 Constructs a colour from red, green and blue values.
  64
  65 \func{}{wxColour}{\param{const wxString\& }{colourNname}}
  66
  67 Constructs a colour object using a colour name
  68 listed in {\bf wxTheColourDatabase}.
  69
  70 \func{}{wxColour}{\param{const wxColour\&}{ colour}}
  71
  72 Copy constructor.
  73
  74 \wxheading{Parameters}
  75
  76 \docparam{red}{The red value.}
  77
  78 \docparam{green}{The green value.}
  79
  80 \docparam{blue}{The blue value.}
  81
  82 \docparam{colourName}{The colour name.}
  83
  84 \docparam{colour}{The colour to copy.}
  85
  86 \wxheading{See also}
  87
  88 \helpref{wxColourDatabase}{wxcolourdatabase}
  89
  90 \pythonnote{Constructors supported by wxPython are:\par
  91 \indented{2cm}{\begin{twocollist}
  92 \twocolitem{{\bf wxColour(red=0, green=0, blue=0)}}{}
  93 \twocolitem{{\bf wxNamedColour(name)}}{}
  94 \end{twocollist}}
  95 }
  96
  97
  98
  99 \membersection{wxColour::Blue}\label{wxcolourblue}
 100
 101 \constfunc{unsigned char}{Blue}{\void}
 102
 103 Returns the blue intensity.
 104
 105
 106 \membersection{wxColour::GetPixel}\label{wxcolourgetpixel}
 107
 108 \constfunc{long}{GetPixel}{\void}
 109
 110 Returns a pixel value which is platform-dependent. On Windows, a COLORREF is returned.
 111 On X, an allocated pixel value is returned.
 112
 113 -1 is returned if the pixel is invalid (on X, unallocated).
 114
 115
 116 \membersection{wxColour::Green}\label{wxcolourgreen}
 117
 118 \constfunc{unsigned char}{Green}{\void}
 119
 120 Returns the green intensity.
 121
 122
 123 \membersection{wxColour::Ok}\label{wxcolourok}
 124
 125 \constfunc{bool}{Ok}{\void}
 126
 127 Returns \true if the colour object is valid (the colour has been initialised with RGB values).
 128
 129
 130 \membersection{wxColour::Red}\label{wxcolourred}
 131
 132 \constfunc{unsigned char}{Red}{\void}
 133
 134 Returns the red intensity.
 135
 136
 137 \membersection{wxColour::Set}\label{wxcolourset}
 138
 139 \func{void}{Set}{\param{unsigned char}{ red}, \param{unsigned char}{ green}, \param{unsigned char}{ blue}}
 140
 141 Sets the RGB intensity values.
 142
 143
 144 \membersection{wxColour::operator $=$}\label{wxcolourassign}
 145
 146 \func{wxColour\&}{operator $=$}{\param{const wxColour\&}{ colour}}
 147
 148 Assignment operator, taking another colour object.
 149
 150 \func{wxColour\&}{operator $=$}{\param{const wxString\&}{ colourName}}
 151
 152 Assignment operator, using a colour name to be found in the colour database.
 153
 154 \wxheading{See also}
 155
 156 \helpref{wxColourDatabase}{wxcolourdatabase}
 157
 158
 159 \membersection{wxColour::operator $==$}\label{wxcolourequality}
 160
 161 \func{bool}{operator $==$}{\param{const wxColour\&}{ colour}}
 162
 163 Tests the equality of two colours by comparing individual red, green blue colours.
 164
 165
 166 \membersection{wxColour::operator $!=$}\label{wxcolourinequality}
 167
 168 \func{bool}{operator $!=$}{\param{const wxColour\&}{ colour}}
 169
 170 Tests the inequality of two colours by comparing individual red, green blue colours.
 171
 172 \section{\class{wxColourData}}\label{wxcolourdata}
 173
 174 This class holds a variety of information related to colour dialogs.
 175
 176 \wxheading{Derived from}
 177
 178 \helpref{wxObject}{wxobject}
 179
 180 \wxheading{Include files}
 181
 182 <wx/cmndata.h>
 183
 184 \wxheading{See also}
 185
 186 \helpref{wxColour}{wxcolour}, \helpref{wxColourDialog}{wxcolourdialog}, \helpref{wxColourDialog overview}{wxcolourdialogoverview}
 187
 188 \latexignore{\rtfignore{\wxheading{Members}}}
 189
 190
 191 \membersection{wxColourData::wxColourData}\label{wxcolourdatactor}
 192
 193 \func{}{wxColourData}{\void}
 194
 195 Constructor. Initializes the custom colours to {\tt wxNullColour},
 196 the {\it data colour} setting
 197 to black, and the {\it choose full} setting to true.
 198
 199
 200 \membersection{wxColourData::\destruct{wxColourData}}\label{wxcolourdatadtor}
 201
 202 \func{}{\destruct{wxColourData}}{\void}
 203
 204 Destructor.
 205
 206
 207 \membersection{wxColourData::GetChooseFull}\label{wxcolourdatagetchoosefull}
 208
 209 \constfunc{bool}{GetChooseFull}{\void}
 210
 211 Under Windows, determines whether the Windows colour dialog will display the full dialog
 212 with custom colour selection controls. Under PalmOS, determines whether colour dialog
 213 will display full rgb colour picker or only available palette indexer.
 214 Has no meaning under other platforms.
 215
 216 The default value is true.
 217
 218
 219 \membersection{wxColourData::GetColour}\label{wxcolourdatagetcolour}
 220
 221 \constfunc{wxColour\&}{GetColour}{\void}
 222
 223 Gets the current colour associated with the colour dialog.
 224
 225 The default colour is black.
 226
 227
 228 \membersection{wxColourData::GetCustomColour}\label{wxcolourdatagetcustomcolour}
 229
 230 \constfunc{wxColour\&}{GetCustomColour}{\param{int}{ i}}
 231
 232 Gets the {\it i}th custom colour associated with the colour dialog. {\it i} should
 233 be an integer between 0 and 15.
 234
 235 The default custom colours are invalid colours.
 236
 237
 238 \membersection{wxColourData::SetChooseFull}\label{wxcolourdatasetchoosefull}
 239
 240 \func{void}{SetChooseFull}{\param{const bool }{flag}}
 241
 242 Under Windows, tells the Windows colour dialog to display the full dialog
 243 with custom colour selection controls. Under other platforms, has no effect.
 244
 245 The default value is true.
 246
 247
 248 \membersection{wxColourData::SetColour}\label{wxcolourdatasetcolour}
 249
 250 \func{void}{SetColour}{\param{const wxColour\&}{ colour}}
 251
 252 Sets the default colour for the colour dialog.
 253
 254 The default colour is black.
 255
 256
 257 \membersection{wxColourData::SetCustomColour}\label{wxcolourdatasetcustomcolour}
 258
 259 \func{void}{SetCustomColour}{\param{int}{ i}, \param{const wxColour\&}{ colour}}
 260
 261 Sets the {\it i}th custom colour for the colour dialog. {\it i} should
 262 be an integer between 0 and 15.
 263
 264 The default custom colours are invalid colours.
 265
 266
 267 \membersection{wxColourData::operator $=$}\label{wxcolourdataassign}
 268
 269 \func{void}{operator $=$}{\param{const wxColourData\&}{ data}}
 270
 271 Assignment operator for the colour data.
 272
 273
 274
 275
 276 \section{\class{wxColourDatabase}}\label{wxcolourdatabase}
 277
 278 wxWidgets maintains a database of standard RGB colours for a predefined
 279 set of named colours (such as ``BLACK'', ``LIGHT GREY''). The
 280 application may add to this set if desired by using
 281 \helpref{AddColour}{wxcolourdatabaseaddcolour} and may use it to look up
 282 colours by names using \helpref{Find}{wxcolourdatabasefind} or find the names
 283 for the standard colour suing \helpref{FindName}{wxcolourdatabasefindname}.
 284
 285 There is one predefined instance of this class called
 286 {\bf wxTheColourDatabase}.
 287
 288 \wxheading{Derived from}
 289
 290 None
 291
 292 \wxheading{Include files}
 293
 294 <wx/gdicmn.h>
 295
 296 \wxheading{Remarks}
 297
 298 The standard database contains at least the following colours:
 299
 300 AQUAMARINE, BLACK, BLUE, BLUE VIOLET, BROWN, CADET BLUE, CORAL,
 301 CORNFLOWER BLUE, CYAN, DARK GREY, DARK GREEN, DARK OLIVE GREEN, DARK
 302 ORCHID, DARK SLATE BLUE, DARK SLATE GREY DARK TURQUOISE, DIM GREY,
 303 FIREBRICK, FOREST GREEN, GOLD, GOLDENROD, GREY, GREEN, GREEN YELLOW,
 304 INDIAN RED, KHAKI, LIGHT BLUE, LIGHT GREY, LIGHT STEEL BLUE, LIME GREEN,
 305 MAGENTA, MAROON, MEDIUM AQUAMARINE, MEDIUM BLUE, MEDIUM FOREST GREEN,
 306 MEDIUM GOLDENROD, MEDIUM ORCHID, MEDIUM SEA GREEN, MEDIUM SLATE BLUE,
 307 MEDIUM SPRING GREEN, MEDIUM TURQUOISE, MEDIUM VIOLET RED, MIDNIGHT BLUE,
 308 NAVY, ORANGE, ORANGE RED, ORCHID, PALE GREEN, PINK, PLUM, PURPLE, RED,
 309 SALMON, SEA GREEN, SIENNA, SKY BLUE, SLATE BLUE, SPRING GREEN, STEEL
 310 BLUE, TAN, THISTLE, TURQUOISE, VIOLET, VIOLET RED, WHEAT, WHITE, YELLOW,
 311 YELLOW GREEN.
 312
 313 \wxheading{See also}
 314
 315 \helpref{wxColour}{wxcolour}
 316
 317 \latexignore{\rtfignore{\wxheading{Members}}}
 318
 319
 320 \membersection{wxColourDatabase::wxColourDatabase}\label{wxcolourdatabaseconstr}
 321
 322 \func{}{wxColourDatabase}{\void}
 323
 324 Constructs the colour database. It will be initialized at the first use.
 325
 326
 327 \membersection{wxColourDatabase::AddColour}\label{wxcolourdatabaseaddcolour}
 328
 329 \func{void}{AddColour}{\param{const wxString\& }{colourName}, \param{const wxColour\&}{colour}}
 330
 331 \func{void}{AddColour}{\param{const wxString\& }{colourName}, \param{wxColour* }{colour}}
 332
 333 Adds a colour to the database. If a colour with the same name already exists,
 334 it is replaced.
 335
 336 Please note that the overload taking a pointer is deprecated and will be
 337 removed in the next wxWidgets version, please don't use it.
 338
 339
 340 \membersection{wxColourDatabase::Find}\label{wxcolourdatabasefind}
 341
 342 \func{wxColour}{Find}{\param{const wxString\& }{colourName}}
 343
 344 Finds a colour given the name. Returns an invalid colour object (that is, such
 345 that its \helpref{Ok()}{wxcolourok} method returns \false) if the colour wasn't
 346 found in the database.
 347
 348
 349 \membersection{wxColourDatabase::FindName}\label{wxcolourdatabasefindname}
 350
 351 \constfunc{wxString}{FindName}{\param{const wxColour\&}{ colour}}
 352
 353 Finds a colour name given the colour. Returns an empty string if the colour is
 354 not found in the database.
 355
 356