view release on metacpan or  search on metacpan

xs/GtkTreeModel.xs  view on Meta::CPAN

=cut

##
## 
##

=for position post_methods

=head1 CREATING A CUSTOM TREE MODEL

GTK+ provides two model implementations, Gtk2::TreeStore and Gtk2::ListStore,
which should be sufficient in most cases.  For some cases, however, it is
advantageous to provide a custom tree model implementation.  It is possible
to create custom tree models in Perl, because we're cool like that.

To do this, you create a Glib::Object derivative which implements the 
Gtk2::TreeModel interface; this is gtk2-perl-speak for "you have to add
a special key when you register your object type."  For example:

  package MyModel;
  use Gtk2;
  use Glib::Object::Subclass
      Glib::Object::,
      interfaces => [ Gtk2::TreeModel:: ],
      ;

This will cause perl to call several virtual methods with ALL_CAPS_NAMES
when Gtk+ attempts to perform certain actions on the model.  You simply
provide (or override) those methods.

=head2 TREE ITERS

Gtk2::TreeIter is normally an opaque object, but on the implementation side
of a Gtk2::TreeModel, you have to define what's inside.  The virtual methods
described below deal with iters as a reference to an array containing four
values:

=over

=item o stamp (integer)

A number unique to this model.

=item o user_data (integer)

An arbitrary integer value.

=item o user_data2 (scalar)

An arbitrary reference.  Will not persist.  May be undef.

=item o user_data3 (scalar)

An arbitrary reference.  Will not persist.  May be undef.

=back

The two references, if used, will generally be to data within the model,
like a row array, or a node object in a tree or linked list.  Keeping the
things referred to alive is the model's responsibility.  An iter doesn't
make them persist, and if the things are destroyed then any iters still
containing them will become invalid (and result in memory corruption if
used).  An iter only has to remain valid until the model contents change, so
generally anything internal to the model is fine.

=head2 VIRTUAL METHODS

An implementation of

=over

=item treemodelflags = GET_FLAGS ($model)

=item integer = GET_N_COLUMNS ($model)

=item string = GET_COLUMN_TYPE ($model, $index)

=item ARRAYREF = GET_ITER ($model, $path)

See above for a description of what goes in the returned array reference.

=item treepath = GET_PATH ($model, ARRAYREF)

=item scalar = GET_VALUE ($model, ARRAYREF, $column)

Implements $treemodel->get().

=item ARRAYREF = ITER_NEXT ($model, ARRAYREF)

=item ARRAYREF = ITER_CHILDREN ($model, ARRAYREF)

=item boolean = ITER_HAS_CHILD ($model, ARRAYREF)

=item integer = ITER_N_CHILDREN ($model, ARRAYREF)

=item ARRAYREF = ITER_NTH_CHILD ($model, ARRAYREF, $n)

=item ARRAYREF = ITER_PARENT ($model, ARRAYREF)

=item REF_NODE ($model, ARRAYREF)

Optional.

=item UNREF_NODE ($model, ARRAYREF)

Optional.

=back

=cut

=for position post_signals

Note that currently in a Perl subclass of an object implementing
C<Gtk2::TreeModel>, the class closure, ie. class default signal
handler, for the C<rows-reordered> signal is called only with an
integer address for the reorder array parameter, not a Perl arrayref
like a handler installed with C<signal_connect> receives.  It works to
C<signal_chain_from_overridden> with the address, but it's otherwise
fairly useless and will likely change in the future.