Ubuntu Manpage: XmContainer — The Container widget class "XmContainer" "container" "Container"

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).

┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
--

       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)

NAME

SYNOPSIS

DESCRIPTION

RELATED