Frame definition files

Frame descriptors for forms

The optional set of frame descriptors can be any valid frame descriptors for forms, in any order. If a descriptor appears more than once in the set, the last one is used.

NOTE: Although technically none of the frame descriptors is required in a form definition file, a form that does not define the done descriptor is virtually useless, since no user input will be recorded when the <SAVE> key is pressed.

altslks

The altslks descriptor defines whether SLKs 9 through 16 are displayed when the frame is initially opened. If altslks evaluates to TRUE, SLKs 9 through 16 will be displayed.

The default, if this descriptor is not defined, is FALSE, which causes SLKs 1 through 8 to be displayed.

autolayout

The autolayout descriptor specifies whether FMLI should use reasonable defaults for the fcol, frow, ncol, nrow, and columns field descriptors in this form. If autolayout evaluates to TRUE, the reasonable defaults will be used; if it evaluates to FALSE, the defaults for these 5 field descriptors will be -1. The default, if this descriptor is not defined, is FALSE.

Using this descriptor and default field descriptor values allows forms to be created more easily, since when it evaluates to TRUE, the only required descriptor to define a field is the name descriptor, specifying the field label. Without this descriptor, all fields require 6 descriptors to be defined. More information may be found in ``Automatic layout of form fields''.

begrow, begcol

The begrow and begcol descriptors define the original position of the top left corner of the form frame in the user's work area. (begrow=0 and begcol=0 evaluates to the upper left corner of the work area.) When writing international applications, autosort should always be set to TRUE, because the fields used in a form will have different lengths in different languages. These descriptors accept values of type position:

center: the form frame will be centered in the work area
current: the form frame overlaps the current frame's position (valid for begrow only)
distinct: the form frame will not overlap the current frame if possible (valid for begrow only)
any: FMLI chooses a position with least amount of total overlap
integer: the form frame will be positioned in an absolute position, defined by integer. Defining begrow and begcol to be integer values causes the frame to appear in the given position.

If either begrow or begcol evaluates to center, then the other can only be an integer value or center. Any other value is ignored and the descriptor defaults to center.

If neither is center, then the value of begrow determines the value of begcol: if begrow is current, distinct, any, or an invalid value, then begcol defaults to any. If begrow is a valid integer, begcol can be a valid integer; if begcol is an invalid integer in this case, it defaults to any. If integer values are supplied and either begrow or begcol are outside the screen boundary, a default value of any will be used.

close

The close descriptor is evaluated when the form is closed and when the user exits from the FMLI application. The close descriptor is of type null, which means its only purpose is to obtain the side effects of backquoted expressions coded in its definition.

done

The done descriptor defines the command to be executed when the user selects <SAVE>. If done is not defined, it defaults to the FMLI command close. Note that user input is not saved automatically; user input to the form should be recorded by backquoted expressions in the done descriptor.

framemsg

The framemsg descriptor displays its value on the message line for as long as the frame is current. It can be temporarily replaced by a message displayed when:

the fieldmsg descriptor is defined for a specific field in the form frame
a message is generated by the message built-in utility with the -t (default) option
an FMLI error message is generated

It can be replaced for as long as the frame is current by a message generated by message with the -f option. (See message(1fmli).)

form

The form descriptor defines the title of the form frame. It will be truncated if it is longer than DISPLAYW-6.

help

The help descriptor specifies what will happen when the user requests help while in the form. Since this descriptor is evaluated at the time the user requests help, the specification of what help is displayed can be determined through parameters that are set interactively.

init

The init descriptor defines whether the form frame will be opened. If this descriptor is not defined, it defaults to TRUE, which means the form frame will be opened. If init evaluates to FALSE, the form frame will not be opened. If init evaluates to FALSE on an update, the frame is closed, unless it is an initial frame.

interrupt

The Boolean descriptor interrupt defines whether an executable that is coded in action or done descriptors can be interrupted by users (FALSE means not interruptible, TRUE means interruptible). It is subject to an inheritance hierarchy: if not defined anywhere in your application, the default value FALSE applies throughout. If explicitly defined at any inheritance level, then executables in action and done descriptors at or above that inheritance level will inherit that defined value. (See ``Interrupt signal handling'' for complete information.)

For example, if defined among the frame descriptors in a form definition file, the value of interrupt is inherited by the frame descriptor done, and the action descriptor in all sets of SLK descriptors in the form, unless it is redefined for a specific SLK.

lifetime

The lifetime descriptor defines when the form will be closed (that is, removed from the work area). It is evaluated whenever the form is opened, closed, made current, or made non-current. The acceptable values are:

shortterm: the form closes whenever the user navigates to another frame or when the command line is accessed (the user presses <CTRL-j> or <CTRL-f> <c>)
longterm: the form closes when the user issues a cleanup or close command
permanent: the form closes whenever the user issues a close command
immortal: the form closes only when the user exits from the application

The lifetime descriptor is ignored in form definition files that are given as arguments when fmli is invoked: such forms have a lifetime of immortal. See ``Defining a help frame for menu items or form fields'' for an example of how this descriptor may be used to close a form when another frame is opened or updated.

oninterrupt

The command descriptor oninterrupt defines what will happen when an interrupt signal is received. If interrupt is not coded anywhere in your application, or if it evaluates to FALSE, oninterrupt is ignored.

oninterrupt is subject to an inheritance hierarchy: if not defined anywhere in your application, the default value `message Operation interrupted!` nop applies throughout. If explicitly defined at any inheritance level, then executables in action and done descriptors at or above that inheritance level will inherit that defined value. (See ``Interrupt signal handling'' for complete information.)

For example, if defined with the frame descriptors in a form definition file, the value of oninterrupt is inherited by the frame descriptor done, and by the action descriptor in all sets of SLK descriptors, unless redefined for a specific SLK.

reread

If reread is not defined, it defaults to FALSE. If reread evaluates to TRUE, the form will be periodically updated by rereading its description file when the checkworld command is executed. checkworld is executed when a SIGALRM alarm occurs (every $MAILCHECK seconds). Other times checkworld is executed include when a frame is opened, closed, or navigated to. (See checkworld in ``Built-in variables''.) When checkworld occurs, all frames whose reread descriptor evaluates to TRUE will be updated. (However, the form descriptor is not reread.) Execution of checkworld may cause the message line to clear.