This chapter describes the optional application-level files that you can define for your application. The application-level definition files define attributes of the application as a whole:
The initialization file is a file containing descriptors that apply to your application as a whole. If you want to use an initialization file for your application, its name can be supplied as an argument, -i initialization_file, when the fmli command is invoked. As its name implies, its contents are read when your application is invoked. (It can also be reread using the reinit command.) In the initialization file you can define the following facets of your application:
A suggested order for initialization file descriptors is the following, although the only order that is enforced is that any sets of screen-labeled function key descriptors must be last in the initialization file.
[introductory_frame_descriptor_1 . . . introductory_frame_descriptor_n] . . . [banner_line_descriptor_1 . . . banner_line_descriptor_n] . . . [color_attribute_descriptor_1 . . . color_attribute_descriptor_n] . . . [general_application_descriptor_1 < . . general_application_descriptor_n] . . . [SLK-n_descriptor_1 . . . SLK-n_descriptor_n ...]
Note that all sets of descriptors in an initialization file are optional, as is the initialization file itself.
An introductory frame is a frame that is displayed briefly when your application starts, and is then cleared from the screen and replaced by the frame(s) you specify as arguments when fmli is invoked, as the initial frame(s) to open. The introductory frame will be displayed again briefly when the user exits from your application.
The introductory frame is defined with four descriptors normally used to define a text frame. Note, however, that the defaults are different when they are used in the initialization file than when they are used in a text-frame definition file.
The introductory frame descriptors are described below. Either the title or text descriptor must be included in the set of introductory frame descriptors.
A definition for an introductory frame is simple, as the following example shows:
title="WELCOME TO" text="My Application Copyright (c) 1989 My Software, Inc. All rights reserved." rows=5 columns=25
Backquoted expressions, containing calls to built-in utilities, may also be used, as in this line:
text="`readfile DEF_FILES/myintrotext`"
which will cause the text frame definition file myintrotext to be read from the directory whose alias is defined to be the text descriptor as the argument. (See "The Alias File" later in this chapter for more information about how to define aliases.)
Your application can display a different banner on the banner line. The banner descriptor must be included in the set of banner line descriptors,
bancol
The bancol descriptor defines the position of the banner in the banner line. If not defined, this descriptor defaults to center. It accepts the following values of type position;
center
centers the value of banner in the banner line.
integer
the banner will begin in the column specified by integer.
banner
The banner descriptor defines information that will appear in the banner line on the user's screen while your FMLI application is running. If not defined, it defaults to NULL.
working
The working descriptor defines a string used to notify users that they must wait until FMLI completes an activity. It always appears flush-right on the banner line. If this descriptor is not defined, it defaults to the string Working.
CAUTION: Taking care that other items on the banner do not run into this area is the responsibility of the developer.
The following lines, in an initialization file, will give you a banner with the program name, the date, and the time the FMLI application was started on the banner line (top line of the screen), starting in the 30th column.
banner="MYPROGRAM - `date`" bancol=30
The working icon appears right justified on the banner line. You can change the working icon, to BUSY for example, by defining the working descriptor in your initialization file as follows:
working="BUSY"
You may also put an application-specific indicator on the banner line by using the built- in utility indicator (see the manual page for complete details on its use).
The color attribute descriptors allow you to define the colors of various elements of the FMLI screen. The color descriptors can only be defined in the initialization file. They will be ignored in other files.
Due to the nature of curses(3X), colors must be set in pairs. This means you must set both the foreground and background for a specific element of the screen, otherwise it will default to monochrome. The pair for each color descriptor is indicated in the descriptions which follow.
CAUTION: If you set the foreground and background to the same color you will not be able to see the text.
The colors that can be used as values for the color attribute descriptors, for either foreground or background, are the following:
You may redefine these colors, or add new ones, with the setcolor built-in utility (see the setcolor manual page for complete details on its use). Of course, if the terminal your application is being run on can't display color FMLI automatically defaults to monochrome.
The following descriptors can be used in the initialization file to specify color attributes for the various screen elements. All of these descriptors are of type string and accept the color values listed previously.
If the terminal your application is running on does not support color, these descriptors are ignored. (You can use the built-in variable HAS_COLORS to test for color support.)
active_border
The active_border descriptor defines the color of the frame border when a frame is current (border foreground). This will enforce the "solid line" look of the screen border. The background for the active border is defined by screen.
active_title_bar
The active_title_bar descriptor defines the color of the title background when a frame is current (background for active_title_text).
active_title_text
The active_title_text descriptor defines the color of the title text when a frame is current (foreground for active_title_bar).
banner_text
The banner_text descriptor defines the color of all text on the banner line. If this descriptor is not defined in the initialization file, the banner text defaults to white. The background for this text is defined by screen.
highlight_bar
The highlight_bar descriptor defines the color of the menu selector bar (background for highlight_bar_text).
highlight_bar_text
The highlight_bar_text descriptor defines the color of the menu selector bar text (foreground for highlight_bar).
inactive_border
The inactive_border descriptor defines the color of the frame border when a frame is non- current (border foreground). The background for the inactive border is defined by screen.
inactive_title_bar
The inactive_title_bar descriptor defines the color of the title background when a frame is non-current (background for inactive_title_text).
inactive_title_text
The inactive_title_text descriptor defines the color of the title text when a frame is non- current (foreground for inactive_title_bar).
screen
The screen descriptor defines the color of the screen (screen background)
slk_bar
The slk_bar descriptor defines the color of the screen-labeled function keys (background for slk_text).
slk_text
The slk_text descriptor defines the color of the screen-labeled function key text (foreground for slk_bar).
window_text
The window_text descriptor defines the color of the text in a frame (text foreground). If this descriptor is not defined in the initialization file, it defaults to white. The background for this text is defined by screen.
The examples below show how to define the color of an area of the screen, and how to use the built-in utility setcolor to redefine one of the default color definitions and assign it to a portion of the screen.
Defining Color for the Banner Line
The color for text on the banner line is controlled by the descriptor banner_text. If this descriptor is not set the default is white text on a background that is the same color as the background for the rest of the screen.
banner_text=yellow
would make all text on the banner line yellow, and the background would be whatever you set it to for the rest of the screen.
Using setcolor to Redefine a Color Definition
The built-in utility setcolor allows you to define your own colors, if the terminal is capable of it. If you want to write machine independent code that uses the setcolor capability, use the OR operator in your backquoted expression. For example:
screen=`setcolor blue 100 24 300 || echo blue'
will set the screen to the default blue if the new one can't be defined. Of course, if the terminal can't display color at all, these descriptors automatically default to monochrome.
NOTE: If you reinitialize the FMLI application with a new background color, text in the banner line will be shifted one character to the right. To avoid this problem, force the banner to be reevaluated by including the banner line descriptors in the new initialization file.
The following descriptors can be used in the initialization file to define some display and functional characteristics globally for your application.
interrupt
The interrupt descriptor in an initialization file defines whether any executable coded in action or done descriptors in your application can be interrupted by the user. If not coded, it defaults to FALSE. If it evaluates to TRUE, then executables will be interruptible.
If defined here, in an initialization file, the value of interrupt affects executables in all action and done descriptors-in the SLK section of the initialization file, in all frame definition files, and in the commands file-unless otherwise defined at one of those levels. (See section "Interrupt Signal Handling", in Chapter 2 for more information.)
nobang
The nobang descriptor allows you to control user access to the UNIX shell and UNIX system commands from the command line. If not defined, nobang defaults to FALSE (users can access the UNIX shell).
FMLI allows users to escape to the UNIX shell from the command line (accessed with CTRL-j or CRTL-f c), by prefixing an exclamation point (!) to the command to be executed in the UNIX system. For example,
-->!pwd
But if nobang evaluates to TRUE, use of the ! prefix to commands typed on the command line will be disabled, and a message to that effect is displayed on the message line. In addition, when nobang evaluates to TRUE, open is also disabled from the command line.
NOTE: The nobang descriptor does not disable the unix-system command. See "The Commands File" later in this chapter for information on disabling access to the UNIX system via the unix-system command.
oninterrupt
The oninterrupt descriptor specifies the action to be taken when an interrupt signal is received. If oninterrupt is not defined anywhere in your application, it defaults to
`message Operation interrupted!` nop
If interrupt is not coded anywhere in your application,oninterrupt is ignored.
If defined in an initialization file, the value of oninterrupt affects executables in all action and done descriptors-in the SLK section of the initialization file, in all frame definition files, and in the commands file-unless otherwise defined at one of those lower levels. (See section "Interrupt Signal Handling", in Chapter 2 for more information.)
permanentmsg
The permanentmsg descriptor defines information that will be displayed on the message line until explicitly replaced or removed by another message of "permanent duration." (Messages of permanent duration are those defined with permanentmsg or with message -p.)
A message of permanent duration can be temporarily displaced by messages of "frame duration" and by messages of "transient duration." When the frame-duration or transient-duration message expires, the value of the most recent use of permanentmsg or message -p will again be displayed on the message line.
(See the message(1F) manual page for complete information on message durations.)
slk_layout
The slk_layout descriptor defines the layout of the screen-labels for the function keys. Two layouts are supported; 4-4 and 3-2-3. The value 4-4 causes the screen-labels to be displayed in two groups of four, as follows:
F1 F2 F3 F4 F5 F6 F7 F8
The value 3-2-3 causes the screen-labels to be displayed in three groups; of three, then two, then three screen labels, as follows:
F1 F2 F3 F4 F5 F6 F7 F8
The default, if this descriptor is not defined, is 3-2-3.
The toggle descriptor defines the way you want valid choices to be displayed when a user presses CHOICES in a form field for which you have defined the rmenu descriptor. By default, the available choices are shown in the field itself if there are three or fewer choices. If there are more than three choices, a pop-up menu, known as a Choices Menu, displays the available choices.
You can change this default behavior by defining the toggle descriptor in the initialization file. It accepts any of the following values:
always
When the CHOICES function key is pressed users will always be toggled through the choices, in the field itself.
integer
When the number of choices is greater than integer, a choices menu will be displayed. When the number of choices is less than or equal to integer, toggle behavior will occur.
never
When the CHOICES function key is pressed the user will never be toggled through choices in the field itself: a choices menu will always appear.
NOTE: If toggle evaluates to less than 1, then it defaults to 3.
use_incorrect_pre4.0_behavior
The use_incorrect_pre4.0_behavior descriptor causes FMLI to re-evaluate variables referenced with the $ notation until no special characters remain in the expression. If this descriptor is not defined, it defaults to FALSE.
If this descriptor evaluates to TRUE, then the $ notation behaves in the manner defined for the $! notation, and the $! notation has no special meaning. (See Variable Evaluation, in Chapter 2 for a complete discussion of the $ and $! notation for variable evaluation.)
CAUTION: This descriptor, and consequently the ability to make the $ notation behave like the $! notation, will be removed in the next release of FMLI.
Eight labels appear on the last line of the user's screen and indicate the functions currently assigned to the corresponding keyboard function keys F1 through F8 which are on most terminals. The screen labels are analogous to a set of menu items that are always displayed and from which the user can make a selection at any time by pressing the corresponding function key. (If a keyboard does not have function keys, the user can select the function using alternate keystrokes. See Appendix B for a list of alternate keystrokes mapped to the eight keyboard function keys.)
FMLI provides two sets of screen labels for function keys. There are eight screen labels in each set. FMLI has preassigned functions to only the first set of eight for each frame type.
Default Assignments of FMLI Commands to Function Keys
Screen-Labeled Menu Form Text Choices Command Function Key Frame Frame Frame Menu Menu F1 help help help help F2 mark* choices prevpage F3 enter save nextpage enter F4 prev-frm prev-frm prev-frm F5 next-frm next-frm next-frm F6 cancel cancel cancel cancel cancel F7 cmd-menu cmd-menu cmd-menu F8 chg-keys** chg-keys** chg-keys** chg-keys** chg-keys** F16 chg-keys** chg-keys** chg-keys** chg-keys** chg-keys**
Function keys F1 through F7 in the first set cannot be redefined. However, they can be disabled.
Function keys F8 through F16 may be defined. However, if you define F8 or F16, the user loses the ability to alternate between the two sets of SLKs. If you want to define PREV-FRM, NEXT-FRM, PREVPAGE, or NEXTPAGE, on the second set of function keys, the labels must be spelled exactly as they are on the first set (case is irrelevant).
NOTE: When you redefine screen-labeled function keys in the initialization file, your re-definitions become the defaults. Screen-labeled function keys may also be defined in individual form, menu, and text frame definition files. When they are defined in frame definition files, those definitions override the defaults (either the FMLI defined defaults, or the defaults you may have defined in the initialization file) while that frame is active.
You can define which set of screen-labeled function keys first appears when a frame is opened by defining the frame-level descriptor altslks in menu, text, and form definition files. If altslks evaluates to TRUE, the screen labels for function keys 9 through 16 will be displayed when the frame is first opened.
Following is a list of the screen-labeled function key descriptors used to define screen-labeled function keys. The name and button descriptors must be included in each set of SLK descriptors, and name must be first.
NOTE: Keep in mind that the screen-labeled function keys must be the last things defined in the initialization file, or in any frame definition file.
action
The action descriptor defines the command to execute when the particular screen-labeled function key is selected.
button
The button descriptor specifies the screen-labeled function key you are defining or disabling. The value of button is an integer corresponding to the number of the function key (1 through 16) to which the screen-label corresponds.
interrupt
The interrupt descriptor defines whether an executable that is coded in the action descriptor can be interrupted by the user. If not coded, interrupt defaults to FALSE. If this descriptor evaluates to TRUE, then executables will be interruptible.
If the interrupt descriptor is defined for a SLK in the initialization file, that value is inherited by the SLK unless the SLK is redefined in a frame definition file. Redefining a SLK in a frame definition file completely overrides a definition of it you may have coded in the initialization file. For example, if you define interrupt for a particular SLK in the initialization file,but do not include interrupt in a re-definition of that SLK in a frame definition file, the SLK will inherit the value of the interrupt descriptor defined at the next higher inheritance level (from the frame descriptors if defined there, then from the general descriptors in the initialization file if defined there, then from the FMLI defaults).
name
The name descriptor defines the name that is displayed on the screen-label. The value of name must be 8 or fewer characters. Defining name as a null string (name="") will disable the function key.
oninterrupt
The oninterrupt descriptor specifies the action to be taken when an interrupt signal is received. If it is not defined anywhere in your application, it defaults to `message Operation interrupted!`nop. It is ignored if interrupt is not coded anywhere in your application or if interrupt evaluates to FALSE.
If the oninterrupt descriptor is defined for a SLK in the initialization file, that value is current for the SLK, unless the SLK is redefined in a frame definition file. If a SLK is re-defined in a frame definition file, all descriptors for that SLK in the initialization file, including the oninterrupt descriptor, are ignored. If a SLK definition does not define oninterrupt, the SLK inherits the value set for oninterrupt from the frame-level descriptors, then from the application-level section of the initialization file.
The following example shows how to disable F7 (labeled CMD-MENU and assigned the FMLI command cmd-menu by default), and define F9 (the first SLK in set 2) to execute the exit command and display the screen label EXIT, in the initialization file:
name="" button=7 name="EXIT" button=9 action=exit
FMLI commands can be added to the Command Menu or disabled. You can also define new, application-specific commands to appear in the Command Menu. This is done in a commands file. If you create a commands file for your application, its name must be supplied as an argument, -c commands_file, when fmli is invoked. Each set of descriptors is ordered as follows:
[command_descriptor_1 . . . command_descriptor_n ...]
NOTE: There is an absolute maximum of 64 sets of command descriptors in a commands file.
The name and action descriptors must be included in each set of command descriptors and name must be first in each set.
action
The action descriptor defines the operation to perform when the command name is selected.
help
The help descriptor defines a command to be executed when the user asks for help on name. Since this descriptor is evaluated when the user requests help, the specification of what help is displayed can be determined through parameters that are set interactively.
interrupt
The interrupt descriptor defines whether an executable that is coded in the action descriptor in a command definition can be interrupted by the user. If not coded, it defaults to FALSE. If this descriptor evaluates to TRUE, then executables defined for this command's action descriptor will be interruptible.
If defined among the general descriptors in an initialization file, that value of interrupt affects all user defined commands which don't redefine interrupt. Note that built-in FMLI commands (such as checkworld) cannot be interrupted.
name
The name descriptor defines a string(the name of the command) that will appear in the Command Menu and that users can enter on the command line.
oninterrupt
The oninterrupt descriptor specifies the action to be taken when an interrupt signal is received. If it is not defined anywhere in your application, it defaults to `message Operation interrupted!`nop. The oninterrupt descriptor is ignored if interrupt is not coded or if interrupt evaluates to FALSE.
If defined among the general application descriptors in the initialization file, that value of oninterrupt affects all user defined commands which don't redefine oninterrupt.
To add a new, application-specific command, for example,
name="date" action=`date | message`nop help=open$MYOBJECTS/Text.datehelp
will allow a user to have a date command that puts the current date and time on the message line.
To disable an existing FMLI command, for example unix-system,
name="unix-system" action=nop
When an FMLI command that appears in the Command Menu by default is disabled in this way, its name no longer appears in the Command Menu.
WARNING: When you disable an FMLI command in the commands file, the command becomes unavailable not only to users, but to developers. That is, you cannot use that command in frame definition files or application level files. In particular, do not disable the exit command.
The contents of the commands file will be reflected in the Command Menu. You should avoid giving a command a name that is a partial match of another command, such as pr which is a partial match of both prev-frm and prevpage, because this makes it more difficult for users to navigate the (select) that command using character matching.
The alias file is a file which contains lines of the form
alias=value
where alias is a name to which you have assigned a pathname to a file or a device. There are two reasons for having an alias file;
The name of the alias file must be given as an argument on the fmli command line with the -a alias_file option when it is invoked.
Whenever you reference a pathname that does not begin with a / or a $ FMLI will check the alias file. For example,
MYTEXT=$HOME/myfiles/mytext
would allow the developer to refer to the text file Text.file in the directory $HOME/myfiles/mytext as MYTEXT/Text.file.
The alias may also contain the name of the file or device, for example,
MYTEXT1=$HOME/myfiles/mytext/Text.file
but frame definition filenames assigned to an alias must conform to the same naming convention as filenames on the invocation line.
More than one possible path may be assigned to a single alias by separating each path with a colon ( : ). For example,
MYFILES=$HOME/myfiles:$HOME/test/myfiles
would search $HOME/myfiles first, and if the file is not found search $HOME/text/myfiles whenever the alias $MYFILES is used. This is similar to the way $PATH is searched in the UNIX system.
The executable file fmli invokes the Form and Menu Language Interpreter and opens the file(s) you have named as the initial frame definition file(s) to open. It requires at least one argument: an initial frame to open. Subsequent interactions are driven by this initial frame.
The syntax of the fmli command is as follows:
fmli [-I initialization_file] [-c commands_file] [-a alias_file] file
where file is the pathname of a frame definition file describing the frame(s) to be opened initially. The argument file must follow the file naming convention Menu.xxx for a menu definition file, Form.xxx for a form definition file, and Text.xxx for a text frame definition file, where xxx is any string that conforms to UNIX system file naming conventions. The descriptor lifetime will be ignored for all frames opened by argument to fmli. Such frames have a lifetime of immortal by default.
Optionally, you may provide the names of initialization_file, commands_file, and alias_file. The initialization_file provides specific global instructions that allow for customization of the application, such as redefining screen colors or the default labels and functions assigned to SLKs. The commands_file allows the definition of commands specific to your application. The alias_file provides access to files via a shell-like ($PATH) notation, and allows you to define short, easy-to-use aliases for long pathnames to files.
CAUTION: FMLI does not use the end-of-file marker to determine when to exit an application, it uses the FMLI exit command. Thus, it is strongly advised that input to FMLI or FMLI applications not be from a pipe ( | ), a redirected file ( < ), or a here document (<< ).