Motif-Based MAINSAIL Tools Reference Guide, Chapter 3

Motif-Based MAINSAIL Tools Reference Guide, Chapter 3

previous next top contents index framed top this page unframed

3. General Information

3.1. Installing the GUI

Currently, in order to install the GUI, you must have the X and Motif header files (.h files) installed on your system; the C portions of the mainsam bootstrap are shipped as source files. XIDAK may start shipping this part of the bootstrap as an object file in some future release of MAINSAIL, in which case you will need only the dynamic libraries (on operating systems that provide dynamic libraries) that support X and Motif.

3.2. Customizing the GUI

The GUI interface can be configured by setting two different kinds of parameters: X- and Motif-specific parameters, and MAINSAIL-specific parameters. The X and Motif parameters are described in Appendix B; the MAINSAIL parameters are described here.

It is not usually necessary to customize the GUI using the MAINSAIL-specific parameters, except for the change described in Section 3.5, which is advisable once you become accustomed to the GUI. Otherwise, the defaults for the GUI options have been chosen to be reasonable. Follow the steps below only if you are dissatisfied with the default behavior.

MAINEDIT (which is embedded in the GUI) is configured according to information in the parameter file (in the 16.20 release, v1620.prm) and the eparms (“editor parameters”) file. These files are discussed in detail in the Chapter 2 of the MAINEDIT User's Guide (Chapter 28 of the MAINSAIL Language Manual contains additional information on the v1620.prm file, which can be used by many applications).

A sample v1620.prm file is shipped with each MAINSAIL system. The actual parameters in this file are commented out; if you wish to change MAINSAIL-specific parameters:

Copy the v1620.prm file from the MAINSAIL directory to your home directory.
Edit the file with your favorite text editor.
You can set any of the parameters as desired, if you do not like the default settings. Remove the comment character # in front of the parameter and specify the desired value for the parameter. The $MAINED and $MAINEDIT group parameters are described in Appendix C and in Section 1.2.2 of the MAINED User's Guide and Section 2.1, and the $MAINDEBUG group parameters are described in Section 4.32.3 of the MAINDEBUG User's Guide. The $GUIDBG parameters are duplicates of some from the $MAINEDIT and $MAINDEBUG groups; they override the parameters from those groups when the GUI debugger is in use.

3.3. Starting the GUI

In order to run the GUI, you must first be running the X Window System. It is assumed that you know how to do this; if not, contact your system manager or whoever maintains the X Window System at your site. Once you have X up and running, you must be able to invoke MAINSAIL from it (presumably in a terminal emulator window). Again, contact a knowledgeable person at your site if you are uncertain how to do this. Invoke the GUI by invoking the MODULE MTFEXE (e.g., at the MAINEX * prompt).

3.4. Starting the GUI under Solaris

On Solaris, the X and Motif dynamic libraries reside someplace other than /usr/lib by default. If your X and Motif libraries are installed in the standard places, you need to ensure that the following directories are included in your LD_LIBRARY_PATH environment variable:

/usr/openwin/lib/opt/SUNWmotif/lib

or, on some installations of Solaris 2.5 or later:

/usr/openwin/lib/usr/dt/lib

e.g., by issuing the command:

% setenv LD_LIBRARY_PATH /usr/openwin/lib:/opt/SUNWmotif/lib<eol>

or:

% setenv LD_LIBRARY_PATH /usr/openwin/lib:/usr/dt/lib<eol>

Otherwise, Motif applications (including MAINSAIL's mainsam bootstrap) will not run.

In addition, on SOLRS, you have to set the following environment variables properly to get key bindings to work correctly for remote X/Motif clients:

setenv MOTIFHOME /opt/SUNWmotifsetenv OPENWINHOME /usr/openwinsetenv XMBINDDIR $MOTIFHOME/lib/bindingssetenv XFILESEARCHPATH $MOTIFHOME/lib/%T/%N%S

The values shown are correct for a typical installation under Solaris 2.3. Values at your site may be different.

3.5. Making the GUI Debugger the Default

Normally, you invoke the GUI by invoking the MODULE MTFEXE or by issuing the guidebug response to the Error response prompt. However, the debugger can also gain control directly from your program because your program called $debugExec, and your program may not have been invoked from MTFEXE. In this case, you get the line-oriented debugger by default rather than the GUI debugger.

To make the GUI debugger the default, so that it is the interface used when the debugger is initialized by a call to $debugExec, you need to make a MODULE name association between the dummy name GUIDBG and the MODULE name MTFDBG. This association can be made interactively with the MAINEX SETMODULE subcommand (typically put in the $MAINEX group of your parameters file, e.g., v1620.prm):

SETMODULE GUIDBG mtfdbg

or programmatically by calling the PROCEDURE setModName:

setModName("GUIDBG","mtfdbg")

3.6. Basic Concepts

When you invoke the GUI it creates a Motif window (the “main window”). The main window contains:

A menu bar at the top.
Command buttons (each labeled with one or two characters) on the left.
A display area, surrounded by a bold line. The topmost line of the display area is used for status messages, and is called the “message line”.
The debuggable PROCEDURE count and debugger's command context at the lower left.

Figure 3–1. The Main Window

As you interact with the debugger, the display area is divided into a number of “display windows”. These display windows are not the same as Motif windows. All display windows appear within the display area of the single Motif window. The term “window” in this document often means a display window, not a Motif window, depending on context.

The display area is organized as follows for the debugger:

The CMDLOG window initially appears at the top of the display area. It shows output from interaction with MAINSAIL. If your program prompts for input, you will enter input in this window.
Other windows are created automatically as needed. The debugger creates new windows to display source code. You may also create new windows to view a file, or you may create a new window and enter new text into it with the text editor. These windows may sometimes obscure each other or the CMDLOG window, but you can always bring any buffer into a visible window using File->Edit buffer....

Each window displays the contents of a “buffer”, typically the contents of a source file (except for CMDLOG). The debugger brings new windows into the bottom of the display area. There may be more buffers than windows; e.g., you might have ten buffers, of which only five are currently visible in windows.

Each window in the display area begins with a “status” line that shows:

The name of the editor front end (e.g., SIMPED) that is accepting commands for that window.
The position (pageNumber.lineNumber) within the buffer of the first line displayed in the window.
If the buffer in the window is read-only, the letters RO.
The name of the buffer displayed in the window.

Depending on which editor front end is in control of the window, other information may be displayed. For example, the MAINED front end displays a mode letter to indicate the current mode (I for “Insert”, C for “Command”, O for “Overstrike”, E for “Escape”; see the MAINEDIT User's Guide).

3.7. GUI Commands

GUI commands are entered by selecting an item from one of the menus in the menu bar, or by moving the cursor and using the mouse buttons. The front ends MAINED and MAINVI also have modes where most keystrokes are interpreted as commands instead of text to be inserted; SIMPED does not have such a mode.

The command buttons at the left of the display area are shortcuts for the most frequently used commands (they are labeled with the accelerators for the commands, without the Meta prefix). Instead of selecting a menu item, you can issue the command by clicking the corresponding button. The buttons are shortcuts for a mixture of editing commands and debugging commands (see Sections 3.8 and 3.9).

3.7.1. Issuing Commands

To open a menu, depress the Select mouse button on a menu name. Release on a menu item to select it. If a menu item has an arrow at the right edge of a menu, moving the mouse to the arrow opens its submenu. The keyboard shortcut (also called an “accelerator”) for a menu item appears at the right of the item (if the item has an accelerator; not all menu items do). The keyboard shortcut for a command is usually the same as the character-based MAINDEBUG command but with the META key depressed for all keystrokes. You must determine which key is the META key on your terminal; on Sun keyboards it is either of the “diamond” keys beside the space bar, but on other keyboards it may be labeled META or ALT. On some keyboards, there is no META key by default, and you must modify your X keymap to establish one if you want to use the keyboard shortcuts.

Note that there are three ways to issue some commands:

Use the mouse to select the command from a menu in the menu bar as described above.
Click the corresponding command button on the left side of the window.
Type the META keyboard shortcut. Some commands can take numeric arguments when issued in this form. An optional numeric argument is indicated by {n} in a menu item's keyboard shortcut. Type the digits while the META key is depressed.

If the name of the menu item ends with “...”, the item has an associated dialog window which prompts for information necessary to perform the command. Choosing the item invokes the dialog window.

3.7.2. Dialog Windows

Dialog windows display information and ask you for commands necessary to complete their tasks. A dialog window usually retains information from the last time you used it. The following buttons are used with the indicated standard meanings in many dialog windows:

OK: Perform the window's action and then close the window.
Apply: Perform the window's action and leave the window open.
Clear: Clear the contents of the window's primary input field so you can enter a new value.
Cancel: Close the window without performing the window's action.
Close: Close the window (actions in this window are performed as soon as you specify them).
Update: Update the dialog contents, in case they have become out of date; this can happen if the dialog is visible during some operation that causes its contents to get out of date, since some operations do not update the dialog.

Menu items are described below in the order in which they appear in the menu bar from left to right. Items within a menu are described in the order in which they appear in the menu from top to bottom. Each menu item is identified with a header of the form:

Menu->Item

or:

Menu->Item->Subitem

For example, File->Kill windows... means the Kill windows... item in the File menu. Edit->Go to->Next page means the Next page item in the Go to submenu of the Edit menu.

3.8. Editing Commands

3.8.1. Changing the Current Buffer

At any time, the buffer that contains the cursor is the “current” buffer; most commands take place with respect to that buffer. The current buffer is displayed in the “current window”. To make a buffer the current buffer, click the Select mouse button (usually the leftmost mouse button) in the window that displays the buffer. The cursor is placed at the location where you clicked (but not beyond the last line of the buffer). You can also click the Select mouse button on a window's status line to make it the current window and to put the cursor at the position it last occupied in the buffer.

3.8.2. Resizing Windows

You can resize windows by using the Select mouse button to drag a status line to the desired location. A status line cannot be dragged past another status line.

3.8.3. Scrolling

All scrollbars have the standard Motif behavior:

Dragging the position slider in the scrollbar scrolls in the direction of the drag.
Clicking the Select mouse button in the scrollbar above the position slider scrolls back 80% of the window; clicking below the position slider scrolls forward 80% of the window.
Clicking the Select mouse button on the arrow at the top of the scrollbar scrolls back one line; clicking on the arrow at the bottom scrolls forward one line.
Clicking the Menu mouse button (usually the middle mouse button) in the scrollbar moves to a position in the buffer proportional to the position of the pointer in the scrollbar; e.g., to go to the middle of the buffer, point to the middle of the scrollbar and click the Menu mouse button.
Pressing the CONTROL key and clicking the Select mouse button in the scrollbar toggles between the beginning of the buffer and the end of the buffer.

3.8.4. Selecting Text

To select text in a window, drag over the text with the Select mouse button. To select a word, double-click the word with the Select mouse button. Word selection selects MAINSAIL identifiers and (most) constants that consist of contiguous digits, alphabetic characters, and single quotes. Triple-clicking selects the entire current line, and quadruple-clicking the entire windowful of text.

To extend a selection, click the Select button with the SHIFT key held down. The text between the current selection and the cursor will be selected (in addition to the already selected text).

To “get rid of” a primary selection, click the Select button once (anywhere). This is a useful thing to be able to do, since if there is a primary selection, commands such as Value use the selected text, whereas if there is no selection, such commands prompt for the text.

3.8.5. Typing in `SIMPED`

The only editing facility available in the SIMPED front end other than those on the Edit menu is the inserting of printing characters, and the use of special keys.

Insert printing characters by typing those characters on the keyboard.

The special keys you can use in SIMPED are:

DELETE, BACKSPACE: These keys are synonyms. If the cursor is within the current selection, deletes the current selection; otherwise, deletes the preceding character.
RETURN: Inserts an end-of-line.
Arrow keys: Move one row or column in the specified direction.

Other front ends have an “insert mode” that behaves like SIMPED, but also have other modes in which front-end-specific commands can be entered. See MAINEDIT User's Guide if you are interested.

If the cursor is located within the current selection, the selection is replaced by whatever character you type. Figures 3–2 and 3–3 shows what happens if you select a word (“sentence”) by double-clicking, then type some text to replace it (“line of text”).

Figure 3–2. After Selecting a Word by Double-Clicking on It

Figure 3–3. After Replacing the Selection by Typing

3.8.6. Cutting, Copying, Pasting, and Deleting Text

The Edit menu contains commands for cutting, copying, pasting, and deleting text. These commands usually operate on the selection; see Section 6.2.

3.8.7. Setting Local Options

Each window has a number of options specific to that window (“local options”) that can be set in the Local Options window. To see the options for the current window, select Local options from the File menu. A quick way to open the Local Options window for any window is to click the Custom (usually the rightmost) mouse button on the window's status line.

3.9. Debugging Commands

All menu items except those on the three leftmost menus (File, Edit, and Subcommands) apply only to debugging.

Debugging commands let you open MODULEs and contexts for examination and manipulation by the debugger (the Access menu), manipulate breakpoints (the Breaks menu), find a particular context (the MoveTo menu), examine values and memory (the Show menu), and control the execution of the debugger or the debugged program (the Execution menu).

Typically, you start a debug session by running MTFEXE, then setting some breakpoints in your program, then invoking the program from MTFEXE. You can also invoke the Motif debugger by typing guidebug when your program calls errMsg and issues the Error response prompt.

You can invoke the debugger directly from a program by making a call to $debugExec in your program, but this may invoke the line-oriented debugger rather than the Motif debugger. To ensure that the debugger uses the GUI interface even when you initialize the debugger with a call to $debugExec, follow the steps in Section 3.5.