Provided by: libmotif-dev_2.3.8-3.1build1_amd64 bug

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_ICONXmSMALL_ICONXmANY_ICON

       Three different layout types are supported by the Container.  They are  specified  by  the
       XmNlayoutType resource:

          •  XmSPATIALXmOUTLINEXmDETAIL

       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)