|
|
|
GDK Reference Manual | |
|---|---|---|---|---|
#include <gdk/gdk.h>
GdkColor;
GdkColormap;
GdkColormap* gdk_colormap_new (GdkVisual *visual,
gboolean allocate);
GdkColormap* gdk_colormap_ref (GdkColormap *cmap);
void gdk_colormap_unref (GdkColormap *cmap);
GdkColormap* gdk_colormap_get_system (void);
gint gdk_colormap_get_system_size (void);
void gdk_colormap_change (GdkColormap *colormap,
gint ncolors);
gint gdk_colormap_alloc_colors (GdkColormap *colormap,
GdkColor *colors,
gint ncolors,
gboolean writeable,
gboolean best_match,
gboolean *success);
gboolean gdk_colormap_alloc_color (GdkColormap *colormap,
GdkColor *color,
gboolean writeable,
gboolean best_match);
void gdk_colormap_free_colors (GdkColormap *colormap,
GdkColor *colors,
gint ncolors);
void gdk_colormap_query_color (GdkColormap *colormap,
gulong pixel,
GdkColor *result);
GdkVisual* gdk_colormap_get_visual (GdkColormap *colormap);
GdkScreen* gdk_colormap_get_screen (GdkColormap *cmap);
void gdk_colors_store (GdkColormap *colormap,
GdkColor *colors,
gint ncolors);
GdkColor* gdk_color_copy (const GdkColor *color);
void gdk_color_free (GdkColor *color);
gint gdk_colors_alloc (GdkColormap *colormap,
gboolean contiguous,
gulong *planes,
gint nplanes,
gulong *pixels,
gint npixels);
void gdk_colors_free (GdkColormap *colormap,
gulong *pixels,
gint npixels,
gulong planes);
gint gdk_color_white (GdkColormap *colormap,
GdkColor *color);
gint gdk_color_black (GdkColormap *colormap,
GdkColor *color);
gboolean gdk_color_parse (const gchar *spec,
GdkColor *color);
gint gdk_color_alloc (GdkColormap *colormap,
GdkColor *color);
gint gdk_color_change (GdkColormap *colormap,
GdkColor *color);
gboolean gdk_color_equal (const GdkColor *colora,
const GdkColor *colorb);
guint gdk_color_hash (const GdkColor *colora);
gchar* gdk_color_to_string (const GdkColor *color);
These functions are used to modify colormaps. A colormap is an object that contains the mapping between the color values stored in memory and the RGB values that are used to display color values. In general, colormaps only contain significant information for pseudo-color visuals, but even for other visual types, a colormap object is required in some circumstances.
There are a couple of special colormaps that can
be retrieved. The system colormap (retrieved
with gdk_colormap_get_system()) is the default
colormap of the system. If you are using GdkRGB,
there is another colormap that is important - the
colormap in which GdkRGB works, retrieved with
gdk_rgb_get_colormap(). However, when using GdkRGB,
it is not generally necessary to allocate colors
directly.
In previous revisions of this interface, a number
of functions that take a GdkColormap parameter
were replaced with functions whose names began
with "gdk_colormap_". This process will probably
be extended somewhat in the future -
gdk_color_white(), gdk_color_black(), and
gdk_color_change() will probably become aliases.
typedef struct {
guint32 pixel;
guint16 red;
guint16 green;
guint16 blue;
} GdkColor;
The GdkColor structure is used to describe an allocated or unallocated color.
guint32 pixel; |
For allocated colors, the value used to draw this color on the screen. |
guint16 red; |
The red component of the color. This is a value between 0 and 65535, with 65535 indicating full intensitiy. |
guint16 green; |
The blue component of the color. |
guint16 blue; |
The green component of the color. |
typedef struct {
gint size;
GdkColor *colors;
} GdkColormap;
The colormap structure contains the following public fields.
GdkColormap* gdk_colormap_new (GdkVisual *visual, gboolean allocate);
Creates a new colormap for the given visual.
visual : |
a GdkVisual. |
allocate : |
if TRUE, the newly created colormap will be
a private colormap, and all colors in it will be
allocated for the applications use.
|
| Returns : | the new GdkColormap. |
GdkColormap* gdk_colormap_ref (GdkColormap *cmap);
gdk_colormap_ref is deprecated and should not be used in newly-written code.
Deprecated function; use g_object_ref() instead.
cmap : |
a GdkColormap |
| Returns : | the colormap |
void gdk_colormap_unref (GdkColormap *cmap);
gdk_colormap_unref is deprecated and should not be used in newly-written code.
Deprecated function; use g_object_ref() instead.
cmap : |
a GdkColormap |
GdkColormap* gdk_colormap_get_system (void);
Gets the system's default colormap for the default screen. (See
gdk_colormap_get_system_for_screen())
| Returns : | the default colormap. |
gint gdk_colormap_get_system_size (void);
gdk_colormap_get_system_size is deprecated and should not be used in newly-written code.
Returns the size of the system's default colormap. (See the description of struct GdkColormap for an explanation of the size of a colormap.)
| Returns : | the size of the system's default colormap. |
void gdk_colormap_change (GdkColormap *colormap, gint ncolors);
gdk_colormap_change is deprecated and should not be used in newly-written code.
Changes the value of the first ncolors in a private colormap
to match the values in the colors
array in the colormap. This function is obsolete and
should not be used. See gdk_color_change().
colormap : |
a GdkColormap. |
ncolors : |
the number of colors to change. |
gint gdk_colormap_alloc_colors (GdkColormap *colormap, GdkColor *colors, gint ncolors, gboolean writeable, gboolean best_match, gboolean *success);
Allocates colors from a colormap.
colormap : |
a GdkColormap. |
colors : |
The color values to allocate. On return, the pixel values for allocated colors will be filled in. |
ncolors : |
The number of colors in colors.
|
writeable : |
If TRUE, the colors are allocated writeable
(their values can later be changed using gdk_color_change()).
Writeable colors cannot be shared between applications.
|
best_match : |
If TRUE, GDK will attempt to do matching against
existing colors if the colors cannot be allocated as requested.
|
success : |
An array of length ncolors. On return, this
indicates whether the corresponding color in colors was
successfully allocated or not.
|
| Returns : | The number of colors that were not successfully allocated. |
gboolean gdk_colormap_alloc_color (GdkColormap *colormap, GdkColor *color, gboolean writeable, gboolean best_match);
Allocates a single color from a colormap.
colormap : |
a GdkColormap. |
color : |
the color to allocate. On return the
pixel field will be
filled in if allocation succeeds.
|
writeable : |
If TRUE, the color is allocated writeable
(their values can later be changed using gdk_color_change()).
Writeable colors cannot be shared between applications.
|
best_match : |
If TRUE, GDK will attempt to do matching against
existing colors if the color cannot be allocated as requested.
|
| Returns : | TRUE if the allocation succeeded.
|
void gdk_colormap_free_colors (GdkColormap *colormap, GdkColor *colors, gint ncolors);
Frees previously allocated colors.
colormap : |
a GdkColormap. |
colors : |
the colors to free. |
ncolors : |
the number of colors in colors.
|
void gdk_colormap_query_color (GdkColormap *colormap, gulong pixel, GdkColor *result);
Locates the RGB color in colormap corresponding to the given
hardware pixel pixel. pixel must be a valid pixel in the
colormap; it's a programmer error to call this function with a
pixel which is not in the colormap. Hardware pixels are normally
obtained from gdk_colormap_alloc_colors(), or from a GdkImage. (A
GdkImage contains image data in hardware format, a GdkPixbuf
contains image data in a canonical 24-bit RGB format.)
This function is rarely useful; it's used for example to implement the eyedropper feature in GtkColorSelection.
colormap : |
a GdkColormap |
pixel : |
pixel value in hardware display format |
result : |
GdkColor with red, green, blue fields initialized |
GdkVisual* gdk_colormap_get_visual (GdkColormap *colormap);
Returns the visual for which a given colormap was created.
colormap : |
a GdkColormap. |
| Returns : | the visual of the colormap. |
GdkScreen* gdk_colormap_get_screen (GdkColormap *cmap);
Gets the screen for which this colormap was created.
cmap : |
a GdkColormap |
| Returns : | the screen for which this colormap was created. |
Since 2.2
void gdk_colors_store (GdkColormap *colormap, GdkColor *colors, gint ncolors);
gdk_colors_store is deprecated and should not be used in newly-written code.
Changes the value of the first ncolors colors in
a private colormap. This function is obsolete and
should not be used. See gdk_color_change().
colormap : |
a GdkColormap. |
colors : |
the new color values. |
ncolors : |
the number of colors to change. |
GdkColor* gdk_color_copy (const GdkColor *color);
Makes a copy of a color structure. The result
must be freed using gdk_color_free().
color : |
a GdkColor. |
| Returns : | a copy of color.
|
void gdk_color_free (GdkColor *color);
Frees a color structure created with
gdk_color_copy().
color : |
a GdkColor. |
gint gdk_colors_alloc (GdkColormap *colormap, gboolean contiguous, gulong *planes, gint nplanes, gulong *pixels, gint npixels);
gdk_colors_alloc is deprecated and should not be used in newly-written code.
Allocates colors from a colormap. This function
is obsolete. See gdk_colormap_alloc_colors().
For full documentation of the fields, see
the Xlib documentation for XAllocColorCells()
colormap : |
a GdkColormap. |
contiguous : |
if TRUE, the colors should be allocated
in contiguous color cells.
|
planes : |
an array in which to store the plane masks. |
nplanes : |
the number of planes to allocate. (Or zero, to indicate that the color allocation should not be planar.) |
pixels : |
an array into which to store allocated pixel values. |
npixels : |
the number of pixels in each plane to allocate. |
| Returns : | TRUE if the allocation was successful
|
void gdk_colors_free (GdkColormap *colormap, gulong *pixels, gint npixels, gulong planes);
gdk_colors_free is deprecated and should not be used in newly-written code.
Frees colors allocated with gdk_colors_alloc(). This
function is obsolete. See gdk_colormap_free_colors().
colormap : |
a GdkColormap. |
pixels : |
the pixel values of the colors to free. |
npixels : |
the number of values in pixels.
|
planes : |
the plane masks for all planes to free, OR'd together. |
gint gdk_color_white (GdkColormap *colormap, GdkColor *color);
gdk_color_white is deprecated and should not be used in newly-written code.
Returns the white color for a given colormap. The resulting value has already allocated been allocated.
colormap : |
a GdkColormap. |
color : |
the location to store the color. |
| Returns : | TRUE if the allocation succeeded.
|
gint gdk_color_black (GdkColormap *colormap, GdkColor *color);
gdk_color_black is deprecated and should not be used in newly-written code.
Returns the black color for a given colormap. The resulting value has already benn allocated.
colormap : |
a GdkColormap. |
color : |
the location to store the color. |
| Returns : | TRUE if the allocation succeeded.
|
gboolean gdk_color_parse (const gchar *spec, GdkColor *color);
Parses a textual specification of a color and fill in
the red,
green, and
blue fields of a
GdkColor structure. The color is not
allocated, you must call gdk_colormap_alloc_color() yourself.
The text string can be in any of the forms accepted
by XParseColor; these include
name for a color from rgb.txt, such as
DarkSlateGray, or a hex specification
such as #3050b2 or #35b.
gint gdk_color_alloc (GdkColormap *colormap, GdkColor *color);
gdk_color_alloc is deprecated and should not be used in newly-written code. Use gdk_colormap_alloc_color() instead.
Allocates a single color from a colormap.
colormap : |
a GdkColormap. |
color : |
The color to allocate. On return, the
pixel field will be filled in.
|
| Returns : | TRUE if the allocation succeeded.
|
gint gdk_color_change (GdkColormap *colormap, GdkColor *color);
gdk_color_change is deprecated and should not be used in newly-written code.
Changes the value of a color that has already
been allocated. If colormap is not a private
colormap, then the color must have been allocated
using gdk_colormap_alloc_colors() with the
writeable set to TRUE.
colormap : |
a GdkColormap. |
color : |
a GdkColor, with the color to change
in the pixel field,
and the new value in the remaining fields.
|
| Returns : | TRUE if the color was successfully changed.
|
gboolean gdk_color_equal (const GdkColor *colora, const GdkColor *colorb);
Compares two colors.
guint gdk_color_hash (const GdkColor *colora);
A hash function suitable for using for a hash table that stores GdkColor's.
colora : |
a GdkColor. |
| Returns : | The hash function applied to colora
|
gchar* gdk_color_to_string (const GdkColor *color);
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.
color : |
a GdkColor |
| Returns : | a newly-allocated text string |
Since 2.12