view release on metacpan or  search on metacpan

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

      croak "GdkColorAlloc: cannot parse colour \"$color\"";
    }
    $color = $parsed_color;
  }

  my $writable = delete $param{'writable'};
  my $best_match
    = (exists $param{'best_match'}  ? delete $param{'best_match'}  : 1);
  my $raise_error
    = (exists $param{'raise_error'} ? delete $param{'raise_error'} : 1);

  # check remaining args before doing the alloc, so we don't leak an
  # allocated cell if we croak
  if (%param) {
    croak "GdkColorAlloc: unrecognised parameter(s): " . join(',', keys %param);
  }

  if (! $colormap->alloc_color ($color, $writable, $best_match)) {
    if ($raise_error) {
      croak 'GdkColorAlloc: cannot allocate colour cell';
    } else {
      return undef;
    }
  }

  my $self = bless $color, $class;  # rebless
  $color_to_colormap{refaddr($self)} = $colormap;

  ### added to color_to_colormap: \%color_to_colormap
  return $self;
}

sub alloc_color {
  my ($class, $colormap, $color, $writable, $best_match) = @_;
  if (@_ < 4) { $best_match = 1; }

  if (ref $color) {
    # Gtk2::Gdk::Color object -- copy so as not to modify the caller's object
    $color = $color->copy;
  } else {
    # string colour name
    my $parsed_color = Gtk2::Gdk::Color->parse ($color)
      or croak "App::Chart::Gtk2::Ex::GdkColorAlloc->new: cannot parse colour \"$color\"";
    $color = $parsed_color;
  }

  $colormap->alloc_color ($color, $writable, $best_match)
    or croak 'GdkColorAlloc: cannot allocate colour cell';

  my $self = bless $color, $class;  # rebless
  $color_to_colormap{refaddr($self)} = $colormap;
  return $self;
}

sub DESTROY {
  my ($self) = @_;
  if (my $colormap = delete $color_to_colormap{refaddr($self)}) {
    $colormap->free_colors ($self);
  }
  ### DESTROY leaves color_to_colormap: \%color_to_colormap
  $self->SUPER::DESTROY;
}

sub colormap {
  my ($self) = @_;
  ### in color_to_colormap: \%color_to_colormap
  return $color_to_colormap{refaddr($self)};
}


1;
__END__

=for stopwords colormap GdkColorAlloc TrueColor PseudoColor Gtk GC Eg ie alloc undef

=head1 NAME

App::Chart::Gtk2::Ex::GdkColorAlloc -- object for allocated colormap cell

=for test_synopsis my ($my_widget, $my_gc)

=head1 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

=head1 CLASS HIERARCHY

C<App::Chart::Gtk2::Ex::GdkColorAlloc> is a Perl subclass of C<Gtk2::Gdk::Color>

    Glib::Boxed
      Gtk2::Gdk::Color
        App::Chart::Gtk2::Ex::GdkColorAlloc

=head1 DESCRIPTION

A GdkColorAlloc object represents a colour cell allocated in a particular
C<Gtk2::Gdk::Colormap>.  When the GdkColorAlloc object is destroyed the cell
is freed.

GdkColorAlloc is a subclass of C<Gtk2::Gdk::Color> and can be used
everywhere such a colour object can be used, for instance setting a pixel
value in a C<Gtk2::Gdk::GC> for some drawing.

GdkColorAlloc object allocates a cell using
C<< Gtk2::Gdk::Colormap->alloc_color >>, and when the object is garbage
collected it calls C<< 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 C<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 C<GdkColorAlloc> is good.
(Despite the fact Cairo versions circa 1.4 broke most Gtk programs on 8-bit