XmList(3X) SDK X11 R4.11MU05 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 compound strings that are defined by the application. Each
compound string becomes an item in the List, with the first compound
string becoming the item in position 1, the second becoming the item
in position 2, and so on.
The size of the List is set by specifying the number of items that
are visible. If the number of visible items is not specified, the
height of the list controls the number of visible items. Each item
assumes the height of the tallest element in the list. To create a
list that allows the user to scroll easily through a large number of
items, use the XmCreateScrolledList convenience function.
To select items, move the pointer or cursor to the desired item and
press the BSelect mouse button or the key defined as KSelect. There
are several styles of selection behavior, and they all highlight the
selected item or items by displaying them in inverse colors. An
appropriate callback is invoked to notify the application of the
user's choice. The application then takes whatever action is
required for the specified selection. When a List is insensitive,
all of the list items are displayed in a stippled fill pattern.
Selection
Each list has one of four selection models:
· Single Select
· Browse Select
· Multiple Select
· Extended Select
In Single Select and Browse Select, at most one item is selected at a
time. In Single Select, pressing BSelect on an item toggles its
selection state and deselects any other selected item. In Browse
Select, pressing BSelect on an item selects it and deselects any
other selected item; dragging BSelect moves the selection as the
pointer is moved. Releasing BSelect on an item moves the location
cursor to that item.
In Multiple Select, any number of items can be selected at a time.
Pressing BSelect on an item toggles its selection state but does not
deselect any other selected items.
In Extended Select, any number of items can be selected at a time,
and the user can easily select ranges of items. Pressing BSelect on
an item selects it and deselects any other selected item. Dragging
BSelect or pressing or dragging BExtend following a BSelect action
selects all items between the item under the pointer and the item on
which BSelect was pressed. This action also deselects any other
selected items outside that range.
Extended Select also allows the user to select and deselect
discontiguous ranges of items. Pressing BToggle on an item toggles
its selection state but does not deselect any other selected items.
Dragging BToggle or pressing or dragging BExtend following a BToggle
action sets the selection state of all items between the item under
the pointer and the item on which BToggle was pressed to the state of
the item on which BToggle was pressed. This action does not deselect
any other selected items outside that range.
All selection operations available from the mouse are also available
from the keyboard. List has two keyboard selection modes, Normal
Mode and Add Mode. In Normal Mode, navigation operations and KSelect
select the item at the location cursor and deselect any other
selected items. In Add Mode, navigation operations have no effect on
selection, and KSelect toggles the selection state of the item at the
location cursor without deselecting any other selected items, except
in Single Select.
Single and Multiple Select use Add Mode, and Browse Select uses
Normal Mode.
Extended Select can use either mode; the user changes modes by
pressing KAddMode. In Extended Select Normal Mode, pressing KSelect
has the same effect as pressing BSelect; KExtend and shifted
navigation have the same effect as pressing BExtend following a
BSelect action. In Extended Select Add Mode, pressing KSelect has
the same effect as pressing BToggle; KExtend and shifted navigation
have the same effect as pressing BExtend following a BToggle action.
Normal Mode is indicated by a solid location cursor, and Add Mode is
indicated by a dashed location cursor.
Classes
List inherits behavior and resources from Core and XmPrimitive
classes.
The class pointer is xmListWidgetClass.
The class name is XmList.
New Resources
The following table defines a set of widget resources used by the
programmer to specify data. The programmer can also set the resource
values for the inherited classes to set attributes for this widget.
To reference a resource by name or by class in a .Xdefaults file,
remove the XmN or XmC prefix and use the remaining letters. To
specify one of the defined values for a resource in a .Xdefaults
file, remove the Xm prefix and use the remaining letters (in either
lowercase or uppercase, but include any underscores between words).
The codes in the access column indicate if the given resource can be
set at creation time (C), set by using XtSetValues (S), retrieved by
using XtGetValues (G), or is not applicable (N/A).
+--------------------------------------------------------------------------------------------------------+
| XmList Resource Set |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|Name | Class | Type | Default | Access |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNautomaticSelection | XmCAutomaticSelection | Boolean | False | CSG |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNbrowseSelectionCallback | XmCCallback | XtCallbackList | NULL | C |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNdefaultActionCallback | XmCCallback | XtCallbackList | NULL | C |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNdoubleClickInterval | XmCDoubleClickInterval | int | dynamic | CSG |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNextendedSelectionCallback | XmCCallback | XtCallbackList | NULL | C |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNfontList | XmCFontList | XmFontList | dynamic | CSG |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNitemCount | XmCItemCount | int | 0 | CSG |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNitems | XmCItems | XmStringTable | NULL | CSG |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNlistMarginHeight | XmCListMarginHeight | Dimension | 0 | CSG |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNlistMarginWidth | XmCListMarginWidth | Dimension | 0 | CSG |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNlistSizePolicy | XmCListSizePolicy | unsigned char | XmVARIABLE | CG |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNlistSpacing | XmCListSpacing | Dimension | 0 | CSG |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNmultipleSelectionCallback | XmCCallback | XtCallbackList | NULL | C |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNscrollBarDisplayPolicy | XmCScrollBarDisplayPolicy | unsigned char | XmAS_NEEDED | CSG |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNselectedItemCount | XmCSelectedItemCount | int | 0 | CSG |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNselectedItems | XmCSelectedItems | XmStringTable | NULL | CSG |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNselectionPolicy | XmCSelectionPolicy | unsigned char | XmBROWSE_SELECT | CSG |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNsingleSelectionCallback | XmCCallback | XtCallbackList | NULL | C |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNstringDirection | XmCStringDirection | XmStringDirection | dynamic | CSG |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNtopItemPosition | XmCTopItemPosition | int | 1 | CSG |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
|XmNvisibleItemCount | XmCVisibleItemCount | int | dynamic | CSG |
+-----------------------------+---------------------------+-------------------+-----------------+--------+
XmNautomaticSelection
Invokes XmNbrowseSelectionCallback or
XmNextendedSelectionCallback when BSelect is pressed and
the items that are shown as selected change if the value is
True and the selection mode is either XmBROWSESELECT or
XmEXTENDEDSELECT respectively. If False, no selection
callbacks are invoked until the user releases the mouse
button. See the Behavior section for further details on
the interaction of this resource with the selection modes.
XmNbrowseSelectionCallback
Specifies a list of callbacks that is called when an item
is selected in the browse selection mode. The reason is
XmCRBROWSESELECT.
XmNdefaultActionCallback
Specifies a list of callbacks that is called when an item
is double clicked or KActivate is pressed. The reason is
XmCRDEFAULTACTION.
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
XmCREXTENDEDSELECT.
XmNfontList
Specifies the font list associated with the list items.
This is used in conjunction with the XmNvisibleItemCount
resource to determine the height of the List widget. If
this value is NULL at initialization, the font list is
initialized by looking up the parent hierarchy of the
widget for an ancestor that is a subclass of the
XmBulletinBoard or VendorShell widget class. If such an
ancestor is found, the font list is initialized to the
XmNtextFontList of the ancestor widget. If no such
ancestor is found, the default is implementation dependent.
Refer to XmFontList(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 XmRESIZEIFPOSSIBLE, the List
attempts to grow or shrink to match the width of the widest item. If
it cannot grow to match the widest size, a horizontal ScrollBar is
added for a ScrolledList if the longest item is wider than the list
viewing area.
The size policy must be set at the time the List widget is created.
It cannot be changed at a later time through XtSetValues.
XmNlistSpacing
Specifies the spacing between list items. This spacing
increases by the value of the XmNhighlightThickness
resource in Primitive.
XmNmultipleSelectionCallback
Specifies a list of callbacks that is called when an item
is selected in multiple selection mode. The reason is
XmCRMULTIPLESELECT.
XmNscrollBarDisplayPolicy
Controls the display of vertical ScrollBars in a
ScrolledList. When the value of this resource is
XmASNEEDED, a vertical ScrollBar is displayed only when
the number of items in the List exceeds the number of
Visible items. When the value is XmSTATIC, a vertical
ScrollBar is always displayed.
XmNselectedItemCount
Specifies the number of strings in the selected items list.
The value must be the number of items in XmNselectedItems
and must not be negative.
XmNselectedItems
Points to an array of compound strings that represents the
list items that are currently selected, either by the user
or by the application. XtGetValues for this resource
returns the list items themselves, not a copy of the list
items. The application must not free the returned items.
Setting XmNselectedItems selects those list items that exactly match
items in the given XmNselectedItems list. There may be additional
items in XmNselectedItems that do not match items in the list. These
items remain until XmNselectedItems is updated. If XmNitems is
changed such that the list now contains items matching previously
unmatched items in XmNselectedItems, those new items will also appear
selected.
Any user interaction with the list that causes at least one item to
be selected or deselected and any call to XmListDeselectAllItems,
XmListDeselectAllItems, XmListDeselectPos, XmListSelectItem,
XmListSelectPos, or XmListUpdateSelectedList cause XmNselectedItems
to be updated immediately to exactly reflect the visual state of the
list. Calls to any other XmList functions do not affect
XmNselectedItems.
XmNselectionPolicy
Defines the interpretation of the selection action. This
can be one of the following:
· XmSINGLESELECT--allows only single selections
· XmMULTIPLESELECT--allows multiple selections
· XmEXTENDEDSELECT--allows extended selections
· XmBROWSESELECT"--allows "drag and browse" functionality
XmNsingleSelectionCallback
Specifies a list of callbacks that is called when an item
is selected in single selection mode. The reason is
XmCRSINGLESELECT.
XmNstringDirection
Specifies the initial direction to draw the string. The
values are XmSTRINGDIRECTIONLTOR and
XmSTRINGDIRECTIONRTOL. 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 XmSTRINGDIRECTIONLTOR.
XmNtopItemPosition
Specifies the position of the item that is the first
visible item in the list. Setting this resource is
equivalent to calling the XmListSetPos function. The
position of the first item in the list is 1; the position
of the second item is 2; and so on. A position of 0
specifies the last item in the list. The value must not be
negative.
XmNvisibleItemCount
Specifies the number of items that can fit in the visible
space of the list work area. The List uses this value to
determine its height. The value must be greater than 0.
Inherited Resources
List inherits behavior and resources from the following superclasses.
For a complete description of each resource, refer to the man page
for that superclass.
+-------------------------------------------------------------------------------------------------+
| XmPrimitive Resource Set |
+----------------------+-----------------------+------------------+----------------------+--------+
|Name | Class | Type | Default | Access |
+----------------------+-----------------------+------------------+----------------------+--------+
+----------------------+-----------------------+------------------+----------------------+--------+
|XmNbottomShadowColor | XmCBottomShadowColor | Pixel | dynamic | CSG |
+----------------------+-----------------------+------------------+----------------------+--------+
|XmNbottomShadowPixmap | XmCBottomShadowPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG |
+----------------------+-----------------------+------------------+----------------------+--------+
|XmNforeground | XmCForeground | Pixel | dynamic | CSG |
+----------------------+-----------------------+------------------+----------------------+--------+
|XmNhelpCallback | XmCCallback | XtCallbackList | NULL | C |
+----------------------+-----------------------+------------------+----------------------+--------+
|XmNhighlightColor | XmCHighlightColor | Pixel | dynamic | CSG |
+----------------------+-----------------------+------------------+----------------------+--------+
|XmNhighlightOnEnter | XmCHighlightOnEnter | Boolean | False | CSG |
+----------------------+-----------------------+------------------+----------------------+--------+
|XmNhighlightPixmap | XmCHighlightPixmap | Pixmap | dynamic | CSG |
+----------------------+-----------------------+------------------+----------------------+--------+
|XmNhighlightThickness | XmCHighlightThickness | Dimension | 2 | CSG |
+----------------------+-----------------------+------------------+----------------------+--------+
|XmNnavigationType | XmCNavigationType | XmNavigationType | XmTAB_GROUP | CSG |
+----------------------+-----------------------+------------------+----------------------+--------+
|XmNshadowThickness | XmCShadowThickness | Dimension | 2 | CSG |
+----------------------+-----------------------+------------------+----------------------+--------+
|XmNtopShadowColor | XmCTopShadowColor | Pixel | dynamic | CSG |
+----------------------+-----------------------+------------------+----------------------+--------+
|XmNtopShadowPixmap | XmCTopShadowPixmap | Pixmap | dynamic | CSG |
+----------------------+-----------------------+------------------+----------------------+--------+
|XmNtraversalOn | XmCTraversalOn | Boolean | True | CSG |
+----------------------+-----------------------+------------------+----------------------+--------+
|XmNunitType | XmCUnitType | unsigned char | dynamic | CSG |
+----------------------+-----------------------+------------------+----------------------+--------+
|XmNuserData | XmCUserData | XtPointer | NULL | CSG |
+----------------------+-----------------------+------------------+----------------------+--------+
+---------------------------------------------------------------------------------------------------------------+
| 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:
typedef struct
{
int reason;
XEvent *event;
XmString item;
int itemlength;
int itemposition;
XmString *selecteditems;
int selecteditemcount;
int *selecteditempositions;
char selectiontype;
} 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.
itemlength Is the length in bytes of item.
itemposition
Is the position of item in the List's XmNitems array.
selecteditems
Is a list of items selected at the time of the event
that caused the callback. selecteditems 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.
selecteditemcount
Is the number of items in the selecteditems list.
This number must be non-negative.
selecteditempositions
Is an array of integers, one for each selected item,
representing the position of each selected item in the
List's XmNitems array. selecteditempositions 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.
selectiontype
Indicates that the most recent extended selection was
the initial selection (XmINITIAL), a modification of an
existing selection (XmMODIFICATION), or an additional
noncontiguous selection (XmADDITION).
The following table describes the reasons for which the individual
callback structure fields are valid:
+---------------------+-------------------------------------------------+
| Reason | Valid Fields |
+---------------------+-------------------------------------------------+
|XmCRSINGLESELECT | reason, event, item, itemlength, itemposition |
+---------------------+-------------------------------------------------+
|XmCRDEFAULTACTION | reason, event, item, itemlength, |
| | itemposition, selecteditems, |
| | selecteditemcount, selecteditempositions |
+---------------------+-------------------------------------------------+
+---------------------+-------------------------------------------------+
|XmCRBROWSESELECT | reason, event, item, itemlength, itemposition |
+---------------------+-------------------------------------------------+
|XmCRMULTIPLESELECT | reason, event, item, itemlength, |
| | itemposition, selecteditems, |
| | selecteditemcount, selecteditempositions |
+---------------------+-------------------------------------------------+
|XmCREXTENDEDSELECT | reason, event, item, itemlength, |
| | itemposition, selecteditems, |
| | selecteditemcount, selecteditempositions, |
| | selectiontype |
+---------------------+-------------------------------------------------+
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: ListExtendPrevItem()
KDown: ListNextItem()
MShift KDown: ListExtendNextItem()
KLeft: ListLeftChar()
MCtrl KLeft: ListLeftPage()
KRight: ListRightChar()
MCtrl KRight: ListRightPage()
KPageUp: ListPrevPage()
KPageDown: ListNextPage()
KPageLeft: ListLeftPage()
KPageRight: ListRightPage()
KBeginLine: ListBeginLine()
KEndLine: ListEndLine()
KBeginData: ListBeginData()
MShift KBeginData:ListBeginDataExtend()
KEndData: ListEndData()
MShift KEndData:ListEndDataExtend()
KAddMode: ListAddMode()
KActivate: ListKbdActivate()
KCopy Press: ListCopyToClipboard()
KSelect Press: ListKbdBeginSelect()
KSelect Release:ListKbdEndSelect()
KExtend Press: ListKbdBeginExtend()
KExtend Release:ListKbdEndExtend()
MAny KCancel: ListKbdCancel()
KSelectAll: ListKbdSelectAll()
KDeselectAll: ListKbdDeSelectAll()
KHelp: PrimitiveHelp()
KNextField PrimitiveNextTabGroup()
KPrevField PrimitivePrevTabGroup()
Action Routines
The XmList action routines are described below. The current
selection is always shown with inverted colors.
ListAddMode():
Toggles the state of Add Mode for keyboard selection.
ListBeginData():
Moves the location cursor to the first item in the list.
In Normal Mode, this also deselects any current selection,
selects the first item in the list, and calls the
appropriate selection callbacks (XmNbrowseSelectionCallback
when XmNselectionPolicy is set to XmBROWSESELECT,
XmNextendedSelectionCallback when XmNselectionPolicy is set
to XmEXTENDEDSELECT).
ListBeginDataExtend():
If the XmNselectionPolicy is set to XmMULTIPLESELECT or
XmEXTENDEDSELECT, moves the location cursor to the first
item in the list.
If the XmNselectionPolicy is set to XmEXTENDEDSELECT, 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 XmEXTENDEDSELECT, 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 XmSINGLESELECT,
deselects any current selection and toggles the selection
state of the item under the pointer.
If the XmNselectionPolicy is set to XmBROWSESELECT, 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 XmMULTIPLESELECT, toggles the
selection state of the item under the pointer. Any previous
selections remain.
If the XmNselectionPolicy is set to XmEXTENDEDSELECT, 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 XmEXTENDEDSELECT, does
the following: Moves the current anchor to the item under
the pointer without changing the current selection. If the
item is unselected, it is selected; if the item is
selected, it is unselected. If XmNautomaticSelection is
set to True, calls the XmNextendedSelectionCallback
callbacks.
ListButtonMotion():
If the XmNselectionPolicy is set to XmBROWSESELECT,
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 XmEXTENDEDSELECT, does the
following: If an extended selection is being made and an extended
selection has previously been made from the current anchor point,
restores the selection state of the items in that range to their
state before the previous extended selection was done. Changes the
selection state of the item under the pointer and all items between
it and the current anchor point to the state of the item at the
current anchor point. If XmNautomaticSelection is set to True and
the pointer has entered a new list item, calls the
XmNextendedSelectionCallback callbacks.
If the pointer leaves a scrolled list, this action scrolls the list
in the direction of the pointer motion.
ListCopyToClipboard()
Copies the content of the selected items to the clipboard
as a single compound string with each item separated by a
newline.
ListEndData():
Moves the location cursor to the last item in the list. In
Normal Mode, this also deselects any current selection,
selects the last item in the list, and calls the
appropriate selection callbacks (XmNbrowseSelectionCallback
when XmNselectionPolicy is set to XmBROWSESELECT,
XmNextendedSelectionCallback when XmNselectionPolicy is set
to XmEXTENDEDSELECT).
ListEndDataExtend():
If the XmNselectionPolicy is set to XmMULTIPLESELECT or
XmEXTENDEDSELECT, moves the location cursor to the last
item in the list.
If the XmNselectionPolicy is set to XmEXTENDEDSELECT, 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 XmEXTENDEDSELECT,
moves the location cursor to the last item selected or
deselected and, if XmNautomaticSelection is set to False,
calls the XmNextendedSelectionCallback callbacks.
ListEndLine():
Moves the horizontal scroll region to the end of the line.
ListEndSelect():
If the XmNselectionPolicy is set to XmSINGLESELECT or
XmMULTIPLESELECT, moves the location cursor to the last
item selected or deselected and calls the appropriate
selection callbacks (XmNsingleSelectionCallback when
XmNselectionPolicy is set to XmSINGLESELECT,
XmNmultipleSelectionCallback when XmNselectionPolicy is set
to XmMULTIPLESELECT).
If the XmNselectionPolicy is set to XmBROWSESELECT or
XmEXTENDEDSELECT, 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 XmBROWSESELECT,
XmNextendedSelectionCallback when XmNselectionPolicy is set to
XmEXTENDEDSELECT).
ListEndToggle():
If the XmNselectionPolicy is set to XmEXTENDEDSELECT,
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 XmEXTENDEDSELECT, 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 XmEXTENDEDSELECT, does
the following: If an extended selection has been made from
the current anchor point, restores the selection state of
the items in that range to their state before the extended
selection was done. Moves the location cursor to the
previous item and changes the selection state of the item
and all items between it and the current anchor point to
the state of the item at the current anchor point. Calls
the XmNextendedSelectionCallback callbacks.
ListScrollCursorVertically(percentage):
Scrolls the line containing the insertion cursor vertically
to an intermediate position in the visible window based on
an input percentage. A value of 0 indicates the top of the
window; a value of 100, the bottom of the window. If this
action is called with no argument, the line containing the
insertion cursor is scrolled vertically to a new position
designated by the y event passed to the routine.
ListKbdActivate():
Calls the callbacks for XmNdefaultActionCallback. If the
List's parent is a manager, this action passes the event to
the parent.
ListKbdBeginExtend():
If the XmNselectionPolicy is set to XmEXTENDEDSELECT, does
the following: If an extended selection has been made from
the current anchor point, restores the selection state of
the items in that range to their state before the extended
selection was done. Changes the selection state of the
item at the location cursor and all items between it and
the current anchor point to the state of the item at the
current anchor point. If XmNautomaticSelection is set to
True, calls the XmNextendedSelectionCallback callbacks.
ListKbdBeginSelect():
If the XmNselectionPolicy is set to XmSINGLESELECT,
deselects any current selection and toggles the state of
the item at the location cursor.
If the XmNselectionPolicy is set to XmBROWSESELECT, 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 XmMULTIPLESELECT, toggles the
selection state of the item at the location cursor. Any previous
selections remain.
If the XmNselectionPolicy is set to XmEXTENDEDSELECT, 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 XmEXTENDEDSELECT and
an extended selection is being made from the current anchor
point, cancels the new selection and restores the selection
state of the items in that range to their state before the
extended selection was done. If XmNautomaticSelection is
set to True, calls the XmNextendedSelectionCallback
callbacks, otherwise, and if the parent is a manager,
passes the event to the parent.
ListKbdDeSelectAll():
If the XmNselectionPolicy is set to XmSINGLESELECT,
XmMULTIPLESELECT, or XmEXTENDEDSELECT in Add Mode,
deselects all items in the list. If the XmNselectionPolicy
is set to XmEXTENDEDSELECT 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 XmSINGLESELECT, XmNmultipleSelectionCallback when
XmNselectionPolicy is set to XmMULTIPLESELECT,
XmNextendedSelectionCallback when XmNselectionPolicy is set
to XmEXTENDEDSELECT).
ListKbdEndExtend():
If the XmNselectionPolicy is set to XmEXTENDEDSELECT and
if XmNautomaticSelection is set to False, calls the
XmNextendedSelectionCallback callbacks.
ListKbdEndSelect():
If the XmNselectionPolicy is set to XmSINGLESELECT or
XmMULTIPLESELECT or if XmNautomaticSelection is set to
False, calls the appropriate selection callbacks
(XmNsingleSelectionCallback when XmNselectionPolicy is set
to XmSINGLESELECT, XmNbrowseSelectionCallback when
XmNselectionPolicy is set to XmBROWSESELECT,
XmNmultipleSelectionCallback when XmNselectionPolicy is set
to XmMULTIPLESELECT, XmNextendedSelectionCallback when
XmNselectionPolicy is set to XmEXTENDEDSELECT).
ListKbdSelectAll():
If the XmNselectionPolicy is set to XmSINGLESELECT or
XmBROWSESELECT, selects the item at the location cursor.
If the XmNselectionPolicy is set to XmEXTENDEDSELECT or
XmMULTIPLESELECT, selects all items in the list. Calls
the appropriate selection callbacks
(XmNsingleSelectionCallback when XmNselectionPolicy is set
to XmSINGLESELECT, XmNbrowseSelectionCallback when
XmNselectionPolicy is set to XmBROWSESELECT,
XmNmultipleSelectionCallback when XmNselectionPolicy is set
to XmMULTIPLESELECT, XmNextendedSelectionCallback when
XmNselectionPolicy is set to XmEXTENDEDSELECT).
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 XmBROWSESELECT, this action also
selects the next item, deselects any current selection, and calls the
XmNbrowseSelectionCallback callbacks.
If the XmNselectionPolicy is set to XmEXTENDEDSELECT, 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 XmBROWSESELECT, this action also
selects the new item, deselects any current selection, and calls the
XmNbrowseSelectionCallback callbacks.
If the XmNselectionPolicy is set to XmEXTENDEDSELECT, 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 XmBROWSESELECT, this action also
selects the previous item, deselects any current selection, and calls
the XmNbrowseSelectionCallback callbacks.
If the XmNselectionPolicy is set to XmEXTENDEDSELECT, 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 XmBROWSESELECT, this action also
selects the new item, deselects any current selection, and calls the
XmNbrowseSelectionCallback callbacks.
If the XmNselectionPolicy is set to XmEXTENDEDSELECT, 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.
ListProcessDrag():
Drags the content of a one or more selected list items.
Each item is separated by a newline. This action creates a
DragContext object whose XmNexportTargets resource is set
to "COMPOUND_TEXT" and the XmNclientData resource is set to
the index of the item in the list. If BDrag is pressed on
an unselected item, drags only that item, excluding any
other selected items.
ListRightChar():
Scrolls the list one character to the right.
ListRightPage():
Scrolls the list one page to the right.
PrimitiveHelp():
Calls the callbacks for XmNhelpCallback if any exist. If
there are no help callbacks for this widget, this action
calls the help callbacks for the nearest ancestor that has
them.
PrimitiveNextTabGroup():
Moves the focus to the first item contained within the next
tab group. If the current tab group is the last entry in
the tab group list, it wraps to the beginning of the tab
group list.
PrimitivePrevTabGroup():
Moves the focus to the first item contained within the
previous tab group. If the beginning of the tab group list
is reached, it wraps to the end of the tab group list.
Additional Behavior
The List widget has the additional behavior described below:
<Double Click>
If a button click is followed by another button click
within the time span specified by the display's multi-click
time, the List interprets that as a double click and calls
the callbacks for XmNdefaultActionCallback. The item's
colors invert to indicate that it is selected. The
XmNdoubleClickInterval resource can be used to specify a
time span that overrides the display's multi-click time.
<FocusIn>:
If the focus policy is Explicit, sets the focus and draw
the location cursor.
<FocusOut>:
If the focus policy is Explicit, removes the focus and
erase the location cursor.
Virtual Bindings
The bindings for virtual keys are vendor specific. For information
about bindings for virtual buttons and keys, see VirtualBindings(3X).
RELATED INFORMATION
Core(3X), XmCreateList(3X), XmCreateScrolledList(3X),
XmFontListAppendEntry(3X), XmListAddItem(3X), XmListAddItems(3X),
XmListAddItemUnselected(3X), XmListAddItemsUnselected(3X),
XmListDeleteAllItems(3X), XmListDeleteItem(3X),
XmListDeleteItems(3X), XmListDeleteItemsPos(3X), XmListDeletePos(3X),
XmListDeletePositions(3X), XmListDeselectAllItems(3X),
XmListDeselectItem(3X), XmListDeselectPos(3X), XmListGetKbdItemPos
XmListGetMatchPos(3X), XmListGetSelectedPos(3X),
XmListItemExists(3X), XmListItemPos(3X), XmListPosToBounds(3X),
XmListReplaceItems(3X), XmListReplaceItemsPos(3X),
XmListReplaceItemsPositions(3X), XmListReplaceItemsPosUnselected(3X),
XmListReplaceItemsUnselected(3X), XmListSelectItem(3X),
XmListSelectPos(3X), XmListSetAddMode(3X), XmListSetBottomItem(3X),
XmListSetBottomPos(3X), XmListSetHorizPos(3X), XmListSetItem(3X),
XmListSetKbdItemPos(3X), XmListSetPos(3X),
XmListUpdateSelectedList(3X), XmListYToPos(3X), XmPrimitive(3X) and
XmStringCreate(3X).
Licensed material--property of copyright holder(s)