List widgets

List widgets (CwList) present a list of items and allow the user to select one or more items from the list. List widgets are created using thecreateList:argBlock:and createScrolledList:argBlock: convenience methods. The latter method makes the list scrollable, but otherwise provides basically the same functionality. Scrolled lists are discussed on Scrolled lists.

The items in the list and the selected items are specified by the items and selectedItems resources, respectively. The selectionPolicy resource specifies the policy for selecting items. It has four possible settings:

XmBROWSESELECT

Allows only single selection. Behavior might vary from platform to platform, but normally the selection moves when the mouse is dragged. This is the default selection policy.

XmSINGLESELECT

Allows only single selection. Behavior might vary from platform to platform, but normally the selection remains the same when the mouse is dragged.

XmMULTIPLESELECT

Allows multiple items to be selected. The selection of an item is toggled when it is clicked on. Clicking on an item does not deselect previously selected items.

XmEXTENDEDSELECT

Allows multiple items to be selected, either by dragging the selection or by clicking on items with a modifier key held down. Behavior might vary from platform to platform, but normally clicking on an item without a modifier key held down deselects all previously selected items.

 

Tip:

On some platforms, browse select and single select work the same way.

List widgets provide several methods for adding, deleting and replacing items and selected items in the list.

The selectionPolicy resource determines which callback is used to notify the application of changes in the selection. List widgets support the following callbacks:

browseSelectionCallback

Executed when an item is selected in browse selection mode

singleSelectionCallback

Executed when an item is selected in single selection mode

multipleSelectionCallback

Executed when an item or group of items is selected in multiple selection mode

extendedSelectionCallback

Executed when an item or group of items is selected in extended selection mode

defaultActionCallback

Executed when an item is double clicked (all modes)

The call data of the selection callback specifies the item or items that were selected, and the position(s) of the selected item(s) in the list. Item positions in the list are numbered starting from one.