XmList(3X)XmList(3X)NAMEXmList - The 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 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 appro‐
priate 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 selec‐
tion 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 out‐
side that range.
Extended Select also allows the user to select and deselect discontigu‐
ous 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 BTog‐
gle; 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 pro‐
grammer to specify data. The programmer can also set the resource val‐
ues 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
Class: XmCAutomaticSelection
Default: False
Type: Boolean
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCDoubleClickInterval
Default: dynamic
Type: int
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCFontList
Default: dynamic
Type: XmFontList
Access: CSG
Class: XmCItemCount
Default: 0
Type: int
Access: CSG
Class: XmCItems
Default: NULL
Type: XmStringTable
Access: CSG
Class: XmCListMarginHeight
Default: 0
Type: Dimension
Access: CSG
Class: XmCListMarginWidth
Default: 0
Type: Dimension
Access: CSG
Class: XmCListSizePolicy
Default: XmVARIABLE
Type: unsigned char
Access: CG
Class: XmCListSpacing
Default: 0
Type: Dimension
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCScrollBarDisplayPolicy
Default: XmAS_NEEDED
Type: unsigned char
Access: CSG
Class: XmCSelectedItemCount
Default: 0
Type: int
Access: CSG
Class: XmCSelectedItems
Default: NULL
Type: XmStringTable
Access: CSG
Class: XmCSelectionPolicy
Default: XmBROWSE_SELECT
Type: unsigned char
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCStringDirection
Default: dynamic
Type: XmStringDirection
Access: CSG
Class: XmCTopItemPosition
Default: 1
Type: int
Access: CSG
Class: XmCVisibleItemCount
Default: dynamic
Type: int
Access: CSG
Invokes XmNbrowseSelectionCallback or XmNextendedSelectionCall‐
back 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. Specifies a list of callbacks that is called when an
item is selected in the browse selection mode. The reason is
XmCR_BROWSE_SELECT. Specifies a list of callbacks that is
called when an item is double clicked or KActivate is pressed.
The reason is XmCR_DEFAULT_ACTION. If a button click is fol‐
lowed by another button click within the time span specified by
this resource (in milliseconds), the button clicks are consid‐
ered 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. Specifies a list of callbacks
that is called when items are selected using the extended selec‐
tion mode. The reason is XmCR_EXTENDED_SELECT. Specifies the
font list associated with the list items. This is used in con‐
junction with the XmNvisibleItemCount resource to determine the
height of the List widget. If this value is NULL at initializa‐
tion, 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 XmNtext‐
FontList of the ancestor widget. If no such ancestor is found,
the default is implementation dependent. Refer to
XmFontList(3X) for more information on a font list structure.
Specifies the total number of items. The value must be the num‐
ber of items in XmNitems and must not be negative. It is auto‐
matically updated by the list whenever an item is added to or
deleted from the list. Points to an array of compound strings
that are to be displayed as the list items. Refer to
XmString(3X) 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 appli‐
cation must not free the returned items. Specifies the height
of the margin between the list border and the items. Specifies
the width of the margin between the list border and the items.
Controls the reaction of the List when an item grows horizon‐
tally 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 cre‐
ated. It cannot be changed at a later time through XtSetValues.
Specifies the spacing between list items. This spacing increases
by the value of the XmNhighlightThickness resource in Primitive.
Specifies a list of callbacks that is called when an item is
selected in multiple selection mode. The reason is XmCR_MULTI‐
PLE_SELECT. 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. 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. Points to an array of compound strings that repre‐
sents 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 XmListDeselectAl‐
lItems, XmListDeselectAllItems, XmListDeselectPos, XmListSelec‐
tItem, XmListSelectPos, or XmListUpdateSelectedList cause XmNse‐
lectedItems to be updated immediately to exactly reflect the
visual state of the list. Calls to any other XmList functions do
not affect XmNselectedItems. Defines the interpretation of the
selection action. This can be one of the following: XmSIN‐
GLE_SELECT--allows only single selections XmMULTI‐
PLE_SELECT--allows multiple selections XmEXTENDED_SELECT--allows
extended selections XmBROWSE_SELECT--allows “drag and browse”
functionality Specifies a list of callbacks that is called when
an item is selected in single selection mode. The reason is
XmCR_SINGLE_SELECT. 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 deter‐
mined 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. Specifies the position of
the item that is the first visible item in the list. Setting
this resource is equivalent to calling the XmListSetPos func‐
tion. The position of the first item in the list is 1; the posi‐
tion of the second item is 2; and so on. A position of 0 speci‐
fies the last item in the list. The value must not be negative.
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
Class: XmCBottomShadowColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCBottomShadowPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCForeground
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCHighlightColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCHighlightOnEnter
Default: False
Type: Boolean
Access: CSG
Class: XmCHighlightPixmap
Default: dynamic
Type: Pixmap
Access: CSG
Class: XmCHighlightThickness
Default: 2
Type: Dimension
Access: CSG
Class: XmCNavigationType
Default: XmTAB_GROUP
Type: XmNavigationType
Access: CSG
Class: XmCShadowThickness
Default: 2
Type: Dimension
Access: CSG
Class: XmCTopShadowColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCTopShadowPixmap
Default: dynamic
Type: Pixmap
Access: CSG
Class: XmCTraversalOn
Default: True
Type: Boolean
Access: CSG
Class: XmCUnitType
Default: dynamic
Type: unsigned char
Access: CSG
Class: XmCUserData
Default: NULL
Type: XtPointer
Access: CSG
Core Resource Set
Class: XmCAccelerators
Default: dynamic
Type: XtAccelerators
Access: CSG
Class: XmCSensitive
Default: dynamic
Type: Boolean
Access: G
Class: XmCBackground
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCBorderColor
Default: XtDefaultForeground
Type: Pixel
Access: CSG
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCBorderWidth
Default: 0
Type: Dimension
Access: CSG
Class: XmCColormap
Default: dynamic
Type: Colormap
Access: CG
Class: XmCDepth
Default: dynamic
Type: int
Access: CG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCHeight
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCInitialResourcesPersistent
Default: True
Type: Boolean
Access: C
Class: XmCMappedWhenManaged
Default: True
Type: Boolean
Access: CSG
Class: XmCScreen
Default: dynamic
Type: Screen *
Access: CG
Class: XmCSensitive
Default: True
Type: Boolean
Access: CSG
Class: XmCTranslations
Default: dynamic
Type: XtTranslations
Access: CSG
Class: XmCWidth
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCPosition
Default: 0
Type: Position
Access: CSG
Class: XmCPosition
Default: 0
Type: Position
Access: 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;
Indicates why the callback was invoked. Points to the XEvent that
triggered the callback. It can be NULL. Is the last item selected at
the time of the event that caused the callback. item points to a tempo‐
rary 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. Is the length in bytes of item. Is the
position of item in the List's XmNitems array. 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. Is
the number of items in the selected_items list. This number must be
non-negative. 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. Indicates that the most recent extended selection was the ini‐
tial selection (XmINITIAL), a modification of an existing selection
(XmMODIFICATION), or an additional noncontiguous selection (XmADDI‐
TION).
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_posi‐
tions
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_posi‐
tions
XmCR_EXTENDED_SELECT reason, event, item, item_length,
item_position, selected_items,
selected_item_count, selected_item_posi‐
tions, selection_type
────────────────────────────────────────────────────────────────
Translations
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: ListEx‐
tendPrevItem() KDown: ListNextItem() MShift KDown: ListExtend‐
NextItem() KLeft: ListLeftChar() MCtrl KLeft: ListLeftPage()
KRight: ListRightChar() MCtrl KRight: ListRightPage() KPageUp:
ListPrevPage() KPageDown: ListNextPage() KPageLeft: ListLeft‐
Page() KPageRight: ListRightPage() KBeginLine: ListBeginLine()
KEndLine: ListEndLine() KBeginData: ListBeginData() MShift KBe‐
ginData:ListBeginDataExtend() KEndData: ListEndData() MShift KEnd‐
Data: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. Toggles the state of Add Mode
for keyboard selection. 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). 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 cur‐
rent 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 XmNextendedSe‐
lectionCallback callbacks. 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 selec‐
tion 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 XmNex‐
tendedSelectionCallback callbacks. Moves the horizontal scroll
region to the beginning of the line. 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 XmNbrowseSelec‐
tionCallback 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 call‐
backs. 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. If the XmNselectionPol‐
icy 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 XmNautomaticS‐
election 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. Copies the content
of the selected items to the clipboard as a single compound
string with each item separated by a newline. Moves the loca‐
tion 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 (XmN‐
browseSelectionCallback when XmNselectionPolicy is set to
XmBROWSE_SELECT, XmNextendedSelectionCallback when XmNselection‐
Policy is set to XmEXTENDED_SELECT). 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 cur‐
rent 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 XmNextendedSelectionCall‐
back callbacks. If the XmNselectionPolicy is set to XmEX‐
TENDED_SELECT, moves the location cursor to the last item
selected or deselected and, if XmNautomaticSelection is set to
False, calls the XmNextendedSelectionCallback callbacks. Moves
the horizontal scroll region to the end of the line. If the
XmNselectionPolicy is set to XmSINGLE_SELECT or XmMULTI‐
PLE_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 XmNselection‐
Policy is set to XmMULTIPLE_SELECT).
If the XmNselectionPolicy is set to XmBROWSE_SELECT or XmEX‐
TENDED_SELECT, moves the location cursor to the last item
selected or deselected and, if XmNautomaticSelection is set to
False, calls the appropriate selection callbacks (XmNbrowseSe‐
lectionCallback when XmNselectionPolicy is set to
XmBROWSE_SELECT, XmNextendedSelectionCallback when XmNselection‐
Policy is set to XmEXTENDED_SELECT). 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 call‐
backs. 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.
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the
following: If an extended selection has been made from the cur‐
rent 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.
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 cur‐
sor is scrolled vertically to a new position designated by the y
event passed to the routine. Calls the callbacks for XmNde‐
faultActionCallback. If the List's parent is a manager, this
action passes the event to the parent. If the XmNselectionPol‐
icy 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 selec‐
tion 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. If the
XmNselectionPolicy is set to XmSINGLE_SELECT, deselects any cur‐
rent 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 cur‐
sor. If XmNautomaticSelection is set to True, calls the XmN‐
browseSelectionCallback callbacks.
If the XmNselectionPolicy is set to XmMULTIPLE_SELECT, toggles
the selection state of the item at the location cursor. Any pre‐
vious 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 XmNselectionPol‐
icy is set to XmEXTENDED_SELECT and an extended selection is
being made from the current anchor point, cancels the new selec‐
tion and restores the selection state of the items in that range
to their state before the extended selection was done. If XmNau‐
tomaticSelection is set to True, calls the XmNextendedSelection‐
Callback callbacks, otherwise, and if the parent is a manager,
passes the event to the parent. If the XmNselectionPolicy is
set to XmSINGLE_SELECT, XmMULTIPLE_SELECT, or XmEXTENDED_SELECT
in Add Mode, deselects all items in the list. If the XmNselec‐
tionPolicy 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, XmNmultipleSelec‐
tionCallback when XmNselectionPolicy is set to XmMULTI‐
PLE_SELECT, XmNextendedSelectionCallback when XmNselectionPolicy
is set to XmEXTENDED_SELECT). If the XmNselectionPolicy is set
to XmEXTENDED_SELECT and if XmNautomaticSelection is set to
False, calls the XmNextendedSelectionCallback callbacks. If the
XmNselectionPolicy is set to XmSINGLE_SELECT or XmMULTI‐
PLE_SELECT or if XmNautomaticSelection is set to False, calls
the appropriate selection callbacks (XmNsingleSelectionCallback
when XmNselectionPolicy is set to XmSINGLE_SELECT, XmNbrowseSe‐
lectionCallback when XmNselectionPolicy is set to
XmBROWSE_SELECT, XmNmultipleSelectionCallback when XmNselection‐
Policy is set to XmMULTIPLE_SELECT, XmNextendedSelectionCallback
when XmNselectionPolicy is set to XmEXTENDED_SELECT). If the
XmNselectionPolicy is set to XmSINGLE_SELECT or XmBROWSE_SELECT,
selects the item at the location cursor. If the XmNselectionPol‐
icy 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 XmNselection‐
Policy is set to XmBROWSE_SELECT, XmNmultipleSelectionCallback
when XmNselectionPolicy is set to XmMULTIPLE_SELECT, XmNextend‐
edSelectionCallback when XmNselectionPolicy is set to XmEX‐
TENDED_SELECT). Scrolls the list one character to the left.
Scrolls the list one page to the left. Moves the location cur‐
sor 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.
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. 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. Scrolls the list to the previous page, moving the loca‐
tion 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. 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. Scrolls the
list one character to the right. Scrolls the list one page to
the right. 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. 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. 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: If a but‐
ton 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 XmNdou‐
bleClickInterval resource can be used to specify a time span that over‐
rides the display's multi-click time. If the focus policy is Explicit,
sets the focus and draw the location cursor. 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(3X).
SEE ALSOCore(3X), XmCreateList(3X), XmCreateScrolledList(3X), XmFontListAppen‐
dEntry(3X), XmListAddItem(3X), XmListAddItems(3X), XmListAddItemUnse‐
lected(3X), XmListAddItemsUnselected(3X), XmListDeleteAllItems(3X),
XmListDeleteItem(3X), XmListDeleteItems(3X), XmListDeleteItemsPos(3X),
XmListDeletePos(3X), XmListDeletePositions(3X), XmListDeselectAl‐
lItems(3X), XmListDeselectItem(3X), XmListDeselectPos(3X), XmListGetKb‐
dItemPos(3X), XmListGetMatchPos(3X), XmListGetSelectedPos(3X), XmLis‐
tItemExists(3X), XmListItemPos(3X), XmListPosToBounds(3X), XmListRepla‐
ceItems(3X), XmListReplaceItemsPos(3X), XmListReplaceItemsPosUnse‐
lected(3X), XmListReplaceItemsUnselected(3X), XmListSelectItem(3X),
XmListSelectPos(3X), XmListSetAddMode(3X), XmListSetBottomItem(3X),
XmListSetBottomPos(3X), XmListSetHorizPos(3X), XmListSetItem(3X),
XmListSetKbdItemPos(3X), XmListSetPos(3X), XmListUpdateSelect‐
edList(3X), XmListYToPos(3X), XmPrimitive(3X), XmStringCreate(3X)XmList(3X)
