[UNDER CONSTRUCTION]
[Current contents will be expanded soon ...]

Document Id : $Id: Form.txt,v 1.1.1.1 1996/08/06 05:51:15 toshok Exp $

1. What's a Form widget good for ?

The XmForm widget is a subclass of XmBulletinBoard, hence also of
XmManager.

You can use XmForm to make an area in which other widgets (children
of XmForm) are layed out in a complicated way that you can describe
using a set of so called "constraint resources", combined with a small
number of resources for the XmForm widget itself.

2. What are constraint resources ?

When you put a widget (say a XmLabel) in a XmForm - so the label is
a child of the form - you will be able to specify a number of
additional resources for that widget which would, in other circum-
stances, be meaningless.

An example is XmNtopAttachment. This constraint resource is meaningless
unless the parent widget is an XmForm.

3. Which important resources can I use for layout ?

The constraint resources :
	XmNxAttachment
	XmNxPosition
	XmNxOffset
	XmNxWidget
in which x can be top, bottom, left, right.

Form's special resources :
	XmNrubberPositioning
	XmNfractionBase

Some general resources :
	XmNmarginHeight, ...
	XmNx, XmNy, XmNwidth, XmNheight

4. Inside the widget

4.1 Where is the layout algorithm ?

The layout algorithm is contained in the function XmFormLayout,
which has the following prototype :
	static void
	XmFormLayout(	XmFormWidget f,
			int mode,
			Widget cw,
			XtWidgetGeometry *cg)

The parameters have the following meaning :
- f is the form itself
- mode is an ORred combination of flags such as Mode_Test and Mode_Resize.
- cw and cg are a child widget and its requested geometry, if
  the current geometry change request comes from a child.
  Note that the Intrinsics state explicitly that in this case,
  that the geometry of that child must not be changed from here !
  Infinite loop avoidance...

/* 
 * XmFormLayout() - run the XmForm layout algorithm
 *
 * If Mode_Test is set, then the cw and cg parameters must be valid, and the 
 *      cw widget must be a managed child of form.
 *
 * Mode_Test : used by GeometryManager to see whether a geometry change is ok.
 *      In this case, a widget and its proposed geometry are passed.
 *      XmFormLayout will apply the changes temporarily, and after the layout
 *      algorithm it'll return the resulting geometry of that widget.
 *      GeometryManager will draw its own conclusions.
 *      
 * Testmode can also be run with the form itself as widget being observed.
 *          
 * ParentChangeMode : allow the thing to change the parent's geometry.
 *      Currently always true. 
 *              
 * For this routine, the fields x, y, w, h, preferred_width, and preferred_height
 *      were added to the constraint record, in FormP.h.
 */     


4.2 When is XmFormLayout called ?

4.3 What does XmFormLayout do ?

4.4 Macros used inside the loops

4.5 Use of temporary storage in XmFormLayout

4.6 ???

5. Why can I get a "bailing out" warning ?

The layout algorithm - as described above - doesn't allow us to
calculate a number of times that the loop can be allowed to run.

I at least have no knowledge of a number of loops in which a valid
geometry will always converge. If there would be such a formula,
(please tell me if you know of one), based on e.g. the number of
child widgets, then we could limit the loop to that number.

Whenever the loop would run longer than that number, we would be sure
that the geometry was invalid.

Given the fact that we don't have such a formula, we do the same thing
as Motif does (at least that's what it suggests in the "bailing out"
warning message) and set the maximum to 10000.

6. Why doesn't  the layout algorithm use widget's preferred geometry ?

Simple answer : because we tried, and it doesn't work if you build it
that way.

Complicated answer #1 : because the other widgets have behaviour that
	doesn't allow this, and the behaviour that we're talking about
	is part of the Motif spec. One example is the XmLabel widget's
	behaviour when its label changes, depending on the setting of
	the XmNrecomputeSize resource.

Complicated answer #2 : <<< Need to look this up >>>