Colormaps and Colors

## Colormaps and Colors 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);
    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);
    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.

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.

### struct GdkColormap

    struct GdkColormap {

      GObject parent_instance;

      gint      size;
      GdkColor *colors;

    };

The colormap structure contains the following public fields.

GObject `parent_instance` |
gint `size` | For pseudo-color colormaps, the number of colors in the colormap.
GdkColor *`colors` | An array containing the current values in the colormap. This can be used to map from pixel values back to RGB values. This is only meaningful for pseudo-color colormaps.

### gdk_colormap_new ()

    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.

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

`cmap` : | a GdkColormap
Returns : | the colormap

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

`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);

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

Returns : | the size of the system's default 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 colormap. This function is obsolete and should not be used. See `gdk_color_change()`.

`colormap` : | a GdkColormap.
`ncolors` : | the number of colors to 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.

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

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

`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,
                                                 GdkColor *colors,
                                                 gint ncolors);

Frees previously allocated colors.

`colormap` : | a GdkColormap.
`colors` : | the colors to free.
`ncolors` : | 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.

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

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

`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);

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

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

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

`color` : | a GdkColor.

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

`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 : |

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

`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);

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

`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);

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

`colormap` : | a GdkColormap.
`color` : | the location to store the color.
Returns : | `TRUE` if the allocation succeeded.

### 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`.

`spec` : | the string specifying the color.
`color` : | the GdkColor to fill in
Returns : | `TRUE` if the parsing succeeded.

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

### 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`.

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

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

`colora` : | a GdkColor.
Returns : | The hash function appled to `colora`