WIDGET CLASS NAME

Caption

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

The diagram Caption Coloration illustrates the resources that affect the coloration of the Caption widget. 

  Figure 2 Caption Coloration

RESOURCES

  Table 1 Caption Widget Resources Caption Resource Set
                Name            Type       Default  Access XtNancestorSensitive         Boolean          TRUE      G∗
            XtNdepth             int    (parent’s)      GI
  XtNdestroyCallback  XtCallbackList          NULL      SI
             XtNfont   XFontStruct ∗  (OPEN LOOK font)      SI
        XtNfontColor           Pixel        Black∗     SGI
           XtNheight       Dimension  (calculated)     SGI
            XtNlabel          String          NULL     SGI XtNmappedWhenManaged         Boolean          TRUE     SGI
        XtNsensitive         Boolean          TRUE     GI∗
            XtNspace       Dimension             4     SGI
         XtNuserData       XtPointer          NULL     SGI
            XtNwidth       Dimension  (calculated)     SGI
                XtNx        Position             0     SGI
                XtNy        Position             0     SGI XtNalignment

Range of Values:

If XtNposition is OL_LEFT or OL_RIGHT:
OL_TOP/"top"
OL_CENTER/"center"
OL_BOTTOM/"bottom"
If XtNposition is OL_TOP or OL_BOTTOM:
OL_LEFT/"left"
OL_CENTER/"center"
OL_RIGHT/"right"

This specifies how the Label is to be aligned relative to the Child Widget, as described below:

OL_LEFTThe left edge of the Label is aligned with the left edge of the Child Widget. 

OL_TOPThe top edge of the Label is aligned with the top edge of the Child Widget. 

OL_CENTER
The center of the Label is aligned with the center of the Child Widget.

OL_RIGHTThe right edge of the Label is aligned with the right edge of the Child Widget. 

OL_BOTTOM
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(3W).  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. 

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:

OL_LEFT/"left"
OL_RIGHT/"right"
OL_TOP/"top"
OL_BOTTOM/"bottom"

This resource determines on which side of the Child Widget the Label is to be placed.  The value may be one of OL_LEFT, OL_RIGHT, OL_TOP, or OL_BOTTOM 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 the diagram Label and Child Widget Spacing. 

  Figure 3 Label and Child Widget Spacing

Sun Release 4.1  —  Last change: 1/8/90