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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
|
<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="class-gdkcolor">
<refnamediv>
<refname>gtk.gdk.Color</refname>
<refpurpose>an object holding color information</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<classsynopsis language="python">
<ooclass><classname>gtk.gdk.Color</classname></ooclass>
<ooclass><classname>gobject.GBoxed</classname></ooclass>
<constructorsynopsis language="python">
<methodname><link
linkend="constructor-gdkcolor">gtk.gdk.Color</link></methodname>
<methodparam><parameter
role="keyword">red</parameter>
<initializer>0</initializer></methodparam>
<methodparam><parameter
role="keyword">green</parameter>
<initializer>0</initializer></methodparam>
<methodparam><parameter
role="keyword">blue</parameter>
<initializer>0</initializer></methodparam>
<methodparam><parameter
role="keyword">pixel</parameter>
<initializer>0</initializer></methodparam>
</constructorsynopsis>
<methodsynopsis language="python">
<methodname><link linkend="method-gdkcolor--to-string">to_string</link></methodname>
<methodparam></methodparam>
</methodsynopsis>
</classsynopsis>
<programlisting>
<emphasis role="bold">Functions</emphasis>
<methodsynopsis language="python">
<methodname><link linkend="function-gdk--color-parse">gtk.gdk.color_parse</link></methodname>
<methodparam><parameter role="keyword">spec</parameter></methodparam>
</methodsynopsis><methodsynopsis language="python">
<methodname><link linkend="function-gdk--color-from-hsv">gtk.gdk.color_from_hsv</link></methodname>
<methodparam><parameter role="keyword">hue</parameter></methodparam>
<methodparam><parameter role="keyword">saturation</parameter></methodparam>
<methodparam><parameter role="keyword">value</parameter></methodparam>
</methodsynopsis></programlisting>
</refsect1>
<refsect1>
<title>Attributes</title>
<note>
<para>Floating-point and HSV attributes are available in PyGTK 2.16 and above.</para>
</note>
<blockquote role="properties">
<informaltable pgwide="1" frame="none">
<tgroup cols="3">
<?dbhtml cellpadding="5"?>
<colspec column="1" colwidth="1in"/>
<colspec column="2" colwidth="1in"/>
<colspec column="3" colwidth="4in"/>
<tbody>
<row valign="top">
<entry>"pixel"</entry>
<entry>Read-Write</entry>
<entry>The pixel value of the color</entry>
</row>
<row valign="top">
<entry>"red"</entry>
<entry>Read-Write</entry>
<entry>The value of the red component of the color</entry>
</row>
<row valign="top">
<entry>"green"</entry>
<entry>Read-Write</entry>
<entry>The value of the green component of the color</entry>
</row>
<row valign="top">
<entry>"blue"</entry>
<entry>Read-Write</entry>
<entry>The value of the blue component of the color</entry>
</row>
<row valign="top">
<entry>"red_float"</entry>
<entry>Read-Write</entry>
<entry>The value of the red component of the color as a float in the range 0.0--1.0</entry>
</row>
<row valign="top">
<entry>"green_float"</entry>
<entry>Read-Write</entry>
<entry>The value of the green component of the color as a float in the range 0.0--1.0</entry>
</row>
<row valign="top">
<entry>"blue_float"</entry>
<entry>Read-Write</entry>
<entry>The value of the blue component of the color as a float in the range 0.0--1.0</entry>
</row>
<row valign="top">
<entry>"hue"</entry>
<entry>Read</entry>
<entry>The hue (in HSV colorspace) of the color as a float in the range 0.0--1.0</entry>
</row>
<row valign="top">
<entry>"saturation"</entry>
<entry>Read</entry>
<entry>The saturation (in HSV colorspace) of the color as a float in the range 0.0--1.0</entry>
</row>
<row valign="top">
<entry>"value"</entry>
<entry>Read</entry>
<entry>The value (in HSV colorspace) of the color as a float in the range 0.0--1.0</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</blockquote>
<para>For details on how assignment to <literal>*_float</literal> attributes work,
see <link linkend="constructor-gdkcolor">constructor documentation</link>.</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>A <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>
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 <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>.
Typically a color is allocated by using the <link
linkend="method-gdkcolormap--alloc-color"><methodname>gdk.Colormap.alloc_color</methodname>()</link>
method. Unallocated colors can be used to specify the color attributes of
<link linkend="class-gtkstyle"><classname>gtk.Style</classname></link>
objects since these colors will be allocated when an attempt is made to use
the <link linkend="class-gtkstyle"><classname>gtk.Style</classname></link>
object.</para>
<para>
Starting with PyGTK 2.14 <classname>gtk.gdk.Color</classname> 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 <classname>gtk.gdk.Color</classname> objects using
the constructor.
</para>
<para>
Also beginning with PyGTK 2.14 <classname>gtk.gdk.Color</classname> objects have
custom support for <function>str</function> and <function>repr</function> Python
functions. For any color it holds that:
</para>
<programlisting>
color == eval(repr(color))
</programlisting>
<para>
PyGTK 2.16 introduces several ways of using floating-point numbers for
creating <link linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>
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.
</para>
</refsect1>
<refsect1 id="constructor-gdkcolor">
<title>Constructor</title>
<programlisting><constructorsynopsis language="python">
<methodname>gtk.gdk.Color</methodname>
<methodparam><parameter
role="keyword">red</parameter>
<initializer>0</initializer></methodparam>
<methodparam><parameter
role="keyword">green</parameter>
<initializer>0</initializer></methodparam>
<methodparam><parameter
role="keyword">blue</parameter>
<initializer>0</initializer></methodparam>
<methodparam><parameter
role="keyword">pixel</parameter>
<initializer>0</initializer></methodparam>
</constructorsynopsis></programlisting>
<programlisting><constructorsynopsis language="python">
<methodname>gtk.gdk.Color</methodname>
<methodparam><parameter
role="keyword">spec</parameter></methodparam>
</constructorsynopsis></programlisting>
<variablelist>
<varlistentry>
<term><parameter role="keyword">red</parameter> :</term>
<listitem><simpara>The red color component in the range
0-65535</simpara></listitem>
</varlistentry>
<varlistentry>
<term><parameter role="keyword">green</parameter> :</term>
<listitem><simpara>The green color component in the range
0-65535</simpara></listitem>
</varlistentry>
<varlistentry>
<term><parameter role="keyword">blue</parameter> :</term>
<listitem><simpara>The blue color component in the range
0-65535</simpara></listitem>
</varlistentry>
<varlistentry>
<term><parameter role="keyword">pixel</parameter> :</term>
<listitem><simpara>The index of the color when allocated in its
colormap</simpara></listitem>
</varlistentry>
<varlistentry>
<term><parameter role="keyword">spec</parameter> :</term>
<listitem><simpara>String containing color specification</simpara></listitem>
</varlistentry>
<varlistentry>
<term><emphasis>Returns</emphasis> :</term>
<listitem><simpara>a new <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>
object</simpara></listitem>
</varlistentry>
</variablelist>
<note>
<para>Second form of the constructor is available in PyGTK 2.14 and above.</para>
</note>
<note>
<para><parameter>red</parameter>, <parameter>green</parameter>
and <parameter>blue</parameter> can be floating-point numbers since PyGTK
2.16.</para>
</note>
<para>Creates a new <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link> object
with the color component values specified by <parameter>red</parameter>,
<parameter>green</parameter> and <parameter>blue</parameter> (all default to
0) and using the pixel value specified by <parameter>pixel</parameter>. The
value of <parameter>pixel</parameter> will be overwritten when the color is
allocated.</para>
<para>Second form of the constructor is analogous to
<link linkend="function-gdk--color-parse"><function>gtk.gdk.color_parse</function></link>.</para>
<para>Starting with PyGTK 2.16, <parameter>red</parameter>, <parameter>green</parameter> and
<parameter>blue</parameter> 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.</para>
<para>Note that internally values are still stored as integers, so values of
corresponding <literal>*_float</literal> 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 <classname>GdkColor</classname>
though.</para>
<para>All of the following expressions create a bright green color:</para>
<programlisting>
gtk.gdk.Color(0, 65535, 0)
gtk.gdk.Color(green=1.0)
gtk.gdk.Color('#0f0')
</programlisting>
</refsect1>
<refsect1>
<title>Methods</title>
<refsect2 id="method-gdkcolor--to-string">
<title>gtk.gdk.Color.to_string</title>
<programlisting><methodsynopsis language="python">
<methodname>to_string</methodname>
<methodparam></methodparam>
</methodsynopsis></programlisting>
<variablelist>
<varlistentry>
<term><emphasis>Returns</emphasis> :</term>
<listitem><simpara>a string</simpara></listitem>
</varlistentry>
</variablelist>
<note>
<para>This method is available in PyGTK 2.12 and above.</para>
</note>
<para>
The <methodname>to_string</methodname>() 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.
</para>
<note>
<para>Starting with PyGTK 2.14 you can also
use <literal>str(color)</literal> code. However, that can return a
shorter (3, 6 or 12 hexadecimal digits) string if shorter version means
the same for the constructor.</para>
</note>
</refsect2>
</refsect1>
<refsect1>
<title>Functions</title>
<refsect2 id="function-gdk--color-parse">
<title>gtk.gdk.color_parse</title>
<programlisting><methodsynopsis language="python">
<methodname>gtk.gdk.color_parse</methodname>
<methodparam><parameter role="keyword">spec</parameter></methodparam>
</methodsynopsis></programlisting>
<variablelist>
<varlistentry>
<term><parameter role="keyword">spec</parameter> :</term>
<listitem><simpara>a string containing a color
specification</simpara></listitem>
</varlistentry>
<varlistentry>
<term><emphasis>Returns</emphasis> :</term>
<listitem><simpara>a <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>
object</simpara></listitem>
</varlistentry>
</variablelist>
<para>The <function>gtk.gdk.color_parse</function>() method returns
the <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>
specified by <parameter>spec</parameter>. The format of
<parameter>spec</parameter> is a string containing the specification of the
color either as a name (e.g. "navajowhite") as specified in the X11
<filename>rgb.txt</filename> 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 <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link> is
<emphasis>not</emphasis> allocated.</para>
<para>This function raise the ValueError (TypeError prior to PyGTK
2.4) exception if unable to parse the color specification</para>
</refsect2>
<refsect2 id="function-gdk--color-from-hsv">
<title>gtk.gdk.color_from_hsv</title>
<programlisting><methodsynopsis language="python">
<methodname>gtk.gdk.color_from_hsv</methodname>
<methodparam><parameter role="keyword">hue</parameter></methodparam>
<methodparam><parameter role="keyword">saturation</parameter></methodparam>
<methodparam><parameter role="keyword">value</parameter></methodparam>
</methodsynopsis></programlisting>
<variablelist>
<varlistentry>
<term><parameter role="keyword">hue</parameter> :</term>
<listitem><simpara>Hue of the desired color as a float in range
0.0--1.0</simpara></listitem>
</varlistentry>
<varlistentry>
<term><parameter role="keyword">saturation</parameter> :</term>
<listitem><simpara>Saturation of the desired color as a float in range
0.0--1.0</simpara></listitem>
</varlistentry>
<varlistentry>
<term><parameter role="keyword">value</parameter> :</term>
<listitem><simpara>Value of the desired color as a float in range
0.0--1.0</simpara></listitem>
</varlistentry>
<varlistentry>
<term><emphasis>Returns</emphasis> :</term>
<listitem><simpara>a <link linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>
object</simpara></listitem>
</varlistentry>
</variablelist>
<note>
<para>This function is available in PyGTK 2.16 and above.</para>
</note>
<para>The <function>gtk.gdk.color_from_hsv</function>() method returns
the <link linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>
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.</para>
<para>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).</para>
<para>Note that internal storage is still integers, so values of
corresponding <literal>hue</literal>, <literal>saturation</literal>
and <literal>value</literal> 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 <classname>GdkColor</classname> though.</para>
<para>For more details read about <ulink url="http://en.wikipedia.org/wiki/HSL_and_HSV">HSV
colorspace</ulink>.</para>
</refsect2>
</refsect1>
</refentry>
|
