XbaeCaption - The Bellcore Application Environment (BAE) XbaeCaption widget class.

Author

AndrewWason, Bellcore, Piscataway NJ; author
       (aw@bae.bellcore.com)

       AndrewLister
       (lister@db.com)

Description

XbaeCaption  is a simple manager used to associate a label with its single child. The label may be either
       an XmString or a Pixmap and can be displayed in any one of twelve positions around the edge of the child.
       XbaeCaption performs geometry management so that its size always matches its child's size plus  the  size
       of  the label and label offset. By using XbaeCaption with an XmFrame child, groups of related widgets can
       be labeled in a visually appealing manner.  XbaeCaption  is  also  useful  for  associating  labels  with
       individual XmTextFields.

   ClassesXbaeCaption  inherits  behavior  and  resources from the Core, Composite, Constraint and XmManager widget
       classes.
       The class pointer is xbaeCaptionWidgetClass.
       The class name is XbaeCaption.

   NewResources
       The following table lists the new resources defined by XbaeCaption.   The  codes  in  the  Access  column
       indicate  whether the given resource can be set at creation time (C), or set by using XtSetValues (S), or
       retrieved by using XtGetValues (G).

       ┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
       │                                        XbaeCaption Resource Set                                        │
       ├────────────────────────┬─────────────────────┬───────────────────────┬────────────────────────┬────────┤
       │ Name                   │ Class               │ Type                  │ Default                │ Access │
       ├────────────────────────┼─────────────────────┼───────────────────────┼────────────────────────┼────────┤
       │ XmNfontList            │ XmCFontList         │ FontList              │ dynamic                │ CSG    │
       ├────────────────────────┼─────────────────────┼───────────────────────┼────────────────────────┼────────┤
       │ XmNlabelAlignment      │ XmCLabelAlignment   │ XbaeLabelAlignment    │ XbaeAlignmentCenter    │ CSG    │
       ├────────────────────────┼─────────────────────┼───────────────────────┼────────────────────────┼────────┤
       │ XmNlabelOffset         │ XmCLabelOffset      │ Int                   │ 0                      │ CSG    │
       ├────────────────────────┼─────────────────────┼───────────────────────┼────────────────────────┼────────┤
       │ XmNlabelPixmap         │ XmCLabelPixmap      │ PrimForegroundPixmap  │ XmUNSPECIFIED_PIXMAP   │ CSG    │
       ├────────────────────────┼─────────────────────┼───────────────────────┼────────────────────────┼────────┤
       │ XmNlabelPosition       │ XmCLabelPosition    │ XbaeLabelPosition     │ XbaePositionLeft       │ CSG    │
       ├────────────────────────┼─────────────────────┼───────────────────────┼────────────────────────┼────────┤
       │ XmNlabelString         │ XmCXmString         │ XmString              │ widget name            │ CSG    │
       ├────────────────────────┼─────────────────────┼───────────────────────┼────────────────────────┼────────┤
       │ XmNlabelTextAlignment  │ XmCAlignment        │ Alignment             │ XmALIGNMENT_CENTER     │ CSG    │
       ├────────────────────────┼─────────────────────┼───────────────────────┼────────────────────────┼────────┤
       │ XmNlabelType           │ XmCLabelType        │ LabelType             │ XmString               │ CSG    │
       └────────────────────────┴─────────────────────┴───────────────────────┴────────────────────────┴────────┘

       XmNfontList
            Specifies the font of the text used in the caption label. If this value is NULL  at  initialization,
            it  is  initialized  by  looking  up  the  parent  hierarchy of the widget for an ancestor that is a
            subclass of the XmBulletinBoard, VendorShell or XmMenuShell widget class. If  such  an  ancestor  is
            found,  the  font  list  is  initialized to the appropriate default font list of the ancestor widget
            XmNdefaultFontListforVendorShell  and  XmMenuShell,  XmNlabelFontList  or  XmNbuttonFontList  for
            XmBulletinBoard.   Refer  to  XmFontList(3X) for more information on the creation and structure of a
            font list. This resource is copied.

       XmNlabelAlignment
            Specifies the alignment of the caption label along the side of the caption child.  Must  be  one  of
            the    enumerated    XbaeLabelAlignment    types:    XbaeAlignmentTopOrLeft,    XbaeAlignmentCenter,
            XbaeAlignmentBottomOrRight.

       XmNlabelOffset
            Specifies the offset, in pixels, of the caption label from the  caption  child.  If  the  offset  is
            negative, then the caption label will overlap the caption child by that many pixels.

       XmNlabelPixmap
            Specifies the caption label pixmap when XmNlabelType is XmPIXMAP.

       XmNlabelPosition
            Specifies on which side of the caption child the caption label should be placed.  Must be one of the
            enumerated    XbaeLabelPosition   types:   XbaePositionLeft,   XbaePositionRight,   XbaePositionTop,
            XbaePositionBottom.

       XmNlabelString
            Specifies the compound string when the XmNlabelTypeisXmSTRING.  If  this  value  is  NULL,  it  is
            initialized  by  converting  the  name of the widget to a compound string. Refer to XmString(3X) for
            more information on the creation and structure of compound strings.

       XmNlabelTextAlignment
            Specifies the text alignment for the caption label. This resource is  only  useful  for  multi  line
            caption  labels. Valid values are: XmALIGNMENT_BEGINNING left alignment causes the left sides of the
            lines of text to be vertically aligned.  XmALIGNMENT_CENTER center alignment causes the  centers  of
            the  lines of text to be vertically aligned.  XmALIGNMENT_END right alignment causes the right sides
            of the lines of text to be vertically aligned.

       XmNlabelType
            Specifies the caption label type. Valid values are: XmSTRING - the caption label  will  display  the
            XmNlabelString.  XmPIXMAP - the caption label will display the XmNlabelPixmap.

   InheritedResources
       The  following  table  lists  the  resources which XbaeCaption inherits from it's superclasses XmManager,
       CompositeandCore.  For a complete description  of  each  resource,  refer  to  the  man  page  for  that
       superclass.   The codes in the "Access" column indicate whether the given resource can be set at creation
       time (C), or set by using XtSetValues (S), or retrieved by using XtGetValues (G).

       ┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
       │                                         XmManager Resource Set                                          │
       ├────────────────────────┬────────────────────────┬─────────────────────┬───────────────────────┬─────────┤
       │ Name                   │ Class                  │ Type                │ Default               │  Access │
       ├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
       │ XmNbottomShadowColor   │ XmCBottomShadowColor   │ Pixel               │ dynamic               │  CSG    │
       ├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
       │ XmNbottomShadowPixmap  │ XmCBottomShadowPixmap  │ Pixmap              │ XmUNSPECIFIED_PIXMAP  │  CSG    │
       ├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
       │ XmNforeground          │ XmCForeground          │ Pixel               │ dynamic               │  CSG    │
       ├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
       │ XmNhelpCallback        │ XmCCallback            │ Callback            │ NULL                  │  CSG    │
       ├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
       │ XmNhighlightColor      │ XmCHighlightColor      │ Pixel               │ dynamic               │  CSG    │
       ├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
       │ XmNhighlightPixmap     │ XmCHighlightPixmap     │ Pixmap              │ dynamic               │  CSG    │
       ├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
       │ XmNnavigationType      │ XmCNavigationType      │ XmNavigationType    │ XmTAB_GROUP           │  CSG    │
       ├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
       │ XmNshadowThickness     │ XmCShadowThickness     │ Dimension           │ 2                     │  CSG    │
       ├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
       │ XmNstringDirection     │ XmCStringDirection     │ XmStringDirection   │ dynamic               │  CG     │
       ├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
       │ XmNtopShadowColor      │ XmCTopShadowColor      │ Pixel               │ dynamic               │  CSG    │
       ├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
       │ XmNtopShadowPixmap     │ XmCTopShadowPixmap     │ Pixmap              │ dynamic               │  CSG    │
       ├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
       │ XmNtraversalOn         │ XmCTraversalOn         │ Boolean             │ True                  │  CSG    │
       ├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
       │ XmNunitType            │ XmCUnitType            │ UnsignedChar        │ dynamic               │  CSG    │
       ├────────────────────────┼────────────────────────┼─────────────────────┼───────────────────────┼─────────┤
       │ XmNuserData            │ XmCUserData            │ Pointer             │ NULL                  │  CSG    │
       └────────────────────────┴────────────────────────┴─────────────────────┴───────────────────────┴─────────┘

       ┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐
       │                                       Composite Resource Set                                        │
       ├───────────────────────┬──────────────────────────┬────────────────────┬────────────────┬────────────┤
       │ Name                  │    Class                 │    Type            │    Default     │     Access │
       ├───────────────────────┼──────────────────────────┼────────────────────┼────────────────┼────────────┤
       │ XmNchildren           │    XmCReadOnly           │    WidgetList      │    private     │     G      │
       ├───────────────────────┼──────────────────────────┼────────────────────┼────────────────┼────────────┤
       │ XmNinsertPosition     │    XmCInsertPosition     │    Function        │    NULL        │     CSG    │
       ├───────────────────────┼──────────────────────────┼────────────────────┼────────────────┼────────────┤
       │ XmNnumChildren        │    XmCReadOnly           │    Cardinal        │    4           │     G      │
       └───────────────────────┴──────────────────────────┴────────────────────┴────────────────┴────────────┘

       ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────┐
       │                                             Core Resource Set                                             │
       ├──────────────────────────────┬─────────────────────────────┬────────────────┬─────────────────────┬───────┤
       │ Name                         │Class                        │Type            │Default              │Access │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNaccelerators              │XmCAccelerators              │AcceleratorTable│NULL                 │CSG    │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNancestorSensitive         │XmCSensitive                 │Boolean         │dynamic              │CSG    │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNbackground                │XmCBackground                │Pixel           │dynamic              │G      │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNbackgroundPixmap          │XmCPixmap                    │Pixmap          │XmUNSPECIFIED_PIXMAP │CSG    │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNborderColor               │XmCBorderColor               │Pixel           │XtDefaultForeground  │CSG    │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNborderPixmap              │XmCPixmap                    │Pixmap          │XmUNSPECIFIED_PIXMAP │CSG    │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNborderWidth               │XmCBorderWidth               │Dimension       │0                    │CSG    │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNcolormap                  │XmCColormap                  │Colormap        │dynamic              │CG     │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNdepth                     │XmCDepth                     │Int             │dynamic              │CG     │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNdestroyCallback           │XmCCallback                  │Callback        │NULL                 │CSG    │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNheight                    │XmCHeight                    │Dimension       │dynamic              │CSG    │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNinitialResourcesPersistent│XmCInitialResourcesPersistent│Boolean         │True                 │CG     │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNmappedWhenManaged         │XmCMappedWhenManaged         │Boolean         │True                 │CSG    │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNscreen                    │XmCScreen                    │Screen          │dynamic              │CG     │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNsensitive                 │XmCSensitive                 │Boolean         │True                 │CSG    │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNtranslations              │XmCTranslations              │TranslationTable│internal             │CSG    │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNwidth                     │XmCWidth                     │Dimension       │dynamic              │CSG    │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNx                         │XmCPosition                  │Position        │0                    │CSG    │
       ├──────────────────────────────┼─────────────────────────────┼────────────────┼─────────────────────┼───────┤
       │ XmNy                         │XmCPosition                  │Position        │0                    │CSG    │
       └──────────────────────────────┴─────────────────────────────┴────────────────┴─────────────────────┴───────┘

   TranslationsXbaeCaptioninheritstranslationsfromXmManager.

   TypeConverters
       In addition to the standard type converters  registered  by  Xt  and  Motif,  XbaeCaption  registers  the
       following additional type converters:

       CvtStringToLabelAlignment()
              Converts  a  String to the enumerated XbaeLabelAlignment type. The Strings TopOrLeft, Top and Left
              are converted to XbaeAlignmentTopOrLeft.  The String Center is converted  to  XbaeAlignmentCenter.
              The  Strings  BottomOrRight,  Bottom  and Right are converted to XbaeAlignmentBottomOrRight.  This
              converter allows the XmNlabelAlignment resource to be specified in a resource file. The  converter
              is case insensitive.

       CvtStringToLabelPosition()
              Converts  a  String  to  the  enumerated  XbaeLabelPosition  type. The String Left is converted to
              XbaePositionLeft.  The String  Right  is  converted  to  XbaePositionRight.   The  String  TopisconvertedtoXbaePositionTop.   The  String  BottomisconvertedtoXbaePositionBottom.  This
              converter allows the XmNlabelPosition resource to be specified in a resource file.  The  converter
              is case insensitive.

   PublicFunctions
       The following external entry points to XbaeCaption class methods are defined:

       XbaeCreateCaption()

              Widget XbaeCreateCaption()
                   Widget     parent;
                   String     name;
                   ArgList    arglist;
                   Cardinal   argcount;parent    Specifies the parent widget ID.

              name      Specifies the name of the created widget

              arglist   Specifies the argument list

              argcount  Specifies the number of attribute/value pairs in the argument list (arglist)

              XbaeCreateCaption() creates an instance of an XbaeCaption widget and returns the associated widget
              ID.

   VirtualBindings
       The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and
       keys, see VirtualBindings(3X).

Name

       XbaeCaption - The Bellcore Application Environment (BAE) XbaeCaption widget class.

Notice Of Limitation

Bellcore, previous and current maintainers of the Xbae widgets (collectively 'authors') provide this
information solely to professionals who have the appropriate degree of experience to understand and
interpret its contents in accordance with generally accepted engineering or other professional standards
and applicable regulations. No recommendations as to products or vendors is made or should be implied.

While the information contained herein has been prepared from sources deemed to be reliable, the authors
reserve the right to revise the information without notice, but have no obligation to do so. Unless the
recipient has been expressly granted a license by Bellcore under separate applicable written agreement
with Bellcore, no license, expressed or implied, is granted under any patents, copyrights or other
intellectual property rights. Use of the information is at your discretion and shall not be deemed an
inducement by Bellcore to infringe any existing or later-issued patent, copyrights or other intellectual
property right.

THE AUTHORS MAKE NO REPRESENTATIONS AND EXTENDS NO WARRANTIES, EXPRESS OR IMPLIED, WITH RESPECT TO THE
INFORMATION, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ANY
PARTICULAR PURPOSE, AND THE WARRANTY AGAINST INFRINGEMENT OF PATENTS OR OTHER INTELLECTUAL PROPERTY
RIGHTS. THE INFORMATION IS PROVIDED ``AS IS'', AND IN NO EVENT SHALL THE AUTHORS OR ANY OF ITS AFFILIATES
BE LIABLE FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES
RELATING TO THE INFORMATION.

The above no warranty extends to all additions and contributions. No contributor shall be held liable;
this work is provided ``as is''. If this is a problem for you, then don't use this software.

xbae 4.60.4 XbaeCaption(3)

Release

       This document describes XbaeCaption from Xbae Version 4.9.

Synopsis

       #include <Xbae/Caption.h>