NAME

Caption − caption widget class

SYNOPSIS

#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xol/OpenLook.h>
#include <Xol/Caption.h>
 . . .
Widget my_caption, my_parent;
String my_name;
ArgList args;
Cardinal num_args;

my_caption =  XtCreate( my_name, captionWidgetClass,

my_parent, args, num_args);

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

Caption              Resource       Set
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
XtNfontColor         Pixel          XtDefaultForeground SGI
XtNheight            Dimension      (calculated)        SGI
XtNlabel             String         NULL                SGI
XtNmnemonic          unsigned       char                NULL
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 timeO = other access
† see resources(3w)

XtNalignment

class:XtCAlignment type:OlDefine default:OL_CENTERaccess:SGI

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:XtCFont type:XFontStruct∗ default:(OPEN LOOK font)access:SI

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

Values: any valid return from XLoadQueryFont()

The default is chosen to match the scale and screen resolution.  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:XtCFontColor type:Pixel default:XtDefaultForegroundaccess:SGI

Action: specifies the font color. 

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

XtNlabel

class:XtCLabel type:String default:NULLaccess:SGI

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:XtCPosition type:OlDefine default:OL_LEFTaccess:SGI

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:XtCRecomputeSize type:Boolean default:TRUEaccess:SGI

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:XtCSpace type:Dimension default:4access:SGI

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  —  Last change: 19 July 91  —  Last change: 19 July 91