Form(3W) UNIX System V Form(3W)
NAME
Form - a composite widget allowing sophisticated management of other
widgets in its boundaries
SYNOPSIS
#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <Form.h>
widget = XtCreateWidget(name, formWidgetClass, ...);
DESCRIPTION
The Form 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.
Spanning Constraints
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.
Row Constraints
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.
Column Constraints
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.
Automatic Form Resizing
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.
Managing, Unmanaging and Destroying Children
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.
10/89 Page 1
Form(3W) UNIX System V Form(3W)
Works with All Children
The Form composite widget works with all the widgets defined in this
document, except those that are sub-classed from the Shell widget class.
Form Coloration
Figure 1 illustrates the resources that affect the coloration of the Form
widget.
Figure 1. Form Coloration
RESOURCES
_______________________________________________________________________________________
| Form Resource Set |
|____________________|______________________|_________________|______________|________|
|Name | Class | Type | Default | Access|
|____________________|______________________|_________________|______________|________|
|____________________|______________________|_________________|______________|________|
|XtNancestorSensitive| XtCSenstitive | Boolean | TRUE | G* |
|____________________|______________________|_________________|______________|________|
|XtNbackground | XtCBackground | Pixel | White | SGI† |
|____________________|______________________|_________________|______________|________|
|XtNbackgroundPixmap | XtCPixmap | Pixmap | (none) | SGI† |
|____________________|______________________|_________________|______________|________|
|XtNborderColor | XtCBorderColor | Pixel | Black | SGI† |
|____________________|______________________|_________________|______________|________|
|XtNborderPixmap | XtCPixmap | Pixmap | (none) | SGI† |
|____________________|______________________|_________________|______________|________|
|XtNborderWidth | XtCBorderWidth | Dimension | 0 | SGI |
|____________________|______________________|_________________|______________|________|
|XtNconsumeEvent | XtCConsumeEvent | XtCallbackList | NULL | SG |
|____________________|______________________|_________________|______________|________|
|XtNdepth | XtCDepth | int | (parent's) | GI |
|____________________|______________________|_________________|______________|________|
|XtNdestroyCallback | XtCCallback | XtCallbackList | NULL | SI |
|____________________|______________________|_________________|______________|________|
|XtNheight | XtCHeight | Dimension | (calculated)| SGI |
|____________________|______________________|_________________|______________|________|
|XtNmappedWhenManaged| XtCMappedWhenManaged| Boolean | TRUE | SGI |
|____________________|______________________|_________________|______________|________|
|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 |
|____________________|______________________|_________________|______________|________|
Page 2 10/89
Form(3W) UNIX System V Form(3W)
CONSTRAINT RESOURCES
Each child widget attached to the Form 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.)
______________________________________________________________________________
| Form Constraint Resource Set |
|__________________|____________________|___________|___________|_____________|
| Name | Class | Type | Default | Access |
|__________________|____________________|___________|___________|_____________|
|__________________|____________________|___________|___________|_____________|
| 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 |
|__________________|____________________|___________|___________|_____________|
XtNxAddWidth
XtNyAddHeight
Range of Values:
TRUE
FALSE
10/89 Page 3
Form(3W) UNIX System V Form(3W)
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.
XtNxAttachOffset
XtNyAttachOffset
Range of Values:
0 < XtNxAttachOffset
0 < XtNyAttachOffset
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.
XtNxAttachRight
XtNyAttachBottom
Range of Values:
TRUE
FALSE
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
XtNxVaryOffset and XtNyVaryOffset resources, they allow a widget to float
along the right or bottom edge of the form. This is done by setting both
the XtNxAttachRight (XtNyAttachBottom) and XtNxVaryOffset
(XtNyVaryOffset) resources to TRUE. A widget can also span the width
(height) of the form by setting the XtNxAttachRight (XtNyAttachBottom)
resource to TRUE and the XtNxVaryOffset (XtNyVaryOffset) resource to
FALSE.
XtNxOffset
XtNyOffset
Range of Values:
0 < XtNxOffset
0 < XtNyOffset
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.
Page 4 10/89
Form(3W) UNIX System V Form(3W)
XtNxRefName
XtNyRefName
Range of Values:
(the name of a widget already created as a child of the form)
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.
If one of these resources is set and the corresponding resource,
XtNxRefWidget or XtNyRefWidget, is also set, they must agree: the name
given in XtNxRefName or XtNyRefName must match the name of the identified
widget. The advantage of using these resources rather than XtNxRefWidget
and XtNyRefWidget is that the references can be used before the widget
instances are made.
XtNxRefWidget
XtNyRefWidget
Range of Values:
(the ID of a widget already created as a child)
Instead of naming the reference widget, an application can give the
reference widget's ID using these resources.
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 ID is used.
XtNxResizable
XtNyResizable
Range of Values:
TRUE
FALSE
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 XtNxVaryOffset (XtNyVaryOffset) resource set to TRUE. The form
keeps track of a widget's initial size or its size generated through
calls to XtSetValues(), so that when the form then becomes larger, the
widget will grow to its original size and no larger.
XtNxVaryOffset
XtNyVaryOffset
10/89 Page 5
Form(3W) UNIX System V Form(3W)
Range of Values:
TRUE
FALSE
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 XtNxAddWidth (XtNyAddHeight)
resource is FALSE or to one pixel if XtNxAddWidth (XtNyAddHeight) is
TRUE.
Page 6 10/89