VtList
Create a List widget
Syntax
VtList object_name [options]
Description
Creates a List widget. (Note that the List widget may exist with
or without scrollbars; see the -scrollBar option for details.)
Returns the List widget name.
Options
- -autoSelect Boolean (CS)
- In character mode, combining this option with -selection
BROWSE will automatically select each item as the user navigates
the list. The default is False.
In graphical mode, combining this option with -selection
BROWSE will cause three callbacks to happen when the mouse is
pressed over one item and dragged to the next item:
- a selection callback from the first item
- a deselection callback from the first item
- a selection callback from the second item
Consequently, this option is usually used just for character mode,
(that is, passed as CHARM_autoSelect).
- -callback cmd (C)
- Sets the callback cmd to call when you select items
in the list (by pressing <Space> or <Enter>, or
single-clicking).
Additional callback keys
- selectedItemList
- List of items selected
- -columns integer (CS)
- In the graphical environment this makes the width of the object
integer * AverageCharWidth pixels wide, where
AverageCharWidth is the average character width in pixels for the
current character set. See the -columnWidth option
of VtSetAppValues.
In character mode this makes the object integer-2
characters wide (because the boundary line characters are included in
the width).
- -defaultCallback cmd (C)
- Callback to handle double-click events (in graphical mode) or
when <Enter> is pressed on a list item (character mode).
Additional callback keys
- (selectedItemList
- List of items selected)
- value
- List of items selected
- -itemList list (CSG)
- Specifies the contents of the List widget.
- -selection SINGLE | EXTENDED | MULTIPLE | BROWSE (CS)
- The selection methods are as follows:
- BROWSE
- (Chosen by default.) An item in the list is always
selected. Users cannot deselect an item; only select a different
one. A solid line shows around the last selected item.
- SINGLE
- Simple select and deselect is permitted. Only one item can
be selected at a time. A dashed line surrounds the last selected (or
deselected) item.
- EXTENDED
- An item is always selected, and surrounded by a solid
line. Drag select (pressing the mouse button with the pointer over the
desired items) extends the selection to cover additional objects.
Multiple non-contiguous objects can be selected using <Control>
mouse-click. <Shift>left-mouse-button selects all the items
between the current item and the last item selected. The
-callback is invoked when the mouse button is
released.
- MULTIPLE
- Any number of items can be selected or deselected. A dashed
line surrounds the last selected or deselected items. Drag selection
is not available, but non-contiguous selection is direct (that is,
selecting additional items does not deselect previous items). The
-callback is invoked when each item is selected.
- -rows integer (CSG)
- Specifies that integer character rows are to be displayed in the List.
- -scrollBar boolean (CS)
- If this option is set to false, a vertical scrollbar is
displayed only when the number of items in the List exceeds the number
of visible items. If set to true, a vertical scrollbar is always
displayed. The default is false.
Note that to get a horizontal scrollbar to appear, the option
-width or -columns must be
set. Otherwise the widget will grow as needed and scrollbars will only
appear when the list exceeds the available area.
- -topItemPosition integer (CSG)
- Sets the position of the item that is at the top of the list.
Example
The following code produces a List widget with 6 rows and 25 columns
offering multiple selections and containing 7 items.
set app [VtOpen "VtList Demo"]
set form [VtForm $app.form]
set list [VtList $form.list \
-rows 6 \
-columns 25 \
-selection MULTIPLE \
-itemList {Apple Banana Kumquat Mango Grape Pineapple Grapefruit} ]
VtShowDialog $app.form
VtMainLoop
This code produces the following:
See also: