view release on metacpan or  search on metacpan

lib/App/Chart/Gtk2/Ex/GdkColorAlloc.pm  view on Meta::CPAN

Allocate a colour cell and return a C<App::Chart::Gtk2::Ex::GdkColorAlloc> object
representing that cell.  The object will have the C<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, croak() on error (default 1)

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

=item C<< $color->colormap >>

Return the C<Gtk2::Gdk::Colormap> in which C<$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.

=back

=head1 OTHER NOTES

Each C<< $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 C<alloc_colors> or the plane-oriented
C<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 niceties
of cross-program sharing with allocate and free don't apply.

=head1 SEE ALSO

L<Gtk2::Gdk::Color>, L<Gtk2::Gdk::Colormap>

=cut