WIDGET CLASS NAME

Form

SYNOPSIS

#include <Intrinsic.h>
#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <Form.h>

widget = XtCreateWidget(name, formWidgetClass, ...);
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.  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.  Keyboard Traversal

Users can traverse among Text and TextField widgets within any ancestor ControlArea, BulletinBoard, or Form widget using the NEXTFIELD and PREVFIELD keys:

—NEXTFIELD moves the caret to the next traversable Text or TextField widget in the managing ancestor widget.  When the caret is in the last traversable field, NEXTFIELD moves the caret to the first traversable field. 

—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. 

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.  Form Coloration

The diagram Form Coloration illustrates the resources that affect the coloration of the Form widget. 

  Figure 1 Form Coloration

RESOURCES

  Table 1 Form Resource Set Form Resource Set\\∗(cO
                Name            Type       Default   Access XtNancestorSensitive         Boolean          TRUE       G∗
       XtNbackground           Pixel         White  SGI†
 XtNbackgroundPixmap          Pixmap        (none)  SGI†
      XtNborderColor           Pixel         Black  SGI†
     XtNborderPixmap          Pixmap        (none)  SGI†
      XtNborderWidth       Dimension             0      SGI
            XtNdepth             int    (parent’s)       GI
  XtNdestroyCallback  XtCallbackList          NULL       SI
           XtNheight       Dimension  (calculated)      SGI XtNmappedWhenManaged         Boolean          TRUE      SGI
        XtNsensitive         Boolean          TRUE      GI∗
 XtNtraversalManager         Boolean         FALSE      SGI
         XtNuserData       XtPointer          NULL      SGI
            XtNwidth       Dimension  (calculated)      SGI
                XtNx        Position             0      SGI
                XtNy        Position             0      SGI

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\\∗(cO
            Name     Type   Default  Access
    XtNxAddWidth  Boolean     FALSE     SGI XtNxAttachOffset      int         0     SGI
 XtNxAttachRight  Boolean     FALSE     SGI
      XtNxOffset      int         0     SGI
     XtNxRefName   String      NULL     SGI
   XtNxRefWidget   Widget    (form)     SGI
   XtNxResizable  Boolean     FALSE     SGI
  XtNxVaryOffset  Boolean     FALSE     SGI
   XtNyAddHeight  Boolean     FALSE     SGI XtNyAttachBottom  Boolean     FALSE     SGI XtNyAttachOffset      int         0     SGI
      XtNyOffset      int         0     SGI
     XtNyRefName   String      NULL     SGI
   XtNyRefWidget   Widget    (form)     SGI
   XtNyResizable  Boolean     FALSE     SGI
  XtNyVaryOffset  Boolean     FALSE     SGI XtNxAddWidth
XtNyAddHeight

Range of Values:

TRUE
TRUE
FALSE

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 ≤ 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
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 XtNxVaryOffset and XtNyVaryOffset 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 XtNxAttachRight (XtNyAttachBottom) (XtNyAttachBottom) and XtNxVaryOffset XtNxVaryOffset (XtNyVaryOffset) (XtNyVaryOffset) resources to TRUE.  TRUE.  A widget can also span the width (height) of the form by setting the XtNxAttachRight XtNxAttachRight (XtNyAttachBottom) (XtNyAttachBottom) resource to TRUE TRUE and the XtNxVaryOffset XtNxVaryOffset (XtNyVaryOffset) (XtNyVaryOffset) resource to FALSE.  FALSE.  XtNxOffset
XtNyOffset

Range of Values:

0 ≤ XtNxOffset
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. 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 XtNxRefWidget or XtNyRefWidget, XtNyRefWidget, is also set, they must agree: the name given in XtNxRefName XtNxRefName or XtNyRefName XtNyRefName must match the name of the identified widget.  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 referred to by name is used.  XtNxResizable
XtNyResizable

Range of Values:

TRUE
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 XtNxVaryOffset (XtNyVaryOffset) (XtNyVaryOffset) resource set to TRUE.  TRUE.  The form keeps track of a widget’s initial size or its size generated through calls to XtSetValues(), XtSetValues(), so that when the form then becomes larger, the widget will grow to its original size and no larger.  XtNtraversalManager

This resource controls whether this widget manages traversal for its descendants.  XtNxVaryOffset
XtNyVaryOffset

Range of Values:

TRUE
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 XtNxAddWidth (XtNyAddHeight) (XtNyAddHeight) resource is FALSE FALSE or to one pixel if XtNxAddWidth XtNxAddWidth (XtNyAddHeight) (XtNyAddHeight) is TRUE.  TRUE. 

Sun Release 4.1  —  Last change: 1/8/90