docs/latex/wx/colour.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        colour.tex
   3 %% Purpose:     wxColour docs
   4 %% Author:
   5 %% Modified by: Francesco Montorsi
   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}, \param{unsigned char}{ alpha=wxALPHA\_OPAQUE}}
  62
  63 Constructs a colour from red, green, blue and alpha values.
  64
  65 \func{}{wxColour}{\param{const wxString\& }{colourNname}}
  66
  67 Constructs a colour using the given string. See \helpref{Set}{wxcolourset} for more info.
  68
  69 \func{}{wxColour}{\param{const wxColour\&}{ colour}}
  70
  71 Copy constructor.
  72
  73 \wxheading{Parameters}
  74
  75 \docparam{red}{The red value.}
  76
  77 \docparam{green}{The green value.}
  78
  79 \docparam{blue}{The blue value.}
  80
  81 \docparam{alpha}{The alpha value. Alpha values range from 0 (wxALPHA\_TRANSPARENT) to 255 (wxALPHA\_OPAQUE).}
  82
  83 \docparam{colourName}{The colour name.}
  84
  85 \docparam{colour}{The colour to copy.}
  86
  87 \wxheading{See also}
  88
  89 \helpref{wxColourDatabase}{wxcolourdatabase}
  90
  91 \pythonnote{Constructors supported by wxPython are:\par
  92 \indented{2cm}{\begin{twocollist}
  93 \twocolitem{{\bf wxColour(red=0, green=0, blue=0)}}{}
  94 \twocolitem{{\bf wxNamedColour(name)}}{}
  95 \end{twocollist}}
  96 }
  97
  98
  99
 100 \membersection{wxColour::Alpha}\label{wxcolouralpha}
 101
 102 \constfunc{unsigned char}{Alpha}{\void}
 103
 104 Returns the alpha value, on platforms where alpha is not yet supported, this always returns wxALPHA\_OPAQUE.
 105
 106
 107 \membersection{wxColour::Blue}\label{wxcolourblue}
 108
 109 \constfunc{unsigned char}{Blue}{\void}
 110
 111 Returns the blue intensity.
 112
 113
 114 \membersection{wxColour::GetAsString}\label{wxcolourgetasstring}
 115
 116 \constfunc{wxString}{GetAsString}{\param{long}{ flags}}
 117
 118 Converts this colour to a \helpref{wxString}{wxstring}
 119 using the given {\it flags}.
 120
 121 The supported flags are \textbf{wxC2S\_NAME}, to obtain the colour name (e.g.
 122 wxColour(255,0,0) -> \texttt{``red"}), \textbf{wxC2S\_CSS\_SYNTAX}, to obtain
 123 the colour in the \texttt{``rgb(r,g,b)"} or \texttt{``rgba(r,g,b,a)"} syntax
 124 (e.g. wxColour(255,0,0,85) -> \texttt{``rgba(255,0,0,0.333)"}), and
 125 \textbf{wxC2S\_HTML\_SYNTAX}, to obtain the colour as  \texttt{``\#"} followed
 126 by 6 hexadecimal digits (e.g. wxColour(255,0,0) -> \texttt{``\#FF0000"}).
 127
 128 This function never fails and always returns a non-empty string but asserts if
 129 the colour has alpha channel (i.e. is non opaque) but
 130 \textbf{wxC2S\_CSS\_SYNTAX} (which is the only one supporting alpha) is not
 131 specified in flags.
 132
 133 \newsince{2.7.0}
 134
 135
 136 \membersection{wxColour::GetPixel}\label{wxcolourgetpixel}
 137
 138 \constfunc{long}{GetPixel}{\void}
 139
 140 Returns a pixel value which is platform-dependent. On Windows, a COLORREF is returned.
 141 On X, an allocated pixel value is returned.
 142
 143 -1 is returned if the pixel is invalid (on X, unallocated).
 144
 145
 146 \membersection{wxColour::Green}\label{wxcolourgreen}
 147
 148 \constfunc{unsigned char}{Green}{\void}
 149
 150 Returns the green intensity.
 151
 152
 153 \membersection{wxColour::IsOk}\label{wxcolourisok}
 154
 155 \constfunc{bool}{IsOk}{\void}
 156
 157 Returns \true if the colour object is valid (the colour has been initialised with RGB values).
 158
 159
 160 \membersection{wxColour::Red}\label{wxcolourred}
 161
 162 \constfunc{unsigned char}{Red}{\void}
 163
 164 Returns the red intensity.
 165
 166
 167 \membersection{wxColour::Set}\label{wxcolourset}
 168
 169 \func{void}{Set}{\param{unsigned char}{ red}, \param{unsigned char}{ green}, \param{unsigned char}{ blue}, \param{unsigned char}{ alpha=wxALPHA\_OPAQUE}}
 170
 171 \func{void}{Set}{\param{unsigned long}{ RGB}}
 172
 173 \func{bool}{Set}{\param{const wxString \&}{ str}}
 174
 175 Sets the RGB intensity values using the given values (first overload), extracting them from the packed long (second overload), using the given string (third overloard).
 176
 177 When using third form, Set() accepts: colour names (those listed in
 178 \helpref{wxTheColourDatabase}{wxcolourdatabase}), the CSS-like
 179 \texttt{``rgb(r,g,b)"} or \texttt{``rgba(r,g,b,a)"} syntax (case insensitive)
 180 and the HTML-like syntax (i.e. \texttt{``\#"} followed by 6 hexadecimal digits
 181 for red, green, blue components).
 182
 183 Returns \true if the conversion was successful, \false otherwise.
 184
 185 \newsince{2.7.0}
 186
 187
 188 \membersection{wxColour::operator $=$}\label{wxcolourassign}
 189
 190 \func{wxColour\&}{operator $=$}{\param{const wxColour\&}{ colour}}
 191
 192 Assignment operator, taking another colour object.
 193
 194 \func{wxColour\&}{operator $=$}{\param{const wxString\&}{ colourName}}
 195
 196 Assignment operator, using a colour name to be found in the colour database.
 197
 198 \wxheading{See also}
 199
 200 \helpref{wxColourDatabase}{wxcolourdatabase}
 201
 202
 203 \membersection{wxColour::operator $==$}\label{wxcolourequality}
 204
 205 \func{bool}{operator $==$}{\param{const wxColour\&}{ colour}}
 206
 207 Tests the equality of two colours by comparing individual red, green, blue colours and alpha values.
 208
 209
 210 \membersection{wxColour::operator $!=$}\label{wxcolourinequality}
 211
 212 \func{bool}{operator $!=$}{\param{const wxColour\&}{ colour}}
 213
 214 Tests the inequality of two colours by comparing individual red, green, blue colours and alpha values.
 215
 216 \section{\class{wxColourData}}\label{wxcolourdata}
 217
 218 This class holds a variety of information related to colour dialogs.
 219
 220 \wxheading{Derived from}
 221
 222 \helpref{wxObject}{wxobject}
 223
 224 \wxheading{Include files}
 225
 226 <wx/cmndata.h>
 227
 228 \wxheading{See also}
 229
 230 \helpref{wxColour}{wxcolour}, \helpref{wxColourDialog}{wxcolourdialog}, \helpref{wxColourDialog overview}{wxcolourdialogoverview}
 231
 232 \latexignore{\rtfignore{\wxheading{Members}}}
 233
 234
 235 \membersection{wxColourData::wxColourData}\label{wxcolourdatactor}
 236
 237 \func{}{wxColourData}{\void}
 238
 239 Constructor. Initializes the custom colours to {\tt wxNullColour},
 240 the {\it data colour} setting
 241 to black, and the {\it choose full} setting to true.
 242
 243
 244 \membersection{wxColourData::\destruct{wxColourData}}\label{wxcolourdatadtor}
 245
 246 \func{}{\destruct{wxColourData}}{\void}
 247
 248 Destructor.
 249
 250
 251 \membersection{wxColourData::GetChooseFull}\label{wxcolourdatagetchoosefull}
 252
 253 \constfunc{bool}{GetChooseFull}{\void}
 254
 255 Under Windows, determines whether the Windows colour dialog will display the full dialog
 256 with custom colour selection controls. Under PalmOS, determines whether colour dialog
 257 will display full rgb colour picker or only available palette indexer.
 258 Has no meaning under other platforms.
 259
 260 The default value is true.
 261
 262
 263 \membersection{wxColourData::GetColour}\label{wxcolourdatagetcolour}
 264
 265 \constfunc{wxColour\&}{GetColour}{\void}
 266
 267 Gets the current colour associated with the colour dialog.
 268
 269 The default colour is black.
 270
 271
 272 \membersection{wxColourData::GetCustomColour}\label{wxcolourdatagetcustomcolour}
 273
 274 \constfunc{wxColour\&}{GetCustomColour}{\param{int}{ i}}
 275
 276 Gets the {\it i}th custom colour associated with the colour dialog. {\it i} should
 277 be an integer between 0 and 15.
 278
 279 The default custom colours are invalid colours.
 280
 281
 282 \membersection{wxColourData::SetChooseFull}\label{wxcolourdatasetchoosefull}
 283
 284 \func{void}{SetChooseFull}{\param{const bool }{flag}}
 285
 286 Under Windows, tells the Windows colour dialog to display the full dialog
 287 with custom colour selection controls. Under other platforms, has no effect.
 288
 289 The default value is true.
 290
 291
 292 \membersection{wxColourData::SetColour}\label{wxcolourdatasetcolour}
 293
 294 \func{void}{SetColour}{\param{const wxColour\&}{ colour}}
 295
 296 Sets the default colour for the colour dialog.
 297
 298 The default colour is black.
 299
 300
 301 \membersection{wxColourData::SetCustomColour}\label{wxcolourdatasetcustomcolour}
 302
 303 \func{void}{SetCustomColour}{\param{int}{ i}, \param{const wxColour\&}{ colour}}
 304
 305 Sets the {\it i}th custom colour for the colour dialog. {\it i} should
 306 be an integer between 0 and 15.
 307
 308 The default custom colours are invalid colours.
 309
 310
 311 \membersection{wxColourData::operator $=$}\label{wxcolourdataassign}
 312
 313 \func{void}{operator $=$}{\param{const wxColourData\&}{ data}}
 314
 315 Assignment operator for the colour data.
 316
 317
 318
 319
 320 \section{\class{wxColourDatabase}}\label{wxcolourdatabase}
 321
 322 wxWidgets maintains a database of standard RGB colours for a predefined
 323 set of named colours (such as ``BLACK'', ``LIGHT GREY''). The
 324 application may add to this set if desired by using
 325 \helpref{AddColour}{wxcolourdatabaseaddcolour} and may use it to look up
 326 colours by names using \helpref{Find}{wxcolourdatabasefind} or find the names
 327 for the standard colour suing \helpref{FindName}{wxcolourdatabasefindname}.
 328
 329 There is one predefined instance of this class called
 330 {\bf wxTheColourDatabase}.
 331
 332 \wxheading{Derived from}
 333
 334 None
 335
 336 \wxheading{Include files}
 337
 338 <wx/gdicmn.h>
 339
 340 \wxheading{Remarks}
 341
 342 The standard database contains at least the following colours:
 343
 344 AQUAMARINE, BLACK, BLUE, BLUE VIOLET, BROWN, CADET BLUE, CORAL,
 345 CORNFLOWER BLUE, CYAN, DARK GREY, DARK GREEN, DARK OLIVE GREEN, DARK
 346 ORCHID, DARK SLATE BLUE, DARK SLATE GREY DARK TURQUOISE, DIM GREY,
 347 FIREBRICK, FOREST GREEN, GOLD, GOLDENROD, GREY, GREEN, GREEN YELLOW,
 348 INDIAN RED, KHAKI, LIGHT BLUE, LIGHT GREY, LIGHT STEEL BLUE, LIME GREEN,
 349 MAGENTA, MAROON, MEDIUM AQUAMARINE, MEDIUM BLUE, MEDIUM FOREST GREEN,
 350 MEDIUM GOLDENROD, MEDIUM ORCHID, MEDIUM SEA GREEN, MEDIUM SLATE BLUE,
 351 MEDIUM SPRING GREEN, MEDIUM TURQUOISE, MEDIUM VIOLET RED, MIDNIGHT BLUE,
 352 NAVY, ORANGE, ORANGE RED, ORCHID, PALE GREEN, PINK, PLUM, PURPLE, RED,
 353 SALMON, SEA GREEN, SIENNA, SKY BLUE, SLATE BLUE, SPRING GREEN, STEEL
 354 BLUE, TAN, THISTLE, TURQUOISE, VIOLET, VIOLET RED, WHEAT, WHITE, YELLOW,
 355 YELLOW GREEN.
 356
 357 \wxheading{See also}
 358
 359 \helpref{wxColour}{wxcolour}
 360
 361 \latexignore{\rtfignore{\wxheading{Members}}}
 362
 363
 364 \membersection{wxColourDatabase::wxColourDatabase}\label{wxcolourdatabaseconstr}
 365
 366 \func{}{wxColourDatabase}{\void}
 367
 368 Constructs the colour database. It will be initialized at the first use.
 369
 370
 371 \membersection{wxColourDatabase::AddColour}\label{wxcolourdatabaseaddcolour}
 372
 373 \func{void}{AddColour}{\param{const wxString\& }{colourName}, \param{const wxColour\&}{colour}}
 374
 375 \func{void}{AddColour}{\param{const wxString\& }{colourName}, \param{wxColour* }{colour}}
 376
 377 Adds a colour to the database. If a colour with the same name already exists,
 378 it is replaced.
 379
 380 Please note that the overload taking a pointer is deprecated and will be
 381 removed in the next wxWidgets version, please don't use it.
 382
 383
 384 \membersection{wxColourDatabase::Find}\label{wxcolourdatabasefind}
 385
 386 \func{wxColour}{Find}{\param{const wxString\& }{colourName}}
 387
 388 Finds a colour given the name. Returns an invalid colour object (that is, such
 389 that its \helpref{Ok()}{wxcolourisok} method returns \false) if the colour wasn't
 390 found in the database.
 391
 392
 393 \membersection{wxColourDatabase::FindName}\label{wxcolourdatabasefindname}
 394
 395 \constfunc{wxString}{FindName}{\param{const wxColour\&}{ colour}}
 396
 397 Finds a colour name given the colour. Returns an empty string if the colour is
 398 not found in the database.
 399