Provided by: libmotif-dev_2.3.8-2build1_amd64 
NAME
XmContainer — The Container widget class "XmContainer" "container" "Container"
SYNOPSIS
#include <Xm/Container.h>
DESCRIPTION
Container manages child widgets that have the ContainerItem trait. These child widgets can be viewed in
several different layout formats, selected using different selection types and techniques, and directly
manipulated by the user.
Three different formats or views are supported by the Container. They are specified via the
XmNentryViewType resource:
• XmLARGE_ICON
• XmSMALL_ICON
• XmANY_ICON
Three different layout types are supported by the Container. They are specified by the XmNlayoutType
resource:
• XmSPATIAL
• XmOUTLINE
• XmDETAIL
In the XmSPATIAL layout type, several other resources (XmNspatialStyle, XmNspatialIncludeModel,
XmNspatialSnapModel) control the positioning of the items within the Container; an application programmer
can specify these resources so that the Container strictly enforces the position of each item or so that
the Container positions items according to constraint resources specified for each item. The user,
however, can alter the position of an item in the XmSPATIAL layout type within the Container by direct
manipulation; for example, by pressing BTransfer over the item and then dragging and releasing BTransfer
over some location within the Container.
In the XmOUTLINE layout type, the Container controls the positioning of the items. Items within the
Container can have parent-child relationships between them. Each item's XmNentryParent resource can
specify another item in the same Container as its parent; items with a non-NULL value for XmNentryParent
can only be displayed in the XmOUTLINE layout type. In the XmOUTLINE layout type, items are positioned in
a tree configuration with connecting lines drawn to illustrate the relationships. Items are positioned
top to bottom in the order specified by XmNpositionIndex within their parent. Container positions a
PushButton next to each item that has a parent relationship to other items. The PushButton contains a
pixmap to illustrate whether the child items are shown or not; the user can activate the PushButton to
toggle between showing or hiding the child items. Direct manipulation to alter the position of the item
is not supported in the XmOUTLINE layout type. Note that the XmNtraversalOn resource of the PushButtons
created by Container are set to False.
The XmDETAIL layout type is the same as XmOUTLINE, except that each item can also display additional
information as rows in columns with column headers specified in the XmNdetailColumnHeading resources. In
each item row, the item's detail information (see the reference page on XmIconGadget for a description of
the XmNentryDetail resource) is displayed. Items are positioned top to bottom in the order specified by
XmNpositionIndex within the parent.
Selection
When a child widget of the container is selected, the container specifies that the item should display
the appropriate visual information to the user via the ContainerItem trait. The application program is
notified of selection changes through XmNselectionCallback.
The container uses four selection policies:
• Single
• Browse
• Multiple
• Extended
In Single Select and Browse Select modes, only one item can be selected at a time. Pressing BSelect on an
item selects it and deselects any other selected item. Pressing BSelect over an empty space in the
Container deselects all items. In Browse Select, dragging BSelect moves the selection as the pointer is
moved.
In Multiple Select and Extended Select modes, any number of items can be selected at the same time. In
Multiple Select, pressing and dragging BSelect or BExtend to specify an item, range of items, or group of
discontiguous items causes the selection states of those items to be toggled. In Extended Select,
pressing and dragging BSelect to indicate an item, range of items, or group of discontiguous items
selects those items and deselects all others. Pressing and dragging BExtend in Extended Select to
indicate an item, range of items, or discontiguous group of items causes the selection states of those
items to be toggled.
Several techniques are available to indicate an item, range of items, or group of discontiguous items in
the Multiple Select and Extended Select modes.
In the XmSPATIAL and XmOUTLINE layout types, the XmNselectionTechnique resource specifies the techniques
to be used to indicate items. The default specification of XmTOUCH_OVER allows both the Random-Swipe and
Marquee techniques to be used when XmNlayoutStyle is XmSPATIAL. The default specification of XmTOUCH_OVER
allows the Range-Swipe, Range-Click, and Marquee techniques to be used when XmNlayoutStyle is XmOUTLINE.
Discontiguous groups of items can be selected using the Random-Swipe technique. In the Random-Swipe
technique, pressing BSelect (or BExtend) over an item and dragging BSelect over other items selects all
of those items. Only those items that pointer passed over are selected.
In the Range-Swipe technique, the user presses BSelect (or BExtend) over the first item and releases
BSelect over the last item; all items within the range between the first and last item are selected
whether the pointer actually passed over them or not. In the Range-Click technique, the user presses and
releases BSelect (or BExtend) over the first item and then presses and releases BExtend over the last
item.
In the Marquee technique, pressing BSelect (or BExtend) over a blank space within the Container indicates
the starting point of a Marquee rectangle. Dragging BSelect draws a Marquee rectangle (rubberband line)
between the starting point and current pointer. All items completely within the Marquee rectangle are
selected.
Specifying XmTOUCH_ONLY for XmNselectionTechnique enforces the Random-Swipe technique even when BSelect
(or BExtend) is pressed over a blank space. Similarly, specifying XmMARQUEE enforces the Marquee
technique even when BSelect (or BExtend) is pressed over an item; since the item over which the press
occurs is only partially included in the Marquee rectangle, it is not selected. XmMARQUEE_EXTEND_START
and XmMARQUEE_EXTEND_BOTH enforce the Marquee technique and also cause the rectangle to extend
automatically around the first item indicated and, for XmMARQUEE_EXTEND_BOTH, the last item.
In the XmDETAIL layout type, the Range-Swipe and Range-Click techniques are available to indicate a range
of items for selection.
Container uses the XmQTcontainerItem, XmQTscrollFrame, and XmQTspecifyRenderTable traits and holds the
XmQTcontainer and XmQTtransfer traits.
Data Transfer Behavior
Container supports dragging of selected items from the widget. Depending on the value of
XmNprimaryOwnership, Container can also support primary selection.
As a source of data, Container 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 items in
the encoding of the locale. The value for each item transferred, except the last, includes a
trailing separator. Each item value is the XmNlabelString of the item.
COMPOUND_TEXT
The widget transfers the selected items as type COMPOUND_TEXT. The value for each item
transferred, except the last, includes a trailing separator. Each item value is the
XmNlabelString of the item.
DELETE The widget deletes the selected items.
PIXMAP The widget transfers a list of the pixmap IDs of the selected items as type DRAWABLE.
STRING The widget transfers the selected items as type STRING. The value for each item transferred,
except the last, includes a trailing separator. Each item value is the XmNlabelString of the
item.
TEXT If the selected items are fully convertible to the encoding of the locale, the widget transfers
the selected items in the encoding of the locale. Otherwise, the widget transfers the selected
items as type COMPOUND_TEXT. The value for each item transferred, except the last, includes a
trailing separator. Each item value is the XmNlabelString of the item.
_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 and PIXMAP. If the selected
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 items as a compound string in Byte Stream format. The value
for each item transferred, except the last, includes a trailing separator. Each item value is
the XmNlabelString of the item.
UTF8_STRING
The widget transfers the selected items as type UTF8_STRING. The value for each item
transferred, except the last, includes a trailing separator. Each item value is the
XmNlabelString of the item.
_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_DRAG_OFFSET
The widget transfers a list of two 16-bit numbers, of type INTEGER, representing an x and y
offset for an item being dragged. This offset is calculated so that, if the offset were added
to the x and y coordinates at the drop site, and the dragged pixmap placed at that position, it
would correspond to the position the user would expect the pixmap to placed at, based on the
drag icon used at the drop site.
_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, PIXMAP, COMPOUND_TEXT, the encoding of the locale, STRING, TEXT,
BACKGROUND, FOREGROUND, and UTF8_STRING.
As a source of data, Container 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, PIXMAP,
COMPOUND_TEXT, the encoding of the locale, STRING, TEXT, and UTF8_STRING.
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.
As a destination for data, Container supports only the dropping of items being dragged from the same
widget. Subclasses and the XmNdestinationCallback procedures are responsible for any other data
transfers to the widget.
Classes
Container inherits behavior, resources, and traits from the Core, Composite, Constraint, and XmManager
classes.
The class pointer is xmContainerWidgetClass.
The class name is XmContainer.
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 whether 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
Composite(3), Constraint(3), Core(3), XmContainerCopy, XmContainerCopyLink, XmContainerCut, XmContainerGetItemChildren, XmContainerPaste, XmContainerPasteLink, XmContainerRelayout(3), XmContainerReorder(3), XmCreateContainer(3), XmCreateIconGadget(3), XmIconGadget(3), XmManager(3), XmVaCreateContainer(3), and XmVaCreateManagedContainer(3). XmContainer(3)