'\"!  tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | eqn | tbl | tbl | tbl | tbl | tbl | tbl | tbl | mmdoc
'\"macro stdmacro
.if n .pH g3w.olRectButton @(#)olRectButton	40.3 of 1/8/90
.SO BP.HEADER \" This header enables use of .BP macro for PostScript graphics
.ig
Modified 10/18/89 by lmh
..
.ds cW RECTBUTTON
.ds rW RectButton
.ds nW RectButton
.ds wW rectButton
.ds bW \fB\*(rW\fP
.ds iW \fI\*(rW\fP
.ds oS \*(cW
.nr oN 0
.nr X
.if \nX=0 .ds x} ""RECTBUTTON WIDGET" 3W "\&"
.if \nX=1 .ds x} ""RECTBUTTON WIDGET" 3W
.if \nX=2 .ds x} ""RECTBUTTON WIDGET" "" "\&"
.if \nX=3 .ds x} ""RECTBUTTON "" "" "\&"
.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
.P
.nf
\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 surrounded by a rectangular Border.
The Border can change to reflect that the button may be a
default of several buttons (double border),
or represents a current state of an object (thick border),
or represents a current state of one of several objects with
different states (dimmed border).
.P
Figure 1 shows several buttons,
in normal, default, and current states (two versions).
.br
.ne3.5i
.BP PSART/ps.nonex1
.P
.ce
\f3Figure 1.\f1  Rectangular Buttons
.bp
\f3Use of Rectangular Buttons\f1
.P
Rectangular buttons are not used alone
but in one of the
\f3Exclusives\f1
or
\f3Nonexclusives\f1
composite widgets for implementing a one-of-many or
several-of-many selection.
Making this widget a child of a different composite widget will
not produce an error message,
but proper behavior is not guaranteed.
.sp
\f3Toggling the State\f1
.P
A \*(bW widget has two states:
"set" and "not set".
(When set,
its border is thickened.)
Toggling this state alternates a resource
(\f4XtNset\f1)
between "true" and "false" and starts an action
associated with the button.
The \*(bW widget is typically toggled by the user using SELECT
or MENU,
except that it is possible to disable user toggling of a button
that is already set.
.sp
\f3Work in Exclusives/Nonexclusives Only\f1
.P
The \*(bW widget needs to be a child of a proper composite
widget to work correctly.
Only the
\f3Exclusives\f1
and
\f3Nonexclusives\f1
composite widgets have the necessary capabilities.
.P
The descriptions below of using the \*(bW widget in a menu
should be read to imply that the \*(bW widget is enclosed in an
\f3Exclusives\f1
or
\f3Nonexclusives\f1
widget,
which, in turn, is enclosed in a menu.
.sp
\f3Rectangular Buttons in a Pop-up Menu\f1
.P
Entering a rectangular button while MENU is depressed 
changes the appearance of the button from unset to set state 
or vice versa,
to reflect the state the button would be in if MENU were
released.
Releasing MENU toggles the state associated with the button.
Leaving the button before releasing MENU restore the original
state appearance and does not toggle the button.
.sp
\f3Rectangular Buttons Not in a Pop-up Menu\f1
.P
Clicking SELECT on a rectangular button toggles the state
associated with it.
Pressing SELECT,
or moving the pointer into the button while SELECT is pressed,
changes the border from unset to set state or vice versa,
to reflect the state the button would be in if SELECT were
released.
Releasing SELECT toggles the state.
Moving the pointer off the button before releasing SELECT
restores the state appearance and does not toggle the button.
but does not toggle the state.
.P
If the button is in a stay-up menu,
clicking or pressing MENU works the same as SELECT.
If the button is not in a stay-up (or pop-up) menu,
clicking or pressing MENU does not do anything;
the event is passed up to an ancestor widget.
.sp
\f3\*(rW Coloration\f1
.P
Figure 2 illustrates the resources that affect the coloration
of the \*(bW widget.
.br
.ne 3.5i
.BP PSART/ps.rectang2
.P
.ce
\f3Figure 2.\f1  Rectangular Button Coloration
.P
.SH "RESOURCES"
.ds cO
.TS 
allbox;
cB s s s s
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2
lp-2 lp-2 lp-2 lp-2 lp-2.
\*(bW Resource Set
Name	Class	Type	Default	Access
_
XtNancestorSensitive	XtCSenstitive	Boolean	TRUE	G*
XtNbackground	XtCBackground	Pixel	White	SGI\(dg
XtNbackgroundPixmap	XtCPixmap	Pixmap	(none)	SGI\(dg
XtNdefault	XtCDefault	Boolean	FALSE	SGI
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 *	NULL	SGI
XtNlabelJustify	XtCLabelJustify	OlDefine	OL_LEFT	SGI
XtNlabelTile	XtCLabelTile	Boolean	FALSE	SGI
XtNlabelType	XtCLabelType	int	OL_STRING	SGI
.TE
.SK
.TS 
allbox;
cB s s s s
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2
lp-2 lp-2 lp-2 lp-2 lp-2.
\*(bW Resource Set (cont.)
Name	Class	Type	Default	Access
_
XtNmappedWhenManaged	XtCMappedWhenManaged	Boolean	TRUE	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
.TE
.sp
\f3XtNdefault\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4TRUE
FALSE\f1
.in -5
.fi
.PP
If this resource is
\f4TRUE\f1,
the Border is doubled to two lines,
to show that the button is the default choice of one or more
buttons.
.sp
\f3XtNdim\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4TRUE
FALSE\f1
.in -5
.fi
.PP
If this resource is
\f4TRUE\f1,
then the button border is dimmed to
show that the button 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.
.sp
\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.
This resource is ignored unless the
\f4XtNlabelType\f1
resource has the value
\f4OL_IMAGE\f1.
.P
If the image is of type
\f4XYBitmap\f1,
the image is highlighted when appropriate by reversing the 0
and 1 values of each pixel
(i.e. by "`xor'ing" the image data).
If the image is of type
\f4XYPixmap\f1
or
\f4ZPixmap\f1,
the image is not highlighted,
although the space around the image inside the Border is
highlighted.
.P
If the image is smaller than the space available for it inside
the Border
and
\f4XtNlabelTile\f1
is
\f4FALSE\f1,
the image 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 Border.
If the
\f4XtNdefault\f1
resource is
\f4TRUE\f1
so that the Border is doubled,
the space available is that inside the inner line of the
Border.
.sp
\f3XtNlabelJustify\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4OL_LEFT/"left"
OL_CENTER/"center"\f1
.in -5
.fi
.PP
This resource dictates whether the Label should be 
left-justified or centered within the widget width.
.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
\f4XtNlabelJustify\f1
resource.
.P
The
\f4XtNlabelTile\f1
resource is ignored for text labels.
.sp
\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.
.P
.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
\f3XtNselect\f1
.P
This is the list of callbacks invoked when the widget is
selected.
.sp 0.75
\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 button.
The button's border is thickened to show a
\f4TRUE\f1
state.
.sp 0.75
\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.
.sp 0.75
\f3XtNdim, XtNdefault, XtNset\f1
.P
The
\f4XtNdim\f1,
\f4XtNdefault\f1,
and
\f4XtNset\f1
resources can be set independently;
however,
all these states cannot be reflected in the visual
appearance of the rectangular button,
as the state table in Figure 3 shows.
.br
.ne3.5i
.BP PSART/ps.rectang3
.P
.ce
\f3Figure 3.\f1  Rectangular Button Appearance when Set/Default/Dim
.sp
\f3Label Appearance\f1
.P
The
\f4XtNwidth\f1,
\f4XtNheight\f1,
\f4XtNrecomputeSize\f1,
and
\f4XtNlabelJustify\f1
resources interact to produce a truncated, clipped, centered, or
left-justified label as shown in Figure 4.
.br
.ne3.5i
.BP PSART/ps.rectang4
.P
.ce
\f3Figure 4.\f1  Label Appearance
.P
When the label is centered or left-justified,
the extra space is filled with the background color of the
\*(bW widget,
as determined by the
\f4XtNbackground\f1
and
\f4XtNbackgroundPixmap\f1
resources.
.P
When the label is truncated,
a solid-black triangle is inserted to show that part of the
label is missing.
The triangle
requires that more of the label be truncated than would
otherwise be necessary.
If the width of the button is too small to show even one
character with the triangle,
only the triangle is shown.
If the width is so small that the entire triangle cannot be
shown,
the triangle is clipped on the right.
.P
See also the
\f4XtNlabelTile\f1
resource for how it affects the appearance of a label.
