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