File Coverage

blib/lib/Gtk2/Ex/CellLayout/Base.pm

Criterion	Covered	Total	%
statement	16	18	88.8
branch			n/a
condition			n/a
subroutine	6	6	100.0
pod			n/a
total	22	24	91.6

# Copyright 2007, 2008, 2009, 2010 Kevin Ryde

# This file is part of Gtk2-Ex-CellLayout-Base.
#
# Gtk2-Ex-CellLayout-Base is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License as published
# by the Free Software Foundation; either version 3, or (at your option) any
# later version.
#
# Gtk2-Ex-CellLayout-Base is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
# Public License for more details.
#
# You should have received a copy of the GNU General Public License along
# with Gtk2-Ex-CellLayout-Base.  If not, see .

package Gtk2::Ex::CellLayout::Base;
use 5.008;
use strict;
use warnings;
use Carp;
use List::Util;
use Gtk2;
use Glib::Ex::FreezeNotify;

our $VERSION = 5;


#------------------------------------------------------------------------------
# Gtk2::CellLayout interface functions

# gtk_cell_layout_pack_start
#
# Because calls here have been spun through GInterface, $expand will be a
# the usual Gtk2-Perl representation of a boolean, ie. either '' or 1.
#
sub PACK_START {
  my ($self, $cell, $expand) = @_;
  my $cellinfo_list = ($self->{'cellinfo_list'} ||= []);
  if (List::Util::first {$_->{'cell'} == $cell} @$cellinfo_list) {
    croak "this cell renderer already packed into this widget";
  }
  push @$cellinfo_list, { cell => $cell,
                          pack => 'start',
                          expand => $expand };
  $self->_cellinfo_list_changed;
}

# gtk_cell_layout_pack_end
sub PACK_END {
  my ($self, $cell, $expand) = @_;
  my $cellinfo_list = ($self->{'cellinfo_list'} ||= []);
  if (List::Util::first {$_->{'cell'} == $cell} @$cellinfo_list) {
    croak "this cell renderer already packed into this widget";
  }
  push @$cellinfo_list, { cell => $cell,
                          pack => 'end',
                          expand => $expand };
  $self->_cellinfo_list_changed;
}

# gtk_cell_layout_clear
sub CLEAR {
  my ($self) = @_;
  $self->{'cellinfo_list'} = [];
  $self->_cellinfo_list_changed;
}

# gtk_cell_layout_add_attribute
#
# The core widgets like Gtk2::TreeViewColumn seem a bit slack in their
# add_attributes() when the property name is the same as previously added.
# They do a list "prepend" and so end up with the oldest setting applied
# last and thus having priority.  It's hard to believe that's right, either
# an error or the latest setting would surely have to be right.  For now we
# plonk into the hash so a new setting overwrites any previous.
#
sub ADD_ATTRIBUTE {
  my ($self, $cell, $attribute, $column) = @_;
  my $cellinfo =  $self->_get_cellinfo_for_cell ($cell);
  $cellinfo->{'attributes'}->{$attribute} = $column;
  $self->_cellinfo_attributes_changed;
}

# gtk_cell_layout_set_cell_data_func
sub SET_CELL_DATA_FUNC {
  my ($self, $cell, $func, $userdata) = @_;
  my $cellinfo =  $self->_get_cellinfo_for_cell ($cell);
  $cellinfo->{'datafunc'} = $func;
  $cellinfo->{'datafunc_userdata'} = $userdata;
  $self->_cellinfo_attributes_changed;
}

# gtk_cell_layout_clear_attributes
sub CLEAR_ATTRIBUTES {
  my ($self, $cell) = @_;
  my $cellinfo =  $self->_get_cellinfo_for_cell ($cell);
  %{$cellinfo->{'attributes'}} = ();
  $self->_cellinfo_attributes_changed;
}

# gtk_cell_layout_reorder
sub REORDER {
  my ($self, $cell, $position) = @_;
  my $cellinfo_list = $self->{'cellinfo_list'};
  foreach my $i (0 .. $#$cellinfo_list) {
    if ($cellinfo_list->[$i]->{'cell'} == $cell) {
      if ($i == $position) {
        return; # already in the right position
      }
      my $cellinfo = splice @$cellinfo_list, $i, 1;
      splice @$cellinfo_list, $position,0, $cellinfo;
      $self->_cellinfo_list_changed;
      return;
    }
  }
  croak "cell renderer not in this widget";
}

# gtk_cell_layout_get_cells (new in Gtk 2.12)
sub GET_CELLS {
  my ($self) = @_;
  return map {$_->{'cell'}} @{$self->{'cellinfo_list'}};
}

# return the cellinfo record containing the renderer $cell
sub _get_cellinfo_for_cell {
  my ($self, $cell) = @_;
  return ((List::Util::first {$_->{'cell'} == $cell}
           @{$self->{'cellinfo_list'}})
          || croak "cell renderer not in this widget");
}


#------------------------------------------------------------------------------
# extra functions

# When setting cell data, GtkCellView, GtkIconView and GtkTreeViewColumn all
# apply attributes first then run the function, so do the same here.
#
# The freeze_notify across the attributes and func is the same as the core
# viewers.  Don't know what it's for, maybe just the general principle of
# holding back notifying a group of property changes until all are done.
#
# The plain hash used for $cellinfo->{'attributes'} gives the property name
# keys in no particular order.  That should be fine, nobody should expect a
# particular order.
#
# The FreezeNotify mechanism protects against an error throw leaving the
# renderer permanently frozen.  Errors could arise from dodgy value types to
# the $cell->set(), and can arise easily from application code in $func.
#
# Freezing is not done if there's no attributes to set and no func to call.
# This will be unusual, but it saves a couple of cycles on a purely fixed
# renderer like for instance a pixbuf icon.
#
sub _set_cell_data {
  my ($self, $iter, @extra_settings) = @_;
  my $model = $self->{'model'} or return;

  foreach my $cellinfo (@{$self->{'cellinfo_list'}}) {
    my $cell = $cellinfo->{'cell'};
    my $freezer;

    if (my $ahash = $cellinfo->{'attributes'}) {
      if (my @settings = %$ahash) {
        $freezer = Glib::Ex::FreezeNotify->new ($cell);
        for (my $i = 1; $i < @settings; $i += 2) {
          $settings[$i] = $model->get_value ($iter, $settings[$i]);
        }
        $cell->set (@settings);
      }
    }
    if (@extra_settings) {
      $freezer ||= Glib::Ex::FreezeNotify->new ($cell);
      $cell->set (@extra_settings);
    }
    if (my $func = $cellinfo->{'datafunc'}) {
      $freezer ||= Glib::Ex::FreezeNotify->new ($cell);
      $func->($self, $cell, $model, $iter, $cellinfo->{'datafunc_userdata'});
    }
  }
}

sub _cellinfo_starts {
  my ($self) = @_;
  return grep {$_->{'pack'} eq 'start'} @{$self->{'cellinfo_list'}};
}
sub _cellinfo_ends {
  my ($self) = @_;
  return grep {$_->{'pack'} ne 'start'} @{$self->{'cellinfo_list'}};
}

#------------------------------------------------------------------------------
# overridable class callouts

# Not yet 100% certain about these "changed" methods.
# It's maybe, perhaps, possibly, kinda, sorta going to be like the following
# ...

sub _cellinfo_list_changed {
  my ($self) = @_;
  $self->queue_resize;
  $self->queue_draw;
}

sub _cellinfo_attributes_changed {
  my ($self) = @_;
  $self->queue_resize;
  $self->queue_draw;
}

# =head1 METHOD OVERRIDES
#
# The recommended C shown in the synopsis above brings
# C into your C<@ISA> in the usual way, and also
# in the usual way you can override the functions in C with
# your own implementations, probably chaining up to the base ones, perhaps
# not.  The following methods in particular can be intercepted,
#
# =over 4
#
# =item C<< $self->_cellinfo_list_changed () >>
#
# This method is called by C, C, C and C
# to indicate that the list of renderers has changed.  The default
# implementation does a C and C, expecting a new
# size for new renderers and of course new drawing.
#
# Viewer widget code might add to this if it for instance maintains additional
# data relating to the renderers.
#
# =item C<< $self->_cellinfo_attributes_changed () >>
#
# This method is called by C, C and
# C to indicate that renderer attributes have changed.
# The default implementation does a C and C,
# expecting a possible new size or new drawing from different attributes.
#
# Viewer widget code might add to this, for instance to invalidate renderer
# display size data if maybe it tries to cache that for on-screen or nearby
# rows.
#
# =back


#------------------------------------------------------------------------------
# Gtk2::Buildable interface functions

# This is the same as _gtk_cell_layout_buildable_add_child(), in particular
# as per that function it always does "pack_start" and false for the expand
# parameter.
#
sub ADD_CHILD {
  my ($self, $builder, $child, $type) = @_;
  $self->pack_start ($child, 0);
}

# In a ... block under one of our new viewer widget, we
# handle ... to make add_attributes calls.
#
# $self is a viewer widget, ie. someone using us, and $child is the
# Gtk2::CellRenderer child being added to the viewer.
#
sub CUSTOM_TAG_START {
  my ($self, $builder, $child, $tagname) = @_;
  if ($child && $tagname eq 'attributes') {
    require Gtk2::Ex::CellLayout::BuildAttributes;
    return Gtk2::Ex::CellLayout::BuildAttributes->new (cell_layout => $self,
                                                       cell_renderer=> $child);
  } else {
    return undef;
  }
}


1;
__END__