WIDGET CLASS NAME

CheckBox

SYNOPSIS

#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <CheckBox.h>

widget = XtCreateWidget(name, checkBoxWidgetClass, ...);

DESCRIPTION

CheckBox Components

The CheckBox widget implements one of the OPEN LOOK button widgets.  It consists of a Label next to a Check Box; the Check Box will have a Check Mark, if selected. 

The diagram Check Boxes shows several buttons, in unselected and selected, as well as normal and dim states. 

Typical Use of Check Boxes

Check Boxes may be used alone, but are usually used in the Nonexclusives composite widget, where they are used to implement a several-of-many selection.  Making the CheckBox widget a child of a different composite widget will not produce an error, but proper behavior is not guaranteed.  Operating on Check Boxes

A CheckBox widget has two states: "set" and "not set".  When set, the Check Mark is visible.  Toggling this state alternates a resource (XtNset) between "true" and "false" and starts an action associated with the check box.  Clicking SELECT on a check box toggles the state associated with it.  Pressing SELECT, or moving the pointer into the check box while SELECT is pressed, adds or removes the Check Mark to reflect the state the check box would be in if SELECT was released.  Releasing SELECT toggles the state.  Moving the pointer off the check box before releasing SELECT restores the original Check Box, but does not toggle the state.  Clicking or pressing MENU does not do anything in the CheckBox widget; the event is passed up to an ancestor widget.  Bounds on SELECT

Only the Check Box and Check Mark respond to SELECT, as shown in the diagram Active Region for a Check Box. 

CheckBox Coloration

The diagram Check Box Coloration illustrates the resources that affect the coloration of the CheckBox widget. 

RESOURCES

CheckBox Resource Set
                Name            Type       Default   Access XtNancestorSensitive         Boolean          TRUE       G∗
            XtNdepth             int    (parent’s)       GI
  XtNdestroyCallback  XtCallbackList          NULL       SI
              XtNdim         Boolean         FALSE      SGI
             XtNfont   XFontStruct ∗  (OPEN LOOK font)       SI
        XtNfontColor           Pixel        Black∗      SGI
       XtNforeground           Pixel         Black  SGI†
           XtNheight       Dimension  (calculated)      SGI
            XtNlabel          String  (class name)      SGI
       XtNlabelImage        XImage ∗  (class name)      SGI
        XtNlabelTile         Boolean         FALSE      SGI XtNmappedWhenManaged         Boolean          TRUE      SGI
    XtNrecomputeSize         Boolean          TRUE      SGI
           XtNselect  XtCallbackList          NULL       SI
        XtNsensitive         Boolean          TRUE      GI∗
              XtNset         Boolean          TRUE      SGI
         XtNunselect  XtCallbackList          NULL       SI
         XtNuserData       XtPointer          NULL      SGI
            XtNwidth       Dimension  (calculated)      SGI
                XtNx        Position             0      SGI
                XtNy        Position             0      SGI
XtNdim

Range of Values:

TRUE
FALSE

If this resource is TRUE, the check box border is dimmed to show that the check box represents the state of one or more of several objects that, as a group, are in different states.  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).  XtNforeground

This resource defines the foreground color for the widget. 

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 is a pointer to the text for the Label.  This resource is ignored if the XtNlabelType resource has the value OL_IMAGE.  XtNlabelImage

This resource is a pointer to the image for the Label of the CheckBox widget.  This resource is ignored unless the XtNlabelType resource has the value OL_IMAGE. 

If the image is smaller than the space available for it next to the Check Box, it is centered vertically and either centered or left-justified horizontally depending on the value of the XtNlabelJustify resource.  If the image is larger than the space available for it, it is clipped so that it does not stray outside the space.  XtNlabelJustify

Range of Values:

OL_LEFT/"left"
OL_RIGHT/"right"

This resource dictates whether the Label should be left- or right-justified within the space left before or after the Check Box, if the XtNwidth resource gives more space than needed.  XtNlabelTile

Range of Values:

TRUE
FALSE

This resource augments the XtNlabelImage/XtNlabelPixmap resource to allow tiling of the sub-object’s background.  For an image/pixmap that is smaller than the sub-object’s background, the label area is tiled with the image/pixmap to fill the sub-object’s background if this resource is TRUE; otherwise, the label is placed as described by the XtNlabelImage resource. 

The XtNlabelTile resource is ignored for text labels.  XtNlabelType

Range of Values:

OL_STRING/"string"
OL_IMAGE/"image"

This resource identifies the form that the Label takes.  It can have the value OL_STRING or OL_IMAGE for text or image, respectively.  XtNposition

Range of Values:

OL_LEFT/"left"
OL_RIGHT/"right"

This resource determines on which side of the Check Box the Label is to be placed.  The value may be one of OL_LEFT or OL_RIGHT to indicate that the Label is to be placed to the left or to the right of the Check Box, respectively. 
XtNrecomputeSize

Range of Values:

TRUE
FALSE

This resource indicates whether the CheckBox widget should calculate its size and automatically set the XtNheight and XtNwidth resources.  If set to TRUE, the CheckBox widget will do normal size calculations that may cause its geometry to change.  If set to FALSE, the CheckBox widget will leave its size alone; this may cause truncation of the visible image being shown by the CheckBox widget if the fixed size is too small, or may cause padding if the fixed size is too large.  The location of the padding is determined by the XtNlabelJustify resource.  XtNselect

This is the list of callbacks invoked when the widget is selected.  XtNset

Range of Values:

TRUE
FALSE

This resource reflects the current state of the check box.  The Check Mark is present if XtNset is TRUE and is absent otherwise.  XtNunselect

This is the list of callbacks invoked when a CheckBox widget is toggled into the “unset” mode by the end user to make XtNset be FALSE.  Note that simply setting XtNset to FALSE with a call to XtSetValues() does not issue the XtNunselect callbacks.  XtNdim and XtNset Interaction

The XtNdim and XtNset resources can be set independently, as the state table in the diagram Check Box Appearance with Set/Default/Dim shows. 

Label and Check Box Appearance

The XtNwidth, XtNheight, XtNrecomputeSize, and XtNlabelJustify resources interact to produce a truncated, clipped, centered, left-justified, or right-justified Label and Check Box as shown in the diagram Label and Check Box Appearance. 

When the label is left-justified, right-justified, or centered the extra space is filled with the background color of the CheckBox widget’s parent, as determined by the XtNbackground and XtNbackgroundPixmap resources of the parent.  See also the XtNlabelTile resource for how it affects the appearance of a label. 

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