Setting up the ui.xml file - Revision history

Ekern at 02:24, 7 January 2023

2023-01-07T02:24:59Z

← Older revision		Revision as of 02:24, 7 January 2023
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 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>		<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>
Line 102:		Line 102:

	=== 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 139:		Line 139:
	:: 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.		:: 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 [[Setting up the ui.xml file#Validation of 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]]

Ekern at 20:43, 7 December 2022

2022-12-07T20:43:09Z

Ekern at 21:37, 30 September 2022

2022-09-30T21:37:52Z

Show changes

Ekern at 14:49, 19 September 2022

2022-09-19T14:49:01Z

← Older revision		Revision as of 14:49, 19 September 2022
Line 7:		Line 7:
	: 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.html#use_mapbutton\|use the mapButton or the mapKey command]] to reconfigure buttons or hot keys without editing a mapping file.

	To set up a <var>ui.xml</var> file:		==== To set up a <var>ui.xml</var> file: ====

	1. From the Client's </span><var>File</var><span class="f_ListNum1"> menu, select <var>Edit ui.xml</var>.		1. From the Client's </span><var>File</var><span class="f_ListNum1"> menu, select <var>Edit ui.xml</var>.

Ekern at 14:40, 19 September 2022

2022-09-19T14:40:05Z

Ekern at 21:54, 15 September 2022

2022-09-15T21:54:53Z

← Older revision		Revision as of 21:54, 15 September 2022
Line 7:		Line 7:
	: 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.html#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>.		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.)		: 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.)

Ekern at 21:54, 15 September 2022

2022-09-15T21:54:12Z

Show changes

Ekern: 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..."

2022-09-15T20:01:24Z

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

New page

__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.

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 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 [[setup_ui_xml_file.html#override_ui.xml_file|uimore.xml file]] that override those in the ui.xml 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. 

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 [[using_debugger_macros.html|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: 

<div style="text-align: left; text-indent: 0; padding: 0 0 0 0; margin: 12px 0 12px 30px;">

{|
|width="50%"| '''command'''
|width="50%"|
A double quoted string that contains a Client command, each of which is described in the [[Client Command Reference|command reference]], and two of which deserve special mention here: 

*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 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 [[intro_configurable_components.html#named_buttons|named button]] (button0, . . ., button14 for the main [[review_common_buttons.html|button bar]], and extrabutton0, . . ., extrabutton14 for an [[review_common_buttons.html#launch_second_bar|extra]] button bar). 

If no button setting is specified, a key setting must be specified.
|-
| '''buttonModifier'''
| A [[intro_configurable_components.html#button_modifier|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 [[intro_configurable_components.html#keyboard_shortcut|key modifier]] (alt or ctrl). This attribute is optional.
|}

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

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 [[change_location_client_work.html|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 [[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: 

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 [[Setting up the ui.xml file|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 [[setup_ui_xml_file.html#validate_mappings|structure and content validation]]. 

3. [[file_menu_opts.html|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.

← Older revision		Revision as of 20:43, 7 December 2022
Line 45:		Line 45:
	<span class="f_DefListDDTable">The quoted command string may include a command parameter or an "i</span><span class="f_Monospace">n </span>''window''<span class="f_DefListDDTable">" 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 "i</span><span class="f_Monospace">n </span>''window''<span class="f_DefListDDTable">" prefix if appropriate. Check the individual command description in the command reference. As an example: </span>

	<p class="syntax"><span class="f_CodeExampleTable"><mapping command="runUntilVariableChanges %i"</span~~><br /~~>		<p class="syntax"><span class="f_CodeExampleTable"><mapping command="runUntilVariableChanges %i"</span>
	<span class="f_CodeExampleTable"> button="button12"/> </span></p>		<span class="f_CodeExampleTable"> button="button12"/> </span></p>

	'''Note:''' If a command parameter contains an ampersand (&), you need to XML entity encode it. For example, to map the command <var>set &foo = %i</var>, you specify it like this:		'''Note:''' If a command parameter contains an ampersand (&), you need to XML entity encode it. For example, to map the command <var>set &foo = %i</var>, you specify it like this:
	<p class="syntax><span class="f_CodeExampleTable"><mapping</span><span class="f_CodeExampleTable" style="font-size: 11px;"> </span><span class="f_CodeExampleTable">command="set</span><span class="f_CodeExampleTable" style="font-size: 11px;"> </span><span class="f_CodeExampleTable">&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" </span~~><br /~~>		<p class="syntax><span class="f_CodeExampleTable"><mapping</span><span class="f_CodeExampleTable" style="font-size: 11px;"> </span><span class="f_CodeExampleTable">command="set</span><span class="f_CodeExampleTable" style="font-size: 11px;"> </span><span class="f_CodeExampleTable">&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" </span>
	<span class="f_CodeExampleTable"> button="button14"/> </span></p>		<span class="f_CodeExampleTable"> button="button14"/> </span></p>
	\|-		\|-
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"><mappings useDefaults="true" startUpMacro="myDefault"> </span~~><br /~~>		<p class="syntax><span class="f_CodeExList"><mappings useDefaults="true" startUpMacro="myDefault"> </span>
	<span class="f_CodeExList"> <mapping command="step" button="button0" /> </span~~><br /~~>		<span class="f_CodeExList"> <mapping command="step" button="button0" /> </span>
	<span class="f_CodeExList"> <mapping command="run" button="button1" key="f5" /> </span~~><br /~~>		<span class="f_CodeExList"> <mapping command="run" button="button1" key="f5" /> </span>
	<span class="f_CodeExList"> <mapping command="cancel" button="button2" /> </span~~><br /~~>		<span class="f_CodeExList"> <mapping command="cancel" button="button2" /> </span>
	<span class="f_CodeExList"> <mapping command="stepOut" button="button3" /> </span~~><br /~~>		<span class="f_CodeExList"> <mapping command="stepOut" button="button3" /> </span>
	<span class="f_CodeExList"> <mapping command="runWithoutDaemons" button="button4" /> </span~~><br /~~>		<span class="f_CodeExList"> <mapping command="runWithoutDaemons" button="button4" /> </span>
	<span class="f_CodeExList"> <mapping command="in auditTrail top" button="button5" /> </span~~><br /~~>		<span class="f_CodeExList"> <mapping command="in auditTrail top" button="button5" /> </span>
	<span class="f_CodeExList"> <mapping command="traceValues" button="button6" /> </span~~><br /~~>		<span class="f_CodeExList"> <mapping command="traceValues" button="button6" /> </span>
	<span class="f_CodeExList"> <mapping command="breakOnNextProc" key="9" /></span~~><br /~~>		<span class="f_CodeExList"> <mapping command="breakOnNextProc" key="9" /></span>
	<span class="f_CodeExList"> <mapping command="nextCompileError" key="F2"/> </span~~><br /~~>		<span class="f_CodeExList"> <mapping command="nextCompileError" key="F2"/> </span>
	<span class="f_CodeExList"> <mapping command="previousCompileError" key="F2" keyModifier="alt"/> </span~~><br /~~>		<span class="f_CodeExList"> <mapping command="previousCompileError" key="F2" keyModifier="alt"/> </span>
	<span class="f_CodeExList"> <mapping command="macro myMacro" key="Z" keyModifier="ctrl"/></span~~><br /~~>		<span class="f_CodeExList"> <mapping command="macro myMacro" key="Z" keyModifier="ctrl"/></span>
	<span class="f_CodeExList"> <mapping command="openMacroConsole" button="button10"/> </span~~><br /~~>		<span class="f_CodeExList"> <mapping command="openMacroConsole" button="button10"/> </span>
	<span class="f_CodeExList"> <mapping command="closeMacroConsole" button="button11"/></span~~><br /~~>		<span class="f_CodeExList"> <mapping command="closeMacroConsole" button="button11"/></span>
	<span class="f_CodeExList"> <mapping command="showCommands" button="button12" /> </span~~><br /~~>		<span class="f_CodeExList"> <mapping command="showCommands" button="button12" /> </span>
	<span class="f_CodeExList"> <mapping command="help" button="button13" /> </span~~><br /~~>		<span class="f_CodeExList"> <mapping command="help" button="button13" /> </span>
	<span class="f_CodeExList"> <mapping command="step" button="button14" /> </span~~><br /~~>		<span class="f_CodeExList"> <mapping command="step" button="button14" /> </span>
	<span class="f_CodeExList"> <mapping command="manual" button="extrabutton0" /> </span~~><br /~~>		<span class="f_CodeExList"> <mapping command="manual" button="extrabutton0" /> </span>
	<span class="f_CodeExList"> <mapping command="showAbout" button="extrabutton1" /> </span~~><br /~~>		<span class="f_CodeExList"> <mapping command="showAbout" button="extrabutton1" /> </span>
	<span class="f_CodeExList"> <mapping command="showShortcuts" button="extrabutton2" /></span~~><br /~~>		<span class="f_CodeExList"> <mapping command="showShortcuts" button="extrabutton2" /></span>
	<span class="f_CodeExList"> <mapping command="manual" button="extrabutton3" /></span~~><br /~~>		<span class="f_CodeExList"> <mapping command="manual" button="extrabutton3" /></span>
	<span class="f_CodeExList"></mappings> </span></p>		<span class="f_CodeExList"></mappings> </span></p>

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"><mapping command="stepOver" button="button8"/> </span~~><br /~~>		<p class="syntax"><span class="f_CodeExample"><mapping command="stepOver" button="button8"/> </span>
	<span class="f_CodeExample"><mapping command="nextCompileError" button="button8"/> </span~~><br /~~>		<span class="f_CodeExample"><mapping command="nextCompileError" button="button8"/> </span>
	<span class="f_CodeExample"><mapping command="stepOut" button="button9" /> </span~~><br /~~>		<span class="f_CodeExample"><mapping command="stepOut" button="button9" /> </span>
	<span class="f_CodeExample"><mapping command="previousCompileError" button="button9" /> </span></p>		<span class="f_CodeExample"><mapping command="previousCompileError" button="button9" /> </span></p>

← Older revision		Revision as of 14:40, 19 September 2022
Line 2:		Line 2:
	<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 [[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><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 [[setup_ui_xml_file.html#override_ui.xml_file\|uimore.xml file]] that override those in the <var>ui.xml</var> file.
Line 9:		Line 9:
	To set up a <var>ui.xml</var> file:		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>.		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.)		: 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>		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>
Line 17:		Line 17:

	: <span class="term">useDefaults</span> indicates the mode in which the mappings are applied:		: <span class="term">useDefaults</span> indicates the mode in which the mappings are applied:
	*<p class="syntax">useDefaults="true"</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="true"</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.		: Use this mode if you generally like the defaults but want to make a small number of additions or changes to them.
			: <p class="syntax">useDefaults="false"</p>
	*<p class="syntax">useDefaults="false"</p>
	: tells the Client ''not'' to set the defaults, just to process the <var>ui.xml</var> file mappings. You start with a "clean slate" and only the settable buttons and hot keys you assign will be available.		: tells the Client ''not'' to set the defaults, just to process the <var>ui.xml</var> 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.		: Use this mode if you want to completely change the settings from the defaults.
	: This is the default.		: This is the default.
	*<p class="syntax">startUpMacro</p>		: <p class="syntax">startUpMacro</p>
	: indicates a [[~~using_debugger_macros.html~~\|macro]] that is run when the Client starts.		: indicates a [[Using Debugger Macros\|macro]] that is run when the Client starts.

	3. Specify or update <~~</span><span class="f_MonoBold">~~mapping>~~</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 '''<mapping>''' elements for your buttons/keys.
	: Contained within the <span class="term"><mappings></span> element are one or more <span class="term"><mapping></span> elements. Each <span class="term"><mapping></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"><mappings></span> element are one or more <span class="term"><mapping></span> elements. Each <span class="term"><mapping></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"><mapping></span> attributes are described below, after which is a comprehensive example:		: The <span class="term"><mapping></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 37:		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
Line 96:		Line 95:
	<span class="f_CodeExList"></mappings> </span></p>		<span class="f_CodeExList"></mappings> </span></p>

	: If you define more than one mapping for the same key or button, the last mapping (closest to the <var"></mappings></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></mappings></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.]]

Line 118:		Line 117:
	<span class="f_CodeExample"><mapping command="previousCompileError" button="button9" /> </span></p>		<span class="f_CodeExample"><mapping command="previousCompileError" button="button9" /> </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 138:		Line 137:

	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 [[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.

Setting up the ui.xml file - Revision history

Ekern at 02:24, 7 January 2023

Ekern at 20:43, 7 December 2022

Ekern at 21:37, 30 September 2022

Ekern at 14:49, 19 September 2022

Ekern at 14:40, 19 September 2022

Ekern at 21:54, 15 September 2022

Ekern at 21:54, 15 September 2022

Ekern: 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..."

Ekern: 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..."