XmList(3X) UNIX System V XmList(3X)
NAME
XmList - 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 strings that are defined by the application.
Each string becomes an item in the List, with the first string becoming
the item in position 1, the second string 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. To create a list that allows the user to scroll easily through
a large number of items, use the XmCreateScrolledList convenience
function.
If the List has no items at initialization or as a result of XtSetValues,
it saves the current value of XmNtraversalOn and forces XmNtraversalOn to
False. If XtSetValues is called for XmNtraversalOn while the List has no
items, the List updates the saved value but does not change the
XmNtraversalOn resource. If the List later has items as a result of
XtSetValues, it sets XmNtraversalOn to the saved value.
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.
Selection
Each list has one of four selection models:
⊕ Single Select
⊕ Browse Select
⊕ Multiple Select
⊕ Extended Select
10/89 Page 1
XmList(3X) UNIX System V XmList(3X)
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 along with the cursor.
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.
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.
Page 2 10/89
XmList(3X) UNIX System V XmList(3X)
Classes
List inherits behavior and resources from Core and XmPrimitive classes.
The class pointer is xmListWidgetClass.
The class name is XmList.
New Resources
The following table defines a set of widget resources used by the
programmer to specify data. The programmer can also set the resource
values for the inherited classes to set attributes for this widget. To
reference a resource by name or by class in a .Xdefaults file, remove the
XmN or XmC prefix and use the remaining letters. To specify one of the
defined values for a resource in a .Xdefaults file, remove the Xm prefix
and use the remaining letters (in either lowercase or uppercase, but
include any underscores between words). The codes in the access column
indicate if the given resource can be set at creation time (C), set by
using XtSetValues (S), retrieved by using XtGetValues (G), or is not
applicable (N/A).
_________________________________________________________________________________________________________
XmList Resource Set
_________________________________________________________________________________________________________
Name Class Type Default Access
_________________________________________________________________________________________________________
_________________________________________________________________________________________________________
XmNautomaticSelection XmCAutomaticSelection Boolean False CSG
_________________________________________________________________________________________________________
XmNbrowseSelectionCallback XmCCallback XtCallbackList NULL C
_________________________________________________________________________________________________________
XmNdefaultActionCallback XmCCallback XtCallbackList NULL C
_________________________________________________________________________________________________________
XmNdoubleClickInterval XmCDoubleClickInterval int dynamic CSG
_________________________________________________________________________________________________________
XmNextendedSelectionCallback XmCCallback XtCallbackList NULL C
_________________________________________________________________________________________________________
XmNfontList XmCFontList XmFontList dynamic CSG
_________________________________________________________________________________________________________
XmNitemCount XmCItemCount int 0 CSG
_________________________________________________________________________________________________________
XmNitems XmCItems XmStringTable NULL CSG
_________________________________________________________________________________________________________
XmNlistMarginHeight XmCListMarginHeight Dimension 0 CSG
_________________________________________________________________________________________________________
XmNlistMarginWidth XmCListMarginWidth Dimension 0 CSG
_________________________________________________________________________________________________________
XmNlistSizePolicy XmCListSizePolicy unsigned char XmVARIABLE CG
_________________________________________________________________________________________________________
XmNlistSpacing XmCListSpacing Dimension 0 CSG
_________________________________________________________________________________________________________
XmNmultipleSelectionCallback XmCCallback XtCallbackList NULL C
10/89 Page 3
XmList(3X) UNIX System V XmList(3X)
|____________________________|___________________________|___________________|_________________|________|
|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 | 1 | CSG |
|____________________________|___________________________|___________________|_________________|________|
XmNautomaticSelection
Invokes XmNsingleSelectionCallback when the user moves into a new
item if the value is True and the selection mode is either
XmBROWSESELECT or XmEXTENDED_SELECT. If False, no selection
callbacks are invoked until the user releases the mouse button.
See the Behavior section for further details on the interaction of
this resource with the selection modes.
XmNbrowseSelectionCallback
Specifies a list of callbacks that is called when an item is
selected in the browse selection mode. The reason is
XmCR_BROWSE_SELECT.
XmNdefaultActionCallback
Specifies a list of callbacks that is called when an item is double
clicked. The reason is XmCR_DEFAULT_ACTION.
XmNdoubleClickInterval
If a button click is followed by another button click within the
time span specified by this resource (in milliseconds), the button
clicks are considered a double-click action, rather than two
single-click actions. The value must not be negative. The default
value is the display's multi-click time.
XmNextendedSelectionCallback
Specifies a list of callbacks that is called when items are
selected using the extended selection mode. The reason is
XmCR_EXTENDED_SELECT.
XmNfontList
Specifies the font list associated with the list items. This is
used in conjunction with the XmNvisibleItemCount resource to
determine the height of the List widget. If this value is NULL at
Page 4 10/89
XmList(3X) UNIX System V XmList(3X)
initialization, it is initialized by looking up the parent
hierarchy of the widget for an ancestor that is a subclass of the
XmBulletinBoard, VendorShell, or XmMenuShell widget class. If such
an ancestor is found, the font list is initialized to the
appropriate default font list of the ancestor widget
(XmNdefaultFontList for VendorShell and XmMenuShell,
XmNtextFontList for XmBulletinBoard). Refer to XmString(3X) for
more information on a font list structure.
XmNitemCount
Specifies the total number of items. The value must be the number
of items in XmNitems and must not be negative. It is automatically
updated by the list whenever an item is added to or deleted from
the list.
XmNitems
Points to an array of compound strings that are to be displayed as
the list items. Refer to XmString(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 application must not free the returned items.
XmNlistMarginHeight
Specifies the height of the margin between the list border and the
items.
XmNlistMarginWidth
Specifies the width of the margin between the list border and the
items.
XmNlistSizePolicy
Controls the reaction of the List when an item grows horizontally
beyond the current size of the list work area. If the value is
XmCONSTANT, the list viewing area does not grow, and a horizontal
ScrollBar is added for a ScrolledList. If this resource is set to
XmVARIABLE, the List grows to
match the size of the longest item, and no horizontal ScrollBar
appears.
When the value of this resource is XmRESIZE_IF_POSSIBLE, the List
attempts to grow or shrink to match the width of the widest item.
If it cannot grow to match the widest size, a horizontal ScrollBar
is added for a ScrolledList if the longest item is wider than the
list viewing area.
The size policy must be set at the time the List widget is created.
It cannot be changed at a later time through XtSetValues.
XmNlistSpacing
Specifies the spacing between list items. This spacing increases
by the value of the XmNhighlightThickness resource in Primitive.
10/89 Page 5
XmList(3X) UNIX System V XmList(3X)
XmNmultipleSelectionCallback
Specifies a list of callbacks that is called when an item is
selected in multiple selection mode. The reason is
XmCR_MULTIPLE_SELECT.
XmNscrollBarDisplayPolicy
Controls the display of vertical ScrollBars in a ScrolledList.
When the value of this resource is XmAS_NEEDED, a vertical
ScrollBar is displayed only when the number of items in the List
exceeds the number of Visible items. When the value is XmSTATIC, a
vertical ScrollBar is always displayed.
XmNselectedItemCount
Specifies the number of strings in the selected items list. The
value must be the number of items in XmNselectedItems and must not
be negative.
XmNselectedItems
Points to an array of compound strings that represents the list
items that are currently selected, either by the user or by the
application. XtGetValues for this resource returns the list items
themselves, not a copy of the list items. The application must not
free the returned items.
XmNselectionPolicy
Defines the interpretation of the selection action. This can be
one of the following:
⊕ XmSINGLE_SELECT - allows only single selections
⊕ XmMULTIPLE_SELECT - allows multiple selections
⊕ XmEXTENDED_SELECT - allows extended selections
⊕ XmBROWSE_SELECT - allows PM "drag and browse" functionality
XmNsingleSelectionCallback
Specifies a list of callbacks that is called when an item is
selected in single selection mode. The reason is
XmCR_SINGLE_SELECT.
XmNstringDirection
Specifies the initial direction to draw the string. The values are
XmSTRING_DIRECTION_L_TO_R and XmSTRING_DIRECTION_R_TO_L. The value
of this resource is determined at creation time. If the widget's
parent is a manager, this value is inherited from the widget's
parent, otherwise it is set to XmSTRING_DIRECTION_L_TO_R.
XmNtopItemPosition
Specifies the position of the item that is the first visible item
in the list. Setting this resource is equivalent to calling the
XmListSetPos function. The position of the first item in the list
Page 6 10/89
XmList(3X) UNIX System V XmList(3X)
is 1; the position of the second item is 2; and so on. A position
of 0 specifies the last item in the list. The value must not be
negative.
XmNvisibleItemCount
Specifies the number of items that can fit in the visible space of
the list work area. The List uses this value to determine its
height. The value must be greater than 0.
Inherited Resources
List inherits behavior and resources from the following superclasses.
For a complete description of each resource, refer to the man page for
that superclass.
__________________________________________________________________________________________________
| XmPrimitive Resource Set |
|_____________________|_______________________|__________________|______________________|________|
|Name | Class | Type | Default | Access|
|_____________________|_______________________|__________________|______________________|________|
|_____________________|_______________________|__________________|______________________|________|
|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 | G |
|_____________________|_______________________|__________________|______________________|________|
|XmNshadowThickness | XmCShadowThickness | Dimension | 2 | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNtopShadowColor | XmCTopShadowColor | Pixel | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNtopShadowPixmap | XmCTopShadowPixmap | Pixmap | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNtraversalOn | XmCTraversalOn | Boolean | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNunitType | XmCUnitType | unsigned char | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNuserData | XmCUserData | Pointer | NULL | CSG |
|_____________________|_______________________|__________________|______________________|________|
10/89 Page 7
XmList(3X) UNIX System V XmList(3X)
________________________________________________________________________________________________________________
| Core Resource Set |
|_____________________________|_______________________________|________________|______________________|________|
|Name | Class | Type | Default | Access|
|_____________________________|_______________________________|________________|______________________|________|
|_____________________________|_______________________________|________________|______________________|________|
|XmNaccelerators | XmCAccelerators | XtAccelerators| dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNancestorSensitive | XmCSensitive | Boolean | dynamic | G |
|_____________________________|_______________________________|________________|______________________|________|
|XmNbackground | XmCBackground | Pixel | dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNbackgroundPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP| CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNborderColor | XmCBorderColor | Pixel | XtDefaultForeground | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNborderPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP| CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNborderWidth | XmCBorderWidth | Dimension | 0 | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNcolormap | XmCColormap | Colormap | dynamic | CG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNdepth | XmCDepth | int | dynamic | CG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNdestroyCallback | XmCCallback | XtCallbackList| NULL | C |
|_____________________________|_______________________________|________________|______________________|________|
|XmNheight | XmCHeight | Dimension | dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNinitialResourcesPersistent| XmCInitialResourcesPersistent| Boolean | True | C |
|_____________________________|_______________________________|________________|______________________|________|
|XmNmappedWhenManaged | XmCMappedWhenManaged | Boolean | True | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNscreen | XmCScreen | Screen * | dynamic | CG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNsensitive | XmCSensitive | Boolean | True | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNtranslations | XmCTranslations | XtTranslations| dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNwidth | XmCWidth | Dimension | dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNx | XmCPosition | Position | 0 | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNy | XmCPosition | Position | 0 | CSG |
|_____________________________|_______________________________|________________|______________________|________|
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:
Page 8 10/89
XmList(3X) UNIX System V XmList(3X)
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;
int selection_type;
} XmListCallbackStruct;
reason Indicates why the callback was invoked.
event Points to the XEvent that triggered the callback. It can be
NULL.
item Is the last item selected at the time of the event that
caused the callback. item points to a temporary storage
space that is reused after the callback is finished.
Therefore, if an application needs to save the item, it
should copy the item into its own data space.
item_length Is the length in bytes of item.
item_position
Is the position of item in the List's XmNitems array.
selected_items
Is a list of items selected at the time of the event that
caused the callback. selected_items points to a temporary
storage space that is reused after the callback is finished.
Therefore, if an application needs to save the selected
list, it should copy the list into its own data space.
selected_item_count
Is the number of items in the selected_items list.
selected_item_positions
Is an array of integers, one for each selected item,
representing the position of each selected item in the
List's XmNitems array. selected_item_positions points to a
temporary storage space that is reused after the callback is
finished. Therefore, if an application needs to save this
array, it should copy the array into its own data space.
selection_type
Indicates that the most recent extended selection was the
initial selection (XmINITIAL), a modification of an existing
selection (XmMODIFICATION), or an additional noncontiguous
10/89 Page 9
XmList(3X) UNIX System V XmList(3X)
selection (XmADDITION).
The following table describes the reasons for which the individual
callback structure fields are valid:
________________________________________________________________________
| Reason | Valid Fields |
|||
| XmCRSINGLESELECT | reason, event, item, item_length, item_position|
|_____________________|_________________________________________________|
| XmCRDEFAULTACTION | reason, event, item, item_length, item_position|
|_____________________|_________________________________________________|
| XmCRBROWSESELECT | reason, event, item, item_length, item_position|
|_____________________|_________________________________________________|
| XmCRMULTIPLESELECT| reason, event, item, item_length, |
| | item_position, selected_items, |
| | selected_item_count, selected_item_positions |
|_____________________|_________________________________________________|
| XmCREXTENDEDSELECT| reason, event, item, item_length, |
| | item_position, selected_items, |
| | selected_item_count, selected_item_positions, |
| | selection_type |
|_____________________|_________________________________________________|
Translations
XmList includes translations from Primitive. The XmList translations are
listed 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()
KUp: ListPrevItem()
MShift KUp: ListExtendPrevItem()
KDown: ListNextItem()
MShift KDown: ListExtendNextItem()
KLeft: ListLeftChar()
MCtrl KLeft: ListLeftPage()
KRight: ListRightChar()
Page 10 10/89
XmList(3X) UNIX System V XmList(3X)
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()
KSelect Press: ListKbdBeginSelect()
KSelect Release:ListKbdEndSelect()
KExtend Press: ListKbdBeginExtend()
KExtend Release:ListKbdEndExtend()
MAny KCancel: ListKbdCancel()
KSelectAll: ListKbdSelectAll()
KDeselectAll: ListKbdDeSelectAll()
KHelp: PrimitiveHelp()
KNextField PrimitiveNextTabGroup()
KPrevField PrimitivePrevTabGroup()
Action Routines
The XmList action routines are described below. The current selection is
always shown with inverted colors.
ListAddMode():
Toggles the state of Add Mode for keyboard selection.
ListBeginData():
Moves the location cursor to the first item in the list. In Normal
Mode, this also deselects any current selection, selects the first
item in the list, and calls the appropriate selection callbacks
(XmNbrowseSelectionCallback when XmNselectionPolicy is set to
XmBROWSE_SELECT, XmNextendedSelectionCallback when
XmNselectionPolicy is set to XmEXTENDED_SELECT).
10/89 Page 11
XmList(3X) UNIX System V XmList(3X)
ListBeginDataExtend():
If the XmNselectionPolicy is set to XmMULTIPLE_SELECT or
XmEXTENDED_SELECT, moves the location cursor to the first item in
the list.
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the
following: If an extended selection has been made from the current
anchor point, restores the selection state of the items in that
range to their state before the extended selection was done.
Changes the selection state of the first item and all items between
it and the current anchor point to the state of the item at the
current anchor point. Calls the XmNextendedSelectionCallback
callbacks.
ListBeginExtend():
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the
following: If an extended selection has been made from the current
anchor point, restores the selection state of the items in that
range to their state before the extended selection was done.
Changes the selection state of the item under the pointer and all
items between it and the current anchor point to the state of the
item at the current anchor point. If XmNautomaticSelection is set
to True, calls the XmNextendedSelectionCallback callbacks.
ListBeginLine():
Moves the horizontal scroll region to the beginning of the line.
ListBeginSelect():
If the XmNselectionPolicy is set to XmSINGLE_SELECT, deselects any
current selection and toggles the selection state of the item under
the pointer.
If the XmNselectionPolicy is set to XmBROWSE_SELECT, deselects any
current selection and selects the item under the pointer. If
XmNautomaticSelection is set to True, calls the
XmNbrowseSelectionCallback callbacks.
If the XmNselectionPolicy is set to XmMULTIPLE_SELECT, toggles the
selection state of the item under the pointer. Any previous
selections remain.
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, deselects
any current selection, selects the item under the pointer, and sets
the current anchor at that item. If XmNautomaticSelection is set
to True, calls the XmNextendedSelectionCallback callbacks.
ListBeginToggle():
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the
following: Moves the current anchor to the item under the pointer
without changing the current selection. If the item is unselected,
it is selected; if the item is selected, it is unselected. If
XmNautomaticSelection is set to True, calls the
Page 12 10/89
XmList(3X) UNIX System V XmList(3X)
XmNextendedSelectionCallback callbacks.
ListButtonMotion():
If the XmNselectionPolicy is set to XmBROWSE_SELECT, deselects any
current selection and selects the item under the
pointer. If XmNautomaticSelection is set to True and the pointer
has entered a new list item, calls the XmNbrowseSelectionCallback
callbacks.
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the
following: If an extended selection is being made and an extended
selection has previously been made from the current anchor point,
restores the selection state of the items in that range to their
state before the previous extended selection was done. Changes the
selection state of the item under the pointer and all items between
it and the current anchor point to the state of the item at the
current anchor point. If XmNautomaticSelection is set to True and
the pointer has entered a new list item, calls the
XmNextendedSelectionCallback callbacks.
If the pointer leaves a scrolled list, this action scrolls the list
in the direction of the pointer motion.
ListEndData():
Moves the location cursor to the last item in the list. In Normal
Mode, this also deselects any current selection, selects the last
item in the list, and calls the appropriate selection callbacks
(XmNbrowseSelectionCallback when XmNselectionPolicy is set to
XmBROWSE_SELECT, XmNextendedSelectionCallback when
XmNselectionPolicy is set to XmEXTENDED_SELECT).
ListEndDataExtend():
If the XmNselectionPolicy is set to XmMULTIPLE_SELECT or
XmEXTENDED_SELECT, moves the location cursor to the last item in
the list.
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the
following: If an extended selection has been made from the current
anchor point, restores the selection state of the items in that
range to their state before the extended selection was done.
Changes the selection state of the last item and all items between
it and the current anchor point to the state of the item at the
current anchor point. Calls the XmNextendedSelectionCallback
callbacks.
ListEndExtend():
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, moves the
location cursor to the last item selected or deselected and, if
XmNautomaticSelection is set to False, calls the
XmNextendedSelectionCallback callbacks.
10/89 Page 13
XmList(3X) UNIX System V XmList(3X)
ListEndLine():
Moves the horizontal scroll region to the end of the line.
ListEndSelect():
If the XmNselectionPolicy is set to XmSINGLE_SELECT or
XmMULTIPLE_SELECT, moves the location cursor to the last item
selected or deselected and calls the appropriate selection
callbacks (XmNsingleSelectionCallback when XmNselectionPolicy is
set to XmSINGLE_SELECT, XmNmultipleSelectionCallback when
XmNselectionPolicy is set to XmMULTIPLE_SELECT).
If the XmNselectionPolicy is set to XmBROWSE_SELECT or
XmEXTENDED_SELECT, moves the location cursor to the last item
selected or deselected and, if XmNautomaticSelection is set to
False, calls the appropriate selection callbacks
(XmNbrowseSelectionCallback when XmNselectionPolicy is set to
XmBROWSE_SELECT, XmNextendedSelectionCallback when
XmNselectionPolicy is set to XmEXTENDED_SELECT).
ListEndToggle():
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.
ListExtendNextItem():
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the
following: If an extended selection has been made from the current
anchor point, restores the selection state of the items in that
range to their state before the extended selection was done. Moves
the location cursor to the next item and changes the selection
state of the item and all items between it and the current anchor
point to the state of the item at the current anchor point. Calls
the XmNextendedSelectionCallback callbacks.
ListExtendPrevItem():
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the
following: If an extended selection has been made from the current
anchor point, restores the selection state of the items in that
range to their state before the extended selection was done. Moves
the location cursor to the previous item and changes the selection
state of the item and all items between it and the current anchor
point to the state of the item at the current anchor point. Calls
the XmNextendedSelectionCallback callbacks.
ListKbdActivate():
Calls the callbacks for XmNdefaultActionCallback.
ListKbdBeginExtend():
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, does the
following: If an extended selection has been made from the current
anchor point, restores the selection state of the items in that
Page 14 10/89
XmList(3X) UNIX System V XmList(3X)
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.
ListKbdBeginSelect():
If the XmNselectionPolicy is set to XmSINGLE_SELECT, deselects any
current selection and toggles the state of the item at the location
cursor.
If the XmNselectionPolicy is set to XmBROWSE_SELECT, deselects any
current selection and selects the item at the location cursor. If
XmNautomaticSelection is set to True, calls the
XmNbrowseSelectionCallback callbacks.
If the XmNselectionPolicy is set to XmMULTIPLE_SELECT, toggles the
selection state of the item at the location cursor. Any previous
selections remain.
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, moves the
current anchor to the item at the location cursor. In Normal Mode,
deselects any current selection and selects the item at the
location cursor. In Add Mode, toggles the selection state of the
item at the location cursor and leaves the current selection
unchanged. If XmNautomaticSelection is set to True, calls the
XmNextendedSelectionCallback callbacks.
ListKbdCancel():
If the XmNselectionPolicy is set to XmEXTENDED_SELECT and an
extended selection is being made from the current anchor point,
cancels the new selection and restores the selection state of the
items in that range to their state before the extended selection
was done.
ListKbdDeSelectAll():
If the XmNselectionPolicy is set to XmSINGLE_SELECT,
XmMULTIPLE_SELECT, or XmEXTENDED_SELECT in Add Mode, deselects all
items in the list. If the XmNselectionPolicy is set to
XmEXTENDED_SELECT in Normal Mode, deselects all items in the list
(except the item at the location cursor if the shell's
XmNkeyboardFocusPolicy is XmEXPLICIT). Calls the appropriate
selection callbacks (XmNsingleSelectionCallback when
XmNselectionPolicy is set to XmSINGLE_SELECT,
XmNmultipleSelectionCallback when XmNselectionPolicy is set to
XmMULTIPLE_SELECT, XmNextendedSelectionCallback when
XmNselectionPolicy is set to XmEXTENDED_SELECT).
ListKbdEndExtend():
If the XmNselectionPolicy is set to XmEXTENDED_SELECT and if
XmNautomaticSelection is set to False, calls the
XmNextendedSelectionCallback callbacks.
10/89 Page 15
XmList(3X) UNIX System V XmList(3X)
ListKbdEndSelect():
If the XmNselectionPolicy is set to XmSINGLE_SELECT or
XmMULTIPLE_SELECT or if XmNautomaticSelection is set to False,
calls the appropriate selection callbacks
(XmNsingleSelectionCallback when XmNselectionPolicy is set to
XmSINGLE_SELECT, XmNbrowseSelectionCallback when XmNselectionPolicy
is set to XmBROWSE_SELECT, XmNmultipleSelectionCallback when
XmNselectionPolicy is set to XmMULTIPLE_SELECT,
XmNextendedSelectionCallback when XmNselectionPolicy is set to
XmEXTENDED_SELECT).
ListKbdSelectAll():
If the XmNselectionPolicy is set to XmSINGLE_SELECT or
XmBROWSE_SELECT, selects the item at the location cursor. If the
XmNselectionPolicy is set to XmEXTENDED_SELECT or
XmMULTIPLE_SELECT, selects all items in the list. Calls the
appropriate selection callbacks (XmNsingleSelectionCallback when
XmNselectionPolicy is set to XmSINGLE_SELECT,
XmNbrowseSelectionCallback when XmNselectionPolicy is set to
XmBROWSE_SELECT, XmNmultipleSelectionCallback when
XmNselectionPolicy is set to XmMULTIPLE_SELECT,
XmNextendedSelectionCallback when XmNselectionPolicy is set to
XmEXTENDED_SELECT).
ListLeftChar():
Scrolls the list one character to the left.
ListLeftPage():
Scrolls the list one page to the left.
ListNextItem():
Moves the location cursor to the next item in the list.
If the XmNselectionPolicy is set to XmBROWSE_SELECT, this action
also selects the next item, deselects any current selection, and
calls the XmNbrowseSelectionCallback callbacks.
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, this action
in Normal Mode also selects the next item, deselects any current
selection, moves the current anchor to the next item, and calls the
XmNextendedSelectionCallback callbacks. In Add Mode this action
does not affect the selection or the anchor.
ListNextPage():
Scrolls the list to the next page, moving the location cursor to a
new item.
If the XmNselectionPolicy is set to XmBROWSE_SELECT, this action
also selects the new item, deselects any current selection, and
calls the XmNbrowseSelectionCallback callbacks.
Page 16 10/89
XmList(3X) UNIX System V XmList(3X)
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, this action
in Normal Mode also selects the new item, deselects any current
selection, moves the current anchor to the new item, and calls the
XmNextendedSelectionCallback callbacks. In Add Mode this action
does not affect the selection or the anchor.
ListPrevItem():
Moves the location cursor to the previous item in the list.
If the XmNselectionPolicy is set to XmBROWSE_SELECT, this action
also selects the previous item, deselects any current selection,
and calls the XmNbrowseSelectionCallback callbacks.
If the XmNselectionPolicy is set to XmEXTENDED_SELECT, this action
in Normal Mode also selects the previous item, deselects any
current selection, moves the current anchor to the previous item,
and calls the XmNextendedSelectionCallback callbacks. In Add Mode
this action does not affect the selection or the anchor.
ListPrevPage():
Scrolls the list to the previous page, moving the location cursor
to a new item.
If the XmNselectionPolicy is set to XmBROWSE_SELECT, this action
also selects the new item, deselects any current selection, and
calls the XmNbrowseSelectionCallback callbacks.
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.
ListRightChar():
Scrolls the list one character to the right.
ListRightPage():
Scrolls the list one page to the right.
PrimitiveHelp():
Calls the callbacks for XmNhelpCallback if any exist. If there are
no help callbacks for this widget, this action calls the help
callbacks for the nearest ancestor that has them.
PrimitiveNextTabGroup():
Moves the focus to the first item contained within the next tab
group. If the current tab group is the last entry in the tab group
list, it wraps to the beginning of the tab group list.
PrimitivePrevTabGroup():
Moves the focus to the first item contained within the previous tab
group. If the beginning of the tab group list is reached, it wraps
10/89 Page 17
XmList(3X) UNIX System V XmList(3X)
to the end of the tab group list.
Additional Behavior
The List widget has the additional behavior described below:
<Double Click>
If a button click is followed by another button click within the
time span specified by the display's multi-click time, the List
interprets that as a double click and calls the callbacks for
XmNdefaultActionCallback. The item's colors invert to indicate
that it is selected. The XmNdoubleClickInterval resource can be
used to specify a time span that overrides the display's multi-
click time.
<FocusIn>:
If the focus policy is Explicit, sets the focus and draw the
location cursor.
<FocusOut>:
If the focus policy is Explicit, removes the focus and erase the
location cursor.
Virtual Bindings
The bindings for virtual keys are vendor specific. For information about
bindings for virtual buttons and keys, see VirtualBindings(3X).
RELATED INFORMATION
Core(3X), XmCreateList(3X), XmCreateScrolledList(3X),
XmFontListCreate(3X) XmListAddItem(3X), XmListAddItemUnselected(3X),
XmListDeleteItem(3X), XmListDeletePos(3X), XmListDeselectItem(3X),
XmListDeselectAllItems(3X), XmListSelectItem(3X), XmListSetHorizPos(3X),
XmListSetItem(3X), XmListSetPos(3X), XmListSetBottomItem(3X),
XmListSetBottomPos(3X), XmListSelectPos(3X), XmListDeselectPos(3X),
XmListItemExists(3X), XmStringCreate(3X), and XmPrimitive(3X).
Page 18 10/89