1QColor(3qt)                                                        QColor(3qt)
2
3
4

NAME

6       QColor - Colors based on RGB or HSV values
7

SYNOPSIS

9       #include <qcolor.h>
10
11   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
44   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

DESCRIPTION

68       The QColor class provides colors based on RGB or HSV values.
69
70       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
75       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
80       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
86       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
91       <center>
92                                   [Image Omitted]
93
94       </center>
95
96       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
101       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
108       <ol type=1>
109
110       1      Is the pixel value valid? If it is, just return it; otherwise,
111              allocate a pixel value.
112
113       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
117       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
121       4      The color could not be allocated. Find the closest matching
122              color, save it in the internal table, and return it.
123
124       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
132       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
136       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

HSV Colors

141       Because many people don't know the HSV color model very well, we'll
142       cover it briefly here.
143
144       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
150       HSV, like RGB, has three components:
151
152       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
157       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
161       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
164       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
169       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
173       See also QPalette, QColorGroup, QApplication::setColorSpec(), Color
174       FAQ, Widget Appearance and Style, Graphics Classes, and Image
175       Processing Classes.
176
177   Member Type Documentation

QColor::Spec

179       The type of color specified, either RGB or HSV, e.g. in the
180       QColor::QColor( x, y, z, colorSpec) constructor.
181
182       QColor::Rgb
183
184       QColor::Hsv
185

MEMBER FUNCTION DOCUMENTATION

QColor::QColor ()

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
192       The alpha value of an invalid color is unspecified.
193
194       See also isValid().
195

QColor::QColor ( int r, int g, int b )

197       Constructs a color with the RGB value r, g, b, in the same way as
198       setRgb().
199
200       The color is left invalid if any or the arguments are illegal.
201
202       See also setRgb().
203

QColor::QColor ( int x, int y, int z, Spec colorSpec )

205       Constructs a color with the RGB or HSV value x, y, z.
206
207       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
210       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
214       See also setRgb() and setHsv().
215

QColor::QColor ( QRgb rgb, uint pixel = 0xffffffff )

217       Constructs a color with the RGB value rgb and a custom pixel value
218       pixel.
219
220       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

QColor::QColor ( const QString & name )

225       Constructs a named color in the same way as setNamedColor() using name
226       name.
227
228       The color is left invalid if name cannot be parsed.
229
230       See also setNamedColor().
231

QColor::QColor ( const char * name )

233       Constructs a named color in the same way as setNamedColor() using name
234       name.
235
236       The color is left invalid if name cannot be parsed.
237
238       See also setNamedColor().
239

QColor::QColor ( const QColor & c )

241       Constructs a color that is a copy of c.
242

uint QColor::alloc ()

244       Allocates the RGB color and returns the pixel value.
245
246       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
250       The pixel() function calls alloc() if necessary, so in general you
251       don't need to call this function.
252
253       See also enterAllocContext().
254

int QColor::blue () const

256       Returns the B (blue) component of the RGB value.
257

void QColor::cleanup () [static]

259       Internal clean up required for QColor. This function is called from the
260       QApplication destructor.
261
262       See also initialize().
263

QStringList QColor::colorNames () [static]

265       Returns a QStringList containing the color names Qt knows about.
266

int QColor::currentAllocContext () [static]

268       Returns the current color allocation context.
269
270       The default context is 0.
271
272       See also enterAllocContext() and leaveAllocContext().
273

QColor QColor::dark ( int factor = 200 ) const

275       Returns a darker (or lighter) color, but does not change this object.
276
277       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
280       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
284       (This function converts the current RGB color to HSV, divides V by
285       factor and converts back to RGB.)
286
287       See also light().
288
289       Examples:
290

void QColor::destroyAllocContext ( int context ) [static]

292       Destroys a color allocation context, context.
293
294       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
300       The function does nothing for true color displays.
301
302       See also enterAllocContext() and alloc().
303
304       Example: showimg/showimg.cpp.
305

int QColor::enterAllocContext () [static]

307       Enters a color allocation context and returns a non-zero unique
308       identifier.
309
310       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
316       Example:
317
318           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
329       The example code loads a pixmap from file. It frees up all colors that
330       were allocated the last time loadPixmap() was called.
331
332       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
336       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
341               // 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
353       You may also want to set the application's color specification. See
354       QApplication::setColorSpec() for more information.
355
356       See also leaveAllocContext(), currentAllocContext(),
357       destroyAllocContext(), and QApplication::setColorSpec().
358
359       Example: showimg/showimg.cpp.
360

void QColor::getHsv ( int * h, int * s, int * v ) const

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
366       The hue (which h points to) is set to -1 if the color is achromatic.
367
368       Warning: Colors are stored internally as RGB values, so getHSv() may
369       return slightly different values to those set by setHsv().
370
371       See also setHsv() and rgb().
372

void QColor::getHsv ( int & h, int & s, int & v ) const

374       This function is obsolete. It is provided to keep old source working.
375       We strongly advise against using it in new code.
376

void QColor::getRgb ( int * r, int * g, int * b ) const

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
382       See also rgb(), setRgb(), and getHsv().
383

int QColor::green () const

385       Returns the G (green) component of the RGB value.
386

void QColor::hsv ( int * h, int * s, int * v ) const

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
391       Example: themes/metal.cpp.
392

void QColor::initialize () [static]

394       Internal initialization required for QColor. This function is called
395       from the QApplication constructor.
396
397       See also cleanup().
398

bool QColor::isValid () const

400       Returns FALSE if the color is invalid, i.e. it was constructed using
401       the default constructor; otherwise returns TRUE.
402
403       Examples:
404

void QColor::leaveAllocContext () [static]

406       Leaves a color allocation context.
407
408       See enterAllocContext() for a detailed explanation.
409
410       See also enterAllocContext() and currentAllocContext().
411
412       Example: showimg/showimg.cpp.
413

QColor QColor::light ( int factor = 150 ) const

415       Returns a lighter (or darker) color, but does not change this object.
416
417       Returns a lighter color if factor is greater than 100. Setting factor
418       to 150 returns a color that is 50% brighter.
419
420       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
424       (This function converts the current RGB color to HSV, multiplies V by
425       factor, and converts the result back to RGB.)
426
427       See also dark().
428
429       Examples:
430

int QColor::maxColors () [static]

432       Returns the maximum number of colors supported by the underlying window
433       system if the window system uses a palette.
434
435       Otherwise returns -1. Use numBitPlanes() to calculate the available
436       colors in that case.
437

QString QColor::name () const

439       Returns the name of the color in the format "#RRGGBB", i.e. a "#"
440       character followed by three two-digit hexadecimal numbers.
441
442       See also setNamedColor().
443
444       Example: chart/setdataform.cpp.
445

int QColor::numBitPlanes () [static]

447       Returns the number of color bit planes for the underlying window
448       system.
449
450       The returned value is equal to the default pixmap depth.
451
452       See also QPixmap::defaultDepth().
453

bool QColor::operator!= ( const QColor & c ) const

455       Returns TRUE if this color has a different RGB value from c; otherwise
456       returns FALSE.
457

QColor & QColor::operator= ( const QColor & c )

459       Assigns a copy of the color c and returns a reference to this color.
460

bool QColor::operator== ( const QColor & c ) const

462       Returns TRUE if this color has the same RGB value as c; otherwise
463       returns FALSE.
464

uint QColor::pixel () const

466       Returns the pixel value.
467
468       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
472       See also alloc().
473

uint QColor::pixel ( int screen ) const

475       This is an overloaded member function, provided for convenience. It
476       behaves essentially like the above function.
477
478       Returns the pixel value for screen screen.
479
480       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
484       See also alloc().
485

int QColor::red () const

487       Returns the R (red) component of the RGB value.
488

QRgb QColor::rgb () const

490       Returns the RGB value.
491
492       The return type QRgb is equivalent to unsigned int.
493
494       For an invalid color, the alpha value of the returned color is
495       unspecified.
496
497       See also setRgb(), hsv(), qRed(), qBlue(), qGreen(), and isValid().
498

void QColor::rgb ( int * r, int * g, int * b ) const

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

void QColor::setHsv ( int h, int s, int v )

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
507       If s or v are not in the range 0-255, or h is < -1, the color is not
508       changed.
509
510       Warning: Colors are stored internally as RGB values, so getHSv() may
511       return slightly different values to those set by setHsv().
512
513       See also hsv() and setRgb().
514
515       Examples:
516

void QColor::setNamedColor ( const QString & name )

518       Sets the RGB value to name, which may be in one of these formats:
519
520       #RGB (each of R, G and B is a single hex digit)
521
522       #RRGGBB
523
524       #RRRGGGBBB
525
526       #RRRRGGGGBBBB
527
528       A name from the X color database (rgb.txt) (e.g." steelblue" or
529       "gainsboro"). These color names also work under Windows.
530
531       The color is invalid if name cannot be parsed.
532

void QColor::setRgb ( int r, int g, int b )

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
538       See also rgb() and setHsv().
539

void QColor::setRgb ( QRgb rgb )

541       This is an overloaded member function, provided for convenience. It
542       behaves essentially like the above function.
543
544       Sets the RGB value to rgb.
545
546       The type QRgb is equivalent to unsigned int.
547
548       See also rgb() and setHsv().
549

QDataStream & operator<< ( QDataStream & s, const QColor & c )

552       Writes a color object, c to the stream, s.
553
554       See also Format of the QDataStream operators.
555

QDataStream & operator>> ( QDataStream & s, QColor & c )

557       Reads a color object, c, from the stream, s.
558
559       See also Format of the QDataStream operators.
560

int qAlpha ( QRgb rgba )

562       Returns the alpha component of the RGBA quadruplet rgba.
563

int qBlue ( QRgb rgb )

565       Returns the blue component of the RGB triplet rgb.
566
567       See also qRgb() and QColor::blue().
568

int qGray ( int r, int g, int b )

570       Returns a gray value 0..255 from the (r, g, b) triplet.
571
572       The gray value is calculated using the formula (r*11 + g*16 + b*5)/32.
573

int qGray ( qRgb rgb )

575       This is an overloaded member function, provided for convenience. It
576       behaves essentially like the above function.
577
578       Returns a gray value 0..255 from the given rgb colour.
579

int qGreen ( QRgb rgb )

581       Returns the green component of the RGB triplet rgb.
582
583       See also qRgb() and QColor::green().
584

int qRed ( QRgb rgb )

586       Returns the red component of the RGB triplet rgb.
587
588       See also qRgb() and QColor::red().
589

QRgb qRgb ( int r, int g, int b )

591       Returns the RGB triplet (r,g,b).
592
593       The return type QRgb is equivalent to unsigned int.
594
595       See also qRgba(), qRed(), qGreen(), and qBlue().
596

QRgb qRgba ( int r, int g, int b, int a )

598       Returns the RGBA quadruplet (r,g,b,a).
599
600       The return type QRgba is equivalent to unsigned int.
601
602       See also qRgb(), qRed(), qGreen(), and qBlue().
603
604

SEE ALSO

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

AUTHOR

615       Generated automatically from the source code.
616

BUGS

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
622       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
628       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).
631
632
633
634Trolltech AS                    2 February 2007                    QColor(3qt)
Impressum