1
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
5
<title>Colormaps and Colors</title>
6
<meta name="generator" content="DocBook XSL Stylesheets V1.72.0">
7
<link rel="start" href="index.html" title="GDK Reference Manual">
8
<link rel="up" href="reference.html" title="API Reference">
9
<link rel="prev" href="gdk-Pixbufs.html" title="Pixbufs">
10
<link rel="next" href="gdk-Visuals.html" title="Visuals">
11
<meta name="generator" content="GTK-Doc V1.7 (XML mode)">
12
<link rel="stylesheet" href="style.css" type="text/css">
13
<link rel="reference" href="reference.html" title="API Reference">
14
<link rel="index" href="ix01.html" title="Index">
15
<link rel="index" href="ix02.html" title="Index of deprecated symbols">
16
<link rel="index" href="ix03.html" title="Index of new symbols in 2.2">
17
<link rel="index" href="ix04.html" title="Index of new symbols in 2.4">
18
<link rel="index" href="ix05.html" title="Index of new symbols in 2.6">
19
<link rel="index" href="ix06.html" title="Index of new symbols in 2.8">
20
<link rel="index" href="ix07.html" title="Index of new symbols in 2.10">
22
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
23
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
25
<td><a accesskey="p" href="gdk-Pixbufs.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
26
<td><a accesskey="u" href="reference.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
27
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
28
<th width="100%" align="center">GDK Reference Manual</th>
29
<td><a accesskey="n" href="gdk-Visuals.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
31
<tr><td colspan="5" class="shortcuts"><nobr><a href="#id2660088" class="shortcut">Top</a>
33
<a href="#id2660882" class="shortcut">Description</a></nobr></td></tr>
35
<div class="refentry" lang="en">
36
<a name="gdk-Colormaps-and-Colors"></a><div class="titlepage"></div>
37
<div class="refnamediv"><table width="100%"><tr>
40
<a name="id2660088"></a><span class="refentrytitle">Colormaps and Colors</span>
42
<p>Colormaps and Colors — Manipulation of colors and colormaps</p>
44
<td valign="top" align="right"></td>
46
<div class="refsynopsisdiv">
48
<pre class="synopsis">
50
#include <gdk/gdk.h>
53
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a>;
54
<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a>;
55
<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a>* <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-new">gdk_colormap_new</a> (<a href="gdk-Visuals.html#GdkVisual">GdkVisual</a> *visual,
57
<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a>* <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-ref">gdk_colormap_ref</a> (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *cmap);
58
void <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-unref">gdk_colormap_unref</a> (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *cmap);
59
<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a>* <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-get-system">gdk_colormap_get_system</a> (void);
60
gint <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-get-system-size">gdk_colormap_get_system_size</a> (void);
61
void <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-change">gdk_colormap_change</a> (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
63
gint <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-alloc-colors">gdk_colormap_alloc_colors</a> (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
64
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *colors,
69
gboolean <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-alloc-color">gdk_colormap_alloc_color</a> (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
70
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *color,
73
void <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-free-colors">gdk_colormap_free_colors</a> (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
74
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *colors,
76
void <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-query-color">gdk_colormap_query_color</a> (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
78
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *result);
79
<a href="gdk-Visuals.html#GdkVisual">GdkVisual</a>* <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-get-visual">gdk_colormap_get_visual</a> (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap);
80
<a href="GdkScreen.html" title="GdkScreen">GdkScreen</a>* <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-get-screen">gdk_colormap_get_screen</a> (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *cmap);
81
void <a href="gdk-Colormaps-and-Colors.html#gdk-colors-store">gdk_colors_store</a> (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
82
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *colors,
84
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a>* <a href="gdk-Colormaps-and-Colors.html#gdk-color-copy">gdk_color_copy</a> (const <a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *color);
85
void <a href="gdk-Colormaps-and-Colors.html#gdk-color-free">gdk_color_free</a> (<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *color);
86
gint <a href="gdk-Colormaps-and-Colors.html#gdk-colors-alloc">gdk_colors_alloc</a> (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
92
void <a href="gdk-Colormaps-and-Colors.html#gdk-colors-free">gdk_colors_free</a> (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
96
gint <a href="gdk-Colormaps-and-Colors.html#gdk-color-white">gdk_color_white</a> (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
97
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *color);
98
gint <a href="gdk-Colormaps-and-Colors.html#gdk-color-black">gdk_color_black</a> (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
99
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *color);
100
gboolean <a href="gdk-Colormaps-and-Colors.html#gdk-color-parse">gdk_color_parse</a> (const gchar *spec,
101
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *color);
102
gint <a href="gdk-Colormaps-and-Colors.html#gdk-color-alloc">gdk_color_alloc</a> (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
103
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *color);
104
gint <a href="gdk-Colormaps-and-Colors.html#gdk-color-change">gdk_color_change</a> (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
105
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *color);
106
gboolean <a href="gdk-Colormaps-and-Colors.html#gdk-color-equal">gdk_color_equal</a> (const <a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *colora,
107
const <a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *colorb);
108
guint <a href="gdk-Colormaps-and-Colors.html#gdk-color-hash">gdk_color_hash</a> (const <a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *colora);
113
<div class="refsect1" lang="en">
114
<a name="id2660882"></a><h2>Description</h2>
116
These functions are used to modify colormaps.
117
A colormap is an object that contains the mapping
118
between the color values stored in memory and
119
the RGB values that are used to display color
120
values. In general, colormaps only contain
121
significant information for pseudo-color visuals,
122
but even for other visual types, a colormap object
123
is required in some circumstances.
126
There are a couple of special colormaps that can
127
be retrieved. The system colormap (retrieved
128
with <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-get-system"><code class="function">gdk_colormap_get_system()</code></a>) is the default
129
colormap of the system. If you are using GdkRGB,
130
there is another colormap that is important - the
131
colormap in which GdkRGB works, retrieved with
132
<a href="gdk-GdkRGB.html#gdk-rgb-get-cmap"><code class="function">gdk_rgb_get_cmap()</code></a>. However, when using GdkRGB,
133
it is not generally necessary to allocate colors
137
In previous revisions of this interface, a number
138
of functions that take a <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a> parameter
139
were replaced with functions whose names began
140
with "gdk_colormap_". This process will probably
141
be extended somewhat in the future -
142
<a href="gdk-Colormaps-and-Colors.html#gdk-color-white"><code class="function">gdk_color_white()</code></a>, <a href="gdk-Colormaps-and-Colors.html#gdk-color-black"><code class="function">gdk_color_black()</code></a>, and
143
<a href="gdk-Colormaps-and-Colors.html#gdk-color-change"><code class="function">gdk_color_change()</code></a> will probably become aliases.
146
<div class="refsect1" lang="en">
147
<a name="id2660980"></a><h2>Details</h2>
148
<div class="refsect2" lang="en">
149
<a name="id2660991"></a><h3>
150
<a name="GdkColor"></a>GdkColor</h3>
151
<a class="indexterm" name="id2661003"></a><pre class="programlisting">typedef struct {
159
The <a href="gdk-Colormaps-and-Colors.html#GdkColor"><span class="type">GdkColor</span></a> structure is used to describe an
160
allocated or unallocated color.
162
<div class="variablelist"><table border="0">
163
<col align="left" valign="top">
166
<td><span class="term">guint32 <em class="structfield"><code>pixel</code></em>;</span></td>
167
<td>For allocated colors, the value used to
168
draw this color on the screen.
172
<td><span class="term">guint16 <em class="structfield"><code>red</code></em>;</span></td>
173
<td>The red component of the color. This is
174
a value between 0 and 65535, with 65535 indicating
179
<td><span class="term">guint16 <em class="structfield"><code>green</code></em>;</span></td>
180
<td>The blue component of the color.
184
<td><span class="term">guint16 <em class="structfield"><code>blue</code></em>;</span></td>
185
<td>The green component of the color.
193
<div class="refsect2" lang="en">
194
<a name="id2661117"></a><h3>
195
<a name="GdkColormap"></a>GdkColormap</h3>
196
<a class="indexterm" name="id2661129"></a><pre class="programlisting">typedef struct {
202
The colormap structure contains the following public fields.
204
<div class="variablelist"><table border="0">
205
<col align="left" valign="top">
208
<td><span class="term">gint <em class="structfield"><code>size</code></em>;</span></td>
209
<td>For pseudo-color colormaps, the number of colors
214
<td><span class="term"><a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *<em class="structfield"><code>colors</code></em>;</span></td>
215
<td>An array containing the current values in the
216
colormap. This can be used to map from pixel values
217
back to RGB values. This is only meaningful for
218
pseudo-color colormaps.
226
<div class="refsect2" lang="en">
227
<a name="id2661195"></a><h3>
228
<a name="gdk-colormap-new"></a>gdk_colormap_new ()</h3>
229
<a class="indexterm" name="id2661208"></a><pre class="programlisting"><a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a>* gdk_colormap_new (<a href="gdk-Visuals.html#GdkVisual">GdkVisual</a> *visual,
230
gboolean allocate);</pre>
232
Creates a new colormap for the given visual.</p>
235
<div class="variablelist"><table border="0">
236
<col align="left" valign="top">
239
<td><span class="term"><em class="parameter"><code>visual</code></em> :</span></td>
240
<td> a <a href="gdk-Visuals.html#GdkVisual"><span class="type">GdkVisual</span></a>.
244
<td><span class="term"><em class="parameter"><code>allocate</code></em> :</span></td>
245
<td> if <code class="literal">TRUE</code>, the newly created colormap will be
246
a private colormap, and all colors in it will be
247
allocated for the applications use.
251
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
252
<td> the new <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a>.
259
<div class="refsect2" lang="en">
260
<a name="id2661318"></a><h3>
261
<a name="gdk-colormap-ref"></a>gdk_colormap_ref ()</h3>
262
<a class="indexterm" name="id2661333"></a><pre class="programlisting"><a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a>* gdk_colormap_ref (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *cmap);</pre>
263
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
264
<h3 class="title">Warning</h3>
265
<p><code class="literal">gdk_colormap_ref</code> is deprecated and should not be used in newly-written code.</p>
268
Deprecated function; use <code class="function">g_object_ref()</code> instead.</p>
272
<div class="variablelist"><table border="0">
273
<col align="left" valign="top">
276
<td><span class="term"><em class="parameter"><code>cmap</code></em> :</span></td>
277
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a>
281
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
289
<div class="refsect2" lang="en">
290
<a name="id2661424"></a><h3>
291
<a name="gdk-colormap-unref"></a>gdk_colormap_unref ()</h3>
292
<a class="indexterm" name="id2661440"></a><pre class="programlisting">void gdk_colormap_unref (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *cmap);</pre>
293
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
294
<h3 class="title">Warning</h3>
295
<p><code class="literal">gdk_colormap_unref</code> is deprecated and should not be used in newly-written code.</p>
298
Deprecated function; use <code class="function">g_object_ref()</code> instead.</p>
302
<div class="variablelist"><table border="0">
303
<col align="left" valign="top">
305
<td><span class="term"><em class="parameter"><code>cmap</code></em> :</span></td>
306
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a>
312
<div class="refsect2" lang="en">
313
<a name="id2661520"></a><h3>
314
<a name="gdk-colormap-get-system"></a>gdk_colormap_get_system ()</h3>
315
<a class="indexterm" name="id2661534"></a><pre class="programlisting"><a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a>* gdk_colormap_get_system (void);</pre>
317
Gets the system's default colormap for the default screen. (See
318
<code class="function">gdk_colormap_get_system_for_screen()</code>)</p>
321
<div class="variablelist"><table border="0">
322
<col align="left" valign="top">
324
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
325
<td> the default colormap.
331
<div class="refsect2" lang="en">
332
<a name="id2661588"></a><h3>
333
<a name="gdk-colormap-get-system-size"></a>gdk_colormap_get_system_size ()</h3>
334
<a class="indexterm" name="id2661603"></a><pre class="programlisting">gint gdk_colormap_get_system_size (void);</pre>
335
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
336
<h3 class="title">Warning</h3>
337
<p><code class="literal">gdk_colormap_get_system_size</code> is deprecated and should not be used in newly-written code.</p>
340
Returns the size of the system's default colormap.
341
(See the description of struct <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a> for an
342
explanation of the size of a colormap.)</p>
345
<div class="variablelist"><table border="0">
346
<col align="left" valign="top">
348
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
349
<td> the size of the system's default colormap.
355
<div class="refsect2" lang="en">
356
<a name="id2661666"></a><h3>
357
<a name="gdk-colormap-change"></a>gdk_colormap_change ()</h3>
358
<a class="indexterm" name="id2661681"></a><pre class="programlisting">void gdk_colormap_change (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
360
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
361
<h3 class="title">Warning</h3>
362
<p><code class="literal">gdk_colormap_change</code> is deprecated and should not be used in newly-written code.</p>
365
Changes the value of the first <em class="parameter"><code>ncolors</code></em> in a private colormap
366
to match the values in the <em class="structfield"><code>colors</code></em>
367
array in the colormap. This function is obsolete and
368
should not be used. See <a href="gdk-Colormaps-and-Colors.html#gdk-color-change"><code class="function">gdk_color_change()</code></a>.</p>
371
<div class="variablelist"><table border="0">
372
<col align="left" valign="top">
375
<td><span class="term"><em class="parameter"><code>colormap</code></em> :</span></td>
376
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a>.
380
<td><span class="term"><em class="parameter"><code>ncolors</code></em> :</span></td>
381
<td> the number of colors to change.
388
<div class="refsect2" lang="en">
389
<a name="id2661795"></a><h3>
390
<a name="gdk-colormap-alloc-colors"></a>gdk_colormap_alloc_colors ()</h3>
391
<a class="indexterm" name="id2661809"></a><pre class="programlisting">gint gdk_colormap_alloc_colors (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
392
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *colors,
396
gboolean *success);</pre>
398
Allocates colors from a colormap.</p>
401
<div class="variablelist"><table border="0">
402
<col align="left" valign="top">
405
<td><span class="term"><em class="parameter"><code>colormap</code></em> :</span></td>
406
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a>.
410
<td><span class="term"><em class="parameter"><code>colors</code></em> :</span></td>
411
<td> The color values to allocate. On return, the pixel
412
values for allocated colors will be filled in.
416
<td><span class="term"><em class="parameter"><code>ncolors</code></em> :</span></td>
417
<td> The number of colors in <em class="parameter"><code>colors</code></em>.
421
<td><span class="term"><em class="parameter"><code>writeable</code></em> :</span></td>
422
<td> If <code class="literal">TRUE</code>, the colors are allocated writeable
423
(their values can later be changed using <a href="gdk-Colormaps-and-Colors.html#gdk-color-change"><code class="function">gdk_color_change()</code></a>).
424
Writeable colors cannot be shared between applications.
428
<td><span class="term"><em class="parameter"><code>best_match</code></em> :</span></td>
429
<td> If <code class="literal">TRUE</code>, GDK will attempt to do matching against
430
existing colors if the colors cannot be allocated as requested.
434
<td><span class="term"><em class="parameter"><code>success</code></em> :</span></td>
435
<td> An array of length <em class="parameter"><code>ncolors</code></em>. On return, this
436
indicates whether the corresponding color in <em class="parameter"><code>colors</code></em> was
437
successfully allocated or not.
441
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
442
<td> The number of colors that were not successfully
450
<div class="refsect2" lang="en">
451
<a name="id2662043"></a><h3>
452
<a name="gdk-colormap-alloc-color"></a>gdk_colormap_alloc_color ()</h3>
453
<a class="indexterm" name="id2662056"></a><pre class="programlisting">gboolean gdk_colormap_alloc_color (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
454
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *color,
456
gboolean best_match);</pre>
458
Allocates a single color from a colormap.</p>
461
<div class="variablelist"><table border="0">
462
<col align="left" valign="top">
465
<td><span class="term"><em class="parameter"><code>colormap</code></em> :</span></td>
466
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a>.
470
<td><span class="term"><em class="parameter"><code>color</code></em> :</span></td>
471
<td> the color to allocate. On return the
472
<em class="structfield"><code>pixel</code></em> field will be
473
filled in if allocation succeeds.
477
<td><span class="term"><em class="parameter"><code>writeable</code></em> :</span></td>
478
<td> If <code class="literal">TRUE</code>, the color is allocated writeable
479
(their values can later be changed using <a href="gdk-Colormaps-and-Colors.html#gdk-color-change"><code class="function">gdk_color_change()</code></a>).
480
Writeable colors cannot be shared between applications.
484
<td><span class="term"><em class="parameter"><code>best_match</code></em> :</span></td>
485
<td> If <code class="literal">TRUE</code>, GDK will attempt to do matching against
486
existing colors if the color cannot be allocated as requested.
490
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
491
<td> <code class="literal">TRUE</code> if the allocation succeeded.
498
<div class="refsect2" lang="en">
499
<a name="id2662240"></a><h3>
500
<a name="gdk-colormap-free-colors"></a>gdk_colormap_free_colors ()</h3>
501
<a class="indexterm" name="id2662253"></a><pre class="programlisting">void gdk_colormap_free_colors (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
502
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *colors,
505
Frees previously allocated colors.</p>
508
<div class="variablelist"><table border="0">
509
<col align="left" valign="top">
512
<td><span class="term"><em class="parameter"><code>colormap</code></em> :</span></td>
513
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a>.
517
<td><span class="term"><em class="parameter"><code>colors</code></em> :</span></td>
518
<td> the colors to free.
522
<td><span class="term"><em class="parameter"><code>ncolors</code></em> :</span></td>
523
<td> the number of colors in <em class="parameter"><code>colors</code></em>.
530
<div class="refsect2" lang="en">
531
<a name="id2662360"></a><h3>
532
<a name="gdk-colormap-query-color"></a>gdk_colormap_query_color ()</h3>
533
<a class="indexterm" name="id2662373"></a><pre class="programlisting">void gdk_colormap_query_color (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
535
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *result);</pre>
537
Locates the RGB color in <em class="parameter"><code>colormap</code></em> corresponding to the given
538
hardware pixel <em class="parameter"><code>pixel</code></em>. <em class="parameter"><code>pixel</code></em> must be a valid pixel in the
539
colormap; it's a programmer error to call this function with a
540
pixel which is not in the colormap. Hardware pixels are normally
541
obtained from <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-alloc-colors"><code class="function">gdk_colormap_alloc_colors()</code></a>, or from a <a href="gdk-Images.html#GdkImage"><span class="type">GdkImage</span></a>. (A
542
<a href="gdk-Images.html#GdkImage"><span class="type">GdkImage</span></a> contains image data in hardware format, a <a
543
href="../gdk-pixbuf/gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf"
544
><span class="type">GdkPixbuf</span></a>
545
contains image data in a canonical 24-bit RGB format.)
548
This function is rarely useful; it's used for example to
549
implement the eyedropper feature in <span class="type">GtkColorSelection</span>.</p>
553
<div class="variablelist"><table border="0">
554
<col align="left" valign="top">
557
<td><span class="term"><em class="parameter"><code>colormap</code></em> :</span></td>
558
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a>
562
<td><span class="term"><em class="parameter"><code>pixel</code></em> :</span></td>
563
<td> pixel value in hardware display format
567
<td><span class="term"><em class="parameter"><code>result</code></em> :</span></td>
568
<td> <a href="gdk-Colormaps-and-Colors.html#GdkColor"><span class="type">GdkColor</span></a> with red, green, blue fields initialized
575
<div class="refsect2" lang="en">
576
<a name="id2662555"></a><h3>
577
<a name="gdk-colormap-get-visual"></a>gdk_colormap_get_visual ()</h3>
578
<a class="indexterm" name="id2662569"></a><pre class="programlisting"><a href="gdk-Visuals.html#GdkVisual">GdkVisual</a>* gdk_colormap_get_visual (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap);</pre>
580
Returns the visual for which a given colormap was created.</p>
583
<div class="variablelist"><table border="0">
584
<col align="left" valign="top">
587
<td><span class="term"><em class="parameter"><code>colormap</code></em> :</span></td>
588
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a>.
592
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
593
<td> the visual of the colormap.
600
<div class="refsect2" lang="en">
601
<a name="id2662638"></a><h3>
602
<a name="gdk-colormap-get-screen"></a>gdk_colormap_get_screen ()</h3>
603
<a class="indexterm" name="id2662653"></a><pre class="programlisting"><a href="GdkScreen.html" title="GdkScreen">GdkScreen</a>* gdk_colormap_get_screen (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *cmap);</pre>
605
Gets the screen for which this colormap was created.</p>
609
<div class="variablelist"><table border="0">
610
<col align="left" valign="top">
613
<td><span class="term"><em class="parameter"><code>cmap</code></em> :</span></td>
614
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a>
618
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
619
<td> the screen for which this colormap was created.
625
<p class="since">Since 2.2
629
<div class="refsect2" lang="en">
630
<a name="id2662729"></a><h3>
631
<a name="gdk-colors-store"></a>gdk_colors_store ()</h3>
632
<a class="indexterm" name="id2662744"></a><pre class="programlisting">void gdk_colors_store (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
633
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *colors,
635
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
636
<h3 class="title">Warning</h3>
637
<p><code class="literal">gdk_colors_store</code> is deprecated and should not be used in newly-written code.</p>
640
Changes the value of the first <em class="parameter"><code>ncolors</code></em> colors in
641
a private colormap. This function is obsolete and
642
should not be used. See <a href="gdk-Colormaps-and-Colors.html#gdk-color-change"><code class="function">gdk_color_change()</code></a>.</p>
645
<div class="variablelist"><table border="0">
646
<col align="left" valign="top">
649
<td><span class="term"><em class="parameter"><code>colormap</code></em> :</span></td>
650
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a>.
654
<td><span class="term"><em class="parameter"><code>colors</code></em> :</span></td>
655
<td> the new color values.
659
<td><span class="term"><em class="parameter"><code>ncolors</code></em> :</span></td>
660
<td> the number of colors to change.
667
<div class="refsect2" lang="en">
668
<a name="id2662876"></a><h3>
669
<a name="gdk-color-copy"></a>gdk_color_copy ()</h3>
670
<a class="indexterm" name="id2662888"></a><pre class="programlisting"><a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a>* gdk_color_copy (const <a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *color);</pre>
672
Makes a copy of a color structure. The result
673
must be freed using <a href="gdk-Colormaps-and-Colors.html#gdk-color-free"><code class="function">gdk_color_free()</code></a>.</p>
676
<div class="variablelist"><table border="0">
677
<col align="left" valign="top">
680
<td><span class="term"><em class="parameter"><code>color</code></em> :</span></td>
681
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColor"><span class="type">GdkColor</span></a>.
685
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
686
<td> a copy of <em class="parameter"><code>color</code></em>.
693
<div class="refsect2" lang="en">
694
<a name="id2662973"></a><h3>
695
<a name="gdk-color-free"></a>gdk_color_free ()</h3>
696
<a class="indexterm" name="id2662986"></a><pre class="programlisting">void gdk_color_free (<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *color);</pre>
698
Frees a color structure created with
699
<a href="gdk-Colormaps-and-Colors.html#gdk-color-copy"><code class="function">gdk_color_copy()</code></a>.</p>
702
<div class="variablelist"><table border="0">
703
<col align="left" valign="top">
705
<td><span class="term"><em class="parameter"><code>color</code></em> :</span></td>
706
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColor"><span class="type">GdkColor</span></a>.
712
<div class="refsect2" lang="en">
713
<a name="id2663054"></a><h3>
714
<a name="gdk-colors-alloc"></a>gdk_colors_alloc ()</h3>
715
<a class="indexterm" name="id2663069"></a><pre class="programlisting">gint gdk_colors_alloc (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
721
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
722
<h3 class="title">Warning</h3>
723
<p><code class="literal">gdk_colors_alloc</code> is deprecated and should not be used in newly-written code.</p>
726
Allocates colors from a colormap. This function
727
is obsolete. See <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-alloc-colors"><code class="function">gdk_colormap_alloc_colors()</code></a>.
728
For full documentation of the fields, see
729
the Xlib documentation for <code class="function"><code class="function">XAllocColorCells()</code></code>.</p>
732
<div class="variablelist"><table border="0">
733
<col align="left" valign="top">
736
<td><span class="term"><em class="parameter"><code>colormap</code></em> :</span></td>
737
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a>.
741
<td><span class="term"><em class="parameter"><code>contiguous</code></em> :</span></td>
742
<td> if <code class="literal">TRUE</code>, the colors should be allocated
743
in contiguous color cells.
747
<td><span class="term"><em class="parameter"><code>planes</code></em> :</span></td>
748
<td> an array in which to store the plane masks.
752
<td><span class="term"><em class="parameter"><code>nplanes</code></em> :</span></td>
753
<td> the number of planes to allocate. (Or zero,
754
to indicate that the color allocation should not be planar.)
758
<td><span class="term"><em class="parameter"><code>pixels</code></em> :</span></td>
759
<td> an array into which to store allocated pixel values.
763
<td><span class="term"><em class="parameter"><code>npixels</code></em> :</span></td>
764
<td> the number of pixels in each plane to allocate.
768
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
769
<td> <code class="literal">TRUE</code> if the allocation was successful
776
<div class="refsect2" lang="en">
777
<a name="id2663312"></a><h3>
778
<a name="gdk-colors-free"></a>gdk_colors_free ()</h3>
779
<a class="indexterm" name="id2663327"></a><pre class="programlisting">void gdk_colors_free (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
782
gulong planes);</pre>
783
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
784
<h3 class="title">Warning</h3>
785
<p><code class="literal">gdk_colors_free</code> is deprecated and should not be used in newly-written code.</p>
788
Frees colors allocated with <a href="gdk-Colormaps-and-Colors.html#gdk-colors-alloc"><code class="function">gdk_colors_alloc()</code></a>. This
789
function is obsolete. See <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-free-colors"><code class="function">gdk_colormap_free_colors()</code></a>.</p>
792
<div class="variablelist"><table border="0">
793
<col align="left" valign="top">
796
<td><span class="term"><em class="parameter"><code>colormap</code></em> :</span></td>
797
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a>.
801
<td><span class="term"><em class="parameter"><code>pixels</code></em> :</span></td>
802
<td> the pixel values of the colors to free.
806
<td><span class="term"><em class="parameter"><code>npixels</code></em> :</span></td>
807
<td> the number of values in <em class="parameter"><code>pixels</code></em>.
811
<td><span class="term"><em class="parameter"><code>planes</code></em> :</span></td>
812
<td> the plane masks for all planes to free, OR'd together.
819
<div class="refsect2" lang="en">
820
<a name="id2663491"></a><h3>
821
<a name="gdk-color-white"></a>gdk_color_white ()</h3>
822
<a class="indexterm" name="id2663506"></a><pre class="programlisting">gint gdk_color_white (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
823
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *color);</pre>
824
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
825
<h3 class="title">Warning</h3>
826
<p><code class="literal">gdk_color_white</code> is deprecated and should not be used in newly-written code.</p>
829
Returns the white color for a given colormap. The resulting
830
value has already allocated been allocated.</p>
833
<div class="variablelist"><table border="0">
834
<col align="left" valign="top">
837
<td><span class="term"><em class="parameter"><code>colormap</code></em> :</span></td>
838
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a>.
842
<td><span class="term"><em class="parameter"><code>color</code></em> :</span></td>
843
<td> the location to store the color.
847
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
848
<td> <code class="literal">TRUE</code> if the allocation succeeded.
855
<div class="refsect2" lang="en">
856
<a name="id2663621"></a><h3>
857
<a name="gdk-color-black"></a>gdk_color_black ()</h3>
858
<a class="indexterm" name="id2663636"></a><pre class="programlisting">gint gdk_color_black (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
859
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *color);</pre>
860
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
861
<h3 class="title">Warning</h3>
862
<p><code class="literal">gdk_color_black</code> is deprecated and should not be used in newly-written code.</p>
865
Returns the black color for a given colormap. The resulting
866
value has already benn allocated.</p>
869
<div class="variablelist"><table border="0">
870
<col align="left" valign="top">
873
<td><span class="term"><em class="parameter"><code>colormap</code></em> :</span></td>
874
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a>.
878
<td><span class="term"><em class="parameter"><code>color</code></em> :</span></td>
879
<td> the location to store the color.
883
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
884
<td> <code class="literal">TRUE</code> if the allocation succeeded.
891
<div class="refsect2" lang="en">
892
<a name="id2663750"></a><h3>
893
<a name="gdk-color-parse"></a>gdk_color_parse ()</h3>
894
<a class="indexterm" name="id2663763"></a><pre class="programlisting">gboolean gdk_color_parse (const gchar *spec,
895
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *color);</pre>
897
Parses a textual specification of a color and fill in
898
the <em class="structfield"><code>red</code></em>,
899
<em class="structfield"><code>green</code></em>, and
900
<em class="structfield"><code>blue</code></em> fields of a
901
<a href="gdk-Colormaps-and-Colors.html#GdkColor"><span class="type">GdkColor</span></a> structure. The color is <span class="emphasis"><em>not</em></span>
902
allocated, you must call <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-alloc-color"><code class="function">gdk_colormap_alloc_color()</code></a> yourself.
903
The text string can be in any of the forms accepted
904
by <code class="function">XParseColor</code>; these include
905
name for a color from <code class="filename">rgb.txt</code>, such as
906
<code class="literal">DarkSlateGray</code>, or a hex specification
907
such as <code class="literal">#3050b2</code> or <code class="literal">#35b</code>.</p>
910
<div class="variablelist"><table border="0">
911
<col align="left" valign="top">
914
<td><span class="term"><em class="parameter"><code>spec</code></em> :</span></td>
915
<td> the string specifying the color.
919
<td><span class="term"><em class="parameter"><code>color</code></em> :</span></td>
920
<td> the <a href="gdk-Colormaps-and-Colors.html#GdkColor"><span class="type">GdkColor</span></a> to fill in
924
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
925
<td> <code class="literal">TRUE</code> if the parsing succeeded.
932
<div class="refsect2" lang="en">
933
<a name="id2663930"></a><h3>
934
<a name="gdk-color-alloc"></a>gdk_color_alloc ()</h3>
935
<a class="indexterm" name="id2663946"></a><pre class="programlisting">gint gdk_color_alloc (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
936
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *color);</pre>
937
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
938
<h3 class="title">Warning</h3>
939
<p><code class="literal">gdk_color_alloc</code> is deprecated and should not be used in newly-written code. Use <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-alloc-color"><code class="function">gdk_colormap_alloc_color()</code></a> instead.</p>
942
Allocates a single color from a colormap.</p>
945
<div class="variablelist"><table border="0">
946
<col align="left" valign="top">
949
<td><span class="term"><em class="parameter"><code>colormap</code></em> :</span></td>
950
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a>.
954
<td><span class="term"><em class="parameter"><code>color</code></em> :</span></td>
955
<td> The color to allocate. On return, the
956
<em class="structfield"><code>pixel</code></em> field will be filled in.
960
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
961
<td> <code class="literal">TRUE</code> if the allocation succeeded.
969
<div class="refsect2" lang="en">
970
<a name="id2664074"></a><h3>
971
<a name="gdk-color-change"></a>gdk_color_change ()</h3>
972
<a class="indexterm" name="id2664089"></a><pre class="programlisting">gint gdk_color_change (<a href="gdk-Colormaps-and-Colors.html#GdkColormap">GdkColormap</a> *colormap,
973
<a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *color);</pre>
974
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
975
<h3 class="title">Warning</h3>
976
<p><code class="literal">gdk_color_change</code> is deprecated and should not be used in newly-written code.</p>
979
Changes the value of a color that has already
980
been allocated. If <em class="parameter"><code>colormap</code></em> is not a private
981
colormap, then the color must have been allocated
982
using <a href="gdk-Colormaps-and-Colors.html#gdk-colormap-alloc-colors"><code class="function">gdk_colormap_alloc_colors()</code></a> with the
983
<em class="parameter"><code>writeable</code></em> set to <code class="literal">TRUE</code>.</p>
986
<div class="variablelist"><table border="0">
987
<col align="left" valign="top">
990
<td><span class="term"><em class="parameter"><code>colormap</code></em> :</span></td>
991
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColormap"><span class="type">GdkColormap</span></a>.
995
<td><span class="term"><em class="parameter"><code>color</code></em> :</span></td>
996
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColor"><span class="type">GdkColor</span></a>, with the color to change
997
in the <em class="structfield"><code>pixel</code></em> field,
998
and the new value in the remaining fields.
1002
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
1003
<td> <code class="literal">TRUE</code> if the color was successfully changed.
1010
<div class="refsect2" lang="en">
1011
<a name="id2664250"></a><h3>
1012
<a name="gdk-color-equal"></a>gdk_color_equal ()</h3>
1013
<a class="indexterm" name="id2664262"></a><pre class="programlisting">gboolean gdk_color_equal (const <a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *colora,
1014
const <a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *colorb);</pre>
1016
Compares two colors.</p>
1019
<div class="variablelist"><table border="0">
1020
<col align="left" valign="top">
1023
<td><span class="term"><em class="parameter"><code>colora</code></em> :</span></td>
1024
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColor"><span class="type">GdkColor</span></a>.
1028
<td><span class="term"><em class="parameter"><code>colorb</code></em> :</span></td>
1029
<td> another <a href="gdk-Colormaps-and-Colors.html#GdkColor"><span class="type">GdkColor</span></a>.
1033
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
1034
<td> <code class="literal">TRUE</code> if the two colors compare equal
1041
<div class="refsect2" lang="en">
1042
<a name="id2664370"></a><h3>
1043
<a name="gdk-color-hash"></a>gdk_color_hash ()</h3>
1044
<a class="indexterm" name="id2664383"></a><pre class="programlisting">guint gdk_color_hash (const <a href="gdk-Colormaps-and-Colors.html#GdkColor">GdkColor</a> *colora);</pre>
1046
A hash function suitable for using for a hash
1047
table that stores <a href="gdk-Colormaps-and-Colors.html#GdkColor"><span class="type">GdkColor</span></a>'s.</p>
1050
<div class="variablelist"><table border="0">
1051
<col align="left" valign="top">
1054
<td><span class="term"><em class="parameter"><code>colora</code></em> :</span></td>
1055
<td> a <a href="gdk-Colormaps-and-Colors.html#GdkColor"><span class="type">GdkColor</span></a>.
1059
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
1060
<td> The hash function appled to <em class="parameter"><code>colora</code></em>