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
18 -xscrollcommand -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
46 characters.
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
60 bottom. If the entries cannot be contained in one column, the
61 remaining entries will go to the next column, and so on. When set
62 to "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
85 border to draw around selected items. The value may have any of
86 the 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
113 normal 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
125 configure 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
130 display the list entries in a two dimensional format and (2) you can
131 use 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
135 following 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
157 commands. If the -itemtype is omitted, then by default the type
158 specified 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
198 dropsite is used to indicate the target of a drag-and-drop action.
199 Currently drag-and-drop functionality has not been implemented in
200 Tix 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
214 identified by index. If no option is specified, returns a list
215 describing all of the available options for index (see
216 Tk_ConfigureInfo for information on the format of this list). If
217 option is specified with no value, then the method returns a list
218 describing the one named option (this list will be identical to the
219 corresponding sublist of the value returned if no option is
220 specified). If one or more option-value pairs are specified, then
221 the command modifies the given option(s) to have the given
222 value(s); in this case the method returns an empty string. Option
223 may have any of the values accepted by the insert method. The exact
224 set of options depends on the value of the -itemtype option passed
225 to the the insert method 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
237 specified, then by default the type specified by this TList
238 widget'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
249 configure the display item associated with this list entry. The set
250 of additional configuration options depends on the type of the
251 display item given by the -itemtype option. Please see Tk::DItem
252 for a list of the configuration options for each of the display
253 item types.
254 $tlist->info(option, arg, ...)
256 Query information about the TList widget. option can be one of the
257 following:
258 $tlist->info(anchor, index)
260 Returns the index of the current anchor, if any, of the
261 TList widget. If the anchor is not set, returns the empty
262 string.
263 $tlist->info(dragsite, index)
265 Returns the index of the current dragsite, if any, of the
266 TList widget. If the dragsite is not set, returns the empty
267 string.
268 $tlist->info(dropsite, index)
270 Returns the index of the current dropsite, if any, of the
271 TList widget. If the dropsite is not set, returns the empty
272 string.
273 $tlist->info(selection)
275 Returns a list of selected elements in the TList widget. If
276 no entries are selected, returns an empty string.
277 $tlist->nearest(x, y)
279 Given an (x,y) coordinate within the TList window, this command
280 returns the index of the TList element nearest to that coordinate.
281 $tlist->see(index)
283 Adjust the view in the TList so that the entry given by index is
284 visible. If the entry is already visible then the command has no
285 effect; otherwise TList scrolls to bring the element into view at
286 the edge to which it is nearest.
287 $tlist->selection(option, arg, ...)
289 This command is used to adjust the selection within a TList widget.
290 It has several forms, depending on option:
291 $tlist->selectionClear(?from?, ?to?)
293 When no extra arguments are given, deselects all of the
294 list entrie(s) in this TList widget. When only from is
295 given, only the list entry identified by from is
296 deselected. When both from and to are given, deselects all
297 of the list entrie(s) between between from and to,
298 inclusive, without affecting the selection state of entries
299 outside that range.
300 $tlist->selectionIncludes(index)
302 Returns 1 if the list entry indicated by index is currently
303 selected; returns 0 otherwise.
304 $tlist->selectionSet(from, ?to?)
306 Selects all of the list entrie(s) between between from and
307 to, inclusive, without affecting the selection state of
308 entries outside that range. When only from is given, only
309 the list entry identified by from is selected.
310 $tlist->xview(args)
312 This command is used to query and change the horizontal position of
313 the information in the widget's window. It can take any of the
314 following forms:
315 $tlist->xview
317 Returns a list containing two elements. Each element is a
318 real fraction between 0 and 1; together they describe the
319 horizontal span that is visible in the window. For
320 example, if the first element is 0.2 and the second element
321 is 0.6, 20% of the TList entry is off-screen to the left,
322 the middle 40% is visible in the window, and 40% of the
323 entry is off-screen to the right. These are the same values
324 passed to scrollbars via the -xscrollcommand option.
325 $tlist->xview(index)
327 Adjusts the view in the window so that the list entry
328 identified by index is aligned to the left edge of the
329 window.
330 $tlist->xviewMoveto(fraction)
332 Adjusts the view in the window so that fraction of the
333 total width of the TList is off-screen to the left.
334 fraction must be a fraction between 0 and 1.
335 $tlist->xviewScroll(number, what)
337 This command shifts the view in the window left or right
338 according to number and what. Number must be an integer.
339 What must be either units or pages or an abbreviation of
340 one of these. If what is units, the view adjusts left or
341 right by number character units (the width of the 0
342 character) on the display; if it is pages then the view
343 adjusts by number screenfuls. If number is negative then
344 characters farther to the left become visible; if it is
345 positive then characters farther to the right become
346 visible.
347 $tlist->yview(?args?)
349 This command is used to query and change the vertical position of
350 the entries in the widget's window. It can take any of the
351 following forms:
352 $tlist->yview
354 Returns a list containing two elements, both of which are
355 real fractions between 0 and 1. The first element gives
356 the position of the list element at the top of the window,
357 relative to the TList as a whole (0.5 means it is halfway
358 through the TList, for example). The second element gives
359 the position of the list entry just after the last one in
360 the window, relative to the TList as a whole. These are
361 the same values passed to scrollbars via the
362 -yscrollcommand option.
363 $tlist->yview(index)
365 Adjusts the view in the window so that the list entry given
366 by index is displayed at the top of the window.
367 $tlist->yviewMoveto(fraction)
369 Adjusts the view in the window so that the list entry given
370 by fraction appears at the top of the window. Fraction is a
371 fraction between 0 and 1; 0 indicates the first entry in
372 the TList, 0.33 indicates the entry one-third the way
373 through the TList, and so on.
374 $tlist->yviewScroll(number, what)
376 This command adjust the view in the window up or down
377 according to number and what. Number must be an integer.
378 What must be either units or pages. If what is units, the
379 view adjusts up or down by number lines; if it is pages
380 then the view adjusts by number screenfuls. If number is
381 negative then earlier entries become visible; if it is
382 positive then later entries become visible.
383
385 [1] If the -selectmode is "browse", when the user drags the mouse
386 pointer over the list entries, the entry under the pointer will be
387 highlighted and the -browsecmd procedure will be called with one
388 parameter, the index of the highlighted entry. Only one entry can
389 be highlighted at a time. The -command procedure will be called
390 when the user double-clicks on a list entry.
391 [2] If the -selectmode is "single", the entries will only be
393 highlighted by mouse <ButtonRelease-1> events. When a new list
394 entry is highlighted, the -browsecmd procedure will be called with
395 one parameter indicating the highlighted list entry. The -command
396 procedure will be called when the user double-clicks on a list
397 entry.
398 [3] If the -selectmode is "multiple", when the user drags the mouse
400 pointer over the list entries, all the entries under the pointer
401 will be highlighted. However, only a contiguous region of list
402 entries can be selected. When the highlighted area is changed, the
403 -browsecmd procedure will be called with an undefined parameter. It
404 is the responsibility of the -browsecmd procedure to find out the
405 exact highlighted selection in the TList. The -command procedure
406 will be called when the user double-clicks on a list entry.
407 [4] If the -selectmode is "extended", when the user drags the mouse
409 pointer over the list entries, all the entries under the pointer
410 will be highlighted. The user can also make disjointed selections
411 using <Control-ButtonPress-1>. When the highlighted area is
412 changed, the -browsecmd procedure will be called with an undefined
413 parameter. It is the responsibility of the -browsecmd procedure to
414 find out the exact highlighted selection in the TList. The -command
415 procedure will be called when the user double-clicks on a list
416 entry.
417
419 This example demonstrates how to use an TList to store a list of
420 numbers:
421 use strict;
423 use Tk ();
424 use Tk::TList;
425 my $mw = Tk::MainWindow->new();
427 my $image = $mw->Getimage('folder');
428 my $tlist = $mw->TList(-orient => 'vertical');
429 for my $text ( qw/one two three four five six seven eight nine/ ) {
430 $tlist->insert('end',
431 -itemtype=>'imagetext', -image=>$image, -text=>$text);
432 }
433 $tlist->pack(-expand=>'yes', -fill=>'both');
435 Tk::MainLoop;
437
439 Tk::options Tk::Widget Tk::DItem Tk::HList Tk::TixGrid
440
442 Tix(n), Tabular Listbox, Display Items
443perl v5.36.0 2023-01-20 TList(3)