1Gtk2::Ex::Simple::List(U3s)er Contributed Perl DocumentatGitokn2::Ex::Simple::List(3)
2
3
4

NAME

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

SYNOPSIS

10         use Glib qw(TRUE FALSE);
11         use Gtk2 '-init';
12         use Gtk2::Ex::Simple::List;
13
14         my $slist = Gtk2::Ex::Simple::List->new (
15                       'Text Field'    => 'text',
16                       'Markup Field'  => 'markup',
17                       'Int Field'     => 'int',
18                       'Double Field'  => 'double',
19                       'Bool Field'    => 'bool',
20                       'Scalar Field'  => 'scalar',
21                       'Pixbuf Field'  => 'pixbuf',
22                     );
23
24         @{$slist->{data}} = (
25                 [ 'text', 1, 1.1,  TRUE, $var, $pixbuf ],
26                 [ 'text', 2, 2.2, FALSE, $var, $pixbuf ],
27         );
28
29         # (almost) anything you can do to an array you can do to
30         # $slist->{data} which is an array reference tied to the list model
31         push @{$slist->{data}}, [ 'text', 3, 3.3, TRUE, $var, $pixbuf ];
32
33         # mess with selections
34         $slist->get_selection->set_mode ('multiple');
35         $slist->get_selection->unselect_all;
36         $slist->select (1, 3, 5..9); # select rows by index
37         $slist->unselect (3, 8); # unselect rows by index
38         @sel = $slist->get_selected_indices;
39
40         # simple way to make text columns editable
41         $slist->set_column_editable ($col_num, TRUE);
42
43         # Gtk2::Ex::Simple::List derives from Gtk2::TreeView, so all methods
44         # on a treeview are available.
45         $slist->set_rules_hint (TRUE);
46         $slist->signal_connect (row_activated => sub {
47                 my ($sl, $path, $column) = @_;
48                 my $row_ref = $sl->get_row_data_from_path ($path);
49                 # $row_ref is now an array ref to the double-clicked row's data.
50             });
51
52         # turn an existing TreeView into a SimpleList; useful for
53         # Glade-generated interfaces.
54         $simplelist = Gtk2::Ex::Simple::List->new_from_treeview (
55                           $glade->get_widget ('treeview'),
56                           'Text Field'    => 'text',
57                           'Int Field'     => 'int',
58                           'Double Field'  => 'double',
59                        );
60

ABSTRACT

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

DESCRIPTION

67       Gtk2 has a powerful, but complex MVC (Model, View, Controller) system
68       used to implement list and tree widgets.  Gtk2::Ex::Simple::List
69       automates the complex setup work and allows you to treat the list model
70       as a more natural list of lists structure.
71
72       After creating a new Gtk2::Ex::Simple::List object with the desired
73       columns you may set the list data with a simple Perl array assignment.
74       Rows may be added or deleted with all of the normal array operations.
75       You can treat the "data" member of the Simple::List object as an array
76       reference, and manipulate the list data with perl's normal array
77       operators.
78
79       A mechanism has also been put into place allowing columns to be Perl
80       scalars.  The scalar is converted to text through Perl's normal
81       mechanisms and then displayed in the list. This same mechanism can be
82       expanded by defining arbitrary new column types before calling the new
83       function.
84

OBJECT HIERARCHY

86        Glib::Object
87        +--- Gtk2::Object
88             +--- Gtk2::Widget
89                  +--- Gtk2::TreeView
90                       +--- Gtk2::Ex::Simple::List
91

METHODS

93       $slist = Gtk2::Ex::Simple::List->new ($cname, $ctype, ...)
94               ·   $cname (string)
95
96               ·   $ctype (string)
97
98           Creates a new Gtk2::Ex::Simple::List object with the specified
99           columns. The parameter "cname" is the name of the column, what will
100           be displayed in the list headers if they are turned on. The
101           parameter ctype is the type of the column, one of:
102
103            text    normal text strings
104            markup  pango markup strings
105            int     integer values
106            double  double-precision floating point values
107            bool    boolean values, displayed as toggle-able checkboxes
108            scalar  a perl scalar, displayed as a text string by default
109            pixbuf  a Gtk2::Gdk::Pixbuf
110
111           or the name of a custom type you add with "add_column_type".  These
112           should be provided in pairs according to the desired columns for
113           your list.
114
115       $slist = Gtk2::Ex::Simple::List->new_from_treeview ($treeview, $cname,
116       $ctype, ...)
117               ·   $treeview (Gtk2::TreeView)
118
119               ·   $cname (string)
120
121               ·   $ctype (string)
122
123           Like "Gtk2::Ex::Simple::List->new()", but turns an existing
124           Gtk2::TreeView into a Gtk2::Ex::Simple::List.  This is intended
125           mostly for use with stuff like Glade, where the widget is created
126           for you.  This will create and attach a new model and remove any
127           existing columns from treeview.  Returns treeview, re-blessed as a
128           Gtk2::Ex::Simple::List.
129
130       $slist->set_data_array ($arrayref)
131               ·   $arrayref (array reference)
132
133           Set the data in the list to the array reference $arrayref. This is
134           completely equivalent to @{$list->{data}} = @{$arrayref} and is
135           only here for convenience and for those programmers who don't like
136           to type-cast and have static, set once data.
137
138       @indices = $slist->get_selected_indices
139           Return the indices of the selected rows in the ListStore.
140
141       $slist->get_row_data_from_path ($path)
142               ·   $path (Gtk2::TreePath) the path of the desired row
143
144           Returns an array ref with the data of the row indicated by $path.
145
146       $slist->select ($index, ...);
147       $slist->unselect ($index, ...);
148               ·   $index (integer)
149
150           Select or unselect rows in the list by index.  If the list is set
151           for multiple selection, all indices in the list will be set/unset;
152           otherwise, just the first is used.  If the list is set for no
153           selection, then nothing happens.
154
155           To set the selection mode, or to select all or none of the rows,
156           use the normal TreeView/TreeSelection stuff, e.g.
157           $slist->get_selection and the TreeSelection methods "get_mode",
158           "set_mode", "select_all", and "unselect_all".
159
160       $slist->set_column_editable ($index, $editable)
161               ·   $index (integer)
162
163               ·   $editable (boolean)
164
165       boolean = $slist->get_column_editable ($index)
166               ·   $index (integer)
167
168           This is a very simple interface to Gtk2::TreeView's editable text
169           column cells.  All columns which use the attr "text" (basically,
170           any text or number column, see "add_column_type") automatically
171           have callbacks installed to update data when cells are edited.
172           With "set_column_editable", you can enable the in-place editing.
173
174           "get_column_editable" tells you if column index is currently
175           editable.
176
177       Gtk2::Ex::Simple::List->add_column_type ($type_name, ...)
178               $type_name (string)
179
180           Add a new column type to the list of possible types. Initially six
181           column types are defined, text, int, double, bool, scalar, and
182           pixbuf. The bool column type uses a toggle cell renderer, the
183           pixbuf uses a pixbuf cell renderer, and the rest use text cell
184           renderers. In the process of adding a new column type you may use
185           any cell renderer you wish.
186
187           The first parameter is the column type name, the list of six are
188           examples.  There are no restrictions on the names and you may even
189           overwrite the existing ones should you choose to do so. The
190           remaining parameters are the type definition consisting of key
191           value pairs. There are three required: type, renderer, and attr.
192           The type key determines what actual datatype will be stored in the
193           underlying model representation; this is a package name, e.g.
194           Glib::String, Glib::Int, Glib::Boolean, but in general if you want
195           an arbitrary Perl data structure you will want to use
196           'Glib::Scalar'. The renderer key should hold the class name of the
197           cell renderer to create for this column type; this may be any of
198           Gtk2::CellRendererText, Gtk2::CellRendererToggle,
199           Gtk2::CellRendererPixbuf, or some other, possibly custom, cell
200           renderer class.  The attr key is magical; it may be either a
201           string, in which case it specifies the attribute which will be set
202           from the specified column (e.g. 'text' for a text renderer,
203           'active' for a toggle renderer, etc), or it may be a reference to a
204           subroutine which will be called each time the renderer needs to
205           draw the data.
206
207           This function, described as a GtkTreeCellDataFunc in the API
208           reference, will receive 5 parameters: $treecol, $cell, $model,
209           $iter, $col_num (when SimpleList hooks up the function, it sets the
210           column number to be passed as the user data).  The data value for
211           the particular cell in question is available via $model->get
212           ($iter, $col_num); you can then do whatever it is you have to do to
213           render the cell the way you want.  Here are some examples:
214
215             # just displays the value in a scalar as
216             # Perl would convert it to a string
217             Gtk2::Ex::Simple::List->add_column_type( 'a_scalar',
218                     type     => 'Glib::Scalar',
219                     renderer => 'Gtk2::CellRendererText',
220                     attr     => sub {
221                          my ($treecol, $cell, $model, $iter, $col_num) = @_;
222                          my $info = $model->get ($iter, $col_num);
223                          $cell->set (text => $info);
224                     }
225                );
226
227             # sums up the values in an array ref and displays
228             # that in a text renderer
229             Gtk2::Ex::Simple::List->add_column_type( 'sum_of_array',
230                     type     => 'Glib::Scalar',
231                     renderer => 'Gtk2::CellRendererText',
232                     attr     => sub {
233                          my ($treecol, $cell, $model, $iter, $col_num) = @_;
234                          my $sum = 0;
235                          my $info = $model->get ($iter, $col_num);
236                          foreach (@$info)
237                          {
238                              $sum += $_;
239                          }
240                          $cell->set (text => $sum);
241                     }
242                );
243

MODIFYING LIST DATA

245       After creating a new Gtk2::Ex::Simple::List object there will be a
246       member called "data" which is a tied array. That means data may be
247       treated as an array, but in reality the data resides in something else.
248       There is no need to understand the details of this it just means that
249       you put data into, take data out of, and modify it just like any other
250       array. This includes using array operations like push, pop, unshift,
251       and shift. For those of you very familiar with perl this section will
252       prove redundant, but just in case:
253
254         Adding and removing rows:
255
256           # push a row onto the end of the list
257           push @{$slist->{data}}, [col1_data, col2_data, ..., coln_data];
258           # pop a row off of the end of the list
259           $rowref = pop @{$slist->{data}};
260           # unshift a row onto the beginning of the list
261           unshift @{$slist->{data}}, [col1_data, col2_data, ..., coln_data];
262           # shift a row off of the beginning of the list
263           $rowref = shift @{$slist->{data}};
264           # delete the row at index $n, 0 indexed
265           splice @{ $slist->{data} }, $n, 1;
266           # set the entire list to be the data in a array
267           @{$slist->{data}} = ( [row1, ...], [row2, ...], [row3, ...] );
268
269         Getting at the data in the list:
270
271           # get an array reference to the entire nth row
272           $rowref = $slist->{data}[n];
273           # get the scalar in the mth column of the nth row, 0 indexed
274           $val = $slist->{data}[n][m];
275           # set an array reference to the entire nth row
276           $slist->{data}[n] = [col1_data, col2_data, ..., coln_data];
277           # get the scalar in the mth column of the nth row, 0 indexed
278           $slist->{data}[n][m] = $rowm_coln_value;
279

SEE ALSO

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

AUTHORS

285        muppet <scott at asofyet dot org>
286        Ross McFarland <rwmcfa1 at neces dot com>
287        Gavin Brown <gavin dot brown at uk dot com>
288
290       Copyright 2004 by the Gtk2-Perl team.
291
292       This library is free software; you can redistribute it and/or modify it
293       under the terms of the GNU Library General Public License as published
294       by the Free Software Foundation; either version 2.1 of the License, or
295       (at your option) any later version.
296
297       This library is distributed in the hope that it will be useful, but
298       WITHOUT ANY WARRANTY; without even the implied warranty of
299       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
300       Library General Public License for more details.
301
302       You should have received a copy of the GNU Library General Public
303       License along with this library; if not, write to the Free Software
304       Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307
305       USA.
306
307
308
309perl v5.12.0                      2004-12-02         Gtk2::Ex::Simple::List(3)
Impressum