1QColor(3qt) QColor(3qt)
2
6 QColor - Colors based on RGB or HSV values
7
9 #include <qcolor.h>
10 Public Members
12 enum Spec { Rgb, Hsv }
13 QColor ()
14 QColor ( int r, int g, int b )
15 QColor ( int x, int y, int z, Spec colorSpec )
16 QColor ( QRgb rgb, uint pixel = 0xffffffff )
17 QColor ( const QString & name )
18 QColor ( const char * name )
19 QColor ( const QColor & c )
20 QColor & operator= ( const QColor & c )
21 bool isValid () const
22 QString name () const
23 void setNamedColor ( const QString & name )
24 QRgb rgb () const
25 void setRgb ( int r, int g, int b )
26 void setRgb ( QRgb rgb )
27 void getRgb ( int * r, int * g, int * b ) const
28 void rgb ( int * r, int * g, int * b ) const (obsolete)
29 int red () const
30 int green () const
31 int blue () const
32 void setHsv ( int h, int s, int v )
33 void getHsv ( int * h, int * s, int * v ) const
34 void hsv ( int * h, int * s, int * v ) const (obsolete)
35 void getHsv ( int & h, int & s, int & v ) const (obsolete)
36 QColor light ( int factor = 150 ) const
37 QColor dark ( int factor = 200 ) const
38 bool operator== ( const QColor & c ) const
39 bool operator!= ( const QColor & c ) const
40 uint alloc ()
41 uint pixel () const
42 uint pixel ( int screen ) const
43 Static Public Members
45 int maxColors ()
46 int numBitPlanes ()
47 int enterAllocContext ()
48 void leaveAllocContext ()
49 int currentAllocContext ()
50 void destroyAllocContext ( int context )
51 void initialize ()
52 void cleanup ()
53 QStringList colorNames ()
54
56 QDataStream & operator<< ( QDataStream & s, const QColor & c )
57 QDataStream & operator>> ( QDataStream & s, QColor & c )
58 int qRed ( QRgb rgb )
59 int qGreen ( QRgb rgb )
60 int qBlue ( QRgb rgb )
61 int qAlpha ( QRgb rgba )
62 QRgb qRgb ( int r, int g, int b )
63 QRgb qRgba ( int r, int g, int b, int a )
64 int qGray ( int r, int g, int b )
65 int qGray ( qRgb rgb )
66
68 The QColor class provides colors based on RGB or HSV values.
69 A color is normally specified in terms of RGB (red, green and blue)
71 components, but it is also possible to specify HSV (hue, saturation and
72 value) or set a color name (the names are copied from from the X11
73 color database).
74 In addition to the RGB value, a QColor also has a pixel value and a
76 validity. The pixel value is used by the underlying window system to
77 refer to a color. It can be thought of as an index into the display
78 hardware's color table.
79 The validity (isValid()) indicates whether the color is legal at all.
81 For example, a RGB color with RGB values out of range is illegal. For
82 performance reasons, QColor mostly disregards illegal colors. The
83 result of using an invalid color is unspecified and will usually be
84 surprising.
85 There are 19 predefined QColor objects: white, black, red, darkRed,
87 green, darkGreen, blue, darkBlue, cyan, darkCyan, magenta, darkMagenta,
88 yellow, darkYellow, gray, darkGray, lightGray, color0 and color1,
89 accessible as members of the Qt namespace (ie. Qt::red).
90 <center>
92 [Image Omitted]
93 </center>
95 The colors color0 (zero pixel value) and color1 (non-zero pixel value)
97 are special colors for drawing in bitmaps. Painting with color0 sets
98 the bitmap bits to 0 (transparent, i.e. background), and painting with
99 color1 sets the bits to 1 (opaque, i.e. foreground).
100 The QColor class has an efficient, dynamic color allocation strategy. A
102 color is normally allocated the first time it is used (lazy
103 allocation), that is, whenever the pixel() function is called. The
104 following steps are taken to allocate a color. If, at any point, a
105 suitable color is found then the appropriate pixel value is returned
106 and the subsequent steps are not taken:
107 <ol type=1>
109 1 Is the pixel value valid? If it is, just return it; otherwise,
111 allocate a pixel value.
112 2 Check an internal hash table to see if we allocated an equal RGB
114 value earlier. If we did, set the corresponding pixel value for
115 the color and return it.
116 3 Try to allocate the RGB value. If we succeed, we get a pixel
118 value that we save in the internal table with the RGB value.
119 Return the pixel value.
120 4 The color could not be allocated. Find the closest matching
122 color, save it in the internal table, and return it.
123 A color can be set by passing setNamedColor() an RGB string like"
125 #112233", or a color name, e.g. "blue". The names are taken from X11's
126 rgb.txt database but can also be used under Windows. To get a lighter
127 or darker color use light() and dark() respectively. Colors can also be
128 set using setRgb() and setHsv(). The color components can be accessed
129 in one go with rgb() and hsv(), or individually with red(), green() and
130 blue().
131 Use maxColors() and numBitPlanes() to determine the maximum number of
133 colors and the number of bit planes supported by the underlying window
134 system,
135 If you need to allocate many colors temporarily, for example in an
137 image viewer application, enterAllocContext(), leaveAllocContext() and
138 destroyAllocContext() will prove useful.
139
141 Because many people don't know the HSV color model very well, we'll
142 cover it briefly here.
143 The RGB model is hardware-oriented. Its representation is close to what
145 most monitors show. In contrast, HSV represents color in a way more
146 suited to the human perception of color. For example, the relationships
147 "stronger than", "darker than" and "the opposite of" are easily
148 expressed in HSV but are much harder to express in RGB.
149 HSV, like RGB, has three components:
151 H, for hue, is either 0-359 if the color is chromatic (not gray), or
153 meaningless if it is gray. It represents degrees on the color wheel
154 familiar to most people. Red is 0 (degrees), green is 120 and blue is
155 240.
156 S, for saturation, is 0-255, and the bigger it is, the stronger the
158 color is. Grayish colors have saturation near 0; very strong colors
159 have saturation near 255.
160 V, for value, is 0-255 and represents lightness or brightness of the
162 color. 0 is black; 255 is as far from black as possible.
163 Here are some examples: Pure red is H=0, S=255, V=255. A dark red,
165 moving slightly towards the magenta, could be H=350 (equivalent to
166 -10), S=255, V=180. A grayish light red could have H about 0 (say
167 350-359 or 0-10), S about 50-100, and S=255.
168 Qt returns a hue value of -1 for achromatic colors. If you pass a too-
170 big hue value, Qt forces it into range. Hue 360 or 720 is treated as 0;
171 hue 540 is treated as 180.
172 See also QPalette, QColorGroup, QApplication::setColorSpec(), Color
174 FAQ, Widget Appearance and Style, Graphics Classes, and Image
175 Processing Classes.
176 Member Type Documentation
179 The type of color specified, either RGB or HSV, e.g. in the
180 QColor::QColor( x, y, z, colorSpec) constructor.
181 QColor::Rgb
183 QColor::Hsv
185
188 Constructs an invalid color with the RGB value (0, 0, 0). An invalid
189 color is a color that is not properly set up for the underlying window
190 system.
191 The alpha value of an invalid color is unspecified.
193 See also isValid().
195
197 Constructs a color with the RGB value r, g, b, in the same way as
198 setRgb().
199 The color is left invalid if any or the arguments are illegal.
201 See also setRgb().
203
205 Constructs a color with the RGB or HSV value x, y, z.
206 The arguments are an RGB value if colorSpec is QColor::Rgb. x (red), y
208 (green), and z (blue). All of them must be in the range 0-255.
209 The arguments are an HSV value if colorSpec is QColor::Hsv. x (hue)
211 must be -1 for achromatic colors and 0-359 for chromatic colors; y
212 (saturation) and z (value) must both be in the range 0-255.
213 See also setRgb() and setHsv().
215
217 Constructs a color with the RGB value rgb and a custom pixel value
218 pixel.
219 If pixel == 0xffffffff (the default), then the color uses the RGB value
221 in a standard way. If pixel is something else, then the pixel value is
222 set directly to pixel, skipping the normal allocation procedure.
223
225 Constructs a named color in the same way as setNamedColor() using name
226 name.
227 The color is left invalid if name cannot be parsed.
229 See also setNamedColor().
231
233 Constructs a named color in the same way as setNamedColor() using name
234 name.
235 The color is left invalid if name cannot be parsed.
237 See also setNamedColor().
239
241 Constructs a color that is a copy of c.
242
244 Allocates the RGB color and returns the pixel value.
245 Allocating a color means to obtain a pixel value from the RGB
247 specification. The pixel value is an index into the global color table,
248 but should be considered an arbitrary platform-dependent value.
249 The pixel() function calls alloc() if necessary, so in general you
251 don't need to call this function.
252 See also enterAllocContext().
254
256 Returns the B (blue) component of the RGB value.
257
259 Internal clean up required for QColor. This function is called from the
260 QApplication destructor.
261 See also initialize().
263
265 Returns a QStringList containing the color names Qt knows about.
266
268 Returns the current color allocation context.
269 The default context is 0.
271 See also enterAllocContext() and leaveAllocContext().
273
275 Returns a darker (or lighter) color, but does not change this object.
276 Returns a darker color if factor is greater than 100. Setting factor to
278 300 returns a color that has one-third the brightness.
279 Returns a lighter color if factor is less than 100. We recommend using
281 lighter() for this purpose. If factor is 0 or negative, the return
282 value is unspecified.
283 (This function converts the current RGB color to HSV, divides V by
285 factor and converts back to RGB.)
286 See also light().
288 Examples:
290
292 Destroys a color allocation context, context.
293 This function deallocates all colors that were allocated in the
295 specified context. If context == -1, it frees up all colors that the
296 application has allocated. If context == -2, it frees up all colors
297 that the application has allocated, except those in the default
298 context.
299 The function does nothing for true color displays.
301 See also enterAllocContext() and alloc().
303 Example: showimg/showimg.cpp.
305
307 Enters a color allocation context and returns a non-zero unique
308 identifier.
309 Color allocation contexts are useful for programs that need to allocate
311 many colors and throw them away later, like image viewers. The
312 allocation context functions work for true color displays as well as
313 for colormap displays, except that QColor::destroyAllocContext() does
314 nothing for true color.
315 Example:
317 QPixmap loadPixmap( QString fileName )
319 {
320 static int alloc_context = 0;
321 if ( alloc_context )
322 QColor::destroyAllocContext( alloc_context );
323 alloc_context = QColor::enterAllocContext();
324 QPixmap pm( fileName );
325 QColor::leaveAllocContext();
326 return pm;
327 }
328 The example code loads a pixmap from file. It frees up all colors that
330 were allocated the last time loadPixmap() was called.
331 The initial/default context is 0. Qt keeps a list of colors associated
333 with their allocation contexts. You can call destroyAllocContext() to
334 get rid of all colors that were allocated in a specific context.
335 Calling enterAllocContext() enters an allocation context. The
337 allocation context lasts until you call leaveAllocContext(). QColor has
338 an internal stack of allocation contexts. Each call to
339 enterAllocContex() must have a corresponding leaveAllocContext().
340 // context 0 active
342 int c1 = QColor::enterAllocContext(); // enter context c1
343 // context c1 active
344 int c2 = QColor::enterAllocContext(); // enter context c2
345 // context c2 active
346 QColor::leaveAllocContext(); // leave context c2
347 // context c1 active
348 QColor::leaveAllocContext(); // leave context c1
349 // context 0 active
350 // Now, free all colors that were allocated in context c2
351 QColor::destroyAllocContext( c2 );
352 You may also want to set the application's color specification. See
354 QApplication::setColorSpec() for more information.
355 See also leaveAllocContext(), currentAllocContext(),
357 destroyAllocContext(), and QApplication::setColorSpec().
358 Example: showimg/showimg.cpp.
360
362 Returns the current RGB value as HSV. The contents of the h, s and v
363 pointers are set to the HSV values. If any of the three pointers are
364 null, the function does nothing.
365 The hue (which h points to) is set to -1 if the color is achromatic.
367 Warning: Colors are stored internally as RGB values, so getHSv() may
369 return slightly different values to those set by setHsv().
370 See also setHsv() and rgb().
372
374 This function is obsolete. It is provided to keep old source working.
375 We strongly advise against using it in new code.
376
378 Sets the contents pointed to by r, g and b to the red, green and blue
379 components of the RGB value respectively. The value range for a
380 component is 0..255.
381 See also rgb(), setRgb(), and getHsv().
383
385 Returns the G (green) component of the RGB value.
386
388 This function is obsolete. It is provided to keep old source working.
389 We strongly advise against using it in new code. Use getHsv() instead.
390 Example: themes/metal.cpp.
392
394 Internal initialization required for QColor. This function is called
395 from the QApplication constructor.
396 See also cleanup().
398
400 Returns FALSE if the color is invalid, i.e. it was constructed using
401 the default constructor; otherwise returns TRUE.
402 Examples:
404
406 Leaves a color allocation context.
407 See enterAllocContext() for a detailed explanation.
409 See also enterAllocContext() and currentAllocContext().
411 Example: showimg/showimg.cpp.
413
415 Returns a lighter (or darker) color, but does not change this object.
416 Returns a lighter color if factor is greater than 100. Setting factor
418 to 150 returns a color that is 50% brighter.
419 Returns a darker color if factor is less than 100. We recommend using
421 dark() for this purpose. If factor is 0 or negative, the return value
422 is unspecified.
423 (This function converts the current RGB color to HSV, multiplies V by
425 factor, and converts the result back to RGB.)
426 See also dark().
428 Examples:
430
432 Returns the maximum number of colors supported by the underlying window
433 system if the window system uses a palette.
434 Otherwise returns -1. Use numBitPlanes() to calculate the available
436 colors in that case.
437
439 Returns the name of the color in the format "#RRGGBB", i.e. a "#"
440 character followed by three two-digit hexadecimal numbers.
441 See also setNamedColor().
443 Example: chart/setdataform.cpp.
445
447 Returns the number of color bit planes for the underlying window
448 system.
449 The returned value is equal to the default pixmap depth.
451 See also QPixmap::defaultDepth().
453
455 Returns TRUE if this color has a different RGB value from c; otherwise
456 returns FALSE.
457
459 Assigns a copy of the color c and returns a reference to this color.
460
462 Returns TRUE if this color has the same RGB value as c; otherwise
463 returns FALSE.
464
466 Returns the pixel value.
467 This value is used by the underlying window system to refer to a color.
469 It can be thought of as an index into the display hardware's color
470 table, but the value is an arbitrary 32-bit value.
471 See also alloc().
473
475 This is an overloaded member function, provided for convenience. It
476 behaves essentially like the above function.
477 Returns the pixel value for screen screen.
479 This value is used by the underlying window system to refer to a color.
481 It can be thought of as an index into the display hardware's color
482 table, but the value is an arbitrary 32-bit value.
483 See also alloc().
485
487 Returns the R (red) component of the RGB value.
488
490 Returns the RGB value.
491 The return type QRgb is equivalent to unsigned int.
493 For an invalid color, the alpha value of the returned color is
495 unspecified.
496 See also setRgb(), hsv(), qRed(), qBlue(), qGreen(), and isValid().
498
500 This function is obsolete. It is provided to keep old source working.
501 We strongly advise against using it in new code. Use getRgb() instead
502
504 Sets a HSV color value. h is the hue, s is the saturation and v is the
505 value of the HSV color.
506 If s or v are not in the range 0-255, or h is < -1, the color is not
508 changed.
509 Warning: Colors are stored internally as RGB values, so getHSv() may
511 return slightly different values to those set by setHsv().
512 See also hsv() and setRgb().
514 Examples:
516
518 Sets the RGB value to name, which may be in one of these formats:
519 #RGB (each of R, G and B is a single hex digit)
521 #RRGGBB
523 #RRRGGGBBB
525 #RRRRGGGGBBBB
527 A name from the X color database (rgb.txt) (e.g." steelblue" or
529 "gainsboro"). These color names also work under Windows.
530 The color is invalid if name cannot be parsed.
532
534 Sets the RGB value to r, g, b. The arguments, r, g and b must all be in
535 the range 0..255. If any of them are outside the legal range, the color
536 is not changed.
537 See also rgb() and setHsv().
539
541 This is an overloaded member function, provided for convenience. It
542 behaves essentially like the above function.
543 Sets the RGB value to rgb.
545 The type QRgb is equivalent to unsigned int.
547 See also rgb() and setHsv().
549
552 Writes a color object, c to the stream, s.
553 See also Format of the QDataStream operators.
555
557 Reads a color object, c, from the stream, s.
558 See also Format of the QDataStream operators.
560
562 Returns the alpha component of the RGBA quadruplet rgba.
563
565 Returns the blue component of the RGB triplet rgb.
566 See also qRgb() and QColor::blue().
568
570 Returns a gray value 0..255 from the (r, g, b) triplet.
571 The gray value is calculated using the formula (r*11 + g*16 + b*5)/32.
573
575 This is an overloaded member function, provided for convenience. It
576 behaves essentially like the above function.
577 Returns a gray value 0..255 from the given rgb colour.
579
581 Returns the green component of the RGB triplet rgb.
582 See also qRgb() and QColor::green().
584
586 Returns the red component of the RGB triplet rgb.
587 See also qRgb() and QColor::red().
589
591 Returns the RGB triplet (r,g,b).
592 The return type QRgb is equivalent to unsigned int.
594 See also qRgba(), qRed(), qGreen(), and qBlue().
596
598 Returns the RGBA quadruplet (r,g,b,a).
599 The return type QRgba is equivalent to unsigned int.
601 See also qRgb(), qRed(), qGreen(), and qBlue().
603
606 http://doc.trolltech.com/qcolor.html
607 http://www.trolltech.com/faq/tech.html
608
610 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
611 license file included in the distribution for a complete license
612 statement.
613
615 Generated automatically from the source code.
616
618 If you find a bug in Qt, please report it as described in
619 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
620 help you. Thank you.
621 The definitive Qt documentation is provided in HTML format; it is
623 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
624 web browser. This man page is provided as a convenience for those users
625 who prefer man pages, although this format is not officially supported
626 by Trolltech.
627 If you find errors in this manual page, please report them to qt-
629 bugs@trolltech.com. Please include the name of the manual page
630 (qcolor.3qt) and the Qt version (3.3.8).
631Trolltech AS 2 February 2007 QColor(3qt)