Colormaps and Colors: GDK 2 Reference Manual

## Colormaps and Colors Colormaps and Colors |

## Functions

GdkColormap * | gdk_colormap_new ()
GdkColormap * | gdk_colormap_ref ()
void | gdk_colormap_unref ()
GdkColormap * | gdk_colormap_get_system ()
gint | gdk_colormap_get_system_size ()
void | gdk_colormap_change ()
gint | gdk_colormap_alloc_colors ()
gboolean | gdk_colormap_alloc_color ()
void | gdk_colormap_free_colors ()
void | gdk_colormap_query_color ()
GdkVisual * | gdk_colormap_get_visual ()
GdkScreen * | gdk_colormap_get_screen ()
void | gdk_colors_store ()
GdkColor * | gdk_color_copy ()
void | gdk_color_free ()
gint | gdk_colors_alloc ()
void | gdk_colors_free ()
gint | gdk_color_white ()
gint | gdk_color_black ()
gboolean | gdk_color_parse ()
gint | gdk_color_alloc ()
gint | gdk_color_change ()
gboolean | gdk_color_equal ()
guint | gdk_color_hash ()
gchar * | gdk_color_to_string ()

## Types and Values

| GdkColor
| GdkColormap

## Includes

    #include <gdk/gdk.h>

## Description

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

### GdkColormap

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