A Prototype XSAR Menuing System

July 7, 1992

This is a follow-up to my earlier memo about user-programmable widgets and the extensible Tcl command language; the subject is timely, considering the recent TPOCC memo about STOL buttons on the Opcom menu bar. Using embedded Tcl, I wrote a user-programmable, TSTOL directive-generating, generic, Motif menu processor in little more than a day, although, if Jeff keeps lambasting my choice of editors, I might stretch its development out over 7 releases.

A Tcl-based menuing system has the following advantages over code- and/or UIL-based systems:

Menu hierarchies are easily created.
Menu definitions are easily modified.
A powerful language is available for defining the behavior of menus (i.e., the actions taken when menu items are picked).

XMENU

The menu processor, XMENU, reads a Tcl script file (an ASCII file containing Tcl commands) that defines the desired menu configuration and actions. The attached screen print shows the Telemetry System menu bar and pulldowns (in the upper right corner) generated by XMENU from a TS menu script. XMENU fits as follows into the XSAR user interface architecture:

                             XMENU       XTPDSP
                                  \     /   (Display)
                                   TSTOL
                                     |
                                State Manager

The XTPDSP display program (which can be automatically started up from XMENU's script program) connects to a TSTOL parser. TSTOL's startup procedure would then have two REMOTE directives that connect the parser both to XMENU and to the state manager. Directives submitted to TSTOL by the XMENU processor are executed as if they were submitted by XTPDSP. For example, on the attached screen print, XSTOL was run in place of XTPDSP:

                             XMENU       XSTOL
                                  \     /
                                   TSTOL

Picking the TS Status entry of the TS Presentation menu results in a "page TS_STATUS" directive being sent to TSTOL; TSTOL parses the directive and sends a page command to XSTOL/XTPDSP. In the command history window of the XSTOL panel, you can see an "[NI]" (network input) message showing the page directive received from the menu processor (known to TSTOL as TS_MENU).

Implementation

The XMENU menu processor is very simple. XMENU goes through the following initialization steps:

Initializes its X environment.
Creates a bulletin board object as the ancestor of the to-be-defined menus.
Creates a TSTOL command line input popup.
Registers some new commands with the Tcl interpreter.
Reads and executes the commands found in a Tcl script file.
Calls XtMainLoop().

XMENU extends the Tcl language with the following commands, used to define Motif-based menus:

menu pathname [-t type]: defines a menu. pathname is the name assigned to the menu display object. type is pulldown for a columnar menu (entries are stacked vertically) or bar for a menu bar (entries are arranged horizontally in a row); the default is pulldown.
pathname add [-c command] [-l label] [-m submenu] [-t type]: adds an entry to the menu specified by pathname. (pathname is added as a new Tcl command when the menu is defined.) command is a string to be executed by the Tcl interpreter when this menu entry is selected; it may be one or more Tcl commands or even the invocation of a Tcl procedure. label is the text to be displayed for the menu entry. submenu is the name of another menu to be displayed if this entry is a cascade button. type is one of the following: cascade (the default), label, pushbutton, or separator. A cascade button without a submenu acts just like a pushbutton.
manage pathname
unmanage pathname: manage or unmanage the widget named pathname. These commands allow a menu pick to bring up and take down an arbitrary display object. For example, the TS Control menu has, for testing purposes, a TSTOL submenu that allows you to popup a TSTOL command line input window.
callback pathname callbackName command: binds a Tcl command string to callback callbackName of widget pathname. When the callback is invoked, the command string is passed to the Tcl interpreter for execution. Note that the callback command allows you to assign a Tcl command (and therefore TSTOL directives) to an arbitrary callback of an arbitrary widget, not just to STOL buttons and menu entries.
tstol answer -s serverName
tstol call -m mission [-h host]
tstol receive
tstol send string: provide an interface to TSTOL. tstol answer initiates the answering of a connection request from TSTOL (or another process if desired); XtAppAddInput() is used to put the actual establishment of a connection in the "background". tstol send sends the specified string to the TSTOL parser; the string can be a nested Tcl command that, when evaluated at run-time, returns a string. tstol call and tstol receive are available, but have only been used for testing so far.

Using these new commands, the TS menu bar was defined as follows in a Tcl script file:

    menu ts -t bar
    ts add -l "  Control  " -m control
    ts add -l "  Analysis  " -m analysis
    ts add -l "  Presentation  " -m presentation
    ts add -l "  Database  " -c { puts stderr "-- Not Available --" }
    ts add -l "    "
    ts add -l "  Help  " -c { puts stderr "-- Not Available --" }

The "-m" options on the first three entries link them to the appropriate pulldown menus. Picking either the Database entry or the Help entry produces an error message.

The Presentation pulldown menu is defined by the following commands:

    menu presentation
    presentation add -l "Hardcopy" -m hardcopy
    presentation add -l "Dynamic" -m dynamic
    presentation add -l "Static" -m static
    presentation add -l "TS Status" -c { tstol send "page TS_STATUS" }

The first three entries are linked to cascading submenus. The last entry, TS Status, is used to bring up the Telemetry System status page. When this entry is selected, a "page TS_STATUS" directive is sent to TSTOL, which, in turn, sends a page command to Display (XTPDSP) to actually bring up the page.

The main and Presentation menus above show the basics of defining the structure and behavior of menus in the XMENU script file. A couple of other examples show some additional capabilities of Tcl-defined menus. The Exit option on the TS Control menu executes two Tcl commands, one to send an "\exit" directive to TSTOL and the second to terminate the XMENU program itself:

    control add -l "Exit" -c { tstol send "\\exit" ; exit }

The Command Line option on the TSTOL submenu opens up XMENU's TSTOL command line input window:

    tstol_menu add -l "Command Line" -c { manage tstol_window }

This window is simply a Motif command widget, consisting of a command input line and a scrolling command history list; selecting a line in the history list transfers the text to the input line, where the directive can be edited before it is submitted to TSTOL. (Are you sure you want TPOCC's previous-command-only recall capability?) Messages received by the menu processor from TSTOL are added, courtesy of XtAppAddInput(), to the scrolling history list.

XMENU's input file is primarily intended as, but not restricted to being, a menu definition file. For example, my current XMENU script, ts.tcl, defines the TS menu hierarchy, spawns the display program (XSTOL in my case, but it could be XTPDSP), and begins listening for a connection request from TSTOL.

Improving on Perfection

XMENU was very rapidly prototyped. Although XMENU is a functional, working program, enhancements would need to be made in a production version of the software:

Error checking must be more extensive and robust.
The new Tcl commands used to define menus could be refined further; the current command set was hastily thrown together.
Command arguments could use word options rather than letter options; e.g., "-label label" instead of "-l label".
Support for sensitive menu entries and toggle entries needs to be added. Given the former capability, XMENU could desensitize menu entries based on the operator's allowable privileges.
Support for other Motif menu attributes could be added - by someone more familiar with them!
Currently, a menu tree must be defined from the bottom up; i.e., submenus must be defined before their parents are. Checking a list of unresolved submenu references whenever a new menu is defined would eliminate this restriction.

Conclusions

The use of an embedded command language like Tcl allowed the writing of a general-purpose, Motif-based menu display and processing program. This menu processor can handle, without changes to the executable, the TS menus, the CS menus, and other menus that are, as of yet, only a gleam on our system administrator's earring.

Although the XMENU program could work with menus defined via UIL, UIL seems a tedious way of defining a menu hierarchy. The examples in the TPOCC memo on STOL buttons required 10-15 lines of UIL for a menu entry that would be a Tcl one-liner. UIL provides great flexibility in specifying the appearance of a display object, but there are only so many ways you can or would want to change the appearance of a menu. More important is the ability to easily specify the behavior of a menu. The XSAR-extended Tcl gives us this capability without forcing us to write special-purpose callback functions in addition to our menu definitions.

Alex Measday / E-mail