NAME

App::Chart::Gtk2::Ex::ListOfListsModel -- two-level tree model presenting lists

SYNOPSIS

 use App::Chart::Gtk2::Ex::ListOfListsModel;
 my $ll = App::Chart::Gtk2::Ex::ListOfListsModel->new (list_model => $mmod);

OBJECT HIERARCHY

App::Chart::Gtk2::Ex::ListOfListsModel is a subclass of Glib::Object.

    Glib::Object
      App::Chart::Gtk2::Ex::ListOfListsModel

and implements the interfaces

    Gtk2::TreeModel
    Gtk2::TreeDragSource
    Gtk2::TreeDragDest

DESCRIPTION

App::Chart::Gtk2::Ex::ListOfListsModel presents a set of list models as a two level tree,

    Toplevel row 0
        Submodel 0 row 0
        Submodel 0 row 1
        Submodel 0 row 2
    Toplevel row 1
        Submodel 1 row 0
        Submodel 1 row 1

The list-model property is a model containing submodel objects. Column 0 in list-model should be the submodel objects. Changes in that list-model and changes in the submodels are all reported up through the ListOfLists.

The columns in the ListOfLists are those of list-model followed by those of the submodels. The submodels are expected to all have the same number of columns and column types. So

    +-----------+-----------+-----------+-----------+-----------+
    | LL col 0  | LL col 1  | LL col 2  | LL col 3  | LL col 4  |
    +-----------+-----------+-----------+-----------+-----------+

with 2 columns in list-store and 3 in the submodels would be

    +-----------+-----------+-----------+-----------+-----------+
    | top col 0 | top col 1 | sub col 0 | sub col 1 | sub col 2 |
    +-----------+-----------+-----------+-----------+-----------+

Drag and Drop

ListOfLists implements TreeDragSource and TreeDragDest, allowing rows to be moved by dragging in a Gtk2::TreeView or similar. Dragging is delegated to the list-model and the submodels. So a row can be dragged if its model implements TreeDragSource, and a position can be a drop if its model implements TreeDragDest. The effect is that you can drag to re-order the toplevel rows, and drag within the submodels and perhaps between them.

Dragging between models depends on the destination model being prepared to accept the source row offered. For example as of Gtk 2.12 a Gtk2::ListStore only accepts its own rows (ie. a re-ordering of itself), not rows from other models, even if the column types seem compatible. If that's not enough for you the suggestion is to wrap or subclass the offending models to make them accept more.

PROPERTIES

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

A model containing the submodels to present. It's expected to be a list type model (ie. just one level), but currently that's not checked or enforced.

Currently when the list-model property is changed there's no row-inserted / row-deleted etc signals emitted by the ListofLists to announce the new or altered data presented. Perhaps this will change. The disadvantage is that changing to or from a big model could generate thousands of fairly pointless signals. The suggestion is to treat list-model as if it were "construct-only" and make a new ListOfLists for a new set of models.

FUNCTIONS

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

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

    my $ll = App::Chart::Gtk2::Ex::ListOfListsModel->new (list_model => $mmod);

SIGNALS

The TreeModel interface as implemented by ListOfLists provides the following usual signals

    row-changed    ($ll, $path, $iter, $userdata)
    row-inserted   ($ll, $path, $iter, $userdata)
    row-deleted    ($ll, $path, $userdata)
    rows-reordered ($ll, $path, $iter, $arrayref, $userdata)

When a change occurs in a sub-model the corresponding signal is reported up through the ListOfLists too. Of course the path and iter reported are in the list-of-lists tree coordinates and iters, not the sub-models'.

LIMITATIONS

The ref_node and unref_node methods are no-ops. The intention is to apply them down on the sub-models, but hopefully without needing lots of bookkeeping in the ListOfLists as to what's currently reffed.

It mostly works to have the same submodel appear in multiple toplevel rows, it's simply presented at each of those points. The row-deleted and row-inserted signals are emitted on the ListOfLists the right number of times, but the multiple changes are all present in the data as of the first emit, which could potentially confuse handler code. (The idea could be some sort of temporary index mapping to make the changes seem one-at-a-time for the handlers.)

SEE ALSO

Gtk2::TreeModel, Gtk2::ListStore, Glib::Object

Gtk2::Ex::ListModelConcat, a similar thing as one level.

HOME PAGE

http://user42.tuxfamily.org/gtk2-ex-listoflistsmodel/index.html

COPYRIGHT

Copyright 2008, 2009, 2010, 2011 Kevin Ryde

Chart 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.

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

cpanm App::Chart

perl -MCPAN -e shell
install App::Chart