NAME
App::Chart::Gtk2::Ex::GdkColorAlloc -- object for allocated colormap cell
SYNOPSIS
use App::Chart::Gtk2::Ex::GdkColorAlloc;
my $color = App::Chart::Gtk2::Ex::GdkColorAlloc->new (widget => $my_widget,
color => 'red');
$my_gc->set_foreground ($color);
$color = undef; # cell freed when destroyed
CLASS HIERARCHY
App::Chart::Gtk2::Ex::GdkColorAlloc
is a Perl subclass of Gtk2::Gdk::Color
Glib::Boxed
Gtk2::Gdk::Color
App::Chart::Gtk2::Ex::GdkColorAlloc
DESCRIPTION
A GdkColorAlloc object represents a colour cell allocated in a particular Gtk2::Gdk::Colormap
. When the GdkColorAlloc object is destroyed the cell is freed.
GdkColorAlloc is a subclass of Gtk2::Gdk::Color
and can be used everywhere such a colour object can be used, for instance setting a pixel value in a Gtk2::Gdk::GC
for some drawing.
GdkColorAlloc object allocates a cell using Gtk2::Gdk::Colormap->alloc_color
, and when the object is garbage collected it calls Gtk2::Gdk::Colormap->free_colors
to free that cell. This means you can just forget the object when you don't need the colour any more, without an explicit free.
Whether you actually need this depends on how you use your colours. You might be happy with the Gtk2::Gdk::Rgb
system. Or if you allocate at the start of a program and never change then freeing doesn't matter. Or if you only care about TrueColor visuals then colours are fixed and there's nothing to free. But for 8-bit PseudoColor with cells released on widget destruction or colour scheme changes then GdkColorAlloc
is good. (Despite the fact Cairo versions circa 1.4 broke most Gtk programs on 8-bit displays.)
FUNCTIONS
App::Chart::Gtk2::Ex::GdkColorAlloc->new (key => value, ...)
-
Allocate a colour cell and return a
App::Chart::Gtk2::Ex::GdkColorAlloc
object representing that cell. The object will have thepixel
field set ready for use in a GC or similar. Eg.my $color = App::Chart::Gtk2::Ex::GdkColorAlloc->new (color => 'red', widget => $my_widget); $my_gc->set_foreground ($color);
The following key parameters are accepted,
color Gtk2::Gdk::Color object, or string name colormap Gtk2::Gdk::Colormap object widget Gtk2::Widget, to use its colormap window Gtk2::Gdk::Window, to use its colormap writable boolean, ask for a writable cell (default 0) best_match boolean, get closest matching colour (default 1) raise_error boolean, C<croak> on error (default 1)
The most basic call is just with
color
andcolormap
, to ask for a non-writable (ie. shared) best-match colour.color
can be either a string colour name to be parsed byGtk2::Gdk::Color->parse
, or aGtk2::Gdk::Color
object withred
/green
/blue
fields set (which is copied so the object you pass is unmodified).my $color = App::Chart::Gtk2::Ex::GdkColorAlloc->new (colormap => $my_cmap, color => 'red'); my $rgb = Gtk2::Gdk::Color->new (0x7F00, 0x0000, 0x0000); my $color = App::Chart::Gtk2::Ex::GdkColorAlloc->new (color => $rgb, colormap => $my_cmap);
If you want a colour cell for use in a
Gtk2::Widget
orGtk2::Gdk::Window
, then you can pass that to have its colormap used.my $color = App::Chart::Gtk2::Ex::GdkColorAlloc->new (widget => $my_widget, color => 'blue'); my $color = App::Chart::Gtk2::Ex::GdkColorAlloc->new (window => $my_win, color => 'purple');
The
writable
andbest_match
options are passed on to$colormap->alloc_color
(see Gtk2::Gdk::Colormap). The default iswritable
false andbest_match
true. If you change that then the alloc can fail. The default is tocroak
on failure, butraise_error
can be set to false to return undef instead. Eg.my $color = App::Chart::Gtk2::Ex::GdkColorAlloc->new (widget => $my_widget, color => 'yellow', writable => 1, raise_error => 0); if (! $color) { print "cannot allocate writable colour\n"; }
$color->colormap
-
Return the
Gtk2::Gdk::Colormap
in which$color
is allocated.A GdkColorAlloc object keeps a reference to its colormap, so the colormap will remain alive for as long as there's a GdkColorAlloc object using it.
OTHER NOTES
Each $colormap->alloc_color
does a round-trip to the X server, which may be slow if you've got thousands of colours to allocate. An equivalent to the mass-allocation of alloc_colors
or the plane-oriented gdk_colors_alloc
would be wanted for big colour sets, but chances are if you're working with thousands of colours you'll want a pattern in the pixel values and so would be getting a private colormap anyway where the nicities of cross-program sharing with allocate and free don't apply.