xmList

An xmScrolledList should be used when the number of items may be too large to display in the allotted space in the interface: the interface is automatically changed to display an xmScrollBar (see below) to move the visible part of the list. A scrolled list widget w is a composite widget that has the following children:

w.HorScrollBar    w.VertScrollBar    w.ClipWindow

xmScrolledList .list managed
.list.VertScrollBar setValues -troughColor red

single_select

Only one item may be selected at a time. A click within the list deselects any previous selection, and selects the highlighted item. Each time a selection is made, singleSelectionCallback is called.

multiple_select

Shift-clicks may be used to make multiple selections. Each time an item is selected or unselected, multipleSelectionCallback is called.

extended_select

Any single mouse click deselects anything, and selects the current item. Any shift-click extends the current selection up to the item underneath the mouse pointer. Each time an item is selected or deselected, extendedSelectionCallback is called.

browse_select

Mouse dragging may be used to select a range of items. Using shift-click or shift-drag, more than one range may be selected at a given time. For each newly selected item, browseSelectionCallback is called, once the mouse button is released. This is the default mode.

L addItem item position

Add the specified item (any Tcl string value) to the existing list, at the given position. If position is 1 or greater, the new item is placed in that position; if position is 0, the new item is placed at the end.

L addItemUnselected item position

Normally, if one item is selected, the second instance is also selected. This method prevents a newly inserted item from being selected.

L deletePosition position

Delete the item specified by position. If position is 0, delete the last item.

L deleteItem item

Delete the first occurrence of item in the list. A warning occurs if the item does not exist.

L deleteAllItems

Delete all items in the list.

L selectPosition position notify

Select the item at a given position in the list. If notify is true, the corresponding callback is invoked.

L selectItem item notify

Select the first specified item in the list. If notify is true, the corresponding callback should be invoked.

L deselectItem item

Deselect the first specified item in the list. If the item is at multiple positions in the list, only the first occurrence is deselected, even if it is not the selected one.

L deselectPosition position

Deselect the item at the given position in the list.

L itemExists item

Reply true if the item is in the list, false if not.

L itemPosition item

Return the list position of the given item, or 0 if item does not exist.

L positionSelected position

Reply true if the position is currently selected, false if not.

L setItem item

Scroll the list so that the first occurrence of item is at the top of the currently displayed part of the list.

L setPosition position

Scroll the list so that the item at the given position is at the top of the currently displayed part of the list.

L setBottomItem item

Scroll the list so that the first occurrence of item is at the bottom of the currently displayed part of the list.

L setBottomPosition position

Scroll the list so that the item at the given position is at the bottom of the currently displayed part of the list.

xmList Resources

Resource Name	Default Value	Type or Legal Values
-automaticSelection	False	Boolean
-doubleClickInterval	Inherited	Integer
-fontList	Inherited	Font List
-itemCount	computed	Integer
-items	none	String array
-listMarginHeight	0	Integer
-listMarginWidth	0	Integer
-listSizePolicy	variable	constant resize_if_possible variable
-listSpacing	0	Integer
-scrollBarDisplayPolicy	as_needed	as_needed static
-selectedItemCount	0	Integer
-selectedItems	none	String array
-selectionPolicy	browse_select	browse_select extended_select multiple_select single_select
-stringDirection	Inherited	string_direction_l_to_r string_direction_r_to_l
-topItemPosition	1	Integer
-visibleItemCount	1	Integer

Other resources are derived from the Core, Primitive, and Label classes.

Supported list-specific callbacks are listed in Table 4-33.

List Widget Callbacks

Method Name	Why
defaultActionCallback	An item was double-clicked
singleSelectionCallback	A single item was selected
multipleSelectionCallback	An item was selected while in multiple selection mode
browseSelectionCallback	An item was selected while in browse selection mode
extendedSelectionCallback	An item was selected while in extended selection mode

The following substitutions are defined for the above callbacks:

%item

The currently selected item string

%item_length

The string length of the currently selected item

%item_position

The current item position, 1 indicating the first one

%selected_items

Valid only in multiple, browse, or extended callbacks; returns a comma-separated list of all currently-selected items

Text widgets also inherit the standard callbacks from the Primitive class, namely helpCallback and destroyCallback.