NAME
Form widget − geometry-managing widget implementing constraints on children.
SYNOPSIS
Public Headers:<X11/StringDefs.h> <X11/Xaw/Form.h>
Private Header:<X11/Xaw/FormP.h>
Class Name:Form
Class Pointer:formWidgetClass
Instantiation:widget = XtCreateWidget(name, formWidgetClass, ...)
CLASS HIERARCHY
Core → Composite → Constraint → Form
DESCRIPTION
The Form widget can contain an arbitrary number of children of any class. The Form provides geometry management for its children, including individual control of the position of each child. The initial positions of the children may be computed relative to the positions of previously created children. When the Form is resized, it computes new positions and sizes for its children. This computation is based upon information provided as constraints when each child is added to the Form.
RESOURCES
When creating a Form widget instance, the following resources are retrieved from the argument list or from the resource database:
| Name (XtN...) | Type | Default | Description | |||
| XtNaccelerators | AcceleratorTable | NULL | List of event-to-action bindings to be executed by this widget, even though the event occurred in another widget. | |||
| XtNancestor− Sensitive |
Boolean | True | (D) Sensitivity state of the ancestors of this widget: a widget is insensitive if either it or any of its ancestors is insensitive. | |||
| XtNbackground | Pixel | XtDefault− Background |
Window background color. | |||
| XtNbackground− Pixmap |
Pixmap | XtUnspecified− Pixmap |
Window background pixmap. | |||
| XtNborderColor | Pixel | XtDefault− Foreground |
Window border color. | |||
| XtNborderPixmap | Pixmap | XtUnspecified− Pixmap |
Window border pixmap. | |||
| XtNborderWidth | Dimension | 1 | Width of border in pixels. | |||
| XtNchildren | WidgetList | NULL | (R) List of all this composite widget’s current children. | |||
| XtNcolormap | Colormap | Parent’s colormap. | Colormap that this widget will use. | |||
| XtNdefault− Distance |
int | 4 | Default value for XtNhorizDistance and XtNvertDistance. | |||
| XtNdepth | int | Parent’s depth. | (C) Depth of this widget’s window. | |||
| XtNdestroy− Callback |
XtCallbackList | NULL | Callbacks for XtDestroyWidget(). | |||
| XtNheight | Dimension | Computed at realize. |
(A) Height of form. | |||
| XtNmappedWhen− Managed |
Boolean | TRUE | Whether XtMapWidget() is automatic. | |||
| XtNnumChildren | Cardinal | 0 | (R) Number of children in this composite widget. | |||
| XtNscreen | Screen | Parent’s screen | (R) Screen on which this widget is displayed. | |||
| XtNsensitive | Boolean | TRUE | Whether widget receives input. | |||
| XtNtranslations | TranslationTable | NULL | Event-to-action translations. | |||
| XtNwidth | Dimension | Computed at realize. |
(A) Width of form. | |||
| XtNx | Position | 0 | x coordinate in pixels. | |||
| XtNy | Position | 0 | y coordinate in pixels. | |||
CONSTRAINTS
When creating children to be added to a Form, the following additional resources are retrieved from the argument list or from the resource database. Note that these resources are maintained by the Form widget, even though they are stored in the child.
| Name (XtN...) | Type | Default | Description | |||
| XtNbottom | XtEdgeType | XtRubber | See text. | |||
| XtNfromHoriz | Widget | NULL | See text. | |||
| XtNfromVert | Widget | NULL | See text. | |||
| XtNhorizDistance | int | XtdefaultDistance | See text. | |||
| XtNleft | XtEdgeType | XtRubber | See text. | |||
| XtNresizable | Boolean | FALSE | TRUE if children allowed to resize themselves. | |||
| XtNright | XtEdgeType | XtRubber | See text. | |||
| XtNtop | XtEdgeType | XtRubber | See text. | |||
| XtNvertDistance | int | XtdefaultDistance | See text. | |||
These resources are called constraints, and can be specified to the Form to indicate where the child should be positioned within the Form.
The resources XtNhorizDistance and XtNfromHoriz let the widget position itself a specified number of pixels horizontally away from another widget in the form. As an example, XtNhorizDistance could equal 10 and XtNfromHoriz could be the widget ID of another widget in the Form. The new widget will be placed 10 pixels to the right of the widget defined in XtNfromHoriz. If XtNfromHoriz equals NULL, then XtNhorizDistance is measured from the left edge of the Form.
Similarly, the resources XtNvertDistance and XtNfromVert let the widget position itself a specified number of pixels vertically away from another widget in the Form. If XtNfromVert equals NULL, then XtNvertDistance is measured from the top of the Form. Form provides a cvtStringToWidget conversion procedure. Using this procedure, the resource database may be used to specify the XtNfromHoriz and XtNfromVert resources by widget name rather than widget ID. The string value must be the name of a child of the same Form widget parent.
The XtNtop, XtNbottom, XtNleft, and XtNright resources tell the Form where to position the child when the Form is resized. XtEdgeType is defined in <X11/Xaw/Form.h> and is one of XtChainTop, XtChainBottom, XtChainLeft, XtChainRight, or XtRubber.
The values XtChainTop, XtChainBottom, XtChainLeft, and XtChainRight specify that a constant distance is to be maintained from an edge of the child to the top, bottom, left, and right edges, respectively, of the Form. The value XtRubber specifies that a proportional distance from the edge of the child to the left or top edge of the Form is to be maintained when the form is resized. The proportion is determined from the initial position of the child and the initial size of the Form. Form provides an XtrStringtoXtrEdgeType resource converter to allow the resize constraints to be specified easily in a resource file.
The default width of the Form is the minimum width needed to enclose the children after computing their initial layout, with a margin of XtNdefaultDistance at the right and bottom edges. If a width and height is assigned to the Form that is too small for the layout, the children will be clipped by the right and bottom edges of the Form.
PUBLIC FUNCTIONS
When a new child becomes managed or an old child unmanaged, the Form widget will recalculate the positions of its children according to the values of the XtNhorizDistance, XtNfromHoriz, XtNvertDistance, and XtNfromVert constraints at the time the change is made. No re-layout is performed when a child makes a geometry request.
•To force or defer a re-layout of the Form widget, use XtFormDoLayout(): void XtFormDoLayout(w, do_layout) Widget w; Boolean do_layout; where:
wSpecifies the Form widget.
do_layoutEnables (if True) or disables (if False) layout of the Form widget.
When making several changes to the children of a Form widget after the Form has been realized, it is a good idea to disable re-layout until all changes have been made, then allow the layout. The Form widget increments an internal count each time XtFormDoLayout is called with do_layout set to False; the Form widget decrements the count when do_layout is True. When the count reaches 0, the Form widget performs a re-layout.