XmList - The List widget class
#include <Xm/List.h>
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.
Each list has one of four selection models:
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.
List inherits behavior and resources from Core and XmPrimitive classes.
The class pointer is xmListWidgetClass.
The class name is XmList.
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).
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 |
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.
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.
List inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass.
Name | Class | Type | Default | Access |
---|---|---|---|---|
XmNbottomShadowColor | 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 |
---|---|---|---|---|
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 |
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 |
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;
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 |
XmList includes translations from Primitive. The XmList translations are listed below. 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()
The XmList action routines are described below. The current selection is always shown with inverted colors.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
The List widget has the additional behavior described below:
The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see VirtualBindings(3X).
Core(3X), XmCreateList(3X), XmCreateScrolledList(3X), XmFontListAppendEntry(3X), XmListAddItem(3X), XmListAddItems(3X), XmListAddItemUnselected(3X), XmListAddItemsUnselected(3X), XmListDeleteAllItems(3X), XmListDeleteItem(3X), XmListDeleteItems(3X), XmListDeleteItemsPos(3X), XmListDeletePos(3X), XmListDeletePositions(3X), XmListDeselectAllItems(3X), XmListDeselectItem(3X), XmListDeselectPos(3X), XmListGetKbdItemPos XmListGetMatchPos(3X), XmListGetSelectedPos(3X), XmListItemExists(3X), XmListItemPos(3X), XmListPosToBounds(3X), XmListReplaceItems(3X), XmListReplaceItemsPos(3X), XmListReplaceItemsPosUnselected(3X), XmListReplaceItemsUnselected(3X), XmListSelectItem(3X), XmListSelectPos(3X), XmListSetAddMode(3X), XmListSetBottomItem(3X), XmListSetBottomPos(3X), XmListSetHorizPos(3X), XmListSetItem(3X), XmListSetKbdItemPos(3X), XmListSetPos(3X), XmListUpdateSelectedList(3X), XmListYToPos(3X), XmPrimitive(3X) and XmStringCreate(3X).