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