NAME
Gtk2::Ex::CellLayout::Base -- basic Gtk2::CellLayout implementation functions
SYNOPSIS
package MyNewViewer;
use Gtk2;
use base 'Gtk2::Ex::CellLayout::Base';
use Glib::Object::Subclass
Gtk2::Widget::,
interfaces => [ 'Gtk2::CellLayout', 'Gtk2::Buildable' ],
properties => [ ... ];
sub my_expose {
my ($self, $event) = @_;
$self->_set_cell_data;
foreach my $cellinfo (@{$self->{'cellinfo_list'}}) {
next unless $cell->{'pack'} eq 'start';
$cellinfo->{'cell'}->render (...);
}
...
}DESCRIPTION
Gtk2::Ex::CellLayout::Base provides a basic set of functions for use by new data viewer widgets written in Perl and wanting to implement the Gtk2::CellLayout interface. This means
PACK_START
PACK_END
CLEAR
ADD_ATTRIBUTE
CLEAR_ATTRIBUTES
SET_CELL_DATA_FUNC
REORDER
GET_CELLSThe functions maintain a list of Gtk2::CellRenderer objects packed into the viewer widget by the application, with associated attribute settings or data setup function.
Gtk2::Ex::CellLayoutBase is designed as a multiple-inheritance superclass to be brought in with use base per the synopsis above (see base). You can enhance it or override it by writing your own versions of the functions offered, chaining (or not) to the originals with SUPER in the usual way.
CELL INFO LIST
Gtk2::Ex::CellLayout::Base keeps information on the added cell renderers in $self->{'cellinfo_list'} on the viewer widget. This field is an array reference, created when first needed, and each element in the array is a hash reference.
[ { cell => $renderer1, ... },
{ cell => $renderer2, ... },
... ]The element fields are
cell Gtk2::CellRenderer object
pack string 'start' or 'end'
expand boolean
attributes hash ref { propname => colnum }
datafunc code ref or undef
datafunc_userdata any scalarcell is the renderer object added in by pack_start or pack_end, and expand is the flag passed in those calls. The pack field is "start" or "end" according to which function was used. "start" and "end" values are per the Gtk2::PackType enumeration, though that enum doesn't normally arise in the context of a viewer widget.
attributes is a hash table of property name to column number built by add_attribute or set_attributes. datafunc and datafunc_userdata come from set_cell_data_func. All these are used when preparing the renderers to draw a particular row of the Gtk2::TreeModel.
The widget size_request and expose operations are the two most obvious places the cell information is needed. Both will want to prepare the renderers with data from the model, then ask the size, and in the case of expose do some drawing. The following function is designed to prepare the renderers
$self->_set_cell_data ($iter, [propname=>value])-
Set the property values in all the cell renderers packed into
$self, ready to draw the model row given by$iter. The model object is expected to be in$self->{'model'}and the$self->{'cellinfo_list'}attributes described above are used.Extra
propname=>valueparameters can be given, to be applied to all the renderers. For example theis_expanderandis_expandedproperties could be set according to the viewer's state (and whether the model row has children and can be expanded).
Here's a minimal size_request handler for a viewer like the core Gtk2::CellView which displays a single row of a model, with each renderer one after the other horizontally. The width is the total of all renderers, and the height is the maximum among them. It could look like
sub do_size_request {
my ($self, $requisition) = @_;
my $model = $self->{'model'};
my $iter = $model->iter_nth_child (undef, $self->{'rownum'});
$self->_set_cell_data ($iter);
my $total_width = 0;
my $max_height = 0;
foreach my $cellinfo (@{$self->{'cellinfo_list'}}) {
my $cell = $cellinfo->{'cell'};
my (undef,undef, $width,$height)
= $cell->get_size ($self, undef);
$total_width += $width;
$max_height = max ($max_height, $height);
}
$requisition->width ($total_width);
$requisition->height ($max_height);
}An expose handler is a little more complicated, firstly the cells shouldn't drawn in cellinfo_list order, but instead the start ones from the left, then the end ones from the right. And the expand flag is meant to indicate which cells (if any) should grow to fill available space when there's more than needed.
BUILDABLE INTERFACE
Gtk2::Ex::CellLayout::Base provides the following functions for use by a viewer widget also implementing the Gtk2::Buildable interface.
ADD_CHILD
CUSTOM_TAG_STARTTo use them you must put "Gtk2::Buildable" in your interfaces list along with Gtk2::CellLayout (as shown in "SYNOPSIS" above). If you don't then you can still create a viewer object with buildable, but not add renderers as "children". As with the CellLayout functions above you can override with your own versions and chain (or not) with SUPER in the usual way.
The functions implement the same syntax as the core widgets like Gtk2::TreeViewColumn. Renderers are added to layout objects with <child>, and after the <object> form an <attributes> does the equivalent of add_attribute() setups. The GtkTreeView documentation has an example of GtkTreeViewColumn. Here's another with a hypothetical MyNewViewer class,
<object class="MyNewViewer" id="myviewer">
<property name="model">myliststore</property>
<child>
<object class="GtkCellRendererText" id="myrenderer">
<property name="underline">single</property>
</object>
<attributes>
<attribute name="text">0</attribute>
</attributes>
</child>
</object>A renderer "child" added this way uses pack_start with "expand" false. This is the same as the core widgets, and like the core there's currently no way to instead use pack_end or expand. (child has a type option which might be pressed into service, or GtkBox has expand etc as settable properties, but we'd prefer to let the Gtk core take the lead on that.)
As of Gtk2-Perl 1.183 there's no chaining up to tag handlers in widget superclasses, which means a buildable interface like this loses anything those superclasses add to GtkBuilder's standard forms. In particular for example you loose <accelerator> and <accessibility> from GtkWidget. Not sure how bad that is in practice. Hopefully a future Gtk2-Perl will allow chaining, or do it automatically.
OTHER NOTES
The cellinfo_list idea is based on the similar cell info lists maintained inside the core Gtk2::TreeViewColumn, Gtk2::CellView and Gtk2::IconView widgets. Elements are hashes so there's room for widget code to hang extra information, like the "editing" flag of IconView, or the focus flag and calculated width TreeViewColumn keeps.
The _set_cell_data function provided above is also similar to what the core widgets do. Gtk2::TreeViewColumn even makes its version of that public as $column->cell_set_cell_data. It's probably equally valid to setup one renderer at a time as used, rather than all at once; so perhaps in the future Gtk2::Ex::CellLayout::Base might offer something for that, maybe even as a method on the cellinfo_list elements if they became objects as such.
The display layout intended by pack_start and pack_end isn't well described in the GtkCellLayout documentation, but it's the same as GtkBox so see there for details. You might wonder why cellinfo_list isn't maintained with starts and ends separated in the first place, since that's what will be wanted for drawing. The reason is the reorder method which works in terms of renderers in sequence, with pack_start and pack_end together, counting from 0. This makes more sense in GtkBox where pack type can be changed later (something CellLayout doesn't do).
Perhaps in the future Gtk2::Ex::CellLayout::Base could offer functions to pick the start elements out from the ends. But if your expose code uses two loops in the style of say the core Gtk2::CellView then it's just as easy to skip the opposite ones as you go. Otherwise a couple of greps and reverse gives you all elements in display order if you want that. Eg.
my @disps = (grep ({$_->{'pack'} eq 'start'} @$cellinfo_list),
reverse grep {$_->{'pack'} eq 'end'} @$cellinfo_list);The GET_CELLS method is always provided, but it's only used if Gtk2-Perl was compiled against Gtk version 2.12 or higher which is when the gtk_cell_layout_get_cells function was introduced. Within viewer widget code if you want all the renderers (which is simply the cell fields picked out of cellinfo_list) then you can call capital GET_CELLS rather than worry whether lowercase get_cells is available or not.
SEE ALSO
Gtk2::CellLayout, Gtk2::CellRenderer
HOME PAGE
http://www.geocities.com/user42_kevin/gtk2-ex-celllayout-base/index.html
LICENSE
Copyright 2007, 2008 Kevin Ryde
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 http://www.gnu.org/licenses/.