Button Bar

Many of the Client's basic operations are controlled by the buttons arrayed in the button bar, which by default is displayed above the main window.

These same operations can also be invoked by Client menu options and by keyboard shortcut. The operations are implemented by Client commands, of which there are many more than there are buttons. You can change the default mapping of buttons and hot keys to commands to suit your preference.

The subsections below describe how:

• The buttons may be divided into function categories.
• The position of the main button bar may be changed.
• You can extract the button bar to a window that is external to the Client.
• You can create an extra button bar if you want more than the 15 buttons that the main button bar can accommodate.

Types of buttons

The Client default buttons may be divided by function as follows:

• Page navigation

The Top and Bottom buttons operate on the currently active Audit Trail, Source Code (or Daemon), or Web Buffer tab. Top brings to the top of the page the first line of the current page. Bottom highlights the last line of the current page.

The mappable Client commands that perform the same actions are top and bottom.

• Program execution

The Step, Step Over, and Run buttons advance the Source Code page (or Daemon page) processing position by executing one or more "executable" User Language statements. For more details, see Step, Step Over, Run.

By default, the F5 key is equivalent to the Run button; F4 is equivalent to Step (as is F11); and F10 is equivalent to Step Over.

The Cancel button stops the execution of the current program in the Source Code page. You can cancel the request at any time.

The mappable Client commands that perform these execution actions are step, stepOver, run, and cancel.

• Page clearing

The Clear Audit, Clear Breaks, and Clear Watch buttons remove entirely the contents of the Client's Audit Trail tabbed page, the breakpoints defined in the program being debugged, and the Client's Watch Window.

The mappable Client commands that perform these actions are clearAudit, clearBreaks, and clearWatch.

Positioning the button bar within the Client window

You can change the location of the main button bar from its default (above the main tabs) to either of these other positions in the Client window:

• Immediately below the main tabs (but above the search, tracing, and value displaying controls):

To move the button bar to this position:

1. From the File menu, select Preferences, or use the CTRL-P keyboard shortcut or the preferences command.
2. In the Main Button Bar area of the Preferences dialog box, select the Center option:

The button bar immediately relocates.

• At the very bottom of the Client window:

To move the button bar to this position, select the Bottom option in the Main Button Bar area of the Preferences dialog box.

The mappable Client command that positions the button bar is mainButtonBar.

Launching an external button bar

For your convenience, the location of the button bar is not fixed. In addition to changing its position on the main Client window as described above, you can move the main button bar to a separate window outside the Client application window. You do so in either of the following ways:

• Selecting the Show Main Button Bar in External Window option of the Window menu
• Invoking a button, key, or macro mapped to the openExternalButtonWindow or the buttonBar command

The resulting external Button Bar window shares the characteristics of the other Client external windows. You can close the external window at any time by Client command (closeExternalButtonWindow), by the Exit option of the button bar File menu, or simply by clicking the X button in the upper right corner. In addition, the opened Button Bar window has Dock menu options, as described below.

The buttonBar command has parameter options that let you select where on your desktop to locate the window. You can dock it, stationary, in the top or bottom left corner of the desktop, or you can simply open it, undocked, as with the launching options (menu and command) described above. Also, once opened, the Button Bar window Dock menu has Top, Bottom, and Float options that perform the same functions as the corresponding buttonBar command arguments.

Launching a second button bar

You may open an additional button bar (in the Extra Buttons external window) which can contain as many as 15 buttons. Like the buttons in the main button bar, these extra buttons are mappable in the ui.xml file or via the mapButton command. You launch such an extra button bar by either of the following:

• Selecting the Show Extra Button Bar Window option of the Window menu  
• Invoking a button, key, or macro mapped to the extraButtonBar command

The resulting external Extra Buttons window is just like the external main Button Bar window (described above), and it shares the characteristics of the other Client external windows.

As stated above, you add buttons to the extra button bar by mapping them in the ui.xml file to the commands you want them to execute. The mapping commands are the same as those for the buttons in the main button bar, except the buttons are named extraButton0 through extraButton14. For example, the buttons in the extra button bar shown above result from the following commands:

<mapping command="showAbout" button="extrabutton0" /> <mapping command="step" button="extrabutton1" />  <mapping command="showCommands" button="extrabutton2" />  <mapping command="help" button="extrabutton3" />  <mapping command="manual" button="extrabutton4" />  <mapping command="saveWatch" button="extrabutton5" /> 

You may add your extra buttons to the existing main button bar instead of opening an additional window. For example, the following image shows the extra buttons (defined above) added to the main button bar, which is positioned at the bottom of the Client main window:

To merge extra buttons with those in the main button bar (instead of opening a second button bar), define the mapping commands in ui.xml as above, then do either of the following:

• Select the Extra Buttons checkbox of the Preferences dialog box  
• Invoke a button, key, or macro mapped to an extraButtonBar command that specifies the position parameter main.

If the main and second button bars are open in separate external windows, selecting the Extra Buttons checkbox or invoking an extraButtonBar main command merges all the buttons in the primary external button bar.

Once a merged button bar exists, the extra buttons remain part of the primary button bar if it is subsequently moved to an external window from the Client, or if moved back to the Client from an external window.

To decouple a merged button bar, you can clear the Extra Buttons checkbox. Less directly, you can select Window > Show Extra Button Bar Window; this action simultaneously clears the Extra Buttons checkbox.