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