Building jxlayout

    If you downloaded the link-kit, simply type "Link" to create the binaries.
(I cannot distribute statically linked binaries because that would force me to
place the source under the GPL.)

Changes from previous versions

1.0.6
    If the new header file is identical to the old one, it is left untouched to
avoid unnecessary recompilation.

fdesign

    fdesign is the widget layout editor written for use with the XForms library.
We are providing it only as a convenience (We could simply have told you where
to download it.)  and only because we have not had time to write our own widget
layout editor yet.  The documentation for fdesign is available on the web at

    http://www.westworld.com/~dau/xforms/node4.html#SECTION04000000000000000000

and via ftp from

    ftp://bragg.phys.uwm.edu/pub/xforms/

    There are two important points to keep in mind when using fdesign.  First,
the widgets that fdesign provides are those that XForms provides.  These are not
identical to the JX widgets.  The file jxlayout.class.map shows which XForms
widgets map to JX widgets.  The first column is the type selected in the fdesign
control window.  The second column is the type selected in the Options dialog
window obtained by right-double-clicking on the widget.

    The second point to remember is that you should not use the big arrow button
in the upper right corner of the Options dialog window because jxlayout cannot
parse what it produces.

jfdesign

    This script file runs fdesign with the options that are appropriate for
generating an .fd file for use with jxlayout.  The script assumes that fdesign
is on your search path.

jxlayout

    jxlayout was written to generate code for JX from an fdesign file.  It is a
simple, text-based program that generates C++ code to construct the Widgets and
arrange them in the Window.  The best way to understand how jxlayout works is to
study testjx.fd and the associated code.

    Since each Window should have its own custom WindowDirector, Document, or
DialogDirector, the creation and layout code is only a small part of the total
code required.  The rest of the code must be written by hand.  As an example, a
class MyDialog derived from DialogDirector requires at least a constructor, a
destructor, and methods for retrieving the information when the Window is
closed.  In order to retrieve this information, the relevant objects in the
window must be declared as instance variables.  This, in turn, requires that the
header file for MyDialog be directly modified by jxlayout.  In addition, it is
most convenient if the source code can also be placed directly in the source
file for MyDialog.  This is accomplished by delimiting a region of the source
and header files for explicit use by jxlayout.  The region begins with "// begin
JXLayout" and ends with "// end JXLayout".  jxlayout replaces everything inside
this region with code generated from the .fd file.  This code can, of course, be
part of a larger routine.  To create additional Widgets (e.g. menus) or adjust
the initial values of Widgets constructed by jxlayout, simply append this code
to the routine after the "// end JXLayout" delimiter.  Note that jxlayout makes
a backup (file -> file~) of each file that it modifies.

    Unnamed objects in the .fd file are assigned unique, arbitrary names in the
resulting C++ code.  Named objects are considered to be instance variables and
are declared in the header file.  If one needs to refer to an object inside the
routine, but nowhere else, one can enclose the name in parentheses (e.g.
(okButton)).  Thus, unlike unnamed objects, the name will not be arbitrary, but
it will be declared locally in the routine instead of at class scope in the
header file.  If one needs to use a local variable that has already been
declared, one can enclose the name in brackets.  This is primarily useful for
arrays (e.g. <radioButton[2]>).

    jxlayout.class.map defines how objects that fdesign understands map to JX
classes.  Classes that are not listed in this file and custom classes derived
from JXUserWidget can be included in the .fd file by creating an fdesign box
object of type NO_BOX and setting the label to be the name of the JX class.  The
most common examples are JXMenuBar and JXScrollbarSet.  Custom classes usually
require extra arguments in the constructor.  This can be handled by placing
these arguments first, and then using "MyWidget(arg1,arg2," as the label.
jxlayout will append the standard arguments in order to complete the
constructor.  (Such code will obviously not compile unless arg1 and arg2 are
defined before the "// begin JXLayout" delimiter.)

    A Widget's container is calculated by finding the smallest Widget that has
already been encountered in the .fd file and that contains the new Widget.
jxlayout translates the XForms gravity specifications into JX resizing options.
NoGravity translates to elastic resizing.  To fix the top edge, add North to the
NWGravity.  To fix the left edge, add West to the NWGravity.  To fix the bottom
edge, add South to the SEGravity.  To fix the right edge, add East to the
SEGravity.

    The code generated in the region delimited by "// begin JXLayout" and "//
end JXLayout" always starts with the creation of a JXWindow object.  If you want
to create a layout for the inside of a JXWidget (e.g. each page of a
JXCardFile), you can create a new form in fdesign, give it the same name, and
then specify a different tag to look for in the source and header files by
appending "--tag--encl" to the name of the form.  As an example, the form called
"MyDirector" will generate code in MyDirector.cc and MyDirector.h between "//
begin JXLayout" and "// end JXLayout", and all Widgets will be constructed with
window as their enclosure.  The form called "MyDirector--sub1--MyWidget" will
generate code in MyDirector.cc and MyDirector.h between "// begin sub1" and "//
end sub1", and all Widgets will be constructed with MyWidget as their enclosure.

    You can also specify extra constructor arguments for the JXWindow objects
that are created with the JXLayout tag by appending "JXLayout<"title">" or
"JXLayout<"title", ownsColormap, colormap>" to the name of the form.  The
default is to construct the window with:

    new JXWindow(this, w,h, "");

    With "JXLayout<"title">", this becomes:

    new JXWindow(this, w,h, "title");

    With "JXLayout<"title", ownsColormap, colormap>", this becomes:

    new JXWindow(this, w,h, "title", ownsColormap, colormap);

    The first option allows you to specify the window title without having to
call SetTitle().  The second option allows you to construct a JXWindow with a
private colormap.  (Refer to the TestDirector class in the testjx application
for an example of this last option.)

    The callback argument field in fdesign is used to set the ID of
RadioButtons.
