1Gtk2::Ex::Simple::List(U3s)er Contributed Perl DocumentatGitokn2::Ex::Simple::List(3)
2
6 Gtk2::Ex::Simple::List - A simple interface to Gtk2's complex MVC list
7 widget
8
10 use Glib qw(TRUE FALSE);
11 use Gtk2 '-init';
12 use Gtk2::Ex::Simple::List;
13 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 @{$slist->{data}} = (
25 [ 'text', 1, 1.1, TRUE, $var, $pixbuf ],
26 [ 'text', 2, 2.2, FALSE, $var, $pixbuf ],
27 );
28 # (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 # 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 # simple way to make text columns editable
41 $slist->set_column_editable ($col_num, TRUE);
42 # 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 # 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
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
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 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 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
86 Glib::Object
87 +--- Gtk2::Object
88 +--- Gtk2::Widget
89 +--- Gtk2::TreeView
90 +--- Gtk2::Ex::Simple::List
91
93 $slist = Gtk2::Ex::Simple::List->new ($cname, $ctype, ...)
94 · $cname (string)
95 · $ctype (string)
97 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 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 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 $slist = Gtk2::Ex::Simple::List->new_from_treeview ($treeview, $cname,
116 $ctype, ...)
117 · $treeview (Gtk2::TreeView)
118 · $cname (string)
120 · $ctype (string)
122 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 $slist->set_data_array ($arrayref)
131 · $arrayref (array reference)
132 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 @indices = $slist->get_selected_indices
139 Return the indices of the selected rows in the ListStore.
140 $slist->get_row_data_from_path ($path)
142 · $path (Gtk2::TreePath) the path of the desired row
143 Returns an array ref with the data of the row indicated by $path.
145 $slist->select ($index, ...);
147 $slist->unselect ($index, ...);
148 · $index (integer)
149 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 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 $slist->set_column_editable ($index, $editable)
161 · $index (integer)
162 · $editable (boolean)
164 boolean = $slist->get_column_editable ($index)
166 · $index (integer)
167 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 "get_column_editable" tells you if column index is currently
175 editable.
176 Gtk2::Ex::Simple::List->add_column_type ($type_name, ...)
178 $type_name (string)
179 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 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 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 # 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 # 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
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 Adding and removing rows:
255 # 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 Getting at the data in the list:
270 # 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
281 Perl(1), Glib(3pm), Gtk2(3pm), Gtk2::TreeView(3pm),
282 Gtk2::TreeModel(3pm), Gtk2::ListStore(3pm).
283
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 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 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 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.
306perl v5.28.1 2004-12-02 Gtk2::Ex::Simple::List(3)