Volume 6A: Motif Programming Manual

reject the resize request of the child that started all the negotiation. Geometry management is by no means a simple

task; it is explained more completely in Volume Four, X Toolkit Intrinsics Programming Manual.

9.4 The Form Widget

The Form widget is subclassed from the BulletinBoard class, so it inherits all of the resources that the BulletinBoard

has to offer. Accordingly, the children of a Form can be placed at specific x,y coordinates and geometry management

can be performed as in the source code However, the Form provides additional geometry management features that

allow its children to be positioned relative to one another and relative to specific locations in the Form.

In order to use a Form, you must include the file <Xm/Form.h>. A Form is created in a similar way to other manager

widgets, as shown below:

Widget form;

form = XtVaCreateWidget ("name",

xmFormWidgetClass, parent,

resource−value−list,

NULL);

/* create children */

XtManageChild (form);

9.4.1 Form Attachments

Geometry management in a Form is done using attachment resources. These resources are constraint resources, which

means that they are specified for the children of the Form. The resources provide various ways of specifying the

position of a child of a Form by attaching each of the four sides of the child to another entity. The side of a widget can

be attached to another widget, to a fixed position in the Form, to a flexible position in the Form, to the Form itself, or

to nothing at all. These attachments can be considered hooks, rods, and anchor points, as shown in the figure.

9 Manager Widgets 9.4 The Form Widget

207

Attachments in a Form

In this figure, there are three widgets. The sizes and types of the widgets are not important. What is important is the

relationship between the widgets with respect to their positions in the Form. Widget 1 is attached to the top and left

sides of the Form by creating two attachments. The top side of the widget is hooked to the top of the Form. It can slide

from side to side, but it cannot be moved up or down (just like a shower curtain). The left side can slide up and down,

but not to the right or to the left. Given these two attachment constraints, the top and left sides of the widget are fixed.

The right and bottom edges of the widget are not attached to anything, but other widgets are attached to those edges.

The left side of Widget 2 is attached to the right side of Widget 1. Similarly, the top side of Widget 2 is attached to

the top side of Widget 1. As a result, the top and left sides of the widget cannot be moved unless Widget 1 moves.

The same kind of attachments hold for Widget 3. The top side of this widget is attached to the bottom of Widget 1

and its left side is attached to the left side of Widget 1. Given these constraints, no matter how large each of the

widgets may be, or how the Form may be resized, the positional relationship of the widgets is maintained.

In general, you must attach at least two adjacent edges of a widget to keep it from moving unpredictably. If you attach

opposing sides of the widget, the widget will probably be resized by the Form in order to satisfy the attachment

policies. The following resources represent the four sides of a widget:

XmNtopAttachment

XmNbottomAttachment

XmNrightAttachment

XmNleftAttachment

For example, if we want to specify that the top of a widget is attached to something, we use the

XmNtopAttachment resource. Each of the four resources can be set to one of the following values:

9 Manager Widgets 9.4 The Form Widget

208

XmATTACH_FORM

XmATTACH_OPPOSITE_FORM

XmATTACH_WIDGET

XmATTACH_OPPOSITE_WIDGET

XmATTACH_NONE

XmATTACH_SELF

XmATTACH_POSITION

When an attachment is set to XmATTACH_FORM, the specified side is attached to the Form as shown in the figure. If

the resource that has this value is XmNtopAttachment, then the top side of the widget is attached to the top of the

Form. The top attachment does not guarantee that the widget will not move from side to side. If

XmNbottomAttachment is also set to XmATTACH_FORM, the bottom of the widget is attached to the bottom side

of the Form. With both of these attachments, the widget is resized to the height of the Form itself. The same would be

true for the right and left edges of the widget if they were attached to the Form.

XmNtopAttachment set to XmATTACH_FORM

When an attachment is set to XmATTACH_OPPOSITE_FORM, the specified side of the widget is attached to the

opposite side of the Form. For example, if XmNtopAttachment is set to XmATTACH_OPPOSITE_FORM, the top

side of the widget is attached to the bottom side of the Form. This value must be used with a negative offset value

(discussed in the next section) or the widget is placed off of the edge of the Form and it is not visible. While it may

seem confusing, this value is the only one that can be applied to an attachment resource that allows you to specify a

constant offset from the edge of a Form. The XmATTACH_WIDGET value indicates that the side of a widget is

attached to another widget. The other widget must be specified using the appropriate resource from the following list:

XmNtopWidget

XmNbottomWidget

XmNleftWidget

XmNrightWidget

The value for one of these resources must be the widget ID. For example, the figure shows how to attach the right side

of Widget 1 to the left side of Widget 2. This attachment method is commonly used to chain together a series of

adjacent widgets. Chaining widgets horizontally does not guarantee that the widgets will be aligned vertically, or vice

9 Manager Widgets 9.4 The Form Widget

209

versa.

XmNrightAttachment set to XmATTACH_WIDGET

The XmATTACH_OPPOSITE_WIDGET value is just like XmATTACH_WIDGET, except that the widget is attached to

the same edge of the specified widget, as shown in the figure. In this case, the right side of Widget 1 is attached to the

right side of Widget 3. This attachment method allows you to align the edges of a group of widgets. As with

XmATTACH_WIDGET, the other widget must be specified using XmNtopWidget, XmN-bottom-Widget,

XmNleftWidget, or XmNrightWidget.

XmNrightAttachment set to XmATTACH_OPPOSITE_WIDGET

9 Manager Widgets 9.4 The Form Widget

210

XmATTACH_NONE specifies that the side of a widget is not attached to anything, which is the default value. This case

could be represented by a dangling hook that is not attached to anything. If the entire widget moves because another

side is attached to something, then this side gets dragged along with it so that the widget does not need resizing.

Unless a particular side of a widget is attached to something, that side of the widget is free−floating and moves

proportionally with the other parts of the widget. When the side of a widget is attached using

XmATTACH_POSITION, the side is anchored to a relative position in the Form. This value works by segmenting the

Form into a fixed number of equally−spaced horizontal and vertical positions, based on the value of the

XmN-fraction-Base resource. The position of the side must be specified using the appropriate resource from the

following list:

XmNtopPosition

XmNbottomPosition

XmNleftPosition

XmNrightPosition

See Section #sformpos for a complete discussion of position attachments. When an attachment is set to

XmATTACH_SELF, the side of the widget is attached to its initial position in the Form. You position the widget

initially by specifying its x,y location in the Form. After the widget has been placed in the Form, the attachment for

the side reverts to XmATTACH_POSITION, with the corresponding position resource set to the relative position of the

x,y coordinate in the Form. Now that we have explained the concept of Form attachments, we can reimplement the

four corners example from the previous section. Unlike in the previous version, we no longer need a resize procedure

to calculate the positions of the widgets. By specifying the correct attachments, as shown in the source code the

widgets are placed and managed correctly by the Form when it is resized. XtSetLanguageProc() is only

available in X11R5; there is no corresponding function in X11R4.

/* form_corners.c −− demonstrate form layout management. Just as

* in corners.c, there are four widgets each labeled top−left,

* top−right, bottom−left and bottom−right. Their positions in the

* form correspond to their names. As opposed to the BulletinBoard

* widget, the Form manages this layout management automatically by

* specifying attachment types for each of the widgets.

*/

#include <Xm/PushB.h>

#include <Xm/Form.h>

char *corners[] = {

"Top Left", "Top Right", "Bottom Left", "Bottom Right",

};

main(argc, argv)

char *argv[];

{

Widget toplevel, form;

XtAppContext app;

XtSetLanguageProc (NULL, NULL, NULL);

toplevel = XtVaAppInitialize (&app, "Demos", NULL, 0,

&argc, argv, NULL, NULL);

form = XtVaCreateManagedWidget ("form",

xmFormWidgetClass, toplevel, NULL);

/* Attach the edges of the widgets to the Form. Which edge of

* the widget that's attached is relative to where the widget is

* positioned in the Form. Edges not attached default to having

* an attachment type of XmATTACH_NONE.

9 Manager Widgets 9.4 The Form Widget

211