Colormaps and Colors

Colormaps and Colors — Manipulation of colors and colormaps

Types and Values

Includes

#include <gdk/gdk.h>

Description

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.

Functions

gdk_colormap_new ()

GdkColormap *
gdk_colormap_new (GdkVisual *visual,
                  gboolean allocate);

Creates a new colormap for the given visual.

Parameters

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.


gdk_colormap_ref ()

GdkColormap *
gdk_colormap_ref (GdkColormap *cmap);

gdk_colormap_ref has been deprecated since version 2.0 and should not be used in newly-written code.

Use g_object_ref() instead.

Deprecated function; use g_object_ref() instead.

Parameters

cmap

a GdkColormap

 

Returns

the colormap


gdk_colormap_unref ()

void
gdk_colormap_unref (GdkColormap *cmap);

gdk_colormap_unref has been deprecated since version 2.0 and should not be used in newly-written code.

Use g_object_unref() instead.

Deprecated function; use g_object_unref() instead.

Parameters

cmap

a GdkColormap

 

gdk_colormap_get_system ()

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.


gdk_colormap_get_system_size ()

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.


gdk_colormap_change ()

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().

Parameters

colormap

a GdkColormap.

 

ncolors

the number of colors to change.

 

gdk_colormap_alloc_colors ()

gint
gdk_colormap_alloc_colors (GdkColormap *colormap,
                           GdkColor *colors,
                           gint n_colors,
                           gboolean writeable,
                           gboolean best_match,
                           gboolean *success);

Allocates colors from a colormap.

Parameters

colormap

a GdkColormap.

 

colors

The color values to allocate. On return, the pixel values for allocated colors will be filled in.

 

n_colors

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.


gdk_colormap_alloc_color ()

gboolean
gdk_colormap_alloc_color (GdkColormap *colormap,
                          GdkColor *color,
                          gboolean writeable,
                          gboolean best_match);

Allocates a single color from a colormap.

Parameters

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.


gdk_colormap_free_colors ()

void
gdk_colormap_free_colors (GdkColormap *colormap,
                          const GdkColor *colors,
                          gint n_colors);

Frees previously allocated colors.

Parameters

colormap

a GdkColormap.

 

colors

the colors to free.

 

n_colors

the number of colors in colors .

 

gdk_colormap_query_color ()

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.

Parameters

colormap

a GdkColormap

 

pixel

pixel value in hardware display format

 

result

GdkColor with red, green, blue fields initialized

 

gdk_colormap_get_visual ()

GdkVisual *
gdk_colormap_get_visual (GdkColormap *colormap);

Returns the visual for which a given colormap was created.

Parameters

colormap

a GdkColormap.

 

Returns

the visual of the colormap.


gdk_colormap_get_screen ()

GdkScreen *
gdk_colormap_get_screen (GdkColormap *cmap);

Gets the screen for which this colormap was created.

Parameters

cmap

a GdkColormap

 

Returns

the screen for which this colormap was created.

Since: 2.2


gdk_colors_store ()

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().

Parameters

colormap

a GdkColormap.

 

colors

the new color values.

 

ncolors

the number of colors to change.

 

gdk_color_copy ()

GdkColor *
gdk_color_copy (const GdkColor *color);

Makes a copy of a color structure. The result must be freed using gdk_color_free().

Parameters

color

a GdkColor.

 

Returns

a copy of color .


gdk_color_free ()

void
gdk_color_free (GdkColor *color);

Frees a color structure created with gdk_color_copy().

Parameters

color

a GdkColor.

 

gdk_colors_alloc ()

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().

Parameters

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


gdk_colors_free ()

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().

Parameters

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.

 

gdk_color_white ()

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.

Parameters

colormap

a GdkColormap.

 

color

the location to store the color.

 

Returns

TRUE if the allocation succeeded.


gdk_color_black ()

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 been allocated.

Parameters

colormap

a GdkColormap.

 

color

the location to store the color.

 

Returns

TRUE if the allocation succeeded.


gdk_color_parse ()

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 string can either one of a large set of standard names. (Taken from the X11 rgb.txt file), or it can be a hex value in the form '#rgb' '#rrggbb' '#rrrgggbbb' or '#rrrrggggbbbb' where 'r', 'g' and 'b' are hex digits of the red, green, and blue components of the color, respectively. (White in the four forms is '#fff' '#ffffff' '#fffffffff' and '#ffffffffffff')

Parameters

spec

the string specifying the color.

 

color

the GdkColor to fill in.

[out]

Returns

TRUE if the parsing succeeded.


gdk_color_alloc ()

gint
gdk_color_alloc (GdkColormap *colormap,
                 GdkColor *color);

gdk_color_alloc has been deprecated since version 2.2 and should not be used in newly-written code.

Use gdk_colormap_alloc_color() instead.

Allocates a single color from a colormap.

Parameters

colormap

a GdkColormap.

 

color

The color to allocate. On return, the pixel field will be filled in.

 

Returns

TRUE if the allocation succeeded.


gdk_color_change ()

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.

Parameters

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.


gdk_color_equal ()

gboolean
gdk_color_equal (const GdkColor *colora,
                 const GdkColor *colorb);

Compares two colors.

Parameters

colora

a GdkColor.

 

colorb

another GdkColor.

 

Returns

TRUE if the two colors compare equal


gdk_color_hash ()

guint
gdk_color_hash (const GdkColor *colora);

A hash function suitable for using for a hash table that stores GdkColor's.

Parameters

colora

a GdkColor.

 

Returns

The hash function applied to colora


gdk_color_to_string ()

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.

Parameters

color

a GdkColor

 

Returns

a newly-allocated text string

Since: 2.12

Types and Values

GdkColor

typedef struct {
  guint32 pixel;
  guint16 red;
  guint16 green;
  guint16 blue;
} GdkColor;

The GdkColor structure is used to describe an allocated or unallocated color.

Members

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 green component of the color.

 

guint16 blue;

The blue component of the color.

 

GdkColormap

typedef struct {
  gint      GSEAL (size);
  GdkColor *GSEAL (colors);
} GdkColormap;

The colormap structure contains the following public fields.