Provided by: libmotif-dev_2.3.8-2build1_amd64 
NAME
XmList — The List widget class "XmList" "widget class" "List"
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.
Specifying the number of items that are visible sets the size of the List. 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 <Btn1> mouse button or the
key defined as <osfSelect>. 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.
List uses the XmQTspecifyRenderTable, XmQTscrollFrame, and XmQTnavigator traits, and holds the
XmQTtransfer trait.
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
<Btn1> on an item toggles its selection state and deselects any other selected item. In Browse Select,
pressing <Btn1> on an item selects it and deselects any other selected item; dragging <Btn1> moves the
selection as the pointer is moved. Releasing <Btn1> on an item moves the location cursor to that item.
In Multiple Select, any number of items can be selected at a time. Pressing <Btn1> 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 <Btn1> on an item selects it and deselects any other selected item. Dragging <Btn1>
or pressing or dragging <Shift><Btn1> following a <Btn1> action selects all items between the item under
the pointer and the item on which <Btn1> 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
<Ctrl><Btn1> on an item toggles its selection state but does not deselect any other selected items.
Dragging <Ctrl><Btn1> or pressing or dragging <Shift><Btn1> following a <Ctrl><Btn1> action sets the
selection state of all items between the item under the pointer and the item on which <Ctrl><Btn1> was
pressed to the state of the item on which <Ctrl><Btn1> 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
<osfSelect> select the item at the location cursor and deselect any other selected items. In Add Mode,
navigation operations have no effect on selection, and <osfSelect> 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 <osfAddMode>. In Extended Select
Normal Mode, pressing <osfSelect> has the same effect as pressing <Btn1>; <osfExtend> and shifted
navigation have the same effect as pressing <Shift><Btn1> following a <Btn1> action. In Extended Select
Add Mode, pressing <osfSelect> has the same effect as pressing <Ctrl><Btn1>; <osfExtend> and shifted
navigation have the same effect as pressing <Shift><Btn1> following a <Ctrl><Btn1> action.
Normal Mode is indicated by a solid location cursor, and Add Mode is indicated by a dashed location
cursor.
Data Transfer Behavior
List supports dragging of items from the List and transfer of items to the clipboard. When the user
presses BTransfer on a selected item, the widget transfers all selected items. When the user presses
BTransfer on an unselected item, the widget transfers only that item. Depending on the value of
XmNprimaryOwnership, List can also support primary selection.
When the XmNconvertCallback procedures are called, the location_data member of the
XmConvertCallbackStruct member is NULL if the selected items are being transferred. If the selected
items are not being transferred, this member has the following value: If a single item is being
transferred, the value is an integer representing the position of the item in the List. A value of 1
transfers the first item in the List; a value of 2 transfers the second item; and so on. If the entire
contents of the List are being transferred, the value is -1.
As a source of data, List supports the following targets and associated conversions of data to these
targets:
locale If the locale target matches the widget's locale, the widget transfers the selected list items
in the encoding of the locale. Each item transferred except the last includes a trailing
separator.
COMPOUND_TEXT
The widget transfers the selected list items as type COMPOUND_TEXT. Each item transferred
except the last includes a trailing separator.
UTF8_STRING
The widget transfers the selected list items as type UTF8_STRING. Each item transferred except
the last includes a trailing separator.
STRING The widget transfers the selected list items as type STRING. Each item transferred except the
last includes a trailing separator.
TEXT If the selected list items are fully convertible to the encoding of the locale, the widget
transfers the selected list items in the encoding of the locale. Otherwise, the widget
transfers the selected list items as type COMPOUND_TEXT. Each item transferred except the last
includes a trailing separator.
_MOTIF_CLIPBOARD_TARGETS
The widget transfers, as type ATOM, a list of the targets it supports for immediate transfer
for the CLIPBOARD selection. These include _MOTIF_COMPOUND_STRING. If the selected list items
are fully convertible to STRING, these also include STRING; otherwise, they also include
COMPOUND_TEXT and UTF8_STRING.
_MOTIF_COMPOUND_STRING
The widget transfers the selected list items as a compound string in Byte Stream format. Each
item transferred except the last includes a trailing separator.
_MOTIF_DEFERRED_CLIPBOARD_TARGETS
The widget transfers, as type ATOM, a list of the targets it supports for delayed transfer for
the CLIPBOARD selection. This widget currently supplies no targets for
_MOTIF_DEFERRED_CLIPBOARD_TARGETS.
_MOTIF_EXPORT_TARGETS
The widget transfers, as type ATOM, a list of the targets to be used as the value of the
DragContext's XmNexportTargets in a drag-and-drop transfer. These include
_MOTIF_COMPOUND_STRING, COMPOUND_TEXT, UTF8_STRING, the encoding of the locale, STRING, TEXT,
BACKGROUND, and FOREGROUND.
_MOTIF_LOSE_SELECTION
When the widget loses the selection, it deselects all list items.
As a source of data, List also supports the following standard Motif targets:
BACKGROUND
The widget transfers XmNbackground as type PIXEL.
CLASS The widget finds the first shell in the widget hierarchy that has a WM_CLASS property and
transfers the contents as text in the current locale.
CLIENT_WINDOW
The widget finds the first shell in the widget hierarchy and transfers its window as type
WINDOW.
COLORMAP The widget transfers XmNcolormap as type COLORMAP.
FOREGROUND
The widget transfers XmNforeground as type PIXEL.
NAME The widget finds the first shell in the widget hierarchy that has a WM_NAME property and
transfers the contents as text in the current locale.
TARGETS The widget transfers, as type ATOM, a list of the targets it supports. These include the
standard targets in this list. These also include _MOTIF_COMPOUND_STRING, COMPOUND_TEXT,
UTF8_STRING the encoding of the locale, STRING, and TEXT.
TIMESTAMP The widget transfers the timestamp used to acquire the selection as type INTEGER.
_MOTIF_RENDER_TABLE
The widget transfers XmNrenderTable if it exists, or else the default text render table, as
type STRING.
_MOTIF_ENCODING_REGISTRY
The widget transfers its encoding registry as type STRING. The value is a list of NULL
separated items in the form of tag encoding pairs. This target symbolizes the transfer target
for the Motif Segment Encoding Registry. Widgets and applications can use this Registry to
register text encoding formats for specified render table tags. Applications access this
Registry by calling XmRegisterSegmentEncoding and XmMapSegmentEncoding.
List has no widget class destination procedure. Subclasses and the XmNdestinationCallback procedures are
responsible for any data transfers to the widget.
Classes
List inherits behavior, resources, and traits from Core and XmPrimitive.
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).
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
--
RELATED
Core(3), XmCreateList(3), XmCreateScrolledList(3), XmFontListCreate(3), XmFontListAppendEntry(3),
XmListAddItem(3), XmListAddItems(3), XmListAddItemUnselected(3), XmListAddItemsUnselected(3),
XmListDeleteAllItems(3), XmListDeleteItem(3), XmListDeleteItems(3), XmListDeleteItemsPos(3),
XmListDeletePos(3), XmListDeletePositions(3), XmListDeselectAllItems(3), XmListDeselectItem(3),
XmListDeselectPos(3), XmListGetKbdItemPos XmListGetMatchPos(3), XmListGetSelectedPos(3),
XmListItemExists(3), XmListItemPos(3), XmListPosToBounds(3), XmListReplaceItems(3),
XmListReplaceItemsPos(3), XmListReplaceItemsPos(3), XmListReplaceItemsPosUnselected(3),
XmListReplaceItemsUnselected(3), XmListSelectItem(3), XmListSelectPos(3), XmListSetAddMode(3),
XmListSetBottomItem(3), XmListSetBottomPos(3), XmListSetHorizPos(3), XmListSetItem(3),
XmListSetKbdItemPos(3), XmListSetPos(3), XmListUpdateSelectedList(3), XmListYToPos(3), XmPrimitive(3)
XmStringCreate(3), XmVaCreateList(3), and XmVaCreateManagedList(3).
XmList(3)