.sp 2
.NH 1 "WRITING AN XVROUTINE"
.XS
\s12\*(SN  WRITING AN XVROUTINE\s0
.XE
.sp
.PP
The information provided in this section concerns the process of
writing an xvroutine.  This is prefaced by an outline of the steps
involved in writing an xvroutine, followed by more detailed information
concerning each step in the process.  
.IP
The first thing that you must do when preparing to create a new program
under Khoros is to decide on a \fItoolbox\fP that the new routine will
belong to.  If the toolbox does not exist, you must create one.  For example,
if you are writing an interactive application for medical imaging, you might 
create a "medical_imaging" toolbox; all programs written to address medical imaging
problems would then be added to the "medical_imaging" toolbox.  For complete
instructions on creating and using a toolbox, please see Section I.
.IP 
\fB1) Creating the *.pane file - \fP Create the UIS file (ie, *.pane file) 
which will contain the definitions and specifications for the Command Line 
User Interface (CLUI).  
.sp
.IP
\fB2) Using the ghost routines - \fP The \fBghost routines\fP help to automate 
writing of the source code and ensure consistency throughout the Khoros system. 
\fBGhostwriter\fP is a code generator that generates your main driver, 
include file, library file, and man pages.  Note that if your program must 
link against FORTRAN code, you must specify the [-type fxprog].
The first time \fBghostwriter\fP is run, a template Program Specification 
(PS) file is created for you, which contains key fields for the documentation 
and source code.  DO NOT DELETE any of the \fItags\fP that \fBghostwriter\fP
will insert into your source code and man pages! The \fBghost routines\fP 
facilitate the writing and maintenance of new programs via this PS file, 
which, once completed, contains all of the necessary information to 
re-generate the manual pages and associated source code files at any time, 
thus making the future addition or deletion of command line arguments a 
trivial process.  
.sp
.IP 
\fB3) Creating the *.form file -\fP Most xvroutines have a separate 
UIS file (ie, *.form file) that describes their Graphical User Interface 
(GUI). While in theory, the same UIS file can describe both the CLUI 
and the GUI of an xvroutine, we have found that the GUI of an xvroutine 
is generally much more comprehensive than the CLUI, thus prompting the 
creation of two UIS files: one for use with the \fBghost routines\fP (mentioned
in step 1 above), and this one, for use with \fBconductor\fP.
.sp
.IP
\fB4) Using conductor-\fP This step involves running \fBconductor\fP,
a code generation program.  \fBConductor\fP should be run
using the \fB[-b 1]\fP flag immediately after running \fBghostwriter\fP for
the first time.  Instructions are given in Chapter 6 of the Khoros
Programmer's Manual to integrate the two drivers.  \fBConductor\fP is driven
by a UIS file (ie, the *.form file) which is usually \fInot\fP the same as the
*.pane file that is used by the \fBghost routines\fP -- more will be said
about this later.
.sp
.IP 
\fB5) Writing the new program -\fP As you add your code and documentation 
to the files generated by \fBghostwriter\fP, run \fBghostreader\fP 
occasionally to update your PS file.  Documentation and source code will
be inserted into the program specification (PS) file between 
the appropriate keys.  Several important points are discussed later in this 
chapter concerning arguments, error handling, data structures, and memory 
allocation. 
.sp
.IP 
\fB6) Installing the new program & integrating it into cantata-\fP 
Once the new program is completed to your satisfaction, you must install 
it in the Khoros Source Tree, and integrate it into the \fBcantata\fP
visual language.  There is currently no program to install xvroutines.
They must be installed and integrated by hand.  Details on installing
your xvroutine are provided later in the following sections.
.sp 2
.NH 2 "CREATING THE *.pane FILE FOR YOUR XVROUTINE"
.XS
      \*(SN  CREATING THE *.pane FILE FOR YOUR XVROUTINE
.XE
.sp
.PP
The *.pane file for your xvroutine will be used for two purposes: it will
be used as input to \fBghostwriter\fP to generate the command line user 
interface for your xvroutine, and it will be used to integrate your xvroutine
into \fBcantata\fP.  For the purpose of using \fBghostwriter\fP, it is 
important to make sure that the *.pane file provides a complete description 
of all desired program arguments.  In addition, for the purpose of 
using the *.pane file to integrate your xvroutine into \fBcantata\fP, you must
make sure that the *.pane file describes an I/0 pane that will fit into the
appropriate subform of \fBcantata\fP, that it includes a Help Button, and that
it has a Routine button so that the user will be able to access your new 
xvroutine through \fBcantata\fP.  No extraneous UIS lines should appear in 
your *.pane file. Furthermore, it should also present a graphical 
user interface that is visually pleasing, since the *.pane file is what will be
used to integrate your xvroutine into \fBcantata\fP.  
.PP
There are many different types of UIS lines, some of which are 
required to appear in every UIS file, others of which are used only by
the command line user interface, and others which are used only by the 
graphical user interface.
.PP
There are several \fBrequired lines\fP for all *.pane (and *.form) files.  
The \fBrequired lines\fP include:
.sp
.in +.5i
.IP \(bu
\fBStartForm (-F) -\fP The (-F) line begins the user interface specification.  
This line contains several fields which contain information concerning the 
version number of the \fIxvforms\fP library, the geometry of the form, and 
the title of the form among others  (the -F line is required in every UIS file).
.br
.IP \(bu
\fBStartSubForm (-M) -\fP The (-M) line contains information describing the 
size, position, and title of the subform (the -M line is required in every UIS 
file).
.br
.IP \(bu
\fBStartPane (-P) -\fP The (-P) line describes the graphical user interface 
pane that provides a backplane for selections and action buttons to allow 
input to the application program (the -P line is required in every UIS file).
.br
.IP \(bu
\fBHelp (-H) -\fP The (-H) line describes a specialized button on the user
interface which will bring up an on-line help file when selected.  A help button
is required to appear on all \fBcantata\fP panes;  therefore your *.pane file
should contain a -H line that references the version of the man1 page for your 
xvroutine that is formatted for online help.  Note that the -H line is ignored 
by \fBghostwriter\fP.
.br
.IP \(bu
\fBEnd (-E) -\fP The (-E) line is used to end a set of definitions in a 
UIS file.  The (-E) line closes a corresponding definition line in the UIS
file.  For example, a (-F) line must have a corresponding (-E) line to complete
the form definition, a (-M) line must have a corresponding (-E) line to 
complete the subform definition, and a (-P) line must have a (-E) line to
complete the pane definition.  
.in -.5i
.sp 1
.PP
\fBOptional lines\fP for structuring the command line user interface in
the *.pane file include:
.sp
.in +.5i
.IP \(bu
\fBToggle (-T) -\fP The (-T) line defines a set of one or more \fIselection\fP
items of the same type.  The value of the toggle group will take on the default
value of the selected item (except in the case of a Logical toggle, which 
takes on the number of the selected item, where logical members of the
toggle are numbered starting at 1 with the first item).
.br
.IP \(bu
\fBMutExcl (-C) -\fP The (-C) line defines a mutually exclusive group
of \fIselections\fP.  Members of the mutually exclusive group may be of
the same or different types. The value of the mutually exclusive group will
take on the current value of the selected item.
.in -.5i
.PP
Other lines that may appear in the UIS pane file pertain to \fIselections\fP,
which are used to identify the inputs, outputs, and program arguments.
These include the following:
.sp
.in +.5i
.IP \(bu
\fBInputFile (-I) -\fP The (-I) line specifies an \fIinput file selection\fP.
.br
.IP \(bu
\fBOutputFile (-O) -\fP The (-O) line specifies an \fIoutput file selection\fP.
.br
.IP \(bu
\fBInteger (-i) -\fP The (-i) line specifies an \fIinteger selection\fP.
.br
.IP \(bu
\fBFloat (-f) -\fP The (-f) line specifies a \fIfloat selection\fP.
.br
.IP \(bu
\fBString (-s) -\fP The (-s) line specifies a \fIstring selection\fP.
.br
.IP \(bu
\fBLogical (-l) -\fP The (-l) line specifies a \fIlogical selection\fP.
.br
.IP \(bu
\fBRoutine (-R) -\fP The (-R) line describes a specialized action button
which must appear on the pane when it is integrated into
\fBcantata\fP.  When the user clicks on this button, the xvroutine
will be executed.   This line is ignored by \fBghostwriter\fP.
.br
.IP \(bu
\fBBlank (-b) -\fP The (-b) line is used for adding comments and extra titles
into the pane, for extra clarity on the pane when it is integrated into
\fBcantata\fP.  Note that the -b line is ignored by \fBghostwriter\fP.
.br
.IP \(bu
\fBHelp (-H) -\fP The (-H) line is used to add a "Help" button to the
\fBcantata\fP pane that represents your vroutine.  The Khoros convention
is to provide a "Help" button that accesses the man1 page for your vroutine.
.in -.5i
.sp 1
.LP
A complete description of each of the UIS lines can be found in Chapter 2,
section B.3 of the Khoros Programmer's Manual.
.sp
.PP
An example of the *.pane file for the xvroutine \fBwarpimage\fP is presented 
below.  This illustrates the use and placement of the various lines in a 
UIS pane file. 
.sp
.DS L
.ps 9
.vs 11
\f(CW
-F 4.2 1 0 170x7+10+20 +35+1 'CANTATA Visual Programming Environment for the KHO
ROS System' cantata
   -M 1 0 100x40+10+20 +28+1 'Warp Images' gis_warp
      -P 1 1 80x38+22+2 +11+0 'Interactive Image Warp' warpimage
	 -I 1 0 1 0 0 1 50x1+1+2 +0+0 ' ' 'Input Source Image' 'input source image' src
	 -I 1 0 1 0 0 1 50x1+1+3 +0+0 ' ' 'Input Target Image' 'input target image' target
         -T 1 0 1 1 0 40x1+1+5 +0+0 1 'Tiepoint Mode' 'selection type ' tp_mode
            -l 1 0 1 1 0 40x1+2+1 +2+0 0 'Source & Target' 'False' 'True' 'Select Source & Destination' dummy
            -l 1 0 1 0 0 40x1+2+2 +2+0 0 'Source Only' 'False' 'True' 'Select Source Only' dummy
         -E
         -R 1 0 1 13x2+1+13 'Execute' 'do operation in foreground' warpimage
         -H 1  13x2+39+13 'Help' 'man page for editimage' KHOROS_HOME/doc/manpages/warpimage.1
      -E
   -E
-E
\fP
.DE
.ps 11
.vs 13
.sp
.PP
As in every *.pane file, there are three required lines for the *.pane file.
These include the \fBStartForm (-F)\fP line for starting a UIS, a 
\fBStartSubForm (-M)\fP line beginning the definition of a subform, 
and a \fBStartPane (-P)\fP line beginning the definition of an I/O pane.
Note that each of these lines has a corresponding \fBEnd (-E)\fP line
to terminate the respective set of definitions.  These lines are all ignored
by \fBghostwriter\fP.
.PP
Note that the (-F) line is the standard \fBcantata\fP (-F) line for all *.pane 
files, and that the (-M) line is the same as all other *.pane files that
will be included in the chosen \fBcantata\fP subform, in this case, the
"Warp Images" subform.  If you would like to look up this example, it can
be found in \f(CWKHOROS_HOME/repos/cantata/subforms/gis_warp\fP.
.PP
The reader is once again urged to study the detailed discussions provided in 
in Chapter 2 of the Khoros Programmer's Manual for a complete description 
of the proper syntax and use of each line in a *.pane file, as they will
not be repeated here.  An experienced Khoros programmer should be able to
look at the *.pane file above, and note that it is a *.pane file for a
program named \fBwarpimage\fP.  A quick glance confirms that \fBwarpimage\fP 
has two optional input files that will be specified on the command line as 
[-src {viff image}] and [-target {viff image}], respectively.
There is also an optional [-tp_mode] flag that may be specified as 0 (for
"Source & Target") or 1 (for "Source Only").  The \fBwarpimage\fP program 
will be accessed from the \fBcantata\fP subform labeled, "Warp Images", on
the pane labeled "Interactive Image Warp".  
.PP
The "warpimage.pane" file also includes a (-H) line describing a help button 
so that the user may look at its man1 page when they are using \fBcantata\fP, 
and a (-R) line so that the user may enter command line arguments into 
\fBcantata\fP's pane for \fBwarpimage\fP, before clicking on the Routine button
described by this (-R) line, in order to execute the \fBwarpimage\fP program.
Other info contained in the UIS lines may be looked up when necessary in 
Chapter 2. 
.PP
Once the UIS pane file has been created, the next step is to create a driver
program for the xvroutine, using all of the arguments specified in the UIS
pane file.  This is easily accomplished using the \fBghost routines\fP provided
for this purpose.  The next section  describes how to use the \fBghost
routines\fP to create a driver program and generate the framework for the
library routine.
.sp 2
.NH 2 "USING THE GHOST ROUTINES"
.XS
      \*(SN  USING THE GHOST ROUTINES
.XE
.sp
.PP
Programming is a difficult task that involves many steps between the analysis 
of the problem and its efficient solution.  A huge gap must be bridged 
between a formal (descriptive) specification of a problem and its 
accommodation to a given programming environment on a particular machine. 
There is widespread agreement that the difficulties involved in
constructing correct programs can only be overcome if the whole task is
broken into sufficient small and formally justified steps following
well structured standards.  Because of the importance of this, 
Khoros contains code generators that help to automate part of
the procedure of programming.
.PP
To get started, create a new directory that can be used as the
development directory for the new routine.  Create a UIS (*.pane) file
using either \fBcomposer\fP or a modification of an existing UIS (*.pane)
file, as detailed in Chapters 2-4.  
.PP
The first tool you will use is \fBghostwriter\fP.  However,
keep in mind that \fBghostwriter\fP requires a UIS file as input
(discussed in the previous sections).  \fBGhostwriter\fP can be run with 
the UIS file to create a template for the PS file, the include file, 
the source code files for the main driver, the library file,
and the manual pages for the program.
Alternatively, you can begin with an empty template PS 
file, fill in the appropriate fields, and run \fBghostwriter\fP to
generate the source code and manual page files.  We have found that a hybrid
method is most popular with the Khoros group;  however, after writing one or 
more programs under the Khoros system, you will find your own preference.
.LP
The following example demonstrates the use of \fBghostwriter\fP to generate 
an xvroutine:
.PP
\f(CW
% ghostwriter -name xvroutine -type xprog -toolbox {toolbox name}
\fP
.sp
.LP
This will generate the files "xvroutine.c", "lxvroutine.c", "xvroutine.1",
"lxvroutine.3", "xvroutine.h"\fP.  Note that in order for \fBghostwriter\fP
to run, a valid UIS file (in this case, "xvroutine.pane") must exist 
in the current working directory.  
\fBGhostwriter\fP will look for a valid PS file in the current working
directory; if one does not exist, a template PS file ("xvroutine.prog") 
will be created.  In addition, \fBghostwriter\fP will also look for a 
configuration file in the current working directory;  if one does not exist, a 
template configuration file ("xvroutine.conf") will be created as well. The use
of the configuration file is explained later in this chapter;  for more 
detailed information about the configuration file, see Chapter 5 of the Khoros
Programmer's Manual.  In general, the configuration file is ignored while
writing the new program;  it is not used until the program is to be installed
in the appropriate toolbox.
.PP
When writing an xvroutine, you must remember 
to provide the [-type xprog] argument!  If your xvroutine links against
FORTRAN (note that the \fIlinpack\fP and \fIeispack\fP libraries are in 
FORTRAN), you should instead provide the [-type fxprog].  If you do not
provide the correct [-type] flag to \fBghostwriter\fP for your xvroutine,
your code will not compile.  
.PP
There are several options with \fBghostwriter\fP which allow use of a
configuration file, formatting, debug statements, and generation of
certain files.  The various options may be listed using the [-U 1] option; or,
you may wish to run the program with prompts for each command line
option using the [-P 1] option.  
An answer file, which specifies the desired arguments to \fBghostwriter\fP,
may be created by using the [-A ghost.ans] and [-P 1] options together, making 
it easier to perform successive runs of \fBghostwriter\fP (a certainty!).
.PP
In this example, if we had used the [-A ghost.ans] option to \fBghostwriter\fP, 
for the xvroutine, its answer file, "xvroutine.ans", for future executions 
of \fBghostwriter\fP would look like:
.in +.5i 
.sp
-name xvroutine
.br
-config f
.br
-lib t
.br
-man3 t
.br
-install f
.br
-format 1
.br
-debug f
.br
-tag t
.br
-force f
.br
-prog t
.br
-type xprog
.br
-toolbox {toolbox name}
.sp
.in -.5i
.LP
Now, for successive runs of \fBghostwriter\fP, we need not provide arguments
on the command line, or interactively with the [-P 1] option.  To execute
\fBghostwriter\fP with the exact same arguments as before, all that is
necessary is to run:
.PP
\f(CW
% ghostwriter -a ghost.ans
\fP
.LP
In addition to 
creating the source files and man files for your xvroutine,
\fBghostwriter\fP will also make calls to \fBimkmf\fP and \fBmakemake\fP 
for you, thus generating (respectively) the appropriate "Imakefile" and 
"Makefile" files for this program.  The xvroutine is now ready to be compiled; 
of course, lxvroutine() will simply return to the main program (initially,
it is generated with only a \fIreturn(TRUE)\fP statement).  You may wish 
to compile at this point, checking for any errors in the driver 
and include files.  To compile, simply type:
.br
\f(CW
% make
\fP
.br
.LP
No errors should occur, unless you modify these files in some way;  however,
if compile errors do occur 
in any of the source files, you can fix the problems in the problem source 
files, but remember to follow any modifications with a call to 
\fBghostreader\fP.  Note that \fBghostreader\fP has a subset of the complete
set of \fBghostwriter\fP arguments - those arguments that are identical for
the two programs have the same meaning,  and neither program checks for
invalid arguments, so that you may provide the same answer file, "ghost.ans"
for both programs.  To execute \fBghostreader\fP, then:
.in +.5i
.br
\f(CW
% ghostreader -name xvroutine
\fP
.br
or
.br
\f(CW
% ghostreader -a ghost.ans
\fP
.br
.in -.5i
.LP
.PP
The Program Specification (PS) file contains key fields for the insertion
of Khoros system documentation, man page documentation, and source code.
A template "xvroutine.prog" file is created when \fBghostwriter\fP 
is run for the first time, containing all of the key fields for 
constructing a complete PS file.  Each key field in the "xvroutine.prog" file
is delineated by 
\fIbegin\fP and \fIend keys\fP.  All comments, code, and documentation is 
placed between the appropriate \fIbegin\fP and \fIend tags\fP for a 
particular field.  An example of a template PS file is presented in 
Chapter 5. Chapter 5 should be consulted for specific descriptions 
and guidelines concerning the information to be included in each of 
the key fields of the PS file.  An example illustrating the use and format 
of each key field of a *.prog file is included in Chapter 5.  This format 
should be adhered to when creating a PS file to ensure maintainability of 
the Khoros System.
.PP
\fBGhostwriter\fP creates the source code, include files, and man pages 
with pre-defined \fPtags\fP, that are recognized by \fBghostreader\fP.
Thus, segments of code and/or documentation between these tags 
may be modified by the programmer and then reinserted into the 
PS file by running \fBghostreader\fP.  \fBGhostreader\fP takes as 
input the 5 files: "xvroutine.c","xvroutine.h", "xvroutine.1", and 
"lxvroutine.3", as well as the old PS file "xvroutine.prog".  First it loads
in the information provided in the old "xvroutine.prog" file.  It then looks 
for the tags in the source and man files, and pulls any text between a pair 
of begin and end tags into the corresponding place in the new "xvroutine.prog"
file, thus over-writing the old information.  In this way, a new PS file 
may be generated containing the new information.
.PP
Running \fBghostreader\fP insures that all modifications are correctly 
updated in the "xvroutine.prog" PS file; thus, when \fBghostwriter\fP is 
run again (perhaps with the [-a ghost.ans] flag), the updates will be written 
to the appropriate files.  BE WARNED that if you modify source code or man 
pages, and forget to run \fBghostreader\fP, \fIall your changes to source code 
and man pages will disappear the next time you run\fP \fBghostwriter\fP!
.sp 2
.NH 2 "CREATING THE *.form FILE FOR YOUR XVROUTINE"
.XS
      \*(SN  CREATING THE *.form FILE FOR YOUR XVROUTINE
.XE
.sp
.PP
First of all, a short discussion of the use of UIS files is in order.  
While in theory, the same UIS file can be used for both the command line user
interface (CLUI) and the graphical user interface (GUI) of an xvroutine (as
it ALWAYS is for vroutines), we in the Khoros group have found that most 
often, the CLUI requires fewer arguments than the GUI.  That is, it is usually
appropriate to offer options to the user in the graphical user interface 
that would not be appropriate on the command line.  For example, 
\fBeditimage\fP offers only 13 command line arguments.  Anyone that has used
the \fBeditimage\fP program knows that the graphical user interface offers
dozens more options than that!  
.PP
To resolve this conflict of interest, xvroutines almost always have 
\fItwo\fP UIS files. The first, named "xvroutine.pane", is located with the 
source code of the xvroutine;  it is short, and used with \fBghostwriter\fP 
as detailed above; in addition, it is used to integrate the xvroutine into 
\fBcantata\fP.  The second, named "xvroutine.form", is located in
\f(CW{toolbox_name}/repos/xvroutine/\fP; it is generally much longer and more 
comprehensive, and is used with the code generated by \fBconductor\fP to 
present the user with a complete graphical user interface.
.PP
If you have not already done so, examine your "xvroutine.pane" file.  It 
should have ONLY those arguments that will be input to your program from
the command line.  However, does it really have everything it needs to 
make your xvroutine complete?  If not, copy your "xvroutine.pane" file to
"xvroutine.form".  Use your imagination, future plans for the program, and
\fBpreview\fP to extend the "xvroutine.form" UIS file to a point where it
offers the user with all the options they will need (that you are willing
to implement)!  Don't worry if you won't have time to put in all the 
functionality right away;  portions of the GUI can be de-activated (see
Chapter 2 of the Khoros Programmer's Manual), or simply not used until later.
.PP
While we will not detail all the lines you may decide to have in your *.form
file to structure your graphical user interface, some lines you might consider
using for the *.form file that you would \fInot\fP add to a *.pane file include:
.sp
.in +.5i
.IP \(bu
\fBSubMenu (-D) -\fP The (-D) line specifies a \fIpull-down menu\fP.
.br
.IP \(bu
\fBStartMaster (-S) -\fP The (-S) line specifies a \fImaster form\fP.
.br
.IP \(bu
\fBSubFormButton (-d) -\fP The (-d) line specifies a \fIsubform button\fP.
.br
.IP \(bu
\fBMasterAction (-n) -\fP The (-n) line specifies a \fImaster action button\fP.
.br
.IP \(bu
\fBStartGuide (-G) -\fP The (-G) line specifies a \fIguide pane\fP.
.br
.IP \(bu
\fBGuideButton (-g) -\fP The (-g) line specifies a \fIguide button\fP.
.br
.IP \(bu
\fBSubformAction (-m) -\fP The (-m) line specifies a \fIsubform action button\fP.
.br
.IP \(bu
\fBWorkspace (-w) -\fP The (-w) line specifies a \fIworkspace\fP.
.br
.in -.5i
A complete description of each of the UIS lines can be found in Chapter 2,
section B.3 of the Khoros Programmer's Manual.
.sp
.PP
An example of the *.form file for the xvroutine \fBwarpimage\fP is presented 
below.  This illustrates the use and placement of the various lines in a 
UIS form file.  
.sp
.DS L
.ps 9
.vs 11
\f(CW
-F 4.2 1 1 70x3+10+15 +60+1 'Warp Image' Master
   -M 1 1 70x60+10+5 +60+0  'WARP IMAGE' WarpImage
      -G 1 20x60+0+0 +1+0 ' '
	 -w 1000x690+0+5 +25+1 ' ' 'source image' workspace
         -g 1 1 17x1+1+0 'Operations'
	 -g 1 0 17x1+1+1 'Input'
	 -g 1 0 17x1+1+2 'Output'
	 -m 1 0 17x1+1+3 'VIEW TIEPOINTS' 'view tiepoints' view
	 -m 1 0 17x1+1+4 'CLEAR TIEPOINTS' 'view tiepoints' clear
	 -m 1 0 17x1+1+5 'WARP/VIEW IMAGE' 'warp image ' warp
	 -H 1   10x1+125+0 'HELP' 'Master Form Help' $KHOROS_HOME/doc/warpimage/help
	 -H 1   10x1+125+2 'Copyright' 'Copyright' $KHOROS_HOME/doc/copyright/copyright
	 -Q 1 0 10x1+125+4 'QUIT'
      -E
      -P 1 1 40x60+19+0 +2+0 'WARPIMAGE OPERATIONS' Options
	 -T 1 0 0 1 1 20x1+2+1 +0+0 1 'Tiepoint Operation' 'operation' operation
            -l 1 0 1 1 0 40x1+1+1 +0+0 0 'Add' 'False' 'True' ' ' dummy
            -l 1 0 1 0 0 40x1+1+2 +0+0 0 'Delete' 'False' 'True' ' ' dummy
         -E
	 -b +27+1 'Zoom Type'
	 -a 1 0 14x1+25+2 'Rubberband' 'rubber band zoom' rb_zoom
	 -a 1 0 14x1+25+3 'Point & Click' 'point & click' pc_zoom

	 -b +53+1 'Zoom Factor' 
	 -f 1 0 0 1 1 20x1+48+2 +0+0 2.0 2.0 2.0 'Source      ' 'zoom factor' src_zoom_factor
	 -f 1 0 0 1 1 20x1+48+3 +0+0 2.0 2.0 2.0 'Destination:' 'zoom factor' dest_zoom_factor
      -E
      -P 1 0 40x60+19+0 +0+0 'WARPIMAGE INPUT' Input
	 -I 1 0 0 1 1 1 85x1+0+1 +0+0 ' ' 'Input Source Image ' 'input file' in_src_img
	 -I 1 0 0 1 1 1 85x1+0+2 +0+0 ' ' 'Input Target Image ' 'output file' in_dest_img
	 -O 1 0 0 1 1 1 85x1+0+3 +0+0 ' ' 'Input Tiepoints    ' 'input tiepoints file' in_tp
      -E
      -P 1 0 40x60+19+0 +0+0 'WARPIMAGE OUTPUT' Output
	 -O 1 0 0 1 1 1 85x1+0+1 +0+0 ' ' 'Output Tiepoints       ' 'output file' out_tp
	 -O 1 0 0 1 1 1 85x1+0+2 +0+0 ' ' 'Output Coefficients    ' 'output file' out_coeff
      -E
   -E
-E
\fP
.DE
.ps 11
.vs 13
.PP
Compare the *.form file for \fBwarpimage\fP, above, with the *.pane file for
\fBwarpimage\fP, given earlier.  See how the *.form file is much more complete,
and contains UIS lines describing options not available through the command 
line.  Furthermore, there are many lines in the *.form file that are used to
structure the graphical user interface of \fBwarpimage\fP - examination
reveals that the GUI for \fBwarpimage\fP has no master form; it has a single
subform with three guide buttons and three subform buttons on the guide pane,
which will appear on the upper left hand corner of the GUI. The guide buttons 
bring up a "WARPIMAGE OPERATIONS" pane, a "WARPIMAGE INPUT" pane, and a 
"WARPIMAGE OUTPUT" pane, thus separating the functionality of
\fBwarpimage\fP into obvious categories for the user.  These panes will appear
to the right of the guide pane.  Below the guide pane and the panes will be
a workspace on which the source and target images can be displayed.
.PP
Note that the (-H) lines in the *.form file for \fBwarpimage\fP are different
than the single (-H) line in its *.pane file.  While every *.pane file has
a single (-H) line that references the man1 page of the program, a *.form
file usually has several (-H) lines - one on the master form, if there is one,
one on each subform, and one on each pane.  These (-H) lines reference on-line
help that is found in \f(CWKHOROS_HOME/doc/warpimage/help\fP; in addition,
(-H) lines are used to access the Khoros copyright.  
.PP
You should have online documentation for your new xvroutine, 
and you should put it in \f(CW{toolbox_name}/doc/xvroutine/help\fP, 
\fBWarpimage\fP is an exception to the many-help-button xvroutine rule: 
since the panes are small and few, a single Help button to the far right 
produces an online help page with little buttons across the top that access 
the entire \fBwarpimage\fP help directory - by selecting the button labeled 
with the name of the help file they are interested in, users may read the 
online help for all aspects of \fBwarpimage\fP.
.PP
Use \fBpreview\fP often when developing your *.form file to make sure that it
looks good, and presents options in a readable fashion.  Asking co-workers
or other potential users of your program for feedback is usually a good way 
to get an idea of how well you are designing your graphical user interface,
and to obtain suggestions and constructive criticism.
.sp 2
.NH 2 "USING CONDUCTOR"
.XS
      \*(SN  USING CONDUCTOR
.XE
.sp
.PP
When your "xvroutine.form" file is satisfactory, go on to run \fBconductor\fP 
to generate the files "form_drv.c", "form_info.h", "form_info.c", and 
"form_init.c".  If you have never used \fBconductor\fP before, you should read 
Chapter 6 of the Khoros Programmer's Manual, if you have not already done so.  
The rest of this discussion will assume that you understand the use of 
\fBconductor\fP, that you have already used it with the [-b 1] flag, and
that you have integrated the "form_drv.c" file generated
by \fBconductor\fP with the "lxvroutine.c" file generated by \fBghostwriter\fP, 
according to the step-by-step instructions that can be found in Chapter 6 
of the Khoros Programmer's Manual, on \fBconductor\fP.
.sp 2
.NH 2 "WRITING THE NEW XVROUTINE"
.XS
      \*(SN  WRITING THE NEW XVROUTINE
.XE
.sp
.PP
Writers of xvroutines may want to do some initializations in the 
"lxvroutine.c" file, but most of the
functionality for the xvroutine will go into other files (created by the
programmer with appropriate names).  Calls to the subroutines and/or functions
created in these other files should be made in the "run_xvroutine.c" file, 
replacing those comments created by \fBconductor\fP that say, 
"PUT YOUR CODE HERE".  
.PP
It is STRONGLY recommended that you read the man pages on the \fIverror, 
vgparm, vmath, vrast,\fP and \fIvutils\fP libraries.  These are public Khoros
libraries, and contain many useful routines for I/O, math, and 
reading/writing/checking of images that help the programmer avoid
"re-inventing the wheel".  Writers of xvroutines are also referred to the
man pages on the \fIxvforms, xvutils, xvgraphics,\fP and \fIxvdisplay\fP 
libraries. The man pages on \fIxvforms\fP will augment Chapter 6 in helping
you understand the main user interface loop that was generated by conductor,
while the man pages on \fIxvutils\fP will inform you about utilities
for pop-up error messages, warning messages, and the like.  \fIXvgraphics\fP
contains an extensive collection of graphics routines, while \fIxvdisplay\fP
provides routines for displaying VIFF images.
.PP
When the source code for library routine is completed, you are reminded 
(again!) to use \fBghostreader\fP to update your PS files in preparation for
any future runs of \fBghostwriter\fP.  The program should then be 
carefully tested for proper operation, using all possible options both
separately and in different combinations.
.PP
Finally, you will be required to complete the man1 page information for your
new program.  The purpose of the man1 page is to provide a detailed 
description of the function of your new program.  This should include 
descriptions of the input files, output files, and arguments to the program.  
Try to be as complete as possible in your descriptions of the inputs, 
outputs, and arguments to the program.  This information will be of 
valuable assistance to anyone using your program.  All Khoros programs
must have a man1 page (after all, you want to let users know of your 
new program)!  
.PP
Many people prefer to fill in the appropriate fields in the PS file for
the man1 page, and then run \fBghostwriter\fP to update their man1 page
properly.  Alternatively, you may fill in the man1 page directly, and run
\fBghostreader\fP when you are done to update the PS file.  
You may want to 
look at some of the man1 files for other Khoros programs to get the feel 
of how to write one.  Man1 files can be found in \f(CWKHOROS_HOME/man/man1\fP.
They can be accessed by executing: \f(CW% vman {program}\fP.
.PP
Formatting for man1 pages should be done in \fInroff\fP 
format.  This is to ensure that the on-line man page is generated
correctly and to maintain consistent formatting throughout the documentation.
Certain fields found in the PS file need no formatting since they must consist 
of only a one line description (notes on the PS file will follow later).  
Some of the more common \fInroff\fP formatting commands that you may
find useful include:
.sp
.DS
	.IP/.LP - for new block paragraphs
	.RS/.RE - for indenting
	.DS/.DE - for non-formatted sections
	.SH    - for section headers
	.sp #  - for adding # blank lines
.DE
.sp
.PP
For an xvroutine, you need not worry about the man3 file at all - remember that 
"lxvroutine.c" does not really contain a "library" routine - however, you 
should not delete it, as \fBghostreader\fP will complain if it doesn't exist.  
.PP
Finally, you should read Section D of this document, labeled, "CONVENTIONS & 
GUIDELINES FOR ALL KHOROS ROUTINES"  for valuable information that may apply
to you.  In addition, a table of file naming conventions and a listing of
variable naming conventions are given there.
.sp 2
.NH 2 "JOURNAL RECORD / JOURNAL PLAYBACK"
.XS
      \*(SN  JOURNAL RECORD / JOURNAL PLAYBACK
.XE
.sp
.PP
When you write an xvroutine, it will automatically have the ability to have
journal record and journal playback, due to its use of the \fIxvforms\fP 
library;  by the same token, it will also be a viable target program for the
\fBconcert\fP distributed user interface collaboration tool. If you would like
to use the journal record / playback capability for demos or other purposes,
you must first make a journal recording of your program.  This is done by
executing:
.sp
\f(CW
% xvroutine -jr xvroutine.jp
\fP
If your xvroutine has any required arguments, you must provide them as well
on the command line;  optional arguments may be provided as desired.  Remember
the command line arguments that you used when recording, as you MUST provide
these same arguments when playing back.   The program will start up as usual, 
with no apparent difference.  Go through a normal session with your xvroutine, 
remembering that the journal recording mechanism records your XEvents 
\fIin real time\fP.  That is, if you stop in the middle of your recording 
session to answer the phone, a pause of the same length  will be played back 
at the time when you paused.  For the same reason, it is recommended that 
you make a mental plan of the session and follow it through smoothly while 
making the recording, especially when making journal recordings for demo 
purposes;  errors, typos, mistakes and pauses will all be recorded.
.PP
When you have created your journal recording file, you may then play it back
whenever desired.  Note that the journal recording/playback mechanism is 
machine independent, so that you need not be on the same architecture when
playing back a journal session as you were when you recorded it.  To play 
back the recorded session of your xvroutine, simply execute:
.sp
\f(CW
% xvroutine -jp xvroutine.jp
\fP
.PP
Remember that if you provided any command line arguments (required or optional)
when you recorded the session, you \fImust provide the exact same arguments\fP
when playing back the session.  If you forget arguments, or substitute others
for the original ones, the actions produced by journal playback will be 
unpredictable.  In this case, the playback may or may not work;  it may or 
may not exhibit bizarre behavior, and it may or may not crash your program.   
.PP
As of Khoros 1.0, when using a window manager that requires interactive
placement of windows, you are unfortunately required to map widgets as they 
appear during a journal playback session.  That is, you will have to map 
the widgets during the playback session as you did when they were recorded.  
Positioning is irrelevant;  however, timing is important.  Pay attention to 
the journal playback session, and map items of the graphical user interface
as soon as they appear.  Failing to map widgets in a short amount of time
may result in events piling up behind you, and happening all at once the moment
the widget is mapped.  In many instances, this proves quite confusing to the
observer.  We will attempt to address this problem before the next release
of Khoros.  Note that if your window manager automatically maps windows, 
this issue should not be a problem for you.
.PP
You may also wish to use the \fBconcert\fP collaboration program to "share"
the execution of your program with one or more other people.  You may do
this by executing:
.sp
\f(CW
% concert -command xvroutine -d2 display2 [-d3 display3 ... ]
\fP
.sp
For more information on the \fBconcert\fP distributed interface, see the man
page on \fBconcert\fP, or read Chapter 9 of the Khoros User's Manual.
.sp 2
.NH 2 "INSTALLATION OF THE XVROUTINE"
.XS
      \*(SN  INSTALLATION OF THE XVROUTINE
.XE
.sp 2
.PP
The installation process of a new routine is the process of moving all the files
involved in the new program into their proper places in the Khoros source tree,
and compiling the program.  The layout of the Khoros source tree is explained
in detail in Chapter 9 of the Khoros Programmer's Manual - you are encouraged
to read this chapter if you have not already done so.  
The installation process for an xvroutine is not animated like the process
for a vroutine;  unfortunately, there are too many variations to be easily
addressed by a high-level installation program like \fBkinstall\fP to handle.  
Therefore, it must be done by hand.  
.sp
.IP 1)
Go to the location of the toolbox source tree where you want to install the
new xvroutine.  Create a new directory with the same name as your program. 
Move into the new directory.  Copy all source code into the new 
directory, including the Imakefile, *.c file, *.h file, l*.c file, *.prog file, 
*.conf file, files generated by conductor, and any other source files you may 
have created to use with your xvroutine.  
.IP 2)
Execute \f(CW% makemake\fP to create a clean Makefile.
.IP 3)
Now, if your site supports different computer architectures, you must create 
a "shadow" of this directory in the srcmach trees (if your site supports only
one architecture, skip this step).  First, make sure that
the directory created in Step (1) is free of all extraneous files. This is
important, because once you run \fBksrcconf\fP, any incorrect symbolic
links must be removed by hand. Once the directory is clean, you run 
\fBksrcconf\fP to create the machine-dependent representation of your program.
run:
.br
\f(CW
% ksrcconf -toolbox {toolbox_name}
\fP
.sp
\fBksrcconf\fP should respond by listing each location in the srcmach tree
that it is making symbolic links.  There will be one message for each 
architecture that is supported by your site. If you go to the srcmach tree,
to the location that mimics the location in the source tree where you just
copied your source, you should find a matching directory.  In this directory
you should find a symbolic link to your Imakefile, a Makefile that is 
particular to the specific machine architecture, and symbolic links to all
other files that you copied into the Khoros source tree in Step 1. 
.IP 4) 
Now, you are ready to compile your program.  If your site supports only one 
architecture, you simply execute:
.br
\f(CW
% make install
\fP
On the other hand, if your site supports multiple architectures, execute:
.br
\f(CW
% kmakeall -toolbox {toolbox_name} install
\fP
.br
\fBKmakeall\fP will mail you (one mail message for 
each architecture) with the results of your compile.  If there are any errors, 
they will appear in the mail.
.IP 5)
Now, test your program to make sure that all is well.  Don't forget to first
execute:
.br
\f(CW
% rehash
\fP
Since you are installing your program for the first time, forgetting to run
\fIrehash\fP will result in the operating system error, "Command not found".
Extensive testing is usually not necessary on installation, as you should 
have already completed the testing and debugging process in your work area,
before installation.  However, \fInever\fP neglect to do at least cursory
testing on your installed program!  Sometimes a compile looks successful,
but in fact is corrupted due to system problems or corrupted library files.
When this is the case, the result is usually an immediate segmentation 
violation and/or core dump, even before your graphical user interface is
mapped to the screen.  If this happens, repeat step (4).
.IP 6)
Move your man1 page (*.1 file)  into its appropriate location in
\f(CW{toolbox_name}/man/man1\fP.
Make sure that its appearance is correct by executing:
.br
\f(CW
% vman xvroutine
\fP
.br
.IP 7)
Finally, you may want to integrate your new program into \fBcantata\fP.  If so,
that procedure is detailed in the next section.
