XmList(Xm)

XmList -- the List widget class

Syntax

#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 compound strings that are defined by the application. Each compound string becomes an item in the List, with the first compound string becoming the item in position 1, the second becoming the item in position 2, and so on.

The size of the List is set by specifying the number of items that are visible. If the number of visible items is not specified, the height of the list controls the number of visible items. Each item assumes the height of the tallest element in the list. To create a list that allows the user to scroll easily through a large number of items, use the XmCreateScrolledList convenience function.

To select items, move the pointer or cursor to the desired item and press the BSelect mouse button or the key defined as KSelect. 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. When a List is insensitive, all of the list items are displayed in a stippled fill pattern.

Selection

Each list has one of four selection models:

Single Select
Browse Select
Multiple Select
Extended Select

In Single Select and Browse Select, at most one item is selected at a time. In Single Select, pressing BSelect on an item toggles its selection state and deselects any other selected item. In Browse Select, pressing BSelect on an item selects it and deselects any other selected item; dragging BSelect moves the selection as the pointer is moved. Releasing BSelect on an item moves the location cursor to that item.

In Multiple Select, any number of items can be selected at a time. Pressing BSelect on an item toggles its selection state but does not deselect any other selected items.

In Extended Select, any number of items can be selected at a time, and the user can easily select ranges of items. Pressing BSelect on an item selects it and deselects any other selected item. Dragging BSelect or pressing or dragging BExtend following a BSelect action selects all items between the item under the pointer and the item on which BSelect was pressed. This action also deselects any other selected items outside that range.

Extended Select also allows the user to select and deselect discontiguous ranges of items. Pressing BToggle on an item toggles its selection state but does not deselect any other selected items. Dragging BToggle or pressing or dragging BExtend following a BToggle action sets the selection state of all items between the item under the pointer and the item on which BToggle was pressed to the state of the item on which BToggle was pressed. This action does not deselect any other selected items outside that range.

All selection operations available from the mouse are also available from the keyboard. List has two keyboard selection modes, Normal Mode and Add Mode. In Normal Mode, navigation operations and KSelect select the item at the location cursor and deselect any other selected items. In Add Mode, navigation operations have no effect on selection, and KSelect toggles the selection state of the item at the location cursor without deselecting any other selected items, except in Single Select.

Single and Multiple Select use Add Mode, and Browse Select uses Normal Mode.

Extended Select can use either mode; the user changes modes by pressing KAddMode. In Extended Select Normal Mode, pressing KSelect has the same effect as pressing BSelect; KExtend and shifted navigation have the same effect as pressing BExtend following a BSelect action. In Extended Select Add Mode, pressing KSelect has the same effect as pressing BToggle; KExtend and shifted navigation have the same effect as pressing BExtend following a BToggle action.

Normal Mode is indicated by a solid location cursor, and Add Mode is indicated by a dashed location cursor.

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 lowercase or uppercase, 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).

XmList resource set

Name Class Type Default Access

XmNautomaticSelection XmCAutomaticSelection Boolean False CSG

XmNbrowseSelectionCallback XmCCallback XtCallbackList NULL C

XmNdefaultActionCallback XmCCallback XtCallbackList NULL C

XmNdoubleClickInterval XmCDoubleClickInterval int dynamic CSG

XmNextendedSelectionCallback XmCCallback XtCallbackList NULL C

XmNfontList XmCFontList XmFontList dynamic CSG

XmNitemCount XmCItemCount int 0 CSG

XmNitems XmCItems XmStringTable NULL CSG

XmNlistMarginHeight XmCListMarginHeight Dimension 0 CSG

XmNlistMarginWidth XmCListMarginWidth Dimension 0 CSG

XmNlistSizePolicy XmCListSizePolicy unsigned char XmVARIABLE CG

XmNlistSpacing XmCListSpacing Dimension 0 CSG

XmNmultipleSelectionCallback XmCCallback XtCallbackList NULL C

XmNscrollBarDisplayPolicy XmCScrollBarDisplayPolicy unsigned char XmAS_NEEDED

CSG

XmNselectedItemCount XmCSelectedItemCount int 0 CSG

XmNselectedItems XmCSelectedItems XmStringTable NULL CSG

XmNselectionPolicy XmCSelectionPolicy unsigned char XmBROWSE_SELECT CSG

XmNsingleSelectionCallback XmCCallback XtCallbackList NULL C

XmNstringDirection XmCStringDirection XmStringDirection dynamic CSG

XmNtopItemPosition XmCTopItemPosition int 1 CSG

XmNvisibleItemCount XmCVisibleItemCount int dynamic CSG

Name	Class	Type	Default	Access
XmNautomaticSelection	XmCAutomaticSelection	Boolean	False	CSG
XmNbrowseSelectionCallback	XmCCallback	XtCallbackList	NULL	C
XmNdefaultActionCallback	XmCCallback	XtCallbackList	NULL	C
XmNdoubleClickInterval	XmCDoubleClickInterval	int	dynamic	CSG
XmNextendedSelectionCallback	XmCCallback	XtCallbackList	NULL	C
XmNfontList	XmCFontList	XmFontList	dynamic	CSG
XmNitemCount	XmCItemCount	int	0	CSG
XmNitems	XmCItems	XmStringTable	NULL	CSG
XmNlistMarginHeight	XmCListMarginHeight	Dimension	0	CSG
XmNlistMarginWidth	XmCListMarginWidth	Dimension	0	CSG
XmNlistSizePolicy	XmCListSizePolicy	unsigned char	XmVARIABLE	CG
XmNlistSpacing	XmCListSpacing	Dimension	0	CSG
XmNmultipleSelectionCallback	XmCCallback	XtCallbackList	NULL	C
XmNscrollBarDisplayPolicy	XmCScrollBarDisplayPolicy	unsigned	char	XmAS_NEEDED
CSG
XmNselectedItemCount	XmCSelectedItemCount	int	0	CSG
XmNselectedItems	XmCSelectedItems	XmStringTable	NULL	CSG
XmNselectionPolicy	XmCSelectionPolicy	unsigned char	XmBROWSE_SELECT	CSG
XmNsingleSelectionCallback	XmCCallback	XtCallbackList	NULL	C
XmNstringDirection	XmCStringDirection	XmStringDirection	dynamic	CSG
XmNtopItemPosition	XmCTopItemPosition	int	1	CSG
XmNvisibleItemCount	XmCVisibleItemCount	int	dynamic	CSG

XmNautomaticSelection

Invokes XmNbrowseSelectionCallback or XmNextendedSelectionCallback when BSelect is pressed and the items that are shown as selected change if the value is True and the selection mode is either XmBROWSE_SELECT or XmEXTENDED_SELECT respectively. If False, no selection callbacks are invoked 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 or KActivate is pressed. The reason is XmCR_DEFAULT_ACTION.

XmNdoubleClickInterval

If a button click is followed by another button click within the time span specified by this resource (in milliseconds), the button clicks are considered a double-click action, rather than two single-click actions. The value must not be negative. The default value is the display's multi-click time.

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 XmNvisibleItemCount resource to determine the height of the List widget. If this value is NULL at initialization, the font list is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard or VendorShell widget class. If such an ancestor is found, the font list is initialized to the XmNtextFontList of the ancestor widget. If no such ancestor is found, the default is implementation dependent. Refer to XmFontList(Xm) for more information on a font list structure.

XmNitemCount

Specifies the total number of items. The value must be the number of items in XmNitems and must not be negative. It is automatically updated by the list whenever an item 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(Xm) for more information on the creation and structure of compound strings. XtGetValues for this resource returns the list items themselves, not a copy of the list items. The application must not free the returned items.

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.

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 does not grow, and a horizontal ScrollBar is added for a ScrolledList. If this resource is set to XmVARIABLE, the List grows to match the size of the longest item, and no horizontal ScrollBar appears.

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 for a ScrolledList 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.

XmNlistSpacing

Specifies the spacing between list items. This spacing increases by the value of the XmNhighlightThickness resource 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.

XmNscrollBarDisplayPolicy

Controls the display of vertical ScrollBars in a ScrolledList. When the value of this resource is XmAS_NEEDED, a vertical ScrollBar is displayed only when the number of items in the List exceeds the number of Visible items. When the value is XmSTATIC, a vertical ScrollBar is always displayed.

XmNselectedItemCount

Specifies the number of strings in the selected items list. The value must be the number of items in XmNselectedItems and must not be negative.

XmNselectedItems

Points to an array of compound strings that represents the list items that are currently selected, either by the user or by the application. XtGetValues for this resource returns the list items themselves, not a copy of the list items. The application must not free the returned items.

Setting XmNselectedItems selects those list items that exactly match items in the given XmNselectedItems list. There may be additional items in XmNselectedItems that do not match items in the list. These items remain until XmNselectedItems is updated. If XmNitems is changed such that the list now contains items matching previously unmatched items in XmNselectedItems, those new items will also appear selected.

Any user interaction with the list that causes at least one item to be selected or deselected and any call to XmListDeselectAllItems, XmListDeselectAllItems, XmListDeselectPos, XmListSelectItem, XmListSelectPos, or XmListUpdateSelectedList cause XmNselectedItems to be updated immediately to exactly reflect the visual state of the list. Calls to any other XmList functions do not affect XmNselectedItems.

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 ``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. The value of this resource is determined at creation time. If the widget's parent is a manager, this value is inherited from the widget's parent, otherwise it is set to XmSTRING_DIRECTION_L_TO_R.

XmNtopItemPosition

Specifies the position of the item that is the first visible item in the list. Setting this resource is equivalent to calling the XmListSetPos function. The position of the first item in the list is 1; the position of the second item is 2; and so on. A position of 0 specifies the last item in the list. The value must not be negative.

XmNvisibleItemCount

Specifies the number of items that can fit in the visible space of the list work area. The List uses this value to determine its height. The value must be greater than 0.

Inherited resources

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

XmPrimitive resource set

Name Class Type Default Access

XmNboexpandttomShadowColor XmCBottomShadowColor Pixel dynamic CSG

XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG

XmNforeground XmCForeground Pixel dynamic CSG

XmNhelpCallback XmCCallback XtCallbackList NULL C

XmNhighlightColor XmCHighlightColor Pixel dynamic CSG

XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG

XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG

XmNhighlightThickness XmCHighlightThickness Dimension 2 CSG

XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG

XmNshadowThickness XmCShadowThickness Dimension 2 CSG

XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG

XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG

XmNtraversalOn XmCTraversalOn Boolean True CSG

XmNunitType XmCUnitType unsigned char dynamic CSG

XmNuserData XmCUserData XtPointer NULL CSG

Name	Class	Type	Default	Access
XmNboexpandttomShadowColor	XmCBottomShadowColor	Pixel	dynamic	CSG
XmNbottomShadowPixmap	XmCBottomShadowPixmap	Pixmap	XmUNSPECIFIED_PIXMAP	CSG
XmNforeground	XmCForeground	Pixel	dynamic	CSG
XmNhelpCallback	XmCCallback	XtCallbackList	NULL	C
XmNhighlightColor	XmCHighlightColor	Pixel	dynamic	CSG
XmNhighlightOnEnter	XmCHighlightOnEnter	Boolean	False	CSG
XmNhighlightPixmap	XmCHighlightPixmap	Pixmap	dynamic	CSG
XmNhighlightThickness	XmCHighlightThickness	Dimension	2	CSG
XmNnavigationType	XmCNavigationType	XmNavigationType	XmTAB_GROUP	CSG
XmNshadowThickness	XmCShadowThickness	Dimension	2	CSG
XmNtopShadowColor	XmCTopShadowColor	Pixel	dynamic	CSG
XmNtopShadowPixmap	XmCTopShadowPixmap	Pixmap	dynamic	CSG
XmNtraversalOn	XmCTraversalOn	Boolean	True	CSG
XmNunitType	XmCUnitType	unsigned char	dynamic	CSG
XmNuserData	XmCUserData	XtPointer	NULL	CSG

Core resource set

Name Class Type Default Access

XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG

XmNancestorSensitive XmCSensitive Boolean dynamic G

XmNbackground XmCBackground Pixel dynamic CSG

XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG

XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG

XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG

XmNborderWidth XmCBorderWidth Dimension 0 CSG

XmNcolormap XmCColormap Colormap dynamic CG

XmNdepth XmCDepth int dynamic CG

XmNdestroyCallback XmCCallback XtCallbackList NULL C

XmNheight XmCHeight Dimension dynamic CSG

XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C

XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG

XmNscreen XmCScreen Screen dynamic CG

XmNsensitive XmCSensitive Boolean True CSG

XmNtranslations XmCTranslations XtTranslations dynamic CSG

XmNwidth XmCWidth Dimension dynamic CSG

XmNx XmCPosition Position 0 CSG

XmNy XmCPosition Position 0 CSG

Name	Class	Type	Default	Access
XmNaccelerators	XmCAccelerators	XtAccelerators	dynamic	CSG
XmNancestorSensitive	XmCSensitive	Boolean	dynamic	G
XmNbackground	XmCBackground	Pixel	dynamic	CSG
XmNbackgroundPixmap	XmCPixmap	Pixmap	XmUNSPECIFIED_PIXMAP	CSG
XmNborderColor	XmCBorderColor	Pixel	XtDefaultForeground	CSG
XmNborderPixmap	XmCPixmap	Pixmap	XmUNSPECIFIED_PIXMAP	CSG
XmNborderWidth	XmCBorderWidth	Dimension	0	CSG
XmNcolormap	XmCColormap	Colormap	dynamic	CG
XmNdepth	XmCDepth	int	dynamic	CG
XmNdestroyCallback	XmCCallback	XtCallbackList	NULL	C
XmNheight	XmCHeight	Dimension	dynamic	CSG
XmNinitialResourcesPersistent	XmCInitialResourcesPersistent	Boolean	True	C
XmNmappedWhenManaged	XmCMappedWhenManaged	Boolean	True	CSG
XmNscreen	XmCScreen	Screen	dynamic	CG
XmNsensitive	XmCSensitive	Boolean	True	CSG
XmNtranslations	XmCTranslations	XtTranslations	dynamic	CSG
XmNwidth	XmCWidth	Dimension	dynamic	CSG
XmNx	XmCPosition	Position	0	CSG
XmNy	XmCPosition	Position	0	CSG

Callback information

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

   typedef struct
   {
   	int		reason;
   	XEvent		*event;
   	XmString	item;
   	int		item_length;
   	int		item_position;
   	XmString	*selected_items;
   	int		selected_item_count;
   	int		*selected_item_positions;
   	char		selection_type;
   } XmListCallbackStruct;

reason: Indicates why the callback was invoked.
event: Points to the XEvent that triggered the callback. It can be NULL.
item: Is the last item selected at the time of the event that caused the callback. item points to a temporary storage space that is reused after the callback is finished. Therefore, if an application needs to save the item, it should copy the item into its own data space.
item_length: Is the length in bytes of item.
item_position: Is the position of item in the List's XmNitems array.
selected_items: Is a 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_item_count: Is the number of items in the selected_items list. This number must be non-negative.
selected_item_positions: Is an array of integers, one for each selected item, representing the position of each selected item in the List's XmNitems array. selected_item_positions points to a temporary storage space that is reused after the callback is finished. Therefore, if an application needs to save this array, it should copy the array into its own data space.
selection_type: Indicates that the most recent extended selection was 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:

Reason Valid fields

XmCR_SINGLE_SELECT reason, event, item, item_length, item_position

XmCR_DEFAULT_ACTION reason, event, item, item_length, item_position, selected_items, selected_item_count, selected_item_positions

XmCR_BROWSE_SELECT reason, event, item, item_length, item_position

XmCR_MULTIPLE_SELECT reason, event, item, item_length, item_position, selected_items, selected_item_count, selected_item_positions

XmCR_EXTENDED_SELECT reason, event, item, item_length, item_position, selected_items, selected_item_count, selected_item_positions, selection_type

Reason	Valid fields
XmCR_SINGLE_SELECT	reason, event, item, item_length, item_position
XmCR_DEFAULT_ACTION	reason, event, item, item_length, item_position, selected_items, selected_item_count, selected_item_positions
XmCR_BROWSE_SELECT	reason, event, item, item_length, item_position
XmCR_MULTIPLE_SELECT	reason, event, item, item_length, item_position, selected_items, selected_item_count, selected_item_positions
XmCR_EXTENDED_SELECT	reason, event, item, item_length, item_position, selected_items, selected_item_count, selected_item_positions, selection_type

Translations

XmList includes translations from Primitive. The XmList translations are listed in the following table. These translations may not directly correspond to a translation table.

   BSelect Press:		ListBeginSelect()
   BSelect Motion:		ListButtonMotion()
   BSelect Release:	ListEndSelect()

   BExtend Press:		ListBeginExtend()
   BExtend Motion:		ListButtonMotion()
   BExtend Release:	ListEndExtend()

   BToggle Press:		ListBeginToggle()
   BToggle Motion:		ListButtonMotion()
   BToggle Release:	ListEndToggle()
   BDrag Press:		ListProcessDrag()

   KUp:			ListPrevItem()
   MShift KUp:		ListExtendPrevItem()

   KDown:			ListNextItem()
   MShift KDown:		ListExtendNextItem()

   KLeft:			ListLeftChar()
   MCtrl KLeft:		ListLeftPage()

   KRight:			ListRightChar()
   MCtrl KRight:		ListRightPage()

   KPageUp:		ListPrevPage()
   KPageDown:		ListNextPage()
   KPageLeft:		ListLeftPage()
   KPageRight:		ListRightPage()

   KBeginLine:		ListBeginLine()
   KEndLine:		ListEndLine()

   KBeginData:		ListBeginData()
   MShift KBeginData:	ListBeginDataExtend()

   KEndData:		ListEndData()
   MShift KEndData:	ListEndDataExtend()

   KAddMode:		ListAddMode()

   KActivate:		ListKbdActivate()

   KCopy Press:		ListCopyToClipboard()
   KSelect Press:		ListKbdBeginSelect()
   KSelect Release:	ListKbdEndSelect()

   KExtend Press:		ListKbdBeginExtend()
   KExtend Release:	ListKbdEndExtend()

   MAny KCancel:		ListKbdCancel()
   KSelectAll:		ListKbdSelectAll()
   KDeselectAll:		ListKbdDeSelectAll()

   KHelp:			PrimitiveHelp()
   KNextField		PrimitiveNextTabGroup()
   KPrevField		PrimitivePrevTabGroup()

Action routines

The XmList action routines are described below. The current selection is always shown with inverted colors.

ListAddMode():

Toggles the state of Add Mode for keyboard selection.

ListBeginData():

Moves the location cursor to the first item in the list. In Normal Mode, this also deselects any current selection, selects the first item in the list, and calls the appropriate selection callbacks (XmNbrowseSelectionCallback when XmNselectionPolicy is set to XmBROWSE_SELECT, XmNextendedSelectionCallback when XmNselectionPolicy is set to XmEXTENDED_SELECT).

ListBeginDataExtend():

If the XmNselectionPolicy is set to XmMULTIPLE_SELECT or XmEXTENDED_SELECT, moves the location cursor to the first item in the list.

If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done. Changes the selection state of the first item and all items between it and the current anchor point to the state of the item at the current anchor point. Calls the XmNextendedSelectionCallback callbacks.

ListBeginExtend():

If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done. Changes the selection state of the item under the pointer and all items between it and the current anchor point to the state of the item at the current anchor point. If XmNautomaticSelection is set to True, calls the XmNextendedSelectionCallback callbacks.

ListBeginLine():

Moves the horizontal scroll region to the beginning of the line.

ListBeginSelect():

If the XmNselectionPolicy is set to XmSINGLE_SELECT, deselects any current selection and toggles the selection state of the item under the pointer.

If the XmNselectionPolicy is set to XmBROWSE_SELECT, deselects any current selection and selects the item under the pointer. If XmNautomaticSelection is set to True, calls the XmNbrowseSelectionCallback callbacks.

If the XmNselectionPolicy is set to XmMULTIPLE_SELECT, toggles the selection state of the item under the pointer. Any previous selections remain.

If the XmNselectionPolicy is set to XmEXTENDED_SELECT, deselects any current selection, selects the item under the pointer, and sets the current anchor at that item. If XmNautomaticSelection is set to True, calls the XmNextendedSelectionCallback callbacks.

ListBeginToggle():

If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the following: Moves the current anchor to the item under the pointer without changing the current selection. If the item is unselected, it is selected; if the item is selected, it is unselected. If XmNautomaticSelection is set to True, calls the XmNextendedSelectionCallback callbacks.

ListButtonMotion():

If the XmNselectionPolicy is set to XmBROWSE_SELECT, deselects any current selection and selects the item under the pointer. If XmNautomaticSelection is set to True and the pointer has entered a new list item, calls the XmNbrowseSelectionCallback callbacks.

If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the following: If an extended selection is being made and an extended selection has previously been made from the current anchor point, restores the selection state of the items in that range to their state before the previous extended selection was done. Changes the selection state of the item under the pointer and all items between it and the current anchor point to the state of the item at the current anchor point. If XmNautomaticSelection is set to True and the pointer has entered a new list item, calls the XmNextendedSelectionCallback callbacks.

If the pointer leaves a scrolled list, this action scrolls the list in the direction of the pointer motion.

ListCopyToClipboard()

Copies the content of the selected items to the clipboard as a single compound string with each item separated by a newline.

ListEndData():

Moves the location cursor to the last item in the list. In Normal Mode, this also deselects any current selection, selects the last item in the list, and calls the appropriate selection callbacks (XmNbrowseSelectionCallback when XmNselectionPolicy is set to XmBROWSE_SELECT, XmNextendedSelectionCallback when XmNselectionPolicy is set to XmEXTENDED_SELECT).

ListEndDataExtend():

If the XmNselectionPolicy is set to XmMULTIPLE_SELECT or XmEXTENDED_SELECT, moves the location cursor to the last item in the list.

If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done. Changes the selection state of the last item and all items between it and the current anchor point to the state of the item at the current anchor point. Calls the XmNextendedSelectionCallback callbacks.

ListEndExtend():

If the XmNselectionPolicy is set to XmEXTENDED_SELECT, moves the location cursor to the last item selected or deselected and, if XmNautomaticSelection is set to False, calls the XmNextendedSelectionCallback callbacks.

ListEndLine():

Moves the horizontal scroll region to the end of the line.

ListEndSelect():

If the XmNselectionPolicy is set to XmSINGLE_SELECT or XmMULTIPLE_SELECT, moves the location cursor to the last item selected or deselected and calls the appropriate selection callbacks (XmNsingleSelectionCallback when XmNselectionPolicy is set to XmSINGLE_SELECT, XmNmultipleSelectionCallback when XmNselectionPolicy is set to XmMULTIPLE_SELECT).

If the XmNselectionPolicy is set to XmBROWSE_SELECT or XmEXTENDED_SELECT, moves the location cursor to the last item selected or deselected and, if XmNautomaticSelection is set to False, calls the appropriate selection callbacks (XmNbrowseSelectionCallback when XmNselectionPolicy is set to XmBROWSE_SELECT, XmNextendedSelectionCallback when XmNselectionPolicy is set to XmEXTENDED_SELECT).

ListEndToggle():

ListExtendNextItem():

If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done. Moves the location cursor to the next item and changes the selection state of the item and all items between it and the current anchor point to the state of the item at the current anchor point. Calls the XmNextendedSelectionCallback callbacks.

ListExtendPrevItem():

If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done. Moves the location cursor to the previous item and changes the selection state of the item and all items between it and the current anchor point to the state of the item at the current anchor point. Calls the XmNextendedSelectionCallback callbacks.

ListScrollCursorVertically(percentage):

Scrolls the line containing the insertion cursor vertically to an intermediate position in the visible window based on an input percentage. A value of 0 indicates the top of the window; a value of 100, the bottom of the window. If this action is called with no argument, the line containing the insertion cursor is scrolled vertically to a new position designated by the y event passed to the routine.

ListKbdActivate():

Calls the callbacks for XmNdefaultActionCallback. If the List's parent is a manager, this action passes the event to the parent.

ListKbdBeginExtend():

If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done. Changes the selection state of the item at the location cursor and all items between it and the current anchor point to the state of the item at the current anchor point. If XmNautomaticSelection is set to True, calls the XmNextendedSelectionCallback callbacks.

ListKbdBeginSelect():

If the XmNselectionPolicy is set to XmSINGLE_SELECT, deselects any current selection and toggles the state of the item at the location cursor.

If the XmNselectionPolicy is set to XmBROWSE_SELECT, deselects any current selection and selects the item at the location cursor. If XmNautomaticSelection is set to True, calls the XmNbrowseSelectionCallback callbacks.

If the XmNselectionPolicy is set to XmMULTIPLE_SELECT, toggles the selection state of the item at the location cursor. Any previous selections remain.

If the XmNselectionPolicy is set to XmEXTENDED_SELECT, moves the current anchor to the item at the location cursor. In Normal Mode, deselects any current selection and selects the item at the location cursor. In Add Mode, toggles the selection state of the item at the location cursor and leaves the current selection unchanged. If XmNautomaticSelection is set to True, calls the XmNextendedSelectionCallback callbacks.

ListKbdCancel():

If the XmNselectionPolicy is set to XmEXTENDED_SELECT and an extended selection is being made from the current anchor point, cancels the new selection and restores the selection state of the items in that range to their state before the extended selection was done. If XmNautomaticSelection is set to True, calls the XmNextendedSelectionCallback callbacks, otherwise, and if the parent is a manager, passes the event to the parent.

ListKbdDeSelectAll():

If the XmNselectionPolicy is set to XmSINGLE_SELECT, XmMULTIPLE_SELECT, or XmEXTENDED_SELECT in Add Mode, deselects all items in the list. If the XmNselectionPolicy is set to XmEXTENDED_SELECT in Normal Mode, deselects all items in the list (except the item at the location cursor if the shell's XmNkeyboardFocusPolicy is XmEXPLICIT). Calls the appropriate selection callbacks (XmNsingleSelectionCallback when XmNselectionPolicy is set to XmSINGLE_SELECT, XmNmultipleSelectionCallback when XmNselectionPolicy is set to XmMULTIPLE_SELECT, XmNextendedSelectionCallback when XmNselectionPolicy is set to XmEXTENDED_SELECT).

ListKbdEndExtend():

If the XmNselectionPolicy is set to XmEXTENDED_SELECT and if XmNautomaticSelection is set to False, calls the XmNextendedSelectionCallback callbacks.

ListKbdEndSelect():

If the XmNselectionPolicy is set to XmSINGLE_SELECT or XmMULTIPLE_SELECT or if XmNautomaticSelection is set to False, calls the appropriate selection callbacks (XmNsingleSelectionCallback when XmNselectionPolicy is set to XmSINGLE_SELECT, XmNbrowseSelectionCallback when XmNselectionPolicy is set to XmBROWSE_SELECT, XmNmultipleSelectionCallback when XmNselectionPolicy is set to XmMULTIPLE_SELECT, XmNextendedSelectionCallback when XmNselectionPolicy is set to XmEXTENDED_SELECT).

ListKbdSelectAll():

If the XmNselectionPolicy is set to XmSINGLE_SELECT or XmBROWSE_SELECT, selects the item at the location cursor. If the XmNselectionPolicy is set to XmEXTENDED_SELECT or XmMULTIPLE_SELECT, selects all items in the list. Calls the appropriate selection callbacks (XmNsingleSelectionCallback when XmNselectionPolicy is set to XmSINGLE_SELECT, XmNbrowseSelectionCallback when XmNselectionPolicy is set to XmBROWSE_SELECT, XmNmultipleSelectionCallback when XmNselectionPolicy is set to XmMULTIPLE_SELECT, XmNextendedSelectionCallback when XmNselectionPolicy is set to XmEXTENDED_SELECT).

ListLeftChar():

Scrolls the list one character to the left.

ListLeftPage():

Scrolls the list one page to the left.

ListNextItem():

Moves the location cursor to the next item in the list.

If the XmNselectionPolicy is set to XmBROWSE_SELECT, this action also selects the next item, deselects any current selection, and calls the XmNbrowseSelectionCallback callbacks.

If the XmNselectionPolicy is set to XmEXTENDED_SELECT, this action in Normal Mode also selects the next item, deselects any current selection, moves the current anchor to the next item, and calls the XmNextendedSelectionCallback callbacks. In Add Mode this action does not affect the selection or the anchor.

ListNextPage():

Scrolls the list to the next page, moving the location cursor to a new item.

If the XmNselectionPolicy is set to XmBROWSE_SELECT, this action also selects the new item, deselects any current selection, and calls the XmNbrowseSelectionCallback callbacks.

If the XmNselectionPolicy is set to XmEXTENDED_SELECT, this action in Normal Mode also selects the new item, deselects any current selection, moves the current anchor to the new item, and calls the XmNextendedSelectionCallback callbacks. In Add Mode this action does not affect the selection or the anchor.

ListPrevItem():

Moves the location cursor to the previous item in the list.

If the XmNselectionPolicy is set to XmBROWSE_SELECT, this action also selects the previous item, deselects any current selection, and calls the XmNbrowseSelectionCallback callbacks.

If the XmNselectionPolicy is set to XmEXTENDED_SELECT, this action in Normal Mode also selects the previous item, deselects any current selection, moves the current anchor to the previous item, and calls the XmNextendedSelectionCallback callbacks. In Add Mode this action does not affect the selection or the anchor.

ListPrevPage():

Scrolls the list to the previous page, moving the location cursor to a new item.

If the XmNselectionPolicy is set to XmBROWSE_SELECT, this action also selects the new item, deselects any current selection, and calls the XmNbrowseSelectionCallback callbacks.

ListProcessDrag():

Drags the content of a one or more selected list items. Each item is separated by a newline. This action creates a DragContext object whose XmNexportTargets resource is set to COMPOUND_TEXT and the XmNclientData resource is set to the index of the item in the list. If BDrag is pressed on an unselected item, drags only that item, excluding any other selected items.

ListRightChar():

Scrolls the list one character to the right.

ListRightPage():

Scrolls the list one page to the right.

PrimitiveHelp():

Calls the callbacks for XmNhelpCallback if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them.

PrimitiveNextTabGroup():

Moves the focus to the first item contained within the next tab group. If the current tab group is the last entry in the tab group list, it wraps to the beginning of the tab group list.

PrimitivePrevTabGroup():

Moves the focus to the first item contained within the previous tab group. If the beginning of the tab group list is reached, it wraps to the end of the tab group list.

Additional behavior

The List widget has the additional behavior described below:

<Double Click>: If a button click is followed by another button click within the time span specified by the display's multi-click time, the List interprets that as a double click and calls the callbacks for XmNdefaultActionCallback. The item's colors invert to indicate that it is selected. The XmNdoubleClickInterval resource can be used to specify a time span that overrides the display's multi-click time.
<FocusIn>:: If the focus policy is Explicit, sets the focus and draw the location cursor.
<FocusOut>:: If the focus policy is Explicit, removes the focus and erase the location cursor.

Virtual bindings

The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see VirtualBindings(Xm).