'\"!  tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | mmdoc
'\"macro stdmacro
.if n .pH g3w.olForm @(#)olForm	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 Form
THIS IS THE SECOND VERSION
..
.SO BP.HEADER \" This header enables use of .BP macro for PostScript graphics
.ds cW FORM
.ds rW Form
.ds nW Form
.ds wW form
.ds bW \fB\*(rW\fP
.ds iW \fI\*(rW\fP
.ds oS \*(cW
.nr oN 0
.nr X
.if \nX=0 .ds x} ""FORM WIDGET" 3W "\&"
.if \nX=1 .ds x} ""FORM WIDGET" 3W
.if \nX=2 .ds x} ""FORM WIDGET" "" "\&"
.if \nX=3 .ds x} ""FORM "" "" "\&"
.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"
The \f3Form\f1 widget is a constraint-based manager that provides a
layout language used to establish spatial relationships between
its children.
It then manipulates these relationships when the Form is
resized, new children are added to the Form, or its children
are moved, resized, unmanaged, remanaged, rearranged, or destroyed.
.sp 0.75
\f3Spanning Constraints\f1
.P
A widget can be created with a set of constraints in such
a manner that it
spans the width or height of a form.
Constraints that cause a widget to span both the width and
height of a form can also be specified.
.sp 0.75
\f3Row Constraints\f1
.P
Sets of widgets can be set up as a row so that resizing a form
may increase or decrease the spacing between the widgets.
The form may also make the widgets smaller if desired.
.sp 0.75
\f3Column Constraints\f1
.P
Sets of widgets can be displayed in a single column or in
multiple columns.
The form may increase or decrease the spacing between widgets
or resize the widgets.
.sp 0.75
\f3Automatic Form Resizing\f1
.P
The form calculates new sizes or positions for its children
whenever they change size or position.
The new form size thus generated is passed as a geometry
request to the parent of the form.
Once resized, the form, using its children's constraints,
tries to rearrange its children as intelligently as possible.
.ig
When a geometry almost is returned by the parent,
the form respecifies the constraints to match the parent's
reply size.
.sp 0.75
\f3Optimal Child Sizes and Positions\f1
.P
The Form widget also calculates the sizes and positions of its
children to match the constraints defined and to match
either the initial size of the widget or the size given when
the widget was modified through
\f(CWXtSetValues()\f1.
These values are further constrained to match a given form size
only when the form's size is being explicitly changed through
its resize procedure,
or its parent returns a geometry almost when the form makes a
geometry request.
..
.sp 0.75
\f3Managing, Unmanaging and Destroying Children\f1
.P
When a widget within a form is unmanaged or destroyed,
it is removed from the constraint processing and the
constraints are reprocessed to reposition and/or resize the
form and its contents.
Any widgets that referenced it are rereferenced to the widget
that it had been referencing.
For the unmanaged case,
if the widget is remanaged,
the widgets that were previously referencing it are
rereferenced to it,
thereby reestablishing the original layout.
.bp
\f3Works with All Children\f1
.P
The \*(bW composite widget works with all the widgets defined
in this document,
except those that are sub-classed from the
\f3Shell\f1
widget class.
.sp 0.75
\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 0.75
\f3\*(rW Coloration\f1
.P
Figure 1 illustrates the resources that affect the coloration
of the \*(bW widget.
.br
.ne3.5i
.BP PSART/ps.form1
.ce
\f3Figure 1.\f1  Form Coloration
.bp
.SH "RESOURCES"
.ds cO
.TS H
expand,allbox;
cB s s s s.
\*(bW Resource Set\\\\*(cO
.T&
l1Bp-2 l1Bp-2 l1Bp-2 l1Bp-2 l1Bp-2.
Name	Class	Type	Default	Access
_
.TH
.ds cO " (cont'd)
.T&
l1p-2 l1p-2 l1p-2 l1p-2 l1p-2.
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
XtNdepth	XtCDepth	int	(parent's)	GI
XtNdestroyCallback	XtCCallback	XtCallbackList	NULL	SI
XtNheight	XtCHeight	Dimension	(calculated)	SGI
XtNmappedWhenManaged	XtCMappedWhenManaged	Boolean	TRUE	SGI
.XX TRAVERSAL XtNnextTop	XtCCallback	XtCallbackList	NULL	SI
XtNsensitive	XtCSensitive	Boolean	TRUE	GI*
XtNtraversalManager	XtCTraversalManager	Boolean	FALSE	SGI
.XX TRANSPARENT XtNtransparent	XtCTransparent	Boolean	FALSE	SGI
XtNuserData	XtCUserData	XtPointer	NULL	SGI
XtNwidth	XtCWidth	Dimension	(calculated)	SGI
XtNx	XtCPosition	Position	0	SGI
XtNy	XtCPosition	Position	0	SGI
.TE
.XX TRAVERSAL .so SOURCEFILES/Widgets/common/XtN/nextTop
.XX TRANSPARENT .so SOURCEFILES/Widgets/common/XtN/transparent/composite
.SH "CONSTRAINT RESOURCES"
Each child widget attached to the \*(bW composite widget is
constrained by the following resources:
(In essence,
these resources become resources for each child widget
and can be set and read just like any other resources defined
for the child.)
.ds cO
.TS H
expand,allbox;
cB s s s s.
\*(bW Constraint Resource Set\\\\*(cO
.T&
l1Bp-2 l1Bp-2 l1Bp-2 l1Bp-2 l1Bp-2.
Name	Class	Type	Default	Access
_
.TH
.ds cO " (cont'd)
.T&
l1p-2 l1p-2 l1p-2 l1p-2 l1p-2.
XtNxAddWidth	XtCXAddWidth	Boolean	FALSE	SGI
XtNxAttachOffset	XtCXAttachOffset	int	0	SGI
XtNxAttachRight	XtCXAttachRight	Boolean	FALSE	SGI
XtNxOffset	XtCXOffset	int	0	SGI
XtNxRefName	XtCXRefName	String	NULL	SGI
XtNxRefWidget	XtCXRefWidget	Widget	(form)	SGI
XtNxResizable	XtCXResizable	Boolean	FALSE	SGI
XtNxVaryOffset	XtCXVaryOffset	Boolean	FALSE	SGI
XtNyAddHeight	XtCYAddHeight	Boolean	FALSE	SGI
XtNyAttachBottom	XtCYAttachBottom	Boolean	FALSE	SGI
XtNyAttachOffset	XtCYAttachOffset	int	0	SGI
XtNyOffset	XtCYOffset	int	0	SGI
XtNyRefName	XtCYRefName	String	NULL	SGI
XtNyRefWidget	XtCYRefWidget	Widget	(form)	SGI
XtNyResizable	XtCYResizable	Boolean	FALSE	SGI
XtNyVaryOffset	XtCYVaryOffset	Boolean	FALSE	SGI
.TE
.bp
.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
\f3XtNxAddWidth\f1
.br
\f3XtNyAddHeight\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CWTRUE
FALSE\f1
.in -5
.fi
.PP
These resources indicate whether to add the width or
height of the corresponding reference widget to a widget's
location when determining the widget's position.
.sp
\f3XtNxAttachOffset\f1
.br
\f3XtNyAttachOffset\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CW0 \(<= XtNxAttachOffset
0 \(<= XtNyAttachOffset\f1
.in -5
.fi
.PP
When a widget is attached to the right or bottom edge of the
form, the separation between the widget and the form defaults to
zero pixels.
These resources allow that separation to be set to some other
value.
Also,
for widgets that are not attached to the right or bottom edge
of the form,
these resources specify the minimum spacing between the
widget and the form.
.sp
\f3XtNxAttachRight\f1
.br
\f3XtNyAttachBottom\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CWTRUE
FALSE\f1
.in -5
.fi
.PP
Widgets are normally referenced from ``form left'' to ``form
right'' or from ``form top'' to ``form bottom.''
These resources allow this reference to occur on the opposite
edges of the form.
When used with the
\f(CWXtNxVaryOffset\f1
and
\f(CWXtNyVaryOffset\f1
resources,
they allow a widget to float along the right or bottom edge of
the form.
This is done by setting both the
\f(CWXtNxAttachRight\f1
(\f(CWXtNyAttachBottom\f1)
and
\f(CWXtNxVaryOffset\f1
(\f(CWXtNyVaryOffset\f1)
resources to
\f(CWTRUE\f1.
A widget can also span the width (height) of the form by
setting the
\f(CWXtNxAttachRight\f1
(\f(CWXtNyAttachBottom\f1)
resource to
\f(CWTRUE\f1
and the
\f(CWXtNxVaryOffset\f1
(\f(CWXtNyVaryOffset\f1)
resource to
\f(CWFALSE\f1.
.sp
\f3XtNxOffset\f1
.br
\f3XtNyOffset\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CW0 \(<= XtNxOffset
0 \(<= XtNyOffset\f1
.in -5
.fi
.sp
The location of a widget is determined by the widget it
references.
As the default,
a widget's position on the form exactly matches its reference
widget's location.
There are two additional data used to determine the location.
These resources define integer values representing the number of
pixels to add to the reference widget's location when
calculating the widget's location.
.bp
\f3XtNxRefName\f1
.br
\f3XtNyRefName\f1
.PP
Range of Values:
.br
.in +5
\f1(the name of a widget already created as a child of the form)
.in -5
.PP
When a widget is added as a child of the form, its position is
determined by the widget it references.
These resources allow the name of the reference widget to be given.
The form converts this name to a widget to use for the referencing.
Any widget that is a direct child of the form or the form
widget itself can be used as a reference widget.
.P
If one of these resources is set and the corresponding resource,
\f(CWXtNxRefWidget\f1
or
\f(CWXtNyRefWidget\f1,
is also set,
they must agree: the name given in
\f(CWXtNxRefName\f1
or
\f(CWXtNyRefName\f1
must match the name of the identified widget.
.sp
\f3XtNxRefWidget\f1
.br
\f3XtNyRefWidget\f1
.PP
Range of Values:
.br
.in +5
\f1(the ID of a widget already created as a child)
.in -5
.PP
Instead of naming the reference widget,
an application can give the reference widget's ID using these
resources.
.P
If both a widget ID and a widget name is given for a reference
in the same dimension (x or y),
they must refer to the same widget.
If not,
a warning is made
and the widget referred to by name is used.
.sp
\f3XtNxResizable\f1
.br
\f3XtNyResizable\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CWTRUE
FALSE\f1
.in -5
.fi
.PP
These resources specify whether the form can resize 
(expand or shrink) a widget.
When a form's size becomes smaller, the form will resize its
children only after resizing all the inter-widget spacing of
widgets with their
\f(CWXtNxVaryOffset\f1
(\f(CWXtNyVaryOffset\f1)
resource set to
\f(CWTRUE\f1.
The form keeps track of a widget's initial size or its size
generated through calls to
\f(CWXtSetValues()\f1,
so that when the form then becomes larger, the widget will grow
to its original size and no larger.
.sp
\f3XtNtraversalManager\f1
.PP
This resource controls whether this widget manages traversal
for its descendants.
.sp
\f3XtNxVaryOffset\f1
.br
\f3XtNyVaryOffset\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CWTRUE
FALSE\f1
.in -5
.fi
.PP
When a form is resized,
it processes the constraints contained within its children.
These resources allow the spacing between a widget and the
widget it references to vary
(either increase or decrease)
when a form's size changes.
For widgets that directly reference the form widget, these
resources are ignored.
The spacing between a widget and its reference widget can
decrease to zero pixels if the
\f(CWXtNxAddWidth\f1
(\f(CWXtNyAddHeight\f1)
resource is
\f(CWFALSE\f1
or to one pixel if
\f(CWXtNxAddWidth\f1
(\f(CWXtNyAddHeight\f1)
is
\f(CWTRUE\f1.
.XX TRAVERSAL .SH "TRAVERSAL"
.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.
