Provided by: libmotif-dev_2.3.4-10_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).
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
Binary file (standard input) matches