NAME

Caption − caption widget class

SYNOPSIS

#include <Xol/OpenLook.h>
#include <Xol/Caption.h>
 . . .

ANCESTRY

Core-Composite-Constraint-Manager-Caption

DESCRIPTION

Components

The Caption composite widget provides a convenient way to label an arbitrary widget.  It has two parts: the label and the child widget. 

  Figure 1 Caption Widget

Layout Control

The application can determine how the label is placed next to the child widget (by specifying that it goes above, below, to the left, or to the right), and by specifying how far away the label is to be placed. 

Child Constraints

The Caption composite allows at most one child; attempts to add more than one are refused with a warning.  If the Caption widget is mapped without a child widget, or if the child widget is not managed, only the label is shown. 

Coloration

of the Caption widget. 

  Figure 2 Caption Coloration

Keyboard Traversal

The Caption is a special Manager widget that can be used to display the mnemonic for its single child.  However, the label used as a caption to the child is not accessible via keyboard traversal.  The Caption has the XtNmnemonic resources which should be set to the child widget’s corresponding values.  The return of the OlQueryMnemonicDisplay() on the Caption is used to determine if the Caption should display the mnemonic for the child. 

The action of a mnemonic on a Caption widget is used for traversal only since clicking the SELECT button on a caption does not have an affect. 

Keyboard Mnemonic Display

The Caption widget displays the mnemonic for its child as part of its label.  If the mnemonic character is in the label, then that character is highlighted according to the value returned by OlQueryMnemonicDisplay().  If the mnemonic character is not in the label, it is displayed to the right of the label in parentheses and highlighted according to the value returned by OlQueryMnemonicDisplay(). 

If truncation is necessary, the mnemonic displayed in parentheses is truncated as a unit. 

Keyboard Accelerators Display

The Caption widget displays the keyboard accelerator for its child as part of its label.  The string in the XtNacceleratorText resource is displayed to the right of the label (or mnemonic), right justified, and separated by at least one space. 

If truncation is necessary, the accelerator is truncated as a unit.  The accelerator is truncated before the mnemonic or the label. 

RESOURCES

  Table 1 Caption Widget Resources

Name                      Type              Default           Access
XtNalignment            OlDefine         OL_CENTER               SGI
XtNancestorSensitive-   Boolean          TRUE                    GO
XtNconsumeEvent-        XtCallbackList   NULL                    SG
XtNdepth-               int              (parent’s)              GI
XtNdestroyCallback-     XtCallbackList   NULL                    SI
XtNfont                 XFontStruct∗     (OPEN LOOK bold font)   SI
XtNfontColor            Pixel            XtDefaultForeground     SGI
XtNheight-              Dimension        (calculated)            SGI
XtNlabel                String           NULL                    SGI
XtNmnemonic-            unsigned char    NULL                    SGI
XtNmappedWhenManaged-   Boolean          TRUE                    SGI
XtNposition             OlDefine         OL_LEFT                 SGI
XtNrecomputeSize        Boolean          TRUE                    SGI
XtNsensitive-           Boolean          TRUE                    GIO
XtNspace                Dimension        4                       SGI
XtNtraversalOn-         Boolean          TRUE                    SGI
XtNuserData-            XtPointer        NULL                    SGI
XtNwidth-               Dimension        (calculated)            SGI
XtNx-                   Position         0                       SGI
XtNy-                   Position         0                       SGI

Access:   S = XtSetValues   G = XtGetValues
            I = init time   O = other access
† see resources(3W)

XtNalignment

 class:XtCAlignmenttype:OlDefinedefault:OL_CENTEROL_CENTER’u’access:SGISGI’u’

Action: specifies how the label is to be aligned relative to the child widget. 

Values: OL_LEFT/left – left edge of label aligned with left edge of child widget.  OL_TOP/top – top edge of label with top edge of child widget.  OL_CENTER/center – center of label with center of child widget.  OL_RIGHT/right – right edge of label with right edge of child widget.  OL_BOTTOM/bottom – bottom edge of label with bottom edge of child widget. 

Note the interaction between this resource and the XtNposition resource.  Not all possible combinations of the two resources make sense.  The ones that do are as follows. 

If XtNposition is

OL_LEFT or OL_RIGHT, then the alignment can be

OL_TOP/top, OL_CENTER/center, or OL_BOTTOM/bottom.

OL_TOP or OL_BOTTOM, then the alignment can be

OL_LEFT/left, OL_CENTER/center, or OL_RIGHT/right. 

XtNfont

 class:XtCFonttype:XFontStruct∗default:(OPEN LOOK bold font)(OPEN LOOK bold font)’u’access:SISI’u’

Action: identifies the font to be used to display the label. 

Values: any valid return from XLoadQueryFont()

The default is the bold version of the font specified by the XtNolDefaultFont application resource.  The default value points to a cached font structure; an application should not expect to get this value with a call to XtGetValues() and use it reliably thereafter. 

XtNfontColor

 class:XtCFontColortype:Pixeldefault:XtDefaultForegroundXtDefaultForeground’u’access:SGISGI’u’

Action: specifies the font color. 

Values: any pixel value valid for the current display, or
any name from the rgb.txt file

XtNlabel

 class:XtCLabeltype:Stringdefault:NULLNULL’u’access:SGISGI’u’

Action: gives the string to use for the label. 

Values: string – the string is the label. NULL – the size of the Caption widget will be identical to the size of the child widget. 

Note: the label is displayed as given; no punctuation (such as a colon) is added.  Control characters (other than spaces) are ignored without warning.  For example, embedded newlines do not cause line breaks. 

XtNposition

 class:XtCPositiontype:OlDefinedefault:OL_LEFTOL_LEFT’u’access:SGISGI’u’

Action: determines on which side of the child widget the label is to be placed. 

Values: OL_LEFT/left, OL_RIGHT/right, OL_TOP/top, or OL_BOTTOM/bottom

XtNrecomputeSize

 class:XtCRecomputeSizetype:Booleandefault:TRUETRUE’u’access:SGISGI’u’

Action: determines whether Caption resizes itself. 

Values: TRUE – the widget resizes itself to accomodate changes in its children’s sizes due to changed factors such as fonts or labels. 
FALSE – the widget does not resizes itself

XtNspace

 class:XtCSpacetype:Dimensiondefault:44’u’access:SGISGI’u’

Action:  gives the separation of the label from the child widget, in pixels. 

Values: 0 ≤ XtNspace

The separation of the label and child widget is shown in the following figure. 

  Figure 3 Label and Child Widget Spacing
 
 
 
 

Version 3.0.1  —  Last change: June 92