.ds f. uis1.sec
.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, and 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 
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 
The Pane 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 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
A routine button is like an action button, except that when the user clicks
on this button, the specified program is immediately executed.  This specialized
button was developed specifically for \fBcantata\fP, and probably will not be
used by other applications.  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 
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 currently 28 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
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 GUI Items on a Master Form
.PP
The legal GUI 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 to enter a value for that parameter.  All keyboard I/O 
is done through a Pane.
.sp
.LP
2)  Legal Buttons  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) Pane Action Button
.br
	h) Toggle  Groups
.br
	h) Mutually Exclusive Groups
.br
	i) Routine
.br
	j) Blank
.br
	k) Help Buttons
.br
	l) Quit Button
.br
	m) 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 routine button allows the 
user to call a particular routine (program) directly, as in a system call.  
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.  
.PP
Finally, the key item on a pane 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 good user interface 
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 UIS files that will be 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.
.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
.PP



