Setting up the ui.xml file: Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
__TOC__
__TOC__
<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">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 [[Changing the location of Client work files|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><var>ui.xml</var><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 settings of buttons and hot keys|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 <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.
'''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 [[Setting up the ui.xml file#Overriding the 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.  
: And/or: You can [[Reconfiguring GUI buttons and hot keys#use_mapbutton|use the mapButton or the mapKey command]] to reconfigure buttons or hot keys without editing a mapping file.  


<span class="f_Para">To set up a </span><var>ui.xml</var><span class="f_Para"> file: </span>
=== To set up a <var>ui.xml</var> file: ===  
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">):


: <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>
: 1. From the Client's </span><var>File</var><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="term">useDefaults</span> indicates the mode in which the mappings are applied:
:: <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>
*<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.


: Use this mode if you generally like the defaults but want to make a small number of additions or changes to them.  
:: <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.  


*<p class="syntax">useDefaults=&quot;false&quot;</p>  
:: Use this mode if you generally like the defaults but want to make a small number of additions or changes to them.
: 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.
:: <p class="syntax">useDefaults=&quot;false&quot;</p>  
: Use this mode if you want to completely change the settings from the defaults.  
:: 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.
: This is the default.
:: Use this mode if you want to completely change the settings from the defaults.  
*<p class="syntax">startUpMacro</p>
:: This is the default.
: indicates a [[using_debugger_macros.html|macro]] that is run when the Client starts.
:: <p class="syntax">startUpMacro</p>
:: indicates a [[Using Debugger Macros|macro]] that is run when the Client starts.


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>
: 3. Specify or update '''&lt;mapping&gt;''' elements for your buttons/keys.
: 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.  
:: 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.  
: The </span><span class="term">&lt;mapping&gt;</span> attributes are described below, after which is a comprehensive example:
:: The <span class="term">&lt;mapping&gt;</span> attributes are described below, after which is a comprehensive example:


<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 36: 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_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>
<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>


*The [[macro command|macro]] command calls a user defined macro  
*The [[macro command|macro]] command calls a user defined macro  
*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 <span class="term">separator</span> keyword creates an inactive button whose only function is to be a visual [[Introducing the configurable components#Named buttons and separators|button separator]] on a Client button bar  


<span class="f_DefListDDTable"> The </span><span class="f_Monospace">command</span><span class="f_DefListDDTable"> attribute is required. </span>
<span class="f_DefListDDTable"> The </span><span class="f_Monospace">command</span><span class="f_DefListDDTable"> attribute is required. </span>
Line 45: Line 45:
<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_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>


<p class="syntax"><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>
<span class="f_CodeExampleTable">  button=&quot;button12&quot;/&gt; </span></p>
<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 <var>set &amp;foo = %i</var>, 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 />
<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>
<span class="f_CodeExampleTable">  button=&quot;button14&quot;/&gt; </span></p>
<span class="f_CodeExampleTable">  button=&quot;button14&quot;/&gt; </span></p>
|-
|-
| '''button'''
| '''button'''
|
|
<span class="f_DefListDDTable">A [[intro_configurable_components.html#named_buttons|named button]] (</span><span class="f_MonoSpTable">button0</span><span class="f_DefListDDTable">, . . ., </span><span class="f_MonoSpTable">button14</span><span class="f_DefListDDTable"> for the main [[review_common_buttons.html|button bar]], and </span><span class="f_MonoSpTable">extrabutton0</span><span class="f_DefListDDTable">, . . ., </span><span class="f_MonoSpTable">extrabutton14</span><span class="f_DefListDDTable"> for an [[review_common_buttons.html#launch_second_bar|extra]] button bar). </span>
<span class="f_DefListDDTable">A [[Introducing the configurable components#Named buttons and separators|named button]] (</span><span class="f_MonoSpTable">button0</span><span class="f_DefListDDTable">, . . ., </span><span class="f_MonoSpTable">button14</span><span class="f_DefListDDTable"> for the main [[Button Bar|button bar]], and </span><span class="f_MonoSpTable">extrabutton0</span><span class="f_DefListDDTable">, . . ., </span><span class="f_MonoSpTable">extrabutton14</span><span class="f_DefListDDTable"> for an [[Button Bar#Launching a second button bar|extra]] button bar). </span>


<span class="f_DefListDDTable">If no </span><span class="f_MonoSpTable">button</span><span class="f_DefListDDTable"> setting is specified, a </span><span class="f_MonoSpTable">key</span><span class="f_DefListDDTable"> setting must be specified.</span>
<span class="f_DefListDDTable">If no </span><span class="f_MonoSpTable">button</span><span class="f_DefListDDTable"> setting is specified, a </span><span class="f_MonoSpTable">key</span><span class="f_DefListDDTable"> setting must be specified.</span>
|-
|-
| '''buttonModifier'''
| '''buttonModifier'''
| <span class="f_DefListDDTable">A [[intro_configurable_components.html#button_modifier|button modifier]] (Alt or Ctrl). This attribute is optional.</span>
| <span class="f_DefListDDTable">A [[Introducing the configurable components#Button modifiers|button modifier]] (Alt or Ctrl). This attribute is optional.</span>
|-
|-
| '''key'''
| '''key'''
Line 65: Line 65:
|-
|-
| '''keyModifier'''
| '''keyModifier'''
| <span class="f_DefListDDTable">A [[intro_configurable_components.html#keyboard_shortcut|key modifier]] (alt or ctrl). This attribute is optional.</span>
| <span class="f_DefListDDTable">A [[Introducing the configurable components#Keyboard shortcuts|key modifier]] (alt or ctrl). This attribute is optional.</span>
|}
|}


Line 72: Line 72:
'''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:  
: 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:  
<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>
<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>
<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>
<span class="f_CodeExList">   &lt;mapping command=&quot;cancel&quot; button=&quot;button2&quot; /&gt; </span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;cancel&quot; button=&quot;button2&quot; /&gt; </span>
<span class="f_CodeExList">   &lt;mapping command=&quot;stepOut&quot; button=&quot;button3&quot; /&gt; </span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;stepOut&quot; button=&quot;button3&quot; /&gt; </span>
<span class="f_CodeExList">   &lt;mapping command=&quot;runWithoutDaemons&quot; button=&quot;button4&quot; /&gt; </span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;runWithoutDaemons&quot; button=&quot;button4&quot; /&gt; </span>
<span class="f_CodeExList">   &lt;mapping command=&quot;in auditTrail top&quot; button=&quot;button5&quot; /&gt; </span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;in auditTrail top&quot; button=&quot;button5&quot; /&gt; </span>
<span class="f_CodeExList">   &lt;mapping command=&quot;traceValues&quot; button=&quot;button6&quot; /&gt; </span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;traceValues&quot; button=&quot;button6&quot; /&gt; </span>
<span class="f_CodeExList">   &lt;mapping command=&quot;breakOnNextProc&quot; key=&quot;9&quot; /&gt;</span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;breakOnNextProc&quot; key=&quot;9&quot; /&gt;</span>
<span class="f_CodeExList">   &lt;mapping command=&quot;nextCompileError&quot; key=&quot;F2&quot;/&gt; </span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;nextCompileError&quot; key=&quot;F2&quot;/&gt; </span>
<span class="f_CodeExList">   &lt;mapping command=&quot;previousCompileError&quot; key=&quot;F2&quot; keyModifier=&quot;alt&quot;/&gt; </span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;previousCompileError&quot; key=&quot;F2&quot; keyModifier=&quot;alt&quot;/&gt; </span>
<span class="f_CodeExList">   &lt;mapping command=&quot;macro myMacro&quot; key=&quot;Z&quot; keyModifier=&quot;ctrl&quot;/&gt;</span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;macro myMacro&quot; key=&quot;Z&quot; keyModifier=&quot;ctrl&quot;/&gt;</span>
<span class="f_CodeExList">   &lt;mapping command=&quot;openMacroConsole&quot; button=&quot;button10&quot;/&gt; </span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;openMacroConsole&quot; button=&quot;button10&quot;/&gt; </span>
<span class="f_CodeExList">   &lt;mapping command=&quot;closeMacroConsole&quot; button=&quot;button11&quot;/&gt;</span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;closeMacroConsole&quot; button=&quot;button11&quot;/&gt;</span>
<span class="f_CodeExList">   &lt;mapping command=&quot;showCommands&quot; button=&quot;button12&quot; /&gt; </span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;showCommands&quot; button=&quot;button12&quot; /&gt; </span>
<span class="f_CodeExList">   &lt;mapping command=&quot;help&quot; button=&quot;button13&quot; /&gt;  </span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;help&quot; button=&quot;button13&quot; /&gt;  </span>
<span class="f_CodeExList">   &lt;mapping command=&quot;step&quot; button=&quot;button14&quot; /&gt; </span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;step&quot; button=&quot;button14&quot; /&gt; </span>
<span class="f_CodeExList">   &lt;mapping command=&quot;manual&quot; button=&quot;extrabutton0&quot; /&gt; </span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;manual&quot; button=&quot;extrabutton0&quot; /&gt; </span>
<span class="f_CodeExList">   &lt;mapping command=&quot;showAbout&quot; button=&quot;extrabutton1&quot; /&gt;  </span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;showAbout&quot; button=&quot;extrabutton1&quot; /&gt;  </span>
<span class="f_CodeExList">   &lt;mapping command=&quot;showShortcuts&quot; button=&quot;extrabutton2&quot; /&gt;</span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;showShortcuts&quot; button=&quot;extrabutton2&quot; /&gt;</span>
<span class="f_CodeExList">   &lt;mapping command=&quot;manual&quot; button=&quot;extrabutton3&quot; /&gt;</span><br />
<span class="f_CodeExList">   &lt;mapping command=&quot;manual&quot; button=&quot;extrabutton3&quot; /&gt;</span>
<span class="f_CodeExList">&lt;/mappings&gt;  </span></p>
<span class="f_CodeExList">&lt;/mappings&gt;  </span></p>


: 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 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.]]
:: 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.]]


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.
:: If you edited an existing <var>ui.xml</var> file, the updated settings take effect the next time the Client is started.


==== 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 [[Viewing programs that contain coding 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 class="syntax">previousCompileError 
Line 112: 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>
<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>
<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>
<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>


<span class="f_Subhead">Validation of mappings  <span id="validate_mappings" class="hmanchor"></span> </span>
=== Validation of mappings   ===


<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 129: Line 129:
: 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.  
: 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.  


==== 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><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">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>


To override the <var>ui.xml</var> file:  
To override the <var>ui.xml</var> file:  


1. Define a <var>ui.xml</var> file following the guidelines specified [[Setting up the ui.xml file|above.]]  
: 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.
: 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.
:: You can use the editing tool of your choice, or you can use the <var>Edit uimore.xml</var> 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]].
:: 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 [[Setting up the ui.xml file#Validation of mappings|structure and content validation]].
3. [[file_menu_opts.html|Restart]] the Debugger Client.
: 3. [[File menu options|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.
:: 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.


[[Category:Debugger Home]]
[[Category:Debugger Home]]

Latest revision as of 02:24, 7 January 2023

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.