1TList(3) User Contributed Perl Documentation TList(3)
2
6 Tk::TList - Create and manipulate Tix Tabular List widgets
7
9 $tlist = $parent->TList(?options?);
10
12 None.
13
15 -background -borderwidth -class -cursor -foreground
16 -font -height -highlightcolor -highlightthickness
17 -relief -selectbackground -selectforeground -xscrollcom‐
18 mand -yscrollcommand -width
19 See Tk::options for details of the standard options.
21
23 Name: browsecmd
24 Class: BrowseCmd
25 Switch: -browsecmd
26 Specifies a perl/Tk callback to be executed when the user browses
27 through the entries in the TList widget.
28 Name: command
30 Class: Command
31 Switch: -command
32 Specifies the perl/Tk callback to be executed when the user invokes
33 a list entry in the TList widget. Normally the user invokes a list
34 entry by double-clicking it or pressing the Return key.
35 Name: foreground
37 Class: Foreground
38 Switch: -foreground
39 Alias: -fg
40 Specifies the default foreground color for the list entries.
41 Name: height
43 Class: Height
44 Switch: -height
45 Specifies the desired height for the window in number of charac‐
46 ters.
47 Name: itemType
49 Class: ItemType
50 Switch: -itemtype
51 Specifies the default type of display item for this TList widget.
52 When you call the insert methods, display items of this type will
53 be created if the -itemtype option is not specified.
54 Name: orient
56 Class: Orient
57 Switch: -orient
58 Specifies the order of tabularizing the list entries. When set to
59 "vertical", the entries are arranged in a column, from top to bot‐
60 tom. If the entries cannot be contained in one column, the remain‐
61 ing entries will go to the next column, and so on. When set to
62 "horizontal", the entries are arranged in a row, from left to
63 right. If the entries cannot be contained in one row, the remaining
64 entries will go to the next row, and so on.
65 Name: padX
67 Class: Pad
68 Switch: -padx
69 The default horizontal padding for list entries.
70 Name: padY
72 Class: Pad
73 Switch: -padx
74 The default vertical padding for list entries.
75 Name: selectBackground
77 Class: SelectBackground
78 Switch: -selectbackground
79 Specifies the background color for the selected list entries.
80 Name: selectBorderWidth
82 Class: BorderWidth
83 Switch: -selectborderwidth
84 Specifies a non-negative value indicating the width of the 3-D bor‐
85 der to draw around selected items. The value may have any of the
86 forms acceptable to Tk_GetPixels.
87 Name: selectForeground
89 Class: SelectForeground
90 Switch: -selectforeground
91 Specifies the foreground color for the selected list entries.
92 Name: selectMode
94 Class: SelectMode
95 Switch: -selectmode
96 Specifies one of several styles for manipulating the selection.
97 The value of the option may be arbitrary, but the default bindings
98 expect it to be either single, browse, multiple, or extended; the
99 default value is single.
100 Name: sizeCmd
102 Class: SizeCmd
103 Switch: -sizecmd
104 Specifies a perl/Tk callback to be called whenever the TList widget
105 changes its size. This command can be useful to implement "user
106 scroll bars when needed" features.
107 Name: state
109 Class: State
110 Switch: -state
111 Specifies whether the TList command should react to user actions.
112 When set to "normal", the TList reacts to user actions in the nor‐
113 mal way. When set to "disabled", the TList can only be scrolled,
114 but its entries cannot be selected or activated.
115 Name: width
117 Class: Width
118 Switch: -width
119 Specifies the desired width for the window in characters.
120
122 The TList method creates a new window (given by the $widget argument)
123 and makes it into a TList widget. Additional options, described above,
124 may be specified on the command line or in the option database to con‐
125 figure aspects of the TList widget such as its cursor and relief.
126 The TList widget can be used to display data in a tabular format. The
128 list entries of a TList widget are similar to the entries in the Tk
129 listbox widget. The main differences are (1) the TList widget can dis‐
130 play the list entries in a two dimensional format and (2) you can use
131 graphical images as well as multiple colors and fonts for the list
132 entries.
133 Each list entry is identified by an index, which can be in the follow‐
135 ing forms:
136 number
138 An integer that indicates the position of the entry in the list. 0
139 means the first position, 1 means the second position, and so on.
140 end Indicates the end of the listbox. For some commands this means just
142 after the last entry; for other commands it means the last entry.
143 @x,y
145 Indicates the element that covers the point in the listbox window
146 specified by x and y (in pixel coordinates). If no element covers
147 that point, then the closest element to that point is used.
148
150 Each list entry in an TList widget is associated with a display item.
151 The display item determines what visual information should be displayed
152 for this list entry. Please see Tk::DItem for a list of all display
153 items.
154 When a list entry is created by the insert command, the type of its
156 display item is determined by the -itemtype option passed to these com‐
157 mands. If the -itemtype is omitted, then by default the type specified
158 by this TList widget's -itemtype option is used.
159
161 The TList method creates a widget object.
162 This object supports the configure and cget methods described in
164 Tk::options which can be used to enquire and modify the options
165 described above. The widget also inherits all the methods provided by
166 the generic Tk::Widget class.
167 The following additional methods are available for TList widgets:
169 $tlist->anchorSet(index)
171 Sets the anchor to the list entry identified by index. The anchor
172 is the end of the selection that is fixed while dragging out a
173 selection with the mouse.
174 $tlist->anchorClear
176 Removes the anchor, if any, from this TList widget. This only
177 removes the surrounding highlights of the anchor entry and does not
178 affect its selection status.
179 $tlist->delete(from, ?to?)
181 Deletes one or more list entries between the two entries specified
182 by the indices from and to. If to is not specified, deletes the
183 single entry specified by from.
184 $tlist->dragsiteSet(index)
186 Sets the dragsite to the list entry identified by index. The
187 dragsite is used to indicate the source of a drag-and-drop action.
188 Currently drag-and-drop functionality has not been implemented in
189 Tix yet.
190 $tlist->dragsiteClear
192 Remove the dragsite, if any, from the this TList widget. This only
193 removes the surrounding highlights of the dragsite entry and does
194 not affect its selection status.
195 $tlist->dropsiteSet(index)
197 Sets the dropsite to the list entry identified by index. The drop‐
198 site is used to indicate the target of a drag-and-drop action. Cur‐
199 rently drag-and-drop functionality has not been implemented in Tix
200 yet.
201 $tlist->dropsiteClear
203 Remove the dropsite, if any, from the this TList widget. This only
204 removes the surrounding highlights of the dropsite entry and does
205 not affect its selection status.
206 $tlist->entrycget(index, option)
208 Returns the current value of the configuration option given by
209 option for the entry indentfied by index. Option may have any of
210 the values accepted by the insert method.
211 $tlist->entryconfigure(index, ?option?, ?value, option, value, ...?)
213 Query or modify the configuration options of the list entry identi‐
214 fied by index. If no option is specified, returns a list describing
215 all of the available options for index (see Tk_ConfigureInfo for
216 information on the format of this list). If option is specified
217 with no value, then the method returns a list describing the one
218 named option (this list will be identical to the corresponding sub‐
219 list of the value returned if no option is specified). If one or
220 more option-value pairs are specified, then the command modifies
221 the given option(s) to have the given value(s); in this case the
222 method returns an empty string. Option may have any of the values
223 accepted by the insert method. The exact set of options depends on
224 the value of the -itemtype option passed to the the insert method
225 when this list entry is created.
226 $tlist->insert(index, ?option, value, ...?)
228 Creates a new list entry at the position indicated by index. The
229 following configuration options can be given to configure the list
230 entry:
231 -itemtype => type
233 Specifies the type of display item to be display for the
234 new list entry. type must be a valid display item type.
235 Currently the available display item types are image,
236 imagetext, text, and $widget. If this option is not speci‐
237 fied, then by default the type specified by this TList wid‐
238 get's -itemtype option is used.
239 -state => state
241 Specifies whether this entry can be selected or invoked by
242 the user. Must be either normal or disabled.
243 -data => data
245 Arbitrary data to be associated with the entry (a perl
246 scalar value).
247 The insert method accepts additional configuration options to con‐
249 figure the display item associated with this list entry. The set of
250 additional configuration options depends on the type of the display
251 item given by the -itemtype option. Please see Tk::DItem for a list
252 of the configuration options for each of the display item types.
253 $tlist->info(option, arg, ...)
255 Query information about the TList widget. option can be one of the
256 following:
257 $tlist->info(anchor, index)
259 Returns the index of the current anchor, if any, of the
260 TList widget. If the anchor is not set, returns the empty
261 string.
262 $tlist->info(dragsite, index)
264 Returns the index of the current dragsite, if any, of the
265 TList widget. If the dragsite is not set, returns the empty
266 string.
267 $tlist->info(dropsite, index)
269 Returns the index of the current dropsite, if any, of the
270 TList widget. If the dropsite is not set, returns the empty
271 string.
272 $tlist->info(selection)
274 Returns a list of selected elements in the TList widget. If
275 no entries are selected, returns an empty string.
276 $tlist->nearest(x, y)
278 Given an (x,y) coordinate within the TList window, this command
279 returns the index of the TList element nearest to that coordinate.
280 $tlist->see(index)
282 Adjust the view in the TList so that the entry given by index is
283 visible. If the entry is already visible then the command has no
284 effect; otherwise TList scrolls to bring the element into view at
285 the edge to which it is nearest.
286 $tlist->selection(option, arg, ...)
288 This command is used to adjust the selection within a TList widget.
289 It has several forms, depending on option:
290 $tlist->selectionClear(?from?, ?to?)
292 When no extra arguments are given, deselects all of the
293 list entrie(s) in this TList widget. When only from is
294 given, only the list entry identified by from is dese‐
295 lected. When both from and to are given, deselects all of
296 the list entrie(s) between between from and to, inclusive,
297 without affecting the selection state of entries outside
298 that range.
299 $tlist->selectionIncludes(index)
301 Returns 1 if the list entry indicated by index is currently
302 selected; returns 0 otherwise.
303 $tlist->selectionSet(from, ?to?)
305 Selects all of the list entrie(s) between between from and
306 to, inclusive, without affecting the selection state of
307 entries outside that range. When only from is given, only
308 the list entry identified by from is selected.
309 $tlist->xview(args)
311 This command is used to query and change the horizontal position of
312 the information in the widget's window. It can take any of the fol‐
313 lowing forms:
314 $tlist->xview
316 Returns a list containing two elements. Each element is a
317 real fraction between 0 and 1; together they describe the
318 horizontal span that is visible in the window. For exam‐
319 ple, if the first element is 0.2 and the second element is
320 0.6, 20% of the TList entry is off-screen to the left, the
321 middle 40% is visible in the window, and 40% of the entry
322 is off-screen to the right. These are the same values
323 passed to scrollbars via the -xscrollcommand option.
324 $tlist->xview(index)
326 Adjusts the view in the window so that the list entry iden‐
327 tified by index is aligned to the left edge of the window.
328 $tlist->xviewMoveto(fraction)
330 Adjusts the view in the window so that fraction of the
331 total width of the TList is off-screen to the left. frac‐
332 tion must be a fraction between 0 and 1.
333 $tlist->xviewScroll(number, what)
335 This command shifts the view in the window left or right
336 according to number and what. Number must be an integer.
337 What must be either units or pages or an abbreviation of
338 one of these. If what is units, the view adjusts left or
339 right by number character units (the width of the 0 charac‐
340 ter) on the display; if it is pages then the view adjusts
341 by number screenfuls. If number is negative then characters
342 farther to the left become visible; if it is positive then
343 characters farther to the right become visible.
344 $tlist->yview(?args?)
346 This command is used to query and change the vertical position of
347 the entries in the widget's window. It can take any of the follow‐
348 ing forms:
349 $tlist->yview
351 Returns a list containing two elements, both of which are
352 real fractions between 0 and 1. The first element gives
353 the position of the list element at the top of the window,
354 relative to the TList as a whole (0.5 means it is halfway
355 through the TList, for example). The second element gives
356 the position of the list entry just after the last one in
357 the window, relative to the TList as a whole. These are
358 the same values passed to scrollbars via the -yscrollcom‐
359 mand option.
360 $tlist->yview(index)
362 Adjusts the view in the window so that the list entry given
363 by index is displayed at the top of the window.
364 $tlist->yviewMoveto(fraction)
366 Adjusts the view in the window so that the list entry given
367 by fraction appears at the top of the window. Fraction is a
368 fraction between 0 and 1; 0 indicates the first entry in
369 the TList, 0.33 indicates the entry one-third the way
370 through the TList, and so on.
371 $tlist->yviewScroll(number, what)
373 This command adjust the view in the window up or down
374 according to number and what. Number must be an integer.
375 What must be either units or pages. If what is units, the
376 view adjusts up or down by number lines; if it is pages
377 then the view adjusts by number screenfuls. If number is
378 negative then earlier entries become visible; if it is pos‐
379 itive then later entries become visible.
380
382 [1] If the -selectmode is "browse", when the user drags the mouse
383 pointer over the list entries, the entry under the pointer will be
384 highlighted and the -browsecmd procedure will be called with one
385 parameter, the index of the highlighted entry. Only one entry can
386 be highlighted at a time. The -command procedure will be called
387 when the user double-clicks on a list entry.
388 [2] If the -selectmode is "single", the entries will only be high‐
390 lighted by mouse <ButtonRelease-1> events. When a new list entry is
391 highlighted, the -browsecmd procedure will be called with one
392 parameter indicating the highlighted list entry. The -command pro‐
393 cedure will be called when the user double-clicks on a list entry.
394 [3] If the -selectmode is "multiple", when the user drags the mouse
396 pointer over the list entries, all the entries under the pointer
397 will be highlighted. However, only a contiguous region of list
398 entries can be selected. When the highlighted area is changed, the
399 -browsecmd procedure will be called with an undefined parameter. It
400 is the responsibility of the -browsecmd procedure to find out the
401 exact highlighted selection in the TList. The -command procedure
402 will be called when the user double-clicks on a list entry.
403 [4] If the -selectmode is "extended", when the user drags the mouse
405 pointer over the list entries, all the entries under the pointer
406 will be highlighted. The user can also make disjointed selections
407 using <Control-ButtonPress-1>. When the highlighted area is
408 changed, the -browsecmd procedure will be called with an undefined
409 parameter. It is the responsibility of the -browsecmd procedure to
410 find out the exact highlighted selection in the TList. The -command
411 procedure will be called when the user double-clicks on a list
412 entry.
413
415 This example demonstrates how to use an TList to store a list of num‐
416 bers:
417 use strict;
419 use Tk ();
420 use Tk::TList;
421 my $mw = Tk::MainWindow->new();
423 my $image = $mw->Getimage('folder');
424 my $tlist = $mw->TList(-orient => 'vertical');
425 for my $text ( qw/one two three four five six seven eight nine/ ) {
426 $tlist->insert('end',
427 -itemtype=>'imagetext', -image=>$image, -text=>$text);
428 }
429 $tlist->pack(-expand=>'yes', -fill=>'both');
431 Tk::MainLoop;
433
435 Tk::options Tk::Widget Tk::DItem Tk::HList Tk::TixGrid
436
438 Tix(n), Tabular Listbox, Display Items
439perl v5.8.8 2008-02-05 TList(3)