Xfce Foundation Classes
Main Page  | IndexNamespace List  |  Alphabetical List  |  Class List  |  File List


Xfc::Gdk::Colormap Class Reference

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

#include <xfc/gdk/color.hh>

Inheritance diagram for Xfc::Gdk::Colormap:

Xfc::G::Object Xfc::G::TypeInstance Xfc::Trackable List of all members.

Public Member Functions

Constructors
Accessors
Methods
RGB Methods

Static Public Member Functions

Accessors

Protected Member Functions

Constructors

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.

Note: dynamically allocated objects must either be unreferenced or assigned to a smart pointer. Stack objects are automatically unreferenced when they go out of scope.


Constructor & Destructor Documentation

Xfc::Gdk::Colormap::Colormap GdkColormap *  colormap,
bool  owns_reference = true
[explicit, protected]
 

Construct a new Colormap from an existing GdkColormap.

Parameters:
colormap A pointer to a GdkColormap.
owns_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).

Xfc::Gdk::Colormap::Colormap const Visual visual,
bool  allocate = false
 

Constructs a new colormap for the given visual with a reference count of 1 that the caller owns.

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 Xfc::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 Xfc::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 Xfc::Gdk::Colormap::free_color const Color color  ) 
 

Frees a previously allocated color.

Parameters:
color The Color to free.

void Xfc::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* Xfc::Gdk::Colormap::get_screen  )  const
 

Gets the screen for which this colormap was created.

Returns:
The screen for which the colormap was created.

Colormap* Xfc::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* Xfc::Gdk::Colormap::get_visual  )  const
 

Gets the visual for which this colormap was created.

Returns:
The visual of the colormap.

Color Xfc::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 Xfc::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 Xfc::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: Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC 4.3