NAME

Gtk2::Ex::TiedListColumn - tie an array to a column of a list TreeModel

SYNOPSIS

 use Gtk2::Ex::TiedListColumn;
 # any sort of model ...
 my $my_model = Gtk2::ListStore->new ('Glib::String');

 my @array;
 tie @array, 'Gtk2::Ex::TiedListColumn', $my_model, 0;

 my $aref = Gtk2::Ex::TiedListColumn->new ($my_model, 5);

DESCRIPTION

TiedListColumn ties an array to a single column of a list-type Gtk2::TreeModel object so that reading from the array reads from the model. If the model implements modification functions like set, insert and remove in the style of Gtk2::ListStore then writing to the array modifies the model too.

Most tie things tend to be better in concept than actuality and TiedListColumn is no exception. The benefit is being able to apply generic array algorithms to data in a model, eg. a binary search, uniqifying, or perl's array slice manipulation. As a starting point it's good, but a tie is a fair slowdown and model access is not very fast anyway, so for big crunching you're likely to end up copying data out to an ordinary array anyway. (See column_contents in Gtk2::Ex::TreeModelBits for help on that).

delete and exists

A TreeModel has no per-row notion of "exists". If you delete an element in the middle of the array then it's cleared to undef, but exists is still true, unlike an ordinary perl array where exists is false in that case. (The tied exists method simply checks whether the given index is within the number of rows in the model.)

Deleting the endmost element of a TiedListColumn works the same as an ordinary array though. In this case the row is removed from the model, shortening it, and exists is then false (beyond the end of the model).

Other Ways To Do It

TiedListColumn differs from Gtk2::Ex::TiedList (part of Gtk2::Ex::Simple::List) in presenting just a single column of the model, whereas TiedList gives array elements which are TiedRow objects presenting a sub-array of all the values in the row. TiedListColumn is good if your model only has one column, or only one you're interested in.

TiedListColumn uses insert_with_values in various places. That function is only available for Gtk2::ListStore in Gtk 2.6 and higher, so ensure your Gtk is new enough if you're extending a tied ListStore (push, unshift, or splice insertion).

FUNCTIONS

tie @var, 'Gtk2::Ex::TiedListColumn', $model

tie @var, 'Gtk2::Ex::TiedListColumn', $model, $column

Tie array variable @var to the given $model so it accesses the model contents in $column. The default column is 0, which is the first column.

$model can be any Glib object implementing the Gtk2::TreeModel interface. It's expected to be a list style model, but currently that's not enforced.

Gtk2::Ex::TiedListColumn->new ($model)

Gtk2::Ex::TiedListColumn->new ($model, $column)

Return an arrayref which is tied to $model and $column (default 0). For example

    my $aref = Gtk2::Ex::TiedListColumn->new ($model, 6);

is the same as

    tie (my @array, 'Gtk2::Ex::TiedListColumn', $model, 6);
    my $aref = \@array;

If you want your own @array as such then the plain tie is easier. If you want an arrayref to pass around to other funcs then new saves a line of code.

Object Methods

The tie object associated with the array (as returned by the tie or obtained later with tied) has the following methods.

$tlcobj->model

$tlcobj->column

Return the underlying model object or column number. Eg.

    my @array;
    tie @array, 'Gtk2::Ex::TiedListColumn', $model;
    ...
    my $tlcobj = tied(@array);
    print $tlcobj->column;  # column 0

Or likewise through an arrayref

    my $aref = Gtk2::Ex::TiedListColumn->new($model);
    ...
    my $model = tied(@$aref)->model;

SEE ALSO

Gtk2::TreeModel, Gtk2::Ex::Simple::List (for Gtk2::Ex::Simple::TiedList), Gtk2::Ex::TiedTreePath, Gtk2::Ex::TreeModelBits

HOME PAGE

http://user42.tuxfamily.org/gtk2-ex-tiedlistcolumn/

COPYRIGHT

Copyright 2008, 2009, 2010 Kevin Ryde

Gtk2-Ex-TiedListColumn 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-TiedListColumn 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-TiedListColumn. If not, see http://www.gnu.org/licenses/.