Subject: Free Motif GUI Builder - Runs or use for Parts
This first revision corrects handling of double-click buttons,
provides an equivalent of the Microsoft Windows Combo Box,
also has minor improvements to Balloon Help and other parts.

Porting Issues:
I am not yet an Imake person, so some hand-work may be needed.

I corrected some things that compiled OK on SGI but nowhere else.
I only have the SGI so I hope I corrected them all as reported.

I use the new ANSI style syntax and function calling prototypes.
You will need to set suitable compiler options, and I would very
much appreciate it if you tell me what works on your system.

I compile with -DFUNCPROTO and -prototypes and get no warnings,
but -fullwarn gives reams of "int vs unsigned int" messages.

Beware the two versions (BSD vs SYSV) of regular expressions!
Compile with the proper flag defined and use the right library.
Both the flag and library location may depend on your system.

A good clue of BSD vs SVSV trouble is clipped file names in Open.

The routine timestamp.c calls the asfctime utility you may not have.
You can use anything here that produces a date-time stamp string,
or you can just dummy it.  It gets written into comment lines in
the generated files, but nothing at all depends on it.

Summary:
It is toolkit-independent but it currently generates only Motif.
I have no immediate plans to write other toolkit back-ends.
Someone else is quite welcome to write another back-end though.
While I would of course appreciate bug reports and suggestions,
I make no guarantee of timely response to any of them.

Description:
First it reads a toolkit-independent UI description ascii text file.

You describe your UI as an AND / OR tree, in which each OR is a Menu,
while each AND is a Dialog Box.  These in turn are filled with input
elements named in generic terms like CHOICES, CHOOSE_ONE, BOOLEAN.

Elements have both required and optional attributes like INIT_VALUE,
ACTION, MIN / MAX and ENABLE that you specify as snippets of C code,
or as names of external functions you will link.

Every element can (should) name a short help file, in which the first
paragraph will serve as "Balloon Help" as well as an introduction.

The spec is repackaged a bit as an array of a big structure,
and written to an include file that gets used in your Makefile.
Somewhat like Heller's menu-builder but lots more stuff in the struct,
hooks to variously enable and disable parts of the UI and so forth.

At runtime your existing code declares a main window and menubar,
and whatever else it wants to draw, and then calls the gui_init to
populate the menubar as specified.

Init generates all the top level menubar buttons and their pulldowns
and dialog boxes, also a toolbar (I don't think anyone "owns" that name)
and a separate popup menu for the drawing area if you want that.

The menubar will include a standard File menu if you provide a file
selection pattern, and the C code for whatever Open and Save do.

Also a standard Help menu with an Index of all the individual topics,
a toggle for Balloon Help, and a few other things.

The Motif calls go with default resources as much as possible,
to stay out of the way of resource files, and all file access for
help text and error messages use the Motif file-getter that looks
where your resources tell it to look.  This should be enough to
support Western (single byte) languages, I think.

I tried to generate the internal Widget names consistently to make
it easy to write resource files.  Hack this if it helps you.

Important Note Before You Begin:
The UI description TEXT file is how you design a menu interface.
There could be, but is NOT, a graphical tool to create this file.
Because the file is toolkit-independent, it is NOT "UIL" format.
You need never see the word Widget or any resource name or value.
I have found the textual "actions" to be the largest part of things,
and the graphical layout to be more a distraction than an issue.
If you disagree this is not the tool for you.

Legalities:
The work is essentially a lengthy example of some known techniques,
and is presented with the same rights and limits as a book example:

1. You are free to copy, modify, and include it in your larger works,
for any reason including sale of the larger work for profit.
(Otherwise it wouldn't be good for much but playing.)
2. You may not sell what is essentially just the work given to you,
for example a "cleaned up" version with more comments or bug fixes.
A graphical tool to create the specification file, or a back-end for
Athena or another free toolkit, or for MS-Windows, would be examples of
substantial new work, that you could sell, rather than give away,
if you wanted to.  (But I can still give this or later versions away.)
If you have any doubts:
 a) ask me,
 b) obtain qualified legal advice,
 c) ask my friends how I behave when I'm upset.
3. You have the right to see this work because:
 a) it was paid for by your taxes,
 b) there is no reason to keep it from you.
4. You have no right to support or upgrades.
(But of course you still have the right to ask for them, and I will do
what I can to respond, subject to other responsibilities.)
5. There is no guarantee of correctness or suitability.  As source code
is provided, you are advised to study it carefully.

(I bet that lawyers love writing this stuff, and smile when they think
noone is watching them!)

Acknowledgement:
Thanks to the many kind folks who post answers with example code!
In particular, thanks to Danny Backx for clear examples.

Runs or use for Parts:
You may find it most useful as a bunch of examples.  Fine with me.

How to get it:
This file UITOC.README and compressed archive UITOC.tar.Z
are available from ftp.x.org in contrib.  The archive will provide
further README information.

Morris Hirsch aka morris@sg25.npt.nuwc.navy.mil 401-841-7800

Greetings from Rhode Island. "You Get Used To It!"