'\"!  tbl | tbl | tbl | tbl | mmdoc
'\"macro stdmacro
.if n .pH g3w.olCheckBox @(#)olCheckBox	40.3 of 1/8/90
.SO BP.HEADER \" This header enables use of .BP macro for PostScript graphics
.ig
Modified by lmh 10/18/89
..
.ds cW CHECKBOX
.ds rW CheckBox
.ds nW CheckBox
.ds wW checkBox
.ds bW \fB\*(rW\fP
.ds iW \fI\*(rW\fP
.ds oS \*(cW
.nr oN 0
.nr X
.if \nX=0 .ds x} ""CHECKBOX WIDGET" 3W "\&"
.if \nX=1 .ds x} ""CHECKBOX WIDGET" 3W
.if \nX=2 .ds x} ""CHECKBOX WIDGET" "" "\&"
.if \nX=3 .ds x} ""CHECKBOX "" "" "\&"
.TH \*(x}
.SH "WIDGET CLASS NAME"
\*(bW
.SH "SYNOPSIS"
.nf
\s-1\f4#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <\*(nW.h>\f1\s+1\f1
.fi
.nf
.P
\s-1\f4widget = XtCreateWidget(\f2name\f4, \*(wWWidgetClass, ...);\f1\s+1
.fi
.SH "DESCRIPTION"
.P
\f3\*(rW Components\f1
.P
The \*(bW 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.
.br
.ne3.5i
.BP PSART/ps.cbox1
.P
.ce
\f3Figure 1.\f1  Check Box Widget
.bp
Figure 2 shows several buttons,
in unselected and selected, as well as normal and dim states.
.br
.ne3.5i
.BP PSART/ps.cbox2
.P
.ce
\f3Figure 2.\f1  Check Boxes
.sp
\f3Typical Use of Check Boxes\f1
.P
Check Boxes may be used alone,
but are usually used in the
\f3Nonexclusives\f1
composite widget, where they are used to implement a 
several-of-many selection.
Making the \*(bW widget a child of a different composite widget will
not produce an error,
but proper behavior is not guaranteed.
.sp
\f3Operating on Check Boxes\f1
.P
A \*(bW widget has two states:
"set" and "not set".
When set,
the Check Mark is visible.
Toggling this state alternates a resource
(\f4XtNset\f1)
between "true" and "false" and starts an action
associated with the check box.
Clicking SELECT on a check box
\f2toggles\f1
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 \*(bW
widget;
the event is passed up to an ancestor widget.
.bp
\f3Bounds on SELECT\f1
.P
Only the Check Box and Check Mark respond to SELECT,
as shown in Figure 3.
.br
.ne3.5i
.BP PSART/ps.cbox3
.P
.ce
\f3Figure 3.\f1  Active Region for a Check Box
.P
.sp
\f3\*(rW Coloration\f1
.P
Figure 4 illustrates the resources that affect the coloration
of the \*(bW widget.
.br
.ne3.5i
.BP PSART/ps.cbox4
.P
.ce
\f3Figure 4.\f1  Check Box Coloration
.sp
.SH "RESOURCES"
.TS H
allbox;
cB s s s s.
\*(bW Resource Set
.T&
l1Bp-2 l1Bp-2 l1Bp-2 l1Bp-2 l1Bp-2.
Name	Class	Type	Default	Access
_
.TH
.T&
l1p-2 l1p-2 l1p-2 l1p-2 l1p-2.
XtNancestorSensitive	XtCAncestorSenstitive	Boolean	TRUE	G*
XtNdepth	XtCDepth	int	(parent's)	GI
XtNdestroyCallback	XtCCallback	XtCallbackList	NULL	SI
XtNdim	XtCDim	Boolean	FALSE	SGI
XtNfont	XtCFont	XFontStruct *	(OPEN LOOK font)	SI
XtNfontColor	XtCFontColor	Pixel	Black*	SGI
XtNforeground	XtCForeground	Pixel	Black	SGI\(dg
XtNheight	XtCHeight	Dimension	(calculated)	SGI
XtNlabel	XtCLabel	String	(class name)	SGI
XtNlabelImage	XtCLabelImage	XImage *	(class name)	SGI
XtNlabelJustify	XtCLabelJustify	OlDefine	OL_LEFT	SGI
XtNlabelTile	XtCLabelTile	Boolean	FALSE	SGI
XtNlabelType	XtCLabelType	int	OL_STRING	SGI
XtNmappedWhenManaged	XtCMappedWhenManaged	Boolean	TRUE	SGI
.TE
.bp
.TS H
allbox;
cB s s s s.
\*(bW Resource Set (cont.)\f1
.T&
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2.
Name	Class	Type	Default	Access
_
.TH
.T&
lw(7P)p-2 lw(7P)p-2 lp-2 lp-2 lp-2.
XtNposition	XtCPosition	OlDefine	OL_LEFT	SGI
XtNrecomputeSize	XtCRecomputeSize	Boolean	TRUE	SGI
XtNselect	XtCCallback	XtCallbackList	NULL	SI
XtNsensitive	XtCSensitive	Boolean	TRUE	GI*
XtNset	XtCSet	Boolean	TRUE	SGI
XtNunselect	XtCCallback	XtCallbackList	NULL	SI
XtNuserData	XtCUserData	XtPointer	NULL	SGI
XtNwidth	XtCWidth	Dimension	(calculated)	SGI
XtNx	XtCPosition	Position	0	SGI
XtNy	XtCPosition	Position	0	SGI
.TE
\f3XtNdim\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4TRUE
FALSE\f1
.in -5
.fi
.PP
If this resource is
\f4TRUE\f1,
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.
.sp
\f3XtNfont\f1
.PP
Range of Values:
.br
.in +5
(any valid return from \f4XLoadQueryFont()\f1)
.in -5
.P
Default:
.br
.in +5
(chosen to match the scale and screen resolution)
.in -5
.PP
This resource identifies the font to be used to display the
Label.
.P
The default value points to a cached font structure;
an application should not expect to get this value with a call to
\f4XtGetValues()\f1
and use it reliably thereafter.
.sp
\f3XtNfontColor\f1
.PP
Range of Values:
.br
.in +5
(any \f4Pixel \f1value valid for the current display)/(any name from the \f4rgb.txt \f1file)
.in -5
.PP
This resource specifies the color for the font.
If not set,
the color from the
\f4XtNforeground\f1
resource,
if available,
is used for the font.
.P
See the note about the interaction of this resource with other
color resources under the description of the
\f4XtNbackground\f1
resource in \f3CORE RESOURCES(3W)\f1.
.bp
\f3XtNforeground\f1
.P
This resource defines the foreground color for the widget.
.P
See the note about the interaction of this resource with other
color resources under the description of the
\f4XtNbackground\f1
resource in \f3CORE RESOURCES(3W)\f1.
.sp
\f3XtNlabel\f1
.P
This resource is a pointer to the text for the Label.
This resource is ignored if the
\f4XtNlabelType\f1
resource has the value
\f4OL_IMAGE\f1.
.sp
\f3XtNlabelImage\f1
.P
This resource is a pointer to the image for the Label of the
\*(bW widget.
This resource is ignored unless the
\f4XtNlabelType\f1
resource has the value
\f4OL_IMAGE\f1.
.P
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
\f4XtNlabelJustify\f1
resource.
If the image is larger than the space available for it,
it is clipped so that it does not stray outside the space.
.sp
\f3XtNlabelJustify\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4OL_LEFT/"left"
OL_RIGHT/"right"\f1
.in -5
.fi
.PP
This resource dictates whether the Label should be left-
or right-justified within the space left before or after the
Check Box,
if the
\f4XtNwidth\f1
resource gives more space than needed.
.sp
\f3XtNlabelTile\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4TRUE
FALSE\f1
.in -5
.fi
.PP
This resource augments the
\f4XtNlabelImage/XtNlabelPixmap\f1 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
\f4TRUE\f1;
otherwise, the label is placed as described by the
\f4XtNlabelImage\f1
resource.
.P
The
\f4XtNlabelTile\f1
resource is ignored for text labels.
.bp
\f3XtNlabelType\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4OL_STRING/"string"
OL_IMAGE/"image"\f1
.in -5
.fi
.PP
This resource identifies the form that the Label takes.
It can have the value
\f4OL_STRING\f1
or
\f4OL_IMAGE\f1
for text or image,
respectively.
.sp
\f3XtNposition\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4OL_LEFT/"left"
OL_RIGHT/"right"\f1
.in -5
.fi
.PP
This resource determines on which side of the Check Box the
Label is to be placed.
The value may be one of
\f4OL_LEFT\f1
or
\f4OL_RIGHT\f1
to indicate that the Label is to be placed to the left or to
the right of the Check Box, respectively.
.sp
\f3XtNrecomputeSize\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4TRUE
FALSE\f1
.in -5
.fi
.PP
This resource indicates whether the \*(bW widget should
calculate its size and automatically set the
\f4XtNheight\f1
and
\f4XtNwidth\f1
resources.
If set to
\f4TRUE\f1,
the \*(bW widget will do normal size calculations that may
cause its geometry to change.
If set to
\f4FALSE\f1,
the \*(bW widget will leave its size alone;
this may cause truncation of the visible image being shown by
the \*(bW 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
\f4XtNlabelJustify\f1
resource.
.sp 0.6
\f3XtNselect\f1
.P
This is the list of callbacks invoked when the widget is
selected.
.sp 0.6
\f3XtNset\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4TRUE
FALSE\f1
.in -5
.fi
.PP
This resource reflects the current state of the check box.
The Check Mark is present if
\f4XtNset\f1
is
\f4TRUE\f1
and is absent otherwise.
.sp 0.6
\f3XtNunselect\f1
.P
This is the list of callbacks invoked when a \*(bW widget
is toggled into the ``unset'' mode by the end user to make
\f4XtNset\f1
be
\f4FALSE\f1.
Note that simply setting
\f4XtNset\f1
to
\f4FALSE\f1
with a call to
\f4XtSetValues()\f1
does not issue the
\f4XtNunselect\f1
callbacks.
.bp
\f3XtNdim and XtNset Interaction\f1
.P
The
\f4XtNdim\f1
and
\f4XtNset\f1
resources can be set independently,
as the state table in Figure 5 shows.
.sp
.ne3.5i
.BP PSART/ps.cbox5
.P
.ce
\f3Figure 5.\f1  Check Box Appearance with Set/Default/Dim
.sp
\f3Label and Check Box Appearance\f1
.P
The
\f4XtNwidth\f1,
\f4XtNheight\f1,
\f4XtNrecomputeSize\f1,
and
\f4XtNlabelJustify\f1
resources interact to produce a truncated, clipped, centered,
left-justified, or
right-justified Label and Check Box as shown in Figure 6.
.bp
.ne3.5i
.BP PSART/ps.cbox6
.P
.ce
\f3Figure 6.\f1  Label and Check Box Appearance
.sp
When the label is left-justified, right-justified, or centered
the extra space is filled with the background color of the
\*(bW widget's parent,
as determined by the
\f4XtNbackground\f1
and
\f4XtNbackgroundPixmap\f1
resources of the parent.
.sp
See also the
\f4XtNlabelTile\f1
resource for how it affects the appearance of a label.
