List widget

The list widget displays a list of text items and allows the user to select entries in the list. It is the recommended way of implementing a one-of-many choice when the number of choices is large, although the widget can also be used to select a number or range of items from a list.

The list widget supports several selection policies:

A Single Selection policy (SINGLE_SELECT) means that only one item can be selected from the list. The user selects an item by pressing a mouse button over it. If any item is already selected and the user selects a second item, the first item is no longer selected. Any specified singleSelectionCallback is invoked when an item is selected; you can specify an application procedure for this callback using the Callbacks page of the List resource panel.

With a Multiple Selection policy (MULTIPLE_SELECT) one or more items can be selected from the list. Items are selected when a mouse button is pressed while the pointer is over them. Selecting additional items does not un-select previous items. Deselection is performed by pressing the mouse button over the item a second time. The multipleSelectionCallback is invoked when items are selected and you can specify an application procedure for this in the same way as singleSelectionCallback.

Extended Selection (EXTENDED_SELECT) again allows one or more items to be selected from the list. Items are selected by pressing a mouse button on the initial item and dragging the pointer over the other desired items. This is different from Multiple Select, where each item has to be selected individually. You can de-select an individual item without deselecting others by pressing the mouse button over it with the Control key held down; without the Control key, all items are first deselected, then the item in question becomes newly selected. The extendedSelectionCallback is invoked when the mouse button is released.

Browse Selection (BROWSE_SELECT) is another single item selection policy. The user can browse the list by pushing a mouse button over an item and dragging the pointer over the list. Each item under the pointer is a candidate for selection. An item is chosen when the mouse button is released. The browseSelectionCallback is invoked when the mouse button is released.

The defaultActionCallback is invoked when an item is double clicked: you can specify an application procedure for this by using the Default button (in the Callbacks page of the List resource panel) to display the Callbacks dialog.

For more information concerning the List widget, consult XmList(3X) in the OSF/Motif Programmer's Reference.

HINTS

Items can be added to the list using the Items page of the List resource panel.

See also: