DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
Frame definition files

Field descriptors

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.


NOTE: There must be at least one active, visible (that is, show=true) field in a form. If you open a form and none of the fields can be posted because rows or columns is negative or 0, or if frow or fcol is negative, FMLI will display an empty frame with the cursor positioned in the title bar. If the form definition file contains properly defined field labels, they will be displayed.


autoadvance
The 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
The 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.

columns
See the entry for rows, columns later in this section.

fieldmsg
The 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, fcol
The 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

If the field is the first field in the form, fcol defaults to 1+current_ncol+lengthOfLabel. By default, then, the input area of any field whose label is as long or longer than that of a previous field will be separated from the field label by one space. (Recall that position 0 is the first available column.) You can code the name descriptor for the first field with padded blanks to cause the value of lengthOfLabel to be longer than the actual word length of the label. The name and padded blanks must be surrounded by matching single or double quotes. That is, name='Field1   ' would have a length of 9, not 6, for the purpose of default positioning of the field. Assuming ncol has a value for 0 for the field, the value of fcol would be 10. Since the field will start at position 0, that will leave four spaces between the label and the input area.

inactive
The 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, invalidOnDoneMsg
The 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
The 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
The 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.


NOTE: If you define menuonly for a field, do not define the valid descriptor.


name
The 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
The 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, ncol
The 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
The 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
The rmenu descriptor defines a list of choices for a field. Two formats are acceptable when defining this descriptor:

rows, columns
The 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
The 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
The 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
The 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.


NOTE: The built-in utility regex is often used in a valid descriptor for field validation. For example, it can be used to require that part of a field be non-numeric.

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.

  1. If the field has been visited and modified, validation occurs upon any navigation key being pressed.

  2. If the field has been visited but not modified, validation occurs upon the <ENTER> key being pressed. The use of other navigation keys will not initiate validation.

    (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.)

  3. If the field has not been visited, or if it was visited but not modified and some key other than <ENTER> was used to navigate away from it, validation occurs upon the <SAVE> key being pressed.
So, if a user opens a form frame with five fields that define the 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.


validOnDone
The validOnDone descriptor does the same thing as the valid descriptor but is evaluated only when the user attempts to save the form, and is used with the invalidOnDoneMsg descriptor rather than the invalidmsg descriptor. You should use it to validate the relationship between the values of different fields, as in the following scenario.

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).


NOTE: The invalidOnDone descriptor can be coded as validOnDone=validonentry to request that any validation done with the valid descriptor be repeated when the user attempts to save the form. This allows you to code one validation in two places, eliminating a possible maintenance problem.


value
The 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
The 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.


NOTE: Screen labels and actions for function keys can be defined in a form description file as well as at the initialization file level. Each set of screen-labeled function key descriptors must include the name and button descriptors; the name descriptor must be first. If a descriptor appears more than once in a set, the last one is used. See ``Application level definition files'' for a discussion of how to use the screen-labeled function key descriptors.

Automatic layout of form fields

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:

Some applications have made use of these capabilities and will not be broken.

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=field5
These 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=fieldE
These 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.


Next topic: Example form definition files
Previous topic: Frame descriptors for forms

© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 27 April 2004