.ds f. uis3.sec
.sp 2
.NH 2 "UIS FILE--LINE SYNTAX"
.XS
      \*(SN  UIS FILE--LINE SYNTAX
.XE
.sp 2
.NH 3 " StartForm (-F) Line"
.XS
              \*(SN   StartForm (-F)
.XE
.sp 2
.B
.nf
syntax:    -F   Vers   Act   Sel   GS   TOffset   'Title'   Var 
.fi
.sp 2
Vers:  
.R
.IP
This is a special \fIversion\fP field, specific to the (-F) line only.  
It is the version number of the current implementation of the \fIxvforms\fP 
library.  The current version of the UIS is 4.2.  Thus, ALL (-F) lines MUST 
have a version number of 4.2.  The version number provides a way for the 
\fIxvforms\fP library to check if the UIS file will have a syntax proper 
to the current implementation.  If, for instance, another field is added to 
the (-F) line at some later date, this field will no longer be 4.2, but will 
be incremented to 4.3.  This allows us to keep track of outdated UIS files, 
and inform the user that they have been outdated.  When Khoros 0.9 was 
distributed, the UIS version had been changed from 4.1 to 4.2, requiring 
those programmers with previously-created UIS files to run the \fBxvupdate\fP
program in order to update their UIS files, and the \fBupdatewksp\fP program
to update saved \fBcantata\fP workspaces.  However, the UIS has undergone
no changes since Khoros 0.9;  therefore, any UIS files or saved \fBcantata\fP
workspaces created under Khoros Beta will be compatible with Khoros 1.0.
.LP
.B
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0 
if the entire user interface is to be de-activated, an extremely rare instance.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field is always set to 1 on the (-F) line.
.LP
.B
GS:
.R
.IP
The \fIgeometry string\fP field, [wxh+x+y] becomes the geometry of the master 
form if a [-S to -E] master form description is present, unused if a master form 
is not used. Never set width or height to 0.  Geometry strings may be specified
as float or integer values.
.LP
.B
TOffset:
.R
.IP
The \fItitle offset\fP field, +x+y, dictates positioning of title 
on the master form if a [-S to -E]
master form description is present, the positioning of title on the backplane
of the subform if a master form is not used.
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks; it 
will appear as the title on the
master form if the [-S to -E] master form definition occurs; will appear on
the backplane of the subform if a master form is not used, and if the subform
geometry does not obscure it.  If no title is desired, specify ' '.
.LP
.B
Var:
.R
.IP
The \fIvariable\fP name is used by the \fBconductor\fP code generation program 
to name the Form Information structure that it generates.  For more details,
see the documentation on \fBconductor\fP.
.sp
.LP
.B
.ps 10
.nf
example:   -F  4.2  1  1  70x90+0+0  +5+1  'Our Form'  tutorial
.fi
.R
.sp
.IP
In the above example, the StartForm line shows that the UIS is of the current
version, 4.2;  the \fIactive\fP field is set as required, and the title "Our
Form" is correctly surrounded by tic marks.  The title will appear five 
character widths over and one character width down from the upper left hand
corner of the backplane of the form.
.sp 3
.NH 3 " StartMaster (-S) Line"
.XS
              \*(SN   StartMaster (-S)
.XE
.sp 2
.B
.nf
syntax:    -S   Act   Mutually_Exclusive
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0 
if the entire master form is to be de-activated, an extremely rare instance.
.LP
.B
Mutually_Exclusive:  
.R
.IP
This is a special field, specific to the (-S) line only.  It tells whether
the subform buttons specified by the (-d) lines within the master form 
definition [-S to -E] are mutually exclusive with each other.  Note that 
this field has absolutely nothing to do with the (-C) line, which designates
a mutually exclusive group of selections.  If the \fIMutually_Exclusive\fP
field is set to 0, the \fIxvforms\fP library will allow any or all of the
subforms associated with the subform buttons to map when a subform button
is clicked on by the user.  If the \fIMutually_Exclusive\fP field is set to
1, only one subform will be allowed to map at any time.  If the user clicks on
a subform button while a subform is already mapped, the previous subform will
go away, and the new subform will replace it.
.sp
.LP
.B
.ps 10
.nf
example:   -S  1  1
.fi
.R
.sp
.IP
In the example, the presence of the StartMaster line indicates that we will
be using a master form; subform buttons on the master will be mutually 
exclusive, so that the user will not be able to map more than one subform at
any one time.
.sp 3
.NH 3 " SubFormButton (-d) Line"
.XS
              \*(SN   SubFormButton (-d) 
.XE
.sp 2
.B
.nf
syntax:    -d   Act   Sel   GS   'Title'
.fi
.sp 2
Act:
.R
.IP 
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 
0 if the subform associated with the subform button described by this 
(-d) line is to be deactivated.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 1 
if the subform associated with the subform button described by this 
(-d) line is to be automatically mapped along with the master form, 
not a very common usage.
.LP
.B
GS:
.R
.IP
The \fIgeometry string\fP field, wxh+x+y, in characters, describes the size 
of the subform button and its position on the master in characters. 
Note that the width field must be large enough to accommodate the title, 
or the title will be truncated.   Geometry strings may be specified
as float or integer values.
.LP 
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks; will appear as 
the title on the subform button.  
.sp
.LP
.B
.ps 10
.nf
example:   -d  1  0  10x2+2+2  'Subform 1'
.fi
.R
.sp
.IP
In the example, we have a subform button, 10 characters wide by 2 characters
tall, located 2 characters to the right and 2 characters down from the upper
left hand corner of the master, labeled "Subform 1".  Suppose that this is
the third (-d) line in the master definition.  Then, the subform button
produced by this line will control the mapping of the subform which is 
described by the third [-M to -E] subform definition.
.sp 3
.NH 3 " MasterAction (-n) Line"
.XS
              \*(SN   MasterAction (-n)
.XE
.sp 2
.B
.nf
syntax:    -n   Act   Sel   GS   'Title'   'Desc'   Var
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0 
if the action button described by this (-n) line is to be deactivated.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, always set to 0.
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y, in characters, describes the size of the 
action button and its position on the master in characters. Note that the 
width field must be large enough to accommodate the title, or the title will 
be truncated.  Geometry strings may be specified as float or integer values.
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks; will appear 
as the title on the action button.  
.LP
.B
Desc:
.R
.IP
The \fIdescription\fP string must be delineated by tic marks; it should
mention what the action button is for.
.LP
.B
Var:
.R
.IP
The \fIvariable\fP name is used by the \fBconductor\fP code generation 
program to name the elements corresponding to this action button in the 
Form Information structure that it generates.  For more details, see the 
documentation on \fBconductor\fP.
.sp
.LP
.B
.ps 10
.nf
example:   -n  1  0  7x2+2+5  'Info'  'Gives information'  info
.fi
.R
.sp
.IP
In the example, we have a master action button, 7  characters wide by 2 
characters tall, located 2 characters to the right and 5 characters down 
from the upper left hand corner of the master, labeled "Info".
.sp 3
.NH 3 " PsuedoSubform (-u) Line"
.XS
              \*(SN   PsuedoSubform (-u)
.XE
.sp 2
.B
.nf
syntax:    -u   Act   Sel   GS   'Title'
.fi
.sp 2
Act:
.R
.IP 
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 
0 if the subform associated with the psuedo-subform button described by this 
(-u) line is to be deactivated.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, always set to 0 (FALSE).  
.LP
.B
GS:
.R
.IP
The \fIgeometry string\fP field, wxh+x+y, in characters, describes the size 
of the psuedo-subform button and its position on the master in characters. 
Note that the width field must be large enough to accommodate the title, 
or the title will be truncated. Geometry strings may be specified as float
or integer values.
.LP 
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks; will appear as 
the title on the psuedo-subform button.  
.sp
.LP
.B
.ps 10
.nf
example:   -u  1  0  17x2+4+2  'Psuedo-Subform'
.fi
.R
.sp
.IP
In the example, we have a psuedo-subform button, 17 characters wide by 2 characters
tall, located 4 characters to the right and 2 characters down from the upper
left hand corner of the master, labeled "Psuedo-Subform".  Suppose that this is
the third (-u or -d) line in the master definition.  Then, the application
program will be in charge of mapping of the subform which is described by the 
third [-M to -E] subform definition when the user clicks on this button.
.sp 3
.NH 3 " Help (-H) Line"
.XS
              \*(SN   Help (-H)
.XE
.sp 2
.B
.nf
syntax:    -H   Act   GS   'Title'   'Desc'   Help_Path
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0
if the help button described by this (-H) line is to be deactivated.
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y, in characters, describes the size of the
help button and its position on the master in characters. Note that the
width field must be large enough to accommodate the title, or the title will
be truncated. Geometry strings may be specified as float or integer values.
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks; will appear
as the title on the help button.  
.LP
.B
Desc:
.R
.IP
The \fIdescription\fP string must be delineated by tic marks; it should
mention what the help file(s) talk about.
.LP
.B
Help_Path:
.R
.IP
This path may be the path of a specific help file to be displayed
when the user clicks on the Help button, or it may be the path to a directory
in which two or more help files are contained.  If the \fIhelp_path\fP accesses
a particular file, the help widget will come up with that file displayed in 
it.  If it accesses a directory, the Help widget that comes up will have 
buttons across the top, one for each file in the directory.  When the user 
clicks on one of the buttons, the file that it names will be displayed. When
this latter method is used, it is recommended that a special file be created
in the directory, labeled "Overview".  The routine that creates a Help widget
will look in the specified directory for this file, and if it exists, will 
initially display this file in the help widget.  The "Overview" file should
list the other help files that are available, and mention the subjects that
are discussed therein.  NOTE:  if a directory is specified as the help path,
it is important to make sure that no extraneous files exist in that directory,
as the help widget will create a button labeled with the name of every file
in the directory, and allow the user to access every file in the directory. 
NOTE: if the \fIhelp_path\fP specified is invalid, the user will receive an
error message when they click on the help button.
.sp 
.LP
.B
.ps 10
.nf
example:   -H  1  7x2+2+7 'Help'  KHOROS_HOME/doc/xprism/output/formatted
.fi
.R
.sp
.IP
The \fIHelp_Path\fP used here specifies
a directory (note that the use of the KHOROS_HOME environment variable is 
accepted, as is the use of a tilde, "~").  This particular directory happens to
contain 5 help files that discuss methods of output for the \fBxprism2\fP and
\fBxprism3\fP plotting packages; all of them are properly formatted for online 
display. When the user clicks on the help button,
the help widget will appear with 5 buttons, one for each file in the directory.
The file named "Overview" found in this directory will initially be displayed
in the text window.
.sp 3
.NH 3 " Quit (-Q) Line"
.XS
              \*(SN   Quit (-Q)
.XE
.sp 2
.B
.nf
syntax:    -Q   Act   Sel   GS   'Title' 
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0
if the quit button described by this (-Q) line is to be deactivated.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, always set to 0 (FALSE).  
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y, in characters, describes the size of the
quit button and its position on the master in characters. Note that the
width field must be large enough to accommodate the title, or the title will
be truncated. Geometry strings may be set to float or integer values.
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks; will appear
as the title on the help button.  If the (-Q) line describing the quit button
appears in the description of a subform that is subordinate to a master form,
this title is often specified as 'Close', since it causes the subform to unmap, 
rather than causing the program to end.
.sp
.LP
.B
.ps 10
.nf
example:   -Q  1  0  5x2+2+9  'Quit'
.fi
.R
.sp
.IP
In the example, we have a quit button, 5  characters wide by 2 
characters tall, located 2 characters to the right and 9 characters down 
from the upper left hand corner of the master, guide pane, or pane on which
it appears, labeled "Quit".  
.sp 3
.NH 3 " StartSubMenu (-D) Line"
.XS
              \*(SN   StartSubMenu (-D)
.XE
.sp 2
.B
.nf
syntax:    -D   Act   Sel   GS   TOffset   'Title'   Var
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0
if the submenu button described by this (-D) line is to be deactivated.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, always set to 0.
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y, in characters, describes the size of the
submenu button and its position on the master in characters. Note that the
width field must be large enough to accommodate the title, or the title will
be truncated. Geometry strings may be set to float or integer values.
.LP
.B
TOffset:
.R
.IP
The \fItitle offset\fP field, +x+y, currently unused at this time, but
may not be omitted.  Use +0+0.
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks; will appear
as the title on the submenu button.  
.LP
.B
Var:
.R
.IP
The \fIvariable\fP field is currently unused at this time, but it may 
not be omitted.
.sp
.LP
.B
.ps 10
.nf
example:   -D  1  0  10x5+4+3  +0+0 'Output'  submenu
.fi
.R
.sp
.IP
In the example, we are creating a submenu button that is 10 characters wide
and 5 characters high, located 4 characters to the right and 3 characters down
from the upper left hand corner of the master on which it appears.  It will be
labeled "Output", implying that the subforms accessible via this pull-down
submenu will perhaps allow the user to perform different types of output.
.sp 3
.NH 3 " StartSubForm (-M) Line"
.XS
              \*(SN   StartSubForm (-M)
.XE
.sp 2
.B
.nf
syntax:    -M   Act   Sel   GS   TOffset   'Title'   Var
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0
if the subform described by the [-M to -E] set beginning with this (-M) 
line is to be deactivated.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, always set to 0, except in the one rare case when,
in the master form [-S to -E] description, the (-d) SubFormButton line that
is paired with this subform has its \fIselected\fP field set to 1, indicating
that this subform should be mapped immediately, along with the master form.
Subforms are very rarely mapped immediately.
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y. If no master form is used, the geometry
describes, in characters, the size of the subform and its position 
on the backplane. If a master form is used, the geometry should be large enough
to accommodate the guide pane (if there is one) plus the largest of all panes
that will appear on this subform. Geometry strings may be set to float or integer values.
.LP
.B
TOffset
.R
.IP
The \fItitle offset\fP field, +x+y, specifies in characters the distance from
the upper left hand corner of the backplane of the subform that the subform
title should appear.
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks; will appear
on the backplane of the subform at the position specified by the \fItitle 
offset\fP, unless it is obscured by one of the panes on the subform.
If no title is desired, specify ' '.
.LP
.B
Var:
.R
.IP
The \fIvariable\fP name is used by the \fBconductor\fP code generation 
program to name the structure corresponding to this subform in the 
Form Information structure that it generates.  For more details, see the 
documentation on \fBconductor\fP.
.sp
.LP
.B
.ps 10
.nf
example:   -M  1  0  50x70+6+8  +5+1  'Subform Number One'  subform_one 
.fi
.R
.sp
.IP
In this example, we have a subform labeled "Subform Number One"; this title
will appear 5 characters to the right and 1 character down from the upper
left hand corner of the backplane of the subform.
.sp 3
.NH 3 " StartGuide (-G) Line"
.XS
              \*(SN   StartGuide (-G)
.XE
.sp 2
.B
.nf
syntax:    -G   Act   GS   TOffset   'Title'
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0
if the guide pane described by the [-G to -E] set beginning with this (-G) 
line is to be deactivated; a very rare situation.
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y, describes, in characters, the size of the 
guide pane and its position on the subform. The geometry should be large enough
to accommodate all the buttons on the guide pane. Geometry strings may be set to float or integer values.
.LP
.B
TOffset:
.R
.IP
The \fItitle offset\fP field, +x+y, specifies in characters the distance from
the upper left hand corner of the backplane of the guide pane that the guide
pane title should appear.
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks; will appear
on the backplane of the guide pane at the position specified by the \fItitle 
offset\fP, unless it is obscured by one of the buttons on the guide pane.
If no title is desired, specify ' '.
.sp
.LP
.B
.ps 10
.nf
example:   -G  1  20x70+0+0  +0+0  ' '
.fi
.R
.sp
.IP
This example shows a guide pane that will appear along the left side of the
subform on which it appears.  The title has been deliberately left out.
.sp 3
.NH 3 " GuideButton (-g) Line"
.XS
              \*(SN   GuideButton (-g)
.XE
.sp 2
.B
.nf
syntax:    -g   Act   Sel   GS   'Title'
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0
if the pane described by the [-P to -E] set associated with this (-g) 
line is to be deactivated; a common way to de-activate a pane on a subform.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 1 
if the pane associated with the guide button described by this (-g) line is 
the one to be displayed immediately when this subform is mapped. In this case,
you must make sure that the (-P) line of the [-P to -E] pane definition
describing the pane associated with this (-g) guide button also has its 
\fIselected\fP field set to 1.
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y, describes, in characters, the size of the 
guide button and its position on the guide pane. The geometry should be large 
enough to accommodate the title, or it will be truncated. Geometry strings may be set to float or integer values.
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks; will appear
on the backplane of the guide pane at the position specified by the \fItitle 
offset\fP, unless it is obscured by one of the buttons on the guide pane.
.sp
.LP
.B
.ps 10
.nf
example:   -g  1  0  5x2+6+1  'Input'
.fi
.R
.sp
.IP
In this example, we are creating a guide button labeled "Input", implying the
pane that it is associated with will deal with input.  It is 5 characters wide
and 2 characters high, located 6 characters to the right and 1 character down
from the upper left hand corner of the guide pane in which it is located.  
Suppose that this is the second (-g) line to appear in the guide pane 
definition.  Thus, the guide button produced by
this (-g) line will control the mapping of the pane described by the second
[-P to -E] pane definition.  Since the \fIselected\fP field of this second
(-g) line is set to 0, we must make sure that the (-P) line of the second
[-P to -E] pane definition in this subform definition is also set to 0.  If we
had wanted the second pane to appear on this subform as the default, we would
have set the \fIselected\fP field on this (-g) line to 1; we would have
to go to the second (-P) line and set its \fIselected\fP field to 1 also, and
finally would have to check all other (-g) and (-P) lines to make sure that all
the other \fIselected\fP fields on these other lines were set to 0, so as not
to interfere.
.sp 3
.NH 3 " SubformAction (-m) Line"
.XS
              \*(SN   SubformAction (-m)
.XE
.sp 2
.B
.nf
syntax:    -m   Act   Sel   GS   'Title'   'Desc'   Var
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0 
if the action button described by this (-m) line is to be deactivated.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, always set to 0.
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y, in characters, describes the size of the 
action button and its position on the master in characters. Note that the 
width field must be large enough to accommodate the title, or the title will 
be truncated. Geometry strings may be set to float or integer values.
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks; will appear 
as the title on the action button.
.LP
.B
Desc:
.R
.IP
The \fIdescription\fP string, it must be delineated by tic marks; give a 
brief description of the purpose of the action button.
.LP
.B
Var:
.R
.IP
The \fIvariable\fP name is used by the \fBconductor\fP code generation 
program to name the elements corresponding to this action button in the 
Form Information structure that it generates.  For more details, see the 
documentation on \fBconductor\fP.
.sp
.LP
.B
.ps 10
.nf
example:   -m  1  0  7x2+2+5  'Plot'  'Plot the data'  plot
.fi
.R
.sp
.IP
In the example, we have a subform action button, 7  characters wide by 2 
characters tall, located 2 characters to the right and 5 characters down 
from the upper left hand corner of the guide pane, labeled "Plot".
.sp 3
.NH 3 " StartPane (-P) Line"
.XS
              \*(SN   StartPane (-P)
.XE
.sp 2
.B
.nf
syntax:    -P   Act   Sel   GS   TOffset   'Title'   Var
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0
if the pane described by the [-M to -E] set beginning with this (-M) 
line is to be deactivated.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, always set to 0, except in the case when,
in the guide pane [-G to -E] description, the (-g) GuideButton line that
is paired with this pane has its \fIselected\fP field set to 1, indicating
that this pane should be displayed immediately when this subform is mapped.
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y. The geometry describes, in characters, 
the size of the pane and its position on the subform. 
The geometry should be large enough to accommodate all selections on the 
pane. Geometry strings may be set to float or integer values.
.LP
.B
TOffset
.R
.IP
The \fItitle offset\fP field, +x+y, specifies in characters the distance from
the upper left hand corner of the backplane of the pane that the pane
title should appear.
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks; will appear
on the backplane of the pane at the position specified by the \fItitle 
offset\fP, unless it is obscured by one of the selections on the pane.
If no title is desired, specify ' '.
.LP
.B
Var:
.R
.IP
The \fIvariable\fP name is used by the \fBconductor\fP code generation 
program to name the structure corresponding to this pane in the 
Form Information structure that it generates.  For more details, see the 
documentation on \fBconductor\fP.
.sp
.LP
.B
.ps 10
.nf
example:   -P  1  0  30x70+20+2  +10+2  'Pane Number One'  pane_one 
.fi
.R
.sp
.IP
In this example, we have a pane labeled "Pane Number One"; this title
will appear 5 characters to the right and 2 characters down from the upper
left hand corner of the backplane of the pane.  Note that the geometry specifies
that this pane is to be created 20 characters to the right of the upper left
hand corner of the subform that it resides in - most likely to make room for
a guide pane to the left.
.sp 3
.NH 3 " InputFile (-I) Line"
.XS
              \*(SN   InputFile (-I)
.XE
.sp 2
.B
.nf
syntax:    -I   Act   Sel   Opt   OptSel   Live   FileType   GS   TOffset   'Def'   'Title'   'Desc'   Var
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0
if the input selection described by the (-I) line is to be deactivated.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, always set to 0. 
.LP
.B
Opt:
.R
.IP
The \fIoptional\fP field, 1 if selection is optional, 0 if it is required.
.LP
.B
OptSel:
.R
.IP
The \fIoption selected\fP field; 1 if selection is required, 1 if it is optional
and the default action is to use the default value provided, 0 if it is 
optional and the default action is to ignore its value.
.LP
.B
Live:
.R
.IP
The \fIlive\fP field, 1 if the selection is to return immediately when the user
hits <cr>, 0 otherwise.
.LP
.B
FileType:
.R
.IP
The \fIfile type\fP field, not currently used, will in the future indicate what
type of input file is expected.  Set this field to 1 for now.
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y. The geometry describes, in characters, 
the size of the input file selection and its position on the pane. 
The geometry should be large enough to accommodate all components of the input
file selection - the optional box, if the selection is optional, the title,
and a reasonable amount of space for the parameter box in which the user will
type in the filename of the inputfile. Geometry strings may be set to float or integer values.
.LP
.B
TOffset
.R
.IP
The \fItitle offset\fP field, +x+y, specifies in characters the distance from
the upper left hand corner of the backplane of the selection that the title
should appear. This is generally set to +0+0 on an input file selection
.LP
.B
Def:
.R
.IP
The \fIdefault\fP field may contain a value for the default input file, or
may contain a space, indicating that no default is applicable.  The default
field must be surrounded by tic marks.
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks;  it should be 
as short as possible, yet should still give a clear idea as to the purpose of
the input file.  If no title is desired, specify ' '.
.LP
.B
Desc:
.R
.IP
The \fIdescription\fP field should contain a short description of the input 
file; \fBghostwriter\fP will use this string as a comment when generating code
for the command line user interface. The description must be surrounded by
tic marks.  
.LP
.B
Var:
.R
.IP
The \fIvariable\fP name is used by \fBghostwriter\fP to determine the name
of the flag that will mark this input file argument to the program.  
The user must specify "-\fIvariable\fP filename" on the command line, 
as one of the arguments.  The \fIvariable\fP name is also used by the 
\fBconductor\fP code generation program to name the fields corresponding 
to this selection in the Form Information structure that it generates.  
For more details, see the documentation on \fBghostwriter\fP and 
\fBconductor\fP.  
.sp
.LP
.B
.ps 10
.nf
example:   -I  1  0  0  1  1  1  40x1+1+4  +0+0  ' '  'Input Image'  'the input image'  i1
.fi
.R
.sp
.IP
In this example, we have a required input file selection that is "live", so
that when used with a graphical user interface, control will be returned 
immediately to the application when the user hits <cr> in the parameter box.
The \fIfile type\fP is 1, indicating that the input file will be a image file
formatted for the Khoros System.  The selection has been given plenty of room-
40 characters- so that the parameter box will be nice and long;  the title of
this input file selection is "Input Image". The name of the field in the
Form Information structure generated by \fBconductor\fP will be identifiable by
the letters, "i1", and the flag provided for the command line user interface
will be "-i1 filename". 
.sp 3
.NH 3 " OutputFile (-O) Line"
.XS
              \*(SN   OutputFile (-O)
.XE
.sp 2
.B
.nf
syntax:    -O   Act   Sel   Opt   OptSel   Live   FileType   GS   TOffset   'Def'   'Title'   'Desc'   Var
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0
if the output selection described by the (-O) line is to be deactivated.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, always set to 0. 
.LP
.B
Opt:
.R
.IP
The \fIoptional\fP field, 1 if selection is optional, 0 if it is required.
.LP
.B
OptSel:
.R
.IP
The \fIoption selected\fP field; 1 if selection is required, 1 if it is optional
and the default action is to use the default value provided, 0 if it is 
optional and the default action is to ignore its value.
.LP
.B
Live:
.R
.IP
The \fIlive\fP field, 1 if the selection is to return immediately when the user
hits <cr>, 0 otherwise.
.LP
.B
FileType:
.R
.IP
The \fIfile type\fP field, not currently used, will in the future indicate what
type of output file is expected.  Set this field to 1 for now.
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y. The geometry describes, in characters, 
the size of the output file selection and its position on the pane. 
The geometry should be large enough to accommodate all components of the output
file selection - the optional box, if the selection is optional, the title,
and a reasonable amount of space for the parameter box in which the user will
type in the filename of the output file. Geometry strings may be set to float or integer values.
.LP
.B
TOffset
.R
.IP
The \fItitle offset\fP field, +x+y, specifies in characters the distance from
the upper left hand corner of the backplane of the selection that the title
should appear. This is generally set to +0+0 on an output file selection
.LP
.B
Def:
.R
.IP
The \fIdefault\fP field may contain a value for the default output file, or
may contain a space, indicating that no default is applicable.  The default
field must be surrounded by tic marks.
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks;  it should be 
as short as possible, yet should still give a clear idea as to the purpose of
the output file.  If no title is desired, specify ' '.
.LP
.B
Desc:
.R
.IP
The \fIdescription\fP field should contain a short description of the output 
file; \fBghostwriter\fP will use this string as a comment when generating code
for the command line user interface. The description must be surrounded by
tic marks.  
.LP
.B
Var:
.R
.IP
The \fIvariable\fP name is used by \fBghostwriter\fP to determine the name
of the flag that will mark this output file argument to the program.  
The user may specify "-\fIvariable\fP filename" on the command line, 
as one of the arguments.  The \fIvariable\fP name is also used by the 
\fBconductor\fP code generation program to name the fields corresponding 
to this selection in the Form Information structure that it generates.  
For more details, see the documentation on \fBghostwriter\fP and 
\fBconductor\fP.  
.sp
.LP
.B
.ps 10
.nf
example:
.sp
-O 1  0  1  0  0  1  40x1+1+4 +0+0  ' '  'Blurred Output Image'  'output blurred image'  o2
.fi
.R
.sp
.IP
In this example, we have an optional output file selection; the default action
will be to ignore this selection, as the \fIoption selected\fP field is set to
false, and no default value has been provided.  The \fIfile type\fP is 1, 
indicating that if this selection is used, the output file will be a image file
formatted for the Khoros System.  The selection has been given plenty of room-
40 characters- so that the parameter box will be nice and long;  the title of
this output file selection is "Blurred Output Image". The name of the field 
in the Form Information structure generated by \fBconductor\fP will be 
identifiable by the letters, "o2", and the flag provided for the command 
line user interface will be "-o2 filename". 
.sp 3
.NH 3 " Integer (-i) Line"
.XS
              \*(SN   Integer (-i)
.XE
.sp 2
.B
.nf
syntax:    -i   Act   Sel   Opt   OptSel   Live   GS TOffset   LB   UB   Def   'Title'   'Desc'   Var
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0
if the integer selection described by the (-i) line is to be deactivated.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, always set to 0. 
.LP
.B
Opt:
.R
.IP
The \fIoptional\fP field, 1 if selection is optional, 0 if it is required.
.LP
.B
OptSel:
.R
.IP
The \fIoption selected\fP field; 1 if selection is required, 1 if it is optional
and the default action is to use the default value provided, 0 if it is 
optional and the default action is to ignore its value.
.LP
.B
Live:
.R
.IP
The \fIlive\fP field, 1 if the selection is to return immediately when the user
hits <cr>, 0 otherwise.
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y. The geometry describes, in characters, 
the size of the integer selection and its position on the pane. 
The geometry should be large enough to accommodate all components of the integer
file selection - the optional box, if the selection is optional, the title,
and a reasonable amount of space for the parameter box in which the user will
type in a value for the integer.  Extra space must be allocated for a
scroll bar, if one is desired. Geometry strings may be set to float or integer values.
.LP
.B
TOffset
.R
.IP
The \fItitle offset\fP field, +x+y, specifies in characters the distance from
the upper left hand corner of the backplane of the selection that the title
should appear. This is generally set to +0+0 on an integer selection.
.LP
.B
LB and UB
.R
.IP
The \fIlower bound\fP and \fIupper bound\fP fields of the integer selection
are very important.  Here are the possible values for the lower and upper
bounds of an integer:
.sp
.in +1i
LB = UB = -2 {legal values  < 0}
.br
LB = UB = -1 {legal values <= 0}
.br
LB = UB =  1 {legal values >= 0}
.br
LB = UB =  2 {legal values >  0}
.br
LB = UB =  X {no range checking}
.br
LB = X;  UB = Y  { X <= legal value <= Y}
.in -1i
.sp
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks;  it should be 
as short as possible, yet should still give a clear idea as to the purpose of
the integer's use.  If no title is desired, specify ' '.
.LP
.B
Desc:
.R
.IP
The \fIdescription\fP field should contain a short description of the purpose 
of the integer; \fBghostwriter\fP will use this string as a comment when 
generating code for the command line user interface. The description must 
be surrounded by tic marks.  
.LP
.B
Var:
.R
.IP
The \fIvariable\fP name is used by \fBghostwriter\fP to determine the name
of the flag that will mark this integer argument to the program.  
The user might specify "-\fIvariable\fP 5" on the command line, 
as one of the arguments.  The \fIvariable\fP name is also used by the 
\fBconductor\fP code generation program to name the fields corresponding 
to this selection in the Form Information structure that it generates.  
For more details, see the documentation on \fBghostwriter\fP and 
\fBconductor\fP.  
.sp
.LP
.B
.ps 10
.nf
example:   -i  1  0  0  1  0  50x1+1+4  +0+0  0  255  40  'Threshold'  'threshold value'  thres
.fi
.R
.sp
.IP
In this example, we have an required integer selection; The selection has 
been given plenty of room- 50 characters- so that the bounded integer will be
given a scroll bar next to the parameter box; because there is lots of room,
the scroll bar will be long, and therefore precise.  The title of this integer
selection is "Threshold". Legal values for the Threshold integer will be from
0 to 255, inclusive, and the default value will be 40.  
The name of the field in the Form Information 
structure generated by \fBconductor\fP will be identifiable by the letters, 
"thres", and the flag provided for the command line user interface might be 
"-thres 10". 
.sp 3
.NH 3 " Float (-f) Line"
.XS
              \*(SN   Float (-f)
.XE
.sp 2
.B
.nf
syntax:    -f   Act   Sel   Opt   OptSel   Live   GS   TOffset   LB   UB   Def   'Title'   'Desc'   Var
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0
if the float selection described by the (-f) line is to be deactivated.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, always set to 0. 
.LP
.B
Opt:
.R
.IP
The \fIoptional\fP field, 1 if selection is optional, 0 if it is required.
.LP
.B
OptSel:
.R
.IP
The \fIoption selected\fP field; 1 if selection is required, 1 if it is optional
and the default action is to use the default value provided, 0 if it is 
optional and the default action is to ignore its value.
.LP
.B
Live:
.R
.IP
The \fIlive\fP field, 1 if the selection is to return immediately when the user
hits <cr>, 0 otherwise.
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y. The geometry describes, in characters, 
the size of the float selection and its position on the pane. 
The geometry should be large enough to accommodate all components of the float
selection - the optional box, if the selection is optional, the title,
and a reasonable amount of space for the parameter box in which the user will
type in the value of the float.  Extra space must be allocated for a
scroll bar, if one is desired. Geometry strings may be set to float or integer values.
.LP
.B
TOffset
.R
.IP
The \fItitle offset\fP field, +x+y, specifies in characters the distance from
the upper left hand corner of the backplane of the selection that the title
should appear. This is generally set to +0+0 on float selection
.LP
.B
LB and UB
.R
.IP
The \fIlower bound\fP and \fIupper bound\fP fields of the float selection
are very important.  Here are the possible values for the lower and upper
bounds of a float:
.sp
.in +1i
LB = UB = -2 {legal values  < 0.0}
.br
LB = UB = -1 {legal values <= 0.0}
.br
LB = UB =  1 {legal values >= 0.0}
.br
LB = UB =  2 {legal values >  0.0}
.br
LB = UB =  X {no range checking}
.br
LB = X;  UB = Y  { X <= legal value <= Y}
.sp
.in -1i
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks;  it should be 
as short as possible, yet should still give a clear idea as to the purpose of
the float's use.  If no title is desired, specify ' '.
.LP
.B
Desc:
.R
.IP
The \fIdescription\fP field should contain a short description of the purpose 
of the integer; \fBghostwriter\fP will use this string as a comment when 
generating code for the command line user interface. The description must 
be surrounded by tic marks.  
.LP
.B
Var:
.R
.IP
The \fIvariable\fP name is used by \fBghostwriter\fP to determine the name
of the flag that will mark this float argument to the program.  
The user might specify "-\fIvariable\fP 3.5" on the command line, 
as one of the arguments.  The \fIvariable\fP name is also used by the 
\fBconductor\fP code generation program to name the fields corresponding 
to this selection in the Form Information structure that it generates.  
For more details, see the documentation on \fBghostwriter\fP and 
\fBconductor\fP.  
.sp
.LP
.B
.ps 10
.nf
example:
.sp
-f  1  0  1  1  0  25x1+1+4 +0+0  -2.0 -2.0 -3.0  'Neg Displacement'  'neg displace value'  dspmt
.fi
.R
.sp
.IP
In this example, we have an optional float selection; since the option
selected\fP field is set to 1, the default action will be to use the default 
value of -3.0. The selection has been given just enough room--25 
characters--and we know that it cannot have a scroll bar, since the value is 
unbounded. Legal values are any floats strictly less than 0.0. The title of this
float selection is "Neg Displacement".  The name of the field in the Form 
Information structure generated by \fBconductor\fP will be identifiable by 
the letters, "dspmt", and the flag provided for the command line user 
interface might be "-dspmt -10.0". 
.sp 3
.NH 3 " String (-s) Line"
.XS
              \*(SN   String (-s)
.XE
.sp 2
.B
.nf
syntax:    -s   Act   Sel   Opt   OptSel   Live   GS   TOffset   'Def'   'Title'   'Desc'   Var
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0
if the string selection described by the (-s) line is to be deactivated.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, always set to 0. 
.LP
.B
Opt:
.R
.IP
The \fIoptional\fP field, 1 if selection is optional, 0 if it is required.
.LP
.B
OptSel:
.R
.IP
The \fIoption selected\fP field; 1 if selection is required, 1 if it is optional
and the default action is to use the default value provided, 0 if it is 
optional and the default action is to ignore its value.
.LP
.B
Live:
.R
.IP
The \fIlive\fP field, 1 if the selection is to return immediately when the user
hits <cr>, 0 otherwise.
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y. The geometry describes, in characters, 
the size of the string selection and its position on the pane. 
The geometry should be large enough to accommodate all components of the string
selection - the optional box, if the selection is optional, the title,
and a reasonable amount of space for the parameter box in which the user will
type in the value of the string. Geometry strings may be set to float or integer values.
.LP
.B
TOffset
.R
.IP
The \fItitle offset\fP field, +x+y, specifies in characters the distance from
the upper left hand corner of the backplane of the selection that the title
should appear. This is generally set to +0+0 on an string selection.
.LP
.B
Def:
.R
.IP
The \fIdefault\fP field may contain a value for the string, or
may contain a space, indicating that no default is applicable.  The default
field must be surrounded by tic marks.
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks;  it should be 
as short as possible, yet should still give a clear idea as to the purpose of
the string. If no title is desired, specify ' '.
.LP
.B
Desc:
.R
.IP
The \fIdescription\fP field should contain a short description of the purpose
of the string selection;
\fBghostwriter\fP will use this description as a comment when generating code
for the command line user interface. The description must be surrounded by
tic marks.  
.sp 3
.LP
.B
Var:
.R
.IP
The \fIvariable\fP name is used by \fBghostwriter\fP to determine the name
of the flag that will mark this string argument to the program.  
The user may specify "-\fIvariable\fP string" on the command line, 
as one of the arguments.  The \fIvariable\fP name is also used by the 
\fBconductor\fP code generation program to name the fields corresponding 
to this selection in the Form Information structure that it generates.  
For more details, see the documentation on \fBghostwriter\fP and 
\fBconductor\fP.  
.sp
.LP
.B
.ps 10
.nf
example:   -s  1  0  0  1  0  40x2+1+5  +0+0  'sin(x)*cos(y)'  'Function'  '3D function'  function
.fi
.R
.sp
.IP
In this example, we have a required string selection. The selection has been 
given an excessive amount of room--40 characters long and 2 characters 
high-- so that the parameter box will have lots of room for the function, and 
if that isn't enough, the cursor will wrap around to the second line. The title 
of this string selection is "Function", and the default value of this function 
is "sin(x)*cos(y)". The name of the field in the Form Information structure 
generated by \fBconductor\fP will be identifiable by the letters, "function", 
and the flag provided for the command line user interface will be "-function 
xxxxxx". 
.sp 3
.NH 3 " Logical (-l) Line"
.XS
              \*(SN   Logical (-l)
.XE
.sp 2
.B
.nf
syntax:    -l   Act   Sel   Opt   OptSel   Live   GS   TOffset   Def   'Title'   'L0'   'L1'   'Desc'   Var
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0
if the logical selection described by the (-l) line is to be deactivated.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, always set to 0. 
.LP
.B
Opt:
.R
.IP
The \fIoptional\fP field, 1 if selection is optional, 0 if it is required.
.IP OptSel:
The \fIoption selected\fP field; 1 if selection is required, 1 if it is optional
and the default action is to use the default value provided, 0 if it is 
optional and the default action is to ignore its value.
.LP
.B
Live:
.R
.IP
The \fIlive\fP field, 1 if the selection is to return immediately when the user
changes the value of the logical, 0 otherwise.
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y. The geometry describes, in characters, 
the size of the logical selection and its position on the pane. 
The geometry should be large enough to accommodate all components of the logical
selection - the optional box, if the logical is optional, the title, and the
oval button which will display the current boolean value of the logical. Geometry strings may be set to float or integer values.
.LP
.B
TOffset
.R
.IP
The \fItitle offset\fP field, +x+y, specifies in characters the distance from
the upper left hand corner of the backplane of the selection that the title
should appear. This is generally set to +0+0 on a logical selection.
.LP
.B
Def:
.R
.IP
The \fIdefault\fP field specifies the default value of the logical.  It must 
be set to 1 (TRUE) or 0 (FALSE).
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks;  it should be 
as short as possible, yet should still give a clear idea as to the purpose of
the logical selection. If no title is desired, specify ' '.
.LP
.B
L0:
.R
.IP
The \fIlabel0\fP string, it must be delineated by tic marks;  this is the label
that will appear on the oval value widget of the logical selection when the
value of the logical is equal to 0.  The most common \fIlabel0\fP string is
"False".  
.LP
.B
L1:
.R
.IP
The \fIlabel1\fP string, it must be delineated by tic marks;  this is the label
that will appear on the oval value widget of the logical selection when the
value of the logical is equal to 1.  The most common \fIlabel0\fP string is
"True".
.LP
.B
Desc:
.R
.IP
The \fIdescription\fP field should contain a short description of the string
\fBghostwriter\fP will use this description as a comment when generating code
for the command line user interface. The description must be surrounded by
tic marks.  
.LP
.B
Var:
.R
.IP
The \fIvariable\fP name is used by \fBghostwriter\fP to determine the name
of the flag that will mark this logical argument to the program.  
The user may specify "-\fIvariable\fP {1/0}" on the command line, 
as one of the arguments.  The \fIvariable\fP name is also used by the 
\fBconductor\fP code generation program to name the fields corresponding 
to this selection in the Form Information structure that it generates.  
For more details, see the documentation on \fBghostwriter\fP and 
\fBconductor\fP.  
.sp
.LP
.B
.ps 10
.nf
example:
.sp
-l  1  0  1  1  0  20x1+1+5  +0+0  1  'Display Grid?'  'No'  'Yes'  'request grid display?'  grid
.fi
.R
.sp
.IP
In this example, we have an optional logical selection; thus, the selection
will appear with the optional box in front of the title. 
Since the \fIoption selected\fP field is set to TRUE, 
the optional box will be initially highlighted, indicating that the 
default action will be to use the value of the logical. This value, according 
to the value of the \fIdefault\fP field, will be 1 (TRUE), interpreted in this
case as a response of "Yes" to the question, "Display Grid?"  
.sp 3
.NH 3 " Routine (-R) Line"
.XS
              \*(SN   Routine (-R)
.XE
.sp 2
.B
.nf
syntax:    -R   Act   Sel   Exec_Type   GS   'Title'   'Desc'   Routine
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0
if the logical selection described by the (-R) line is to be deactivated.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, always set to 0. 
.LP
.B
Exec_Type:
.R
.IP
The \fIexecute type\fP field is mainly used with programs that can be 
accessed via \fBcantata\fP;  this field indicates how cantata should treat
the execution of the routine.  Possible values for the \fIexecute type\fP
field include:
.sp
.in +0.2i
0 : Don't really execute the routine; simply demonstrate how it would be called
if it was executed
.br
1 : Check to see if this routine is already running; if it is, kill the 
existing process before starting the new one
.br
2 : Check to see if this routine is already running; if it is, don't run it
again.
.br
3 : Allow this routine to be run multiple times; begin a new execution without
checking if one is already running
.br
4 : Take output of this routine, and send it to the expression parser used
by cantata.  Output of routine must be of the form: [variable = number] or
[variable = expression].
.sp
For creation of programs which will not be integrated into \fBcantata\fP, or
for those who may not be sure which \fIexecution type\fP their routine should
have, a value of 1 is recommended.
.in -0.2i
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y. The geometry describes, in characters, 
the size of the logical selection and its position on the pane. 
The geometry should be large enough to accommodate all components of the logical
selection - the optional box, if the logical is optional, the title, and the
oval button which will display the current boolean value of the logical. Geometry strings may be set to float or integer values.
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks;  in the case of
the (-R) line, the title is usually "Execute", indicating to the user that
when they click on the Routine button, the routine in question will be executed.
.LP
.B
Desc:
.R
.IP
The \fIdescription\fP field is unused in the (-R) line.
.LP
.B
Routine:
.R
.IP
This is the routine that will be called when the user clicks on the Routine
button.  It is \fIalways\fP the name of the routine (program) to be executed.
.sp
.LP
.B
.ps 10
.nf
example:   -R  1  0  1  8x2+1+6  'Execute'  'run vconvert'  vconvert
.fi
.R
.sp
.IP
In this example, we are creating a routine button that will execute the 
\fBvconvert\fP routine when clicked on by the user.  The title of the routine
button will be "Execute", so as to match practically every other routine
button currently existing in the Khoros system.   We have set the \fIexec_type\fP
field to 1,  so that only one of these processes may be running at any 
particular time.
.sp 3
.NH 3 " Toggle (-T) Line"
.XS
              \*(SN   Toggle (-T)
.XE
.sp 2
.B
.nf
syntax:    -T   Act   Sel   Opt   OptSel   Live   GS   TOffset   Def   'Title'   'Desc'   Var
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0
if the entire toggle is to be deactivated.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, always set to 0. 
.LP
.B
Opt:
.R
.IP
The \fIoptional\fP field, 1 if use of the toggle is optional, 
0 if it is required.
.LP
.B
OptSel:
.R
.IP
The \fIoption selected\fP field; 1 if toggle is required, 1 if it is optional
and the default action is to use the default value of the toggle, 0 if use
of the toggle is optional and the default action is to ignore its value.
.LP
.B
Live:
.R
.IP
The \fIlive\fP field, 1 if control is to be returned immediately to the 
application when the user changes the value of the toggle, 0 otherwise.
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y. The geometry describes, in characters, 
the size of the toggle and its position on the pane. The geometry should be 
large enough to accommodate all items within the toggle group. Geometry strings may be set to float or integer values.
.LP
.B
TOffset
.R
.IP
The \fItitle offset\fP field, +x+y, specifies in characters the distance from
the upper left hand corner of the backplane of the toggle that the title
should appear. 
.LP
.B
Def:
.R
.IP
The \fIdefault\fP field specifies which of the selections in the toggle group
will provide the default value for the toggle.  This \fIdefault\fP field on
the (-T) line will be the NUMBER OF THE DESIRED SELECTION, where the number 
of the selection is determined by ORDER OF ITS APPEARANCE in the toggle group.  
For example, if the third selection in the toggle group is to provide the 
default value, the \fIdefault\fP field must be set to 3.  Note that selections 
are numbered beginning with 1.
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks;  it should be 
as short as possible, yet should still give a clear idea as to the purpose of
the toggle group.  If no title is desired, specify ' '.
.LP
.B
Desc:
.R
.IP
The \fIdescription\fP field should contain a short description of the toggle.
\fBghostwriter\fP will use this description as a comment when generating code
for the command line user interface. The description must be surrounded by
tic marks.  
.LP
.B
Var:
.R
.IP
The \fIvariable\fP name is used by \fBghostwriter\fP to determine the name
of the flag that will mark this logical argument to the program.  
The user may specify "-\fIvariable\fP {toggle value}" on the command line, 
as one of the arguments.  The \fIvariable\fP name is also used by the 
\fBconductor\fP code generation program to name the fields corresponding 
to this selection in the Form Information structure that it generates.  
Note that both \fBconductor\fP and \fBghostwriter\fP will generate code that
is consistent with the type of the toggle.  For example, if the items within
the toggle are of type string, both \fBghostwriter\fP and \fBconductor\fP
will generate a line similar to "char *\fIvariable;\fP" in which to return
the value of the toggle. For more details, see the documentation on 
\fBghostwriter\fP and \fBconductor\fP.  
.sp
.LP
.B
.ps 10
.nf
example:   -T  1  0  0  1  0  20x1+1+5  +0+0  4  'Plot Type'  'type of plot'  plot_type
.fi
.R
.sp
.IP
In this example, we are describing a toggle that will give us the desired
plot type.  From the (-T) line alone, one cannot tell if this will be an
integer, logical, float, or string toggle - this will be decided by the
type of selections that follow, although we can probably assume from the
title that it will be an integer toggle (if plot types are #defined) or
a string toggle (if we will be using the names of the plot types).  The
default is 4, indicating that the fourth selection to follow the (-T) line
will provide the default in its \fIdefault\fP field. 
.sp
.LP
.B
Special Notes on Toggles:
.R
.IP
Since toggles are somewhat more complicated, it is worthwhile to spend a
few moments detailing the finer points here:
.IP
Toggles may have Logical, String, Integer, Inputfile, OutputFile, or Float
selections as their members; however, all toggle selections inside the 
[-T to -E] toggle definition MUST be of the same type.
.IP
The toggle value that is returned to the application program is the same type 
as the items inside the toggle.  Thus, if a toggle has all float selections 
within it, the toggle value returned will be a float having the value
of the \fIdefault\fP field specified for the float selection the is currently 
selected.
.IP
The variable names on all selections within the toggle definition are ignored.
.IP
IT IS VERY IMPORTANT TO INITIALIZE YOUR TOGGLE PROPERLY! 
.br
\(bu
\fIOne and only one\fP selection within the toggle must have its \fIoption
selected\fP field = 1.  All others \fImust\fP have this field set to 0.  The
one selection that does have its \fIoption selected\fP field set to 1 will be
the default choice of the toggle;  the number of this selection MUST match the
\fIdefault\fP field on the (-T) line.  For example, if the (-T) line specifies
4 as its \fIdefault\fP, the 4th selection should be the only line in the
toggle definition with \fIoption selected\fP set to 1. 
.br
\(bu
Don't forget that it is the \fIdefault\fP fields of each selection within the
toggle definition that provide the possible values for the toggle.  Therefore,
the \fIdefault\fP fields on the selections that make up the toggle must be
set carefully!
.br
\(bu
For toggles of strings, the label of each string selection should be IDENTICAL 
to its default value.  This simplifies matters for the application programmer, 
as there is no confusion as to the value of the toggle at any time.
.br
\(bu
For toggles of logicals, the value returned will be the number (in order of
appearance) of the logical that is currently selected. This is because the
\fIdefault\fP fields of logicals (which can be either 0 or 1) do not offer 
enough choices to be very useful for providing values for a toggle with more
than 2 toggles. Therefore, in a toggle of logicals, if the 4th logical is 
selected, the toggle will take on a value of 4, and not a value of 0 or 1.
.br
\(bu
All selections within the toggle definition should have their \fIoptional\fP
fields set to TRUE (1).
.br
\(bu
All selections within the toggle have the \fIy\fP value of the \fIgeometry
string\fP RELATIVE to the geometry on the (-T) line.  This is in contrast
to every other case, where all \fIgeometry strings\fP use absolute values. Geometry strings may be set to float or integer values.
.sp
.LP
.B
example 1: 
.sp
.ps 10
.nf
-T  1  0  0  1  0  20x1+1+5  +0+0   4  'Plot Type'  'type of plot'  plot_type
   -l  1  0  1  0  0  10x1+0+1  +3+0  0  '2D'  '2D plot'  dummy
   -l  1  0  1  0  0  10x1+14+1 +3+0  0  'Discrete'  'discrete plot'  dummy
   -l  1  0  1  0  0  10x1+28+1 +3+0  0  'Histogram'  'histogram plot'  dummy
   -l  1  0  1  1  0  10x1+7+2  +3+0  0  'Polymarker'  'polymarker'  dummy
   -l  1  0  1  0  0  10x1+21+2 +3+0  0  'Linemarker'  'linemarker'  dummy
-E
.fi
.R
.IP
In example 1, we see one way in which the (-T) line might be used to create
a toggle to give the plot_type variable a value.  In this example, we have
chosen a required logical toggle.  The toggle itself (i.e, the integer 
"plot_type" variable) will take on values of 1, 2, 3, 4, or 5, 
depending on which of
the logicals is selected.  In this situation, it would be simplest if we
had #defines designating a 2D Plot as 1, a Discrete Plot as 2, and so on.
 The \fIdefaults\fP of the logicals do not matter - they are all set to 0.  
Likewise, the \fIvariable\fP fields on the logicals will not be used - we put 
in "dummy" to remind us of this fact.  We check to make sure that the default
of the toggle is set correctly - the \fIdefault\fP field on the (-T) line is
set to 4, and the fourth logical is the only one to have its \fIoption
selected\fP field set to 1, so everything is fine- our default will be 4.  
Finally, we check the
geometry, to make sure we have specified the \fIy\fP field relative to the
(-T) line;  the geometry of the logicals will specify 2 rows of toggle items,
the top row with three selections, and the bottom row with two selections.
.sp
.LP
.B
example 2: 
.sp
.ps 10
.nf
-T  1  0  1  1  0  20x1+1+5  +0+0   2  'Plot Type'  'type of plot'  plot_type
   -i  1  0  1  0  0  15x1+1+1  +0+0  0  0  21  '2D Plot'  '2d plot'  dummy
   -i  1  0  1  1  0  15x1+1+2  +0+0  0  0  23  'Discrete Plot'  'discrete plot'  dummy
   -i  1  0  1  0  0  15x1+1+3  +0+0  0  0  28  'Histogram Plot'  'histogram'  dummy
   -i  1  0  1  0  0  15x1+1+4  +0+0  0  0  27  'Polymarker'  'linemarker'  dummy
-E
.fi
.R
.IP
In example 2, we see another way in which the plot_type toggle may have been
specified.  This toggle is optional, and since the \fIoption selected\fP field
on the (-T) line is set to 1, the default action will be to use this toggle,
unless the user specifically indicates that they do not wish to use it.
Suppose that as in example 1, the different plot types had been
given #define'd values.  However, in this case, they do not begin at 1 and
increment consecutively; instead, the 2D Plot is #defined to 21, and plot
types do not increment neatly.  This situation calls for an integer toggle,
since the value of the plot_type toggle will take on the value of the 
\fIdefault\fP field of the chosen item, which can be set as desired to our
#define'd numbers.  This time, the \fIdefault\fP field of the (-T) line is 
set to 2, and accordingly, it is the second (-i) line that has its \fIoption
selected\fP field set to 1; the default of this toggle, therefore, will be
23.  The position given by the \fIy\fP value of the relative \fIgeometry 
strings\fP of the (-i) lines indicates that the items in the toggle will be 
aligned along the left hand side of the pane,
starting with the toggle title "Plot Type" at an area 5 characters down 
from the top of the pane.  Since bounds on the integers will not come 
into play, they are set to 0.
.sp
.LP
.B
example 3: 
.sp
.ps 10
.nf
-T  1  0  0  1  1  20x1+1+5  +0+0   1  'Plot Type'  'type of plot'  plot_type
   -s  1  0  1  1  0  25x1+2+1  +0+0  '2D Plot'  '2D Plot'  '2d plot'  dummy
   -s  1  0  1  0  0  25x1+30+1 +0+0  'Discrete'  'Discrete'  'discrete plot'  dummy
   -s  1  0  1  0  0  25x1+2+2  +0+0  'Histogram'  'Histogram'  'histogram plot'  dummy
   -s  1  0  1  0  0  25x1+30+6 +0+0  'Polymarker'  'Polymarker'  'polymarker plot' dummy
-E
.fi
.R
.IP
In example 3, we have a required toggle, that is "live" - that is, as soon
as the user changes the value of the toggle, control will be immediately 
returned to the application program, so that it can take some kind of action
in response to the change of plot type.  This is a toggle of strings: the
value returned in the "plot_type" variable will be a string, and it will have
as its value on the \fIdefault\fP field of one of the string selections -
"2D Plot", "Discrete", "Histogram", or "Polymarker".  To avoid confusion,
in each string selection, the \fItitle\fP is identical to the \fIdefault\fP.
The default of this string toggle is the \fIdefault\fP of the first string
selection, or "2D Plot".
.sp 3
.NH 3 " MutExcl (-C) Line"
.XS
              \*(SN   MutExcl (-C)
.XE
.sp 2
.B
.nf
syntax:    -C   Required 
.fi
.sp 2
Required:
.R
.IP
The \fIrequired\fP field, 0 if the mutually exclusive group \fIas a whole\fP
is optional, 1 if it is required.  In other words, a 1 in the  \fIrequired\fP
field says, "the user MUST provide EXACTLY ONE of these selections", whereas
a 0 in the \fIrequired\fP field says, "the user MAY provide ONE of these
selections".
.sp
.LP
.B
Special Notes on Mutually Exclusive Groups:
.R
.IP
While the mutually exclusive set is somewhat similar to a toggle, it is more
flexible.  While the toggle set is limited to a single type of selection, the
mutually exclusive group may contain a mixed group of Integer, String, 
InputFile, OutputFile, Float, or Logical selections.
.IP
Furthermore, the mutually exclusive set differs from the toggle in that 
selections within the set WILL retain the usual text widget in which the 
user may enter a desired value.  Thus, while a toggle is static, the 
mutually exclusive set is dynamic; it provides more freedom for the user,
but less control for the application program.
.IP
All selections in a mutually exclusive group MUST be specified as optional.
The user will only be able to "turn on" one of the mutually exclusive 
selections (by highlighting the optional box) at any one time; this is the
only one of the selections' values that is guaranteed to be valid 
at any one time.
.IP
IT IS VERY IMPORTANT TO INITIALIZE YOUR MUTUALLY EXCLUSIVE GROUP PROPERLY! 
.br
\(bu
ALL selections within the set MUST have their \fIoptional\fP field set to 1.
.br
\(bu
Like the toggle, ONE and ONLY ONE selection within the set must have its 
\fIoption selected\fP field set to 1.  This selection will be the default 
choice of the mutually exclusive group.  Unlike the toggle, there is no
\fIdefault\fP field on the (-C) line that must match the number of the 
selection.
.br
\(bu
ALL selections in the set must have a valid default value provided if the 
\fIrequired\fP field is FALSE (0).  As always, lower and upper bounds on 
integers and floats should be set carefully.
.sp
.LP
.B
example 1: 
.sp
.ps 10
.nf
-C  1
   -I  1  0  1  1  0  1  45x1+1+13 +0+0  './'  'Input Path'  'input path selection'  input_path
   -O 1  0  1  0  0  1  45x1+1+14 +0+0  './'  'Output Path'  'output path select'  output_path
   -s  1  0  1  0  0   45x1+1+15 +0+0  ' '  'String Sel'  'string selection'  string1
-E
.fi
.R
.IP
This mutually exclusive group is required; that is, the user MUST provide a
value for one and only one of the items.  The operation of a mutually exclusive
group in the command line user interface is slightly different from the 
operation of a mutually exclusive group in the graphical user interface. See
how the default values for the input_path and output_path parameters are both
set to "./".  When using this mutually exclusive group on the command line, 
these defaults are unused -- the user will be forced to specify a value
for one of the selections, and if they choose the input_path or output_path
parameters, will still have to explicitly enter a value, even if they want the
"./" directory specified.  However, for the graphical user interface, it 
is good to specify these defaults - the selections will come up in the order
listed, and the input_path and output_path selections' parameter boxes will
have "./" appearing inside them.  The optional box in front of the input_path
selection will be highlighted -- if the user wishes to specify the input_path
selection as their choice from the group (the default of the group) and they
also wish to have "./" as the value of the input_path selection (the default
of the input_path selection), they need not do anything.
.IP
Other things to notice about this example are that none of the items in the
group are "live" - in a mutually exclusive group, one should never have "live"
selections, as this interferes with the operation of the group as a whole.
Also, notice that as opposed to a toggle group, items in a mutually exclusive
group do not have relative positioning.  As in every other part of the UIS
(except toggle groups),  positioning indicated by the geometry strings is 
absolute.  In addition, see how the positioning of the items keeps them in
a physical as well as operational group.  Items in a mutually exclusive group
should never be separated from one another by another (isolated) item, as
this makes a graphical user interface confusing to the user.
.sp
.LP
.B
example 2: 
.sp
.ps 10
.nf
-C  0
   -I  1  0  1  1  0  1  45x1+1+13 +0+0  './'  'Input Path'  'input path selection'  input_path
   -O 1  0  1  0  0  1  45x1+1+14 +0+0  './'  'Output Path'  'output path select'  output_path
   -s  1  0  1  0  0   45x1+1+15 +0+0  ' '  'String Sel'  'string selection'  string1
-E
.fi
.R
.IP
Example 2 is identical to example 1, except for one key thing - the (-C) line
in example 2 specifies an optional mutually exclusive group, not a required
one as in example 1.   Thus, this mutually exclusive group will be optional;
the user \fImay\fP use one and only one of the items, but they will not have
to use any of them.
.IP
Again, operation of the group differs from the command line user interface
to the graphical user interface.  In fact, the \fIrequired\fP field on the (-C)
line is used only with the command line user interface.  In the graphical
user interface, there is no difference between the operation of a required 
mutually exclusive group and an optional mutually exclusive group.  In either
situation, one and only one of the selections will provide a value to the 
application program,  and in either situation, the selection that provides
the value will be determined by which selection has its optional box 
highlighted.  
.IP
With the command line user interface, however, the \fIrequired\fP field 
on the (-C) line does make a difference.  Whereas in example 1, the user would
be forced to enter a value for one of the items, in example 2, the user may
or may not enter a value for one of the items, as desired.
.sp 3
.NH 3 " Blank (-b) Line"
.XS
              \*(SN   Blank (-b)
.XE
.sp 2
.B
.nf
syntax:    -b   +x+y   'Title'
.fi
.sp 2
+x+y:
.R
.IP
This is the absolute position, in character widths, of the text specified in
the \fItitle\fP field from the upper left hand corner of the pane in which
it appears.
.LP
.B
Title:
.R
.IP
The \fITitle\fP is the text that is desired on the blank selection.
Remember that the Blank selection is most often used for adding text to
the graphical user interface - any text can be added to any pane in the
graphical user interface by using Blank selections.  
If no title is desired, there is no need for the use of the (-b) line.
.sp
.LP
.B
.ps 10
.nf
example:   -b  +5+6  'This is a test of the blank selection'
.fi
.R
.sp
.IP
In this example, the text specified, "this is a test of the blank selection" 
will appear on the fifth line down and 6 character widths over from the 
upper left hand corner of the pane in which it appears.
.sp 3
.NH 3 " PaneAction (-a) Line"
.XS
              \*(SN   PaneAction (-a)
.XE
.sp 2
.B
.nf
syntax:    -a   Act   Sel   GS   'Title'   'Desc'   Var
.fi
.sp 2
Act:
.R
.IP
The \fIactivation\fP field, set to 1 (TRUE) or 0 (FALSE).  Only set to 0 
if the action button described by this (-n) line is to be deactivated.
.LP
.B
Sel:
.R
.IP
The \fIselected\fP field, always set to 0.
.LP
.B
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y, in characters, describes the size of the 
action button and its position on the pane in characters. Note that the 
width field must be large enough to accommodate the title, or the title will 
be truncated. Geometry strings may be set to float or integer values.
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks; will appear 
as the title on the action button.
.LP
.B
Desc:
.R
.IP
The \fIdescription\fP field should contain a short description of the purpose
of the action button.
.LP
.B
Var:
.R
.IP
The \fIvariable\fP name is used by the \fBconductor\fP code generation 
program to name the elements corresponding to this action button in the 
Form Information structure that it generates.  For more details, see the 
documentation on \fBconductor\fP.
.sp
.LP
.B
.ps 10
.nf
example:   -a  1  0  15x2+12+15  'Do It'  'do something'  do_it
.fi
.R
.sp
.IP
In the example, we have a pane action button, 15 characters wide by 2 
characters tall, located 12 characters to the right and 15 characters down 
from the upper left hand corner of the master, labeled "Do It", indicating
that when the user clicks on this button, the application will "do it", 
whatever "it" may be.
.sp 3
.NH 3 " Workspace (-w) Line"
.XS
              \*(SN   Workspace (-w)
.XE
.sp 2
.B
.nf
syntax:    -w   GS   TOffset   'Title'   'Desc'   Var
.fi
.sp 2
GS:
.R
.IP
The \fIgeometry\fP field, wxh+x+y, in characters, describes the size of the 
workspace widget and its position on the master, guide pane, or pane in 
\fIpixels\fP (note that it is the only line in the UIS to have a geometry 
string in terms of pixels, and not characters). The geometry string for a
(-w) line must have integer values.
.LP
.B
Title:
.R
.IP
The \fItitle\fP string, it must be delineated by tic marks; will appear 
as the title on the workspace widget.  Note that this title may be specified
as ' ' if no title is desired.
.LP
.B
Var:
.R
.IP
The \fIvariable\fP name is used by the \fBconductor\fP code generation 
program to name the elements corresponding to this workspace widget in the 
Form Information structure that it generates.  For more details, see the 
documentation on \fBconductor\fP.
.sp
.LP
.B
.ps 10
.nf
example:   -w  1  0  500x500+2+5  +10+1  'Workspace'  workspace
.fi
.R
.sp
.IP
In the example, we have a workspace widget that is 500 square pixels in size. 
It can be used for anything desired by the application programmer.  It is 
located 2 characters down and 5 characters across from the upper left hand
corner of the master, guide pane, or pane, depending on whether the line appears
in the [-S to -E] master definition, [-G to -E] guide pane definition, or in 
the [-P to -E] pane definition.  It is labeled with the title, "Workspace", 
10 characters to the right and one character down from the upper left hand
corner of the widget itself.
.sp 3
.NH 3 " IncludeSubform (-k) Line"
.XS
              \*(SN   IncludeSubform (-k)
.XE
.sp 2
.B
.nf
syntax:    -k   Filename
.fi
.sp 2
Filename:
.R
.IP
The full path and filename of the file that contains the subform [-M to -E]
definition to be included at the place where the (-k) line occurs. 
Note that use of the tilde (~) and the KHOROS_HOME environment variable are
both accepted.
.sp
.LP
.B
.ps 10
.nf
example:   -k  KHOROS_HOME/repos/cantata/subforms/classify/classify.sub
.fi
.R
.sp
.IP
In this example, we substitute the single (-k) line for the entire 
[-M to -E] subform definition that otherwise would have appeared in the UIS
at this point.  In the file found in 
KHOROS_HOME/repos/cantata/subforms/classify/classify.sub, the entire subform
definition must appear.
.sp 3
.NH 3 " IncludePane (-p) Line"
.XS
              \*(SN   IncludePane (-p)
.XE
.sp 2
.B
.nf
syntax:    -p   Filename
.fi
.sp 2
Filename:
.R
.IP
The full path and filename of the file that contains the pane [-P to -E]
definition to be included at the place where the (-p) line occurs.
Note that use of the tilde (~) and the KHOROS_HOME environment variable are
both accepted.
.sp
.LP
.B
.ps 10
.nf
example:   -p  KHOROS_HOME/repos/cantata/subforms/classify/vkmeans.pane
.fi
.R
.sp
.IP
In this example, we substitute the single (-p) line for the entire [-P to -E] 
pane definition that otherwise would have appeared in the UIS at this point. 
In the file found in KHOROS_HOME/repos/cantata/subforms/classify/vkmeans.pane, 
the entire pane definition must appear.
.sp 3
.NH 3 " End (-E) Line"
.XS
              \*(SN   End (-E)
.XE
.sp 2
.B
.nf
syntax:    -E
.fi
.sp 2
.R
.IP
The End (-E) line has no fields following it.  
