NAME

Form − form widget

SYNOPSIS

#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xol/OpenLook.h>
#include <Xol/Form.h>
 . . .
Widget my_form, my_parent;
String my_name;
ArgList args;
Cardinal num_args;

my_form =  XtCreate( my_name, formWidgetClass,

my_parent, args, num_args);

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. 

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.

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

Child Management

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. 

Limitations

The Form composite widget works with all the widgets defined in this document, except those that are sub-classed from the Shell widget class. 

Coloration

of the Form widget. 

  Figure 1 Form Coloration

RESOURCES

  Table 1 Form Resource Set

Form                 Resource       Set
Name                 Type           Default             Access
 
XtNancestorSensitive Boolean        TRUE                GO
XtNbackground        Pixel          XtDefaultBackground SGI
XtNbackgroundPixmap  Pixmap         (none)              SGI
XtNborderColor       Pixel          XtDefaultForeground SGI
XtNborderPixmap      Pixmap         (none)              SGI
XtNborderWidth       Dimension      0                   SGI
XtNconsumeEvent      XtCallbackList NULL                SG
XtNdepth             int            (parent’s)          GI
XtNdestroyCallback   XtCallbackList NULL                SI
XtNheight            Dimension      (calculated)        SGI
XtNmappedWhenManaged Boolean        TRUE                SGI
XtNsensitive         Boolean        TRUE                GIO
XtNtraversalManager  Boolean        FALSE               SGI
XtNuserData          XtPointer      NULL                SGI
XtNwidth             Dimension      (calculated)        SGI
XtNx                 Position       0                   SGI
XtNy                 Position       0                   SGI

Access:S = XtSetValues G = XtGetValues
        I = init timeO = other access
† see resources(3W)

Child Constraints

Each child widget attached to the Form composite widget is constrained by the resources detailed in the following table.  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. 

  Table 2 Form Child Constraining Resources

Child            Constraint Resource Set
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

Access:S = XtSetValues G = XtGetValues
        I = init timeO = other access

XtNxAddWidth

class:XtCXAddWidth type:Boolean default:FALSEaccess:SGI class:XtCYAddHeight type:Boolean default:FALSEaccess:SGI

Action: indicate whether to add the width or height of the corresponding reference widget to a widget’s location when determining the widget’s position. 

Values: TRUE, FALSE

XtNxAttachOffset

class:XtCXAttachOffset type:int default:0access:SGI class:XtCYAttachOffset type:int default:0access:SGI

Action: determine separation between Form widget and children. 

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

class:XtCXAttachRight type:Boolean default:FALSEaccess:SGI class:XtCYAttachBottom type:Boolean default:FALSEaccess:SGI

Action: set the reference direction on the form

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 XtNxVaryOffset and XtNyVaryOffset, these resources allow a widget to float along the right or bottom edge of the form. 

In the x–direction, this is done by setting both the XtNxAttachRight and XtNxVaryOffset resources to TRUE A widget can also span the width of the form by setting the XtNxAttachRight resource to TRUE and the XtNxVaryOffset resource to FALSE. 

In the y–direction, this is done by setting both the XtNyAttachBottom and XtNyVaryOffset resources to TRUE A widget can also span the height of the form by setting the XtNyAttachBottom resource to TRUE and the XtNyVaryOffset resource to FALSE. 

XtNxOffset

class:XtCXOffset type:int default:0access:SGI class:XtCYOffset type:int default:0access:SGI

Action: define the offset from reference widget. 

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. 

XtNxRefName

class:XtCXRefName type:String default:NULLaccess:SGI class:XtCYRefName type:String default:NULLaccess:SGI

Action: specify reference widget by name. 

Values: 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. 

XtNxRefWidget

class:XtCXRefWidget type:Widget default:(form)access:SGI class:XtCYRefWidget type:Widget default:(form)access:SGI

Action: specify reference widget by id. 

Values: 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

class:XtCXResizable type:Boolean default:FALSEaccess:SGI class:XtCYResizable type:Boolean default:FALSEaccess:SGI

Action: specify whether the Form resizes children. 

Values: TRUE, FALSE

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, or 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. 

XtNtraversalManager

class:XtCTraversalManager type:Boolean default:FALSEaccess:SGI

Action: controls whether widget manages traversal for descendants. 

XtNxVaryOffset

class:XtCXVaryOffset type:Boolean default:FALSEaccess:SGI class:XtCYVaryOffset type:Boolean default:FALSEaccess:SGI

Action: specify variable spacing between widget and reference widget. 

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. 
 

Version 3.0  —  Last change: 19 July 91  —  Last change: 19 July 91