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:

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: