Motif Programmer's Guide Migration Version

Motif 2.1 Programmer's Guide

List

A List is an array of textual items from which the user selects one or more entries. Each item is a compound string. List has four modes, controlled by the XmNselectionPolicy resource, for selecting items:

Single Select

At most one item is selected. Performing the selection action on an item toggles the selection state of the item and deselects any other selected item.

Browse Select

At most one item is selected. Performing the selection action on an item selects the item and deselects any other selected item. Dragging Btn1 through the list moves the selection along with the cursor.

Multiple Select

Any number of items can be selected. Performing the selection action on an item toggles the selection state of the item but does not deselect any other selected item.

Extended Select

Any number of items can be selected. The user can select either continuous or discontinuous ranges of items, depending on the mouse buttons used or, when using the keyboard, on whether the List is in Normal Mode or Add Mode.

When the user makes a selection, the List invokes one of four callback lists, depending on the selection policy:

Selection Policy	Callback List
Single Select	XmNsingleSelectionCallback
Browse Select	XmNbrowseSelectionCallback
Multiple Select	XmNmultipleSelectionCallback
Extended Select	XmNextendedSelectionCallback

By default, the List does not invoke a callback list when the List is in Browse Select or Extended Select mode and the user drags the mouse cursor over a new item. It does invoke the callbacks when the user releases the mouse button. If XmNautomaticSelection is True, the List invokes the callbacks while the user is dragging the mouse.

The widget data passed to selection callback routines contains both the selected items--the compound strings--and integers representing the positions within the list of the selected items. The first item in the list is at position 1, the second item at position 2, and so on.

List has another callback list, XmNdefaultActionCallback, which it invokes when the user double clicks or presses osfActivate on an item. The widget data passed to these callback routines contains only the item at the location cursor and its position, not the selected items. When the user performs the default action via a double click, the List calls the appropriate selection callbacks on the first click and the XmNdefaultActionCallback callbacks on the second click.

List includes several other sets of resources:

Arrays and counts of the List items and selected items

The number of items, XmNvisibleItemCount, that the list can display at one time, and the position in the List of the first visible item

Several resources that affect the appearance of the list items: render table, justification (XmNstringDirection), spacing between items, and margins between the items and the List border

The maximum time interval between clicks for a double click

A resource (XmNlistSizePolicy) that determines what the List does when an item is too wide to fit into the List: it can keep its size and, if it is a ScrolledList, add a horizontal ScrollBar; grow to accommodate the item; or try to grow and, if it fails to accommodate the item but is a ScrolledList, add a ScrollBar

A resource that determines whether the ScrollBars in a ScrolledList are displayed at all times or only when needed

A ScrolledList is a List inside a ScrolledWindow. The application can use XmCreateScrolledList to create one.

In addition to its resources, List has a variety of convenience routines that allow the application to add, remove, select, and deselect items; specify the first or last visible item; find the position of an item or the positions of the selected items; set Add Mode; and scroll the List horizontally.