XmList(3X) OSF/Motif 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 BSe‐
lect or pressing or dragging BExtend following a BSelect action selects
all items between the item under the pointer and the item on which BSe‐
lect was pressed. This action also deselects any other selected items
outside 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 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 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
────────────────────────────────────────────────────────────────────
Name Default Access
Class Type
────────────────────────────────────────────────────────────────────
────────────────────────────────────────────────────────────────────
XmNautomaticSelection False CSG
XmCAutomaticSelection Boolean
────────────────────────────────────────────────────────────────────
XmNbrowseSelectionCallback NULL C
XmCCallback XtCallbackList
────────────────────────────────────────────────────────────────────
XmNdefaultActionCallback NULL C
XmCCallback XtCallbackList
────────────────────────────────────────────────────────────────────
XmNdoubleClickInterval dynamic CSG
XmCDoubleClickInterval int
────────────────────────────────────────────────────────────────────
XmNextendedSelectionCallback NULL C
XmCCallback XtCallbackList
────────────────────────────────────────────────────────────────────
XmNfontList dynamic CSG
XmCFontList XmFontList
────────────────────────────────────────────────────────────────────
XmNitemCount 0 CSG
XmCItemCount int
────────────────────────────────────────────────────────────────────
XmNitems NULL CSG
XmCItems XmStringTable
────────────────────────────────────────────────────────────────────
XmNlistMarginHeight 0 CSG
XmCListMarginHeight Dimension
────────────────────────────────────────────────────────────────────
XmNlistMarginWidth 0 CSG
XmCListMarginWidth Dimension
────────────────────────────────────────────────────────────────────
XmNlistSizePolicy XmVARIABLE CG
XmCListSizePolicy unsigned char
────────────────────────────────────────────────────────────────────
XmNlistSpacing 0 CSG
XmCListSpacing Dimension
────────────────────────────────────────────────────────────────────
XmNmultipleSelectionCallback NULL C
XmCCallback XtCallbackList
────────────────────────────────────────────────────────────────────
XmNscrollBarDisplayPolicy XmAS_NEEDED CSG
XmCScrollBarDisplayPolicy unsigned char
────────────────────────────────────────────────────────────────────
XmNselectedItemCount 0 CSG
XmCSelectedItemCount int
────────────────────────────────────────────────────────────────────
XmNselectedItems NULL CSG
XmCSelectedItems XmStringTable
────────────────────────────────────────────────────────────────────
XmNselectionPolicy XmBROWSE_SELECT CSG
XmCSelectionPolicy unsigned char
────────────────────────────────────────────────────────────────────
XmNsingleSelectionCallback NULL C
XmCCallback XtCallbackList
────────────────────────────────────────────────────────────────────
XmNstringDirection dynamic CSG
XmCStringDirection XmStringDirection
────────────────────────────────────────────────────────────────────
XmNtopItemPosition 1 CSG
XmCTopItemPosition int
────────────────────────────────────────────────────────────────────
XmNvisibleItemCount dynamic CSG
XmCVisibleItemCount int
────────────────────────────────────────────────────────────────────
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. 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 followed by another button
click within the time span specified by this resource (in millisec‐
onds), 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. Specifies a list of
callbacks that is called when items are selected using the extended
selection mode. The reason is XmCR_EXTENDED_SELECT. 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 wid‐
get 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(3X) for more information on a font list structure. Speci‐
fies 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. 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 applica‐
tion 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 reac‐
tion of the List when an item grows horizontally beyond the current
size of the list work area. If the value is XmCONSTANT, the list view‐
ing 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. Specifies the
spacing between list items. This spacing increases by the value of the
XmNhighlightThickness resource in Primitive. Specifies a list of call‐
backs that is called when an item is selected in multiple selection
mode. The reason is XmCR_MULTIPLE_SELECT. Controls the display of ver‐
tical 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 represents the list items that are
currently selected, either by the user or by the application. XtGet‐
Values 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, XmList‐
DeselectAllItems, XmListDeselectPos, XmListSelectItem, XmListSelectPos,
or XmListUpdateSelectedList cause XmNselectedItems to be updated imme‐
diately 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 follow‐
ing: XmSINGLE_SELECT—allows only single selections XmMULTIPLE_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 ini‐
tial direction to draw the string. The values are XmSTRING_DIREC‐
TION_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. Specifies the position of the item that
is the first visible item in the list. Setting this resource is equiv‐
alent 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. 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 Default Access
Class Type
───────────────────────────────────────────────────────────────
───────────────────────────────────────────────────────────────
XmNbottomShadowColor dynamic CSG
XmCBottomShadowColor Pixel
───────────────────────────────────────────────────────────────
XmNbottomShadowPixmap XmUNSPECIFIED_PIXMAP CSG
XmCBottomShadowPixmap Pixmap
───────────────────────────────────────────────────────────────
XmNforeground dynamic CSG
XmCForeground Pixel
───────────────────────────────────────────────────────────────
XmNhelpCallback NULL C
XmCCallback XtCallbackList
───────────────────────────────────────────────────────────────
XmNhighlightColor dynamic CSG
XmCHighlightColor Pixel
───────────────────────────────────────────────────────────────
XmNhighlightOnEnter False CSG
XmCHighlightOnEnter Boolean
───────────────────────────────────────────────────────────────
XmNhighlightPixmap dynamic CSG
XmCHighlightPixmap Pixmap
───────────────────────────────────────────────────────────────
XmNhighlightThickness 2 CSG
XmCHighlightThickness Dimension
───────────────────────────────────────────────────────────────
XmNnavigationType XmTAB_GROUP CSG
XmCNavigationType XmNavigationType
───────────────────────────────────────────────────────────────
XmNshadowThickness 2 CSG
XmCShadowThickness Dimension
───────────────────────────────────────────────────────────────
XmNtopShadowColor dynamic CSG
XmCTopShadowColor Pixel
───────────────────────────────────────────────────────────────
XmNtopShadowPixmap dynamic CSG
XmCTopShadowPixmap Pixmap
───────────────────────────────────────────────────────────────
XmNtraversalOn True CSG
XmCTraversalOn Boolean
───────────────────────────────────────────────────────────────
XmNunitType dynamic CSG
XmCUnitType unsigned char
───────────────────────────────────────────────────────────────
XmNuserData NULL CSG
XmCUserData XtPointer
───────────────────────────────────────────────────────────────
Core Resource Set
─────────────────────────────────────────────────────────────────────
Name Default Access
Class Type
─────────────────────────────────────────────────────────────────────
─────────────────────────────────────────────────────────────────────
XmNaccelerators dynamic CSG
XmCAccelerators XtAccelerators
─────────────────────────────────────────────────────────────────────
XmNancestorSensitive dynamic G
XmCSensitive Boolean
─────────────────────────────────────────────────────────────────────
XmNbackground dynamic CSG
XmCBackground Pixel
─────────────────────────────────────────────────────────────────────
XmNbackgroundPixmap XmUNSPECIFIED_PIXMAP CSG
XmCPixmap Pixmap
─────────────────────────────────────────────────────────────────────
XmNborderColor XtDefaultForeground CSG
XmCBorderColor Pixel
─────────────────────────────────────────────────────────────────────
XmNborderPixmap XmUNSPECIFIED_PIXMAP CSG
XmCPixmap Pixmap
─────────────────────────────────────────────────────────────────────
XmNborderWidth 0 CSG
XmCBorderWidth Dimension
─────────────────────────────────────────────────────────────────────
XmNcolormap dynamic CG
XmCColormap Colormap
─────────────────────────────────────────────────────────────────────
XmNdepth dynamic CG
XmCDepth int
─────────────────────────────────────────────────────────────────────
XmNdestroyCallback NULL C
XmCCallback XtCallbackList
─────────────────────────────────────────────────────────────────────
XmNheight dynamic CSG
XmCHeight Dimension
─────────────────────────────────────────────────────────────────────
XmNinitialResourcesPersistent True C
XmCInitialResourcesPersistent Boolean
─────────────────────────────────────────────────────────────────────
XmNmappedWhenManaged True CSG
XmCMappedWhenManaged Boolean
─────────────────────────────────────────────────────────────────────
XmNscreen dynamic CG
XmCScreen Screen *
─────────────────────────────────────────────────────────────────────
XmNsensitive True CSG
XmCSensitive Boolean
─────────────────────────────────────────────────────────────────────
XmNtranslations dynamic CSG
XmCTranslations XtTranslations
─────────────────────────────────────────────────────────────────────
XmNwidth dynamic CSG
XmCWidth Dimension
─────────────────────────────────────────────────────────────────────
XmNx 0 CSG
XmCPosition Position
─────────────────────────────────────────────────────────────────────
XmNy 0 CSG
XmCPosition Position
─────────────────────────────────────────────────────────────────────
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_posi‐
tions; 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 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. 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 initial selection (XmINITIAL), a mod‐
ification 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_posi‐
tion, 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_posi‐
tion, selected_items, selected_item_count,
selected_item_positions
───────────────────────────────────────────────────────────────────────
XmCR_EXTENDED_SELECT reason, event, item, item_length, item_posi‐
tion, selected_items, selected_item_count,
selected_item_positions, 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() BEx‐
tend 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: ListKbdBeginSe‐
lect() KSelect Release:ListKbdEndSelect()
KExtend Press: ListKbdBeginExtend() KExtend Release:ListKbdEndExtend()
MAny KCancel: ListKbdCancel() KSelectAll: ListKbdSelectAll() KDese‐
lectAll: 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 follow‐
ing: 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 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 XmNautomaticSelec‐
tion is set to True, calls the XmNextendedSelectionCallback 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 cur‐
rent selection and selects the item under the pointer. If XmNautomat‐
icSelection is set to True, calls the XmNbrowseSelectionCallback call‐
backs.
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 XmNselection‐
Policy is set to XmEXTENDED_SELECT, does the following: Moves the cur‐
rent 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 XmNselection‐
Policy 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 call‐
backs.
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the follow‐
ing: 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. Copies the content of the
selected items to the clipboard as a single compound string with each
item separated by a newline. 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 XmNselec‐
tionPolicy is set to XmEXTENDED_SELECT). If the XmNselectionPolicy is
set to XmMULTIPLE_SELECT or XmEXTENDED_SELECT, moves the location cur‐
sor to the last item in the list.
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the follow‐
ing: 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 XmEXTENDED_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 XmMULTIPLE_SELECT, moves the location cursor to
the last item selected or deselected and calls the appropriate selec‐
tion 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 (XmNbrowseSelectionCallback when XmNse‐
lectionPolicy is set to XmBROWSE_SELECT, XmNextendedSelectionCallback
when XmNselectionPolicy is set to XmEXTENDED_SELECT). If the XmNselec‐
tionPolicy 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. 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 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 loca‐
tion 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 XmNextendedSelec‐
tionCallback callbacks. Scrolls the line containing the insertion cur‐
sor 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. Calls the callbacks for XmNdefaultActionCallback. If the
List's parent is a manager, this action passes the event to the parent.
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the follow‐
ing: 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 XmNextended‐
SelectionCallback callbacks. If the XmNselectionPolicy is set to XmS‐
INGLE_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 cur‐
rent selection and selects the item at the location cursor. If XmNau‐
tomaticSelection 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 cur‐
rent anchor to the item at the location cursor. In Normal Mode, dese‐
lects any current selection and selects the item at the location cur‐
sor. In Add Mode, toggles the selection state of the item at the loca‐
tion cursor and leaves the current selection unchanged. If XmNautomat‐
icSelection is set to True, calls the XmNextendedSelectionCallback
callbacks. If the XmNselectionPolicy is set to XmEXTENDED_SELECT and
an extended selection is being made from the current anchor point, can‐
cels 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 XmNextendedSelection‐
Callback callbacks, otherwise, and if the parent is a manager, passes
the event to the parent. If the XmNselectionPolicy is set to XmSIN‐
GLE_SELECT, XmMULTIPLE_SELECT, or XmEXTENDED_SELECT in Add Mode, dese‐
lects all items in the list. If the XmNselectionPolicy is set to XmEX‐
TENDED_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 (XmNsingleS‐
electionCallback when XmNselectionPolicy is set to XmSINGLE_SELECT,
XmNmultipleSelectionCallback when XmNselectionPolicy is set to XmMULTI‐
PLE_SELECT, XmNextendedSelectionCallback when XmNselectionPolicy is set
to XmEXTENDED_SELECT). If the XmNselectionPolicy is set to XmEX‐
TENDED_SELECT and if XmNautomaticSelection is set to False, calls the
XmNextendedSelectionCallback callbacks. If the XmNselectionPolicy is
set to XmSINGLE_SELECT or XmMULTIPLE_SELECT or if XmNautomaticSelection
is set to False, calls the appropriate selection callbacks (XmNsingleS‐
electionCallback 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 XmNse‐
lectionPolicy 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 XmNselectionPolicy is set to XmEXTENDED_SELECT
or XmMULTIPLE_SELECT, selects all items in the list. Calls the appro‐
priate selection callbacks (XmNsingleSelectionCallback when XmNselec‐
tionPolicy is set to XmSINGLE_SELECT, XmNbrowseSelectionCallback when
XmNselectionPolicy is set to XmBROWSE_SELECT, XmNmultipleSelectionCall‐
back when XmNselectionPolicy is set to XmMULTIPLE_SELECT, XmNextendedS‐
electionCallback when XmNselectionPolicy is set to XmEXTENDED_SELECT).
Scrolls the list one character to the left. Scrolls the list one page
to the left. 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 selec‐
tion, moves the current anchor to the next item, and calls the XmNex‐
tendedSelectionCallback 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 XmNextendedSe‐
lectionCallback 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 previ‐
ous 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 XmNextendedSe‐
lectionCallback 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 "COM‐
POUND_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).
RELATED INFORMATIONCore(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 XmListGetMatchPos(3X), XmListGetSelectedPos(3X), XmListItemEx‐
ists(3X), XmListItemPos(3X), XmListPosToBounds(3X), XmListReplaceIt‐
ems(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)
