Setting up the ui.xml file

Each time the Client is started, it checks for the presence of a ui.xml file in the same folder as the Client executable file itself (the default) or in the folder specified in the Client configuration file. If no such file is located, the Client opens with its default presentation of GUI buttons and their associated commands, and it responds to its default set of hot keys and their associated commands.

If you want to change the Client's default buttons and hot key associations, you must provide in the appropriate folder a ui.xml text file that adheres to the structure described in this section.

Note: You can also define an alternative to the ui.xml file: following the same rules for setting up the ui.xml file, you provide settings in the uimore.xml file that override those in the ui.xml file.

And/or: You can use the mapButton or the mapKey command to reconfigure buttons or hot keys without editing a mapping file.

To set up a ui.xml file:

1. From the Client's File menu, select Edit ui.xml.

An untitled Notepad file is opened for you, along with a prompt to create a ui.xml file. (If a ui.xml file already exists, that file is opened.)

2. In the file, specify or update the mappings tag, the first line in the file.

The top level tag in the ui.xml file is the mappings tag, which has two optional attributes (useDefaults and startUpMacro):

<mappings [useDefaults="true|false"] [startUpMacro="macro"]> 

useDefaults indicates the mode in which the mappings are applied:

useDefaults="true"

tells the Client to apply the ui.xml file mappings after the defaults are set for the buttons and hot keys. In this mode, your mappings are additions or overrides to the existing defaults.

Use this mode if you generally like the defaults but want to make a small number of additions or changes to them.

useDefaults="false"

tells the Client not to set the defaults, just to process the ui.xml file mappings. You start with a "clean slate" and only the settable buttons and hot keys you assign will be available.

Use this mode if you want to completely change the settings from the defaults.

This is the default.

startUpMacro

indicates a macro that is run when the Client starts.

3. Specify or update <mapping> elements for your buttons/keys.

Contained within the <mappings> element are one or more <mapping> elements. Each <mapping> associates a command or macro with a button, a hot key sequence, or both. If it associates a command or macro with a button, it may also specify a modifier for the button.

The <mapping> attributes are described below, after which is a comprehensive example:

command	A double quoted string that contains a Client command, each of which is described in the command reference, and two of which deserve special mention here: The macro command calls a user defined macro The separator keyword creates an inactive button whose only function is to be a visual button separator on a Client button bar The command attribute is required. The quoted command string may include a command parameter or an "in window" prefix if appropriate. Check the individual command description in the command reference. As an example: <mapping command="runUntilVariableChanges %i"  button="button12"/> Note: If a command parameter contains an ampersand (&), you need to XML entity encode it. For example, to map the command set &foo = %i, you specify it like this: <mapping command="set &amp;foo = %i"  button="button14"/>
button	A named button (button0, . . ., button14 for the main button bar, and extrabutton0, . . ., extrabutton14 for an extra button bar). If no button setting is specified, a key setting must be specified.
buttonModifier	A button modifier (Alt or Ctrl). This attribute is optional.
key	One of these keyboard keys: a-z, A-Z, or F2-F12. If no key setting is specified, a button setting must be specified.
keyModifier	A key modifier (alt or ctrl). This attribute is optional.

Note: As with all XML, the element and attribute names are case sensitive. Attribute values, which must be quoted and non-null, are not case sensitive.  

For any given mapping element, you must specify a button or key setting (or both). Here is an example:

<mappings useDefaults="true" startUpMacro="myDefault"> 
   <mapping command="step" button="button0" /> 
   <mapping command="run" button="button1" key="f5" /> 
   <mapping command="cancel" button="button2" /> 
   <mapping command="stepOut" button="button3" /> 
   <mapping command="runWithoutDaemons" button="button4" /> 
   <mapping command="in auditTrail top" button="button5" /> 
   <mapping command="traceValues" button="button6" /> 
   <mapping command="breakOnNextProc" key="9" />
   <mapping command="nextCompileError" key="F2"/> 
   <mapping command="previousCompileError" key="F2" keyModifier="alt"/> 
   <mapping command="macro myMacro" key="Z" keyModifier="ctrl"/>
   <mapping command="openMacroConsole" button="button10"/> 
   <mapping command="closeMacroConsole" button="button11"/>
   <mapping command="showCommands" button="button12" /> 
   <mapping command="help" button="button13" />  
   <mapping command="step" button="button14" /> 
   <mapping command="manual" button="extrabutton0" /> 
   <mapping command="showAbout" button="extrabutton1" />  
   <mapping command="showShortcuts" button="extrabutton2" />
   <mapping command="manual" button="extrabutton3" />
</mappings>  

If you define more than one mapping for the same key or button, the last mapping (closest to the </mappings> end tag) takes precedence.

If you specify a macro, it is assumed to reside in the same folder as the Debugger Client executable file unless you configured a different location.

4. Save, then Exit the file.

If you edited an existing ui.xml file, the updated settings take effect the next time the Client is started.

Button toggle for compilation errors

The following two commands are only meaningful in the context of examining the results of a failed compilation. If the program you are debugging has no compilation errors, these commands do nothing:

previousCompileError  nextCompileError 

Since a button you map to one of these commands is not likely to often be used, you are allowed to map these commands (and only these) to a button that has another command or macro mapped to it. Then, if a request you are debugging encounters a compilation error, the button switches its association from the first command or macro you specified to the compile error function.

The button toggle occurs only when viewing a failed compilation.

Here is an example:  

<mapping command="stepOver" button="button8"/> 
<mapping command="nextCompileError" button="button8"/> 
<mapping command="stepOut" button="button9" /> 
<mapping command="previousCompileError" button="button9" /> 

Validation of mappings  

When you (re)start the Client, the ui.xml file is validated for XML structure and conformance to the rules given above for specifying its elements and attributes. Parsing violations produce an error message, the Debugger Client opens, and  either of the following result, depending on whether the offending attribute was optional or required:

• The offending attribute is absent, but the other items are as mapped.
• All the mappings are rejected, and the Client has a set of default mappings.

For semantic violations like misspelling a command name or specifying a command that is not supported in the current Client build, the Client opens with an error message, and the offending attribute is absent while the other items are as mapped.

Note: You may set a command to a button with a modifier only if you have set a command for that button without a modifier.

So, to successfully map a command to an "ALT-button" or "CTRL-button" combination, you must first map a command to an unaccompanied button click.

Overriding the ui.xml file

It may be suitable at your site to provide a second level of overrides to the default button and key mappings of the Debugger Client. For example, you might define a ui.xml file that contains a set of standard mappings for all the users in a group, and let individuals in the group override the group settings by defining their own mappings in a uimore.xml file.

To override the ui.xml file:

1. Define a ui.xml file following the guidelines specified above.

2. In the same file folder and using the same format, define a uimore.xml file.

You can use the editing tool of your choice, or you can use the Edit uimore.xml option in the Client's File menu.

The settings in the uimore.xml file override those in the ui.xml file, and they will be subject to the same structure and content validation.

3. Restart the Debugger Client.

The uimore.xml file is read after and only if a valid ui.xml file is read. If no ui.xml file is present or if it contains a significant error, the uimore.xml file is not processed.