Setting up the ui.xml file: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Created page with "__TOC__ 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 change_loca...")
 
No edit summary
Line 1: Line 1:
__TOC__
__TOC__
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 [[change_location_client_work.html|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.  
<span class="f_Para">Each time the Client is started, it checks for the presence of a </span><var>ui.xml</var><span class="f_Para"> file in the same folder as the Client executable file itself (the default) or [[change_location_client_work.html|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. </span>


<span class="f_Para">If you want to change the Client's [[default_buttons_keys.html|default buttons and hot key associations]], you must provide in the appropriate folder a </span><span class="f_Monospace">ui.xml</span><span class="f_Para"> text file that adheres to the structure described in this section.</span>
<span class="f_Para">If you want to change the Client's [[default_buttons_keys.html|default buttons and hot key associations]], you must provide in the appropriate folder a </span><var>ui.xml</var><span class="f_Para"> text file that adheres to the structure described in this section.</span>


'''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 [[setup_ui_xml_file.html#override_ui.xml_file|uimore.xml file]] that override those in the ui.xml file.  
'''Note:''' You can also define an alternative to the <var>ui.xml</var> file: following the same rules for setting up the <var>ui.xml</var> file, you provide settings in the [[setup_ui_xml_file.html#override_ui.xml_file|uimore.xml file]] that override those in the <var>ui.xml</var> file.
: And/or: You can [[reconfiguring_gui_buttons.html#use_mapbutton|use the mapButton or the mapKey command]] to reconfigure buttons or hot keys without editing a mapping file.  


<span class="f_NoteContinue">And/or:</span>
<span class="f_Para">To set up a </span><var>ui.xml</var><span class="f_Para"> file: </span>
1. From the Client's </span><span class="f_GUIlabel">File</span><span class="f_ListNum1"> menu, select <var>Edit ui.xml</var>.
: An untitled <span class="term">Notepad</span> file is opened for you, along with a prompt to create a </span><var>ui.xml</var> file. (If a <var>ui.xml</var> file already exists, that file is opened.)
2. In the file, specify or update</span><span class="f_Para"> the </span><var>mappings</var><span class="f_Para"> tag, the first line in the file.</span><span id="startupmacro_att" class="hmanchor"></span><span class="f_ListNum1"> </span>
: The top level tag in the </span><var>ui.xml</var><span class="f_ListContinue"> file is the </span><span class="f_Monospace">mappings</span><span class="f_ListContinue"> tag, which has two optional attributes (</span><span class="f_Monospace">useDefaults </span><span class="f_ListContinue">and</span><span class="f_Monospace"> startUpMacro</span><span class="f_ListContinue">):


<span class="f_NoteContinue">You can [[reconfiguring_gui_buttons.html#use_mapbutton|use the mapButton or the mapKey command]] to reconfigure buttons or hot keys without editing a mapping file. </span>
: <p class="syntax>&lt;mappings [useDefaults=&quot;true|false&quot;] [startUpMacro=&quot;</span><span class="f_CodeExampleItalic">macro</span><span class="f_CodeExList">&quot;]&gt; </p>


<span class="f_Para">To set up a </span><span class="f_Monospace">ui.xml</span><span class="f_Para"> file: </span>
: <span class="term">useDefaults</span> indicates the mode in which the mappings are applied:
*<p class="syntax">useDefaults=&quot;true&quot;</p> 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.


1. From the Client's File menu, select Edit ui.xml.
: Use this mode if you generally like the defaults but want to make a small number of additions or changes to them.  


<span class="f_ListContinue">An untitled </span><span class="f_Product">Notepad</span><span class="f_ListContinue"> file is opened for you, along with a prompt to create a </span><span class="f_Monospace">ui.xml</span><span class="f_ListContinue"> file. (If a </span><span class="f_Monospace">ui.xml</span><span class="f_ListContinue"> file already exists, that file is opened.)</span>
*<p class="syntax">useDefaults=&quot;false&quot;</p>  
: tells the Client ''not'' to set the defaults, just to process the <var>ui.xml</var> file mappings. You start with a &quot;clean slate&quot; 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.
*<p class="syntax">startUpMacro</p>
: indicates a [[using_debugger_macros.html|macro]] that is run when the Client starts.


2. In the file, specify or update the '''mappings''' tag, the first line in the file.
3. Specify or update &lt;</span><span class="f_MonoBold">mapping&gt;</span><span class="f_Para"> elements for your buttons/keys.</span><span id="mapping_element" class="hmanchor"></span><span class="f_ListNum1"> </span>
 
: Contained within the <span class="term">&lt;mappings&gt;</span> element are one or more <span class="term">&lt;mapping&gt;</span> elements. Each <span class="term">&lt;mapping&gt;</span> 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.  
<span class="f_ListContinue">The top level tag in the </span><span class="f_Monospace">ui.xml</span><span class="f_ListContinue"> file is the </span><span class="f_Monospace">mappings</span><span class="f_ListContinue"> tag, which has two optional attributes (</span><span class="f_Monospace">useDefaults </span><span class="f_ListContinue">and</span><span class="f_Monospace"> startUpMacro</span><span class="f_ListContinue">): </span>
: The </span><span class="term">&lt;mapping&gt;</span> attributes are described below, after which is a comprehensive example:
 
<span class="f_CodeExList">&lt;mappings [useDefaults=&quot;true|false&quot;] [startUpMacro=&quot;</span><span class="f_CodeExampleItalic">macro</span><span class="f_CodeExList">&quot;]&gt; </span>
 
'''useDefaults''' indicates the mode in which the mappings are applied:
 
*useDefaults</span><span class="f_=XmpPrint">=</span>&quot;true&quot; 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<span class="f_=XmpPrint">=</span>&quot;false&quot; tells the Client ''not'' to set the defaults, just to process the ui.xml file mappings. You start with a &quot;clean slate&quot; and only the settable buttons and hot keys you assign will be available.
 
<span class="f_ListContinue2">Use this mode if you want to completely change the settings from the defaults. </span>
 
<span class="f_ListContinue2">This is the default.</span>
 
*startUpMacro indicates a [[using_debugger_macros.html|macro]] that is run when the Client starts.
 
3. Specify or update &lt;'''mapping&gt;''' elements for your buttons/keys.
 
<span class="f_ListContinue">Contained within the </span><span class="f_Monospace">&lt;mappings&gt;</span><span class="f_ListContinue"> element are one or more </span><span class="f_Monospace">&lt;mapping&gt;</span><span class="f_ListContinue"> elements. Each </span><span class="f_Monospace">&lt;mapping&gt;</span><span class="f_ListContinue"> 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. </span>
 
<span class="f_ListContinue">The </span><span class="f_Monospace">&lt;mapping&gt;</span><span class="f_ListContinue"> attributes are described below, after which is a comprehensive example: </span>


<div style="text-align: left; text-indent: 0; padding: 0 0 0 0; margin: 12px 0 12px 30px;">
<div style="text-align: left; text-indent: 0; padding: 0 0 0 0; margin: 12px 0 12px 30px;">
Line 47: Line 36:
|width="50%"| '''command'''
|width="50%"| '''command'''
|width="50%"|
|width="50%"|
<span class="f_DefListDDTable">A double quoted string that contains a </span><span class="f_ListBul1Table">Client command, each of which is described in the [[Client Command Reference|command reference]], and two</span><span class="f_DefListDDTable"> of which deserve special mention here:</span><span class="f_ListBul1Table"> </span><span class="f_DefListDDTable"> </span>
<span class="f_DefListDDTable">A double quoted string that contains a </span><span class="f_ListBul1Table">Client command, each of which is described in the [[client_command_ref.html|command reference]], and two</span><span class="f_DefListDDTable"> of which deserve special mention here:</span><span class="f_ListBul1Table"> </span><span class="f_DefListDDTable"> </span>


*The [[macro command|macro]] command calls a user defined macro  
*The [[macro command|macro]] command calls a user defined macro  
*The separator keyword creates an inactive button whose only function is to be a visual [[intro_configurable_components.html#named_buttons|button separator]] on a Client button bar
*The <span class="term">separator</span> keyword creates an inactive button whose only function is to be a visual [[intro_configurable_components.html#named_buttons|button separator]] on a Client button bar  


The command attribute is required.  
<span class="f_DefListDDTable"> The </span><span class="f_Monospace">command</span><span class="f_DefListDDTable"> attribute is required. </span>


The quoted command string may include a command parameter or an &quot;in ''window''&quot; prefix if appropriate. Check the individual command description in the command reference. As an example:  
<span class="f_DefListDDTable">The quoted command string may include a command parameter or an &quot;i</span><span class="f_Monospace">n </span>''window''<span class="f_DefListDDTable">&quot; prefix if appropriate. Check the individual command description in the command reference. As an example: </span>


<span class="f_CodeExampleTable">&lt;mapping command=&quot;runUntilVariableChanges %i&quot;</span><br />
<p class="syntax"><span class="f_CodeExampleTable">&lt;mapping command=&quot;runUntilVariableChanges %i&quot;</span><br />
<span class="f_CodeExampleTable">  button=&quot;button12&quot;/&gt; </span>
<span class="f_CodeExampleTable">  button=&quot;button12&quot;/&gt; </span></p>


'''Note:''' If a command parameter contains an ampersand (&amp;), you need to XML entity encode it. For example, to map the command set &amp;foo = %i, you specify it like this:
'''Note:''' If a command parameter contains an ampersand (&amp;), you need to XML entity encode it. For example, to map the command <var>set &amp;foo = %i</var>, you specify it like this:
 
<p class="syntax><span class="f_CodeExampleTable">&lt;mapping</span><span class="f_CodeExampleTable" style="font-size: 11px;"> </span><span class="f_CodeExampleTable">command=&quot;set</span><span class="f_CodeExampleTable" style="font-size: 11px;"> </span><span class="f_CodeExampleTable">&amp;amp;foo</span><span class="f_CodeExampleTable" style="font-size: 11px;"> </span><span class="f_CodeExampleTable">=</span><span class="f_CodeExampleTable" style="font-size: 11px;"> </span><span class="f_CodeExampleTable">%i&quot; </span><br />
<span class="f_CodeExampleTable">&lt;mapping</span><span class="f_CodeExampleTable" style="font-size: 11px;"> </span><span class="f_CodeExampleTable">command=&quot;set</span><span class="f_CodeExampleTable" style="font-size: 11px;"> </span><span class="f_CodeExampleTable">&amp;amp;foo</span><span class="f_CodeExampleTable" style="font-size: 11px;"> </span><span class="f_CodeExampleTable">=</span><span class="f_CodeExampleTable" style="font-size: 11px;"> </span><span class="f_CodeExampleTable">%i&quot; </span><br />
<span class="f_CodeExampleTable">  button=&quot;button14&quot;/&gt; </span></p>
<span class="f_CodeExampleTable">  button=&quot;button14&quot;/&gt; </span>
|-
|-
| '''button'''
| '''button'''
Line 82: Line 70:


</div>
</div>
'''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.  
'''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 <var>mapping</var> element, you must specify a <var>button</var> or <var>key</var> setting (or both). Here is an example:  
<span class="f_ListContinue">For any given </span><span class="f_Monospace">mapping</span><span class="f_ListContinue"> element, you must specify a </span><span class="f_Monospace">button</span><span class="f_ListContinue"> or </span><span class="f_Monospace">key</span><span class="f_ListContinue"> setting (or both). Here is an example:  </span>
<p class="syntax><span class="f_CodeExList">&lt;mappings useDefaults=&quot;true&quot; startUpMacro=&quot;myDefault&quot;&gt; </span><br />
<p class="syntax">
<span class="f_CodeExList">&lt;mappings useDefaults=&quot;true&quot; startUpMacro=&quot;myDefault&quot;&gt; </span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;step&quot; button=&quot;button0&quot; /&gt; </span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;step&quot; button=&quot;button0&quot; /&gt; </span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;run&quot; button=&quot;button1&quot; key=&quot;f5&quot; /&gt; </span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;run&quot; button=&quot;button1&quot; key=&quot;f5&quot; /&gt; </span><br />
Line 109: Line 95:
<span class="f_CodeExList">&lt;/mappings&gt;  </span></p>
<span class="f_CodeExList">&lt;/mappings&gt;  </span></p>


<span class="f_ListContinue">If you define more than one mapping for the same key or button, the last mapping (closest to the </span><span class="f_Monospace">&lt;/mappings&gt;</span><span class="f_ListContinue"> end tag) takes precedence. </span>
: If you define more than one mapping for the same key or button, the last mapping (closest to the <var">&lt;/mappings&gt;</var> 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 [[change_location_client_work.html|configured a different location.]]
<span class="f_ListContinue">If you specify a macro, it is assumed to reside in the same folder as the Debugger Client executable file unless you [[change_location_client_work.html|configured a different location.]]</span>


4. Save, then Exit the file.
4. Save, then Exit the file.
 
: If you edited an existing <var>ui.xml</var> file, the updated settings take effect the next time the Client is started.
<span class="f_ListContinue">If you edited an existing </span><span class="f_Monospace">ui.xml</span><span class="f_ListContinue"> file, the updated settings take effect the next time the Client is started.</span>


==== Button toggle for compilation errors ====
==== Button toggle for compilation errors ====
<span class="f_Para">The following two commands are only meaningful in the context of [[view_program_coding_err.html#compile_errors|examining the results of a failed compilation]]. If the program you are debugging has no compilation errors, these commands do nothing: </span>
<span class="f_Para">The following two commands are only meaningful in the context of [[view_program_coding_err.html#compile_errors|examining the results of a failed compilation]]. If the program you are debugging has no compilation errors, these commands do nothing: </span>


<p class="syntax">previousCompileError </p>
<p class="syntax">previousCompileError 
<p class="syntax">nextCompileError </p>
nextCompileError </p>


<span class="f_Para">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. </span>
<span class="f_Para">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. </span>
Line 128: Line 112:


<span class="f_Para">Here is an example:  </span>
<span class="f_Para">Here is an example:  </span>
<p class="syntax"<span class="f_CodeExample">&lt;mapping command=&quot;stepOver&quot; button=&quot;button8&quot;/&gt; </span><br />
<p class="syntax"><span class="f_CodeExample">&lt;mapping command=&quot;stepOver&quot; button=&quot;button8&quot;/&gt; </span><br />
<span class="f_CodeExample">&lt;mapping command=&quot;nextCompileError&quot; button=&quot;button8&quot;/&gt; </span><br />
<span class="f_CodeExample">&lt;mapping command=&quot;nextCompileError&quot; button=&quot;button8&quot;/&gt; </span><br />
<span class="f_CodeExample">&lt;mapping command=&quot;stepOut&quot; button=&quot;button9&quot; /&gt; </span><br />
<span class="f_CodeExample">&lt;mapping command=&quot;stepOut&quot; button=&quot;button9&quot; /&gt; </span><br />
<span class="f_CodeExample">&lt;mapping command=&quot;previousCompileError&quot; button=&quot;button9&quot; /&gt; </span></p>
<span class="f_CodeExample">&lt;mapping command=&quot;previousCompileError&quot; button=&quot;button9&quot; /&gt; </span></p>


==== Validation of mappings ====
<span class="f_Subhead">Validation of mappings  <span id="validate_mappings" class="hmanchor"></span> </span>
 
<span class="f_Para">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: </span>
<span class="f_Para">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: </span>


Line 142: Line 127:


'''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.  
'''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 &quot;ALT-button&quot; or &quot;CTRL-button&quot; combination, you must first map a command to an unaccompanied button click.  
<span class="f_NoteContinue">So, to successfully map a command to an &quot;ALT-button&quot; or &quot;CTRL-button&quot; combination, you must first map a command to an unaccompanied button click. </span>


==== Overriding the ui.xml file ====
==== Overriding the ui.xml file ====
<span class="f_Para">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 </span><span class="f_Monospace">ui.xml</span><span class="f_Para"> 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 </span><span class="f_Monospace">uimore.xml</span><span class="f_Para"> file. </span>
<span class="f_Para">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 </span><var>ui.xml</var><span class="f_Para"> 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 </span><var>uimore.xml</var><span class="f_Para"> file. </span>
 
<span class="f_Para">To override the </span><span class="f_Monospace">ui.xml</span><span class="f_Para"> file: </span>
 
1. Define a ui.xml file following the guidelines specified [[Setting up the ui.xml file|above.]]
2. In the same file folder and using the same format, define a uimore.xml file.


<span class="f_ListContinue">You can use the editing tool of your choice, or you can use the </span><span class="f_GUIlabel">Edit uimore.xml</span><span class="f_ListContinue"> option in the Client's </span><span class="f_GUIlabel">File</span><span class="f_ListContinue"> menu.</span>
To override the <var>ui.xml</var> file:


<span class="f_ListContinue">The settings in the uimore.xml file override those in the </span><span class="f_Monospace">ui.xml</span><span class="f_ListContinue"> file, and they will be subject to the same [[setup_ui_xml_file.html#validate_mappings|structure and content validation]]. </span>
1. Define a <var>ui.xml</var> file following the guidelines specified [[Setting up the ui.xml file|above.]]  


2. In the same file folder and using the same format, define a <var>uimore.xml</var> file.
: You can use the editing tool of your choice, or you can use the <span class="term">Edit uimore.xml</span> option in the Client's <var>File</var> menu.
: The settings in the uimore.xml file override those in the </span><var>ui.xml</var> file, and they will be subject to the same [[setup_ui_xml_file.html#validate_mappings|structure and content validation]].
3. [[file_menu_opts.html|Restart]] the Debugger Client.
3. [[file_menu_opts.html|Restart]] the Debugger Client.
: The <var>uimore.xml</var> file is read '''after and only if''' a valid <var>ui.xml</var> file is read. If no <var>ui.xml</var> file is present or if it contains a significant error, the <var>uimore.xml</var> file is not processed.


<span class="f_ListContinue">The </span><span class="f_Monospace">uimore.xml</span><span class="f_ListContinue"> file is read </span><span class="f_EmphBold">after and only if</span><span class="f_ListContinue"> a valid </span><span class="f_Monospace">ui.xml</span><span class="f_ListContinue"> file is read. If no </span><span class="f_Monospace">ui.xml</span><span class="f_ListContinue"> file is present or if it contains a significant error, the </span><span class="f_Monospace">uimore.xml</span><span class="f_ListContinue"> file is not processed.</span>
[[Category:Debugger Home]]

Revision as of 21:54, 15 September 2022

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 <var"></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.