NAME

Gtk2::Ex::TreeModelFilter::Change -- change-rows mix-in for TreeModelFilter subclasses

SYNOPSIS

 package MyNewFilterModel;
 use Gtk2;
 use base 'Gtk2::Ex::TreeModelFilter::Change';

 use Glib::Object::Subclass
   'Gtk2::TreeModelFilter',
   properties => [   ];

DESCRIPTION

Gtk2::Ex::TreeModelFilter::Change is designed as a multi-inheritance mix-in for Perl sub-classes of Gtk2::TreeModelFilter. It provides the following methods

    append
    clear
    insert
    insert_with_values
    insert_after
    insert_before
    move_after
    move_before
    prepend
    remove
    reorder
    swap
    set
    set_value

They work like the corresponding Gtk2::ListStore and Gtk2::TreeStore methods and make changes by calling to the corresponding methods on the filter's child-model.

The child model doesn't have to be a Gtk2::ListStore or Gtk2::TreeStore, it can be anything which implements the same methods.

NOTES

Empty row -- append, prepend, insert, insert_before, insert_after

These functions all insert an empty new row. If your filter is setup to exclude empty rows then the new row is created in the child, but then doesn't appear in the filtered view! You probably don't want to do that.

Currently the functions return undef instead of an iter if the new row is not visible. insert_with_values() can be used to do a combination insert and set to avoid an empty row.

Gtk 2.6 -- insert_with_values

insert_with_values() on ListStore and TreeStore is new in Gtk 2.6. The mix-in method is always provided by TreeModelFilter::Change and always calls to the child model but you might have to check what the child model has if you're using an oldish Gtk.

Parent node arg -- insert_after, insert_before, insert_with_values

These functions take either just a position number like ListStore, or a parent node iter plus a position like TreeStore,

    $filter->insert_after ($pos)                # ListStore
    $filter->insert_after ($parent_iter, $pos)  # TreeStore

The same one or two arguments are then passed through to the child model.

Data access -- get, set

get() and set() fetch and store row data. Make sure Gtk2::Ex::TreeModelFilter::Change is before Glib::Object in your @ISA to have these versions instead of the object property get() and set(). A use base before Glib::Object::Subclass as shown in the synopsis above will accomplish that,

    use base 'Gtk2::Ex::TreeModelFilter::Change';
    use Glib::Object::Subclass 'Gtk2::TreeModelFilter';

The object properties are always available under the names get_property() and set_property(), the same as in Gtk2::ListStore and Gtk2::TreeStore.

    $myfilter->set_property (propname => $propvalue);

Filtered out rows -- set, set_value

If a set() or set_value() of new data causes the child row to be filtered out, ie. to not appear in $filter, then the given $iter no longer refers to a valid row in the filtered model and cannot be used any more.

Currently the iter is not zapped to zeros, perhaps in the future it will be (it's extra work to check if still available, but would help keep you safe).

Data transforms -- set, set_value, insert_with_values

No transformations are applied to stored data, so if you're using a "modify" function to present different types or contents there's no way to reverse-modify. Hopefully this will be possible in the future.

Any columns which are unchanged by a modify function can be stored, and in particular you can use a modify function just to add extra columns intended to be read-only.

SEE ALSO

Gtk2::TreeModelFilter, Gtk2::TreeModel

Gtk2::Ex::TreeModelFilter::DragDest and Gtk2::Ex::TreeModelFilter::Draggable, which propagate drag-and-drop drops to the child model

HOME PAGE

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

LICENSE

Copyright 2008, 2009, 2010, 2011, 2012 Kevin Ryde

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