Previous Page TOC Next Page

Character User Interface (FMLI and ETI)

Application Level Definition Files

Introduction


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


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.


Note that all sets of descriptors in an initialization file are optional, as is the initialization file itself.

Introductory Frame Descriptors


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.


columns
The columns descriptor defines how many columns wide you want the introductory frame to be. It defaults to the integer value 50 if not defined for an introductory frame.


rows
The rows descriptor defines how many rows high you want the introductory frame to be. It defaults to the integer value 10 if not defined for an introductory frame.


text
The text descriptor defines the text that you want to display in the introductory frame. It defaults to NULL if not defined. If neither the title descriptor or the text descriptor is defined in the initialization file, the introductory frame will not be displayed.


title
The title descriptor defines the title that will appear at the top of the introductory frame. It defaults to NULL if not defined. It will be truncated if it is longer than DISPLAYW -6. If neither the title descriptor or the text descriptor is defined, the introductory frame will not be displayed.

Example Definition of an Introductory Frame


A definition for an introductory frame is simple, as the following example shows:


Backquoted expressions, containing calls to built-in utilities, may also be used, as in this line:


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

Banner Line Descriptors


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.

Example Definitions of a Banner Line


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.


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:


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

Color Attribute Descriptors


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.

Examples of Defining Color Attributes


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.


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:


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.

General Application Descriptors


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,


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


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:


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:


The default, if this descriptor is not defined, is 3-2-3.

toggle

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.

Screen-Labeled Function Key Descriptors


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


*
Function key F2 is assigned the mark command only in multi-select menus. In single select menus F2 has no default assigned.


**
Function keys F8 and F16 will default to chg-keys only if any of keys F9 through F15 are defined by the developer.


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.

Example Definitions of Screen-Labeled Function Keys


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:

The Commands File


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:


NOTE: There is an absolute maximum of 64 sets of command descriptors in a commands file.

Command Descriptors


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.

Example of Adding an Application-Specific Command


To add a new, application-specific command, for example,


will allow a user to have a date command that puts the current date and time on the message line.

Example of Disabling an Existing FMLI Command


To disable an existing FMLI command, for example unix-system,


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


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.

Examples of Adding Path Aliases


Whenever you reference a pathname that does not begin with a / or a $ FMLI will check the alias file. For example,


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,


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,


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.

fmli Command Syntax


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

Previous Page Page Top TOC Next Page