'\"!  tbl | tbl | tbl | tbl | tbl | mmdoc
'\"macro stdmacro
.if n .pH g3w.olControlAre @(#)olControlAre	40.3 of 1/8/90
.tr ~
.ig
Revised:  gjh 2/15/89
Revised:  gjh 2/6/89
Revised:  Joy Asay 2/14/89
Revised:  lmh 10/16,17,18/89
format -dshemp -rs1 -man6 gloControlA
THIS IS THE SECOND VERSION
..
.SO BP.HEADER \"This header enables use of .BP macro for PostScript graphics
.ds cW CONTROLAREA
.ds rW ControlArea
.ds nW ControlAre
.ds wW controlArea
.ds bW \fB\*(rW\fP
.ds iW \fI\*(rW\fP
.ds oS \*(cW
.nr oN 0
.nr X
.if \nX=0 .ds x} ""CONTROLAREA WIDGET" 3W "\&"
.if \nX=1 .ds x} ""CONTROLAREA WIDGET" 3W
.if \nX=2 .ds x} ""CONTROLAREA WIDGET" "" "\&"
.if \nX=3 .ds x} ""CONTROLAREA "" "" "\&"
.TH \*(x}
.SH "WIDGET CLASS NAME"
\*(bW
.SH "SYNOPSIS"
.nf
\s-1\f(CW#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <\*(nW.h>\f1\s+1\f1
.fi
.P
.nf
\s-1\f(CWwidget = XtCreateWidget(\f2name\f(CW, \*(wWWidgetClass, ...);\f1\s+1
.fi
.SH "DESCRIPTION"
.sp
\f3\*(rW Components\f1
.P
The \*(bW widget has zero or more Child Widgets and an
optional Border.
.sp
\f3Layout Control\f1
.P
The \*(bW composite widget arranges its
child widgets,
presenting them to the end-user as a group of "controls".
The application can choose one of four simple layout schemes:
Fixed number of columns in the control pane,
fixed number of rows,
fixed overall width of the control area,
and fixed overall height.
The application can also specify the inter-control spacing and
the size of the margin around the children.
.sp
\f3Equal Height Rows\f1
.P
The children in each row align at the top of the row.
The distance between the top of one row and the next is the
height of the tallest control in the row plus the application
specified inter-row spacing.
.sp
\f3Keyboard Traversal\f1
.P
Users can traverse among \f3Text\f1 and \f3TextField\f1
widgets within any ancestor \f3ControlArea, BulletinBoard\f1, or
\f3Form\f1 widget using the NEXTFIELD and PREVFIELD keys:  
.IP "\(em" 5
NEXTFIELD
moves the caret to the next traversable \f3Text\f1 or \f3TextField\f1
widget in the managing ancestor widget. 
When the caret is in the last traversable
field, NEXTFIELD moves the caret to the first traversable field.
.IP "\(em" 
PREVFIELD moves the caret to the previous traversable
field in the managing ancestor widget. 
When the caret is in the first traversable
field, PREVFIELD moves the caret to the last traversable field.
.P
The default key mappings for NEXTFIELD and PREVFIELD are
TAB and SHIFT-TAB, respectively.  A user may change these
defaults through the appropriate Workspace Properties
window.
.sp
\f3\*(rW Coloration\f1
.P
Figure 1 illustrates the resources that affect the coloration
of the \*(bW widget.
.br
.ne3.5i
.BP PSART/ps.control1
.P
.ce
\f3Figure 1.\f1  Control Area Coloration
.P
.SH "RESOURCES"
.TS H
allbox;
cB s s s s.
\*(bW Resource Set
.T&
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2.
Name	Class	Type	Default	Access
_
.TH
.T&
lw(7P)p-2 lw(7.5P)p-2 lw(4.5P)p-2 lp-2 lp-2.
XtNalignCaptions	XtCAlignCaptions	Boolean	FALSE	SGI
XtNancestorSensitive	XtCSenstitive	Boolean	TRUE	G*
XtNbackground	XtCBackground	Pixel	White	SGI\(dg
XtNbackgroundPixmap	XtCPixmap	Pixmap	(none)	SGI\(dg
XtNborderColor	XtCBorderColor	Pixel	Black	SGI\(dg
XtNborderPixmap	XtCPixmap	Pixmap	(none)	SGI\(dg
XtNborderWidth	XtCBorderWidth	Dimension	0	SGI
XtNcenter	XtCCenter	Boolean	FALSE	SGI
XtNdepth	XtCDepth	int	(parent's)	GI
XtNdestroyCallback	XtCCallback	XtCallbackList	NULL	SI
XtNhPad	XtCHPad	Dimension	4	SGI
XtNhSpace	XtCHSpace	Dimension	4	SGI
XtNheight	XtCHeight	Dimension	(calculated)	SGI
XtNlayoutType	XtCLayoutType	OlDefine	OL_FIXEDROWS	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(7.5P)p-2 lw(4.5P)p-2 lp-2 lp-2.
XtNmeasure	XtCMeasure	int	1	SGI
.XX TRAVERSAL XtNnextTop	XtCCallback	XtCallbackList	NULL	SI
XtNsameSize	XtCSameSize	OlDefine	OL_COLUMNS	SGI
XtNsensitive	XtCSensitive	Boolean	TRUE	GI*
.XX TRANSPARENT XtNtransparent	XtCTransparent	Boolean	TRUE	SGI
XtNtraversalManager	XtCTraversalManager	Boolean	FALSE	SGI
XtNuserData	XtCUserData	XtPointer	NULL	SGI
XtNvPad	XtCVPad	Dimension	4	SGI
XtNvSpace	XtCVSpace	Dimension	4	SGI
XtNwidth	XtCWidth	Dimension	(calculated)	SGI
XtNx	XtCPosition	Position	0	SGI
XtNy	XtCPosition	Position	0	SGI
.TE
.sp
\f3XtNalignCaptions\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CWTRUE
FALSE\f1
.in -5
.fi
.PP
This resource controls how the \*(bW widget aligns widgets of
the
\f3Caption\f1
class.
If set to
\f(CWTRUE\f1,
the \*(bW will align all
\f3Caption\f1
widgets in each column so that their captions are right
justified.
This may affect the width calculation for a column:
The effective width for the
\f3Caption\f1
widgets in a column becomes the sum of the width of the widest
caption,
plus the largest caption/child widget separation and child
widget width.
.P
This alignment is only for groups of
\f3Caption\f1
widgets with all their captions on the left or the right.
Mixed orientation,
or captions above or below,
cannot be aligned well.
.bp
.br
.ne 3i
.BP PSART/ps.control2
.P
.ce
\f3Figure 2.\f1  Aligning Captions
.sp
.P
If the
\f(CWXtNalignCaption\f1
resource is set to
\f(CWFALSE\f1,
the \*(bW will align all
\f3Caption\f1
widgets the same as other widgets\(emby their overall width.
.P
This resource takes precedence over the
\f(CWXtNcenter\f1
resource,
but only for
\f3Caption\f1
widgets.
.sp
\f3XtNcenter\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CWTRUE
FALSE\f1
.in -5
.fi
.PP
This resource controls how the \*(bW widget orients each widget
within a column
(although see also
\f(CWXtNalignCaptions\f1).
If set to
\f(CWTRUE\f1,
the \*(bW will center each widget with each column;
if set to
\f(CWFALSE\f1,
the \*(bW will left justify each widget within each column,
unless the
\f(CWXtNalignCaptions\f1
resource is
\f(CWTRUE\f1.
.bp
\f3XtNhPad\f1
.br
\f3XtNvPad\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CW0 \(<= XtNhPad
0 \(<= XtNvPad\f1
.in -5
.fi
.PP
These resources give the amount of padding,
in pixels,
to leave around the edges of the control area,
left and right, and top and bottom, respectively,
as suggested by Figure 3.
.sp
.br
.ne3.5i
.BP PSART/ps.control3
.P
.ce
\f3Figure 3.\f1  Padding Around Controls
.P
.bp
\f3XtNhSpace\f1
.br
\f3XtNvSpace\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CW0 \(<= XtNhSpace
0 \(<= XtNvSpace\f1
.in -5
.fi
.PP
These resources give the amount of space,
in pixels,
to leave between controls horizontally and vertically,
respectively.
If the controls are of different sizes in a row or column,
the spacing applies to the widest or tallest dimension of all
the controls.
.bp
.br
.ne3.5i
.BP PSART/ps.control4
.P
.ce
\f3Figure 4.\f1  Spacing Between Controls
.sp
\f3XtNlayoutType\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CWOL_FIXEDROWS/"fixedrows"
OL_FIXEDCOLS/"fixedcols"
OL_FIXEDWIDTH/"fixedwidth"
OL_FIXEDHEIGHT/"fixedheight"\f1
.in -5
.fi
.PP
This resource controls the layout of the child widgets by the
\*(bW composite.
The choices are to specify the number of rows or columns,
or to specify the overall height or width of the layout area.
Only one of these dimensions can be specified directly;
the other is determined by the number of controls added.
For instance,
if the application specifies that the control area should have
four columns,
the number of rows will be the number of controls divided by
four.
.bp
The values of the
\f(CWXtNlayoutType\f1
resource can be:
.IP \f(CWOL_FIXEDROWS\f1 18
.sp -1
if the layout should have a fixed number of rows and enough
columns to hold all the controls;
.IP \f(CWOL_FIXEDCOLS\f1 18
.sp -1
if the layout should have a fixed number of columns and enough
rows to hold all the controls;
.IP \f(CWOL_FIXEDWIDTH\f1 18
.sp -1
if the layout should be of a fixed width but tall enough to
hold all the controls;
.IP \f(CWOL_FIXEDHEIGHT\f1 18
.sp -1
if the layout should be of a fixed height but wide enough to
hold all the controls.
.P
The
\f(CWXtNmeasure\f1
resource gives the number of rows or columns or the fixed
height or width.
.sp
\f3XtNmeasure\f1
.PP
Range of Values:
.br
.in +5
\f(CW0 < XtNmeasure\f1
.in 0
.P
Default:
.P
.in +5
If \f(CWXtNlayoutType \f1is \f(CWOL_FIXEDROWS \f1or \f(CWOL_FIXEDCOLS\f1: \f(CW1
.br
\f1If \f(CWXtNlayoutType \f1is \f(CWOL_FIXEDWIDTH \f1or \f(CWOL_FIXEDHEIGHT\f1:  
.br
.in +10n
\f(CWwidth or height of widest or tallest widget, depending on
\f(CWXtNlayoutType\f1.
.in 0 
.PP
This resource gives the number of rows or columns in the layout
of the child widgets,
or the fixed width or height of the control area.
When
\f(CWXtNlayoutType\f1
is
\f(CWOL_FIXEDWIDTH\f1
or
\f(CWOL_FIXEDHEIGHT\f1,
the measure includes the
padding on both edges and the inter-control spacing,
as suggested by Figure 5.
.bp
.br
.ne3.5i
.BP PSART/ps.control5
.P
.ce
\f3Figure 5.\f1  XtNmeasure
.XX TRAVERSAL .so SOURCEFILES/Widgets/common/XtN/nextTop
.XX TRAVERSAL .P
.sp
\f3XtNsameSize\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CWOL_NONE/"none"
OL_COLUMNS/"columns"
OL_ALL/"all"\f1
.in -5
.fi
.PP
This resource controls which controls,
if any,
are forced to be the same width within the \*(bW widget:
.IP \f(CWOL_NONE\f1 12
.sp -1
The controls are placed in fixed-width columns,
but the size of each control is left alone.
The width of each column is the width of the widest control in
the column.
.IP \f(CWOL_COLUMNS\f1 12
.sp -1
Controls of the same class in each column are made the same
width as the widest of them.
The width of each column is thus the width of the widest
control in the column.
.IP \f(CWOL_ALL\f1 12
.sp -1
All controls are made the same width,
the width of the widest control in the \*(bW widget.
.P
.sp
\f3XtNtraversalManager\f1
.P
This resource controls whether this widget manages traversal
for its descendants.
.sp
.XX TRANSPARENT .so SOURCEFILES/Widgets/common/XtN/transparent/composite
.XX TRANSPARENT .P
.XX .SH "CONSTRAINT RESOURCES"
.XX Each child widget attached to the \*(bW composite widget is
.XX constrained by the following resources.
.XX In essence,
.XX these resources become resources for each child widget,
.XX that can be set and read just like any other resources defined
.XX for the child.
.XX .TS H
.XX center allbox;
.XX cB s s s s.
.XX \*(bW Constraint Resource Set\\\\*(cO
.XX .T&
.XX lBp-2 lBp-2 lBp-2 lBp-2 lBp-2.
.XX Name	Class	Type	Default	Access
.XX _
.XX .TH
.XX .T&
.XX lp-2 lp-2 lp-2 lp-2 lp-2.
.XX XtNinsertOrder	XtCInsertOrder	Widget	(control area)	SGI
.XX .TE
.XX TRAVERSAL XtNfocusRefName	XtCFocusRefName	String	NULL	SGI
.XX TRAVERSAL XtNfocusRefWidget	XtCFocusRefWidget	Widget	(form)	SGI
.XX TRAVERSAL .so SOURCEFILES/Widgets/common/XtN/focusRefName
.XX TRAVERSAL .so SOURCEFILES/Widgets/common/XtN/focusRefWidget
.XX .so SOURCEFILES/Widgets/common/XtN/insertOrder
.XX TRAVERSAL .SH "TRAVERSAL"
.XX TRAVERSAL \f3Receiving Input Focus via CONTROLAREA\f1
.XX TRAVERSAL .P
.XX TRAVERSAL The \*(bW widget can receive input focus only with the clicking
.XX TRAVERSAL of CONTROLAREA.
.XX TRAVERSAL .P
.XX TRAVERSAL \f3Moving Input Focus by Mnemonic\f1
.XX TRAVERSAL .P
.XX TRAVERSAL The \*(bW widget responds to a key that matches the mnemonic
.XX TRAVERSAL of one of its child widgets by moving the input focus to that
.XX TRAVERSAL child.
.XX TRAVERSAL Any other keys cause the system to beep.
.XX TRAVERSAL .P
.XX TRAVERSAL \f3Moving Input Focus by Child Request\f1
.XX TRAVERSAL .P
.XX TRAVERSAL The \*(bW widget expects the following requests from its child
.XX TRAVERSAL widgets:
.XX TRAVERSAL .IP "move input focus to peer widget" 8
.XX TRAVERSAL moves the input focus in the direction and distance requested.
.XX TRAVERSAL See \f3TRAVERSAL\f1
.XX TRAVERSAL for details on determining directional relationships among
.XX TRAVERSAL child widgets.
.XX TRAVERSAL .IP "move input focus to next category" 8
.XX TRAVERSAL moves the input focus to the next or previous child widget,
.XX TRAVERSAL as requested.
.XX TRAVERSAL The order for passing input focus is identified via the
.XX TRAVERSAL \f(CWXtNfocusRefWidget\f1
.XX TRAVERSAL or
.XX TRAVERSAL \f(CWXtNfocusRefName\f1
.XX TRAVERSAL resources or the
.XX TRAVERSAL \f(CWXtNnextTop\f1
.XX TRAVERSAL callback.
