1pm::SimpleList(3) User Contributed Perl Documentation pm::SimpleList(3)
2
6 Gtk2::SimpleList - A simple interface to Gtk2's complex MVC list widget
7
9 use Glib qw(TRUE FALSE);
10 use Gtk2 '-init';
11 use Gtk2::SimpleList;
12 my $slist = Gtk2::SimpleList->new (
14 'Text Field' => 'text',
15 'Markup Field' => 'markup',
16 'Int Field' => 'int',
17 'Double Field' => 'double',
18 'Bool Field' => 'bool',
19 'Scalar Field' => 'scalar',
20 'Pixbuf Field' => 'pixbuf',
21 );
22 @{$slist->{data}} = (
24 [ 'text', 1, 1.1, TRUE, $var, $pixbuf ],
25 [ 'text', 2, 2.2, FALSE, $var, $pixbuf ],
26 );
27 # (almost) anything you can do to an array you can do to
29 # $slist->{data} which is an array reference tied to the list model
30 push @{$slist->{data}}, [ 'text', 3, 3.3, TRUE, $var, $pixbuf ];
31 # mess with selections
33 $slist->get_selection->set_mode ('multiple');
34 $slist->get_selection->unselect_all;
35 $slist->select (1, 3, 5..9); # select rows by index
36 $slist->unselect (3, 8); # unselect rows by index
37 @sel = $slist->get_selected_indices;
38 # simple way to make text columns editable
40 $slist->set_column_editable ($col_num, TRUE);
41 # Gtk2::SimpleList derives from Gtk2::TreeView, so all methods
43 # on a treeview are available.
44 $slist->set_rules_hint (TRUE);
45 $slist->signal_connect (row_activated => sub {
46 my ($sl, $path, $column) = @_;
47 my $row_ref = $sl->get_row_data_from_path ($path);
48 # $row_ref is now an array ref to the double-clicked row's data.
49 });
50 # turn an existing TreeView into a SimpleList; useful for
52 # Glade-generated interfaces.
53 $simplelist = Gtk2::SimpleList->new_from_treeview (
54 $glade->get_widget ('treeview'),
55 'Text Field' => 'text',
56 'Int Field' => 'int',
57 'Double Field' => 'double',
58 );
59
61 SimpleList is a simple interface to the powerful but complex
62 Gtk2::TreeView and Gtk2::ListStore combination, implementing using tied
63 arrays to make thing simple and easy.
64
66 Gtk2 has a powerful, but complex MVC (Model, View, Controller) system
67 used to implement list and tree widgets. Gtk2::SimpleList automates
68 the complex setup work and allows you to treat the list model as a more
69 natural list of lists structure.
70 After creating a new Gtk2::SimpleList object with the desired columns
72 you may set the list data with a simple Perl array assignment. Rows may
73 be added or deleted with all of the normal array operations. You can
74 treat the "data" member of the list simplelist object as an array ref‐
75 erence, and manipulate the list data with perl's normal array opera‐
76 tors.
77 A mechanism has also been put into place allowing columns to be Perl
79 scalars. The scalar is converted to text through Perl's normal mecha‐
80 nisms and then displayed in the list. This same mechanism can be
81 expanded by defining arbitrary new column types before calling the new
82 function.
83
85 Glib::Object
86 +--- Gtk2::Object
87 +--- Gtk2::Widget
88 +--- Gtk2::TreeView
89 +--- Gtk2::SimpleList
90
92 $slist = Gtk2::SimpleList->new ($cname, $ctype, ...)
93 * $cname (string)
94 * $ctype (string)
95 Creates a new Gtk2::SimpleList object with the specified columns.
97 The parameter "cname" is the name of the column, what will be dis‐
98 played in the list headers if they are turned on. The parameter
99 ctype is the type of the column, one of:
100 text normal text strings
102 markup pango markup strings
103 int integer values
104 double double-precision floating point values
105 bool boolean values, displayed as toggle-able checkboxes
106 scalar a perl scalar, displayed as a text string by default
107 pixbuf a Gtk2::Gdk::Pixbuf
108 or the name of a custom type you add with "add_column_type". These
110 should be provided in pairs according to the desired columns for
111 your list.
112 $slist = Gtk2::SimpleList->new_from_treeview ($treeview, $cname,
114 $ctype, ...)
115 * $treeview (Gtk2::TreeView)
116 * $cname (string)
117 * $ctype (string)
118 Like "Gtk2::SimpleList->new()", but turns an existing Gtk2::Tree‐
120 View into a Gtk2::SimpleList. This is intended mostly for use with
121 stuff like Glade, where the widget is created for you. This will
122 create and attach a new model and remove any existing columns from
123 treeview. Returns treeview, re-blessed as a Gtk2::SimpleList.
124 $slist->set_data_array ($arrayref)
126 * $arrayref (array reference)
127 Set the data in the list to the array reference $arrayref. This is
129 completely equivalent to @{$list->{data}} = @{$arrayref} and is
130 only here for convenience and for those programmers who don't like
131 to type-cast and have static, set once data.
132 @indices = $slist->get_selected_indices
134 Return the indices of the selected rows in the ListStore.
135 $slist->get_row_data_from_path ($path)
137 * $path (Gtk2::TreePath) the path of the desired row
138 Returns an array ref with the data of the row indicated by $path.
140 $slist->select ($index, ...);
142 $slist->unselect ($index, ...);
143 * $index (integer)
144 Select or unselect rows in the list by index. If the list is set
146 for multiple selection, all indices in the list will be set/unset;
147 otherwise, just the first is used. If the list is set for no
148 selection, then nothing happens.
149 To set the selection mode, or to select all or none of the rows,
151 use the normal TreeView/TreeSelection stuff, e.g.
152 $slist->get_selection and the TreeSelection methods "get_mode",
153 "set_mode", "select_all", and "unselect_all".
154 $slist->set_column_editable ($index, $editable)
156 * $index (integer)
157 * $editable (boolean)
158 boolean = $slist->get_column_editable ($index)
159 * $index (integer)
160 This is a very simple interface to Gtk2::TreeView's editable text
162 column cells. All columns which use the attr "text" (basically,
163 any text or number column, see "add_column_type") automatically
164 have callbacks installed to update data when cells are edited.
165 With "set_column_editable", you can enable the in-place editing.
166 "get_column_editable" tells you if column index is currently
168 editable.
169 Gtk2::SimpleList->add_column_type ($type_name, ...)
171 $type_name (string)
172 Add a new column type to the list of possible types. Initially six
174 column types are defined, text, int, double, bool, scalar, and
175 pixbuf. The bool column type uses a toggle cell renderer, the
176 pixbuf uses a pixbuf cell renderer, and the rest use text cell ren‐
177 derers. In the process of adding a new column type you may use any
178 cell renderer you wish.
179 The first parameter is the column type name, the list of six are
181 examples. There are no restrictions on the names and you may even
182 overwrite the existing ones should you choose to do so. The remain‐
183 ing parameters are the type definition consisting of key value
184 pairs. There are three required: type, renderer, and attr. The type
185 key determines what actual datatype will be stored in the underly‐
186 ing model representation; this is a package name, e.g.
187 Glib::String, Glib::Int, Glib::Boolean, but in general if you want
188 an arbitrary Perl data structure you will want to use
189 'Glib::Scalar'. The renderer key should hold the class name of the
190 cell renderer to create for this column type; this may be any of
191 Gtk2::CellRendererText, Gtk2::CellRendererToggle, Gtk2::CellRender‐
192 erPixbuf, or some other, possibly custom, cell renderer class. The
193 attr key is magical; it may be either a string, in which case it
194 specifies the attribute which will be set from the specified column
195 (e.g. 'text' for a text renderer, 'active' for a toggle renderer,
196 etc), or it may be a reference to a subroutine which will be called
197 each time the renderer needs to draw the data.
198 This function, described as a GtkTreeCellDataFunc in the API refer‐
200 ence, will receive 5 parameters: $treecol, $cell, $model, $iter,
201 $col_num (when SimpleList hooks up the function, it sets the column
202 number to be passed as the user data). The data value for the par‐
203 ticular cell in question is available via $model->get ($iter,
204 $col_num); you can then do whatever it is you have to do to render
205 the cell the way you want. Here are some examples:
206 # just displays the value in a scalar as
208 # Perl would convert it to a string
209 Gtk2::SimpleList->add_column_type( 'a_scalar',
210 type => 'Glib::Scalar',
211 renderer => 'Gtk2::CellRendererText',
212 attr => sub {
213 my ($treecol, $cell, $model, $iter, $col_num) = @_;
214 my $info = $model->get ($iter, $col_num);
215 $cell->set (text => $info);
216 }
217 );
218 # sums up the values in an array ref and displays
220 # that in a text renderer
221 Gtk2::SimpleList->add_column_type( 'sum_of_array',
222 type => 'Glib::Scalar',
223 renderer => 'Gtk2::CellRendererText',
224 attr => sub {
225 my ($treecol, $cell, $model, $iter, $col_num) = @_;
226 my $sum = 0;
227 my $info = $model->get ($iter, $col_num);
228 foreach (@$info)
229 {
230 $sum += $_;
231 }
232 $cell->set (text => $sum);
233 }
234 );
235
237 After creating a new Gtk2::SimpleList object there will be a member
238 called "data" which is a tied array. That means data may be treated as
239 an array, but in reality the data resides in something else. There is
240 no need to understand the details of this it just means that you put
241 data into, take data out of, and modify it just like any other array.
242 This includes using array operations like push, pop, unshift, and
243 shift. For those of you very familiar with perl this section will prove
244 redundant, but just in case:
245 Adding and removing rows:
247 # push a row onto the end of the list
249 push @{$slist->{data}}, [col1_data, col2_data, ..., coln_data];
250 # pop a row off of the end of the list
251 $rowref = pop @{$slist->{data}};
252 # unshift a row onto the beginning of the list
253 unshift @{$slist->{data}}, [col1_data, col2_data, ..., coln_data];
254 # shift a row off of the beginning of the list
255 $rowref = shift @{$slist->{data}};
256 # delete the row at index $n, 0 indexed
257 splice @{ $slist->{data} }, $n, 1;
258 # set the entire list to be the data in a array
259 @{$slist->{data}} = ( [row1, ...], [row2, ...], [row3, ...] );
260 Getting at the data in the list:
262 # get an array reference to the entire nth row
264 $rowref = $slist->{data}[n];
265 # get the scalar in the mth column of the nth row, 0 indexed
266 $val = $slist->{data}[n][m];
267 # set an array reference to the entire nth row
268 $slist->{data}[n] = [col1_data, col2_data, ..., coln_data];
269 # get the scalar in the mth column of the nth row, 0 indexed
270 $slist->{data}[n][m] = $rowm_coln_value;
271
273 Perl(1), Glib(3pm), Gtk2(3pm), Gtk2::TreeView(3pm),
274 Gtk2::TreeModel(3pm), Gtk2::ListStore(3pm).
275 Note: Gtk2::SimpleList is deprecated in favor of Gtk2::Ex::Sim‐
277 ple::List, part of the Gtk2-Perl-Ex project at
278 http://gtk2-perl-ex.sf.net .
279
281 muppet <scott at asofyet dot org>
282 Ross McFarland <rwmcfa1 at neces dot com>
283 Gavin Brown <gavin dot brown at uk dot com>
284
286 Copyright 2003-2004 by the Gtk2-Perl team.
287 This library is free software; you can redistribute it and/or modify it
289 under the terms of the GNU Library General Public License as published
290 by the Free Software Foundation; either version 2.1 of the License, or
291 (at your option) any later version.
292 This library is distributed in the hope that it will be useful, but
294 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
295 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library
296 General Public License for more details.
297 You should have received a copy of the GNU Library General Public
299 License along with this library; if not, write to the Free Software
300 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307
301 USA.
302perl v5.8.8 2007-03-18 pm::SimpleList(3)