|
|
The following descriptors can be defined once for each field in a form. In each set of field descriptors, name must be first. If a descriptor appears more than once in a set, the last one is used.
autoadvance
descriptor defines whether a
<<Return>>
is automatically performed when a user fills in the last character
of a field.
It defaults to FALSE (an automatic
<<Return>>
is not performed).
If
autoadvance
is defined and evaluates to TRUE,
when the user types in columns characters,
the field will be automatically
validated, and if valid,
the cursor will be automatically advanced to the next field.
This descriptor is ignored in vertically or horizontally
scrollable fields.
choicemsg
descriptor defines
information to be displayed on the message line when the user
presses
<CHOICES>.
The
choicemsg
descriptor displays a message with transient duration.
That is, it remains on the message line only until the user presses another key
or a
checkworld
occurs.
Transient messages take precedence over frame duration messages and
permanent duration messages (see the
message(1fmli)
manual page
for more information).
If
choicemsg
is not defined, the default is
There are no choices available.
fieldmsg
descriptor defines information that will appear on the message line
when this field is navigated to.
The
fieldmsg
descriptor displays a message with transient duration.
That is, it remains on the message line only until the user presses another key
or a
checkworld
occurs.
Transient messages take precedence over frame duration messages and
permanent duration messages (see the
message(1fmli)
manual page
for more information).
frow
and
fcol
descriptors define the position of the field input area in the frame.
The value of frow can be an integer greater than or
equal to 0 and less than DISPLAYH-2;
the value of fcol
can be an integer greater than or equal to 0 and less
than DISPLAYW-2.
(frow=0 and fcol=0 evaluate
to the upper left corner of the frame,
that is, to the first available row and column, respectively.)
If either value is negative
or if either value is too large (the position is off the screen),
then the field input area will not be displayed.
If no field input areas are displayed on a page of a form, the cursor is
positioned in the title bar.
When autolayout evaluates to FALSE, these descriptors default to -1.
When autolayout evaluates to TRUE, frow defaults to the value current_nrow, where current_nrow is the value of nrow for the field being defined. That is, by default the row in which the field input area appears will be the same as the row in which the label of the field appears.
When autolayout evaluates to TRUE, fcol defaults to the greater of
inactive
descriptor defines a form field that is
displayed in the form, but cannot be navigated to.
If this descriptor is not defined, it defaults to FALSE (the field
will be active).
If this descriptor evaluates to TRUE, the field is displayed in
the form, without an underline, and cannot be navigated to.
By default, the inactive descriptor is
evaluated when the form is opened and thereafter
whenever navigation occurs from a field whose value has been changed.
There must be at least one active field for a form to be
displayed.
invalidmsg
descriptor is used with the valid
or menuonly descriptors and defines
a string that will be printed on the message line when the input for
the field is invalid.
The default is Input is not valid.
The
invalidOnDoneMsg
descriptor is used with the
validOnDone descriptor
and defines a string that will be printed on the message line
when validOnDone evaluates to FALSE.
The default is Relationship of values in 2 or more fields is not valid.
If you use a different message, make sure it indicates to the user that
more than one field is involved.
These descriptors
display a message with transient duration.
That is, it remains on the message line only until the user presses another key
or a
checkworld
occurs.
Transient messages take precedence over frame duration messages and
permanent duration messages (see the
message(1fmli)
manual page
for more information).
lininfo
descriptor
defines a string that will be assigned to the built-in
variable LININFO
when the user navigates to the field.
If
lininfo
is not defined, LININFO evaluates to the null string.
menuonly
descriptor defines
the choices listed in the
rmenu
descriptor to be the only valid input for the field.
If this descriptor evaluates to TRUE, then the user must input
one of the choices in rmenu for the field.
menuonly must only be used when the rmenu descriptor
has been defined using the curly brace format; otherwise no
input will be valid.
name
descriptor defines the label of the field.
The value you define for
name
should tell the user what piece of information is wanted in the field.
It can also be used to display a label, such as Page 2 of 5, if it and these other descriptors for the field are defined as follows:
noecho
descriptor defines whether what the user enters in
the field input area will be displayed.
This descriptor defaults to FALSE (input will be displayed).
If
noecho
does not evaluate to FALSE, then
what the user enters in the field will not be echoed in the display
(this descriptor is often used when the requested input is a password).
noecho should not be defined for multi-line fields.
nrow
and
ncol
descriptors define
the position of the first character of
name
in the form.
These descriptors accept an integer value:
the value of nrow can be greater than or equal to 0
and less than DISPLAYH-2;
the value of ncol can be greater than or equal to 0
and less than DISPLAYW-4.
(nrow=0 and ncol=0 evaluate
to the upper left corner of the frame,
that is, to the first available row and column, respectively.)
If either value is negative,
name
will not be displayed.
If either integer is too large (the position is off the screen),
the entire form will not be displayed.
When autolayout evaluates to FALSE, these descriptors default to -1.
When autolayout evaluates to TRUE, nrow defaults to the value previous_nrow+previous_rows, where previous_nrow and previous_rows are the values, respectively, of nrow and rows for the previous field in the form. If the field is the first field in the form, or the first field on the page of a multi-page form, the default is 0. By default, then, unless the field is the first one on a page, its label will appear one row below the last row of the previous field.
When autolayout evaluates to TRUE, ncol defaults to its value in the previous field, or 0 if the field is the first field of the form.
page
descriptor allows you to define the page of a form on which the field will appear.
It accepts integer values greater than 0.
A value of 0 or a negative value will cause the
field not to appear in the form.
page defaults to 1 (the field will appear on the first page of the form). A value greater than 1 creates a multi-page form. That is, if page is defined for a field and evaluates to 2, for example, the field will appear on the second page of the form.
rmenu
descriptor defines a list of choices
for a field.
Two formats are acceptable when defining this descriptor:
rmenu={ item1 item2 item3 ... itemn }
By default, if this list has three or fewer items, the choices are displayed in the field itself. The first item appears when the user presses the <CHOICES> SLK; the user toggles through the choices by pressing the same key. If the list has more items, the choices will appear in a pop-up choices menu. (See ``Application level definition files'' for a discussion of the toggle descriptor, which can be used to change this default behavior.) When the user selects an item in a pop-up choices menu, the selection is automatically placed in the built-in variable Form_Choice, the value of which is entered in the field when the choices menu closes.
rmenu
descriptor evaluates to opening a menu, and the user selects
from that menu.
For example:
rmenu=open Menu.mtgdatesThe action associated with each choice in the menu must set the built-in variable Form_Choice and close the menu. When the user selects an item in the menu, the selection is placed in Form_Choice, the value of which is entered in the field when the choices menu closes. The toggle descriptor is ignored when this format is used--a pop-up choices menu is always displayed.
rows
and
columns
descriptors define
the size of the input area,
the length and
width, respectively, of the region in which the user can enter input.
These descriptors accept an integer value:
the value of rows must be greater than 0 and
less than DISPLAYH-2;
the value of columns must be greater than 0 and
less than DISPLAYW-4.
If either is less than or equal to 0,
the field will not be displayed.
If either value is too large (the position is off the screen),
the entire form will not be displayed.
rows defaults to 1 (the field will be one row long). A value greater than 1 creates a multi-line field.
If autolayout evaluates to FALSE, columns defaults to -1. If autolayout evaluates to TRUE, columns defaults to its value in the previous field, or 4 (the field will be four columns wide) if the field is the first field of the form. Although a default value cannot be picked that will be useful for real applications, a default value can be useful for learning purposes and for writing test scripts; hence the default 4.
scroll
descriptor defines whether the field input area can scroll.
There are two types of scrolling: vertical, for multi-line fields;
and horizontal, for single-line fields.
If not defined, this descriptor defaults to FALSE (field input
area cannot scroll).
If
scroll
evaluates to TRUE, then the field input area can be scrolled.
This means that the field input area can be as long as the entry the user types,
and the columns descriptor is not a limit for the length of
user input.
For single-line fields, the last space in columns is reserved for
scroll symbols: ``>'' means the field can be scrolled to the right, ``<''
means the field can be scrolled to the left, and ``='' means the field can
be scrolled either left or right.
For example, after the user types in columns-1 valid characters,
the field will scroll, and the ``<'' symbol will appear in the last space,
indicating that the input in the field has scrolled to the left.
For multi-line fields, scroll indicators for up (``^'') and down (``v'')
appear in the bottom right border of the frame when
the user has entered data up to
the last character in the last displayed line of the field.
For example, after the user types in rows lines of information,
the scroll indicator for up (``^'') appears in the lower right border.
show
descriptor defines whether a field will be displayed in the form.
If
show
evaluates to FALSE, then the label and input area will not be shown.
There must be at least one field for which
show
evaluates to TRUE, or the form will not open.
By default, the show descriptor is evaluated when the form is opened and
thereafter whenever navigation occurs from a field whose
value has been changed.
Note that even if the field is not shown,
it still counts as a field for the purpose of evaluating
the built-in variable Fn.
(See
``Variables''
for more information about the built-in
variable Fn.)
valid
descriptor defines whether the input to
a field is valid.
If valid evaluates to FALSE, the current input is considered
invalid and FMLI will not process the field or evaluate the
done descriptor.
Checking the validity of the field is often done
by evaluating a backquoted expression.
The backquoted expression must be coded to evaluate to TRUE when the
value is valid, FALSE otherwise.
The FMLI conditional statement has essentially the same functionality as the UNIX system shell conditional statement, and can be used to do more complicated validations.
Before a user leaves a form, each field that defines the valid descriptor is validated at least once, at one of the following times. Note that the critical factors are whether the field was modified, and which key was used to navigate away from it.
(Note that this behavior is new in FMLI 4.0+. Thus, users can now navigate to other fields when, for example, leaving the current field blank would cause it to fail a validation test.)
valid
descriptor, but only modifies the
first two fields, the two modified fields are
validated before the use can leave them.
The remaining three fields will be validated when
the user saves the form.
If any field (including fields on other pages in a multi-page form) does not pass its validation test, FMLI will not process the field, the cursor will jump to the invalid field if not already on it, the message defined in the descriptor invalidmsg (if defined, otherwise the default message) will be displayed on the message line, and the done descriptor will not be evaluated. In the case of more than one invalid field, this behavior will be repeated in field order, each time the <SAVE> SLK is pressed.
For the reasons given in the validOnDone entry below, you should use valid only to validate the value of a single field, without reference to other fields. Use validOnDone to validate the relationship between the values of different fields.
You should be cautious using the valid descriptor for a field that could become inactive. Unexpected behavior can occur.
Suppose you have defined Major, Degree, and College fields in a form, in that order. For the Degree field you have defined a validation test that will disallow the values BS or MS when Major has the value History. If you use valid to perform the test
valid=`test ( "$F1" = "History" -a
( "$F2" = "BA" -o "$F2" = "MA" )
) -o
( "$F1" = "Electrical Engineering" -a
( "$F2" = "BS" -o "$F2" = "MS" )
) `
invalidmsg=vary The "$F2" degree is not offered in "$F1"
FMLI will correctly disallow an entry of BS
in Degree when Major is History.
Suppose now, though, that the user has entered Electrical Engineering in Major and BS, a valid value, in Degree. This user has a change of mind and, after navigating back to Major, changes its value to History. Because valid has already been evaluated for Degree, FMLI will not check its value against the new value of Major unless Degree is revisited. It will check it, however, if the invalidOnDone descriptor is coded for Degree
validOnDone=`test ( "$F1" = "History" -a
( "$F2" = "BA" -o "$F2" = "MA" )
) -o
( "$F1" = "Electrical Engineering" -a
( "$F2" = "BS" -o "$F2" = "MS" )
) `
invalidOnDoneMsg=vary The "$F2" degree is not offered in "$F1"
because invalidOnDone is
evaluated when the user attempts to save the form.
You would use invalidOnDone in a similar
way if, say, you wanted to disallow
the value Business for College when Major
had the value History and Degree
had the value BA.
When invalidOnDone evaluates to FALSE for a field, the cursor is positioned in the input area of that field. Because the descriptor is evaluated only when the user attempts to save the form, the user can navigate away from the field to any other field. In other words, the user of the example application above could navigate away from Degree to Major and change its value to Electrical Engineering. As this implies, all invalidOnDone descriptors for a form will be re-evaluated each time the user attempts to save the form (because the new value of Major, although valid in relation to the value of Degree, may now be invalid in relation to the value of College).
value
descriptor defines
the default value for the input field.
If this descriptor is defined, its value will be
displayed in the field when the form is opened or updated.
The default is not changed by the user entering data
into the field.
That is, the default value is restored when the form is
opened or updated,
or if the built-in utility reset is run while the
field is current.
Note that valid or invalidOnDone can be used to validate the
input to fields defined to have default values.
wrap
descriptor defines whether word wrap will occur if
a word will not fit on the current line of a multi-line field.
If this descriptor is not defined, it defaults to FALSE.
If
wrap
evaluates to FALSE, then the cursor will not automatically wrap
to the next input line.
If
wrap
evaluates to TRUE, and word will not fit on the current line
but will fit on the next line, then word
will automatically be moved to the next line.
The wrap descriptor is ignored in a single-line field.
In previous versions of FMLI the descriptors that define the position and size of fields and their labels (frow, fcol, nrow, ncol, and columns), defaulted to -1. In effect, this meant that those five descriptors had to be defined for each field in the form.
With FMLI Release 4.0+, new, more reasonable defaults are available for these descriptors. However, to preserve compatibility with older applications, the new defaults are only available if the autolayout frame descriptor for the form evaluates to TRUE, or if the application descriptor autolayout evaluates to TRUE and the same descriptor for the form is not coded. When the autolayout descriptor is defined, the new defaults provide automatic layout of the fields and labels of a form; the only required field descriptor is name. The new defaults are described in detail in the previous section, ``Field descriptors''.
The defaults enabled by autolayout allow easier coding for simple forms and test scripts, rapid prototyping, and provide a reasonable default form appearance, although nrow, ncol frow, fcol, and columns can still be used to obtain precisely formatted forms. In addition, it is still possible, using the previous defaults of -1 for these descriptors, to obtain the following refinements:
A few simple examples will help. A 5-field form can be defined with only 5 field descriptors, instead of the 30 previously required:
autolayout=true name=field1 name=field2 name=field3 name=field4 name=field5These fields would appear in the form as:
A simple form with 2 columns and some other variations could be defined with:
autolayout=true name=field1 name=field2 name=field3 name=field4 name=field5 name=fieldA nrow=0 ncol=14 columns=2 name=fieldB name=fieldC name=fieldD fcol=25 name=fieldEThese fields would appear in the form as:
``Form.addr: defaults used'' shows how defaults would work for a less rigid arrangement of fields and labels.