NAME¶

Gtk2::Ex::Simple::List - A simple interface to Gtk2's complex MVC list widget

SYNOPSIS¶

  use Glib qw(TRUE FALSE);
  use Gtk2 '-init';
  use Gtk2::Ex::Simple::List;
  my $slist = Gtk2::Ex::Simple::List->new (
                'Text Field'    => 'text',
                'Markup Field'  => 'markup',
                'Int Field'     => 'int',
                'Double Field'  => 'double',
                'Bool Field'    => 'bool',
                'Scalar Field'  => 'scalar',
                'Pixbuf Field'  => 'pixbuf',
              );
  @{$slist->{data}} = (
          [ 'text', 1, 1.1,  TRUE, $var, $pixbuf ],
          [ 'text', 2, 2.2, FALSE, $var, $pixbuf ],
  );
  # (almost) anything you can do to an array you can do to 
  # $slist->{data} which is an array reference tied to the list model
  push @{$slist->{data}}, [ 'text', 3, 3.3, TRUE, $var, $pixbuf ];
  # mess with selections
  $slist->get_selection->set_mode ('multiple');
  $slist->get_selection->unselect_all;
  $slist->select (1, 3, 5..9); # select rows by index
  $slist->unselect (3, 8); # unselect rows by index
  @sel = $slist->get_selected_indices;
  # simple way to make text columns editable
  $slist->set_column_editable ($col_num, TRUE);
  # Gtk2::Ex::Simple::List derives from Gtk2::TreeView, so all methods
  # on a treeview are available.
  $slist->set_rules_hint (TRUE);
  $slist->signal_connect (row_activated => sub {
          my ($sl, $path, $column) = @_;
          my $row_ref = $sl->get_row_data_from_path ($path);
          # $row_ref is now an array ref to the double-clicked row's data.
      });
  # turn an existing TreeView into a SimpleList; useful for
  # Glade-generated interfaces.
  $simplelist = Gtk2::Ex::Simple::List->new_from_treeview (
                    $glade->get_widget ('treeview'),
                    'Text Field'    => 'text',
                    'Int Field'     => 'int',
                    'Double Field'  => 'double',
                 );

ABSTRACT¶

SimpleList is a simple interface to the powerful but complex Gtk2::TreeView and Gtk2::ListStore combination, implementing using tied arrays to make thing simple and easy.

DESCRIPTION¶

Gtk2 has a powerful, but complex MVC (Model, View, Controller) system used to implement list and tree widgets. Gtk2::Ex::Simple::List automates the complex setup work and allows you to treat the list model as a more natural list of lists structure.

After creating a new Gtk2::Ex::Simple::List object with the desired columns you may set the list data with a simple Perl array assignment. Rows may be added or deleted with all of the normal array operations. You can treat the "data" member of the Simple::List object as an array reference, and manipulate the list data with perl's normal array operators.

A mechanism has also been put into place allowing columns to be Perl scalars. The scalar is converted to text through Perl's normal mechanisms and then displayed in the list. This same mechanism can be expanded by defining arbitrary new column types before calling the new function.

OBJECT HIERARCHY¶

 Glib::Object
 +--- Gtk2::Object
      +--- Gtk2::Widget
           +--- Gtk2::TreeView
                +--- Gtk2::Ex::Simple::List

METHODS¶

$slist = Gtk2::Ex::Simple::List->new ($cname, $ctype, ...)

 text    normal text strings
 markup  pango markup strings
 int     integer values
 double  double-precision floating point values
 bool    boolean values, displayed as toggle-able checkboxes
 scalar  a perl scalar, displayed as a text string by default
 pixbuf  a Gtk2::Gdk::Pixbuf

$slist = Gtk2::Ex::Simple::List->new_from_treeview ($treeview, $cname, $ctype, ...)

$slist->set_data_array ($arrayref)

@indices = $slist->get_selected_indices

Return the indices of the selected rows in the ListStore.

$slist->get_row_data_from_path ($path)

$slist->select ($index, ...);

$slist->unselect ($index, ...);

$slist->set_column_editable ($index, $editable)

boolean = $slist->get_column_editable ($index)

Gtk2::Ex::Simple::List->add_column_type ($type_name, ...)

  # just displays the value in a scalar as 
  # Perl would convert it to a string
  Gtk2::Ex::Simple::List->add_column_type( 'a_scalar', 
          type     => 'Glib::Scalar',
          renderer => 'Gtk2::CellRendererText',
          attr     => sub {
               my ($treecol, $cell, $model, $iter, $col_num) = @_;
               my $info = $model->get ($iter, $col_num);
               $cell->set (text => $info);
          }
     );
  # sums up the values in an array ref and displays 
  # that in a text renderer
  Gtk2::Ex::Simple::List->add_column_type( 'sum_of_array', 
          type     => 'Glib::Scalar',
          renderer => 'Gtk2::CellRendererText',
          attr     => sub {
               my ($treecol, $cell, $model, $iter, $col_num) = @_;
               my $sum = 0;
               my $info = $model->get ($iter, $col_num);
               foreach (@$info)
               {
                   $sum += $_;
               }
               $cell->set (text => $sum);
          } 
     );

MODIFYING LIST DATA¶

After creating a new Gtk2::Ex::Simple::List object there will be a member called "data" which is a tied array. That means data may be treated as an array, but in reality the data resides in something else. There is no need to understand the details of this it just means that you put data into, take data out of, and modify it just like any other array. This includes using array operations like push, pop, unshift, and shift. For those of you very familiar with perl this section will prove redundant, but just in case:

  Adding and removing rows:
  
    # push a row onto the end of the list
    push @{$slist->{data}}, [col1_data, col2_data, ..., coln_data];
    # pop a row off of the end of the list
    $rowref = pop @{$slist->{data}};
    # unshift a row onto the beginning of the list
    unshift @{$slist->{data}}, [col1_data, col2_data, ..., coln_data];
    # shift a row off of the beginning of the list
    $rowref = shift @{$slist->{data}};
    # delete the row at index $n, 0 indexed
    splice @{ $slist->{data} }, $n, 1;
    # set the entire list to be the data in a array
    @{$slist->{data}} = ( [row1, ...], [row2, ...], [row3, ...] );
  Getting at the data in the list:
  
    # get an array reference to the entire nth row
    $rowref = $slist->{data}[n];
    # get the scalar in the mth column of the nth row, 0 indexed
    $val = $slist->{data}[n][m];
    # set an array reference to the entire nth row
    $slist->{data}[n] = [col1_data, col2_data, ..., coln_data];
    # get the scalar in the mth column of the nth row, 0 indexed
    $slist->{data}[n][m] = $rowm_coln_value;

SEE ALSO¶

Perl(1), Glib(3pm), Gtk2(3pm), Gtk2::TreeView(3pm), Gtk2::TreeModel(3pm), Gtk2::ListStore(3pm).

AUTHORS¶

 muppet <scott at asofyet dot org>
 Ross McFarland <rwmcfa1 at neces dot com>
 Gavin Brown <gavin dot brown at uk dot com>

COPYRIGHT AND LICENSE¶

Copyright 2004 by the Gtk2-Perl team.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library 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 Library General Public License for more details.

You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307 USA.