The FELIX graphical user interface (GUI) contains a variety of interactive menu bars, pulldowns, and control panels that simplify data analysis and processing. Because the GUI consists of a set of FELIX macros that use specific commands to build and display graphical menus, you can easily modify it. To customize the GUI to meet the needs of your laboratory, edit the macros provided, or write your own.
Before developing your own menus, you first need to become familiar with the commands for menu interaction. The FELIX menu components can be divided into two separate categories: menu items and control panels. Menu components are described in detail in this section.
FELIX menus contain items that, when selected, execute commands in macros. Menu-type items can be displayed as horizontal menu bars, vertical pulldowns, or icons. Menu items are selected by moving the cursor onto the desired item and clicking the primary mouse button.
The second category of menu components includes control panels; i.e., dialog boxes. Control panels are separate windows that can be placed anywhere on the screen.
When FELIX starts, it looks for a file called root.mot to display items on the menu bar and pulldowns. The .mot file(s) must be present in one of the current menu directories (defined by the symbol motpfx). The syntax for a .mot file is:
mode item_name mnemonic accelerator accelerator_text call_ back call_back_data filename
mode can have different values depending on the type of menu being defined. A list of modes follows.
The menubar mode is for the items displayed on the menu bar itself. Here is an example of the use of the menubar mode:
menubar File F NULL NULL NULL NULL file.mot
where File is the name of the item that appears on the menu bar; F is the hot key that is used for the command (which is underlined on the menu bar); and file.mot is the name of the file that contains the items listed under the File pulldown.
The popup mode is used when an item in the menu bar has a cascading menu attached to it. The following is an example for the use of this mode:
popup "Plottype" t NULL NULL "view Plottype" NULL plot- type.mot
where "Plottype" is the text that appears on the pulldown or cascading menu; t is the hot key; "view Plottype" is text that is given for this menu and is just for your reference (it is not used); and plottype.mot is the name of the file that contains the items to appear on the cascading menu.
The separator mode draws a line to separate groups of related commands commands in a pulldown or cascading menu; for example:
separator separator NULL NULL NULL NULL NULL NULL
where separator is the text for the separator name. This can be any text you desire.
The toggle mode places a toggle into a pulldown or cascading menu; for example:
toggle "Draw Peaks" D Ctrl<Key>k Ctrl+k "ex drawpeaks" NULL pksdrw
where "Draw Peaks" is the label for the toggle that appears on the menu; D is the hot key; Ctrl<Key>k is the accelerator that is bound to this menu item; Ctrl+k is the text that appears 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 when its accelerator or hot key is pressed; and pksdrw is the name of the symbol that is updated when the state of the toggle is changed.
The item mode is used when you want to execute the call-back without any cascading menus. It has the following general format:
where LABEL is the text that appears on the menu; HOTKEY is the hot key for this menu item; ACCELKEY is the accelerator; CALLBACK is the command that is called when this menu item is selected. CBCONTROL is a flag that controls how many times the callback is excuted if it is a table menu, and DEPEND is a symbol that controls whether this item is to be displayed (when DEPEND is not 0) or to be invisible (when DEPEND is 0).
The keypad mode is used to define actions that are performed when you press the keypad keys; for example:
keypad NULL NULL NULL NULL "exm keypad" NULL NULL
where "exm keypad" is the command that is called when you press the keypad buttons.
The mouser mode is used to define the popup menu (called context or shortcut menu) that appears when the right mouse button is pressed; for example:
mouser NULL NULL NULL NULL NULL NULL mouser.mot
where mouser.mot defines the menu items that comprise the right-mouse menu.
The mousem mode is used to define the action performed when you press the middle mouse button; for example:
mousem NULL NULL NULL NULL "exm cursorval 4" NULL NULL
where "exm cursorval 4" is the call-back that is called when you press the middle mouse button when the cursor is inside a frame.
The file used to display icons on the icon bar is icons.mot. The icon file(s) must be present in one of the current menu directories (defined by the symbols icopfx). The following is the syntax for the icons.mot file:
mode filename call_back ballon_help_text param1 param2 param3 param4
where mode can be one of the following.
The icon mode is used to display the icons in the icon bar. ;. It has the following general format:
where ICONFILE is the icon file that contains the 16 x 15 pixel 16-color bitmap graphic for the icon; CALLBACK is the command that gets called when you select this icon; TOOLTEXT TOOLTEXT is the explanation of the command than appears on the status bar when the cursor is placed above the icon; CBCONTROL is a flag that controls how many times the command is excuted if it is a table menu, DEPEND is a symbol that controls whether this item is to be displayed (when DEPEND is not 0) or to be invisible (when DEPEND is 0).
The separator mode is used to separate the icons; for example:
separator separator NULL NULL NULL NULL NULL NULL
Parameters 1-4 are currently not in use.
The option mode is used to place a combo box on the icon bar; for example:
option plottyp.mnu "ex plottype 0" "plottype" plottyp NULL NULL NULL
where plottype.mnu is the menu file that contains the text to display on the popup menu; "ex plottype 0" is the call-back that is called when this popup is activated; "plottype" is reserved for balloon help but is not currently displayed; plottyp is the symbol that is changed when you select a different item on the popup.
There are many applications in NMR processing where you need to enter information, such as filenames and various processing parameters. For defining this information from within the FELIX GUI environment, you can create customized control panels (dialog boxes) from ASCII text files.
Control panels are separate windows. They can be placed anywhere on the screen. When opened, a control panel appears at the same coordinates where the previous control panel was placed.
Within the file that defines a control panel are two types of commands:
There are two different control panels, modal and modeless. A modal control panel freezes the FELIX main window until you close the control panel. A modeless control panel, however, allows you to access the main window without closing the contro panel.
To open a modal control panel, issue the following command statement with appropriate arguments:
mnu p menu x_origin y_origin
mnu p keywords in the statement tells FELIX to read a menu file containing a control-panel definition. The menu argument is the name of a menu file that 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.
In previous versions of FELIX, x_origin and y_origin was used to define the position of the upper left corner of the box in character units. In FELIX, this is ignored.
For example, the command line:
mnu p xopen 20 4
opens a control panel defined by a menu file xopen.mnu. See the following section for details about menu files.
A modal control panel is closed when you click one of its buttons, or the close button [x] on the upper-right corner of the panel.
To open a modeless control panel, issue the following command statement with appropriate arguments:
mnu a menu x_origin y_origin
A menu file that defines a modeless control panel has almost identical formats as used in a modal control panel, except for the following requirements:
An example is during 2D processing, when D1 has been Fourier tranformed and you choose to phase D1 interactively. The control panel for phasing is modeless; by default the macro would go on for D2 processing without waiting for you to finish the D1 phasing. To hold the macro execution flow, you can add the following command in the macro next to the "mnu a" command:
wai -1 menu
This will force FELIX to hold the macro execution until the control panel defined by menu file has been closed.
mnu remove menu
The macro file ez1dtransform.mac is a good example that allows you to display a modeless control panel for real-time phasing. The corresponding menu file is rtphase.mnu. Most of the input controls trigger a callback macro rtphase.mac. To find those files, see the following section Find your way through the menu interface.
A menu file defines the components in a control panel and their layout and actions to trigger. A full list of the file xopen.mnu, and the control panel it creates, is shown below.
c**xopen.mnu
23 40
*h 1 1 14 `OPEN FILE'
*o 2 2 40 5 5 &mytype&ftype &newpfx&ftype new- fil(de:ftype.ge.0)
*c 3 19 5 `File Type'
*p 12 19 16 7 `Matrix (*.mat)' `Felix Data (*.dat)' `DBA (*.dba)' `Insight II 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
This file creates the following control panel:
The first line that starts with "c**" defines the name of the file and is optional. The second line defines the dimension of the control panel but it is ignored by FELIX. Instead, the dimension of the control panel is automatically optimized by FELIX.
Each of the remaining lines defines a control or a group of controls in the control panel, and optionally the dependency, exit status, and callback macro associated with the control. The formats for such commands are listed below.
These are commands that provide the graphical information needed to design the control panel.
The *h command in the control-panel file specifies the header text. The format of this command is:
*h x_origin y_origin number_of_characters `header text'
The header text must be enclosed in single quotes. By default, the header is left-justified within the control panel and thus the parameters x-origin and y-origin are ignored. Header text may contain characters or use symbol substitution for customizing the header.
The *c command in a control-panel file is used to place text. Text in control panels is most commonly used for labeling the required input for entry boxes. (The command that defines an entry box is not coupled to the text that labels it.) The format of a character string command within a control-panel file is:
*c x_origin y_origin number_of_characters descriptor_text
Using the *c command, character strings can be placed throughout the control panel. Character strings are limited to 64 characters and must be enclosed in single quotes.
To enhance the appearance of control panels, you may uses highlighted rectangles. These rectangles are often used to group related switches or entry boxes. Within a control panel definition, these rectangles are defined as:
*x x_origin y_origin width height text
The x_origin and y_origin parameters define the bottom left corner of the highlighted rectangle. The width and height parameters define the rectangle size in character units. text is an optional string to be placed on the left top line of the highlighted box.
Input commands define information to be input to the program. These commands include functions for entering and updating symbol values, setting the value of the reserved symbol button, and choosing between switches and toggles.
To generate an edit box for data input, the *f command is placed within the control-panel 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 box using character units. The length defines the length of the box in character units. The type defines what the edit box expects. A c means a character must be input into the edit box, an i means an integer, and an r means a real number.
The symbol can be either a reserved symbol name or a user symbol name. In either case, the current value of the symbol is displayed in the box. 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.
A list box is an object that appears within control panels 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 control-panel file. This 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 units. The width and height define the width and height of the list box in character units. The list_file is the name of the ASCII (text) file whose contents are to appear in the list box. select is the name of the symbol that defines which line is selected from the list. The value of select is 1 if the first line in the list is selected, 2 if the second line is selected, and so on. The symbol 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 be test.mac after the "test.mac" line is selected from the list box. From list boxes, you therefore have two means of getting output: select defines the number of the line in the list box that was selected, and symbol represents its actual alphanumeric value. When exiting from a list box, either of these values can be used to make a later decision.
List boxes are especially useful for selecting files or matrices to be read and displayed. The text file named by list_file may be of virtually any form or origin. In many places in the menu interface, FELIX shows a list box of filenames. To do this, FELIX issues a command to obtain a directory listing and store it in a file, then shows the contents of that file in the list box. You could just as easily build a file using the opn, put, and cls commands.
A variable list box is useful when you want to get only a certain word from the selected line in a list box. To display a variable list box the *v command is defined in the following format:
*v x_origin y_origin width height list_file symbol1 num_of_ word symbol2
All the parameters are the same as for a regular list box (see the previous section), except that a value num_of_word is added between symbol1 and symbol2 to define which word from the select line is to be received by symbol2. For example, if num_of_word is 2, the selected line is "H104 N104", then symbol2 received a value of "N104".
Radio buttons (or switches) are used within control panels for setting the values of symbols that integer numbers. By convention, a radio-button option is selected when its circle is highlighted. The command for building switches in control panels takes the format:
*s x_origin_1 y_origin_1 spacing # item1 ... itemN symbol
The # parameter defines the number of radio buttons. The origins define the coordinate positions of the radio buttons. symbol defines the symbol for the switch value. If you select the first radio button, the symbol is 0. Selecting the second radio button sets the symbol to one, and so on. The spacing parameter sets the vertical distance between the radio buttons. 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 control panel is first drawn, the radio button corresponding to the current value of the symbol is highlighted. Only one radio button per switch can be highlighted. When another radio button is selected, the previous one loses the highlight and the new one becomes highlighted. The contents of item1 ... itemN are the text prompts for the radio buttons.
Toggles operate much like switches, but they can be only on or off, and take up less space within the control panel. The command for making toggles in control panels takes the format:
*t x_origin y_origin length # text_1 text_2 symbol
The origins are used to place the toggle using character units. The length is the width of the toggle in character units and is obsolete. Since the actual toggle does not contain any text, text_1 and text_2 are obsolete and can be blank. The # defines the number of toggle options, which is usually 2, since toggles can be only on or off. The symbol 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 branch points. In addition, toggles have applications for telling the user the current state of yes-or-no symbols. For example, the value for the drwbox symbol is either 0 or 1, depending on whether you want a box around your spectrum to be drawn.
When the control panel is first drawn, the toggle value corresponding to the current value of symbol is displayed. As with entry boxes, there is no text prompt outside the toggle. The *c command is often used to put text near the toggle to supply appropriate information.
Buttons are similar to toggles and switches, in that they change symbol values. Buttons differ, however, in that they all change the reserved symbol called button and then exit a control panel. (A control panel that doesn't contain a button cannot be exited!) Buttons are usually used for branching within macro routines. The most common use of buttons is the OK/Cancel choice presented on many control panels.
The command for placing a button within a control panel is:
*b x_origin y_origin length text value
*bt x_origin y_origin length text value
The origins are used to place the button. The length defines the length of the button. The height of the button is 1.3 times of a character height if "*b" is issued, or 1.0 times of a character height if "*bt" is issued. The text is the button text, and the value defines the value of the button reserved symbol when that button is selected.
Buttons are usually used for branching within macro routines. The most common use of buttons is the OK/Cancel choice presented on many control panels. By convention, buttons that have text = CANCEL always set the value argument to zero, and buttons with text = OK always sey the value argument to one. When the value is set to zero, FELIX automatically ignores the changes made to the values of all symbols that are relevant to this control panel. In effect, when Cancel button is pressed, no change is made to the contents in the control panel.
Pulldowns (combo boxes) are very similar to list boxes, except that only the current selection is displayed, not all valid choices at once. Clicking a combo box with the cursor, opens a vertical list of all choices.
or, instead of listing all the options in the command, use a text file containing all the options:
x_origin and y_origin set the left position of this box. length sets the width of the box. num_options is the total number of options. . height is height of the list box when expanded. text_1 ... text_N are the option lines, each enclosed by single quotation marks. Filename is the name of the text file that contains the options. symbol is the symbol that receives the sequential number of the selected option: 0 for the first line, 1 for the second and so on. symbol_line is the symbol that receives the character string of the selected option. num_lines_to_display is an optional value that sets the number of the first options to be displayed. By default all options are displayed. If num_lines_to_display is smaller than num_options, only the the num_lines_to_display options are displayed. Sometimes this is useful when the number of options to display has to be determined in run-time.
File-open combo is a special combination of combo box, list and edit boxes that makes it easier for you to browse and select a folder and/or a file.
x_origin and y_origin set the position of this tool in the control panel. The width and height set the width and height of the tool. #_lines is an obsolete parameter and is ignored. The height determines the number of files to display inside the list box contained within the file-open tool. extension sets the default type of files to be searched for in the directory. dir is the directory to be searched, and filename is the name of the file that is returned when you select a file from the list.
A slider combo comes with a horizontal (or vertical) adjustable "value bar" plus three edit boxes that displays the minimum, maximum and current values. A slider combo is usually used in a modeless control panel for real-time display of a spectrum while interactively adjusting the values of one or more symbols.
A slider combo is created using the following command:
x_origin and y_origin set the upper left position of the slider in character units, and length defines the length of the slider in character units. minimum and maximum define the minimum and maximum values of the slider. The absolute value of decimal tells FELIX how many decimal places to display for the slider position. If decimal > 0, a normal float number is displayed. If decimal < 0, scientific notation is used to display the number. orientation determines the orientation of the slider. When the orientation value is 1, the slider is drawn horizontally; otherwise it is drawn vertically. (For FELIX only horizontal slider can be displayed). drag_mode tells the program when to call the call back macro if provided (see following section for details about callback macros): 0 means to call the callback macro only when the mouse button is released, otherwise the callback macro is called whenever the value of the slider changes. symbol is the symbol that receives the slider value. The label is the text that appears above the slider.
edit_width is an optional parameter that defines the width of the three edit boxes in character units. The default value is six. You can change the minimum, maximum or current value by directly typing in the corresponding edit box followed by <Enter>, and the slider shifts to reflect your changes.
All the components in a control panel can be deactivated (grayed out) depending on a situation defined by you. For example, the selectability of any entry box in a control panel can be made dependent on the value of another symbol. By default, an entry box is always selectable. However, you can define a dependency for the box, so that it is selectable and editable only when some symbol value meets a specific criterion. For example, the entry box for the name of an annotation file can be made dependent on the symbol that controls the drawing of annotations, so that the user can change the annotation filename only when annotation-drawing is turned on.
An example helps to illustrate the usage and syntax. The following two lines come from the FELIX macro that specifies the 1D PLOT GENERAL PARAMETERS control panel. They control automatic drawing of annotations in 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 yes-or-no toggle to control the symbol pltann, the reserved symbol for drawing annotations on plots. The second line defines an entry box where the user can enter the name of the annotation file into the symbol annfil. The last portion of the second line contains the dependency formula, which states that this box is selectable only when pltann is 1; that is, when the toggle is turned on.
Another example from the same control-panel macro controls the selectability of the entry box 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 selectable only when drwpks is greater than zero.
The formal syntax for specifying entry-box dependency requires the following:
(de:usedef.eq.0.or.method.gt.1)
In addition to exiting a control panel via the Cancel or OK button, you may also trigger an immediate exit from a control panel when a pulldown is selected. This is useful for taking immediate action as soon as a pulldown is selected, without having to wait until the user clicks a button.
Another example from the same control-panel macro 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 control panel should immediately exit with button set to 2 whenever the symbol axtype is changed by this pulldown.
The formal syntax for immediate exit requires that the parentheses and the leading ex: be present and define this parameter as 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 and tells the macro that invoked the control panel the precise exit method that was activated.
Sometimes you may want the change in a control to activate the execution of a certain macro immediately. This is especially useful when you display a modeless control panel containing a slider control, and you want to redraw the spectrum whenever you move the slider.
For example, the control panel for 1D real-time phasing has the following command that defines a slider for you to adjust the 0-order phase parameter:
*a 1 2 40 rtpmin0 rtpmax0 &rtpdec0 0 1 rtp0 `0 Order' "exm rtphase 1"
The last parameter "exm rtphase 1" forces the macro rtphase.mac to be executed with a parameter "1" whenever the you move the slider.
As mentioned, the FELIX GUI is built from macros, with the assistance of menus and control panels. Every facet of the functioning of this interface is explicitly contained in these ASCII text files. This allows the GUI to be altered and bugs to be fixed, without the need for a new version of FELIX.
However, this feature necessarily involves a huge number of files. There are literally hundreds of macros, menus, and control-panel files. This section is designed to help you find your way through this maze of files.
FELIX has a reserved symbol that facilitates the generation of diagnostic information about every macro, menu, and control panel invoked while the program is being run. This reserved symbol (verify) has three acceptable values (0, 1, or 2), which specify the type of information to be provided.
When verify is zero (the default value), no verification takes place and FELIX runs normally. If you select the menu item Preference/Macro Debug, and next check the option of Show macro names, verify is set to 1. Then, every time a menu interface file (macro, menu, or control panel) is invoked, the full filename is shown in the output window. This shows you exactly what files are being accessed for every operation that is selected from the interface.
If you select the menu item Preference/Macro Debug, and next check the option of Show all details, this sets verify to 2. FELIX gives even more diagnostic information. In addition to the filename, each FCL command is printed in the output window as it is about to be executed. This allows advanced users to see the complete literal text of each command that FELIX performs and is 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 file to construct a new macro. However, be aware that this activity can slow down command execution, especially if a macro containing long command lines is used.