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