gtk.gdk.Colormap
Prev | The gtk.gdk Class Reference | Next

## gtk.gdk.Colormap

gtk.gdk.Colormap — a table of color display component values

## Synopsis

    class gtk.gdk.Colormap(gobject.GObject):
        gtk.gdk.Colormap(visual, allocate)
        def alloc_color(color, writeable=False, best_match=True)
        def alloc_color(spec, writeable=False, best_match=True)
        def alloc_color(red, green, blue, writeable=False, best_match=True)
        def get_visual()
        def get_screen()
        def query_color(pixel)

    Functions

        def gtk.gdk.colormap_get_system()

## Ancestry

    +-- gobject.GObject
      +-- gtk.gdk.Colormap

## Description

A `gtk.gdk.Colormap` contains a table mapping index values to the RGB color component values used to display the colors. The index value corresponds to the pixel value of a `gtk.gdk.Color` object and the RGB component values correspond to the `gtk.gdk.Color` red, green and blue values. The `gtk.Widget.get_colormap`() method is used to retrieve the colormap used by a widget. The default system colormap is retrieved by using the `gtk.gdk.colormap_get_system`() function. The `alloc_color`() method has three signatures to allow the color specification using an unallocated `gtk.gdk.Color`, a string or a RGB trio.

## Constructor

        gtk.gdk.Colormap(visual, allocate)

`visual` : | the `gtk.gdk.Visual` to use
`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 : | a `gtk.gdk.Colormap` object

Creates a new `gtk.gdk.Colormap` for the `gtk.gdk.Visual` specified by `visual`. If `allocate` is `True` the colormap will be a private colormap for the sole use of the application.

## Methods

### gtk.gdk.Colormap.alloc_color

        def alloc_color(color, writeable=False, best_match=True)

`color` : | an unallocated `gtk.gdk.Color`
`writeable` : | if `True` the colormap entry is writeable.
`best_match` : | if `True` a best match to the requested color can be used if needed.
Returns : | a new `gtk.gdk.Color` object

The `alloc_color`() method allocates the color specified by `color` in the colormap. The value of color should be an unallocated `gtk.gdk.Color`. If `writeable` is `True` the color is allocated writeable which means it can be changed after allocation but cannot be shared with another application. If `best_match` is `True` the closest match to the color will be returned if the request could not be satisfied exactly.

This method raises:

- the ValueError (TypeError prior to PyGTK 2.4) exception if unable to parse the color specification
- the RuntimeError exception if the color could not be allocated

### gtk.gdk.Colormap.alloc_color

        def alloc_color(spec, writeable=False, best_match=True)

`spec` : | a string containing a color specification
`writeable` : | if `True` the colormap entry is writeable.
`best_match` : | if `True` a best match to the requested color can be used if needed.
Returns : | a `gtk.gdk.Color` object

The `alloc_color`() method allocates the color specified by `spec` in the colormap. The format of `spec` is a string containing the specification of the color either as a name (e.g. "navajowhite") as specified in the X11 `rgb.txt` file or as a hexadecimal string (e.g. "#FF0078"). The hexadecimal string must start with '#' and must contain 3 sets of hexadecimal digits of the same length (i.e. 1, 2 ,3 or 4 digits). For example the following specify the same color value: "#F0A", "#FF00AA", "#FFF000AAA" and "#FFFF0000AAAA". If `writeable` is `True` the color is allocated writeable which means it can be changed after allocation but cannot be shared with another application. If `best_match` is `True` the closest match to the color will be returned if the request could not be satisfied exactly.

This method raises:

- the ValueError (TypeError prior to PyGTK 2.4) exception if unable to parse the color specification
- the RuntimeError exception if the color could not be allocated

### gtk.gdk.Colormap.alloc_color

        def alloc_color(red, green, blue, writeable=False, best_match=True)

`red` : | the red component of the color in the range 0-65535
`green` : | the green component of the color in the range 0-65535
`blue` : | the blue component of the color in the range 0-65535
`writeable` : | a gboolean
`best_match` : | a gboolean
Returns : | a `gtk.gdk.Color` object

The `alloc_color`() method allocates the color specified by the component values `red`, `green` and `blue`. If `writeable` is `True` the color is allocated writeable which means it can be changed after allocation but cannot be shared with another application. If `best_match` is `True` the closest match to the color will be returned if the request could not be satisfied exactly.

This method raises:

- the ValueError (TypeError prior to PyGTK 2.4) exception if unable to parse the color specification
- the RuntimeError exception if the color could not be allocated

### gtk.gdk.Colormap.get_visual

        def get_visual()

Returns : | a `gtk.gdk.Visual`

The `get_visual`() method returns the visual the colormap was created for. See the gtk.gdk.Colormap constructor.

### gtk.gdk.Colormap.get_screen

        def get_screen()

Returns : | a `gtk.gdk.Screen`

The `get_screen`() method returns the `gtk.gdk.Screen` the colormap was created for.

### gtk.gdk.Colormap.query_color

        def query_color()

`pixel` : | a pixel value
Returns : | the `gtk.gdk.Color` corresponding to `pixel`

### Note

This method is available in PyGTK 2.4 and above.

The `query_color`() method returns the `gtk.gdk.Color` corresponding to the hardware pixel value specified by `pixel`. `pixel` must be a valid pixel in the colormap. It's a programmer error to call this method with a pixel which is not in the colormap. Hardware pixels are normally obtained from the `alloc_color`() method, or from a `gtk.gdk.Image` object. (A `gtk.gdk.Image` contains image data in hardware format while a `gtk.gdk.Pixbuf` contains image data in a canonical 24-bit RGB format.)

## Functions

### gtk.gdk.colormap_get_system

        def gtk.gdk.colormap_get_system()

Returns : | the system' default colormap

The `gtk.gdk.colormap_get_system`() method returns the default colormap used by the system on the default screen. See the `gtk.gdk.Screen.get_system_colormap`() method for more information.

Prev | Up | Next
gtk.gdk.Color | Home | gtk.gdk.Cursor