Caption(3W) UNIX System V Caption(3W)
NAME
Caption - creates a caption or label for any widget
SYNOPSIS
#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <Caption.h>
widget = XtCreateWidget(name, captionWidgetClass, ...);
DESCRIPTION
Caption Components
The Caption composite widget provides a convenient way to label an
arbitrary widget. It has only 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.
Caption Coloration
Figure 2 illustrates the resources that affect the coloration of the
Caption widget.
10/89 Page 1
Caption(3W) UNIX System V Caption(3W)
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.
Display of Keyboard Mnemonic
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 parenthesis and highlighted according to the value
returned by OlQueryMnemonicDisplay().
If truncation is necessary, the mnemonic displayed in parenthesis is
truncated as a unit.
Display of Keyboard Accelerators
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) separated by at least
one space. The acceleratorText is right justified.
If truncation is necessary, the accelerator is truncated as a unit. The
accelerator is truncated before the mnemonic or the label.
Caption Widget Resources
The Caption has the Primitive resource XtNmnemonic.
RESOURCES
Page 2 10/89
Caption(3W) UNIX System V Caption(3W)
________________________________________________________________________________________
| Caption Resource Set |
|_____________________|_____________________|________________|_________________|________|
| Name | Class | Type | Default | Access |
|_____________________|_____________________|________________|_________________|________|
|_____________________|_____________________|________________|_________________|________|
| XtNalignment | XtCAlignment | OlDefine | OL_CENTER | SGI |
|_____________________|_____________________|________________|_________________|________|
| XtNancestorSensitive| XtCSenstitive | Boolean | TRUE | G* |
|_____________________|_____________________|________________|_________________|________|
| XtNconsumeEvent | XtCConsumeEvent | XtCallbackList | NULL | SG |
|_____________________|_____________________|________________|_________________|________|
| XtNdepth | XtCDepth | int | (parent's) | GI |
|_____________________|_____________________|________________|_________________|________|
| XtNdestroyCallback | XtCCallback | XtCallbackList | NULL | SI |
|_____________________|_____________________|________________|_________________|________|
| XtNfont | XtCFont | XFontStruct * | (OPEN LOOK font)| SI |
|_____________________|_____________________|________________|_________________|________|
| XtNfontColor | XtCFontColor | Pixel | Black* | SGI |
|_____________________|_____________________|________________|_________________|________|
| XtNheight | XtCHeight | Dimension | (calculated) | SGI |
|_____________________|_____________________|________________|_________________|________|
| XtNlabel | XtCLabel | String | NULL | SGI |
|_____________________|_____________________|________________|_________________|________|
| XtNmnemonic | XtCMnemonic | unsigned char | \0 | SGI |
|_____________________|_____________________|________________|_________________|________|
| XtNmappedWhenManaged| XtCMappedWhenManaged| Boolean | TRUE | SGI |
|_____________________|_____________________|________________|_________________|________|
| XtNposition | XtCPosition | OlDefine | OL_LEFT | SGI |
|_____________________|_____________________|________________|_________________|________|
| XtNsensitive | XtCSensitive | Boolean | TRUE | GI* |
|_____________________|_____________________|________________|_________________|________|
| XtNspace | XtCSpace | Dimension | 4 | SGI |
|_____________________|_____________________|________________|_________________|________|
| XtNtraversalOn | XtCTraversalOn | Boolean | TRUE | SGI |
|_____________________|_____________________|________________|_________________|________|
| XtNuserData | XtCUserData | XtPointer | NULL | SGI |
|_____________________|_____________________|________________|_________________|________|
| XtNwidth | XtCWidth | Dimension | (calculated) | SGI |
|_____________________|_____________________|________________|_________________|________|
| XtNx | XtCPosition | Position | 0 | SGI |
|_____________________|_____________________|________________|_________________|________|
| XtNy | XtCPosition | Position | 0 | SGI |
|_____________________|_____________________|________________|_________________|________|
XtNalignment
Range of Values:
If XtNposition is OLLEFT or OLRIGHT:
OLTOP/"top"
OLCENTER/"center"
OLBOTTOM/"bottom"
If XtNposition is OLTOP or OLBOTTOM:
10/89 Page 3
Caption(3W) UNIX System V Caption(3W)
OLLEFT/"left"
OLCENTER/"center"
OLRIGHT/"right"
This specifies how the Label is to be aligned relative to the Child
Widget, as described below:
OLLEFT The left edge of the Label is aligned with the left edge of
the Child Widget.
OLTOP The top edge of the Label is aligned with the top edge of the
Child Widget.
OLCENTER The center of the Label is aligned with the center of the
Child Widget.
OLRIGHT The right edge of the Label is aligned with the right edge of
the Child Widget.
OLBOTTOM The bottom edge of the Label is aligned with the bottom edge
of the Child Widget.
XtNfont
Range of Values:
(any valid return from XLoadQueryFont())
Default:
(chosen to match the scale and screen resolution)
This resource identifies the font to be used to display the Label.
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
Range of Values:
(any Pixel value valid for the current display)/(any name from the
rgb.txt file)
This resource specifies the color for the font. If not set, the color
from the XtNforeground resource, if available, is used for the font.
See the note about the interaction of this resource with other color
resources under the description of the XtNbackground resource in Core
Resources, Section 2.
XtNlabel
This resource gives the string to use for the Label. If NULL, the size
of the Caption widget will be identical to the size of the child widget.
Page 4 10/89
Caption(3W) UNIX System V Caption(3W)
Note that 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
Range of Values:
OLLEFT/"left"
OLRIGHT/"right"
OLTOP/"top"
OLBOTTOM/"bottom"
This resource determines on which side of the Child Widget the Label is
to be placed. The value may be one of OLLEFT, OLRIGHT, OLTOP, or
OLBOTTOM to indicate that the Label is to be placed to the left, to the
right, above, or below the Child Widget, respectively.
XtNspace
Range of Values:
0 < XtNspace
This resource gives the separation of the Label from the child widget, in
pixels, as suggested by Figure 3.
Figure 3. Label and Child Widget Spacing
10/89 Page 5