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

Accessors
Methods
RGB Methods

Static Public Member Functions

Accessors

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.

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

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

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.

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.

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.

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