1TList(3)              User Contributed Perl Documentation             TList(3)
2
3
4

NAME

6       Tk::TList - Create and manipulate Tix Tabular List widgets
7

SYNOPSIS

9           $tlist = $parent->TList(?options?);
10

SUPER-CLASS

12       None.
13

STANDARD OPTIONS

15       -background    -borderwidth   -class    -cursor   -foreground
16       -font     -height   -highlightcolor     -highlightthickness
17       -relief   -selectbackground   -selectforeground
18       -xscrollcommand     -yscrollcommand     -width
19
20       See Tk::options for details of the standard options.
21

WIDGET-SPECIFIC OPTIONS

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
29       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
36       Name:     foreground
37       Class:    Foreground
38       Switch:   -foreground
39       Alias:    -fg
40           Specifies the default foreground color for the list entries.
41
42       Name:     height
43       Class:    Height
44       Switch:   -height
45           Specifies the desired height for the window in number of
46           characters.
47
48       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
55       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
66       Name:     padX
67       Class:    Pad
68       Switch:   -padx
69           The default horizontal padding for list entries.
70
71       Name:     padY
72       Class:    Pad
73       Switch:   -padx
74           The default vertical padding for list entries.
75
76       Name:     selectBackground
77       Class:    SelectBackground
78       Switch:   -selectbackground
79           Specifies the background color for the selected list entries.
80
81       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
88       Name:     selectForeground
89       Class:    SelectForeground
90       Switch:   -selectforeground
91           Specifies the foreground color for the selected list entries.
92
93       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
101       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
108       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
116       Name:     width
117       Class:    Width
118       Switch:   -width
119           Specifies the desired width for the window in characters.
120

DESCRIPTION

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
127       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
134       Each list entry is identified by an index, which can be in the
135       following forms:
136
137       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
141       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
144       @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

DISPLAY ITEMS

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
155       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

WIDGET METHODS

161       The TList method creates a widget object.
162
163       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
168       The following additional methods are available for TList widgets:
169
170       $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
175       $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
180       $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
185       $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
191       $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
196       $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
202       $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
207       $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
212       $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
227       $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
232           -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
240           -state => state
241                   Specifies whether this entry can be selected or invoked by
242                   the user.  Must be either normal or disabled.
243
244           -data => data
245                   Arbitrary data to be associated with the entry (a perl
246                   scalar value).
247
248           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
255       $tlist->info(option, arg, ...)
256           Query information about the TList widget. option can be one of the
257           following:
258
259           $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
264           $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
269           $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
274           $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
278       $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
282       $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
288       $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
292           $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
301           $tlist->selectionIncludes(index)
302                   Returns 1 if the list entry indicated by index is currently
303                   selected; returns 0 otherwise.
304
305           $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
311       $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
316           $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
326           $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
331           $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
336           $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
348       $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
353           $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
364           $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
368           $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
375           $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

BINDINGS

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
392       [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
399       [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
408       [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

EXAMPLE

419       This example demonstrates how to use an TList to store a list of
420       numbers:
421
422           use strict;
423           use Tk ();
424           use Tk::TList;
425
426           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
434           $tlist->pack(-expand=>'yes', -fill=>'both');
435
436           Tk::MainLoop;
437

SEE ALSO

439       Tk::options Tk::Widget Tk::DItem Tk::HList Tk::TixGrid
440

KEYWORDS

442       Tix(n), Tabular Listbox, Display Items
443
444
445
446perl v5.32.0                      2020-07-28                          TList(3)
Impressum