Colormaps and Colors

Name

Colormaps and Colors -- manipulation of colors and colormaps.

Synopsis


#include <gdk/gdk.h>


struct      GdkColor;
struct      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);
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);
gint        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);


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

Details

struct GdkColor

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

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


struct GdkColormap

struct GdkColormap
{
  GObject parent_instance;

  /*< public >*/
  gint      size;
  GdkColor *colors;

  /*< private >*/
  GdkVisual *visual;
  
  gpointer windowing_data;
};

The colormap structure contains the following public fields.


gdk_colormap_new ()

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

Creates a new colormap for the given visual.


gdk_colormap_ref ()

GdkColormap* gdk_colormap_ref               (GdkColormap *cmap);

Warning

gdk_colormap_ref is deprecated and should not be used in newly-written code.

Deprecated function; use g_object_ref() instead.


gdk_colormap_unref ()

void        gdk_colormap_unref              (GdkColormap *cmap);

Warning

gdk_colormap_unref is deprecated and should not be used in newly-written code.

Deprecated function; use g_object_ref() instead.


gdk_colormap_get_system ()

GdkColormap* gdk_colormap_get_system        (void);

Returns the system's default colormap.


gdk_colormap_get_system_size ()

gint        gdk_colormap_get_system_size    (void);

Warning

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


gdk_colormap_change ()

void        gdk_colormap_change             (GdkColormap *colormap,
                                             gint ncolors);

Warning

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 color map. This function is obsolete and should not be used. See gdk_color_change().


gdk_colormap_alloc_colors ()

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

Allocates colors from a colormap.


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.


gdk_colormap_free_colors ()

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

Frees previously allocated 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.


gdk_colormap_get_visual ()

GdkVisual*  gdk_colormap_get_visual         (GdkColormap *colormap);

Returns the visual for which a given colormap was created.


gdk_colors_store ()

void        gdk_colors_store                (GdkColormap *colormap,
                                             GdkColor *colors,
                                             gint ncolors);

Warning

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


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


gdk_color_free ()

void        gdk_color_free                  (GdkColor *color);

Frees a color structure created with gdk_color_copy().


gdk_colors_alloc ()

gint        gdk_colors_alloc                (GdkColormap *colormap,
                                             gboolean contiguous,
                                             gulong *planes,
                                             gint nplanes,
                                             gulong *pixels,
                                             gint npixels);

Warning

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


gdk_colors_free ()

void        gdk_colors_free                 (GdkColormap *colormap,
                                             gulong *pixels,
                                             gint npixels,
                                             gulong planes);

Warning

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


gdk_color_white ()

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

Warning

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.


gdk_color_black ()

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

Warning

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.


gdk_color_parse ()

gint        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 305050.


gdk_color_alloc ()

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

Warning

gdk_color_alloc is deprecated and should not be used in newly-written code.

Allocates a single color from a colormap. This function is obsolete. See gdk_colormap_alloc_color().


gdk_color_change ()

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

Warning

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.


gdk_color_equal ()

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

Compares two colors.


gdk_color_hash ()

guint       gdk_color_hash                  (const GdkColor *colora);

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