NAME

App::Chart::Gtk2::Ex::TreeRowPosition -- position within a list type tree model

SYNOPSIS

 use App::Chart::Gtk2::Ex::TreeRowPosition;
 my $rowpos = App::Chart::Gtk2::Ex::TreeRowPosition->new (model => $my_model);

 my $path = $rowpos->next_path;

OBJECT HIERARCHY

App::Chart::Gtk2::Ex::TreeRowPosition is a subclass of Glib::Object,

    Glib::Object
      App::Chart::Gtk2::Ex::TreeRowPosition

DESCRIPTION

A App::Chart::Gtk2::Ex::TreeRowPosition object keeps track of a position in a list type TreeModel (meaning any Glib::Object implementing the Gtk2::TreeModel interface). It's intended to track a user's position in a list of files, documents, etc.

The position can be "at" a given row, or "before" or "after" one. The position adjusts with inserts, deletes and reordering to follow that row. Special positions "start" and "end" are the ends of the list, not following any row.

A row data "key" scheme allows a row to be followed across a delete and re-insert done by TreeView drag-and-drop, or by a user delete and undo, or re-add.

TreeRowReference

Gtk2::TreeRowReference does a similar thing to TreeRowPosition, but a TreeRowReference is oriented towards tracking just a particular row. If its row is deleted the TreeRowReference points nowhere. TreeRowPosition instead then keeps a position in between remaining rows.

FUNCTIONS

$rowpos = App::Chart::Gtk2::Ex::TreeRowPosition->new (key => value, ...)

Create and return a new TreeRowPosition object. Optional key/value pairs set initial properties as per Glib::Object->new. Eg.

    my $rowpos = App::Chart::Gtk2::Ex::TreeRowPosition->new (model => $my_model,
                                               key_column => 2);

$model = $rowpos->model

$type = $rowpos->type

$path = $rowpos->path

Return the model, type and index properties described below.

$iter = $rowpos->iter

Return a Gtk2::TreeIter which is the current row. If $rowpos is not type "at" or the index is out of range then the return is undef.

$path = $rowpos->next_path

$path = $rowpos->prev_path

$iter = $rowpos->next_iter

$iter = $rowpos->prev_iter

Move $rowpos to the next or previous row from its current position and return an integer index or Gtk2::TreeIter for the new position. If there's no more rows in the respective direction (including if the model is empty) then the return is undef instead.

$rowpos->goto ($path)

$rowpos->goto ($path, $type)

Move $rowpos to the given $path row. The $type parameter defaults to "at", or you can give "before" or "after" instead.

    $rowpos->goto (4, 'before');

goto is the same as setting the respective property values (but changed in one operation).

$rowpos->goto_start

$rowpos->goto_end

Move $rowpos to the start or end of its model, so that next returns the first row or prev the last row (respectively). These functions are the same as setting the type property to "start" or "end", respectively.

PROPERTIES

model (Glib::Object implementing Gtk2::TreeModel)

The model to operate on.

type (App::Chart::Gtk2::Ex::TreeRowPosition::Type enum, default start)

Enum values "at", "before", "after", "start", "end".

The default type is "start", but you can Initialize to a particular row explicitly,

    my $rowpos = App::Chart::Gtk2::Ex::TreeRowPosition->new (model => $my_model,
                                               type  => 'at',
                                               index => 3);

path (Gtk2::TreePath, default an empty path)

Current path in the model.

key-column (integer, default -1)

Column number of row key data. The default -1 means no key column.

notify signals are emitted for path and/or type when model row changes alter those values, in the usual way. A notify handler must not insert, delete or reorder model rows because doing so may invalidate the path and/or iter objects passed to further handlers on the model.

SIGNALS

key-extract, called (treerowpos, model, path, iter)

Callback to extract a key from a row. When set it's called

key-equal, called (treerowpos, string, string)

Row key equality function. The default handler compares with eq.

OTHER NOTES

When a TreeRowPosition is "at" a given row and that row is deleted there's a choice between becoming "after" the previous row, or "before" the next row. This can make a difference in a reorder if the two rows move to different places. The current code always uses "after the previous", or if the first row is deleted then "start".

SEE ALSO

Gtk2::TreeModel, Gtk2::TreeRowReference