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 the pixel 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 and colormap, to ask for a non-writable (ie. shared) best-match colour. color can be either a string colour name to be parsed by Gtk2::Gdk::Color->parse, or a Gtk2::Gdk::Color object with red/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 or Gtk2::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 and best_match options are passed on to $colormap->alloc_color (see Gtk2::Gdk::Colormap). The default is writable false and best_match true. If you change that then the alloc can fail. The default is to croak on failure, but raise_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.

SEE ALSO

Gtk2::Gdk::Color, Gtk2::Gdk::Colormap