1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>gtk.gdk.Color</title><link rel="stylesheet" href="style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="PyGTK 2.0 Reference Manual"><link rel="up" href="gdk-class-reference.html" title="The gtk.gdk Class Reference"><link rel="prev" href="class-gdkcairocontext.html" title="gtk.gdk.CairoContext"><link rel="next" href="class-gdkcolormap.html" title="gtk.gdk.Colormap"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">gtk.gdk.Color</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="class-gdkcairocontext.html">Prev</a> </td><th width="60%" align="center">The gtk.gdk Class Reference</th><td width="20%" align="right"> <a accesskey="n" href="class-gdkcolormap.html">Next</a></td></tr></table><hr></div><div class="refentry" title="gtk.gdk.Color"><a name="class-gdkcolor"></a><div class="titlepage"></div><div class="refnamediv"><h2>gtk.gdk.Color</h2><p>gtk.gdk.Color — an object holding color information</p></div><div class="refsect1" title="Synopsis"><a name="id3469250"></a><h2>Synopsis</h2><table bgcolor="#D0E0F0" width="100%"><tr><td><pre class="classsynopsis">class <span class="ooclass"><span class="classname">gtk.gdk.Color</span></span>(<span class="ooclass"><span class="classname">gobject.GBoxed</span></span>):
<code class="constructorsynopsis"> <span class="methodname"><a class="link" href="class-gdkcolor.html#constructor-gdkcolor" title="Constructor">gtk.gdk.Color</a></span>(<span class="methodparam"><span class="parameter"><strong class="parameter"><code>red</code></strong></span><span class="initializer">=0</span></span>, <span class="methodparam"><span class="parameter"><strong class="parameter"><code>green</code></strong></span><span class="initializer">=0</span></span>, <span class="methodparam"><span class="parameter"><strong class="parameter"><code>blue</code></strong></span><span class="initializer">=0</span></span>, <span class="methodparam"><span class="parameter"><strong class="parameter"><code>pixel</code></strong></span><span class="initializer">=0</span></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a class="link" href="class-gdkcolor.html#method-gdkcolor--to-string" title="gtk.gdk.Color.to_string">to_string</a></span>(<span class="methodparam"></span>)</code><br></pre></td></tr></table><pre class="programlisting">
<span class="bold"><strong>Functions</strong></span>
<code class="methodsynopsis"> def <span class="methodname"><a class="link" href="class-gdkcolor.html#function-gdk--color-parse" title="gtk.gdk.color_parse">gtk.gdk.color_parse</a></span>(<span class="methodparam"><span class="parameter"><strong class="parameter"><code>spec</code></strong></span></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a class="link" href="class-gdkcolor.html#function-gdk--color-from-hsv" title="gtk.gdk.color_from_hsv">gtk.gdk.color_from_hsv</a></span>(<span class="methodparam"><span class="parameter"><strong class="parameter"><code>hue</code></strong></span></span>, <span class="methodparam"><span class="parameter"><strong class="parameter"><code>saturation</code></strong></span></span>, <span class="methodparam"><span class="parameter"><strong class="parameter"><code>value</code></strong></span></span>)</code></pre></div><div class="refsect1" title="Attributes"><a name="id3469065"></a><h2>Attributes</h2><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Floating-point and HSV attributes are available in PyGTK 2.16 and above.</p></div><div class="blockquote"><table width="100%" border="0" bgcolor="#E0E0E0"><tr><td valign="top"><div class="informaltable"><table cellpadding="5" width="100%" border="0"><colgroup><col width="1in"><col width="1in"><col width="4in"></colgroup><tbody><tr valign="top"><td valign="top">"pixel"</td><td valign="top">Read-Write</td><td valign="top">The pixel value of the color</td></tr><tr valign="top"><td valign="top">"red"</td><td valign="top">Read-Write</td><td valign="top">The value of the red component of the color</td></tr><tr valign="top"><td valign="top">"green"</td><td valign="top">Read-Write</td><td valign="top">The value of the green component of the color</td></tr><tr valign="top"><td valign="top">"blue"</td><td valign="top">Read-Write</td><td valign="top">The value of the blue component of the color</td></tr><tr valign="top"><td valign="top">"red_float"</td><td valign="top">Read-Write</td><td valign="top">The value of the red component of the color as a float in the range 0.0--1.0</td></tr><tr valign="top"><td valign="top">"green_float"</td><td valign="top">Read-Write</td><td valign="top">The value of the green component of the color as a float in the range 0.0--1.0</td></tr><tr valign="top"><td valign="top">"blue_float"</td><td valign="top">Read-Write</td><td valign="top">The value of the blue component of the color as a float in the range 0.0--1.0</td></tr><tr valign="top"><td valign="top">"hue"</td><td valign="top">Read</td><td valign="top">The hue (in HSV colorspace) of the color as a float in the range 0.0--1.0</td></tr><tr valign="top"><td valign="top">"saturation"</td><td valign="top">Read</td><td valign="top">The saturation (in HSV colorspace) of the color as a float in the range 0.0--1.0</td></tr><tr valign="top"><td valign="top">"value"</td><td valign="top">Read</td><td valign="top">The value (in HSV colorspace) of the color as a float in the range 0.0--1.0</td></tr></tbody></table></div></td></tr></table></div><p>For details on how assignment to <code class="literal">*_float</code> attributes work,
see <a class="link" href="class-gdkcolor.html#constructor-gdkcolor" title="Constructor">constructor documentation</a>.</p></div><div class="refsect1" title="Description"><a name="id3459601"></a><h2>Description</h2><p>A <a class="link" href="class-gdkcolor.html" title="gtk.gdk.Color"><code class="classname">gtk.gdk.Color</code></a>
contains the values of a color that may or may not be allocated. The red,
green and blue attributes are specified by an unsigned integer in the range
0-65535. The pixel value is an index into the colormap that has allocated
the <a class="link" href="class-gdkcolor.html" title="gtk.gdk.Color"><code class="classname">gtk.gdk.Color</code></a>.
Typically a color is allocated by using the <a class="link" href="class-gdkcolormap.html#method-gdkcolormap--alloc-color" title="gtk.gdk.Colormap.alloc_color"><code class="methodname">gdk.Colormap.alloc_color</code>()</a>
method. Unallocated colors can be used to specify the color attributes of
<a class="link" href="class-gtkstyle.html" title="gtk.Style"><code class="classname">gtk.Style</code></a>
objects since these colors will be allocated when an attempt is made to use
the <a class="link" href="class-gtkstyle.html" title="gtk.Style"><code class="classname">gtk.Style</code></a>
object.</p><p>
Starting with PyGTK 2.14 <code class="classname">gtk.gdk.Color</code> objects are properly
comparable. By Python rules, colors (being mutable) are now unhashable. If you
need to use them as dictionary keys, use string representation instead. You can
convert string representation to <code class="classname">gtk.gdk.Color</code> objects using
the constructor.
</p><p>
Also beginning with PyGTK 2.14 <code class="classname">gtk.gdk.Color</code> objects have
custom support for <code class="function">str</code> and <code class="function">repr</code> Python
functions. For any color it holds that:
</p><pre class="programlisting">
color == eval(repr(color))
</pre><p>
PyGTK 2.16 introduces several ways of using floating-point numbers for
creating <a class="link" href="class-gdkcolor.html" title="gtk.gdk.Color"><code class="classname">gtk.gdk.Color</code></a>
objects or setting their individual components. In all cases it was decided to
silently clamp input values to valid range, rather than being strict and e.g. raise
an exception. The rationale is that floating-point arithmetics are imprecise, so
you could end with a computed value slightly larger than maximum or a little smaller
than minimum valid value. To simplify using new features, such "slightly off"
values are just clamped without any warning.
</p></div><div class="refsect1" title="Constructor"><a name="constructor-gdkcolor"></a><h2>Constructor</h2><pre class="programlisting"><code class="constructorsynopsis"> <span class="methodname">gtk.gdk.Color</span>(<span class="methodparam"><span class="parameter"><strong class="parameter"><code>red</code></strong></span><span class="initializer">=0</span></span>, <span class="methodparam"><span class="parameter"><strong class="parameter"><code>green</code></strong></span><span class="initializer">=0</span></span>, <span class="methodparam"><span class="parameter"><strong class="parameter"><code>blue</code></strong></span><span class="initializer">=0</span></span>, <span class="methodparam"><span class="parameter"><strong class="parameter"><code>pixel</code></strong></span><span class="initializer">=0</span></span>)</code></pre><pre class="programlisting"><code class="constructorsynopsis"> <span class="methodname">gtk.gdk.Color</span>(<span class="methodparam"><span class="parameter"><strong class="parameter"><code>spec</code></strong></span></span>)</code></pre><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><p><span class="term"><strong class="parameter"><code>red</code></strong> :</span></p></td><td>The red color component in the range
0-65535</td></tr><tr><td><p><span class="term"><strong class="parameter"><code>green</code></strong> :</span></p></td><td>The green color component in the range
0-65535</td></tr><tr><td><p><span class="term"><strong class="parameter"><code>blue</code></strong> :</span></p></td><td>The blue color component in the range
0-65535</td></tr><tr><td><p><span class="term"><strong class="parameter"><code>pixel</code></strong> :</span></p></td><td>The index of the color when allocated in its
colormap</td></tr><tr><td><p><span class="term"><strong class="parameter"><code>spec</code></strong> :</span></p></td><td>String containing color specification</td></tr><tr><td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td><td>a new <a class="link" href="class-gdkcolor.html" title="gtk.gdk.Color"><code class="classname">gtk.gdk.Color</code></a>
object</td></tr></tbody></table><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Second form of the constructor is available in PyGTK 2.14 and above.</p></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p><em class="parameter"><code>red</code></em>, <em class="parameter"><code>green</code></em>
and <em class="parameter"><code>blue</code></em> can be floating-point numbers since PyGTK
2.16.</p></div><p>Creates a new <a class="link" href="class-gdkcolor.html" title="gtk.gdk.Color"><code class="classname">gtk.gdk.Color</code></a> object
with the color component values specified by <em class="parameter"><code>red</code></em>,
<em class="parameter"><code>green</code></em> and <em class="parameter"><code>blue</code></em> (all default to
0) and using the pixel value specified by <em class="parameter"><code>pixel</code></em>. The
value of <em class="parameter"><code>pixel</code></em> will be overwritten when the color is
allocated.</p><p>Second form of the constructor is analogous to
<a class="link" href="class-gdkcolor.html#function-gdk--color-parse" title="gtk.gdk.color_parse"><code class="function">gtk.gdk.color_parse</code></a>.</p><p>Starting with PyGTK 2.16, <em class="parameter"><code>red</code></em>, <em class="parameter"><code>green</code></em> and
<em class="parameter"><code>blue</code></em> parameters can also be floating-point numbers in the
range 0.0--1.0. Either all specified values must be integers or floats -- mixing is
not allowed as this would be too error-prone. Values outside the valid range
0.0--1.0 are clamped, so e.g. 3.14 is the same as 1.0.</p><p>Note that internally values are still stored as integers, so values of
corresponding <code class="literal">*_float</code> attribute will not necessarily be the same
as the value used as argument for the constructor. They will be as close as
permitted by 16-bit color component storage used by <code class="classname">GdkColor</code>
though.</p><p>All of the following expressions create a bright green color:</p><pre class="programlisting">
gtk.gdk.Color(0, 65535, 0)
gtk.gdk.Color(green=1.0)
gtk.gdk.Color('#0f0')
</pre></div><div class="refsect1" title="Methods"><a name="id3251841"></a><h2>Methods</h2><div class="refsect2" title="gtk.gdk.Color.to_string"><a name="method-gdkcolor--to-string"></a><h3>gtk.gdk.Color.to_string</h3><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">to_string</span>(<span class="methodparam"></span>)</code></pre><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td><td>a string</td></tr></tbody></table><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This method is available in PyGTK 2.12 and above.</p></div><p>
The <code class="methodname">to_string</code>() method returns a textual
specification of color in the hexadecimal form #rrrrggggbbbb,
where r, g and b are hex digits representing the red,
green and blue components respectively.
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Starting with PyGTK 2.14 you can also
use <code class="literal">str(color)</code> code. However, that can return a
shorter (3, 6 or 12 hexadecimal digits) string if shorter version means
the same for the constructor.</p></div></div></div><div class="refsect1" title="Functions"><a name="id3251754"></a><h2>Functions</h2><div class="refsect2" title="gtk.gdk.color_parse"><a name="function-gdk--color-parse"></a><h3>gtk.gdk.color_parse</h3><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">gtk.gdk.color_parse</span>(<span class="methodparam"><span class="parameter"><strong class="parameter"><code>spec</code></strong></span></span>)</code></pre><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><p><span class="term"><strong class="parameter"><code>spec</code></strong> :</span></p></td><td>a string containing a color
specification</td></tr><tr><td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td><td>a <a class="link" href="class-gdkcolor.html" title="gtk.gdk.Color"><code class="classname">gtk.gdk.Color</code></a>
object</td></tr></tbody></table><p>The <code class="function">gtk.gdk.color_parse</code>() method returns
the <a class="link" href="class-gdkcolor.html" title="gtk.gdk.Color"><code class="classname">gtk.gdk.Color</code></a>
specified by <em class="parameter"><code>spec</code></em>. The format of
<em class="parameter"><code>spec</code></em> is a string containing the specification of the
color either as a name (e.g. "navajowhite") as specified in the X11
<code class="filename">rgb.txt</code> file or as a hexadecimal string (e.g.
"#FF0078"). The hexadecimal string must start with '#' and must contain 3
sets of hexadecimal digits of the same length (i.e. 1, 2 ,3 or 4 digits).
For example the following specify the same color value: "#F0A", "#FF00AA",
"#FFF000AAA" and "#FFFF0000AAAA". The <a class="link" href="class-gdkcolor.html" title="gtk.gdk.Color"><code class="classname">gtk.gdk.Color</code></a> is
<span class="emphasis"><em>not</em></span> allocated.</p><p>This function raise the ValueError (TypeError prior to PyGTK
2.4) exception if unable to parse the color specification</p></div><div class="refsect2" title="gtk.gdk.color_from_hsv"><a name="function-gdk--color-from-hsv"></a><h3>gtk.gdk.color_from_hsv</h3><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">gtk.gdk.color_from_hsv</span>(<span class="methodparam"><span class="parameter"><strong class="parameter"><code>hue</code></strong></span></span>, <span class="methodparam"><span class="parameter"><strong class="parameter"><code>saturation</code></strong></span></span>, <span class="methodparam"><span class="parameter"><strong class="parameter"><code>value</code></strong></span></span>)</code></pre><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><p><span class="term"><strong class="parameter"><code>hue</code></strong> :</span></p></td><td>Hue of the desired color as a float in range
0.0--1.0</td></tr><tr><td><p><span class="term"><strong class="parameter"><code>saturation</code></strong> :</span></p></td><td>Saturation of the desired color as a float in range
0.0--1.0</td></tr><tr><td><p><span class="term"><strong class="parameter"><code>value</code></strong> :</span></p></td><td>Value of the desired color as a float in range
0.0--1.0</td></tr><tr><td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td><td>a <a class="link" href="class-gdkcolor.html" title="gtk.gdk.Color"><code class="classname">gtk.gdk.Color</code></a>
object</td></tr></tbody></table><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This function is available in PyGTK 2.16 and above.</p></div><p>The <code class="function">gtk.gdk.color_from_hsv</code>() method returns
the <a class="link" href="class-gdkcolor.html" title="gtk.gdk.Color"><code class="classname">gtk.gdk.Color</code></a>
specified by the HSV parameters. All three parameters are mandatory and should be
floats from 0.0 to 1.0. The range requirement, however, is not strict, see
below.</p><p>As hue goes from 0 to 1 color goes roughly as red → yellow → green → cyan →
blue → magenta → red. Because of the "circular" nature, this parameter wraps
around, so only fractional part matters. E.g. -4.2 or 1.8 are the same as 0.8.
Saturation determines how intense a color is, with 0.0 meaning pure gray and 1.0
-- fully intense color. Value determines how light a color is, with 0.0 standing
for fully black and 1.0 for completely white color. Both saturation and value are
clamped to valid range (see rationale at the top of the page).</p><p>Note that internal storage is still integers, so values of
corresponding <code class="literal">hue</code>, <code class="literal">saturation</code>
and <code class="literal">value</code> attributes of the returned object will not
necessarily be equal to the value used as argument for this functions. They will
be as close as permitted by 16-bit color component storage used
by <code class="classname">GdkColor</code> though.</p><p>For more details read about <a class="ulink" href="http://en.wikipedia.org/wiki/HSL_and_HSV" target="_top">HSV
colorspace</a>.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="class-gdkcairocontext.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="gdk-class-reference.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="class-gdkcolormap.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">gtk.gdk.CairoContext </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> gtk.gdk.Colormap</td></tr></table></div></body></html>
|
