NAME

XmList — the OSF/Motif List widget class. 

SYNOPSIS

#include <Xm/List.h>

DESCRIPTION

List allows a user to select one or more items from a group of choices.  Items are selected from the list in a variety of ways, using both the pointer and the keyboard. 

List operates on an array of strings that are defined by the application.  Each string becomes an item in List, with the first string becoming the item in position 1, the second string becoming the item in position 2, and so on. 

The visual size of List is set by specifying the number of items that are visible.  If selection scrolling ability through a large set of choices is desired, use the XmCreateScrolledList convenience function. 

To select items, move the pointer or cursor to the desired item and press the mouse button or the key defined as select.  There are several styles of selection behavior, and they all highlight the selected item or items by displaying them in inverse colors.  An appropriate callback is invoked to notify the application of the user’s choice.  The application then takes whatever action is required for the specified selection. 

Classes

List inherits behavior and resources from Core and XmPrimitive classes. 

The class pointer is xmListWidgetClass. 

The class name is XmList. 

New Resources

The following table defines a set of widget resources used by the programmer to specify data.  The programmer can also set the resource values for the inherited classes to set attributes for this widget.  To reference a resource by name or by class in a .Xdefaults file, remove the XmN or XmC prefix and use the remaining letters.  To specify one of the defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remaining letters (in either lower case or upper case, but include any underscores between words).  The codes in the access column indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 

XmNautomaticSelection
Invokes XmNsingleSelectionCallback when the user moves into a new item if the value is True and the selection mode is either XmBROWSE_SELECT or XmEXTENDED_SELECT.  If False, no selection callbacks invoke until the user releases the mouse button.  See the Behavior section for further details on the interaction of this resource with the selection modes. 

XmNbrowseSelectionCallback
Specifies a list of callbacks that is called when an item is selected in the browse selection mode.  The reason is XmCR_BROWSE_SELECT. 

XmNdefaultActionCallback
Specifies a list of callbacks that is called when an item is double clicked.  The reason is XmCR_DEFAULT_ACTION. 

XmNdoubleClickInterval
Specifies the time in milliseconds that two consecutive clicks must occur within to be considered a double-click action, rather than two single-click actions.

XmNextendedSelectionCallback
Specifies a list of callbacks that is called when items are selected using the extended selection mode. The reason is XmCR_EXTENDED_SELECT. 

XmNfontList
Specifies the font list associated with the list items. This is used in conjunction with the XmNvisibleItemsCount resource to determine the height of the List widget.  Refer to XmString(3Xm) for more information on a font list structure. 

XmNitemCount
Specifies the total number of items.  This number must match XmNitems.  It is automatically updated by the list whenever an element is added to or deleted from the list. 

XmNitems
Points to an array of compound strings that are to be displayed as the list items.  Refer to XmString(3Xm) for more information on the creation and structure of compound strings. 

XmNlistMarginHeight
Specifies the height of the margin between the List border and the items.

XmNlistMarginWidth
Specifies the width of the margin between the List border and the items.

XmNlistSpacing
Specifies the spacing between list items.  When keyboard traversal is enabled, this spacing increases by the value of the XmNhighlightThickness parameter in Primitive. 

XmNmultipleSelectionCallback
Specifies a list of callbacks that is called when an item is selected in multiple selection mode. The reason is XmCR_MULTIPLE_SELECT. 

XmNselectedItemCount
Specifies the number of strings in the selected items list.

XmNselectedItems
Points to an array of compound strings that represents the list items that are currently selected, either by the user or the application.

XmNselectionPolicy
Defines the interpretation of the selection action.  This can be one of the following:

•XmSINGLE_SELECT — allows only single selections. 

•XmMULTIPLE_SELECT — allows multiple selections. 

•XmEXTENDED_SELECT — allows extended selections. 

•XmBROWSE_SELECT — allows PM "drag and browse" functionality. 

XmNsingleSelectionCallback
Specifies a list of callbacks that is called when an item is selected in single selection mode. The reason is XmCR_SINGLE_SELECT. 

XmNstringDirection
Specifies the initial direction to draw the string.  The values are XmSTRING_DIRECTION_L_TO_R and XmSTRING_DIRECTION_R_TO_L. 

XmNvisibleItemCount
Specifies the number of items that can fit in the visible space of the List work area.  The list will use this value to determine its height.

XmNhorizontalScrollBar
Specifies the widget ID of the horizontal ScrollBar.  This widget is created automatically by the XmCreateScrolledList convenience function. 

XmNlistSizePolicy
Controls the reaction of the List when an item grows horizontally beyond the current size of the List work area.  If the value is XmCONSTANT, the List viewing area will not grow, and a horizontal ScrollBar will be added.  If this resource is set to XmVARIABLE, List will grow to match the size of the longest item, and no horizontal ScrollBar will appear. 

When the value of this resource is XmRESIZE_IF_POSSIBLE, the List attempts to grow or shrink to match the width of the widest item.  If it cannot grow to match the widest size, a horizontal ScrollBar is added if the longest item is wider than the List viewing area. 

The size policy must be set at the time the List widget is created. It cannot be changed at a later time through XtSetValues. 

XmNscrollBarDisplayPolicy
Specifies the ScrollBar display policy.  When this resource is set to XmAS_NEEDED, the vertical ScrollBar will be displayed only when the number of items in the list exceeds the number of visible items.  If XmNlistSizePolicy is XmCONSTANT or XmRESIZE_IF_POSSIBLE, the horizontal ScrollBar will be displayed only if there is an item that is wider than the current width of the list.  When this resource is set to XmSTATIC, the vertical ScrollBar will always be displayed.  The horizontal ScrollBar will always be displayed if XmNlistSizePolicy is set to XmCONSTANT or XmRESIZE_IF_POSSIBLE. 

XmNscrollBarPlacement
Specifies the positioning of the ScrollBars in relation to the visible items.  The following are the values:

•XmTOP_LEFT — The horizontal ScrollBar is placed above the visible items and the vertical ScrollBar to the left of the  visible items. 

•XmBOTTOM_LEFT — The horizontal ScrollBar is placed below the visible items and the vertical ScrollBar to the left of the visible items. 

•XmTOP_RIGHT — The horizontal ScrollBar is placed above the visible items and the vertical ScrollBar to the right of the  visible items. 

•XmBOTTOM_RIGHT — The horizontal ScrollBar is placed below the visible items and the vertical ScrollBar to the right of the  visible items. 

XmNscrolledWindowMarginHeight
Specifies the margin height on the top and bottom of the ScrolledWindow.

XmNscrolledWindowMarginWidth
Specifies the margin width on the right and left sides of the ScrolledWindow.

XmNspacing
Specifies the distance that separates the ScrollBars from the visible items.

XmNverticalScrollBar
Specifies the widget ID of the vertical ScrollBar.  This widget is created automatically by the XmCreateScrolledList convenience function. 

Inherited Resources

List inherits behavior and resources from the following superclasses.  For a complete description of these resources, refer to the man page for that superclass. 

Callback Information

List defines a new callback structure.  The application must first look at the reason field and only use the structure members that are valid for that particular reason, because not all of the fields are relevant for every possible reason.  The callback structure is defined as follows:

typedef struct
{
intreason;
XEvent∗ event;
XmStringitem;
intitem_length;
intitem_position;
XmString∗ selected_items;
intselected_item_count;
intselection_type;
} XmListCallbackStruct;

reasonIndicates why the callback was invoked. 

eventPoints to the XEvent that triggered the callback.  It can be NULL. 

itemIs the item selected by this action.  selected_items points to a temporary storage space that is reused after the callback is finished.  Therefore, if an application needs to save the selected list, it should copy the list into its own data space. 

item_lengthIs the length of the item when the selection action occurred. 

item_positionIs the position in the List of the selected item. 

selected_itemsPoints to the list of items selected at the time of the event that caused the callback.  selected_items points to a temporary storage space that is reused after the callback is finished.  Therefore, if an application needs to save the selected list, it should copy the list into its own data space. 

selected_items_count
Is the number of items in the selected_items list. 

selection_typeIndicates that the most recent extended selection was either the initial selection (XmINITIAL), a modification of an existing selection (XmMODIFICATION), or an additional noncontiguous selection (XmADDITION). 

The following table describes the reasons for which the individual callback structure fields are valid:

Behavior

List provides several methods for selecting its items.  The general selection model is as follows:

The user moves the pointer to the item that is desired to be selected, either by using the mouse to move the pointer over the desired item, or, in keyboard traversal mode, moving the active highlight to the desired item with the up and down arrow keys.  The item is selected by clicking the select button on the mouse (usually the left mouse button), or by pressing the select key on the keyboard (usually defined to be the Space key). Each of the selection modes provides some variation of the above behavior. 

Note that the keyboard selection interface is only active when traversal is enabled for the List widget. 

The selection mode is set by the XmNselectionPolicy resource and is modified by the XmNautomaticSelection resource. The behavior of the various modes are defined below:

XmSINGLE_SELECT (Single Selection):
Move the mouse pointer or keyboard highlight until it is over the desired item and press the select button or key.  The item inverts its foreground and background colors to indicate that it is to be the selected object.  Any previously selected items are unselected (returned to their normal visual state). When the button or key is released, XmNsingleSelectionCallback is invoked. 

XmBROWSE_SELECT (Browse Selection):
When using the mouse, press the select button; the item under the pointer is highlighted.  While the button is held down, drag the selection by moving the pointer.  When the select button is released, the object under the pointer becomes the selected item and the XmNbrowseSelectionCallback is invoked. 

If XmNautomaticSelection is True, the XmNbrowseSelectionCallback is invoked when the select button is pressed.  For each subsequent item entered while the select button is held down, the callback is invoked when the pointer moves into the item.  No selection callback is invoked when the button is released. 

When selecting through the keyboard and XmNautomaticSelection is False, browse selection is no different from single-selection mode.  However, when XmNautomaticSelection is True, the callback is invoked for each element that is selected.  Both the keyboard highlight and the selection highlight move as the user moves through the list. 

XmMULTIPLE_SELECT (Multiple Selection):
Move the mouse pointer or keyboard highlight until it is over the desired item and press the select button or key.  The item inverts its foreground and background colors to indicate that it is a selected object.  Any previously selected items are not affected by this action.  When the button or key is released, the XmNmultipleSelectionCallback is invoked.  To unselect an item in this mode, move to a selected item and press the select button or key.  The XmNmultipleSelectionCallback is invoked with the updated selection list. 

XmEXTENDED_SELECT (Extended Selection):
This mode selects a contiguous range of objects with one action. Press the select button on the first item of the range. This begins a new selection process, which deselects any previous selection in the list. That item inverts to show its inclusion in the selection. While depressing the button, drag the cursor through other items in the List. As the pointer moves through the list, all items between the initial item and the item currently under the pointer are inverted to show that they are included in the selection. When the button is released, the XmNextendedSelectionCallback is invoked and contains a list of all selected items.  The selection_type field is set to XmINITIAL. 

Modify a selection by pressing and holding the shift key, moving to the new endpoint, and pressing the select button.  The items between the initial start point and the new end point are selected.  The rest of the selection process proceeds as above.  Any previous selections are not unselected.  When the select button is released, the XmNextendedSelectionCallback is invoked and contains a list of all selected items, both new and previous.  The selection_type field is to XmMODIFICATION. 

Items can be added to or deleted from a selected range by using the CTRL key. To add an additional range to an existing selection, move to the first item of the new group, press and hold the CTRL key, and then press the select button. The item under the pointer inverts; any previous selections are unaffected. This item becomes the initial item for the new selection range. If the pointer is dragged through additional items while the CTRL key and select button are held down, those items invert as described above.  When the select button is released, the XmNextendedSelectionCallback is invoked and contains a list of all selected items, both new and previous.  The selection_type field is set to XmADDITION. 

To delete an item or a range of items from an existing selection, move to the first item to be deselected, press and hold the CTRL key, and then press the select button. The item under the pointer returns to its normal visual state to indicate that it is no longer in the selection. This item becomes the initial item for the range to be deselected. If the pointer is dragged through additional selected items while the CTRL key and select button are held down, those items will be deselected. Any other selections are unaffected.  When the select button is released, the XmNextendedSelectionCallback is invoked and contains a list of remaining selected items, both new and previous.  The selection_type field is set to XmADDITION. 

A range of items can also be deselected by setting the initial item for the range as described above, then moving to the end of the range, and pressing the select button while holding the Shift key down. All items between the two endpoints will be deselected. When the button is released, the XmNextendedSelectionCallback will be issued as described above. 

If the XmNautomaticSelection resource is set to True, the XmNextendedSelectionCallback is invoked when the select button is pressed.  For each subsequent item the user selects or deselects, the callback is invoked when the pointer is moved into the item.  The selection_type field is set to reflect the current action.  No selection callback is invoked when the button is released. 

Keyboard selection in extended selection mode is accomplished by moving the keyboard highlight to the start of the desired range and pressing the select key.  The selection callback is invoked with a selection_type value of XmINITIAL.  Then, using the arrow keys, move the keyboard highlight to the end of the range, depress the Shift key, and press the select key.  The XmNextendedSelectionCallback is invoked with a value of XmMODIFICATION. Select additional ranges by moving to the beginning of a range, pressing the select key while depressing the CTRL key, and then moving to the end of the range and pressing the select key while holding the Shift key. Erase previously selected elements by moving to them and pressing the select key while holding down the CTRL key. In all cases, callbacks are issued as described above. 

When using the keyboard with the XmNautomaticSelection resource set to True, the XmNextendedSelectionCallback is invoked when the select button is pressed.  For each subsequent item the user selects, the callback is invoked when the pointer is moved into the item if there are modifier keys in use.  For example, start the selection by pressing the select key, and then extend it by using the arrow keys while holding down the Shift key.  The selection_type field is set to reflect the current action. There is no selection callback invoked when the button is released. 

XmDEFAULT-ACTION (Double Click)
If an object is clicked twice within the interval defined by the XmNdoubleClickInterval resource, the List interprets that as a double click and the XmNdefaultActionCallback is invoked.  The item inverts to indicate its selection. 

Default Translations

The following are the default Translations for XmList:

Button1<Motion>:ListButtonMotion()
Shift  Ctrl ~Meta<Btn1Down>: ListShiftCtrlSelect()
Shift  Ctrl ~Meta<Btn1Up>: ListShiftCtrlUnSelect()
Shift  Ctrl ~Meta<KeyDown>space: ListKbdShiftCtrlSelect()
Shift  Ctrl ~Meta<KeyUp>space: ListKbdShiftCtrlUnSelect()
Shift  Ctrl ~Meta<KeyDown>Select: ListKbdShiftCtrlSelect()
Shift  Ctrl ~Meta<KeyUp>Select: ListKbdShiftCtrlUnSelect()
Shift  ~Ctrl ~Meta<Btn1Down>: ListShiftSelect()
Shift  ~Ctrl ~Meta<Btn1Up>: ListShiftUnSelect()
Shift  ~Ctrl ~Meta<KeyDown>space: ListKbdShiftSelect()
Shift  ~Ctrl ~Meta<KeyUp>space: ListKbdShiftUnSelect()
Shift  ~Ctrl ~Meta<KeyDown>Select: ListKbdShiftSelect()
Shift  ~Ctrl ~Meta<KeyUp>Select: ListKbdShiftUnSelect()
Ctrl  ~Shift ~Meta<Btn1Down>: ListCtrlSelect()
Ctrl  ~Shift ~Meta<Btn1Up>: ListCtrlUnSelect()
Ctrl  ~Shift ~Meta<KeyDown>space: ListKbdCtrlSelect()
Ctrl  ~Shift ~Meta<KeyUp>space: ListKbdCtrlUnSelect()
Ctrl  ~Shift ~Meta<KeyDown>Select: ListKbdCtrlSelect()
Ctrl  ~Shift ~Meta<KeyUp>Select: ListKbdCtrlUnSelect()
~Shift ~Ctrl ~Meta<Btn1Down>: ListElementSelect()
~Shift ~Ctrl ~Meta<Btn1Up>: ListElementUnSelect()
~Shift ~Ctrl ~Meta<KeyDown>space: ListKbdSelect()
~Shift ~Ctrl ~Meta<KeyUp>space: ListKbdUnSelect()
~Shift ~Ctrl ~Meta<KeyDown>Select: ListKbdSelect()
~Shift ~Ctrl ~Meta<KeyUp>Select: ListKbdUnSelect()
Shift Ctrl ~Meta<Key>Up:ListShiftCtrlPrevElement()
Shift Ctrl ~Meta<Key>Down: ListShiftCtrlNextElement()
Shift ~Ctrl ~Meta<Key>Up:ListShiftPrevElement()
Shift ~Ctrl ~Meta<Key>Down: ListShiftNextElement()
~Shift Ctrl ~Meta<Key>Up:ListCtrlPrevElement()
~Shift Ctrl ~Meta<Key>Down: ListCtrlNextElement()
~Shift ~Ctrl ~Meta<Key>Up: ListPrevElement()
~Shift ~Ctrl ~Meta<Key>Down: ListNextElement()
<Enter>:ListEnter()
<Leave>:ListLeave()
<FocusIn>:ListFocusIn()
<FocusOut>:ListFocusOut()
<Unmap>:PrimitiveUnmap()
Shift<Key>Tab:PrimitivePrevTabGroup()
<Key>Tab:PrimitiveNextTabGroup()
<Key>Home:PrimitiveTraverseHome()

Keyboard Traversal

For those actions not inherited from XmPrimitive(3Xm), keyboard traversal is described in the behavior section of this man page. 

RELATED INFORMATION

Core(3Xm), XmCreateList(3Xm), XmCreateScrolledList(3Xm), XmFontListCreate(3Xm) XmListAddItem(3Xm), XmListAddItemUnselected(3Xm), XmListDeleteItem(3Xm), XmListDeletePos(3Xm), XmListDeselectItem(3Xm), XmListDeselectAllItems(3Xm), XmListSelectItem(3Xm), XmListSetHorizPos(3Xm), XmListSetItem(3Xm), XmListSetPos(3Xm), XmListSetBottomItem(3Xm), XmListSetBottomPos(3Xm), XmListSelectPos(3Xm), XmListDeselectPos(3Xm), and XmListItemExists(3Xm), XmPrimitive(3Xm), and XmStringCreate(3Xm). 

7th Edition