.ds f. uis2.sec
.sp 3
.NH 1 "UIS LINE FIELD TYPES & SYNTAX"
.XS
\s12\*(SN  UIS LINE FIELD TYPES & SYNTAX\s0
.XE
.sp 2
.NH 2 "UIS LINE--FIELD TYPES"
.XS
      \*(SN  UIS LINE--FIELD TYPES
.XE
.sp
.PP
Each line in the UIS is made of \fIfields\fP.  Each field of each line in 
the UIS must be specified properly in order for the UIS to be correctly 
interpreted, for use as either a specification of a command line user 
interface or as a graphical user interface.  Many of these fields occur
in most of the different types of lines in the UIS. This section discusses 
in detail the meanings of the fields that occur in more than one type of
line in the User Interface Specification.  Those fields that are specific
to a single type of line in the UIS will be discussed later, in the Explanation
of Syntax for that type of line.  
.sp
.LP
.B
Activate
.R
.IP
The \fIactivate\fP field appears on almost every line of the
UIS; it is applicable only to the \fIxvforms\fP graphical user interface. 
The allowed values for the \fIactivate\fP field are TRUE (1) and FALSE (0).
It indicates whether a selection is active (\fIactivate\fP = TRUE) or 
inactive (\fIactivate\fP = FALSE).
If an item is inactive, it will still be displayed on the forms; however, it 
will often appear undersized, it may appear fuzzy, and will not accept any 
interaction.  This field allows various parts of the forms to be disabled.  
For example, discriminating use of the \fIactive\fP field allows application
programs to be used by persons other than the developer while the 
software itself is still under development; the items corresponding to the 
unfinished software may be deactivated until segments of the controlling
software are debugged, when the appropriate selections may be activated for 
use.  Note that panes may be disabled by setting the \fIactive\fP field to 1 
on the UIS line describing the controlling guide button, and that entire 
subforms may be disabled by setting the \fIactive\fP field to 1  on the UIS 
line describing the controlling subform button.
.sp
.LP
.B
Selected 
.R
.IP
The \fIselected\fP field is mostly for internal bookkeeping by the \fIxvforms\fP
library; it tells if an item has recently had its value changed by the user.
It is applicable only to the \fIxvforms\fP graphical user interface.
The allowed values for the \fIselected\fP field are TRUE (1) and FALSE (0).
As far as creation of a UIS is concerned, this field should always be 0 for
all lines \fIwith the following exceptions:\fP
.br
\(bu The StartForm (-F) line should always have the \fIselected\fP field = 1.
.br
\(bu If a master form is used, the MasterForm (-S) line should have its 
\fIselected\fP field = 1.  
.br
\(bu If a form contains only one subform (ie, there is no master definition,
and the (-F) StartForm line is followed immediately by the [-M to -E] subform
definition), the StartPane (-M) line should have its \fIselected\fP field = 1.
.br
\(bu If a guide pane is used, the StartGuide (-G) line should have its 
\fIselected\fP field = 1.  
.br
\(bu If a guide pane is used on a subform, \fIone and only one\fP of the 
SubFormButton (-g) lines in the guide pane [-G to -E] definition may have
its \fIselected\fP field = 1.  The StartPane (-P) line of the pane to
which it corresponds must also be = 1.  In this way, the designer of the user
interface may specify  which pane, if any, will be automatically mapped when
the subform is initially mapped.  Note that it is not necessary for any pane
on the subform to be mapped initially;  it is perfectly legal to leave the 
\fIselected\fP fields on all (-g) lines and all (-P) line as 0.
.br
\(bu If a subform contains only one pane (ie, there is no guide pane definition,
and the (-M) StartSubform line is followed immediately by the [-P to -E] pane
definition, the StartPane (-P) line should have its \fIselected\fP field = 1.
.sp
.LP
.B
Optional
.R
.IP
The \fIOptional\fP field indicates whether a selection is optional 
(\fIoptional\fP = 1) or required (\fIoptional\fP = 0).  It is used by both the
command line user interface, and the \fIxvforms\fP graphical user interface.
.IP
In the CLUI, an argument described in the UIS by a
selection with its \fIoptional\fP field set to 1 is considered optional on the
command line.  The application will be informed if the user provided the 
appropriate \fIflag\fP corresponding to the selection, and will be expected 
to act accordingly.  If the argument described in the UIS has its 
\fIoptional\fP field set to 0, it will be interpreted as required on the 
command line;  when the user fails to specify the argument on the command 
line, an error message will be displayed.  If the user is running the program 
in interactive mode, they will be repeatedly prompted for a value for the 
required argument until they provide a valid response;  if they are not 
running the program in interactive mode, the program will exit immediately 
after printing the error message.
.IP
In the GUI, a selection that is optional will have a 
small box to the left of the title of the selection.  If the box is highlighted
in the background color, it indicates that this item is currently selected for 
use by the user; if the box is not highlighted, it indicates that the user 
does not wish to utilize the parameter represented by this selection.  The 
optional selection can be used in one of two ways:
.sp
.in +0.5i 
1) When the selection in question is of type InputFile, OutputFile, Integer,
Float, String, or Logical, \fIand the selection is given a default value\fP, 
the user may choose between providing NEW information (by entering a new 
value into the parameter box of the selection and highlighting the box)  
OR using the DEFAULT value of the selection (by unhighlighting the box).
.sp
2) When the selection has no default value, the user may choose between 
USING the selection (by providing information and highlighting the box)  
or NOT USING the information (unhighlighting the box).
.in -0.5i
.sp
.IP 
Which of the above two methods is used is completely determined by the
application programmer, and how the information returned from
the forms is utilized.  NOTE that when using mutually exclusive or toggle 
groups, ALL selections within the [-C to -E] or [-T to -E] group MUST have
the \fIoptional\fP field = 1.
.sp
.LP
.B
Option_Selected
.R
.IP
If a selection is NOT OPTIONAL, this field MUST be TRUE (\fIoption selected\fP
 = 1).  However, when a selection is optional, this field tells whether or not
the optional box (described above) is highlighted or not to begin with.  For
instance, when a selection is optional (\fIoptional\fP = 1), the designer of
the forms must decide whether the default action will be to use the selection
or not to use the selection.  If the default action will be to use the value 
of the selection, (whether or not the current value was provided by the default
specified) the \fIoption selected\fP field should be set to 1.  
If the default action will be to ignore the value of the selection, the 
\fIoption selected\fP field should be set to 0.
.IP
NOTE that the \fIoption selected\fP field on a Toggle (-T) line has a special
function.  When a Toggle [-T to -E] set is used, \fIone and only one\fP
of the selections within the toggle should have the \fIoption selected\fP 
field set to 1.  Which selection has this field set determines the default 
selection of the toggle. Furthermore, note that \fIthe selection in the toggle
group that has its \fPoption selected\fI field set to one MUST be consistent 
with the value of the \fPdefault\fI field on the (-T) line!\fP For instance,
if the \fIdefault\fP field on the (-T) line is set to 3, the \fIthird\fP 
selection in the [-T to -E] toggle group MUST be the one selection having its
\fIoption selected\fP field set to 1.  WARNING:  having NO selections within 
the toggle group with the \fIoption selected\fP field set to 1,  having MORE 
THAN ONE selection within the toggle group with the \fIoption selected\fP 
field set to 1, or having the \fIdefault\fP field of the (-T) line inconsistent
with the number of the selection in the toggle that has its \fIoption 
selected\fP field set to one is asking for trouble!  None of these three errors
can be detected by the syntax checking of the \fIxvforms\fP library, and any
of the three situations will have a severely disruptive effect on the 
performance of the toggle.
.IP
NOTE that similarly to a Toggle, when a Mutually Exclusive [-C to -E] set is
used, ONE and ONLY ONE of the selections within the set should have the 
\fIoptional selected\fP field set to 1. Which one has this field set will 
determine the default selection of the mutually exclusive group. 
Having NO selections within the set with the \fIoption selected\fP field = 1,
or having MORE THAN ONE selection within the group with the \fIoption 
selected\fP set to 1 will have a disruptive effect on the performance of the 
mutual exclusive group.
.sp
.LP
.B
Live
.R
.IP
This is a special field used only with selections by the \fIxvforms\fP 
GUI.  When a selection is "live" (\fIlive\fP = 1), 
the \fIxvforms\fP library will immediately return control to the application
program when the user initiates a change of value in the selection.  This
can be done in the following ways:
.sp
.in +0.5i
1) When the user hits <CR> in the parameter box of a "live" InputFile (-I), 
OutputFile (-O), Float (-f), Integer (-i) or String (-S) selection
.sp
2) When the user moves a scroll bar associated with a "live" Integer (-i) 
or Float (-f) selection
.sp
3) when the user changes the value of a "live" Toggle (-T)
.sp
.in -0.5i
.IP
Making a selection "live" means that software control will be passed
back to the xvroutine when any of the above conditions are
met.  Thus, the application program may immediately take appropriate
action according to the value of the selection.  An example is found in the 
user interface of the \fBxprism2\fP plotting package, on the "Labels" pane 
of the "Options" subform.  Here, the String (-s) selections for the plot title 
and axis labels are all "live".  Thus, when the user types in a string in the 
parameter box for the Plot Title and hits <CR>, control returns to the xprism2 
driver, which notes that there is a request to change the plot title, and 
immediately does so.  Note that in this example, there is only one piece of 
information necessary to change the plot title - a new string.  This makes the
plot title string selection an ideal selection to be "live".  If more
than one piece of information is needed before action can be initiated, 
however, individual selections should NOT be "live".
.sp
.LP
.B
Geometry String
.R
.IP
The geometry string appears as a field in practically every line in the UIS.
Needless to say, it is ignored by the CLUI.  The geometry string gives the 
overall geometry of an item in CHARACTERS of the font size currently being 
used, in the following form, where the xoffset and yoffset are offsets 
from the upper left hand corner of the parent widget.  
.sp
.ce
[width x height + xoffset + yoffset]
.sp
.IP
The \fIgeometry\fP string of the StartForm (-F) line determines the size
of the master form (if there is a master form [-S to -E] definition).
At this time, the x and y offsets on this line are not used.
In the future, they may used to position the form when it is mapped
for the first time, when it is not mapped manually by the user.
If there is no master form, the geometry string of the StartSubform
(-M) line will over-ride the geometry of the StartForm (-F) line, which
 must appear anyway, and must be non-zero.
.IP
The geometry string of the StartSubform (-M) line specifies the size
of the subform in question.  However, if the guide pane and/or panes
contained within the subform exceed the geometry size of the (-M) line,
the size of the subform will expand accordingly. Similarly, if the
guide pane and/or panes in the subform do not require the amount of
space specified in the geometry string, the subform will shrink to
the smallest size in which the guide pane and pane components will fit.
If a master form is used, the x and y offsets of the StartSubform (-M)
line are not used.  If no master form is used, the X and Y offsets of
the StartSubform line dictate the distance of the subform from the upper
left hand corner of the backplane.
.IP
Similarly, the geometry string of the StartGuide (-G) line specifies
the size of the guide pane in question, and the geometry string of the
StartPane (-P) line specifies the size of the pane in question.
In either case, if the items within either the guide pane or the pane
do not exactly match the corresponding geometry string, the guide pane
or pane will expand or shrink accordingly.
.IP
On selections, the geometry must allow enough room for an optional box
(if the selection is optional), the title, and a parameter box for
text input.  If the selection is of type float (-f) or integer (-i),
and a scroll bar is desired, at least 2 character widths should be
provided for the scroll bar.  Note that the size of the scroll bar
determines its accuracy.  If a scroll bar is not desired on a float
or int selection, the width specified in the geometry string should
be reduced until the scroll bar no longer appears.
.sp
.LP
.B
Title Offset
.R
.IP
The \fItitle offset\fP string appears as a field in many lines in the UIS that
have a geometry string.  Like the \fIgeometry\fP field, it is always ignored
by the command line user interface. It must be of the form:
.sp
.ce
[+ x_position + y_position]
.sp
This field gives the x and y positioning of the LABEL of the item, which will
appear \fIx\fP characters to the right and \fIy\fP characters down from the 
upper left hand corner of the backplane of the item.  \fIWARNING: title offsets
may NEVER include negative numbers!\fP
.sp
.LP
.B
Default
.R
.IP
This field gives the \fIdefault\fP value of the selection, whatever that 
selection may be.  It will always be of the same type as the selection.  For
instance, it the selection is specified by a Float (-f) line,  the \fIdefault\fP
field on that line MUST be a floating point number.  Integer selections must
have integer defaults, and so on.  The \fIdefault\fP field is very important
to both the command line user interface and the graphical user interface. In
the command line user interface,  optional arguments that are not specified
by the user on the command line will take on the default value specified by
the \fIdefault\fP field.  In the graphical user interface, the \fIdefault\fP
value will appear as specified on the forms, and will remain so until they
are changed by the user.  
.sp
.LP
.B
Title
.R
.IP
This field specifies the title that will appear on the GUI
for the item.  It is ignored by the CLUI.  The title
can contain spaces, but should remain fairly short (1-20 characters) to
be effective.  Tic marks (') may NOT be used as part of the title.  If no title
is desired, specifying ' ' as the title is accepted.
.sp
.LP
.B
Description
.R
.IP
The \fIdescription\fP field gives a brief description of the purpose of the
item.  It is only used by the command line user interface.  Comments in the
code generated by \fBghostwriter\fP are taken directly from the 
\fIdescription\fP fields in the UIS.  Descriptions should be clear and concise.
Tic marks (') may NOT be used as part of the description.
.sp
.LP
.B
Variable
.R
.IP
The \fIvariable\fP field is used by both the CLUI and
the GUI.  In code generated by \fBghostwriter\fP for the
command line user interface, the \fIvariable\fP field becomes the name of the
argument.  In code generated by \fBconductor\fP for the graphical user 
interface, the \fIvariable\fP field is translated into the naming conventions
for the C structure that provides the link between the application program and
the \fIxvforms\fP library.  For more information on use of the \fIvariable\fP
field, see the documentation on \fBghostwriter\fP, and/or \fBconductor\fP.
