'\"!  tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | eqn | tbl | tbl | tbl | tbl | tbl | mmdoc
'\"macro stdmacro
.if n .pH g3w.olOblngButon @(#)olOblngButon	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 OBLONGBUTTON
.ds rW OblongButton
.ds nW OblongButt
.ds wW oblongButton
.ds bW \fB\*(rW\fP
.ds iW \fI\*(rW\fP
.ds oS \*(cW
.nr oN 0
.nr X
.if \nX=0 .ds x} ""OBLONGBUTTON WIDGET/GADGET" 3W "\&"
.if \nX=1 .ds x} ""OBLONGBUTTON WIDGET/GADGET" 3W
.if \nX=2 .ds x} ""OBLONGBUTTON WIDGET/GADGET" "" "\&"
.if \nX=3 .ds x} ""OBLONGBUTTON "" "" "\&"
.TH \*(x}
.SH "WIDGET CLASS NAME"
\*(bW
.SH "GADGET CLASS NAME"
\*(bW
.SH "SYNOPSIS"
.nf
\s-1\f4#include <Intrinsic.h>
#include <OpenLook.h>
#include <StringDefs.h>
#include <\*(nW.h>
.fi
.P
.nf
\s-1\f4widget = XtCreateWidget(\f2name\f4, \*(wWWidgetClass, ...);\f1\s+1
OR \s-1\f4widget = XtCreateWidget(\f2name\f4, \*(wWGadgetClass, ...);\f1\s+1
.fi
.SH "DESCRIPTION"
.sp
\f3\*(rW Components\f1
.P
The \*(bW consists of a Label surrounded by a rounded,
or oblong,
Border.
.br
.ne3.5i
.BP PSART/ps.oblong1
.P
.ce
\f3Figure 1.\f1  Oblong Buttons
.P
\f3Busy Button while Action Takes Place\f1
.P
Each \*(bW is associated with an application-defined action
implemented as a list of callbacks.
To let the end user know that an action is still taking place,
the \*(bW stipples the area inside the border before issuing
the callbacks.
When the last callback returns,
the \*(bW restores its original appearance.
If the application's action continues to be "busy" after the
callbacks return,
the application should set the
\f4XtNbusy\f1
resource to
\f4TRUE\f1
before returning from the callbacks,
then reset it to
\f4FALSE\f1
when the action is no longer taking place.
.P
The "busy" stipple pattern is designed to show enough dots to
gray the button noticeably,
while still leaving a text label legible.
.sp
\f3Oblong Buttons in a Pop-up Menu\f1
.P
Entering an oblong button while MENU is depressed highlights
the button's interior.
Releasing MENU then restores the original appearance and invokes
the action for the button as described above.
Leaving the button before releasing MENU restores the appearance
but does not invoke the action.
.sp
\f3Oblong Buttons not in a Pop-up Menu\f1
.P
Clicking SELECT on an oblong button starts the action associated
with the button.
Pressing SELECT,
or moving the pointer into the button while SELECT is pressed,
highlights the button's interior.
Releasing SELECT restores the appearance
and invokes the action for the button as described above.
Moving the pointer off the button before releasing SELECT
also restores the appearance,
but does not invoke the action.
.P
If the oblong button is in a stay-up menu,
clicking or pressing MENU works the same as SELECT.
If the oblong 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
\f3OblongButton Gadgets\f1
.P
\f3OblongButton\f1 gadgets cannot be parents (i.e., be used as the parent
parameter when creating a widget or other gadget).
.P
Correct button behavior is not guaranteed if gadgets are positioned so
that they overlap.
.P
Gadgets share some core fields but, since they are not subclasses of
Core, do not have all Core fields.  In particular, they don't have a
name field or a translation field (so translations cannot be
specified/overriden).
.P
Event Handlers cannot be added to gadgets using
\f(CWXtAddEventHandler\fP.
.sp
\f3\*(rW Coloration\f1
.P
Figure 2 illustrates the resources that affect the coloration
of the \*(bW widget.
.P
\f(HBNote:\f1
.br
Events that occur outside the Border (but within the
\*(bW widget) are still in the domain of the button.
.br
.ne 3.5i
.BP PSART/ps.oblong2
.P
.ce
\f3Figure 2.\f1  Oblong Button Coloration
.sp
.SH "RESOURCES"
.ds cO
.TS H
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\\\*(cO
Name	Class	Type	Default	Access
_
.TH
XtNancestorSensitive	XtCSenstitive	Boolean	TRUE	G*
XtNbackground	XtCBackground	Pixel	White	SGI\(dg
\(dd XtNbackgroundPixmap	XtCPixmap	Pixmap	(none)	SGI\(dg
XtNbusy	XtCBusy	Boolean	FALSE	SGI
XtNdefault	XtCDefault	Boolean	FALSE	SGI
\(dd XtNdepth	XtCDepth	int	(parent's)	GI
XtNdestroyCallback	XtCCallback	XtCallbackList	NULL	SI
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
.TE
.bp
.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
_
XtNlabelJustify	XtCLabelJustify	OlDefine	OL_LEFT	SGI
XtNlabelTile	XtCLabelTile	Boolean	FALSE	SGI
XtNlabelType	XtCLabelType	int	OL_STRING	SGI
\(dd XtNmappedWhenManaged	XtCMappedWhenManaged	Boolean	TRUE	SGI
XtNrecomputeSize	XtCRecomputeSize	Boolean	TRUE	SGI
XtNselect	XtCCallback	XtCallbackList	NULL	SI
XtNsensitive	XtCSensitive	Boolean	TRUE	GI*
XtNuserData	XtCUserData	XtPointer	NULL	SGI
XtNwidth	XtCWidth	Dimension	(calculated)	SGI
XtNx	XtCPosition	Position	0	SGI
XtNy	XtCPosition	Position	0	SGI
.TE
\s-1\(dd These resources are not available to OblongButton gadgets.\s+1
.sp
\f3XtNbusy\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4TRUE
FALSE\f1
.in -5
.fi
.PP
This resource controls whether the button interior should be
stippled to show that the action associated with the button is
``busy.''
While
\f4XtNbusy\f1
is
\f4TRUE\f1,
the system will beep if the end user attempts to select the
button;
the attempt is refused and no callbacks are invoked.
.sp
\f3XtNdefault\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4TRUE
FALSE\f1
.in -5
.fi
.PP
If this resource is
\f4TRUE\f1,
and the button is in a menu, an oval ring is drawn around
the button
to show that the button is the default choice of one or more
buttons.
.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.
.bp
\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 0.75
\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 0.75
\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.
.bp
\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 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 0.75
\f3XtNlabelType\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4OL_STRING/"string"
OL_IMAGE/"image"
OL-POPUP/"string..."\f1
.in -5
.fi
.PP
This resource identifies the form that the Label takes.
It can have the value
\f4OL_STRING\f1 for text,
\f4OL_IMAGE\f1 for an image, or
\f4OL_POPUP\f1 for text followed by an ellipsis (such as 
.HK label... )
\.
.sp 0.75
\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.75
\f3XtNselect\f1
.P
This is the list of callbacks invoked when the widget is
selected.
.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 3.
.br
.ne 3.5i
.BP PSART/ps.oblong3
.P
.ce
\f3Figure 3.\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 a text label is truncated,
the truncation occurs at a character boundary and a solid
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
An image label is simply truncated; no triangle is shown.
.P
See also the
\f4XtNlabelTile\f1
resource for how it affects the appearance of a label image.
