.ds f. intro.sec
.NH 1 "WRITING PROGRAMS IN THE KHOROS ENVIRONMENT"
.XS
\s12\*(SN  WRITING PROGRAMS IN THE KHOROS ENVIRONMENT\s0
.XE
.sp
.PP
This chapter provides information necessary to writing a new program
and its integration into the Khoros system.   An introduction is
provided outlining the differences between the two main types of programs
in Khoros (\fIvroutines\fP and \fIxvroutines\fP).  Section B
specifically outlines the writing of a \fIvroutine\fP, while section C
outlines how to write an \fIxvroutine\fP.  Each of these sections gives
appropriate instructions on creating the UIS file, using the \fBghost
routines\fP for automatic program generation, 
and the installation process.  Notes on use of the Program
Specification file are given in section D, which is followed by section E,
on integrating the new program into \fBcantata\fP.  Finally, section F 
presents information on maintenance of new programs in the Khoros system.
.PP
In addition, this document also contains general information about
the Khoros system, including argument and file naming conventions, and important
style and coding conventions.  It is \fIstrongly\fP recommended that you follow
these guidelines for consistency and maintainability of your programs.
Usage of the provided information and recommendations will result in a
high degree of standardization in the source code and an increased 
understanding of the Khoros system.
.sp 3
.NH 2 "INTRODUCTION TO KHOROS VROUTINES & XVROUTINES"
.XS
      \*(SN  INTRODUCTION TO KHOROS VROUTINES & XVROUTINES
.XE
.sp
.PP
First of all, it is necessary for the reader to distinguish
between the two types of programs in the Khoros system:  programs that are
referred to as \fIxvroutines\fP, and those that are referred to as
\fIvroutines\fP. There are also some programs in the Khoros system that
are a cross between the two.  These are referred to as \fIhybrid\fP
routines.
.PP
Usually, an \fIxvroutine\fP is an application which has a graphical user
interface, \fIregardless of whether or not it is executed from the
command line\fP; there are only a few notable exceptions to this rule.
An xvroutine is characterized by the fact that it must link against at
least one of the \fIxvforms, xvutils, xvdisplay,\fP or \fPxvgraphics\fP
libraries.  In general, an xvroutine must also use the \fBconductor\fP
code generation program to initialize and extract information from the
graphical user interface.  An example of an xvroutine is \fBeditimage\fP,
which is used to interactively display and manipulate an image.
.PP
Khoros \fIvroutines\fP also have a graphical user interface,
but this graphical user interface is provided entirely through their inclusion
into the \fBcantata\fP visual language, or via interpretation and display by 
the \fBcomposer\fP
or \fBpreview\fP programs - it is NOT supported by the programs
themselves.  When a \fIvroutine\fP is run from the command line, there is no
graphical display;  data is input, processed, and output.  
An example of a vroutine is \fBvadd\fP, which is one of
the many image processing routines within Khoros.
.PP
The first task of a programmer working in the Khoros environment is
to decide which of the above types of programs they will be writing, let
us explain the difference in greater detail.  Xvroutines will always involve
some sort of graphic display on a screen supporting X Windows, \fIindependently
of any accessibility they may have through\fP \fBcantata\fP.
Xvroutines always use the X Toolkit and the Athena widget set indirectly
(since they will link against one of the Khoros libraries that uses X11.4).
Xlib, the X Toolkit and/or the Athena Widget Set may also be used directly
by the xvroutine if desired.  Examples of \fIxvroutines\fP include all the
major applications of Khoros: \fBanimate, cantata, composer, editimage,
preview, viewimage, warpimage, xprism2,\fP and \fBxprism3.
.PP
All these programs meet the first criterion for an xvroutine:
they \fIalways\fP have a graphical user interface, regardless of whether
they are run from the command line, or executed via \fBcantata\fP.
With one notable exception, the Khoros programmer for each of these
programs had to use the \fBconductor\fP code generation program in the
development and maintenance of the program.  The only exception to this rule
is \fBcantata\fP, which, as a necessarily extensible visual language,
is \fIinterpretive\fP -- that is, it interprets the graphical user interface
on its own, without the aid of automatically generated code, at runtime.
.PP
While the Khoros xvroutines are highly visible, the vast majority of the
programs that make up the Khoros system are vroutines rather than xvroutines.
These include all the programs in the image processing library (vipl), all
the programs in the digital signal processing library (dspl), all the
file-formatting programs, all the classification algorithms and morphology
routines ... in general, almost all the Khoros programs besides those
major applications listed above.
.PP
Some programs, however, cannot be classified as either a vroutine or an
xvroutine.  For instance, some programs may involve graphic display
(like an xvroutine), but may NOT have an interactive graphical user interface
when run from the command line (like a vroutine). These \fIgraphic hybrid\fP
routines must be located with the xvroutines in the Khoros
source tree, as they will usually need the utilities provided by the
\fIxvdisplay\fP or \fIxvgraphics\fP libraries.  However, they are NOT
xvroutines, per se, as they are not interactive, and do not have
a graphical user interface when run from the command line; thus,
they do NOT use the \fBconductor\fP code generation program, as they have
no graphical user interface from which to extract information;
they simply provide non-interactive graphic display.
Examples of these programs are: \fBiconimage, putimage, xverror,\fP and
\fBxvviewer\fP.  The reader is highly encouraged to write this type of
application;  however, be aware that it falls into a "grey" area of the
Khoros domain -  it should be installed in the source tree with the
xvroutines, but will follow the same procedures as that of a vroutine.
.PP
On the other hand, some existing non-graphic Khoros programs must be
located in the Khoros source tree with
the xvroutines since they must link against the \fIxvforms\fP
library.  In particular, \fBgetimage, ghostreader,
ghostwriter,\fP and \fBconductor\fP take advantage of these libraries
to parse and deparse lines out of UIS files, and perform other necessary
operations.  Since they do not display graphics of any sort (user interface
or otherwise), they are not xvroutines, and do not use \fBconductor\fP;
the procedure followed to write them was, like the graphic hybrid
routines, the same as the procedure that will be outlined for vroutines.
These routines are classified as \fInon-graphic hybrid\fP xvroutines.
In contrast to graphic hybrid routines, however, it is
NOT RECOMMENDED to attempt to write a non-graphic hybrid
routine!  The reason for this is (identical to the reason that the reader
is not encouraged to write an interpretive application such as \fBcantata\fP)
that a detailed & thorough knowledge of the internal workings of the
\fIxvforms\fP and \fIxvutils\fP libraries would be necessary for such a task.
While we are confident that Khoros users may be quite capable of acquiring
such knowledge, any use of the non-public, undocumented regions of these
libraries is strongly discouraged, as this code is subject to change
at any time without notice.
.PP
To summarize briefly, simply remember this simple rule of thumb: if your
program will have a graphical user interface when it is run from the
command line, it will be an \fIxvroutine\fP; if it doesn't, it will be a
\fIvroutine\fP.  In the case that you would like to write an application
that is graphical but non-interactive, it will be a \fIgraphic hybrid\fP
routine;  follow the instructions for writing a vroutine, but
installing an xvroutine.   The only real difference between writing an
xvroutine and writing an vroutine (aside from adding the
code that will provide the actual functionality of the program), is that
when writing an xvroutine, you will be required to perform the extra
step of running the \fBconductor\fP code generation program in addition to
using the \fBghostwriter\fP code generation program, and you will have to
do a little work in order to integrate the code generated by these two
programs.  The final difference is that vroutines and xvroutines are
located in different sections of the Khoros source tree.
.PP
Regardless of the type of program, adding a new program
to the Khoros system involves integrating it into the
\fBcantata\fP graphical user interface.  This is easily achieved by modifying
the \fBcantata\fP interface to allow access to any new program added
to the system.  Once a new program is written, it is necessary to follow a few
guidelines to ensure that the program is integrated correctly within the
graphical user interface and to provide consistent and maintainable code.
.PP
Throughout the course of writing a new program, several utilities are
available to aid the programmer in writing the source code and designing a
form for the graphical user interface;  two of these have already been
mentioned.  A complete description of each utility, with usage information,
can be obtained by reading the appropriate sections of the Khoros manual;
online manual pages will provide a quick reference for those already familiar
with the utilities.  A listing of these utilities is provided below.
.sp
.IP "\fBghost routines : ghostwriter, ghostreader, and ghostcheck-\fP" 
These are a set of utilities (used with ALL Khoros programs) which are 
used to facilitate the writing of programs in the Khoros environment.  
The user interface specification file (UIS file) provides the information
which \fBghostwriter\fP uses to generate code which automatically parses the
command line, print manual pages, and generate usage statements. 
\fBGhostwriter\fP ensures that certain conventions are followed for all new
code added to the Khoros system.  This is to ensure that the command line 
and graphical user interface are correctly applied and installed.  In 
addition, with the use of a program specification file (PS file) 
\fBghostwriter\fP guarantees that the source code can be easily modified and
maintained within the framework of the Khoros system.  \fBGhostreader\fP
automatically updates the PS file according to changes made in source 
code and man pages, while \fBghostcheck\fP attempts to provide advice when, 
in the course of program maintenance, the user is not sure whether to begin 
by running \fBghostwriter\fP or \fBghostreader\fP.  In-depth explanations of
the  \fBghost routines\fP are provided in Chapter 5 of the Khoros 
Programmer's Manual.
.br
.IP "\fBconductor -\fP"
This is a utility (used ONLY with xvroutines) which 
automatically generates code to initialize and extract information from 
the graphical user interface. A complete explanation of \fBconductor\fP 
is provided in Chapter 6 of the Khoros Programmer's Manual.
.br
.IP "\fBcomposer -\fP" 
This is a top level tool (used with ANY Khoros program,
if desired)  that provides interactive creation/modification of the 
UIS pane file and PS file.  In addition, it presents a graphical user interface 
to the \fBghost routines\fP.  Complete documentation on
\fBcomposer\fP is provided in Chapter 4 of the Khoros Programmer's Manual.
.IP "\fBpreview -\fP"
This is a utility (used with ALL Khoros programs)
that allows the user to view and edit an existing graphical user 
interface specification (UIS) file.  \fBPreview\fP is covered in Chapter 3
of the Khoros Programmer's Manual.
.sp 3
.NH 2 "OVERVIEW OF PROGRAMMING IN THE KHOROS ENVIRONMENT"
.XS
      \*(SN  OVERVIEW OF PROGRAMMING IN THE KHOROS ENVIRONMENT
.XE
.sp 2
.PP
If you are unfamiliar with the details of the \fIUser Interface
Specification (UIS)\fP, it amy be helpful to review Chapter 2
of the Khoros Programmer's Manual.  All of the programs in 
Khoros are based on the UIS.  Reviewing the documentation on the code 
generators in Chapter 5 (Ghost Routines) may be helpful, if you have not
used these routines before.  If your program is to be an xvroutine, 
it is suggested that you read Chapter 6 (Conductor). If you are going to write
a vroutine, it is suggested that you first try to recreate a existing program 
that is similar to the one you will be attempting to write, using it as a 
model or example (this is not really recommended for writers of xvroutines,
as existing programs are simply too long to attempt to re-create.  However,
it is advisable to become familiar with the graphical user interface and
operation of other xvroutines).
.PP
If your new program is an xvroutine, it is recommended that 
prior to designing your xvroutine, you become familiar with the 
layout and operation of existing xvroutines.  Chapter 7 provides
example xvroutines -- simple programs that follow the Khoros standards for 
xvroutines, and that use the \fIxvforms\fP, \fIxvutils\fP, \fIxvgraphics\fP 
and/or \fIxvdisplay\fP libraries.  After you have used 
\fBghostwriter\fP to generate your command-line program, you will need to 
use \fBconductor\fP to generate the code that will initialize
and extract information from the graphical user interface.  
Next, you will need to integrate the main driver generated by 
\fBconductor\fP with the one generated by \fBghostwriter\fP.  There are 
instructions for doing this in Chapter 6 of the Khoros Programmer's Manual.
.PP
After getting the program started under the Khoros system, you will, of
course, need to add the code that will give your new program its functionality.
Finally, you will need to install your new routine in the Khoros
source tree, and add it into the \fBcantata\fP visual language.
To help you do this with your vroutine is a utility program called 
\fBkinstall\fP.  Unfortunately, \fBkinstall\fP does not work with xvroutines,
which must be installed and added to \fBcantata\fP by hand.
Sections B and C of this chapter describe each of the procedures that 
should be followed 
when writing new programs under the Khoros system.
If your intention is to write a vroutine, then follow section B on
writing a vroutine, otherwise proceed to section C on writing an xvroutine.
.sp
