User Reference:Custom GUI Commands - Revision history

Jhill: /* CUSTOM DIALOG ... */

2026-01-26T00:12:54Z

CUSTOM DIALOG ...

← Older revision		Revision as of 00:12, 26 January 2026
Line 160:		Line 160:

	Notes: In the example above, we have used just one catalog variable, <code>DialogParams</code>, but you are free to use more than one if you want to assemble separate lists of variables for different purposes. The <code>CUSTOM DIALOG</code> command clears each catalog variable the first time it uses it (so, you can run the example above multiple times, and <code>DialogParams</code> will still only contain one copy of each name). Catalog variables get cleared and (re-)filled regardless of whether the dialog is accepted or cancelled.		Notes: In the example above, we have used just one catalog variable, <code>DialogParams</code>, but you are free to use more than one if you want to assemble separate lists of variables for different purposes. The <code>CUSTOM DIALOG</code> command clears each catalog variable the first time it uses it (so, you can run the example above multiple times, and <code>DialogParams</code> will still only contain one copy of each name). Catalog variables get cleared and (re-)filled regardless of whether the dialog is accepted or cancelled.

			====Using <code>HIDDEN</code> (a.k.a. <code>visible=false</code>) and <code>FIXED</code> (a.k.a. <code>fixed=true</code>) to make a "wizard"====

			Each <code>VAR</code> entry may also have a modifier that overrides its visibility and whether the user can actually change it.

			* Use <code>HIDDEN</code> or <code>INVISIBLE</code> or <code>visible=false</code> to hide a particular <code>VAR</code> from the user's view (but it will still set its environment variable if the user accepts the dialog). The opposite, <code>VISIBLE</code> or <code>visible=true</code>, makes the <code>VAR</code> visible in the GUI (which is the default behavior anyway).
			* Use <code>FIXED</code> or <code>fixed=true</code> to display the <code>VAR</code>'s label and value but without giving the user the chance to change it (and it will still set its environment variable if the user accepts the dialog). The opposite, <code>fixed=false</code>, makes the <code>VAR</code> adjustable (which is the default behavior anyway).

			The ability to make certain variables fixed or hidden, while still including them in the GUI, allows the de-facto construction of multi-stage "wizards" using repeated calls to <code>CUSTOM DIALOG</code>. The following example allows the operator to configure the task as "active" (which then makes a certain subset of parameters visible for configuration in the second stage) or "passive" (associated with a different subset of parameters).

			<pre>
			# "wizard" example leveraging `visible=false` and `fixed=true` modifiers

			add parameter Application:Robot string TaskVariant= Active % % % // None or Passive or Active
			add parameter Application:Robot float ActivePulseDuration= 100ms % 50ms % //
			add parameter Application:Robot float ActivePulseISI= 100ms % 10ms % //
			add parameter Application:Robot float PassiveStandardDuration= 100ms % 50ms % //
			add parameter Application:Robot float PassiveDurationDelta= 100ms % 10ms % //

			wizardStage := 1
			set variable response "-"
			while [ $response != Launch ] && [ $response != "" ] # NB: QUIT will not succeed if placed inside the WHILE loop, and there is no BREAK
			if [ $wizardStage == 1 ]
			set environment TaskVariant ""
			set variable buttons {cancel\|Next}
			set variable defaultButton Next
			elseif [ $wizardStage == 2 ]
			set variable buttons {cancel\|Previous\|Launch}
			set variable defaultButton Launch
			end
			set variable response ${
			custom dialog
			var SUBJECTNAME "Subject:" {}
			default "Nobody" minimum 1
			var TaskVariant "Task Variant:" {None\|Passive\|Active}
			default "Active" minimum 1 catalog DialogParams fixed=${[ $wizardStage != 1 ]}
			var PassiveStandardDuration "Passive Standard Duration:" {50ms\|100ms\|150ms\|200ms\|250ms}
			default "100ms" minimum 1 catalog DialogParams visible=${[ $TaskVariant == "Passive" ]}
			var PassiveDurationDelta "Passive Duration Delta:" {0ms\|10ms\|20ms\|30ms\|40ms\|50ms\|60ms\|70ms\|80ms\|90ms\|100ms}
			default "100ms" minimum 1 catalog DialogParams visible=${[ $TaskVariant == "Passive" ]}
			var ActivePulseDuration "Active Pulse Duration:" {50ms\|100ms\|150ms\|200ms\|250ms}
			default "100ms" minimum 1 catalog DialogParams visible=${[ $TaskVariant == "Active" ]}
			var ActivePulseISI "Active Pulse ISI:" {0ms\|10ms\|20ms\|30ms\|40ms\|50ms\|60ms\|70ms\|80ms\|90ms\|100ms}
			default "100ms" minimum 1 catalog DialogParams visible=${[ $TaskVariant == "Active" ]}
			message "(no task-specific parameters)" visible=${[ $task == None ]}
			top 200
			width 400
			cachefile "${parent directory $0}/launcherDialogVars.bci"
			buttons $buttons default $defaultButton escape cancel
			}
			if [ $response == "Previous" ]; wizardStage := wizardStage - 1; end
			if [ $response == "Next" ]; wizardStage := wizardStage + 1; end
			end
			if [ $response == "" ]; quit; end

			for x in $DialogParams
			set parameter $x ${$x}
			end
			</pre>

Jhill: /* CUSTOM DIALOG ... */

2026-01-08T00:31:03Z

CUSTOM DIALOG ...

← Older revision		Revision as of 00:31, 8 January 2026
Line 53:		Line 53:

	; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>] [CATALOG <listVariableName>]</code>		; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>] [CATALOG <listVariableName>]</code>
	: This creates a text field that the user can fill in. If you supply a <code>DEFAULT</code> subclause, the specified default text is pre-filled. If you specify a <code>MINIMUM</code> number of characters, the dialog buttons (except for the designated <code>ESCAPE</code> button) will be disabled until this text field contains at least that many characters. If the dialog is completed (by any button other than the designated <code>ESCAPE</code> button) then the environment variable designated by <code><variableName></code> will be set to the contents of the text field. If you supply a <code>CATALOG</code> subclause, the variable name will be added to a newline-delimited sequence of names stored in another environment variable, designated by <code><listVariableName></code>~~. This~~ can be useful for later iteration (see below). A simple <code>VAR</code> example: <pre>custom dialog var subjectName "Subject Name:" {} default test minimum 1</pre>		: This creates a text field that the user can fill in. If you supply a <code>DEFAULT</code> subclause, the specified default text is pre-filled. If you specify a <code>MINIMUM</code> number of characters, the dialog buttons (except for the designated <code>ESCAPE</code> button) will be disabled until this text field contains at least that many characters. If the dialog is completed (by any button other than the designated <code>ESCAPE</code> button) then the environment variable designated by <code><variableName></code> will be set to the contents of the text field. If you supply a <code>CATALOG</code> subclause, the variable name will be added to a newline-delimited sequence of names stored in another environment variable, designated by <code><listVariableName></code> - this can be useful for later iteration (see below). A simple <code>VAR</code> example: <pre>custom dialog var subjectName "Subject Name:" {} default test minimum 1</pre>

	; <code>VAR <variableName> <visibleLabel> {<opt1>\|<opt2>\|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>] [CATALOG <listVariableName>]</code></code>		; <code>VAR <variableName> <visibleLabel> {<opt1>\|<opt2>\|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>] [CATALOG <listVariableName>]</code></code>
Line 128:		Line 128:

	# Create some new parameters		# Create some new parameters
	add parameter Application:Custom%20Stimuli float MinStimulusGap= 100ms 100ms 0 % // minimum gap to use in custom stimulus generation		add parameter Application:Custom%20Stimuli float MinStimulusGap= 100ms 100ms 0 % // minimum gap to use in custom stimulus generation
	add parameter Application:Custom%20Stimuli float MaxStimulusGap= 400ms 400ms 0 % // maximum gap to use in custom stimulus generation		add parameter Application:Custom%20Stimuli float MaxStimulusGap= 400ms 400ms 0 % // maximum gap to use in custom stimulus generation


	# In the dialog, some entries will be environment variables with exactly ~~the~~		# In the dialog, some entries will be environment variables with exactly
	# same names as parameters - let's catalog these		# the same names as parameters - let's catalog these
	if [ ${		if [ ${
	custom dialog		custom dialog
Line 148:		Line 148:
	# ...		# ...

	~~for var in $DialogParams~~ # The catalog saves ~~you~~ from having to hard-code a list of the new parameter names a third time.		# The catalog saves us from having to hard-code a list of the new parameter names a third time:
	set parameter $var ${$var} # We chose the environment variable names to be the same as the corresponding parameter names.		for var in $DialogParams
			set parameter $var ${$var}
			# We chose the environment variable names to be the same as the corresponding parameter names.
	end		end

	~~load parameterfile $RunType~~ # This dialog variable is handled differently, so we did not catalog it with the others.		# This dialog variable is handled differently, so we did not catalog it with the others:
			load parameterfile $RunType

	</pre>		</pre>

	Notes: In the example above, we have used just one catalog variable, <code>DialogParams</code>, but you are free to use more than one if you want to assemble separate lists of variables for different purposes. The <code>CUSTOM DIALOG</code> command clears each catalog variable the first time it uses it (so, you can run the example above multiple times, and <code>DialogParams</code> will still only contain one copy of each name). Catalog variables get cleared and filled regardless of whether the dialog is accepted or cancelled.		Notes: In the example above, we have used just one catalog variable, <code>DialogParams</code>, but you are free to use more than one if you want to assemble separate lists of variables for different purposes. The <code>CUSTOM DIALOG</code> command clears each catalog variable the first time it uses it (so, you can run the example above multiple times, and <code>DialogParams</code> will still only contain one copy of each name). Catalog variables get cleared and (re-)filled regardless of whether the dialog is accepted or cancelled.

Jhill: /* CUSTOM DIALOG ... */

2026-01-07T16:03:07Z

CUSTOM DIALOG ...

@@ Line 52: / Line 52: @@
 : Each message is rendered as text, word-wrapped to the width of the dialog window. <code>MESSAGE ""</code> can be used to create blank vertical space. Any message that consists only of dashes (e.g. <code>MESSAGE ---</code>) will be turned into a horizontal rule. Simplest example: <pre>custom dialog message "Hello world!"</pre>
-; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code>
+; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>] [CATALOG <listVariableName>]</code>
-: This creates a text field that the user can fill in.  If you supply a <code>DEFAULT</code> subclause, the specified default text is pre-filled. If you specify a <code>MINIMUM</code> number of characters, the dialog buttons (except for the designated <code>ESCAPE</code> button) will be disabled until this text field contains at least that many characters. If the dialog is completed (by any button other than the designated <code>ESCAPE</code> button) then the environment variable designated by <code><variableName></code> will be set to the contents of the text field. For example: <pre>custom dialog var subjectName "Subject Name:" {} default test minimum 1</pre>
+: This creates a text field that the user can fill in.  If you supply a <code>DEFAULT</code> subclause, the specified default text is pre-filled. If you specify a <code>MINIMUM</code> number of characters, the dialog buttons (except for the designated <code>ESCAPE</code> button) will be disabled until this text field contains at least that many characters. If the dialog is completed (by any button other than the designated <code>ESCAPE</code> button) then the environment variable designated by <code><variableName></code> will be set to the contents of the text field. If you supply a <code>CATALOG</code> subclause, the variable name will be added to a newline-delimited sequence of names stored in another environment variable, designated by <code><listVariableName></code>.  This can be useful for later iteration (see below).   A simple <code>VAR</code> example: <pre>custom dialog var subjectName "Subject Name:" {} default test minimum 1</pre>
-; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code>
+; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>] [CATALOG <listVariableName>]</code></code>
 : This is almost the same as the text-field <code>VAR</code> example above, except that the braces are not empty: the <code>|</code>-delimited option labels inside the braces are then rendered as a drop-down menu with the specified limited set of options.  The <code>DEFAULT</code> subclause, if provided, determines which option is pre-selected (if it is omitted, or the <code><defaultOption></code> does not match any of the options, then the first option is pre-selected).  The <code>MINIMUM</code> subclause can be used, in conjunction with an empty first/default option, to force the user to make an explicit selection, as in the following example (note the leading <code>|</code> character inside the braces): <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre>
@@ Line 120: / Line 120: @@
 [[File:CustomDialogExample.png]]

Jhill: /* CUSTOM DIALOG ... */

2025-10-10T15:59:26Z

CUSTOM DIALOG ...

← Older revision		Revision as of 15:59, 10 October 2025
Line 80:		Line 80:

	; <code>CACHEFILE <FILENAME></code>		; <code>CACHEFILE <FILENAME></code>
	: Specifying a cache file allows dialog contents to be made persistent across sessions. If the specified file already exists when the dialog is invoked, it will get run via <code>EXECUTE SCRIPT</code>; if this sets any of the dialog's environment variables, then these new values override the <code>DEFAULT</code> values for the corresponding text fields and drop-down menus. But you do not need to initialize the specified file manually—if it does not exist, nothing is loaded. When the dialog is successfully completed (by any button other than the designated <code>ESCAPE</code> button), <code>WRITE ENVIRONMENT</code> is automatically called to write the corresponding <code>SET ENVIRONMENT</code> statements to the specified file. So, when the same dialog is invoked ~~again~~, these settings will be loaded: the user will see whatever settings they entered/chose ~~the previous~~ time. Example: <pre>custom dialog cachefile vars.bci var subjectName "Subject ID:" {} default Nobody minimum 1 </pre>		: Specifying a cache file allows dialog contents to be made persistent across sessions. If the specified file already exists when the dialog is invoked, it will get run via <code>EXECUTE SCRIPT</code>; if this sets any of the dialog's environment variables, then these new values override the <code>DEFAULT</code> values for the corresponding text fields and drop-down menus. But you do not need to initialize the specified file manually—if it does not exist, nothing is loaded. When the dialog is successfully completed (by any button other than the designated <code>ESCAPE</code> button), <code>WRITE ENVIRONMENT</code> is automatically called to write the corresponding <code>SET ENVIRONMENT</code> statements to the specified file. So, when the same dialog is invoked next time around, these settings will be loaded: the user will see whatever settings they entered/chose this time. Example: <pre>custom dialog cachefile vars.bci var subjectName "Subject ID:" {} default Nobody minimum 1 </pre>

	====Integrated <code>CUSTOM DIALOG</code> example====		====Integrated <code>CUSTOM DIALOG</code> example====

Jhill: /* CUSTOM DIALOG ... */

2025-10-10T15:58:33Z

CUSTOM DIALOG ...

← Older revision		Revision as of 15:58, 10 October 2025
Line 80:		Line 80:

	; <code>CACHEFILE <FILENAME></code>		; <code>CACHEFILE <FILENAME></code>
	: Specifying a cache file allows dialog contents to be made persistent across sessions. If the specified file already exists when the dialog is invoked, ~~the file gets~~ run ~~with~~ <code>EXECUTE SCRIPT</code>; if this sets any of the dialog's environment variables, then these new values override the <code>DEFAULT</code> values for the corresponding text fields and drop-down menus. When the dialog is successfully completed (by any button other than the designated <code>ESCAPE</code> button), <code>WRITE ENVIRONMENT</code> is automatically called to write the corresponding <code>SET ENVIRONMENT</code> statements to the specified file. So, when the same dialog is invoked again, these settings will be loaded: the user will see whatever settings they entered/chose the previous time. Example: <pre>custom dialog cachefile vars.bci var subjectName "Subject ID:" {} default Nobody minimum 1 </pre>		: Specifying a cache file allows dialog contents to be made persistent across sessions. If the specified file already exists when the dialog is invoked, it will get run via <code>EXECUTE SCRIPT</code>; if this sets any of the dialog's environment variables, then these new values override the <code>DEFAULT</code> values for the corresponding text fields and drop-down menus. But you do not need to initialize the specified file manually—if it does not exist, nothing is loaded. When the dialog is successfully completed (by any button other than the designated <code>ESCAPE</code> button), <code>WRITE ENVIRONMENT</code> is automatically called to write the corresponding <code>SET ENVIRONMENT</code> statements to the specified file. So, when the same dialog is invoked again, these settings will be loaded: the user will see whatever settings they entered/chose the previous time. Example: <pre>custom dialog cachefile vars.bci var subjectName "Subject ID:" {} default Nobody minimum 1 </pre>

	====Integrated <code>CUSTOM DIALOG</code> example====		====Integrated <code>CUSTOM DIALOG</code> example====

Jhill: /* Integrated CUSTOM DIALOG example */

2025-10-09T02:08:59Z

Integrated CUSTOM DIALOG example

← Older revision		Revision as of 02:08, 9 October 2025
Line 94:		Line 94:
	title "Auditory BCI Launcher"		title "Auditory BCI Launcher"
	cachefile "${parent directory $0}/launcherDialogVars.bci"		cachefile "${parent directory $0}/launcherDialogVars.bci"
	var subjectName "Subject ID:" {} default "$subjectName"		var subjectName "Subject ID:" {} default "$subjectName" minimum 1
	var runType "Run Type:" {Calibration\|Free Selection}		var runType "Run Type:" {Calibration\|Free Selection}
	var condition "Stimulus Condition:" {SlowStimuli.prm\|FastStimuli.prm}		var condition "Stimulus Condition:" {SlowStimuli.prm\|FastStimuli.prm}

Jhill: /* Integrated CUSTOM DIALOG example */

2025-10-08T23:33:23Z

Integrated CUSTOM DIALOG example

← Older revision		Revision as of 23:33, 8 October 2025
Line 94:		Line 94:
	title "Auditory BCI Launcher"		title "Auditory BCI Launcher"
	cachefile "${parent directory $0}/launcherDialogVars.bci"		cachefile "${parent directory $0}/launcherDialogVars.bci"
	var subjectName "Subject ID:" {} default "$subjectName"		var subjectName "Subject ID:" {} default "$subjectName"
	var runType "Run Type:" {Calibration\|Free Selection}		var runType "Run Type:" {Calibration\|Free Selection}
	var ~~stimulusCondition~~ "Stimulus Condition:" {SlowStimuli.prm\|FastStimuli.prm}		var condition "Stimulus Condition:" {SlowStimuli.prm\|FastStimuli.prm}
	message "NB: each condition should be calibrated separately."		message "NB: each condition should be calibrated separately."
	buttons {Quit\|Launch} default Launch escape Quit		buttons {Quit\|Launch} default Launch escape Quit

Jhill: /* CUSTOM DIALOG ... */

2025-10-08T23:32:29Z

CUSTOM DIALOG ...

← Older revision		Revision as of 23:32, 8 October 2025
Line 80:		Line 80:

	; <code>CACHEFILE <FILENAME></code>		; <code>CACHEFILE <FILENAME></code>
	: Specifying a cache file allows dialog contents to be made persistent across sessions. If the specified file already exists when the dialog is invoked, the file gets run with <code>EXECUTE SCRIPT</code>; if this sets any of the dialog's environment variables, then these new values override the <code>DEFAULT</code> values for the corresponding text fields and drop-down menus. When the dialog is successfully completed (by any button other than the designated <code>ESCAPE</code> button), <code>WRITE ENVIRONMENT</code> is automatically called to write the corresponding <code>SET ENVIRONMENT</code> statements to the specified file. So, when the same dialog is invoked again, these settings will be loaded: the user will see whatever settings they entered/chose the previous time.		: Specifying a cache file allows dialog contents to be made persistent across sessions. If the specified file already exists when the dialog is invoked, the file gets run with <code>EXECUTE SCRIPT</code>; if this sets any of the dialog's environment variables, then these new values override the <code>DEFAULT</code> values for the corresponding text fields and drop-down menus. When the dialog is successfully completed (by any button other than the designated <code>ESCAPE</code> button), <code>WRITE ENVIRONMENT</code> is automatically called to write the corresponding <code>SET ENVIRONMENT</code> statements to the specified file. So, when the same dialog is invoked again, these settings will be loaded: the user will see whatever settings they entered/chose the previous time. Example: <pre>custom dialog cachefile vars.bci var subjectName "Subject ID:" {} default Nobody minimum 1 </pre>

	====Integrated <code>CUSTOM DIALOG</code> example====		====Integrated <code>CUSTOM DIALOG</code> example====
Line 89:		Line 89:
	# [start up modules]		# [start up modules]
	# [load baseline parameters for this BCI]		# [load baseline parameters for this BCI]
	~~# [optionally, you could pre-initialize environment variables subjectName, runType and stimulusCondition]~~


	set environment launcherAction ${		set environment launcherAction ${
	custom dialog		custom dialog
	title "Auditory BCI Launcher"		title "Auditory BCI Launcher"
	var subjectName "Subject ID:" {} default $subjectName ~~minimum 1~~		cachefile "${parent directory $0}/launcherDialogVars.bci"
	var runType "Run Type:" {Calibration\|Free Selection} ~~default $runType~~		var subjectName "Subject ID:" {} default "$subjectName"
	var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm\|FastStimuli.prm} ~~default $stimulusCondition~~		var runType "Run Type:" {Calibration\|Free Selection}
			var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm\|FastStimuli.prm}
	message "NB: each condition should be calibrated separately."		message "NB: each condition should be calibrated separately."
	buttons {Quit\|Launch} default Launch escape Quit		buttons {Quit\|Launch} default Launch escape Quit

Jhill: /* CUSTOM DIALOG ... */

2025-10-08T03:31:16Z

CUSTOM DIALOG ...

← Older revision		Revision as of 03:31, 8 October 2025
Line 78:		Line 78:
	; <code>TOP <N></code>		; <code>TOP <N></code>
	: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.		: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.


	; <code>CACHEFILE <FILENAME></code>		; <code>CACHEFILE <FILENAME></code>

Jhill: /* CUSTOM DIALOG ... */

2025-10-08T03:30:30Z

CUSTOM DIALOG ...

← Older revision		Revision as of 03:30, 8 October 2025
Line 79:		Line 79:
	: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.		: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.


			; <code>CACHEFILE <FILENAME></code>
			: Specifying a cache file allows dialog contents to be made persistent across sessions. If the specified file already exists when the dialog is invoked, the file gets run with <code>EXECUTE SCRIPT</code>; if this sets any of the dialog's environment variables, then these new values override the <code>DEFAULT</code> values for the corresponding text fields and drop-down menus. When the dialog is successfully completed (by any button other than the designated <code>ESCAPE</code> button), <code>WRITE ENVIRONMENT</code> is automatically called to write the corresponding <code>SET ENVIRONMENT</code> statements to the specified file. So, when the same dialog is invoked again, these settings will be loaded: the user will see whatever settings they entered/chose the previous time.

	====Integrated <code>CUSTOM DIALOG</code> example====		====Integrated <code>CUSTOM DIALOG</code> example====