Reference Manual

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Compound List | File List | Namespace Members | Compound Members | File Members

# Inti::Gdk::Colormap Class Reference

A GdkColormap C++ wrapper class. More...

`#include <inti/gdk/color.h>`

Inheritance diagram for Inti::Gdk::Colormap:

List of all members.

## Public Member Functions

Constructors

- Colormap (const Visual &visual, bool allocate=false)
    Creates a new colormap for the given visual.
- virtual ~Colormap ()
    Destructor.

Accessors

- GdkColormap * gdk_colormap () const
    Get a pointer to the GdkColormap structure.
- GdkColormapClass * gdk_colormap_class () const
    Get a pointer to the GdkColormapClass structure.
- operator GdkColormap * () const
    Conversion operator; safely converts a Colormap to a GdkColormap pointer.
- const Visual * get_visual () const
    Gets the visual for which this colormap was created.
- Screen * get_screen () const
    Gets the screen for which this colormap was created.

Methods

- bool alloc_color (Color &color, bool best_match=true, bool writeable=false)
    Allocates a single color from a colormap.
- int alloc_colors (const std::vector< Color > &colors, std::vector< bool > &successes, bool best_match=true, bool writeable=false)
    Allocates colors from the colormap.
- void free_color (const Color &color)
    Frees a previously allocated color.
- void free_colors (const std::vector< Color > &colors)
    Frees previously allocated colors.
- void query_color (unsigned long pixel, Color &result) const
    Locates the RGB color in the colormap corresponding to the given hardware pixel pixel.
- Color query_color (unsigned long pixel) const
    Locates the RGB color in the colormap corresponding to the given hardware pixel pixel.

RGB Methods

- void rgb_find_color (Color &color) const
    Finds the best matching color for color in the colormap.

## Static Public Member Functions

- Colormap * get_system (const Screen *screen=0)
    Gets the system's default colormap for screen.

## Protected Member Functions

Constructors

- Colormap (GdkColormap *colormap, bool reference=true)
    Construct a new Colormap from an existing GdkColormap.

## Detailed Description

A GdkColormap C++ wrapper class.

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 get_system()) is the default colormap of the system. There is another colormap that was important - the colormap in which GdkRGB works, retrieved with gdk_rgb_get_colormap(). Historically you had to use this colormap for all RGB functions because RGB could only render to this colormap. Since GTK+-2.2 RGB can render to any colormap and visual, so there is no need to call this function, and it hasn't been wrapped.

Note when using GdkRGB, it is not generally necessary to allocate colors directly.

## Constructor & Destructor Documentation

Inti::Gdk::Colormap::Colormap | ( | GdkColormap * | colormap,
|  | bool | reference = true
| ) | `[explicit, protected]`

Construct a new Colormap from an existing GdkColormap.

Parameters:

  colormap | A pointer to a GdkColormap.
  reference | Set false if the initial reference count is floating, set true if it's not.

The colormap can be a newly created GdkColormap or an existing GdkColormap. (see G::Object::Object).

Inti::Gdk::Colormap::Colormap | ( | const Visual & | visual,
|  | bool | allocate = false
| ) |

Creates a new colormap for the given visual.

Parameters:

  visual | A Visual.
  allocate | If true, the newly created colormap will be a private colormap, and all colors in it will be allocated for the applications use.

## Member Function Documentation

bool Inti::Gdk::Colormap::alloc_color | ( | Color & | color,
|  | bool | best_match = true,
|  | bool | writeable = false
| ) |

Allocates a single color from a colormap.

Parameters:

  color | The color to allocate.
  best_match | If true, GDK will attempt to do matching against existing colors if the colors cannot be allocated as requested.
  writeable | If true, the colors are allocated writeable.

Returns:
  true if the allocation succeeded.

On return the color's pixel field will be filled in if allocation succeeds. Writeable colors cannot be shared between applications.

int Inti::Gdk::Colormap::alloc_colors | ( | const std::vector< Color > & | colors,
|  | std::vector< bool > & | successes,
|  | bool | best_match = true,
|  | bool | writeable = false
| ) |

Allocates colors from the colormap.

Parameters:

  colors | A reference to a vector of Color that holds the color values to allocate.
  successes | A reference to a vector of bool to hold the allocation success/failure.
  best_match | If true, GDK will attempt to do matching against existing colors if the colors cannot be allocated as requested.
  writeable | If true, the colors are allocated writeable.

Returns:
  The number of colors that were not sucessfully allocated.

On return, the pixel values for the allocated colors will be filled in. If the return value is 0, all colors were successfully allocated and successes was ignored (i.e. not filled in). If there are any unallocated colors successes will be filled in with the success/failure of each color allocation, in the same order the colors appear in colors. Writable colors can have their values changed later using change(), and cannot be shared between applications.

void Inti::Gdk::Colormap::free_color | ( | const Color & | color | ) |

Frees a previously allocated color.

Parameters:

  color | The Color to free.

void Inti::Gdk::Colormap::free_colors | ( | const std::vector< Color > & | colors | ) |

Frees previously allocated colors.

Parameters:

  colors | A reference to a vector of Color that holds the colors to free.

Screen* Inti::Gdk::Colormap::get_screen | ( |  | ) | const

Gets the screen for which this colormap was created.

Returns:
  The screen for which the colormap was created.

Colormap* Inti::Gdk::Colormap::get_system | ( | const Screen * | screen = 0 | ) | `[static]`

Gets the system's default colormap for screen.

Parameters:

  screen | The Screen to use, or null for the default screen.

Returns:
  The default system colormap for screen,

const Visual* Inti::Gdk::Colormap::get_visual | ( |  | ) | const

Gets the visual for which this colormap was created.

Returns:
  The visual of the colormap.

Color Inti::Gdk::Colormap::query_color | ( | unsigned long | pixel | ) | const

Locates the RGB color in the colormap corresponding to the given hardware pixel pixel.

Parameters:

  pixel | The pixel value in hardware display format.

Returns:
  A Color with the red, green and blue fields initialized.

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 alloc_colors(), or from a Gdk::Image. (A Gdk::Image contains image data in hardware format, a Gdk::Pixbuf contains image data in a canonical 24-bit RGB format.)

This method is rarely useful; it's used for example to implement the eyedropper feature in Gtk::ColorSelection.

void Inti::Gdk::Colormap::query_color | ( | unsigned long | pixel,
|  | Color & | result
| ) | const

Locates the RGB color in the colormap corresponding to the given hardware pixel pixel.

Parameters:

  pixel | The pixel value in hardware display format.
  result | A Color with the red, green and blue fields initialized.

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 alloc_colors(), or from a Gdk::Image. (A Gdk::Image contains image data in hardware format, a Gdk::Pixbuf contains image data in a canonical 24-bit RGB format.)

This method is rarely useful; it's used for example to implement the eyedropper feature in Gtk::ColorSelection.

void Inti::Gdk::Colormap::rgb_find_color | ( | Color & | color | ) | const

Finds the best matching color for color in the colormap.

Parameters:

  color | A color.

colormap should be the colormap for the graphics context and drawable you're using to draw. If you're drawing to a Gtk::Widget, call Gtk::Widget::get_colormap(). color should have its red, green, and blue fields initialized; rgb_find_color() will fill in the pixel field with the best matching pixel from a color cube. The color is then ready to be used for drawing, e.g. you can call Gdk::GC::set_foreground() which expects pixel to be initialized.

In many cases, you can avoid this whole issue by calling Gdk::GC::set_rgb_fg_color() or Gdk::GC::set_rgb_bg_color(), which do not expect pixel to be initialized in advance. If you use those methods, there's no need for rgb_find_color().

The documentation for this class was generated from the following file:

- color.h

Main Page - Footer