| Felix Command Language Reference |
<mode> <item-name> <mnemonic> <Accelerator> <Accelerator-text> <call-back> <call-back-data> <filename>
menubar File F NULL NULL NULL NULL file.motwhere File is the name of the item that appears on the menu bar. F is the hot key that is to be used for the command, and that character is underlined on the menu bar. file.mot is the name of the file that contains the items for the File pulldown menu.
popup "Plottype" t NULL NULL "view Plottype" NULL plottype.motIn this example, "Plottype" is the text that appears on the pulldown or cascading menu. t is the hot key to use, and that character is underlined on the menu. "view Plottype" is text that is given for this menu and is just for your reference (it is not used). plottype.mot is the name of the file that contains the items to appear on the cascading menu.
separator separator NULL NULL NULL NULL NULL NULLwhere separator is the text for the widget name. This can be any text you desire.
toggle "Draw Peaks" D Ctrl<Key>k Ctrl+kwhere "Draw Peaks" is the label for the toggle button that will appear on the menu. D is the hot key character that is underlined on the menu. Ctrl<Key>k is the accelerator that motif binds to this menu item. Ctrl+k is the text that will appear next to the text for the menu item. "ex drawpeaks" is the call-back macro that is called when this menu item is selected or the items accelerator keys are pressed. pksdrw is the name of the symbol that is updated when the state of the toggle button is changed.
"ex drawpeaks" NULL pksdrw
item "Plot" P Ctrl<Key>p Ctrl+p "ex plot" NULL NULLwhere "Plot" is the text that appears on the menu. P is the hot key for this menu item. Ctrl<Key>p is the accelerator definition. Ctrl+p is the text that appears next to the label. "ex plot" is the call-back that will be called when this menu item is selected.
keypad NULL NULL NULL NULL "exm keypad" NULL NULLwhere "exm keypad" is the command which gets called when you press the keypad buttons.
mouser NULL NULL NULL NULL NULL NULL mouser.motwhere mouser.mot defines which menu items to pop up when the user hits the right mouse button.
mousem NULL NULL NULL NULL "exm cursorval 4"where "exm cursorval 4" is the call-back that gets called when the user hit the middle mouse button inside of a frame.
NULL NULL
<mode> <filename> <call-back> <ballon-help-text> <param1> <param2> <param3> <param4>where mode has the following two forms:
icon zoom20.icon "ex limits 1" "Zoom" NULL NULL NULL NULLwhere zoom20.icon is the file that contains the bitmap that is used to display the graphic on the icon button. "ex limits 1" is the call-back macro that gets called when the use selects this icon. "Zoom" is the balloon-help-text that is displayed when the cursor is placed above this icon.
separator separator NULL NULL NULL NULL NULL NULLParameters 1-4 are currently not in use.
option plottyp.mnu "ex plottype 0" "plottype" plottyp NULL NULL NULLwhere plottype.mnu is the menu file that contains the text to display on the popup menu. "ex plottype 0" is the call-back which is called when this option menu is activated. "plottype" is used for balloon help but is not currently displayed. plottyp is the symbol that is changed when you select a different item on the popup menu.
To pop a dialog box to the screen, you must issue the following command string with appropriate arguments.
mnu p <menu> <x-origin> <y-origin>The mnu p command in the string above tells the program to read a menu file containing some type of dialog box definition. Whenever the <menu> argument is called, a menu file by that name must be present in one of the current menu directories (defined by mnupfx, mnupf1, and other symbols). By convention, menu files use the .mnu extension. The <x-origin> and <y-origin> parameters define the position of the upper left corner of the box in character cell units (with the motif version these numbers are ignored although they have to be supplied on the command line). A character cell unit is defined as the maximum space that a character needs to be written correctly. A letter `a' is one character cell wide and one character cell high. For example, the command line:
mnu p xopen 20 4generates a dialog box and places it on the screen in a separate window. A full listing of the file with the corresponding dialog box it creates is shown below. Note that most of the files that define dialog boxes begin with the letter `x'. This is not mandatory, but is simply one convention that can be used to help organize the directory containing the menu files.
The ASCII file xopen.mnu looks like this:
c**xopen.mnu 23 40 *h 1 1 14 `OPEN FILE' ;This file creates the following dialog box:
*o 2 2 40 5 5 &mytype&ftype &newpfx&ftype newfil(de:ftype.ge.0) ; *c 3 19 5 `File Type' *p 12 19 16 7 `Matrix (*.mat)' `Felix Data (*.dat)' `DBA (*.dba)' `InsightII Molecule (.car)' `PDB Molecule (.pdb)' `Other Data (Bruker, Varian, JEOL, FFW) (*)' `Macro (*.mac)' ftype ; *c 3 20 5 `Dimension' (de:ftype.eq.1) *p 12 20 8 2 `1D' `ND' datdim (de:ftype.eq.1) ; *c 20 20 5 `Access' (de:ftype.eq.0) *c 20 21 5 `Storage' (de:ftype.eq.0) *p 27 20 10 2 `Read Only' `Write' macces (de:ftype.eq.0) *p 27 21 10 2 `Disk' `Memory' matmem (de:ftype.eq.0) ; *x 2 22 40 5
Within the file that defines a dialog box there are two different classifications of commands. The first group of commands provide the graphical information needed to design the dialog box. These commands define the size of the dialog box, the text for the dialog box header (*h), the text for user prompting (*c), coordinates for displaying highlighted boxes (*x). These commands are for output only. The second group of commands found in dialog boxes are for setting symbol values based on input from the user. These commands create fields (*f), toggles (*t), switches (*s), list boxes (*l), buttons (*b), combo boxes (*p), file-select (*o), and list boxes (*v) with multiple items on a line (so-called "variable lists").
*h <x-origin> <y-origin> <number of characters> `<header text>'Note that in the example above, the <header text> must be enclosed by single quotes. By default, the header is left-justified within the dialog box and thus the parameters <x-origin> and <y-origin> are ignored. Header text may contains characters or may contain symbol substitution for customizing the header.
The *c command in a dialog box file is used to place character text. Text in dialog boxes is most commonly used for labeling the required input for data fields. Note that the command that defines a data field is not coupled to the text that labels it! The format of a character string command within a dialog box file is:
*c <x-origin> <y-origin> <# of characters> <descriptor text>Using the *c command, character strings can be placed throughout the dialog box. Character strings are limited to 64 characters and must be enclosed by single quotes.
To enhance the appearance of dialog boxes, we have provided a command for drawing highlighted boxes. These boxes are often used to group related switches or input fields. Within a dialog box definition, boxes are defined as:
*x <x-origin> <y-origin> <width> <height>The <x-origin> and <y-origin> parameters define the bottom left corner of the highlighted box. The <width> and <height> parameters define the box size in character cell units.
A variation of the highlighted box is when an extra symbol or text string is found on the line:
*x <x-origin> ,y-origin> <text>In this case, the text string is placed on the left top line of the highlighted box.
For dialog boxes needing extra user notification, there is a command for generating a "beep" from the computer. This type of action is commonly placed in dialog boxes that notify of errors or confirm potentially dangerous actions such as file deletion. The command for generating a beep within dialog boxes is simply:
*n
To generate a field for data input, the *f command is placed within the dialog box file. This has the format:
*f <x-origin> <y-origin> <length> <type> <symbol>Again, the <x-origin> and <y-origin> values are used to place the field using character cell units. The <length> parameter defines the length of the field in character cell units. The <type> parameter defines the format of the field. A `c' is used to define character input for the field, an `i' for integer input and a `r' for real number input. The parameter needed for <symbol> can be either a reserved symbol name or a user symbol name. In either case, the current value for the symbol is displayed in the field. If that symbol has not yet been defined, then a new user symbol is created and is defined to have the value 0 or blank, depending on whether the field is numeric or character. The <symbol> parameter does not have the "&" used for substitution because we want the symbol name, not its value. Note that the field contains no user prompting information. Prompting must be performed separately using *c commands as discussed above.
Symbol values can also be updated from within list boxes. A list box is an object that appears within dialog boxes that lets the user select and scroll through values from a displayed list. To display a list box the *l command is placed within the dialog box file. This dialog box command has the format:
*l <x-origin> <y-origin> <width> <height> <list file> <select> <symbol>The <x-origin> and <y-origin> values are used to define the lower left corner of the list box in character cell units. The <width> and <height> arguments define the width and height of the list box in character cell units. The <list file> argument is the name of the text file to appear in the list box. The <select> argument is the name of the symbol that defines which line was selected from the list. The value of the symbol <select> is set to 1 if the first line in the list is selected, 2 if the second line is selected, and so on. The <symbol> argument is the name of the symbol whose value is updated to reflect the selected line. For example, if the selected value was test.mac, <symbol> will have that value after it has been selected from the list box. From list boxes, you therefore have two means of getting output. <select> is updated to define the number of the line in the list box that was selected, while <symbol> represents its actual alphanumeric contents. When exiting from a list box, either of these values can be used to make a later decision. In conclusion, be aware that symbol fields can be updated by selecting items from a list box. This is especially useful for selecting files or matrices to be read and displayed. Note that the text file named by the <list file> argument may be virtually of any form or origin. In many places in the menu interface, Felix puts up a list box of file names. To make this happen, Felix issues a UNIX command to get a directory listing and store it to a file, then shows that file in the list box. You could just as easily build a file using the opn, put, and cls commands. Again, the file shown in a list box can be any ASCII file.
Switches are used within dialog boxes for setting the values of symbols to integer numbers. Switches take the form of circles that can be placed anywhere within the dialog box. The program is currently limited to the placement of four switch circles per switch command. By convention, a switch option is activated when its identifying circle is highlighted. The command for building switches in dialog boxes takes the format:
*s <x-origin 1> <y-origin 1> <spacing> <#> <item1> ....<itemN> <symbol>The <#> parameter defines the number of corresponding switches. The origin parameters define the coordinate positions of the switch circles. The <symbol> parameter defines the symbol for the switch value. By selecting the first switch option, the corresponding symbol will be given a value of 0. Selecting the second switch updates the symbol to be one, and so on. The <spacing> parameter is used to set the distance between the toggle boxes in the vertical dimension. From an application point of view, symbol values set with switches are used within macros for defining branching points or parameter values. If that symbol has not yet been defined, then a new user symbol is created and defined to have a zero value. When the dialog box is first drawn, the switch circle corresponding to the current value of <symbol> is highlighted. Note that only one circle per switch command can be highlighted. When another circle is selected, the previous one loses the highlight and the new circle becomes highlighted. The contents of < item 1 >...< item N > will be the text prompts at the circles.
Toggles operate much like switches but they take up less space within the dialog box. We have chosen to use toggles instead of switches in instances where the "buried" choices are generally obvious. The command for building toggles in dialog boxes takes the format:
*t <x-origin> <y-origin> <length> <#> <text 1> <text 2> <symbol>The origin parameters are used to place the toggle using character cell units. The length parameter is the width of the toggle in character cell units. Since the actual toggle does not contain any text, the parameters <text 1> and <text 2> can be blank. The <#> parameter defines the number of toggle options, which is usually 2 since toggles can have only on/off states. The <symbol> parameter is the reserved or user symbol used for storing the current value of the toggle. From an applications point of view, symbol values set with toggles are used within macros for defining branching points. In addition, toggles have applications for telling the user the current state of Yes/No symbols. For example, a symbol value for drwbox is either 0 or 1, depending whether you want a box around your spectrum to be drawn. When the dialog box is first drawn, the toggle option corresponding to the current value of <symbol> is displayed. Like data fields, there is no text prompt outside of the toggle contents. The *c command is often used to put text near the toggle for extra information.
Buttons are very similar to toggles and switches in that they update symbol values. Buttons differ, however, in that they all update the reserved symbol called button and then exit a dialog box. A dialog box that doesn't contain a button cannot be exited! The command for placing a button within a dialog box is:
*b <x-origin> <y-origin> <length> <text> <value>The origin parameters are used to place a button. The <length> parameter defines the length of the button box. The <text> parameter defines the button text and the <value> parameter defines the value of the button reserved symbol if that button option is selected. In most cases, buttons are used for branching purposes within macro routines. The most common use of buttons is the OK/Cancel choice presented in many dialog boxes. By convention, buttons that have the <text> argument "CANCEL" always have the <value> argument set to zero, while buttons with the <text> argument "OK" always have the <value> argument set to one. Additionally, the text in the Cancel button will appear red. This is because Felix treats two keys on the keyboard as if they were dialog box buttons. When a dialog box is displayed, the <Esc> key allows you to exit the dialog box, and sets button to zero. Likewise, the <Enter> key allows you to exit the dialog box, and sets button to one.
Pulldowns (combo boxes) are very similar to toggles, except that selecting a pulldown shows all valid choices at once, whereas a toggle only shows one choice at a time. Clicking a pulldown with the mouse, activates a vertical list of all choices. Pulldowns are preferred over toggles when the set of all choices is not obvious. For example, a Yes/No choice is ideal for toggles, while a Points/PPM/Hertz/None choice is better suited for a pulldown:
*p <x-origin> <y-origin> <length> <#> <text 1>...<text n> <symbol>Some special widgets are available which take advantage of the Motif widget set and which also to make it easier for the user to create some of their own menus. The file-open widget is such a widget:
*o <x-origin> <yorigin> <width> <height><x-origin> and <y-origin> set the position of this widget in the dialog box. The <width> and <height> parameters set the width and height of the widget. <# lines> sets the number of files to display inside the list box contained within the file-open widget.
<# lines> <extension> <dir> <filename>
*o 2 2 40 5 5 &mytype &newpfx newfilwhere &mytpe is defined to be *.mat and &newpfx is the directory where the matrix files are to be searched in.
An example helps to illustrate the usage and syntax. The following two lines come from the 1D PLOT GENERAL PARAMETERS dialog box. They control automatic drawing of annotations onto the current plot:
*t 20 9 12 2 `No' `Yes' pltann *f 20 10 12 c annfil (de:pltann.eq.1)The first line defines a No/yes toggle to control the symbol pltann, the reserved symbol for drawing annotations on plots. The second line defines a field where the user can enter the name of the annotation file into the symbol annfil. The last portion of the line contains the dependency formula. It states that this field is only selectable when the symbol pltann has the value 1.
Another example from the same dialog box controls the selectability of the field for the 1D peak entity:
*f 20 6 12 c picent (de:drwpks.gt.0)This dependency states that the 1D peak entity name is only selectable when the drwpks symbol has a value greater than zero.
The formal syntax of the field dependency parameter is as follows. The parentheses and the leading "de:" are required, and define this parameter to be a dependency descriptor. The rest of the descriptor must be of the form: <symbol>.<relation>.<value>; this specifies the name of one symbol, one of the arithmetic relations (for exqample, eq, ne, lt, gt, le, or ge), and one numeric value. The field is selectable only when the stated relation is true. Note that a field can have as many dependency descriptors, which are separated by or/and boolean relationships. the following is such an example:
(de:usedef.eq.0.or.method.gt.1)
Another example from the same dialog box illustrates immediate exits via a pulldown:
*p 20 3 12 6 `None' `Points' `Hertz' `PPM' `Seconds' `1/cm' axtype (ex:2)This exit descriptor states that the dialog box should immediately exit with button set to 2 whenever the symbol axtype is changed by this pulldown.
The formal syntax of the immediate exit parameter requires that the parentheses and the leading "ex:" are present, and define this parameter to be an exit descriptor. The rest of the descriptor must be of the form: <value>. This specifies the numeric value to be given to the button symbol. This tells the macro that invoked the dialog box the precise exit method activated.
In earlier versions of Felix, the names of the menu interface files tended to be very cryptic, so that the manual required an explicit "road map" to help advanced users find their way around. The map provided a rough outline of how the interface interacted with the macro files, but was limited in its practical usefulness.
Felix now has a utility that eliminates the need for a "road map" entirely. There is a reserved symbol that facilitates the generation of diagnostic information about every macro, menu, and dialog box invoked while the program is being run. This reserved symbol is called verify, and it has three acceptable values. Its value (which can be 0, 1, or 2) specifies the type of information to be provided.
When verify is zero, no verification takes place and Felix runs normally. If verify is set to one:
def verify 1brief diagnostics are printed to the text frame. Specifically, every time a menu interface file is invoked, the full filename is printed in the text frame. Thus, when a macro is executed, or a menu or dialog box appears on the screen, the filename of that macro, menu, or dialog box is printed in the textframe. This gives a concise trail of exactly what files are being accessed for any operation that can be selected from the interface.
When verify is set to 2, the program gives even more diagnostic information. In addition to the level one filename information, level two verification also prints out every single FCL command as it is about to be executed. This allows the advanced user to see the complete literal text of each command that Felix performs as it is encountered. This is very useful for debugging new macros or altered menu interface macros. In fact, if you choose the "parent text" frame configuration and redirect Felix output to a file, you can capture the actual stream of Felix commands that are executed to a file and then use that to construct a new macro. Also be aware that this mode can slow down command execution, especially if a macro containing long command lines is used.