.sp 3
.NH 1 "GRAPHICAL USER INTERFACE (GUI) ITEMS"
.XS
\s12\*(SN  GRAPHICAL USER INTERFACE (GUI) ITEMS\s0
.XE
.PP
The Graphical User Interface (GUI) is made up of different types of 
\fIitems\fP.  Each item is defined by a line in the UIS
File. Some items are required to appear in every user interface; others are 
recommended for most user interfaces; others will only occur when the 
application program has a special need.  Most items are specific to a 
certain part of the user interface -- for instance, certain items are 
allowed only on the master form, others are allowed only in a subform, 
and finally, there are some that are only allowed on a pane.  A special 
group of items are referred to as \fIselections\fP - these include the 
InputFile, OutputFile, Integer, Float, String, Logical.  Selections 
are allowed only on a pane.  Many of the items are only used 
with the graphical user interface, although a subset is also used by the 
command line user interface; this subset will be discussed in the next
section.  The following is a listing of all the items currently provided 
for the graphical user interface.  
.sp 2
.NH 2 "ITEMS MAKING UP THE STRUCTURE OF THE GUI"
.XS
      \*(SN  ITEMS MAKING UP THE STRUCTURE OF THE GUI
.XE
.sp 2
.LP
.B
The Form
.R
.IP
The GUI of a Khoros program, as a whole, 
is often referred to as a \fI"form"\fP, or as \fI"the forms"\fP.  This applies
regardless of how many subforms the user interface has, whether or not it
uses a master form, etc.  The UIS line that applies best here is the (-F) 
StartForm line, as it begins the entire user interface specification.
.LP
.B
The SubForm
.R
.IP
Every GUI has at least one subform.  For simple user
interfaces, a single subform is all that is necessary.  The subform provides
a backplane for one or more panes;  it is on the panes that most of the I/O
is actually done.  If the subform has more than one pane, it will also have
a guide pane with which to change the pane that is currently displayed.
The UIS line that corresponds to a SubForm is the (-M) StartSubForm line, as
it begins the subform definition.
.LP
.B
The Pane
.R
.IP
Every GUI has at least one pane.  For extremely simple
user interfaces, a single pane on a single subform is all that is necessary.
The pane provides a backplane for selections and action buttons, with which
the user will provide input to the application program. The UIS line that
corresponds to a Pane is the (-P) StartPane line, as it begins the pane
definition.
.LP
.B
The Guide Pane
.R
.IP
For a subform that needs more than one pane, a guide pane is necessary.  The
guide pane is a panel containing guide buttons that allow the user to 
control which pane is currently displayed;  while the currently displayed 
pane will change, the guide pane remains static.  A guide pane may also 
include action buttons, usually those which would otherwise be repeated on 
each of the panes in the subform. The UIS line that corresponds to a Guide 
Pane is the (-G) StartGuide line, as it begins the definition of the guide
pane.
.LP
.B
The Master Form
.R
.IP
For the most complex user interfaces, in which more than one subform is 
needed, a master form is necessary.  A master form contains subform buttons 
which allow the user to control which subform is currently displayed; while
the currently displayed subforms may change, the master form remains static.
A master form may also include action buttons, usually those which would 
otherwise be repeated on each of the subforms in the user interface.
The UIS line that corresponds to a Master Form is the (-S) StartMaster line, 
as it begins the definition of the master form.
.LP
.B
The Toggle
.R
.IP
In many cases, a toggle is desirable on a pane.  A toggle allows the user
to pick one of a predefined number of choices, where the choices may be of any
type of selection, as long as all the choices are of the same type.  For 
instance, one might have a toggle of integers, a toggle of floats, or a 
toggle of strings.  The UIS line that corresponds to a Toggle is the (-T) 
Toggle line, as it begins the definition of the toggle.
.LP
.B
The Mutually Exclusive Group
.R
.IP
In many other cases, a mutually exclusive group is desirable.  The mutually
exclusive group is made up of two or more selections, which need not have
predefined values, and may be of different types.  The user will be able to
provide and use a value for one and only one of the selections in the group.
The UIS line that corresponds to a Mutually Exclusive group is the (-C)
MutExcl line, as it begins the definition of such a group.
.sp 2
.NH 2 "GENERAL PURPOSE ITEMS"
.XS
      \*(SN  GENERAL PURPOSE ITEMS 
.XE
.sp 2
.LP 
.B
The Quit Button
.R
.IP
Every GUI needs a quit button;  this allows the program to exit.
In addition, when a user interface has a master form with several subforms,
quit buttons on the subforms allow the user to unmap them, and thus reduce
clutter on the screen.  The UIS line that specifies a quit button is the 
(-Q) Quit line.
.LP 
.B
The Help Button
.R
.IP
The help button is a standard device on the GUI;  all programs in the Khoros
system are required to provide on-line help which can be accessed 
directly via the user interface.  The Help line of the UIS provides access
to a help file involving no additional work by the application
program.  All that is needed is the correct path to the help file.  The UIS 
line that specifies a help button is the (-H) Help line.
.LP
.B
The Workspace Widget
.R
.IP
The workspace widget provides a general-purpose Form Widget as part of the 
GUI.  However, once the workspace widget is displayed, the GUI
does not manage or further interfere with the it - the workspace widget is 
provided specifically so that the application program may have convenient
access to a widget that may be used for whatever purpose is appropriate.  
The UIS line for a workspace widget is the (-w) line.
.sp 2
.NH 2 "ITEMS APPEARING ONLY ON THE MASTER FORM" 
.XS 
      \*(SN  ITEMS APPEARING ONLY ON THE MASTER FORM
.XE
.sp 2
.LP
.B
The Subform Button
.R
.IP
The user may click on a subform button in order to map the subform with
which it is associated.  Mapping of the subform is done automatically.
The UIS line for a subform button is the (-d) line.
.LP
.B
The Master Action Button
.R
.IP
All action buttons allow the user to indicate that they want something
done right away - control is returned immediately to the application program,
so that the application may take appropriate action.  A master action button
differs from other action buttons in that it may appear only on a master form.
The UIS line for a Master Action button is the (-n) line.
.LP
.B
The Psuedo Subform Button
.R
.IP
A psuedo subform button is half-way between a subform button and an action
button;  it's purpose is to map a subform, but the application must do the
work - subforms are not mapped automatically.  It was developed for use
by \fBcantata\fP and will probably not be used by any other application.
The UIS line for a psuedo subform button is the (-u) line.
.sp 2
.NH 2 "ITEMS APPEARING ONLY ON THE GUIDE PANE" 
.XS 
      \*(SN  ITEMS APPEARING ONLY ON THE GUIDE PANE
.XE
.sp 2
.LP
.B
The Guide Button
.R
.IP 
A guide button allows the user to change which pane is currently displayed
on the subform; it always appears on the guide pane of a subform.  
Mapping of panes is done automatically.  The UIS line for a guide button 
is the (-g) line.
.LP
.B
The Subform Action Button
.R
.IP
All action buttons allow the user to indicate that they want something
done right away - control is returned immediately to the application program,
so that the application may take appropriate action.  A subform action button
differs from other action buttons in that it may appear only on the guide
pane of a subform.  The UIS line for a Subform Action button is the (-m) line.
.sp 2
.NH 2 "ITEMS APPEARING ONLY ON A PANE"
.XS
      \*(SN  ITEMS APPEARING ONLY ON A PANE
.XE
.sp 2
.LP
.B
Input File Selection
.R
.IP
The input file selection allows the user to specify an input file.
The UIS line for an input file selection is the (-I) line.
.LP
.B
Output File Selection
.R
.IP
The output file selection allows the user to specify an output file.
The UIS line for an output file selection is the (-O) line.
.LP
.B
Integer Selection
.R
.IP
The integer selection allows the user to specify an integer.
The UIS line for an integer selection is the (-i) line.
.LP
.B 
Float Selection
.R
.IP
The float selection allows the user to specify a float.
The UIS line for a float selection is the (-f) line.
.LP
.B 
Logical Selection
.R
.IP
The logical selection allows the user to specify a boolean value.
The UIS line for a logical selection is the (-l) line.
.LP
.B 
Cycle Selection
.R
.IP
The cycle selection is similar to the logical selection, except that it
allows the user to specify one of a set of integer values ranging from 0 to N, 
where each of the integer values from 0 to N is represented by a string.
The UIS line for a cycle selection is the (-c) line.
.LP
.B 
String Selection
.R
.IP
The string selection allows the user to specify a character string.
The UIS line for a string selection is the (-s) line.
.LP
.B 
AnswerOutputFile Selection
.R
.IP
The AnswerOutputFile selection allows one to create a GUI answer file according
to the current values of all other selections on the pane.  Later, this GUI 
answer file can be read back in via the AnswerInputputFile selection, in order 
to set all selections on the pane to their earlier values in one step.  
The UIS line for an AnswerOutputFile selection is the (-Z) line; it should 
always be paired with an AnswerInputFile selection.  For more information on
GUI answer files, see the section entitled "USING GUI ANSWER FILES".
.LP
.B
AnswerInputFile Selection
.R
.IP
The AnswerInputFile selection reads in a GUI answer file created earlier by
using an AnswerOutputFile selection;  all selections on the pane will be 
automatically updated according to the values in the GUI answer file.  The
UIS line for an AnswerInputFile selection is the (-A) line.   For more 
information on GUI answer files, see the section entitled "USING GUI ANSWER 
FILES".
.LP
.B 
The Pane Action Button
.R
.IP
The Pane Action Button is used in the GUI of xvroutines;
action buttons allow the user to indicate that they want something
done right away - control is returned immediately to the application program,
so that the application may take appropriate action.  A pane action button
differs from other action buttons in that it may appear only on a pane.
The UIS line for a Pane Action button is the (-a) line.
.LP
.B 
The Routine Button
.R
.IP
The Routine Button is used on the GUI of all Khoros programs, so that
they may be integrated into \fBcantata\fP;
A routine button is like an action button, except that when the user clicks
on this button, the specified program is immediately executed, with the 
arguments specified by the values of all other selections on the pane.  
The UIS line for a routine button is the (-R) line.
.LP
.B
The Blank selection
.R
.IP
A "blank" selection (somewhat of a misnomer) allows text to be inserted into a 
pane.  The UIS line for a blank selection is the (-b) line.
.sp 3
.NH 1 "COMMAND LINE USER INTERFACE (CLUI) ITEMS"
.XS
\s12\*(SN  COMMAND LINE USER INTERFACE (CLUI) ITEMS\s0
.XE
.sp
.PP
The CLUI consists of \fIarguments\fP to 
the program.  You should understand that the same UIS lines that specify 
\fIselections\fP for the GUI also specify \fIarguments\fP 
for the CLUI .  The CLUI only utilizes a small subset of the lines in the 
UIS that are used by the GUI. 
.sp
.LP
.B
Input File Argument
.R
.IP
The input file argument allows the user to specify an input file.
The UIS line for an input file selection is the (-I) line.
.LP
.B
Output File Argument
.R
.IP
The output file argument allows the user to specify an output file.
The UIS line for an output file selection is the (-O) line.
.LP
.B
Integer Argument
.R
.IP
The integer argument allows the user to specify an integer.
The UIS line for an integer selection is the (-i) line.
.LP
.B 
Float Argument
.R
.IP
The float argument allows the user to specify a float.
The UIS line for a float selection is the (-f) line.
.LP
.B 
Logical Argument
.R
.IP
The logical argument allows the user to specify a boolean value.
The UIS line for a logical selection is the (-l) line.
.LP
.B
Cycle Argument
.R
.IP
The cycle selection is similar to the logical selection, except that it
allows the user to specify one of a set of integer values ranging from 0 to N, 
where each of the integer values from 0 to N is represents a string.
.LP
.B 
String Argument
.R
.IP
The string argument allows the user to specify a character string.
The UIS line for a string selection is the (-s) line.
.LP
.B
Toggle Argument
.R
.IP
A toggle is often useful on the command line.  A toggle 
allows the user to specify one of a predefined number of choices, where 
the choices may be of any type of argument (listed above), as long as all 
the choices are of the same type.  For instance, one might have a toggle of 
integers, a toggle of floats, or a toggle of strings.  The UIS line that 
corresponds 
to a Toggle is the (-T) Toggle line, as it begins the definition of the toggle.
The (-T) line must be matched by a (-E) line, marking the end of the toggle
group.
.LP
.B
Mutually Exclusive Arguments
.R
.IP
Mutually exclusive group can also be useful on the command line.  The mutually
exclusive group is made up of two or more arguments, which need not have
predefined values, and may be of different types.  The user will be able to
provide and use a value for one and only one of the selections in the group.
The UIS line that corresponds to a Mutually Exclusive group is the (-C)
MutExcl line, as it begins the definition of such a group.
The (-C) line must be matched by a (-E) line, marking the end of the mutually
exclusive group.
.sp 3
.NH 1 "UIS LINE TYPES"
.XS
\s12\*(SN  UIS LINE TYPES\s0
.XE
.sp
.PP
The UIS is made up of different types of \fIlines\fP; each line is used for 
a very specific purpose, and each line 
has its own very strictly defined syntax which \fImust\fP be followed in 
every instance of use.  There are many different types of lines in 
the UIS.  Some lines are required to appear in every UIS; other lines are 
very common, and appear in most UIS's;  some lines are for use on very rare 
occasions, and will only appear in quite specialized UIS files. 
Positioning of lines in the UIS is quite important.  Some types of 
lines may only appear in certain places, and will cause a syntax error if they
appear anywhere else;  other types of lines, by positioning, dictate where
on the user interface the associated item will appear.  
.PP
This section introduces each type of line in the UIS, and gives a brief 
description of where and how it is used.  Note: as of Khoros 1.0, 
the current UIS version is 4.2.  Most of the lines in the UIS are used only 
by the GUI - those lines that are also used by the 
CLUI will be marked with a "*".  Note that lines 
that are not used by the CLUI \fImay still occur\fP 
in a command line user interface - they will simply be ignored by 
\fBghostwriter\fP.  This is how a single UIS may be used to generate 
both a command line and a graphical user interface for the same program.
.sp 2
.NH 2 "LINES FOR STRUCTURING THE GUI"
.XS
      \*(SN  LINES FOR STRUCTURING THE GUI
.XE
.sp 2
.LP
.B
StartForm *
.R
.IP
\fIEvery\fP UIS file \fImust\fP begin with this line. There may be \fIone and 
only one\fP occurance of this line in every UIS file.  It \fImust\fP be matched
with an End (-E) line, which ends the user interface specification.  
Collectively, the [-F to -E] form description will make up the entire UIS. 
.sp
.LP
.B
StartMaster 
.R
.IP
The StartMaster (-S) line begins the definition of a \fImaster 
form\fP. Any GUI that uses a master form \fIwill\fP 
have \fIone and only one\fP occurance of this line in its UIS file.  The (-S)
line \fImust\fP be matched with an End (-E) line, and as a set, the [-S to -E] 
lines will make up the definition of the master form. If the GUI 
does not require a master form, this line will not occur.  The [-S to -E] master 
form description may include a Quit button (-Q), a Help button (-H), and as 
many MasterAction (-n) buttons as desired. The master form description must
also include at least two SubformButtons (-d) with which the user will be 
able to map subforms.
.sp
.LP
.B
StartSubMenu
.R
.IP
The StartSubMenu (-D) line specifies an action button on the master form, which
will bring up a set of pull-down menus when clicked on by the user.  The (-D)
line also marks the beginning of a group of (-d) SubFormButton lines.  
The (-D) line \fImust\fP be matched by an End (-E) line, to end the group 
of (-d) subform buttons which will make up the pull-down menu.  The (-d) lines
that appear within the the [-D to -E] submenu description, rather than appearing
as separate buttons on the master, will appear as elements of the pull-down
menu instead.  Like isolated subform buttons, they will still cause the subform
that they are associated with to map as soon as they are selected out of the
pull-down menu.  Note that within the [-D to -E] submenu description, the 
ONLY legal items are (-d) subform buttons.   
.sp
.LP
.B
StartSubForm *
.R
.IP
The StartSubForm (-M) line begins the definition of a \fIsubform\fP.
Every UIS file \fImust\fP have \fIat least one\fP StartSubForm line.  GUI's
that utilize a \fImaster form\fP, (implying that more than one
subform will be utilized) will have one (-M) line for each subform. It 
\fImust\fP be matched by an End (-E) line, to end the subform definition.
If the GUI uses a master form, there MUST be one [-M to
-E] subform definition \fIfor each\fP (-d) subform button.  Subform buttons
(-d lines) are matched to subforms ( [-M to -E] sets ) in order of occurrance;
i.e, the first (-d) line will create a subform button, which, when clicked on,
will bring up the subform described by the first [-M to -E] subform definition,
and so on.
.sp
.LP
.B
StartGuide
.R
.IP
The StartGuide (-G) line starts the definition of a \fIguide pane\fP. Any
GUI that uses a guide pane \fIwill\fP have \fIone and only
one\fP occurrance of this line in its UIS file.  It \fImust\fP be matched with
an End (-E) line to end the definition of the guide pane.  If a graphical user 
interface does not require a guide pane, this line will not appear.  
.sp
.LP
.B
StartPane *
.R
.IP
The StartPane (-P) line begins the definition of an \fII/O Pane\fP (more often
known simply as a \fIpane\fP). Every UIS file \fImust\fP have \fIat least 
one\fP StartPane line. GUI's that utilize a 
\fIguide pane\fP (implying that more than one pane will be used) will have 
one (-P) line for each pane. It \fImust\fP be matched by an End (-E) line, 
to end the pane definition.
.sp
.LP
.B
Toggles *
.R
.IP
The Toggle (-T) line begins a definition of a toggle group.  A toggle is a 
set of one or more items (see the Integer, Float, String, Logical, InputFile, or
OutputFile selections) of the same type.  Selections within the toggle are 
created without the usual parameter box in which the user may type a value, as
the definition of a toggle implies that the user may not provide a value other
than those that are defined as part of the toggle.  Depending on which choice 
is selected by the user, the value of the toggle group will take on the 
default value of the selected item. The (-T) line  \fImust\fP be 
matched with an End (-E) line to end the definition of the toggle.  
Toggle lines may also be "live", indicating that the current value of the 
toggle is to be registered immediately when the user changes the value of 
the toggle.
.sp
.LP
.B
MutualExclusion *
.R
.IP
The MutualExclusion (-C) line starts the definition of a mutually exclusive 
group.  Members of the group may be of different types - any or all of the 
Integer, Float, String, Logical, InputFile and OutputFile selections may be 
part of
a mutually exclusive group. All selections within the mutually exclusive 
group are created exactly as they would be if each item was isolated.  
The user may provide an appropriate value in the parameter box of one of the
selections, and if the user also chooses that selection to represent the 
mutually exclusive group, the value of the entire group takes on the value
of the chosen selection.  The (-C) line \fImust\fP be matched with an End 
(-E) line to end the definition of the toggle.  
.sp
.LP
.B
End *
.R
.IP
The End (-E) line is the only UIS line with no fields. End lines are used 
to end all sets of definitions in a UIS file.  Thus, the [-F to -E] 
sequence is the entire UIS; the [-S to -E] sequence defines a master form; the
[-M to -E] sequence specifies a subform; the [-G to -E] set defines a guide
pane, and the [-P to -E] set defines a pane, and so on. It is imperative that 
the (-E) line be used properly, and that it appears in every place necessary 
to end a definition.  Extra (-E) lines will cause a premature EOF of the UIS 
file;  a lack of (-E) lines will cause a stream of UIS syntax errors.  
.sp 2
.NH 2 "LINES DESCRIBING GENERAL PURPOSE ITEMS"
.XS
      \*(SN  LINES DESCRIBING GENERAL PURPOSE ITEMS 
.XE
.sp 2
.LP
.B
QuitForm
.R
.IP
The QuitForm (-Q) line dictates a \fIQuit\fP button.  The (-Q) line may appear
in the master form definition, the guide pane definition, or the pane 
definition.  Depending on the position of the Quit button, it has different 
purposes.  For instance, a Quit button on master form would cause the run of
the application program to end, while a Quit button on a subordinate subform 
of that master form would cause the subform to unmap.  When Quit buttons are
used for the latter purpose, they are usually labeled "Close".
.sp
.LP
.B
Help
.R
.IP
The Help (-H) line requests a specialized button on the user interface which
will immediately bring up an on-line help file when desired. A (-H) line
may appear in the master form definition, the guide pane definition, or the pane
definition. 
.sp
.LP
.B
Workspace
.R
.IP
The Workspace (-w) line may specify a generic form widget for the application
to use for whatever purpose may be applicable.  The workspace widget may appear
the master form definition, the guide pane definition, or the pane definition.
It has absolutely no functionality on its own - the application is provided with
the address of the requested widget, and is then responsible for the use and
maintenance of this widget.
.sp 2
.NH 2 "LINES APPEARING ONLY IN THE MASTER FORM DEFINITION"
.XS
      \*(SN  LINES APPEARING ONLY IN THE MASTER FORM DEFINITION
.XE
.sp 2
.LP
.B
SubFormButton
.R
.IP
The SubFormButton (-d) line specifies a \fIsubform button\fP on a master form.
When the user clicks on a subform button, it brings up the subform that it is
associated with.  The (-d) line appears only within the master form definition,
and when it appears, it will be associated with a [-M to -E] subform definition.
.sp
.LP
.B
PsuedoSubForm
.R
.IP
The PsuedoSubform (-u) line is similar to a subform button, but allows the
application program to bring up the subform, rather than allowing the 
\fIxvforms\fP library do it automatically.  It was designed specifically for
use by \fBcantata\fP, and will most likely never be used for any other program.
.sp
.LP
.B
MasterAction
.R
.IP
The MasterAction (-n) line specifies an \fIaction button\fP which will appear
on a master form.  It may appear \fIonly\fP in the [-S to -E] master form 
definition.  
.sp
.LP
.B
IncludeSubform *
.R
.IP
The IncludeSubform (-k) line works similar to the way that #include statement 
does in C code.  When a UIS has large subform definitions, it may be more 
readable to have one or more of the subform definitions in separate files. Thus,
the (-k) line will take the place of an entire [-M to -E] subform definition
in the UIS.  
.sp
.LP
.B
IncludePane *
.R
.IP
The IncludePane (-p) line works exactly like the IncludeSubForm (-k) line, above,
except that it takes the place of a pane [-P to -E] definition in the UIS.
.sp 2
.NH 2 "LINES APPEARING ONLY IN THE GUIDE PANE DEFINITION"
.XS
      \*(SN  LINES APPEARING ONLY IN THE GUIDE PANE DEFINITION
.XE
.sp 2
.LP
.B
GuideButton
.R
.IP
The GuideButton (-g) line specifies a \fIguide button\fP on a guide pane.
When the user clicks on a guide button, it brings up the pane that it is
associated with.  The (-g) line appears only within the guide pane definition,
and when it appears, it will be associated with a [-P to -E] pane definition.
The GuideButton may only appear within a GuidePane [-G to -E] definition.
.sp
.LP
.B
SubFormAction
.R
.IP
The SubFormAction (-m) line specifies an \fIaction button\fP which will appear
on the guide pane of a subform.  It may appear \fIonly\fP in the [-G to -E] 
guide pane definition.  
.sp 2
.NH 2 "LINES APPEARING ONLY IN THE PANE DEFINITION"
.XS
      \*(SN  LINES APPEARING ONLY IN THE PANE DEFINITION
.XE
.sp 2
.LP
.B
InputFile *
.R
.IP
The Inputfile (-I) line specifies an \fIinput file selection\fP.  InputFile
selections may be part of a toggle, or members of a mutually exclusive group.
They may be optional or required; they may also be "live", so that the value 
of the input file is registered immediately when the user hits <cr>.
.sp
.LP
.B
OutputFile *
.R
.IP
The Outputfile (-O) line specifies an \fIoutput file selection\fP.  OutputFile
selections may be part of a toggle, or members of a mutually exclusive group.
They may be optional or required; they may also be "live", so that the value
of the output file is registered immediately when the user hits <cr>.
.sp
.LP
.B
Integer *
.R
.IP
The Integer (-i) line specifies an \fIinteger selection\fP.  Integer
selections may be part of a toggle, or members of a mutually exclusive group.
They may be optional or required; they may also be "live", so that the value
of the integer is registered immediately when the user hits <cr>.  When
the geometry specified for an integer selection is large enough, a scroll bar
will appear, allowing the user to scroll through valid integer values.  Integer
selections may be bounded or unbounded.
.sp
.LP
.B
Float *
.R
.IP
The Float (-f) line specifies a \fIfloat selection\fP.  Float
selections may be part of a toggle, or members of a mutually exclusive group.
They may be optional or required; they may also be "live", so that the value
of the float is registered immediately when the user hits <cr>.  When
the geometry specified for a float selection is large enough, a scroll bar
will appear, allowing the user to scroll through valid float values.  Float
selections may be bounded or unbounded.
.sp
.LP
.B
String *
.R
.IP
The String (-s) line specifies a \fIstring selection\fP.  String
selections may be part of a toggle, or members of a mutually exclusive group.
They may be optional or required; they may also be "live", so that the value
of the string is registered immediately when the user hits <cr>.
.sp
.LP
.B
Logical *
.R
.IP
The Logical (-l) line specifies a \fIlogical selection\fP.  Logical
selections may be part of a toggle, or members of a mutually exclusive group.
They may be optional or required.  Logical lines may also be "live", so that 
the value of the logical is registered immediately when the user changes 
the value of the logical.
.sp
.LP
.B
Cycle *
.R
.IP
The Cycle (-c) line specifies a \fIcycle selection\fP. Cycle lines may also 
be "live", so that the value of the cycle is registered immediately when the 
user changes the value of the cycle.
.sp
.LP
.B
AnswerOutputFile
.R
.IP
The AnswerOutputFile (-Z) line specifies a \fIGUI answer output file 
selection\fP.  AnswerOutputFile lines are always live, so that the selections
on the pane are automatically updated immediately when the user enters the
name of a valid GUI answer file for that pane and hits <cr>.
.sp
.LP
.B
AnswerInputFile
.R
.IP
The AnswerInputFile (-A) line specifies a \fIGUI answer input file 
selection\fP.  AnswerInputFile lines are always live, so that the values of
selections on the pane are written out immediately when the user enters the
name of for the answer file for that pane and hits <cr>.
.sp
.LP
.B
PaneAction
.R
.IP
The PaneAction (-a) line specifies an \fIaction button\fP which will appear
a pane of a subform.  
.sp
.LP
.B
Routine
.R
.IP
The Routine (-R) line specifies a specialized action button which will appear
a pane of a subform.  This Routine button will call some program automatically
as soon as the user clicks on it.  The program executed by be a system call,
or another program in the Khoros System.  
.sp
.LP
.B
LibCall
.R
.IP
The LibCall (-L) line is the counterpart of the Routine line, only it has no
physical aspect within the user interface - that is, it is invisible to the 
user.  While the Routine line specifies a program to be executed when the
Routine button is clicked on, the LibCall routine will specify a library call
that may be substituted for the program specified in the (-R) line when
appropriate.  Thus, a (-L) line will always appear with a (-R) line, and
never by itself.  WARNING: the LibCall line was designed specifically for 
use by \fBcantata\fP, and may never be utilized by any other application.  
Functionality of the LibCall (-L) line has not been implemented as of Khoros 1.0.
.sp
.LP
.B
Blank
.R
.IP
The Blank (-b) line specifies a non-operational label widget within a pane. 
The name "Blank" is a misnomer, as the (-b) line is primarily used for adding
comments, extra titles, etc. into the pane.  Any reasonably sized piece of 
text desired may be displayed on a pane through use of the (-b) line. 
.sp 3
.NH 1 "NOTES ON DESIGNING THE GUI" 
.XS
\s12\*(SN  NOTES ON DESIGNING THE GUI\s0
.XE
.PP
The following is a collection of notes on designing a GUI.
Those who are writing a \fIvroutine\fP rather than an \fIxvroutine\fP may
skip directly to the section labeled "Panes".
.sp 2
.NH 2 "THE MASTER FORM"
.XS
      \*(SN  THE MASTER FORM 
.XE
.sp 2
.LP
1)  Characteristic Items on the Master Form
.PP
The characteristic buttons on the Master form are the \fIsubform buttons\fP.  
These buttons, when clicked on by the user, will automatically bring up the 
specified \fIsubforms\fP. The use of a Master form enables you
to divide up the input coming from the user into major activities, 
so that one subform may deal exclusively with one aspect of the application 
program, while a different subform may deal exclusively with another.  
.PP
This design of the forms also encourages modular programming - for instance,
it makes sense to have a "master driver" for the master form, and a separate 
subdriver for each subform.  If multiple panes appear on a subform, it is best
to have a specific driver for each pane on the subform.  (Indeed, this is how
the skeleton driver will be generated when the \fBconductor\fP code generation
program is used with the [-b] option -- for more information, see the 
documentation on \fBconductor\fP). Thus, the forms can not only organize 
the flow of the user's actions, but also the flow of the xvroutine
itself.
.sp
.LP
2)  Omission of the Master Form
.PP
The [-S to -E] description indicates that a separate master 
form is desired.  If the [-S to -E] master form description is omitted, the 
(-F) StartForm database line can be followed immediately by a \fIsingle\fP 
[-M to -E] subform definition.  Thus, this constitutes the description of 
a single subform. A key to deciding whether or not to use a Master Form is 
whether or not you need more than one SubForm.  If only one Subform is needed, 
a Master Form is most likely unnecessary.
.sp
.LP
3)  Mutual Exclusion of Subforms
.PP
If a master form is to be used, the (-S) line indicates whether or not 
the subforms are to be mutually exclusive.  If the third field on the 
(-S) line is TRUE (1), this indicates that there \fIis\fP to be 
mutual exclusion.  When the forms are displayed using
\fBpreview\fP, you will notice that only one subform may be brought up at a
time.  Alternately, the mutual exclusion field on the (-S) line may be set to
FALSE (0).  When subforms are not mutually exclusive, all the subforms may be 
brought up at the same time, if desired.
.sp
.LP
4)  Geometry
.PP
Geometry is a key factor in determining how the \fIforms\fP are presented to the
user. All geometry strings are specified in terms of \fIcharacter\fP width and
\fIcharacter\fP height, not in device coordinates.  As of Khoros 1.0, these 
are floating point arguments, so that you may specify a geometry that has, for
example, a two and a half character offset. Note that the master form 
will always be created just large enough to encompass all the buttons in it, 
regardless of the geometry on the (-F) line.  Thus, buttons with a geometry 
string indicating (x,y) positions far away from the other buttons on the
master form will cause the master to become very large, while several buttons 
with the same geometry will cause the master to be very small, with only the 
last button appearing (each button with the same geometry string will cover 
the one beneath it).  This also applies to the Guide Pane on a Subform, and to 
each Pane on a Subform.
.sp
.LP
5)  Legal Items on a Master Form
.PP
The legal items on a master form include:
.br
	a) Subform Buttons
.br
	b) MasterAction Buttons
.br
	c) Help Buttons
.br
	d) Quit Button
.br
	e) Workspaces
.PP
Subform buttons will each bring
up a different subform, and re-direct user attention to the pane(s) on that 
subform.  Master action buttons will return control to the xvroutine,
so that the xvroutine may take the desired action.  Every master form must
have a Help button, that should provide an introduction to and overview of 
the entire application program.  A Workspace is optional on the master form:
it provides a general-use Form Widget of the specified geometry in which you
may display graphics or images, or which you may use as a backplane for 
creating other widgets.  Of course, there should always be a "Quit" button on
the master so that the user may exit the program.
.sp 2
.NH 2 "THE SUBFORM"
.XS
      \*(SN  THE SUBFORM 
.XE
.sp 2
.PP
The \fIsubform\fP is generally divided into two parts:  the \fIguide pane\fP,
and the \fIpanes\fP themselves.  The guide pane is a section of the subform
that, according to the geometry string specified on the (-G) StartGuide 
line, may encompass the far left side of the 
subform, the far right side of the subform, the top or the bottom of the 
subform.   Buttons on the guide pane allow the user to page through the 
panes that appear on the remainder of the subform area.  It is on the
panes that the user may actually type in integer, float, or string values,
set toggles or logicals, etc.
.sp 2
.NH 2 "THE GUIDE PANE"
.XS
      \*(SN  THE GUIDE PANE 
.XE
.sp 2
.LP
1)  Characteristic Items on the Guide Pane
.PP
The characteristic buttons on the guide pane are the guide buttons.  These 
buttons, when clicked on by the user, will automatically bring up the specified 
panes. The use of a guide pane enables the application programmer to divide up 
the input coming from the user into divisions. For example, one pane on a 
subform might deal exclusively with input, while the other pane on the subform
could deal exclusively  with output.
.sp
.LP
2) Omission of the Guide Pane
.PP
The [-G to -E] description indicates that a guide pane is 
desired.  If the [-G to -E] guide pane description is omitted, the (-M)
StartSubform line may be followed with a \fIsingle\fP [-P to -E] pane 
definition; this constitutes the definition of a subform made up of
a single pane.  A key to deciding whether or not to use a Guide Pane is 
whether or not you need more than one Pane.  If only one Pane is needed, 
a Guide Pane is most likely unnecessary.
.sp
3)  Legal Items on a Guide Pane
.PP
The legal items on a Guide Pane include:
.br
	a) Guide Buttons
.br
	b) SubformAction Buttons
.br
	c) Help Buttons
.br
	d) Quit Button
.br
	e) Workspaces
.PP
Guide buttons will each bring up a different pane on the subform, 
and re-direct user attention to that 
particular pane. Subform action buttons will return control to the xvroutine,
so that the xvroutine may take the desired action.  A Help button 
on a guide pane should always provide an introduction to and overview of the 
intent and features provided on that subform. A Workspace is optional on the 
guide pane: it provides a general-use Form Widget of the specified geometry 
in which you may display graphics or images, or which you may use as a 
backplane for creating other widgets.  And, of course, there should 
always be a "Quit" button on the guide pane so that the user may exit the 
program (if a master form is not present), or unmap that subform (if a master
form is used).  Note that in the latter case, it is often more appropriate
to label the Quit button "Close", as the word "Quit" is sometimes misleading
when the actual operation performed is simply an unmapping of the subform.
.sp 2
.NH 2 "PANES"
.XS
      \*(SN  PANES 
.XE
.sp 2
.LS
1)  Characteristic Items on a Pane
.PP
The characteristic items on a pane are \fIselections\fP.  Most, such as Integer 
and Float Selections, have parameter boxes in which the user may type in a 
value.  Most also may be created as optional or required.  If optional, the
parameter box and label of the selection  will be preceded by a little box 
which the user can click ON (filled box) or OFF (unfilled box) to indicate 
whether they would like the value for that parameter used by the program.  
All keyboard I/O is done through a Pane.
.sp
.LP
2)  Legal Items on a Pane include:
.br
	a) Input File Selection
.br
	b) Output File Selection
.br
	c) Integer Selection
.br
	d) Float Selection
.br
	e) String Selection
.br
	f) Logical Selection
.br
	g) Cycle Selection
.br
	h) Answer Infile Selection
.br
	i) Answer Outfile Selection
.br
	j) Pane Action Button
.br
	k) Toggle  Groups
.br
	l) Mutually Exclusive Groups
.br
	m) Routine
.br
	n) Blank
.br
	o) Help Buttons
.br
	p) Quit Button
.br
	q) Workspaces
.PP
Input and output file selections allow the user to enter an input or output
file, respectively.  Integer, float, string, and logical selections allow
the user to set an int, float, string, or boolean value.  A toggle allows the
user to make a choice between a finite number of pre-determined choices, while
a mutually exclusive group allows the user to provide a value for one of a
group of selections and use only that value.  
A blank line may be used for adding comments, labels, etc to the form.  
Help buttons on a pane should give very specific help as to how to use that 
particular pane.  A quit button should never be used on a pane unless there 
is no guide pane on that subform on which to put a quit button.  
The key item on a pane of a program that is to be integrated into \fIcantata\fP
is the routine button, which allows the user to execute the program from 
cantata. The user might enter integers, floats, and strings,
set toggles and logicals, etc, all day long if desired, but the program will
not be executed until the routine button is clicked on.  
.PP
On the other hand, the key item on a pane of the GUI of an xvroutine is the 
pane action button.  The correct use of
the pane action button is crucial when using the \fIxvforms\fP user interface,
since it is the user's click on a pane action button that returns control to
the application program.  The user might enter integers, floats, and strings,
set toggles and logicals, etc, all day long if desired, but control \fIwill 
not be returned to the application until the user clicks on a pane action 
button\fP (there is an exception to this that will be discussed shortly).   
For this reason, it is always best if you
decide beforehand what operations will be available on a particular pane, and
for each operation, which values will need to be set.  A GUI for an xvroutine
will include a set of necessary selections in which the user may 
enter appropriate values, followed by a pane action button labeled with the 
name of the operation to be performed using those values. When the user
clicks on the pane action button, \fIxvforms\fP will return control to the 
application, so that it may gather up the pertinent values
from the user interface, and take the desired action accordingly.
.PP
The exception to the rule detailed above is when selections are made \fIlive\fP.
An inputfile, outputfile, integer, float, string, logical, or toggle selection
may be made \fIlive\fP by setting the appropriate field on the UIS line that
describes it.  When a selection is live, control will return to the application
program whenever the user hits <cr> within the parameter box of that selection.
Thus, if the only piece of information is needed before the application program
can take some particular action, a live selection may fit the bill better than
an non-live selection followed by a pane action button.  If more than one
piece of information is needed, however, the pane action button is still the
method of choice for returning control to the application program.
.PP
A Workspace may also be specified on a pane if desired.  As when it appears
on a Master form or a Guide Pane, the workspace provides a general-use 
Form Widget of the specified geometry in which you may display graphics 
or images, or which you may use as a backplane for creating other widgets.
.sp 2
.NH 2 "SETTING THE CORRECT DEFAULT APPEARANCE OF A SUBFORM"
.XS
      \*(SN  SETTING THE CORRECT DEFAULT APPEARANCE OF A SUBFORM
.XE
.sp
.PP
Suppose that in our UIS, we have a subform with a guide
pane containing several guide buttons, the first of which is labeled, "Input".
We would like this subform to come up with the "Input" guide button selected, 
and the corresponding "Input" pane mapped.  This is done by setting the 
"selected" field to 1 (TRUE) on the (-g) guidebutton line that defines the 
"Input" guide button \fIas well as\fP setting the "selected" field to 1 (TRUE) 
on the (-P) StartPane line that begins the definition of the Input pane.
Since we want the "Input" pane to come up mapped, it is important to set 
\fIboth\fP of these fields to 1, \fIand\fP to make sure that \fIall\fP other 
"selected" fields on other (-g) guide button lines and (-P) StartPane lines for
that subform are set to 0 (FALSE).  Incorrect setting of these fields will cause
unexpected behavior of forms.  
.PP
Suppose that it would also be acceptable to have our hypothetical "Input" 
subform to come up without any guide button selected, and with no pane mapped.
To do this, we would set \fIall\fP "selected" fields on the (-g) and (-P) lines 
within that subform definition to be 0 (FALSE).
.PP
Note that in our example, we said that the (-g) guide button which will bring 
up the "Input" pane is the first guide button to occur in the subform 
definition [-M to -E].  Since guide buttons are matched to their Panes by 
\fIorder of appearance\fP, it is necessary that the "Input" pane definition 
be the first [-P to -E] set to appear.  Note that if, for example, we reversed 
the placement of the "Input" guide button with that of an "Output" guide
button, but did not reverse the placement of their respective [-P to -E]
pane definitions, the "Output" guide button would then bring up the "Input" 
pane and vice versa!
.sp 2
.NH 2 "SPECIAL REQUIREMENTS FOR *.PANE FILES"
.XS
      \*(SN  SPECIAL REQUIREMENTS FOR *.PANE FILES
.XE
.sp
.PP
Some special considerations need to be taken into account for *.pane files,
since they are used to integrate programs into \fBcantata\fP.  
Note that ALL Khoros programs have a *.pane file that is used to integrate 
the program into cantata, so it is very important to follow these guidelines
when creating your *.pane file.
.PP
First of all, if you are using \fBpreview\fP to prototype your *.pane file,
and  you are using the (-u) PsuedoSubForm line, it will not be displayed by
\fBpreview\fP.  This is because \fBcantata\fP maps all psuedosubform buttons
when it is executed -- the definition of a psuedosubform button dictates that
it NOT be mapped by the \fIxvforms\fP library.  While you are prototyping
the GUI using \fIpreview\fP, simply substitute the (-d)
line here,  which is identical in all ways, except that it \fIwill\fP be
displayed by \fBpreview\fP.  When integrating the pane into the \fBcantata\fP
subform of choice, simply replace (-d) with (-u) so that \fBcantata\fP will
work properly with your UIS file.
.PP
Also, it is necessary for *.pane files that will be used to integrate their
associated programs integrated into \fBcantata\fP
to have geometry definitions that are consistent with the rest of the
\fIcantata\fP graphical user interface.
Following is a copy of \fBvadd.pane\fP, the UIS file for the Addition
routine (on the Binary Arithmetic Operations subform).  It may be used as an
example of how the *.pane file for a routine to be integrated into
\fBcantata\fP should appear.  
.PP
Notice that all *.pane files must contain the \fBcantata\fP (-F) Master Form 
line (shown below) for completeness.  The (-M) Subform line should match
the subform that the pane will be included on; in this case, the "Arith Binary"
subform.  The geometry for the (-P) Pane line must match the other panes on 
that subform, in order for it to be integrated correctly.
.PP
ALL *.pane files that will be used to integrate their
associated programs integrated into \fBcantata\fP must have a Routine button.
This Routine button is what allows the user to execute the program from
the visual language;  if no Routine button is present, the user will not have
access to the program.
.sp
.ps 9
.vs 10
\f(CW
-F 4.2 1 0 170x7+10+20 +35+1 'CANTATA Visual Programming Environment for the KHOROS System' cantata
.br
-M 1 0 100x40+10+20 +23+1 'Binary Arithmetic Operations ' binary
.br
  -P 1 0 80x38+22+2 +12+0 'Add Two Images Pixel by Pixel' vadd
.br
    -I 1 0 0 1 0 1 50x1+2+2 +0+0 ' ' 'Input Image #1' 'first input image' i1
.br
    -I 1 0 0 1 0 1 50x1+2+3 +0+0 ' ' 'Input Image #2' 'second input image' i2
.br
    -O 1 0 0 1 0 1 50x1+2+5 +0+0 ' ' 'Output Image  ' 'resulting output image' o
.br
    -I 1 0 1 0 0 1 50x1+2+8 +0+0 ' ' 'Masking Image' 'add operation masking image' m
.br
    -R 1 0 1 13x2+1+13 'Execute' 'execute operation' vadd
.br
    -H 1  13x2+39+13 'Help' 'man page for vadd' KHOROS_HOME/doc/manpages/vadd.1
.br
  -E
.br
-E
.br
-E
\fP
.sp 3
.nr PS 11
.nr VS 13
.sp 2
.NH 2 "USING GUI ANSWER FILES"
.XS
      \*(SN  USING GUI ANSWER FILES
.XE
.sp
.PP
Note that the Graphical User Interface Answer File, also called the GUI answer 
file, differs slightly in content from the Command Line User Interface Answer 
file, or the CLUI answer file. An answer file used by the CLUI has entries 
for program arguments, followed by associated values.  An answer file used by 
the GUI of a program will also has entries for program arguments, followed by 
associated values.  However, the GUI answer file must have additional entries 
for each optional selection, specifying whether or not that selection was 
selected for use when
the GUI answer file was written out.  For example, a CLUI answer file for
a program with an optional float argument called "mass" might have the entry:
\f(CWmass = 1.354\fP.  The GUI answer file for the same program might also have:
\f(CWmass = 1.354\fP;  however, it would also specify \f(CWmass_opt = 1\fP, 
indicating that at the time when the GUI answer file was written out, the 
\fImass\fP float selection had its optional box highlighted, indicating that
the user wanted to use the mass parameter with its value of 1.354.  For this
reason, GUI answer files and CLUI answer files can generally not be used 
interchangably.  A CLUI answer file will not have sufficient information to 
properly set a GUI pane with optional selections;  a GUI answer file for a pane
with optional selections will have additional entries (with the postfix "_opt") 
that will be considered invalid input if the program in question calls the 
\fIcheck_args()\fP routine.  
.PP
Let us take an example.  Suppose that we have a program called "vblend", which
has a UIS as follows:
.sp
.ps 9
.vs 10
\f(CW
-F 4.2 1 0 170x7+10+20 +35+1 'CANTATA Visual Programming Environment for the KHOROS System' cantata
.br
-M 1 1 100x40+10+20 +23+1 'Binary Arithmetic Operations ' binary
.br
-P 1 1 80x38+22+2 +0+0 'Blend two images by adding X*(image 1)+(1-X)*image2' vblend
.br
-A 1 0 52x1+2+1 +0+0 ' ' 'Input Answer File' 
.br
-Z 1 0 52x1+2+2 +0+0 ' ' 'Output Answer File' 
.br
-I 1 0 0 1 0 1 50x1+2+4 +0+0 ' ' 'Input Image #1' 'input image 1' i1
.br
-I 1 0 0 1 0 1 50x1+2+5 +0+0 ' ' 'Input Image #2' 'input image 2' i2
.br
-O 1 0 0 1 0 1 50x1+2+7 +0+0 ' ' 'Output Image  ' 'resulting output image' o
.br
-b +7+9 'Select one of the following blend ratio sources'
.br
-C 0
.br
-I 1 0 1 0 0 1 50x1+2+11 +0+0 ' ' 'Blend Mask Image' 'blend mask image' m
.br
-i 1 0 1 0 0 50x1+2+12 +0+0 0 10 0 'integer ratio   ' 'integer ratio' y
.br
-f 1 0 1 1 1 50x1+2+13 +0+0 0 1 0 'Blending ratio  ' 'Blending ratio' x
.br
-E
.br
-R 1 0 1 13x2+1+15 'Execute' 'execute operation' vblend
.br
-H 1   13x2+39+15 'Help' 'man page for vblend' KHOROS_HOME/doc/manpages/vblend.1
.br
-Q 1 0 10x2+19+15 'LOOP'
.br
-E
.br
-E
.br
-E
\fP
.nr PS 11
.nr VS 13
.sp 2
.PP
A GUI answer file for the \fBvblend\fP program might look like:
.sp
.ps 9
.vs 10
\f(CW
-i1 /research/devel/khaos/data/images/feath.xv
.br
-i2 /research/devel/khaos/data/images/moon.xv
.br
-o junk2.xv
.br
-y 8
.br
-y_opt 1
.br
-x 0.683333
.br
-x_opt 0
\fP
.nr PS 11
.nr VS 13
.sp 2
.PP
Using the GUI answer file above as input to AnswerInputFile parameter of the
vblend pane would set the "Input Image #1", "Input Image #2", and "Output Image"
parameters to "feath.xv", "moon.xv", and "junk2.xv", respectively.  In addition,
it would select the "integer ratio" item from the mutually exclusive group,
and set the integer ration to a value of 8. It would also set the "Blending 
Ratio" float value to 0.683333, in spite of the fact that the "Blending Ratio"
is no longer the selected item out of the mutually exclusive group.
Assuming the user now clicked on the "EXECUTE" button, the vblend program would 
be executed with these parameters.  If the same results were desired from the 
command line, the corresponding CLUI answer file for the vblend program would 
look like:
.sp
.ps 9
.vs 10
\f(CW
-i1 /research/devel/khaos/data/images/feath.xv
.br
-i2 /research/devel/khaos/data/images/moon.xv
.br
-o junk2.xv
.br
-y 8
\fP
.nr PS 11
.nr VS 13
.sp 2
.PP
Using the [-a] option to specify the CLUI answer file when executing
the vblend program from the command line produces the same results as 
using the "EXECUTE" button on the graphical user interface to run the
vblend program after inputting the GUI answer file to set selections on the
vblend pane.  
.PP
Notice that if the CLUI answer file above was used
as an answer file for the graphical user interface of vblend, the selections 
on the pane would be set in such a way as to only be partially correct. The
"Input Image #1", "Input Image #2", and "Output Image" selections would be
filled out correctly.  However, the remaining \f(CW-y 8\fP entry in the CLUI 
answer file simply does not provide enough information to set the vblend pane 
as we intended.  While the "integer ratio" value will be set to 8, the 
selected item of the mutually exclusive group will remain set to the 
"Blending ratio", and will not be changed to the "integer ration", as was our
intention.  
.PP
If the opposite case was true, and the GUI answer file was used as an answer
file for the command line user interface of vblend, the vblend program would
exit immediately.  This is because the vblend program calls the 
\fIcheck_args()\fP routine, causing it to exit when undefined command line
arguments are encountered.  As far as the command line user interface of 
vblend is concerned, the arguments \f(CW-x_opt 0\fP and \f(CW-y_opt 1\fP are
invalid.
.PP
Note that if the UIS for a program has no optionals, no toggles,
and no mutually exclusive groups, the CLUI answer file and the GUI answer file 
will be interchangable.
.PP
The use of GUI answer files are not currently prevalent in the Khoros system;
however, they are provided for the convenience of those people who might find
them useful when developing programs under the Khoros system.  They are highly
recommended when the pane associated with a vroutine is very long and
complex, making it inconvenient for the user to remember and set the values of
parameters when using the program often via cantata.
