.sp 2
.NH 1 "INTRODUCTION"
.XS
\s12\*(SN  INTRODUCTION\s0
.XE
.sp 2
.PP
Programs in the Khoros system all support two types of user interface. 
The first is graphical, mouse-oriented, and runs on workstations supporting 
X Windows, version 11, release 4;  the second is UNIX-like, keyboard oriented, 
and runs on any computer running the UNIX or ULTRIX operating systems.  
The graphical user interface (GUI) used in the Khoros system is often 
referred to as \fIxvforms\fP, or simply the \fIforms\fP, after the name 
of the Khoros library that implements the GUI.  It utilizes the X Toolkit 
and the Athena Widget set to present the user with a hierarchical graphical 
interface to programs.  
Designed to be both flexible and extensible, xvforms provide the user with 
a clear and simple graphical interface, while at the same time providing 
the programmer with a easily maintainable and extensible user interface. 
.PP
On the other hand, the command line user interface (CLUI) provides quick 
and straightforward access to programs to expert users who are accustomed 
to a UNIX-like operating system, and have no need for the mediation of 
a graphical, mouse-driven user interface.  The command line user interface 
is, of course, the only option for those who wish to utilize the Khoros 
system data processing programs on a non-X terminal. 
In either case, automatic generation of code goes far to assist 
the programmer in creating, maintaining, and extending a modular and 
efficient program that is readable and consistent with all other 
applications in the Khoros system.
.PP
"As typically conceived, automatic programming calls for [the] user 
to write a complete specification for what is desired; a completely automatic 
system then generates a program satisfying this specification. Program 
generators of this type have been successfully developed for a number 
of narrow applications.  However, completely automatic programming 
for a broad range of applications is not a realistic near-term goal".  
The user interface code generators for Khoros use the approach of the 
\fIProgrammer's Apprentice\fP, described above; they do not attempt to 
provide a completely automatic system.  Instead, they act as assistants 
to the programmer, by providing intelligent aid in the tasks that prove 
to be repetitive across applications, such as generation of consistently 
formatted manual pages and usage statements, efficient and modular code 
to extract user input from the either the command line or the graphical 
user interface, and C structures to mediate between the application program 
and either type of user interface, as well as the code to properly initialize 
these structures, and generic application drivers with comments that may be 
easily modified as desired by the application programmer. 
.sp 2
.NH 2 "GRAPHICAL USER INTERFACE"
.XS
      \*(SN  GRAPHICAL USER INTERFACE
.XE
.sp
.PP
From the user's point of view, the \fIxvforms\fP user interface is made up
of three distinct parts:  
.br
.in +1i 
1) the \fImaster form\fP,  
.br
2) one or more \fIsubforms\fP, accessible from the master form
.br
3) one or more \fIpanes\fP accessible from within each subform
.in -1i
.sp
The use of such a hierarchical user interface aids the user in categorizing 
problems into classes and subclasses. A key technique to solving problems lies 
in categorization and identification of the problem so that one may then 
reference the relevant parameters and operations; a hierarchical user interface 
aids in the visualization and recall of an effective tree-structure 
organizational system.  
.PP
The graphical user interface (GUI) consists, 
at the highest level, of a \fImaster form\fP. 
This master form contains \fIsubform\fP buttons, each labeled with the 
broadest category of operation that is dealt with in the application program. 
When the user clicks the mouse on the subform button labeled with the desired 
category, a \fIsubform\fP will appear.  This subform 
contains a \fIguide panel\fP to the left, a long panel with buttons labeled 
with each of the subjects that fall in its category.  These \fIguide buttons\fP
are titled with subjects that will each require their own \fIpane\fP in the 
user interface; the user clicks the mouse on the desired \fIguide button\fP 
to bring up the \fII/O pane\fP that they are interested in utilizing. 
.PP
On each individual pane is where most actual I/O takes place -- here,
\fItext selections\fP are provided for entering strings, integers, floats, 
boolean values, input files, and output files.  Any such text selection 
may be made optional, in which case a small box will appear to the left 
of the selection;  the user highlights this box to indicate that they 
wish to utilize the parameter described by the text selection. For most 
situations in an application program, it is necessary for the user to 
enter several values in text selections before initiating an action.  
For these cases, the user may enter values in a pane's
text selections at leisure;  when assured that all parameters are correct,
they click the mouse on an \fIaction button\fP to register the parameters and
perform the desired operation. If, in the application program, the situation
arises that only one input (entered via a text selection) is needed in order 
to perform a certain action, the text selection may be made "live" -- that is,
the desired action is initiated by the user entering the applicable parameter
and hitting the carriage return.  Such "live" text selections are marked by
a stylized <cr> arrow that appears to the right of the text selection, and in
situations where they are appropriate, will reduce the amount of human 
I/O necessary to initiate an action by a factor of two.
.PP
In addition, \fIaction\fP buttons which may be located anywhere on the user 
interface to allow users to perform actions which need no other parameters 
except for registering of the fact that they now wish to perform a particular 
action. When appropriate, action buttons may bring up a \fIlist widget\fP from
which the user may choose one (or more) of several input options using the 
mouse. For entering input files, a \fIfile browser\fP option is provided for 
the convenience of the user who does not wish to remember or type a long 
path name. Feedback messages are provided in pop-up form for error checking
and general user information.  
.PP
In addition to text widgets, \fItoggles\fP are also provided so that the user
may set a parameter to one of a finite number of values.  Toggles may be of
type integer, float, string, input file, or output file.  When a toggle is 
desired, but elements within the proposed toggle are of different types, a 
\fImutually exclusive group\fP may be defined.  Thus, the user may elect to
use one and only one of a number of parameters, each of which may be of a 
different nature.
.PP
\fIHelp\fP buttons provide a mechanism for the user to access
on-line help appropriate to the location in the user interface on 
which it is found.  Since a master form is at the top of the user hierarchy, 
help here should be of the most general kind.  Help found on each subform 
and purpose of that particular subform, while help buttons on each subordinate
pane will explicitly describe the proper use of the parameters on that pane.
.sp 2
.NH 2 "COMMAND LINE USER INTERFACE"
.XS
      \*(SN  COMMAND LINE USER INTERFACE
.XE
.sp
.PP
The command line user interface (CLUI) is supported by all Khoros programs.
It is the only user interface for those who do not have access to 
graphics workstations supporting X Windows.  The command line
user interface is modeled after the basic style for most UNIX 
commands.  The program name is typed in after the prompt, followed 
by appropriate \fI-flags\fP.  The special flag [-U 1] gives the usage 
for each program, and all programs have man pages providing complete 
information on each program.  Some flags are required for each program, 
and the omission of these flags will generate an appropriate error message.  
Other flags are optional; if omitted, default values will be used.  
All programs in the Khoros data processing libraries may be run solely 
from the command line; the command line user interface may be 
run in three different modes:
.sp
.IP "UNIX standard format:"
The user specifies the program name, followed by of flags specified as 
indicated in the usage statement (this is the default mode).
.sp
.IP "Interactive prompting:"
The user specifies the program name followed by the [-P 1] 
flag, indicating that they wish to be interactively prompted for input
.sp
.IP "Answer file:"
The user performs one input sequence, as described by either (1) or
(2) above, and in addition, specifies the [-A 1] flag, which will create an 
ascii answer file for the program being used.  Later, duplicate runs of the 
program with the same same input may be performed by specifying the program 
name followed by the [-a *.ans] flag, indicating that the previously-created 
answer file is to be referenced for input (where * stands for the program name).
.LP
For more information on input/output conventions, see khoros(1).
.sp 2
.NH 2 "USER INTERFACE SPECIFICATION FILE"
.XS
      \*(SN  USER INTERFACE SPECIFICATION FILE
.XE
.sp
.PP
Both the \fIxvforms\fP graphical user interface and the command line
user interface for a program are defined via a User Interface Specification
(UIS) file. This specification is made up of a series of strictly
defined lines, each of which describe a specific part of the user interface.
The UIS was designed at a high level of abstraction; each type of 
line contains the information necessary to completely describe that 
type of item in the \fIxvforms\fP graphic user interface, as well as in the 
command-line user interface.  Thus, from a single UIS
file for a particular application, the code for both the CLUI 
and the GUI may be generated directly (\fIvroutines\fP always use the same
UIS file for both their CLUI and their GUI; however, \fIxvroutines\fP
usually have two UIS files).  
.PP
There are two code generation programs included in Khoros:  \fBghostwriter\fP and
\fBconductor\fP.  The first, \fBghostwriter\fP, generates the code that defines, 
initializes, and extracts information from the user via the CLUI.  
In addition, \fBghostwriter\fP helps you to generate the main driver 
for the program, as well as an include file, man pages, and a skeleton library 
file if desired.  \fBGhostwriter\fP is used to create & maintain \fIALL\fP 
programs under the Khoros system.
.PP
The second, \fBconductor\fP, must be used by all \fIxvroutines\fP (except
\fBcantata\fP). \fIXvroutines\fP always have a GUI \fIwhen executed from 
the command line\fP.  For example, some of the Khoros \fIxvroutines\fP which
are required to use \fBconductor\fP are \fBxprism2, xprism3\fP and 
\fBeditimage\fP.  These programs may be executed from within \fBcantata\fP or 
from the command line; however, regardless of where they may be executed from,
they will always have a graphical user interface.  Contrast these applications 
with Khoros \fIvroutines\fP: such programs as \fBvadd\fP, \fBvdiv\fP, 
and \fBvblend\fP.  The latter programs may also be executed from within 
\fBcantata\fP or from the command line; but when they are executed from 
the command line, they will never have a graphical user interface;  
the graphical user interface for these programs comes solely from their 
inclusion into the \fBcantata\fP visual language.  Programmers of such 
vroutines do not to use \fBconductor\fP for code generation;  the use of 
\fBghostwriter\fP is sufficient.
.PP
The standard procedure is \fIalways\fP to use the \fBghostwriter\fP program to
generate a CLUI for the program.  If the program is an xvroutine, the 
\fBconductor\fP code generation program will also be used, and the program driver
created by \fBghostwriter\fP will be integrated with the main user interface
driver created by \fBconductor\fP.  For more information about this, see
the section on "Writing Programs" in Chapter 1 of the Khoros Programmer's Manual,
Chapter 5 in the Khoros Programmer's Manual on "Ghost Routines", and Chapter
6 of the Khoros Programmer's Manual on "Conductor".
.PP
A popular approach to software engineering states that one should completely
define all requirements, parameters, and I/O mechanisms before beginning 
the implementation of a software project.  However, this assumption is not
realistic; in practice, one quickly finds that requirements change 
continually, often in response to organizational change.  These changes are 
more likely to result from experience in the use of the system and feedback
from users than from an abstract specification in the early design of the system.
.PP
Keeping this reality in mind, both \fBconductor\fP and \fBghostwriter\fP were 
developed specifically to minimize the amount of work necessary to do 
maintenance on the application programs.  The user interface code is separated 
from the actual "working" code of the application program.  Both code generators
were implemented to function both as design tools and as maintenance tools;
once you have begun to add to or modify the existing user 
interface specification, either program may be re-run to update the existing 
structures and extraction code.  Therefore, the code generation programs are not 
only an important aid in the initial development of an application program;  
they are valuable tools for the ongoing maintenance of such programs.  
Together, they will free you from implementation of user interfaces altogether,
and allow you to spend your time implementing the functionality of the 
application programs.  
.sp 2
.NH 2 "UIS FILE INTERPRETER"
.XS
      \*(SN  UIS FILE INTERPRETER
.XE
.sp
.PP
The first task that faces you when you wish to create a program under the
Khoros system is to develop the UIS file that specifies the command line
and graphical user interface for your program.  Whether your program is 
to be a vroutine or an xvroutine, you will need to see how the graphical 
user interface specified by your UIS file looks; the forms 
will be displayed either when your program is accessed through 
\fBcantata\fP (if you are writing a vroutine) or every 
time it is executed (if you are writing an xvroutine).
.PP
There is an interactive GUI specification interpreter to aid 
you in prototyping the desired \fIxvform\fP user interface.  
The \fBpreview\fP program takes as input a UIS file, and displays the 
\fIforms\fP as specified therein, in an active but non-functional state.  
Thus, you may develop the entire GUI for
an application before attempting to write any of the code that will actually 
make the program functional;  this approach is conducive to the design of 
well-defined, carefully planned applications.  
.PP
\fBPreview\fP allows you to repeatedly perform the two-step process involved 
in prototyping a GUI: (1) to edit the UIS file using a visual editor, 
and (2) to display the forms defined in the UIS file, in order to 
visually determine whether or not the UIS file is correct.  Some error checking 
on the UIS file is done, and the you will be informed if lines in the 
UIS file have incorrect syntax, or are out of place.  Furthermore, any 
mistakes made in geometry specifications will be immediately obvious for 
quick correction.
.sp 2
.NH 2 "CODE GENERATOR FOR THE GUI OF XVROUTINES"
.XS
      \*(SN  CODE GENERATOR FOR THE GUI OF XVROUTINES
.XE
.sp
.PP
Once the UIS file has been created and judged satisfactory
for your specific xvroutine, you will run \fBconductor\fP to generate the 
driving code that will control the \fIxvforms\fP user 
interface.  All aspects of the user interface code are created and
managed by the execution of this program.  The first time the code generator
is run, a user interface driver is generated automatically, so that you
need not worry about the links between your application and the 
\fIxvforms\fP library - it is all done for you, with comments indicating
places into which you should insert your own code.  The code generated
includes the C structure which provides the link between the xvroutine and
the GUI, the C code to initialize this structure, and the C code
to extract information from the GUI and update this structure.
Later, when maintenance becomes the issue of concern, \fBconductor\fP 
is re-run to update the latter three files.  Adding to, modifying, re-arranging, 
or deleting elements from the GUI becomes a trivial task with the 
use of \fBconductor\fP generator - you are now free to focus on the 
implementation of the code that will give your xvroutine its functionality.
.sp 2
.NH 2 "CODE GENERATOR FOR THE CLUI OF ALL KHOROS PROGRAMS"
.XS
      \*(SN  CODE GENERATOR FOR THE CLUI OF ALL KHOROS PROGRAMS
.XE
.sp
.PP
The UIS file also serves as the specification for the command line user 
interface.  All aspects of the CLUI code are generated by \fBghostwriter\fP. 
Code generated by \fBghostwriter\fP  includes the C structure which 
mediates between the Khoros program and the CLUI, as well as code to 
get information from the command line, and print out the usage of the program.  
A man1 page is also automatically generated.  If desired, other items may 
also be generated by the comprehensive \fBghostwriter\fP code generation tool.  
Initially, it is useful to have an Imakefile and corresponding Makefile 
created for the new program.  If the new program is to be part of the 
Khoros Image Processing Library (vipl), Digital Signal Processing Library (dspl),
File Formatting (Conversion) Library, Remote Sensing/GIS Library, or Numerical
Analysis Library, the library file should also be generated for use, along 
with its man3 page.  In short, \fBghostwriter\fP can generate all the code 
necessary for a new command line interfaced Khoros program, excepting the 
code that actually provides the functionality.
.PP
In addition to the UIS file, \fBghostwriter\fP
may also take as input a Program Specification (PS) file.  In this 
file, you may provide program specifications that cannot 
be detailed in the UIS file, such as program header 
documentation, syntax for the library call, and specific code segments that you 
wish to appear in the application program.  When \fBghostwriter\fP 
is run for the first time, a template of PS file is generated.  You
may then update this PS file, re-run the code generator, 
and all information given in the PS file will appear in its 
proper place within  the man pages and C code of your program.  
The generated CLUI code is augmented with automatic error checking 
generated according to the UIS file, and documented with text segments 
taken from the PS file.  When maintenance becomes an issue, all that is
necessary is to update either the PS file, the UIS file, or both -- 
\fBghostwriter\fP may be then be re-run to update the C code that controls the 
command line user interface.  The use of the PS file promotes standardized 
styles and methods of programming, and encourages consistent
implementation across the Khoros System.  
.PP
Most people, however, do not feel as comfortable modifying the PS 
file as they do modifying the source code and man pages directly.  
To many, the former method may seem unnatural. To further aid in maintanence 
of a complex system of application programs, the PS file may also be 
automatically generated by \fBghostwriter's\fP counterpart - \fBghostreader\fP.
When modifications are made to the man pages or C code discussed above, 
\fBghostreader\fP may be run to update the PS file.  Thus, the direction of 
automatic CLUI code generation is bi-directional -- you may update the PS file
and run \fBghostwriter\fP to update the C code and manual pages, or you may 
elect to use the opposite approach, updating the C code and manual pages 
and running \fBghostreader\fP to automatically update the PS file.  Since the 
creation of the \fBghostreader\fP and \fBghostwriter\fP programs, most members 
of the Khoros group have found that a combination of the two methods is most 
realistic:  when modifying C code, the actual source code is updated, followed 
by a run of \fBghostreader\fP;  when modifying man pages, the PS file is 
updated, followed by a run of \fBghostwriter\fP.  
.PP
All that is necessary to maintain an effective and up-to-date programming 
environment for any number of application programmers is to ensure that both the
PS file and the automatically generated code are current at any given time.
To help you in remembering which files have been updated most
recently, the \fIBhostcheck\fP program is often useful.  
\fBGhostcheck\fP is a simple-minded shell script which checks the dates on 
the pertinent files.  Based on these dates, \fBghostcheck\fP will give advice 
to help you in deciding what to do next.  It is most helpful to when you
have forgotten where you were last time you worked on your program, or when you
are maintaining code that was originally written by someone else.
