https://www.bci2000.org/wiki/api.php?action=feedcontributions&feedformat=atom&user=JhillBCI2000 Wiki - User contributions [en]2026-06-09T04:46:41ZUser contributionsMediaWiki 1.43.6https://www.bci2000.org/mediawiki/index.php?title=Contributions:SerialInterface&diff=12439Contributions:SerialInterface2026-05-12T17:44:53Z<p>Jhill: /* SkipUnrecognizedBytes */</p>
<hr />
<div>==Synopsis==<br />
An extension that allows flexible communication to and from serial-port devices such as programmable microcontrollers (e.g. Arduino, Teensy, Pico, etc.)<br />
<br />
==Location==<br />
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/SerialInterface<br />
<br />
==Versioning==<br />
<br />
===Authors===<br />
Jeremy Hill (hill@neurotechcenter.org)<br />
<br />
<br />
===Version History===<br />
* 2023-08-10: Initial public release<br />
* 2025-06-13: SerialInput parameter added, expanding the options for two-way communication.<br />
<br />
===Source Code Revisions===<br />
*Initial development: r7523<br />
*Known to compile under: r8888<br />
*Broken since: --<br />
<br />
==Functional Description==<br />
Among the biosignal acquisition devices supported by BCI2000, a few allow "digital output", i.e. the generation of TTL pulses that might be used to trigger or otherwise synchronize with other devices; most, however, do not offer this functionality. Furthermore, many devices support ''acquisition'' of TTL pulses and other auxiliary information alongside biosignal data; however, some devices lack even this capability.<br />
<br />
Where such functionality is lacking, one flexible option for adding it to your system is to build and program a custom solution based on a microcontroller such as an Arduino, Teensy or Pico (hereafter referred to as a "widget"). The SerialInterface extension allows BCI2000 to interface with such widgets.<br />
<br />
The primary intended purpose of the SerialInterface is to send arbitrary byte strings to a widget over a serial port whenever specified BCI2000 [[User Reference:Expression Syntax|Expressions]] become true—this is a simple way in which digital-output functionality may be supplied for hardware that lacks it. This mechanism could also allow your BCI system to control almost anything you can imagine attaching to a custom microcontroller. Since the outgoing byte strings can be configured arbitrarily, you might possibly be able to make this work even if you cannot (re-)program the widget yourself.<br />
<br />
A secondary function of the SerialInterface is to receive and log [[Programming Reference:Events|Event]] information. This can be done in two ways: either by supplying a fixed set of byte strings that BCI2000 should respond to when it receives them from the widget, or by having the widget send actual BCI2000 event descriptors. For the latter, the widget must be programmed to output strings in the format that BCI2000 will understand. If you have the ability to re-program your widget, then you may also optionally make the widget define its own BCI2000 Parameters and Events. Together, these mechanisms allow information from arbitrary sensors to be sent to BCI2000, mediated by a programmable widget.<br />
<br />
An example BCI2000-compatible microcontroller sketch, for the Arduino IDE, is provided in [https://bci2000.org/svn/trunk/src/contrib/Extensions/SerialInterface/TTLExampleSketch/ the TTLExampleSketch subdirectory]. It makes use of [https://www.arduino.cc/reference/en/libraries/keyhole the Keyhole library], which can be installed via the IDE's library manager and which makes it easy for sketches to respond to serial-port commands and to allow their variables to be read and written.<br />
<br />
Note that the SerialInterface Extension is intended to provide ''auxiliary'' input/output functionality to source modules that acquire their primary signal elsewhere. If you also want to acquire the ''primary'' signal from the same widget, you should use the closely-related [[Contributions:SerialWidgetADC|SerialWidgetADC]], which is part of the SerialWidget signal-source module and which requires a more-sophisticated sketch.<br />
<br />
==Enabling SerialInterface==<br />
<br />
[[User_Reference:Logging_Input|Like all Extensions]], SerialInterface is only available if your signal source module was compiled with the appropriate CMake flag enabled: in this case, <code>EXTENSIONS_SERIALINTERFACE=ON</code>.<br />
<br />
Then, when you launch BCI2000, SerialInterface must be enabled by supplying a value for the <code>--SerialPort</code> parameter [[User_Reference:Module_Command_Line_Options#Specifying_Options|on the command-line]]. For example, in a [[User_Reference:Operator_Module_Scripting|BCI2000 script]], you might use the line:<br />
start executable SignalGenerator --local --SerialPort=COM4:baud=9600,dtr=on<br />
<br />
In the example above, note that a suffix has been appended to the usual serial-port address <code>COM4</code>, attached by a colon. In this optional suffix, you can specify a comma-separated list of options as understood by the Windows <code>MODE</code> command (see [https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-buildcommdcba#parameters Microsoft's documentation for the configuration string passed to the BuildCommDCBA() function]). These options may or may not be necessary for your widget—for example, we have found that the Teensy microcontroller does not seem to care whether the <code>dtr</code> option is on or off; however, the Pico will not work properly unless this option is explicitly turned on, whereas the ItsyBitsy M4 will fail to communicate if it ''is'' turned on.<br />
<br />
==Defining BCI2000 Parameters and Events from the Widget==<br />
If you want your widget to define its own BCI2000 Parameters and Events, the widget must be programmed to send this information to BCI2000 on command, and you can specify exactly what sequence of bytes the command comprises. To ensure that the chosen command is sent to the widget during the [[Programming_Reference:GenericFilter_Class#Publish|"Publish" phase]] of BCI2000 startup, you should specify it as the <code>--PublishCommand</code> parameter, again on the command line:<br />
start executable SignalGenerator --local --SerialPort=COM4:baud=9600,dtr=on --PublishCommand=publish\n<br />
<br />
The particular byte sequence <code>publish\n</code> works with <code>TTLExampleSketch.ino</code>. <br />
<br />
When the widget receives the publish command, it must reply with one or more lines of text. BCI2000 will attempt to interpret any line containing the <code>=</code> character as a [[Technical_Reference:Parameter_Definition|Parameter definition]], and any other non-empty line as an [[Programming_Reference:Events#Implementation|Event definition]]. The widget must send a blank line (terminated with <code>\n</code> or <code>\r\n</code>) to signify the end of the definitions (if your sketch omits this, BCI2000 will hang indefinitely, waiting for more definitions).<br />
<br />
A widget Parameter definition may be specified as <code>(readonly)</code>, in which case the Parameter may be of any type and will not be editable by the user. Such read-only parameters are a means by which the widget can make annotations that will be stored in data files' parameter headers (e.g. information about microcontroller model or sketch version). On the other hand, if the <code>(readonly)</code> flag is ''not'' found in the Parameter definition comment, the Parameter will actually be configurable by the user: in this case, only <code>int</code>, <code>float</code> and <code>string</code> Parameters are allowed. If the widget defines configurable Parameters, Parameter values will be sent to the widget when the user presses "Set Config", using strings of the following format:<br />
Foo=1\n<br />
Bar=3.0\n<br />
Boo="this is a string parameter value"\n<br />
<br />
In that case, your widget sketch must be able to interpret such commands (the [https://www.arduino.cc/reference/en/libraries/keyhole Keyhole] library makes this easy, as shown in the example sketch).<br />
<br />
You may also chose to specify a '''ParameterUpdateCommand''': if so, the specified bytes will be sent to the widget in the [[Programming_Reference:GenericFilter_Class#StopRun|"StopRun" phase]], to request updates to the values of widget-defined parameters. When the widget receives the specified parameter-update command, just as with the publish command, it must reply with a sequence of lines terminated by a blank line. As before, if you choose to use this option, BCI2000 will hang until it receives that final blank line. This time, however, the non-blank lines are expected to have the same syntax as the lines that were sent ''to'' the widget on Set Config, e.g. <code>Foo=123</code> or <code>Boo="some string"</code>. Note that you can only update parameters that the widget itself has previously declared, and you cannot update a parameter that was declared as <code>(readonly)</code>.<br />
<br />
==Parameters==<br />
If enabled using the <code>--SerialPort</code> command-line parameter, the full set of SerialInterface's parameters (described below) will appear in the Source tab of BCI2000's Config window. In addition, any Parameters defined by the widget itself, in response to a <code>--PublishCommand</code>, will appear in whichever tabs and sections their definitions dictate.<br />
<br />
Note that, wherever a SerialInterface Parameter specifies a byte string to be sent to the widget, the byte string may be expressed using backslash escapes familiar to the C/C++ or Python programmer: <code>\n</code>, <code>\r</code>, <code>\t</code>, <code>\0</code>, <code>\\</code> and <code>\xNN</code> are all recognized, where <code>NN</code> stands for a pair of hex digits (these are interpreted like Python, not like C—in other words, the maximum expected number of digits is 2). Other backslash escapes are not supported (so, use <code>\x07</code> instead of <code>\a</code>, use<code>\x0B</code> instead of <code>\v</code>, etc.). If your widget sketch uses the Keyhole library, commands are expected to end with either a newline <code>\n</code> or a semicolon <code>;</code> (but in a BCI2000 script, semicolons mean something to the script interpreter, so you would have to ensure they're used in quotes).<br />
<br />
===SerialPort===<br />
This string specifies the port address, optionally followed by a colon and a comma-delimited sequence of serial port options as described above. This must be [[User_Reference:Module_Command_Line_Options#Specifying_Options|specified on the command-line when the signal source module is launched]] and its value cannot be changed without quitting and relaunching BCI2000. If this parameter is absent or its value is empty, the SerialInterface extension is entirely disabled.<br />
<br />
===PublishCommand===<br />
This optional string specifies the sequence of bytes that should be sent by BCI2000 to request Parameter and Event definitions from the widget. If used, this must be [[User_Reference:Module_Command_Line_Options#Specifying_Options|specified on the command-line when the signal source module is launched]]. Its value cannot be changed without quitting and relaunching BCI2000.<br />
<br />
===StartCommand===<br />
If specified, this sequence of bytes is sent to the widget whenever a run is started (e.g. when Start or Resume is pressed).<br />
With <code>TTLExampleSketch.ino</code>, the string <code>mute=0\n</code> can be used, although the sketch will work on most microcontrollers even without a StartCommand and StopCommand.<br />
<br />
===StopCommand===<br />
If specified, this sequence of bytes is sent to the widget whenever a run stops (e.g. when Suspend is pressed) and also when Set Config is pressed.<br />
With <code>TTLExampleSketch.ino</code>, the string <code>mute=1\n</code> can be used, although the sketch will work on most microcontrollers even without a StartCommand and StopCommand.<br />
<br />
===ParameterUpdateCommand===<br />
If specified, this sequence of bytes is sent to the widget whenever a run stops (e.g. when Suspend is pressed).<br />
As with the '''PublishCommand''', BCI2000 will then expect the widget to reply with a sequence of lines, terminated by a blank line. Each line is expected to be of the format <code>ParameterName = VALUE</code>, where <code>ParameterName</code> must denote a writeable parameter previously declared by the widget, and <code>VALUE</code> can be a simple numeric value or string (quoted and backslash-escaped if necessary).<br />
This allows new parameter values to be carried over from one run to the next.<br />
<br />
===SerialInputs===<br />
This matrix parameter gives BCI2000 the limited ability to respond to serial-port messages sent by the widget, even if you cannot re-program your widget.<br />
<br />
If not empty, the matrix must have four columns. The first column contains (backslash-escaped) byte strings that the widget might send to BCI2000. The second column contains names of State Variables that have been declared as [[Programming_Reference:Events|Events]] (perhaps using [[User_Reference:Operator_Module_Scripting#ADD_EVENT_<name>_<bit_width>_<initial_value>|<code>ADD EVENT</code>]] in your launcher script). The third column contains the integer value that should be assigned to the Event when the byte string is received. In the fourth column, the entry should either be left blank (in which case, the Event will remain at the assigned value until it is changed again) or set to 0 (in which case the Event is transient, remaining at the assigned value only for one sample before automatically returning to 0). Thus, the second, third and fourth columns can be read from left to right as a [[Programming_Reference:Events#Descriptor_Syntax|BCI2000 Event descriptor]], like <code>MyEvent 123</code> or <code>MyEvent 123 0</code><br />
<br />
A given byte string is allowed to appear more than once in the table, to trigger multiple Events simultaneously. The Event name (second column) is allowed to be blank, to enable a particular byte string to be recognized but ignored.<br />
<br />
Note that the '''SerialInputs''' mechanism is designed to be very generic, and as such it is not necessarily possible to tailor it to the particular protocol your widget uses. For example, BCI2000 will not know how the widget likes to terminate messages unless you explicitly include the terminator bytes (so, if <code>shutdown</code> and <code>shutdown-gracefully</code> are both configured, the longer command will never be recognized: BCI2000 will greedily recognize and obey <code>shutdown</code> before attempting to move on to <code>-gracefully</code>). The limitations of the '''SerialInputs''' table also make themselves felt if the widget sends a byte string that you have omitted from the table. Then, one of two compromises must be accepted (see the description of the '''SkipUnrecognizedBytes''' parameter, below). In general, it is not possible to support a serial protocol that includes variable values (unless you create a separate '''SerialInputs''' row for every possible combination of values).<br />
<br />
===SkipUnrecognizedBytes===<br />
This boolean parameter determines what happens if you are using the '''SerialInputs''' table to recognize messages from the widget, and the widget sends you a string that is not recognized. Either choice can have unfortunate consequences, depending on your widget's protocol.<br />
<br />
If the '''SkipUnrecognizedBytes''' parameter is set to false (unchecked), then the data coming from the widget will continue to build into an ever-lengthening unrecognized command: BCI2000 will not recognize another '''SerialInputs''' byte string at all until the SerialInterface is reset (which happens at the start of a run if SerialInterface is running as an Extension, or when Set Config is pressed if you are running SerialWidgetADC).<br />
<br />
If '''SkipUnrecognizedBytes''' is set to true (checked), then it will be possible to discard unrecognized bytes and match a known string, but with the danger that substrings of ''un''recognized commands could be falsely recognized as commands. For example, if you have enabled '''SkipUnrecognizedBytes''', and you have listed the command <code>arm_stimulator</code> in '''SerialInputs''' but ''not'' <code>disarm_stimulator</code>, and the widget then happens to send <code>disarm_stimulator</code>, then BCI2000 will discard the bytes <code>dis</code> and recognize <code>arm_stimulator</code>, leading to the opposite of the intended effect. Clearly, this is a function of how the widget's protocol is designed. To avoid such situations, you must either (a) ensure that the entries in the '''SerialInputs''' table exhaustively cover the repertoire of possible widget outputs (don't worry, if a known longer string gets matched, its embedded substrings will not get matched), or (b) accept the consequences of disabling '''SkipUnrecognizedBytes'''. An even more robust option, if possible, is (c) to leave the '''SerialInputs''' table empty and re-program your widget to send BCI2000 event descriptors directly as text (see the [[#State Variables|State Variables]] section, below).<br />
<br />
===SerialOutputs===<br />
This matrix parameter gives BCI2000 the ability to send messages to the widget whenever specified contingencies are met.<br />
<br />
If not empty, the matrix must have two columns. The first column contains [[User Reference:Expression Syntax|Expressions]]. The second column contains (backslash-escaped) byte strings. Expressions are evaluated at the beginning of each sample-block. If an Expression was previously zero and now evaluates to non-zero, the corresponding byte string is immediately sent to the widget. In this way, you can link a BCI2000 State Variable to a widget command that, for example, causes a TTL pulse to be generated.<br />
<br />
If you are using <code>TTLExampleSketch.ino</code>, you would associate Expressions with the commands <code>output=1\n</code> and <code>output=0\n</code>. For example, let's assume you have defined your own State Variable called <code>StimTrigger</code>. Then your '''SerialOutputs''' parameter might look as shown in the screenshot:<br />
<br />
[[File:SerialOutputs.PNG]]<br />
<br />
===ElseIf===<br />
This parameter dictates the logic by which the rows of the '''SerialOutputs''' Parameter are processed.<br />
You may choose to process all rows on every sample-block (and potentially send all byte strings, one after the other);<br />
alternatively, you may choose to stop after the first matching row (so, on any given sample-block, at most one of the byte strings will be sent).<br />
Possible values are 0 ("process all rows") or 1 ("stop at the first match").<br />
<br />
==State Variables==<br />
<br />
The SerialInterface does not define any State Variables or Events of its own, but will define any [[#Defining BCI2000 Parameters and Events from the Widget|Events the widget tells it to define]] in response to a <code>--PublishCommand</code>.<br />
<br />
During a run, a widget may change an Event value at any time by sending an [[Programming_Reference:Events#Descriptor_Syntax|Event descriptor line]]: usually, this is the name of the event, followed by a space, followed by the value expressed as decimal text, followed by a line-ending. Optionally, an Event descriptor may contain an additional space and a zero, to indicate an instantaneous transient event. For example, <code>TTLExampleSketch.ino</code> will send <br />
TTLInput 1\r\n<br />
whenever the voltage on its input pin changes from low to high, and<br />
TTLInput 0\r\n<br />
PulseDurationMsec 123 0\r\n<br />
whenever the voltage changes from high to low (where 123 is a place-holder for however long the input pulse in fact lasted, according to the widget's millisecond timer).<br />
<br />
Note that it is not necessary for the Event in question to have been defined by the widget itself—it could have been added by one of the other filters and loggers, or in your [[User_Reference:Operator_Module_Scripting|BCI2000 script]] using [[User_Reference:Operator_Module_Scripting#ADD_EVENT_<name>_<bit_width>_<initial_value>|an <code>ADD EVENT</code> command]] before the <code>STARTUP SYSTEM</code> line. This means you do not necessarily have to implement the widget's response to a <code>--PublishCommand</code>, even if you are planning to use the widget to log Events.<br />
<br />
If you cannot re-program the widget at all, you may still have some (limited) options for triggering Events in response to messages from the widget, via the '''SerialInputs''' parameter.<br />
<br />
==See also==<br />
[[Contributions:SerialWidgetADC]]<br />
<br />
[[Category:Contributions]][[Category:Extension]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:SerialInterface&diff=12438Contributions:SerialInterface2026-05-12T17:40:41Z<p>Jhill: </p>
<hr />
<div>==Synopsis==<br />
An extension that allows flexible communication to and from serial-port devices such as programmable microcontrollers (e.g. Arduino, Teensy, Pico, etc.)<br />
<br />
==Location==<br />
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/SerialInterface<br />
<br />
==Versioning==<br />
<br />
===Authors===<br />
Jeremy Hill (hill@neurotechcenter.org)<br />
<br />
<br />
===Version History===<br />
* 2023-08-10: Initial public release<br />
* 2025-06-13: SerialInput parameter added, expanding the options for two-way communication.<br />
<br />
===Source Code Revisions===<br />
*Initial development: r7523<br />
*Known to compile under: r8888<br />
*Broken since: --<br />
<br />
==Functional Description==<br />
Among the biosignal acquisition devices supported by BCI2000, a few allow "digital output", i.e. the generation of TTL pulses that might be used to trigger or otherwise synchronize with other devices; most, however, do not offer this functionality. Furthermore, many devices support ''acquisition'' of TTL pulses and other auxiliary information alongside biosignal data; however, some devices lack even this capability.<br />
<br />
Where such functionality is lacking, one flexible option for adding it to your system is to build and program a custom solution based on a microcontroller such as an Arduino, Teensy or Pico (hereafter referred to as a "widget"). The SerialInterface extension allows BCI2000 to interface with such widgets.<br />
<br />
The primary intended purpose of the SerialInterface is to send arbitrary byte strings to a widget over a serial port whenever specified BCI2000 [[User Reference:Expression Syntax|Expressions]] become true—this is a simple way in which digital-output functionality may be supplied for hardware that lacks it. This mechanism could also allow your BCI system to control almost anything you can imagine attaching to a custom microcontroller. Since the outgoing byte strings can be configured arbitrarily, you might possibly be able to make this work even if you cannot (re-)program the widget yourself.<br />
<br />
A secondary function of the SerialInterface is to receive and log [[Programming Reference:Events|Event]] information. This can be done in two ways: either by supplying a fixed set of byte strings that BCI2000 should respond to when it receives them from the widget, or by having the widget send actual BCI2000 event descriptors. For the latter, the widget must be programmed to output strings in the format that BCI2000 will understand. If you have the ability to re-program your widget, then you may also optionally make the widget define its own BCI2000 Parameters and Events. Together, these mechanisms allow information from arbitrary sensors to be sent to BCI2000, mediated by a programmable widget.<br />
<br />
An example BCI2000-compatible microcontroller sketch, for the Arduino IDE, is provided in [https://bci2000.org/svn/trunk/src/contrib/Extensions/SerialInterface/TTLExampleSketch/ the TTLExampleSketch subdirectory]. It makes use of [https://www.arduino.cc/reference/en/libraries/keyhole the Keyhole library], which can be installed via the IDE's library manager and which makes it easy for sketches to respond to serial-port commands and to allow their variables to be read and written.<br />
<br />
Note that the SerialInterface Extension is intended to provide ''auxiliary'' input/output functionality to source modules that acquire their primary signal elsewhere. If you also want to acquire the ''primary'' signal from the same widget, you should use the closely-related [[Contributions:SerialWidgetADC|SerialWidgetADC]], which is part of the SerialWidget signal-source module and which requires a more-sophisticated sketch.<br />
<br />
==Enabling SerialInterface==<br />
<br />
[[User_Reference:Logging_Input|Like all Extensions]], SerialInterface is only available if your signal source module was compiled with the appropriate CMake flag enabled: in this case, <code>EXTENSIONS_SERIALINTERFACE=ON</code>.<br />
<br />
Then, when you launch BCI2000, SerialInterface must be enabled by supplying a value for the <code>--SerialPort</code> parameter [[User_Reference:Module_Command_Line_Options#Specifying_Options|on the command-line]]. For example, in a [[User_Reference:Operator_Module_Scripting|BCI2000 script]], you might use the line:<br />
start executable SignalGenerator --local --SerialPort=COM4:baud=9600,dtr=on<br />
<br />
In the example above, note that a suffix has been appended to the usual serial-port address <code>COM4</code>, attached by a colon. In this optional suffix, you can specify a comma-separated list of options as understood by the Windows <code>MODE</code> command (see [https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-buildcommdcba#parameters Microsoft's documentation for the configuration string passed to the BuildCommDCBA() function]). These options may or may not be necessary for your widget—for example, we have found that the Teensy microcontroller does not seem to care whether the <code>dtr</code> option is on or off; however, the Pico will not work properly unless this option is explicitly turned on, whereas the ItsyBitsy M4 will fail to communicate if it ''is'' turned on.<br />
<br />
==Defining BCI2000 Parameters and Events from the Widget==<br />
If you want your widget to define its own BCI2000 Parameters and Events, the widget must be programmed to send this information to BCI2000 on command, and you can specify exactly what sequence of bytes the command comprises. To ensure that the chosen command is sent to the widget during the [[Programming_Reference:GenericFilter_Class#Publish|"Publish" phase]] of BCI2000 startup, you should specify it as the <code>--PublishCommand</code> parameter, again on the command line:<br />
start executable SignalGenerator --local --SerialPort=COM4:baud=9600,dtr=on --PublishCommand=publish\n<br />
<br />
The particular byte sequence <code>publish\n</code> works with <code>TTLExampleSketch.ino</code>. <br />
<br />
When the widget receives the publish command, it must reply with one or more lines of text. BCI2000 will attempt to interpret any line containing the <code>=</code> character as a [[Technical_Reference:Parameter_Definition|Parameter definition]], and any other non-empty line as an [[Programming_Reference:Events#Implementation|Event definition]]. The widget must send a blank line (terminated with <code>\n</code> or <code>\r\n</code>) to signify the end of the definitions (if your sketch omits this, BCI2000 will hang indefinitely, waiting for more definitions).<br />
<br />
A widget Parameter definition may be specified as <code>(readonly)</code>, in which case the Parameter may be of any type and will not be editable by the user. Such read-only parameters are a means by which the widget can make annotations that will be stored in data files' parameter headers (e.g. information about microcontroller model or sketch version). On the other hand, if the <code>(readonly)</code> flag is ''not'' found in the Parameter definition comment, the Parameter will actually be configurable by the user: in this case, only <code>int</code>, <code>float</code> and <code>string</code> Parameters are allowed. If the widget defines configurable Parameters, Parameter values will be sent to the widget when the user presses "Set Config", using strings of the following format:<br />
Foo=1\n<br />
Bar=3.0\n<br />
Boo="this is a string parameter value"\n<br />
<br />
In that case, your widget sketch must be able to interpret such commands (the [https://www.arduino.cc/reference/en/libraries/keyhole Keyhole] library makes this easy, as shown in the example sketch).<br />
<br />
You may also chose to specify a '''ParameterUpdateCommand''': if so, the specified bytes will be sent to the widget in the [[Programming_Reference:GenericFilter_Class#StopRun|"StopRun" phase]], to request updates to the values of widget-defined parameters. When the widget receives the specified parameter-update command, just as with the publish command, it must reply with a sequence of lines terminated by a blank line. As before, if you choose to use this option, BCI2000 will hang until it receives that final blank line. This time, however, the non-blank lines are expected to have the same syntax as the lines that were sent ''to'' the widget on Set Config, e.g. <code>Foo=123</code> or <code>Boo="some string"</code>. Note that you can only update parameters that the widget itself has previously declared, and you cannot update a parameter that was declared as <code>(readonly)</code>.<br />
<br />
==Parameters==<br />
If enabled using the <code>--SerialPort</code> command-line parameter, the full set of SerialInterface's parameters (described below) will appear in the Source tab of BCI2000's Config window. In addition, any Parameters defined by the widget itself, in response to a <code>--PublishCommand</code>, will appear in whichever tabs and sections their definitions dictate.<br />
<br />
Note that, wherever a SerialInterface Parameter specifies a byte string to be sent to the widget, the byte string may be expressed using backslash escapes familiar to the C/C++ or Python programmer: <code>\n</code>, <code>\r</code>, <code>\t</code>, <code>\0</code>, <code>\\</code> and <code>\xNN</code> are all recognized, where <code>NN</code> stands for a pair of hex digits (these are interpreted like Python, not like C—in other words, the maximum expected number of digits is 2). Other backslash escapes are not supported (so, use <code>\x07</code> instead of <code>\a</code>, use<code>\x0B</code> instead of <code>\v</code>, etc.). If your widget sketch uses the Keyhole library, commands are expected to end with either a newline <code>\n</code> or a semicolon <code>;</code> (but in a BCI2000 script, semicolons mean something to the script interpreter, so you would have to ensure they're used in quotes).<br />
<br />
===SerialPort===<br />
This string specifies the port address, optionally followed by a colon and a comma-delimited sequence of serial port options as described above. This must be [[User_Reference:Module_Command_Line_Options#Specifying_Options|specified on the command-line when the signal source module is launched]] and its value cannot be changed without quitting and relaunching BCI2000. If this parameter is absent or its value is empty, the SerialInterface extension is entirely disabled.<br />
<br />
===PublishCommand===<br />
This optional string specifies the sequence of bytes that should be sent by BCI2000 to request Parameter and Event definitions from the widget. If used, this must be [[User_Reference:Module_Command_Line_Options#Specifying_Options|specified on the command-line when the signal source module is launched]]. Its value cannot be changed without quitting and relaunching BCI2000.<br />
<br />
===StartCommand===<br />
If specified, this sequence of bytes is sent to the widget whenever a run is started (e.g. when Start or Resume is pressed).<br />
With <code>TTLExampleSketch.ino</code>, the string <code>mute=0\n</code> can be used, although the sketch will work on most microcontrollers even without a StartCommand and StopCommand.<br />
<br />
===StopCommand===<br />
If specified, this sequence of bytes is sent to the widget whenever a run stops (e.g. when Suspend is pressed) and also when Set Config is pressed.<br />
With <code>TTLExampleSketch.ino</code>, the string <code>mute=1\n</code> can be used, although the sketch will work on most microcontrollers even without a StartCommand and StopCommand.<br />
<br />
===ParameterUpdateCommand===<br />
If specified, this sequence of bytes is sent to the widget whenever a run stops (e.g. when Suspend is pressed).<br />
As with the '''PublishCommand''', BCI2000 will then expect the widget to reply with a sequence of lines, terminated by a blank line. Each line is expected to be of the format <code>ParameterName = VALUE</code>, where <code>ParameterName</code> must denote a writeable parameter previously declared by the widget, and <code>VALUE</code> can be a simple numeric value or string (quoted and backslash-escaped if necessary).<br />
This allows new parameter values to be carried over from one run to the next.<br />
<br />
===SerialInputs===<br />
This matrix parameter gives BCI2000 the limited ability to respond to serial-port messages sent by the widget, even if you cannot re-program your widget.<br />
<br />
If not empty, the matrix must have four columns. The first column contains (backslash-escaped) byte strings that the widget might send to BCI2000. The second column contains names of State Variables that have been declared as [[Programming_Reference:Events|Events]] (perhaps using [[User_Reference:Operator_Module_Scripting#ADD_EVENT_<name>_<bit_width>_<initial_value>|<code>ADD EVENT</code>]] in your launcher script). The third column contains the integer value that should be assigned to the Event when the byte string is received. In the fourth column, the entry should either be left blank (in which case, the Event will remain at the assigned value until it is changed again) or set to 0 (in which case the Event is transient, remaining at the assigned value only for one sample before automatically returning to 0). Thus, the second, third and fourth columns can be read from left to right as a [[Programming_Reference:Events#Descriptor_Syntax|BCI2000 Event descriptor]], like <code>MyEvent 123</code> or <code>MyEvent 123 0</code><br />
<br />
A given byte string is allowed to appear more than once in the table, to trigger multiple Events simultaneously. The Event name (second column) is allowed to be blank, to enable a particular byte string to be recognized but ignored.<br />
<br />
Note that the '''SerialInputs''' mechanism is designed to be very generic, and as such it is not necessarily possible to tailor it to the particular protocol your widget uses. For example, BCI2000 will not know how the widget likes to terminate messages unless you explicitly include the terminator bytes (so, if <code>shutdown</code> and <code>shutdown-gracefully</code> are both configured, the longer command will never be recognized: BCI2000 will greedily recognize and obey <code>shutdown</code> before attempting to move on to <code>-gracefully</code>). The limitations of the '''SerialInputs''' table also make themselves felt if the widget sends a byte string that you have omitted from the table. Then, one of two compromises must be accepted (see the description of the '''SkipUnrecognizedBytes''' parameter, below). In general, it is not possible to support a serial protocol that includes variable values (unless you create a separate '''SerialInputs''' row for every possible combination of values).<br />
<br />
===SkipUnrecognizedBytes===<br />
This boolean parameter determines what happens if you are using the '''SerialInputs''' table to recognize messages from the widget, and the widget sends you a string that is not recognized. Either choice can have unfortunate consequences, depending on your widget's protocol.<br />
<br />
If the '''SkipUnrecognizedBytes''' parameter is set to false (unchecked), then the data coming from the widget will continue to build into an ever-lengthening unrecognized command: BCI2000 will not recognize another '''SerialInputs''' byte string at all until the SerialInterface is reset (which happens at the start of a run if SerialInterface is running as an Extension, or when Set Config is pressed if you are running SerialWidgetADC).<br />
<br />
If '''SkipUnrecognizedBytes''' is set to true (checked), then it will be possible to discard unrecognized bytes and match a known string, but with the danger that substrings of ''un''recognized commands could be falsely recognized as commands. For example, if you have enabled '''SkipUnrecognizedBytes''', and you have listed the command <code>arm_stimulator</code> in '''SerialInputs''' but ''not'' <code>disarm_stimulator</code>, and the widget then happens to send <code>disarm_stimulator</code>, then BCI2000 will discard the bytes <code>dis</code> and recognize <code>arm_stimulator</code>, leading to the opposite of the intended effect. Clearly, this is a function of how the widget's protocol is designed. To avoid such situations, you must either (a) ensure that the entries in the '''SerialInputs''' table exhaustively cover the repertoire of possible widget outputs (don't worry, if a known longer string gets matched, its substrings will not get matched), or (b) accept the consequences of disabling '''SkipUnrecognizedBytes'''. An even more robust option, if possible, is (c) to leave the '''SerialInputs''' table empty and re-program your widget to send BCI2000 event descriptors directly as text (see the [[#State Variables|State Variables]] section, below).<br />
<br />
===SerialOutputs===<br />
This matrix parameter gives BCI2000 the ability to send messages to the widget whenever specified contingencies are met.<br />
<br />
If not empty, the matrix must have two columns. The first column contains [[User Reference:Expression Syntax|Expressions]]. The second column contains (backslash-escaped) byte strings. Expressions are evaluated at the beginning of each sample-block. If an Expression was previously zero and now evaluates to non-zero, the corresponding byte string is immediately sent to the widget. In this way, you can link a BCI2000 State Variable to a widget command that, for example, causes a TTL pulse to be generated.<br />
<br />
If you are using <code>TTLExampleSketch.ino</code>, you would associate Expressions with the commands <code>output=1\n</code> and <code>output=0\n</code>. For example, let's assume you have defined your own State Variable called <code>StimTrigger</code>. Then your '''SerialOutputs''' parameter might look as shown in the screenshot:<br />
<br />
[[File:SerialOutputs.PNG]]<br />
<br />
===ElseIf===<br />
This parameter dictates the logic by which the rows of the '''SerialOutputs''' Parameter are processed.<br />
You may choose to process all rows on every sample-block (and potentially send all byte strings, one after the other);<br />
alternatively, you may choose to stop after the first matching row (so, on any given sample-block, at most one of the byte strings will be sent).<br />
Possible values are 0 ("process all rows") or 1 ("stop at the first match").<br />
<br />
==State Variables==<br />
<br />
The SerialInterface does not define any State Variables or Events of its own, but will define any [[#Defining BCI2000 Parameters and Events from the Widget|Events the widget tells it to define]] in response to a <code>--PublishCommand</code>.<br />
<br />
During a run, a widget may change an Event value at any time by sending an [[Programming_Reference:Events#Descriptor_Syntax|Event descriptor line]]: usually, this is the name of the event, followed by a space, followed by the value expressed as decimal text, followed by a line-ending. Optionally, an Event descriptor may contain an additional space and a zero, to indicate an instantaneous transient event. For example, <code>TTLExampleSketch.ino</code> will send <br />
TTLInput 1\r\n<br />
whenever the voltage on its input pin changes from low to high, and<br />
TTLInput 0\r\n<br />
PulseDurationMsec 123 0\r\n<br />
whenever the voltage changes from high to low (where 123 is a place-holder for however long the input pulse in fact lasted, according to the widget's millisecond timer).<br />
<br />
Note that it is not necessary for the Event in question to have been defined by the widget itself—it could have been added by one of the other filters and loggers, or in your [[User_Reference:Operator_Module_Scripting|BCI2000 script]] using [[User_Reference:Operator_Module_Scripting#ADD_EVENT_<name>_<bit_width>_<initial_value>|an <code>ADD EVENT</code> command]] before the <code>STARTUP SYSTEM</code> line. This means you do not necessarily have to implement the widget's response to a <code>--PublishCommand</code>, even if you are planning to use the widget to log Events.<br />
<br />
If you cannot re-program the widget at all, you may still have some (limited) options for triggering Events in response to messages from the widget, via the '''SerialInputs''' parameter.<br />
<br />
==See also==<br />
[[Contributions:SerialWidgetADC]]<br />
<br />
[[Category:Contributions]][[Category:Extension]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:SerialInterface&diff=12437Contributions:SerialInterface2026-05-12T17:37:26Z<p>Jhill: /* ElseIf */</p>
<hr />
<div>==Synopsis==<br />
An extension that allows flexible communication to and from serial-port devices such as programmable microcontrollers (e.g. Arduino, Teensy, Pico, etc.)<br />
<br />
==Location==<br />
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/SerialInterface<br />
<br />
==Versioning==<br />
<br />
===Authors===<br />
Jeremy Hill (hill@neurotechcenter.org)<br />
<br />
<br />
===Version History===<br />
* 2023-08-10: Initial public release<br />
* 2025-06-13: SerialInput parameter added, expanding the options for two-way communication.<br />
<br />
===Source Code Revisions===<br />
*Initial development: r7523<br />
*Known to compile under: r8888<br />
*Broken since: --<br />
<br />
==Functional Description==<br />
Among the biosignal acquisition devices supported by BCI2000, a few allow "digital output", i.e. the generation of TTL pulses that might be used to trigger or otherwise synchronize with other devices; most, however, do not offer this functionality. Furthermore, many devices support ''acquisition'' of TTL pulses and other auxiliary information alongside biosignal data; however, some devices lack even this capability.<br />
<br />
Where such functionality is lacking, one flexible option for adding it to your system is to build and program a custom solution based on a microcontroller such as an Arduino, Teensy or Pico (hereafter referred to as a "widget"). The SerialInterface extension allows BCI2000 to interface with such widgets.<br />
<br />
The primary intended purpose of the SerialInterface is to send arbitrary byte strings to a widget over a serial port whenever specified BCI2000 [[User Reference:Expression Syntax|Expressions]] become true—this is a simple way in which digital-output functionality may be supplied for hardware that lacks it. This mechanism could also allow your BCI system to control almost anything you can imagine attaching to a custom microcontroller. Since the outgoing byte strings can be configured arbitrarily, you might possibly be able to make this work even if you cannot (re-)program the widget yourself.<br />
<br />
A secondary function of the SerialInterface is to receive and log [[Programming Reference:Events|Event]] information. This can be done in two ways: either by supplying a fixed set of byte strings that BCI2000 should respond to when it receives them from the widget, or by having the widget send actual BCI2000 event descriptors. For the latter, the widget must be programmed to output strings in the format that BCI2000 will understand. If you have the ability to re-program your widget, then you may also optionally make the widget define its own BCI2000 Parameters and Events. Together, these mechanisms allow information from arbitrary sensors to be sent to BCI2000, mediated by a programmable widget.<br />
<br />
An example BCI2000-compatible microcontroller sketch, for the Arduino IDE, is provided in [https://bci2000.org/svn/trunk/src/contrib/Extensions/SerialInterface/TTLExampleSketch/ the TTLExampleSketch subdirectory]. It makes use of [https://www.arduino.cc/reference/en/libraries/keyhole the Keyhole library], which can be installed via the IDE's library manager and which makes it easy for sketches to respond to serial-port commands and to allow their variables to be read and written.<br />
<br />
Note that the SerialInterface Extension is intended to provide ''auxiliary'' input/output functionality to source modules that acquire their primary signal elsewhere. If you also want to acquire the ''primary'' signal from the same widget, you should use the closely-related [[Contributions:SerialWidgetADC|SerialWidgetADC]], which is part of the SerialWidget signal-source module and which requires a more-sophisticated sketch.<br />
<br />
==Enabling SerialInterface==<br />
<br />
[[User_Reference:Logging_Input|Like all Extensions]], SerialInterface is only available if your signal source module was compiled with the appropriate CMake flag enabled: in this case, <code>EXTENSIONS_SERIALINTERFACE=ON</code>.<br />
<br />
Then, when you launch BCI2000, SerialInterface must be enabled by supplying a value for the <code>--SerialPort</code> parameter [[User_Reference:Module_Command_Line_Options#Specifying_Options|on the command-line]]. For example, in a [[User_Reference:Operator_Module_Scripting|BCI2000 script]], you might use the line:<br />
start executable SignalGenerator --local --SerialPort=COM4:baud=9600,dtr=on<br />
<br />
In the example above, note that a suffix has been appended to the usual serial-port address <code>COM4</code>, attached by a colon. In this optional suffix, you can specify a comma-separated list of options as understood by the Windows <code>MODE</code> command (see [https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-buildcommdcba#parameters Microsoft's documentation for the configuration string passed to the BuildCommDCBA() function]). These options may or may not be necessary for your widget—for example, we have found that the Teensy microcontroller does not seem to care whether the <code>dtr</code> option is on or off; however, the Pico will not work properly unless this option is explicitly turned on, whereas the ItsyBitsy M4 will fail to communicate if it ''is'' turned on.<br />
<br />
==Defining BCI2000 Parameters and Events from the Widget==<br />
If you want your widget to define its own BCI2000 Parameters and Events, the widget must be programmed to send this information to BCI2000 on command, and you can specify exactly what sequence of bytes the command comprises. To ensure that the chosen command is sent to the widget during the [[Programming_Reference:GenericFilter_Class#Publish|"Publish" phase]] of BCI2000 startup, you should specify it as the <code>--PublishCommand</code> parameter, again on the command line:<br />
start executable SignalGenerator --local --SerialPort=COM4:baud=9600,dtr=on --PublishCommand=publish\n<br />
<br />
The particular byte sequence <code>publish\n</code> works with <code>TTLExampleSketch.ino</code>. <br />
<br />
When the widget receives the publish command, it must reply with one or more lines of text. BCI2000 will attempt to interpret any line containing the <code>=</code> character as a [[Technical_Reference:Parameter_Definition|Parameter definition]], and any other non-empty line as an [[Programming_Reference:Events#Implementation|Event definition]]. The widget must send a blank line (terminated with <code>\n</code> or <code>\r\n</code>) to signify the end of the definitions (if your sketch omits this, BCI2000 will hang indefinitely, waiting for more definitions).<br />
<br />
A widget Parameter definition may be specified as <code>(readonly)</code>, in which case the Parameter may be of any type and will not be editable by the user. Such read-only parameters are a means by which the widget can make annotations that will be stored in data files' parameter headers (e.g. information about microcontroller model or sketch version). On the other hand, if the <code>(readonly)</code> flag is ''not'' found in the Parameter definition comment, the Parameter will actually be configurable by the user: in this case, only <code>int</code>, <code>float</code> and <code>string</code> Parameters are allowed. If the widget defines configurable Parameters, Parameter values will be sent to the widget when the user presses "Set Config", using strings of the following format:<br />
Foo=1\n<br />
Bar=3.0\n<br />
Boo="this is a string parameter value"\n<br />
<br />
In that case, your widget sketch must be able to interpret such commands (the [https://www.arduino.cc/reference/en/libraries/keyhole Keyhole] library makes this easy, as shown in the example sketch).<br />
<br />
You may also chose to specify a '''ParameterUpdateCommand''': if so, the specified bytes will be sent to the widget in the [[Programming_Reference:GenericFilter_Class#StopRun|"StopRun" phase]], to request updates to the values of widget-defined parameters. When the widget receives the specified parameter-update command, just as with the publish command, it must reply with a sequence of lines terminated by a blank line. As before, if you choose to use this option, BCI2000 will hang until it receives that final blank line. This time, however, the non-blank lines are expected to have the same syntax as the lines that were sent ''to'' the widget on Set Config, e.g. <code>Foo=123</code> or <code>Boo="some string"</code>. Note that you can only update parameters that the widget itself has previously declared, and you cannot update a parameter that was declared as <code>(readonly)</code>.<br />
<br />
==Parameters==<br />
If enabled using the <code>--SerialPort</code> command-line parameter, the full set of SerialInterface's parameters (described below) will appear in the Source tab of BCI2000's Config window. In addition, any Parameters defined by the widget itself, in response to a <code>--PublishCommand</code>, will appear in whichever tabs and sections their definitions dictate.<br />
<br />
Note that, wherever a SerialInterface Parameter specifies a byte string to be sent to the widget, the byte string may be expressed using backslash escapes familiar to the C/C++ or Python programmer: <code>\n</code>, <code>\r</code>, <code>\t</code>, <code>\0</code>, <code>\\</code> and <code>\xNN</code> are all recognized, where <code>NN</code> stands for a pair of hex digits (these are interpreted like Python, not like C—in other words, the maximum expected number of digits is 2). Other backslash escapes are not supported (so, use <code>\x07</code> instead of <code>\a</code>, use<code>\x0B</code> instead of <code>\v</code>, etc.). If your widget sketch uses the Keyhole library, commands are expected to end with either a newline <code>\n</code> or a semicolon <code>;</code> (but in a BCI2000 script, semicolons mean something to the script interpreter, so you would have to ensure they're used in quotes).<br />
<br />
===SerialPort===<br />
This string specifies the port address, optionally followed by a colon and a comma-delimited sequence of serial port options as described above. This must be [[User_Reference:Module_Command_Line_Options#Specifying_Options|specified on the command-line when the signal source module is launched]] and its value cannot be changed without quitting and relaunching BCI2000. If this parameter is absent or its value is empty, the SerialInterface extension is entirely disabled.<br />
<br />
===PublishCommand===<br />
This optional string specifies the sequence of bytes that should be sent by BCI2000 to request Parameter and Event definitions from the widget. If used, this must be [[User_Reference:Module_Command_Line_Options#Specifying_Options|specified on the command-line when the signal source module is launched]]. Its value cannot be changed without quitting and relaunching BCI2000.<br />
<br />
===StartCommand===<br />
If specified, this sequence of bytes is sent to the widget whenever a run is started (e.g. when Start or Resume is pressed).<br />
With <code>TTLExampleSketch.ino</code>, the string <code>mute=0\n</code> can be used, although the sketch will work on most microcontrollers even without a StartCommand and StopCommand.<br />
<br />
===StopCommand===<br />
If specified, this sequence of bytes is sent to the widget whenever a run stops (e.g. when Suspend is pressed) and also when Set Config is pressed.<br />
With <code>TTLExampleSketch.ino</code>, the string <code>mute=1\n</code> can be used, although the sketch will work on most microcontrollers even without a StartCommand and StopCommand.<br />
<br />
===ParameterUpdateCommand===<br />
If specified, this sequence of bytes is sent to the widget whenever a run stops (e.g. when Suspend is pressed).<br />
As with the '''PublishCommand''', BCI2000 will then expect the widget to reply with a sequence of lines, terminated by a blank line. Each line is expected to be of the format <code>ParameterName = VALUE</code>, where <code>ParameterName</code> must denote a writeable parameter previously declared by the widget, and <code>VALUE</code> can be a simple numeric value or string (quoted and backslash-escaped if necessary).<br />
This allows new parameter values to be carried over from one run to the next.<br />
<br />
===SerialInputs===<br />
This matrix parameter gives BCI2000 the limited ability to respond to serial-port messages sent by the widget, even if you cannot re-program your widget.<br />
<br />
If not empty, the matrix must have four columns. The first column contains (backslash-escaped) byte strings that the widget might send to BCI2000. The second column contains names of State Variables that have been declared as [[Programming_Reference:Events|Events]] (perhaps using [[User_Reference:Operator_Module_Scripting#ADD_EVENT_<name>_<bit_width>_<initial_value>|<code>ADD EVENT</code>]] in your launcher script). The third column contains the integer value that should be assigned to the Event when the byte string is received. In the fourth column, the entry should either be left blank (in which case, the Event will remain at the assigned value until it is changed again) or set to 0 (in which case the Event is transient, remaining at the assigned value only for one sample before automatically returning to 0). Thus, the second, third and fourth columns can be read from left to right as a [[Programming_Reference:Events#Descriptor_Syntax|BCI2000 Event descriptor]], like <code>MyEvent 123</code> or <code>MyEvent 123 0</code><br />
<br />
A given byte string is allowed to appear more than once in the table, to trigger multiple Events simultaneously. The Event name (second column) is allowed to be blank, to enable a particular byte string to be recognized but ignored.<br />
<br />
Note that the '''SerialInputs''' mechanism is designed to be very generic, and as such it is not necessarily possible to tailor it to the particular protocol your widget uses. For example, BCI2000 will not know how the widget likes to terminate messages unless you explicitly include the terminator bytes (so, if <code>shutdown</code> and <code>shutdown-gracefully</code> are both configured, the longer command will never be recognized: BCI2000 will greedily recognize and obey <code>shutdown</code> before attempting to move on to <code>-gracefully</code>). The limitations of the '''SerialInputs''' table also make themselves felt if the widget sends a byte string that you have omitted from the table. Then, one of two compromises must be accepted (see the description of the '''SkipUnrecognizedBytes''' parameter, below). In general, it is not possible to support a serial protocol that includes variable values (unless you create a separate '''SerialInputs''' row for every possible combination of values).<br />
<br />
===SkipUnrecognizedBytes===<br />
This boolean parameter determines what happens if you are using the '''SerialInputs''' table to recognize messages from the widget, and the widget sends you a string that is not recognized. Either choice can have unfortunate consequences, depending on your widget's protocol.<br />
<br />
If the '''SkipUnrecognizedBytes''' parameter is set to false (unchecked), then the data coming from the widget will continue to build into an ever-lengthening unrecognized command: BCI2000 will not recognize another '''SerialInputs''' byte string at all until the SerialInterface is reset (which happens at the start of a run if SerialInterface is running as an Extension, or when Set Config is pressed if you are running SerialWidgetADC).<br />
<br />
If '''SkipUnrecognizedBytes''' is set to true (checked), then it will be possible to discard unrecognized bytes and match a known string, but with the danger that substrings of ''un''recognized commands could be falsely recognized as commands. For example, if you have enabled '''SkipUnrecognizedBytes''', and you have listed the command <code>arm_stimulator</code> in '''SerialInputs''' but ''not'' <code>disarm_stimulator</code>, and the widget then happens to send <code>disarm_stimulator</code>, then BCI2000 will discard the bytes <code>dis</code> and recognize <code>arm_stimulator</code>, leading to the opposite of the intended effect. Clearly, this is a function of how the widget's protocol is designed. To avoid such situations, you must either (a) ensure that the entries in the '''SerialInputs''' table exhaustively cover the repertoire of possible widget outputs (don't worry, if a known longer string gets matched, its substrings will not get matched), or (b) accept the consequences of disabling '''SkipUnrecognizedBytes'''. An even more robust option, if possible, is (c) to leave the '''SerialInputs''' table empty and re-program your widget to send BCI2000 event descriptors directly as text (see the [[#State Variables|State Variables]] section, below).<br />
<br />
===SerialOutputs===<br />
This matrix parameter gives BCI2000 the ability to send messages to the widget whenever specified contingencies are met.<br />
<br />
If not empty, the matrix must have two columns. The first column contains [[User Reference:Expression Syntax|Expressions]]. The second column contains (backslash-escaped) byte strings. Expressions are evaluated at the beginning of each sample-block. If an Expression was previously zero and now evaluates to non-zero, the corresponding byte string is immediately sent to the widget. In this way, you can link a BCI2000 State Variable to a widget command that, for example, causes a TTL pulse to be generated.<br />
<br />
If you are using <code>TTLExampleSketch.ino</code>, you would associate Expressions with the commands <code>output=1\n</code> and <code>output=0\n</code>. For example, let's assume you have defined your own State Variable called <code>StimTrigger</code>. Then your '''SerialOutputs''' parameter might look as shown in the screenshot:<br />
<br />
[[File:SerialOutputs.PNG]]<br />
<br />
===ElseIf===<br />
This parameter dictates the logic by which the rows of the '''SerialOutputs''' Parameter are processed.<br />
You may choose to process all rows on every sample-block (and potentially send all byte strings, one after the other);<br />
alternatively, you may choose to stop after the first matching row (so, on any given sample-block, at most one of the byte strings will be sent).<br />
Possible values are 0 ("process all rows") or 1 ("stop at the first match").<br />
<br />
==State Variables==<br />
<br />
The SerialInterface does not define any State Variables or Events of its own, but will define any Events the widget tells it to define in response to a <code>--PublishCommand</code>.<br />
<br />
During a run, a widget may change an Event value at any time by sending an [[Programming_Reference:Events#Descriptor_Syntax|Event descriptor line]]: usually, this is the name of the event, followed by a space, followed by the value expressed as decimal text, followed by a line-ending. Optionally, an Event descriptor may contain an additional space and a zero, to indicate an instantaneous transient event. For example, <code>TTLExampleSketch.ino</code> will send <br />
TTLInput 1\r\n<br />
whenever the voltage on its input pin changes from low to high, and<br />
TTLInput 0\r\n<br />
PulseDurationMsec 123 0\r\n<br />
whenever the voltage changes from high to low (where 123 is a place-holder for however long the input pulse in fact lasted, according to the widget's millisecond timer).<br />
<br />
Note that it is not necessary for the Event in question to have been defined by the widget itself—it could have been added by one of the other filters and loggers, or in your [[User_Reference:Operator_Module_Scripting|BCI2000 script]] using [[User_Reference:Operator_Module_Scripting#ADD_EVENT_<name>_<bit_width>_<initial_value>|an <code>ADD EVENT</code> command]] before the <code>STARTUP SYSTEM</code> line. This means you do not necessarily have to implement the widget's response to a <code>--PublishCommand</code>, even if you are planning to use the widget to log Events.<br />
<br />
If you cannot re-program the widget at all, you may still have some (limited) options for triggering Events in response to messages from the widget, via the '''SerialInputs''' parameter.<br />
<br />
==See also==<br />
[[Contributions:SerialWidgetADC]]<br />
<br />
[[Category:Contributions]][[Category:Extension]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=Main_Page&diff=12412Main Page2026-05-04T15:49:00Z<p>Jhill: </p>
<hr />
<div>__NOTOC__ __NOEDITSECTION__<br />
<table cellspacing="10" class="noprint" style="float:left; margin-top:0;margin-bottom:0; text-align:right"><br />
<tr><br />
<td style="border-radius: 10px; background-color:#efefef;padding: 1em 1em 1em 1em;word-spacing:1em;"><br />
<htmltag tagname="form" name="sitesearch" action="https://www.google.com/search"><br />
<htmltag tagname="input" name="q" type="text" size="40" /><br />
<htmltag tagname="input" type="submit" value="Google site search of bci2000.org" /><br />
<htmltag tagname="input" type="hidden" name="sitesearch" value="bci2000.org" /><br />
<htmltag tagname="input" type="hidden" name="ie" value="utf-8" /><br />
<htmltag tagname="input" type="hidden" name="oe" value="utf-8" /><br />
</htmltag><br />
</td><br />
</tr><br />
</table><br />
<br />
<table cellspacing="10" style="width:100%;margin-top:-10px"><br />
<td style="margin:0; margin-top:-10px; margin-right:10px; background-color:#ededed; padding:0 1em 1em 1em; align:right; border-radius: 10px; vertical-align:top;"><br />
=<b>Download BCI2000</b>=<br />
<span style="font-size:130%">1. [https://www.bci2000.org/useradmin/ Create a free user account!] (Required to download BCI2000)</span><br />
<br><br />
<span style="font-size:130%">2. Download the [https://bci2000.org/downloads/bin/BCI2000Setup.exe latest release], [[BCI2000 Binaries|previous versions]], or the source code ([[Programming Howto:Building and Customizing BCI2000 |Windows]], [[Programming Howto:Non:Building and Customizing BCI2000 on Non-Windows Platforms |Non-windows]])</span><br />
</td> <br />
</table><br />
<br />
<table cellspacing="10" style="width:100%;margin-top:-10px"><br />
<tr> <td style="margin:0; margin-right:10px; border-radius: 10px; border:0.5px solid #a2a2a2; padding:0 1em 1em 1em; align:right;vertical-align:top;"><br />
=<b>What is BCI2000?</b>=<br />
BCI2000 is a free, open-source, general-purpose software system for brain-computer interface (BCI) research.<br />
BCI2000 includes software tools that can acquire and process data, present stimuli and feedback, and manage interaction with outside devices such as robotic arms. BCI2000 is a real-time system that can synchronize EEG and other signals with a wide variety of biosignals and input devices such as mice or eye-trackers. It has several modules to manage data importing and exporting in common file formats. BCI2000 operates on most Windows systems, and the source code can be compiled on most Windows machines. <br />
<br />
[[File:BCI2000 New Schematic Extra Large.gif|center|800px|BCI2000 Schematic]]<br />
<br />
Above shows the main framework of BCI2000, with examples for each section. Navigate to the [[User Reference:Filters|Filters page]] to learn more about the framework, or view links below for tutorials and more reference pages.<br />
</td> </tr><br />
<br />
<table cellspacing="10" style="width:100%;margin-top:-10px"><br />
<tr><br />
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#fff8dc; align:right;vertical-align:top;"><br />
==BCI2000 for Users==<br />
<br />
* [//{{SERVERNAME}}/useradmin Create or modify a User Account]<br />
* [[DownloadBCI2000|Download BCI2000]]<br />
* [https://bci2000.org/externals/mex/mexfiles.zip Download BCI2000 Matlab MEX files]<br />
<br />
* Take the introductory [[User Tutorial:BCI2000 Tour|BCI2000 Tour]]<br />
* Learn more through an <br /> [[Introduction_to_Adaptive_Neurotechnologies|Introduction to Adaptive Neurotechnologies]]<br />
* Review the terminology in the [[BCI2000 Glossary]]<br />
</td><br />
<br />
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#e3f5fc; align:right;vertical-align:top;"><br />
==BCI2000 for Developers==<br />
* [//{{SERVERNAME}}/useradmin Create or modify a User Account]<br />
* Download source code ([[Programming Howto:Building and Customizing BCI2000 |Windows]], [[Programming Howto:Non:Building and Customizing BCI2000 on Non-Windows Platforms |Non-windows]])<br />
* [[Programming Reference:Patches|Create a patch]] to add your code to the BCI2000 svn!<br />
* [[APIs|BCI2000 API Documentation]]<br />
* [[Rebuild BCI2000]] - instructions for rapid prototyping!<br />
</td><br />
</tr><br />
<br />
<tr><br />
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; background-color:#e3f5fc; padding:0 1em 1em 1em; align:right;vertical-align:top;"><br />
==BCI2000 References==<br />
===BCI2000 Overview and Tools===<br />
* The [[User Reference:Contents|User Reference Manual]] describes all details<br />of system configuration and usage<br />
===Technical References===<br />
* The [[Technical Reference:Contents|Technical Reference Manual]] contains a discussion of its <br />basic concepts, and a detailed specification of the BCI2000 standard.<br />
===Programming References===<br />
* The [[Programming Reference:Contents|Programming Reference]] provides background information <br />which you need in order to understand, modify, or create code that <br />depends on the BCI2000 framework.<br />
===Contributions===<br />
* [[Contributions:Contents|User-Contributed BCI2000 Components and Patches]]<br />
===Categories===<br />
*[[:Category:Data Acquisition | Data Acquisition]]<br />
*[[:Category:Signal Processing | Signal Processing]]<br />
*[[Contributions:Extensions | Extensions]]<br />
*[[:Category:User Application | User Application]]<br />
*[[:Category:External Interfaces | External Interfaces]]<br />
*[[:Category:User Interface | User Interface]]<br />
*[[:Category:Video | Video Tutorials]]<br />
<br />
</td><br />
<br />
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; background-color:#fff8dc; padding:0 1em 1em 1em; align:right;vertical-align:top;"><br />
==BCI2000 Tutorials==<br />
===Setup Tutorials===<br />
*[[Programming Howto:Install Prerequisites|Install Prerequisites]]<br />
*[[Programming Howto:Register with BCI2000 Project|Register with the BCI2000 Project]]<br />
*[[Programming Howto:Download the BCI2000 Sourcecode|Download the BCI2000 Sourcecode]]<br />
*[[Programming Howto:Configure BCI2000 for Compilation|Configure BCI2000 for Compilation]]<br />
*[[Programming Howto:Compile BCI2000|Compile BCI2000]]<br />
===Experimental Tutorials===<br />
*[[User Tutorial:Mu Rhythm BCI Tutorial|Mu Rhythm BCI Tutorial]]<br />
*[[User Tutorial:P300 BCI Tutorial|P300 BCI Tutorial]]<br />
*[[User Tutorial:Testing AV Playback Tutorial|Testing AV Playback Tutorial]]<br />
===Programming Tutorials===<br />
*[[Programming Tutorial:Implementing a Source Module|Implementing a Source Module]]<br />
*[[Programming Howto:Create a custom Signal Processing Module|Implementing a Signal Processing Module]]<br />
*[[Programming Tutorial:Implementing a Matlab-based Filter|Implementing a Matlab-based Filter]]<br />
*[[Programming Tutorial:Implementing an Input Logger|Implementing an Input Logger]]<br />
===Data Analysis Tutorials===<br />
*[[User Tutorial:Data Analysis|Data Analysis with BCI2000]]<br />
* Converting and Analyzing BCI2000 Data with [[User Reference:Matlab MEX Files|Matlab MEX Files]]<br />
* Analyze BCI2000 Data in Python with [https://github.com/neurotechcenter/BCI2kReader BCI2k Reader]<br />
===All Tutorials: See a complete list of [[User Tutorial|BCI2000 tutorials]] here===<br />
* <br />
</td><br />
</tr><br />
<br />
<tr><br />
<td style="margin:0; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#fff8dc; align:right;vertical-align:top;"><br />
==Supported Frameworks==<br />
===BCI2000 Core Frameworks===<br />
* [[User Reference:P3SpellerTask|P3 Speller]]<br />
* [[User Reference:StimulusPresentationTask|Stimulus Presentation]] <br />
* [[User Reference:CursorTask|Cursor Task]]<br />
===[[Supported Frameworks|External Frameworks]]===<br />
* [[User Tutorial:BCI2000Remote|BCI2000 Remote]] - includes Matlab, C++, and Python <br />
* [[PsychoPy]]<br />
* [[BCPy2000]]<br />
</td><br />
<br />
<br />
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#e3f5fc; align:right;vertical-align:top;"><br />
<br />
==Additional Information==<br />
* [[System Features|Features supported by BCI2000]]<br />
* [https://github.com/neurotechcenter NCAN Github]<br />
* [//{{SERVERNAME}}/phpbb BCI2000 Community Forum]<br />
* [//{{SERVERNAME}}/tracproj/newticket Submit a Bug Report] (make sure you log in)<br />
* [[User FAQ|BCI2000 Frequently Asked Questions]]<br />
* [[BCI2000 Glossary]]<br />of terms specific to BCI2000<br />
* [[BCI2000 Licensing|Licensing Information]]<br />
</td><br />
</tr><br />
</table><br />
<br />
<table cellspacing="10" style="width:100%;"><br />
<tr><br />
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; border:0.5px solid #a2a2a2; padding:0 1em 1em 1em; background-color:white; align:right;vertical-align:top;"><br />
==BCI2000 Publications==<br />
* [https://{{SERVERNAME}}/downloads/doc/paper.pdf G. Schalk, D.J. McFarland, T. Hinterberger, N. Birbaumer, and J.R. Wolpaw: ''BCI2000: A General-Purpose Brain-Computer Interface (BCI) System'', IEEE Trans Biomed Eng, 51(6), June 2004.]<br />
* J. Mellinger, G. Schalk: ''BCI2000: A General-Purpose Software Platform for BCI Research,'' In: G. Dornhege, J. del R. Millán, T. Hinterberger, D.J. McFarland, K.-R. Müller (eds.), ''Toward Brain-Computer Interfacing,'' MIT Press, 2007.<br />
* [http://www.amazon.com/Practical-Guide-BrainComputer-Interfacing-BCI2000/dp/1849960917/ G. Schalk, J. Mellinger: "A Practical Guide to Brain-Computer Interfacing with BCI2000", Springer, 2010.]<br />
* J. Mellinger, G. Schalk: "Using BCI2000 in BCI Research," In: B. Graimann, B. Allison, G. Pfurtscheller (eds.), "Brain-Computer Interfaces: Revolutionizing Human-Computer Interaction", Springer, 2010.<br />
</td><br />
</tr><br />
</table></div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=Main_Page&diff=12411Main Page2026-05-04T15:47:54Z<p>Jhill: </p>
<hr />
<div>__NOTOC__ __NOEDITSECTION__<br />
<table cellspacing="10" class="noprint" style="float:left; margin-top:0;margin-bottom:0; text-align:right"><br />
<tr><br />
<td style="border-radius: 10px; background-color:#efefef;padding: 1em 1em 1em 1em;word-spacing:1em;"><br />
<htmltag tagname="form" name="sitesearch" action="https://www.google.com/search"><br />
<htmltag tagname="input" name="q" type="text" size="40" /><br />
<htmltag tagname="input" type="submit" value="Google site search of bci2000.org" /><br />
<htmltag tagname="input" type="hidden" name="sitesearch" value="bci2000.org" /><br />
<htmltag tagname="input" type="hidden" name="ie" value="utf-8" /><br />
<htmltag tagname="input" type="hidden" name="oe" value="utf-8" /><br />
</htmltag><br />
</td><br />
</tr><br />
</table><br />
<br />
<table cellspacing="10" style="width:100%;margin-top:-10px"><br />
<td style="margin:0; margin-top:-10px; margin-right:10px; background-color:#ededed; padding:0 1em 1em 1em; align:right; border-radius: 10px; vertical-align:top;"><br />
=<b>Download BCI2000</b>=<br />
<span style="font-size:130%">1. [https://www.bci2000.org/useradmin/ Create a free user account!] (Required to download BCI2000)</span><br />
<br><br />
<span style="font-size:130%">2. Download the [https://bci2000.org/downloads/bin/BCI2000Setup.exe latest release], [[BCI2000 Binaries|previous versions]], or the source code ([[Programming Howto:Building and Customizing BCI2000 |Windows]], [[Programming Howto:Non:Building and Customizing BCI2000 on Non-Windows Platforms |Non-windows]])</span><br />
</td> <br />
</table><br />
<br />
<table cellspacing="10" style="width:100%;margin-top:-10px"><br />
<tr> <td style="margin:0; margin-right:10px; border-radius: 10px; border:0.5px solid #a2a2a2; padding:0 1em 1em 1em; align:right;vertical-align:top;"><br />
=<b>What is BCI2000?</b>=<br />
BCI2000 is a free, open-source, general-purpose software system for brain-computer interface (BCI) research that.<br />
BCI2000 includes software tools that can acquire and process data, present stimuli and feedback, and manage interaction with outside devices such as robotic arms. BCI2000 is a real-time system that can synchronize EEG and other signals with a wide variety of biosignals and input devices such as mice or eye-trackers. It has several modules to manage data importing and exporting in common file formats. BCI2000 operates on most Windows systems, and the source code can be compiled on most Windows machines. <br />
<br />
[[File:BCI2000 New Schematic Extra Large.gif|center|800px|BCI2000 Schematic]]<br />
<br />
Above shows the main framework of BCI2000, with examples for each section. Navigate to the [[User Reference:Filters|Filters page]] to learn more about the framework, or view links below for tutorials and more reference pages.<br />
</td> </tr><br />
<br />
<table cellspacing="10" style="width:100%;margin-top:-10px"><br />
<tr><br />
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#fff8dc; align:right;vertical-align:top;"><br />
==BCI2000 for Users==<br />
<br />
* [//{{SERVERNAME}}/useradmin Create or modify a User Account]<br />
* [[DownloadBCI2000|Download BCI2000]]<br />
* [https://bci2000.org/externals/mex/mexfiles.zip Download BCI2000 Matlab MEX files]<br />
<br />
* Take the introductory [[User Tutorial:BCI2000 Tour|BCI2000 Tour]]<br />
* Learn more through an <br /> [[Introduction_to_Adaptive_Neurotechnologies|Introduction to Adaptive Neurotechnologies]]<br />
* Review the terminology in the [[BCI2000 Glossary]]<br />
</td><br />
<br />
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#e3f5fc; align:right;vertical-align:top;"><br />
==BCI2000 for Developers==<br />
* [//{{SERVERNAME}}/useradmin Create or modify a User Account]<br />
* Download source code ([[Programming Howto:Building and Customizing BCI2000 |Windows]], [[Programming Howto:Non:Building and Customizing BCI2000 on Non-Windows Platforms |Non-windows]])<br />
* [[Programming Reference:Patches|Create a patch]] to add your code to the BCI2000 svn!<br />
* [[APIs|BCI2000 API Documentation]]<br />
* [[Rebuild BCI2000]] - instructions for rapid prototyping!<br />
</td><br />
</tr><br />
<br />
<tr><br />
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; background-color:#e3f5fc; padding:0 1em 1em 1em; align:right;vertical-align:top;"><br />
==BCI2000 References==<br />
===BCI2000 Overview and Tools===<br />
* The [[User Reference:Contents|User Reference Manual]] describes all details<br />of system configuration and usage<br />
===Technical References===<br />
* The [[Technical Reference:Contents|Technical Reference Manual]] contains a discussion of its <br />basic concepts, and a detailed specification of the BCI2000 standard.<br />
===Programming References===<br />
* The [[Programming Reference:Contents|Programming Reference]] provides background information <br />which you need in order to understand, modify, or create code that <br />depends on the BCI2000 framework.<br />
===Contributions===<br />
* [[Contributions:Contents|User-Contributed BCI2000 Components and Patches]]<br />
===Categories===<br />
*[[:Category:Data Acquisition | Data Acquisition]]<br />
*[[:Category:Signal Processing | Signal Processing]]<br />
*[[Contributions:Extensions | Extensions]]<br />
*[[:Category:User Application | User Application]]<br />
*[[:Category:External Interfaces | External Interfaces]]<br />
*[[:Category:User Interface | User Interface]]<br />
*[[:Category:Video | Video Tutorials]]<br />
<br />
</td><br />
<br />
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; background-color:#fff8dc; padding:0 1em 1em 1em; align:right;vertical-align:top;"><br />
==BCI2000 Tutorials==<br />
===Setup Tutorials===<br />
*[[Programming Howto:Install Prerequisites|Install Prerequisites]]<br />
*[[Programming Howto:Register with BCI2000 Project|Register with the BCI2000 Project]]<br />
*[[Programming Howto:Download the BCI2000 Sourcecode|Download the BCI2000 Sourcecode]]<br />
*[[Programming Howto:Configure BCI2000 for Compilation|Configure BCI2000 for Compilation]]<br />
*[[Programming Howto:Compile BCI2000|Compile BCI2000]]<br />
===Experimental Tutorials===<br />
*[[User Tutorial:Mu Rhythm BCI Tutorial|Mu Rhythm BCI Tutorial]]<br />
*[[User Tutorial:P300 BCI Tutorial|P300 BCI Tutorial]]<br />
*[[User Tutorial:Testing AV Playback Tutorial|Testing AV Playback Tutorial]]<br />
===Programming Tutorials===<br />
*[[Programming Tutorial:Implementing a Source Module|Implementing a Source Module]]<br />
*[[Programming Howto:Create a custom Signal Processing Module|Implementing a Signal Processing Module]]<br />
*[[Programming Tutorial:Implementing a Matlab-based Filter|Implementing a Matlab-based Filter]]<br />
*[[Programming Tutorial:Implementing an Input Logger|Implementing an Input Logger]]<br />
===Data Analysis Tutorials===<br />
*[[User Tutorial:Data Analysis|Data Analysis with BCI2000]]<br />
* Converting and Analyzing BCI2000 Data with [[User Reference:Matlab MEX Files|Matlab MEX Files]]<br />
* Analyze BCI2000 Data in Python with [https://github.com/neurotechcenter/BCI2kReader BCI2k Reader]<br />
===All Tutorials: See a complete list of [[User Tutorial|BCI2000 tutorials]] here===<br />
* <br />
</td><br />
</tr><br />
<br />
<tr><br />
<td style="margin:0; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#fff8dc; align:right;vertical-align:top;"><br />
==Supported Frameworks==<br />
===BCI2000 Core Frameworks===<br />
* [[User Reference:P3SpellerTask|P3 Speller]]<br />
* [[User Reference:StimulusPresentationTask|Stimulus Presentation]] <br />
* [[User Reference:CursorTask|Cursor Task]]<br />
===[[Supported Frameworks|External Frameworks]]===<br />
* [[User Tutorial:BCI2000Remote|BCI2000 Remote]] - includes Matlab, C++, and Python <br />
* [[PsychoPy]]<br />
* [[BCPy2000]]<br />
</td><br />
<br />
<br />
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#e3f5fc; align:right;vertical-align:top;"><br />
<br />
==Additional Information==<br />
* [[System Features|Features supported by BCI2000]]<br />
* [https://github.com/neurotechcenter NCAN Github]<br />
* [//{{SERVERNAME}}/phpbb BCI2000 Community Forum]<br />
* [//{{SERVERNAME}}/tracproj/newticket Submit a Bug Report] (make sure you log in)<br />
* [[User FAQ|BCI2000 Frequently Asked Questions]]<br />
* [[BCI2000 Glossary]]<br />of terms specific to BCI2000<br />
* [[BCI2000 Licensing|Licensing Information]]<br />
</td><br />
</tr><br />
</table><br />
<br />
<table cellspacing="10" style="width:100%;"><br />
<tr><br />
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; border:0.5px solid #a2a2a2; padding:0 1em 1em 1em; background-color:white; align:right;vertical-align:top;"><br />
==BCI2000 Publications==<br />
* [https://{{SERVERNAME}}/downloads/doc/paper.pdf G. Schalk, D.J. McFarland, T. Hinterberger, N. Birbaumer, and J.R. Wolpaw: ''BCI2000: A General-Purpose Brain-Computer Interface (BCI) System'', IEEE Trans Biomed Eng, 51(6), June 2004.]<br />
* J. Mellinger, G. Schalk: ''BCI2000: A General-Purpose Software Platform for BCI Research,'' In: G. Dornhege, J. del R. Millán, T. Hinterberger, D.J. McFarland, K.-R. Müller (eds.), ''Toward Brain-Computer Interfacing,'' MIT Press, 2007.<br />
* [http://www.amazon.com/Practical-Guide-BrainComputer-Interfacing-BCI2000/dp/1849960917/ G. Schalk, J. Mellinger: "A Practical Guide to Brain-Computer Interfacing with BCI2000", Springer, 2010.]<br />
* J. Mellinger, G. Schalk: "Using BCI2000 in BCI Research," In: B. Graimann, B. Allison, G. Pfurtscheller (eds.), "Brain-Computer Interfaces: Revolutionizing Human-Computer Interaction", Springer, 2010.<br />
</td><br />
</tr><br />
</table></div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:SerialWidgetADC&diff=12303Contributions:SerialWidgetADC2026-01-26T00:48:17Z<p>Jhill: /* Widget Timing */</p>
<hr />
<div>==Synopsis==<br />
An ADC that allows signals to be acquired from programmable serial-port devices such as the Arduino, Teensy, Pico, etc.<br />
<br />
<br />
==Location==<br />
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/SerialWidget<br />
<br />
<br />
==Versioning==<br />
<br />
===Authors===<br />
Jeremy Hill (hill@neurotechcenter.org)<br />
<br />
===Version History===<br />
* 2023-09-22: Initial public release<br />
<br />
===Source Code Revisions===<br />
*Initial development: r7613<br />
*Known to compile under: r8888<br />
*Broken since: --<br />
<br />
==Functional Description==<br />
The ''SerialWidgetADC'' filter is the key component of the ''SerialWidget'' source module, and can acquire signals from a serial-port-equipped embedded system such as an Arduino, Teensy or Pico microcontroller (hereafter referred to as a "widget").<br />
<br />
This ADC includes all the functionality of the [[Contributions:SerialInterface|SerialInterface Extension]]<br />
(which allows widgets to be used alongside other source acquisition hardware, providing auxiliary input and output).<br />
The difference is that the ADC allows the primary signal to be acquired from the widget as well. This provides cheap platform possibilities for realtime testing during development of BCI2000 setups (as an alternative to the SignalGenerator, SoundcardSource or FilePlayback modules) and also allows BCI2000 to be used as a development tool in microcontroller programming (when you need higher data rates, better timing stability or greater flexibility than the Arduino IDE's Serial Plotter can provide).<br />
<br />
Developer note: the ''SerialInterface'' Extension and the ''SerialWidgetADC'' are aware of each other, and the Extension will automatically disable itself in the presence of the ADC, so there is no conflict if the Extension is turned on in CMake during the build.<br />
<br />
==Parameters==<br />
<br />
Parameters for handling widgets are described under [[Contributions:SerialInterface]].<br />
<br />
As in the ''SerialInterface'' Extension, the <code>--SerialPort</code> parameter must be supplied on the command-line and cannot be changed without relaunching BCI2000.<br />
For example, your [[User_Reference:Operator_Module_Scripting|BCI2000 script]] might contain the line:<br />
start executable SerialWidget --local --SerialPort=COM4:baud=9600,dtr=on<br />
The same is true of the <code>--PublishCommand</code> parameter, if used. <br />
<br />
The one departure from ''SerialInterface'' behavior is the handling of custom '''StartCommand''' and '''StopCommand''' messages. ADCs expect the signal to be delivered between runs as well as during runs. Therefore, if a '''StartCommand''' message is specified, the ADC sends it to the widget as soon as the user presses Set Config (whereas the ''SerialInterface'' Extension would wait until the user presses Start or Resume). Similarly, if a '''StopCommand''' message is specified, the ADC only sends it immediately prior to disconnecting and reconnecting on subsequent Set Config operations, and/or when BCI2000 quits (whereas the ''SerialInterface'' Extension would send it when the user presses Suspend).<br />
<br />
Additional Parameters may be defined by the widget itself, if you specify a <code>--PublishCommand</code> on the command-line and the widget is programmed to support the specified command, [[Contributions:SerialInterface#Defining_BCI2000_Parameters_and_Events_from_the_Widget|as described in the SerialInterface documentation]]. As also described there, the values of widget-defined parameters may optionally be updated by the widget when a run ends, if you specify a '''ParameterUpdateCommand''' that the widget supports.<br />
<br />
<br />
Parameters common to all source modules ('''SamplingRate''', '''SampleBlockSize''', '''SourceCh''', etc.) are described under [[User Reference:DataIOFilter]].<br />
''SerialWidgetADC'' adds only one parameter of its own:<br />
<br />
===SourceChPins===<br />
<br />
This is a list of integer values, one per channel. The widget interprets these numbers when deciding how to acquire signals. The interpretation depends entirely on the way the widget is programmed: the simplest way would be to interpret the numbers as indices of the pins from which signals should be read (for example, as arguments to <code>analogRead()</code> or <code>digitalRead()</code> in the Arduino language). The parameter takes its name from this idea. However, a more-sophisticated widget might be programmed to do its own digital signal processing, and/or to generate artificial signals in response to external sensor inputs, and the relationship between these signals and the '''SourceChPins''' values may be arbitrary, as long as the number of channels matches the number of '''SourceChPins''' values.<br />
<br />
==States==<br />
<br />
The ''SerialWidgetADC'' does not define any State Variables or Events of its own, but can create Events as directed by the widget, [[Contributions:SerialInterface#Defining_BCI2000_Parameters_and_Events_from_the_Widget|as described in the SerialInterface documentation]].<br />
<br />
<br />
==Widget Programming==<br />
<br />
The requirements for widget programming are somewhat more stringent than they were for compatibility with the SerialInterface Extension.<br />
An example SerialWidgetADC-compatible sketch is provided in [https://bci2000.org/svn/trunk/src/contrib/SignalSource/SerialWidget/ExampleSourceSketch/ the ExampleSourceSketch subdirectory] (programs in the Arduino IDE are called "sketches" for some reason). ''ExampleSourceSketch.ino'' makes use of the [https://www.arduino.cc/reference/en/libraries/signalacquisition SignalAcquisition] and [https://www.arduino.cc/reference/en/libraries/keyhole Keyhole] libraries, which can be installed via the IDE's library manager and which makes it easy for sketches to respond to serial-port commands and to allow their variables to be read and written. This sketch is an expanded version of the ''TTLExampleSketch.ino'' provided with the SerialInterface Extension, and it handles TTL input and output in the same way; however, courtesy of the ''SignalAcquisition'' library, the sketch also fulfills the following additional requirements for SerialWidgetADC compatibility:<br />
<br />
* To enable signal acquisition, the sketch must support the following commands, sent over the serial port (the specific numbers are just examples, but the variable names and syntax must be supported as shown):<br />
samplesPerSecond=1000\n<br />
samplesPerBlock=40\n<br />
sourcePins="26 27"\n<br />
<br />
// NB: in the SignalAcquisition library, the .exposeVariables() method ensures<br />
// that your sketch supports these, if called inside a Keyhole::begin() block<br />
<br />
* The widget is responsible for sample timing. When the widget has acquired a complete sample-block (the specified number of signal samples from all the specified pins) it must send a sample-block header, which is either <code>\x01\x00</code> or <code>\x00\x01</code> followed by a line-ending (<code>\n</code> or <code>\r\n</code>). Disregarding the line-ending, the header is actually the 16-bit binary representation of the number 1 (the former version is little-endian, the latter big-endian). Based on the header, the ADC will automatically determine whether the subsequent sample data need to be endian-swapped. The header can be sent easily using the following Arduino code:<br />
const uint16_t endianMarker = 1;<br />
Serial.write( (uint8_t*)&endianMarker, sizeof(endianMarker) );<br />
Serial.println(); // don't forget the line-ending<br />
<br />
// NB: in the SignalAcquisition library, the .acquire() method does this for you<br />
<br />
* Immediately after the sample-block header, the widget must send the raw sample data as packed 32-bit floats. The size of this payload is exactly (number of pins)*<code>samplesPerBlock</code>*<code>sizeof(float)</code> bytes. All the different channels' values for the first sample should be sent in the order specified by <code>sourcePins</code>, then all the channels' values for the second sample, and so on.<br />
Serial.write( (uint8_t *)data, numberOfBytes );<br />
Serial.println(); // a line-ending at this point is optional, but makes debugging easier in the Arduino IDE's Serial Monitor<br />
Serial.flush(); // important for good timing<br />
<br />
// NB: in the SignalAcquisition library, the .acquire() method does this for you<br />
<br />
* Between sample-blocks, the widget may send other messages provided they end with a line-ending (<code>\n</code> or <code>\r\n</code>) and do '''not''' begin with <code>\x01\x00</code> or <code>\x00\x01</code>. This allows it to send the same message types that the SerialInterface Extension allows, which are:<br />
** BCI2000 [[Programming_Reference:Events#Descriptor_Syntax|Event descriptor]] lines, to mark the timing of arbitrary events: BCI2000 will attempt to interpret any line that does not begin with <code>{</code> as an Event descriptor;<br />
** error messages: BCI2000 will issue a fatal error containing the text of any line it receives from the widget if that line begins with <code>{</code> and contains the substring <code>_ERROR_</code> (which is true of any error message sent by the Keyhole library);<br />
** any other JSON output: BCI2000 will simply ignore any other line beginning with the <code>{</code> character.<br />
** (You can also use the '''SerialInputs''' parameter to recognize strings that do not necessarily have to end with <code>\r\n</code> or <code>\n</code>, as long as you do not include entries beginning with <code>\x01\x00</code> or <code>\x00\x01</code> in the table. However, there's no real advantage to this; since you have control over the widget's firmware, it is better to program it to send event descriptors as text lines.)<br />
<br />
==Widget Timing==<br />
<br />
The particular implementation in the ''SignalAcquisition'' library contains features that will help you verify and debug your widget's timing.<br />
<br />
#. In the Serial Monitor of the Arduino IDE, first send the commands to set the acquisition parameters the way you want them. (NB: where you see <code>\n</code> above, do not literally type a backslash followed by an <code>n</code>: the <code>\n</code> stands for the newline character, which the Serial Monitor will append for you when you press return.)<br />
#. Then, additionally send <code>debugCommOverhead=1</code> to enable measurement of the serial-port overhead.<br />
#. Then send <code>mute=0</code> to begin sending sample-blocks.<br />
#. Send <code>mute=1;?</code> to stop the flow and examine variables.<br />
#. Repeatedly alternate <code>mute=0</code> with <code>mute=1;?</code> to take multiple readings.<br />
<br />
Verify the following:<br />
<br />
#. The <code>idleLoops</code> variable should be reliably greater than 0 when queried with <code>mute=1;?</code> . If it is 0, this indicates that your sketch may be unable to keep up with the desired sample rate. You need to reduce <code>samplesPerSecond</code>.<br />
#. The <code>debugCommOverhead</code> variable will now contain a timing measurement indicating the number of microseconds it took to send data over the serial port for the last sample-block. This will be roughly proportional to the number of channels and the number of samples per block. It should not exceed the sample period in microseconds (<code>1e6/samplesPerSecond</code>): if it does, your data will contain readings that were unevenly sampled in time. In that case, you should reduce <code>samplesPerSecond</code>, reduce <code>samplesPerBlock</code>, or reduce the number of channels in <code>sourcePins</code>.<br />
<br />
You can also probe the capabilities of your system by setting <code>debugSampleInterval=1</code>, then setting <code>samplesPerSecond</code> too high and repeatedly querying the <code>debugSampleInterval</code> variable. This gives you an empirical measurement of the interval between the sample before last and the last one in microseconds. (With <code>debugSampleInterval</code> set to non-zero you can also use BCI2000 to do something similar: set the <code>SamplingRate</code> parameter too high, and use the timing window to look at the difference between nominal and measured sample-block durations.) Remember to set <code>debugSampleInterval=0</code> when you have finished debugging - this makes the system more responsive to, and allows more robust recovery from, transient timing hiccups (whereas prolonged tolerance of overly-long sample intervals will lead to data loss).<br />
<br />
''NB: the use of <code>debugCommOverhead</code> and <code>debugSampleInterval</code> assume you are working with version 1.4.0 or later of the ''SignalAcquisition'' Arduino-IDE library.''<br />
''In earlier versions, similar functionality was available under the names <code>commOverheadMicros</code> and <code>measuredMicrosPerSample</code> but we strongly recommend that you update your library to the latest version.''<br />
<br />
==See also==<br />
[[User Reference:DataIOFilter]], [[Programming Reference:GenericADC Class]], [[Contributions:SerialInterface]]<br />
<br />
[[Category:Filters]][[Category:Data Acquisition]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:SerialWidgetADC&diff=12302Contributions:SerialWidgetADC2026-01-26T00:47:05Z<p>Jhill: /* Widget Timing */</p>
<hr />
<div>==Synopsis==<br />
An ADC that allows signals to be acquired from programmable serial-port devices such as the Arduino, Teensy, Pico, etc.<br />
<br />
<br />
==Location==<br />
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/SerialWidget<br />
<br />
<br />
==Versioning==<br />
<br />
===Authors===<br />
Jeremy Hill (hill@neurotechcenter.org)<br />
<br />
===Version History===<br />
* 2023-09-22: Initial public release<br />
<br />
===Source Code Revisions===<br />
*Initial development: r7613<br />
*Known to compile under: r8888<br />
*Broken since: --<br />
<br />
==Functional Description==<br />
The ''SerialWidgetADC'' filter is the key component of the ''SerialWidget'' source module, and can acquire signals from a serial-port-equipped embedded system such as an Arduino, Teensy or Pico microcontroller (hereafter referred to as a "widget").<br />
<br />
This ADC includes all the functionality of the [[Contributions:SerialInterface|SerialInterface Extension]]<br />
(which allows widgets to be used alongside other source acquisition hardware, providing auxiliary input and output).<br />
The difference is that the ADC allows the primary signal to be acquired from the widget as well. This provides cheap platform possibilities for realtime testing during development of BCI2000 setups (as an alternative to the SignalGenerator, SoundcardSource or FilePlayback modules) and also allows BCI2000 to be used as a development tool in microcontroller programming (when you need higher data rates, better timing stability or greater flexibility than the Arduino IDE's Serial Plotter can provide).<br />
<br />
Developer note: the ''SerialInterface'' Extension and the ''SerialWidgetADC'' are aware of each other, and the Extension will automatically disable itself in the presence of the ADC, so there is no conflict if the Extension is turned on in CMake during the build.<br />
<br />
==Parameters==<br />
<br />
Parameters for handling widgets are described under [[Contributions:SerialInterface]].<br />
<br />
As in the ''SerialInterface'' Extension, the <code>--SerialPort</code> parameter must be supplied on the command-line and cannot be changed without relaunching BCI2000.<br />
For example, your [[User_Reference:Operator_Module_Scripting|BCI2000 script]] might contain the line:<br />
start executable SerialWidget --local --SerialPort=COM4:baud=9600,dtr=on<br />
The same is true of the <code>--PublishCommand</code> parameter, if used. <br />
<br />
The one departure from ''SerialInterface'' behavior is the handling of custom '''StartCommand''' and '''StopCommand''' messages. ADCs expect the signal to be delivered between runs as well as during runs. Therefore, if a '''StartCommand''' message is specified, the ADC sends it to the widget as soon as the user presses Set Config (whereas the ''SerialInterface'' Extension would wait until the user presses Start or Resume). Similarly, if a '''StopCommand''' message is specified, the ADC only sends it immediately prior to disconnecting and reconnecting on subsequent Set Config operations, and/or when BCI2000 quits (whereas the ''SerialInterface'' Extension would send it when the user presses Suspend).<br />
<br />
Additional Parameters may be defined by the widget itself, if you specify a <code>--PublishCommand</code> on the command-line and the widget is programmed to support the specified command, [[Contributions:SerialInterface#Defining_BCI2000_Parameters_and_Events_from_the_Widget|as described in the SerialInterface documentation]]. As also described there, the values of widget-defined parameters may optionally be updated by the widget when a run ends, if you specify a '''ParameterUpdateCommand''' that the widget supports.<br />
<br />
<br />
Parameters common to all source modules ('''SamplingRate''', '''SampleBlockSize''', '''SourceCh''', etc.) are described under [[User Reference:DataIOFilter]].<br />
''SerialWidgetADC'' adds only one parameter of its own:<br />
<br />
===SourceChPins===<br />
<br />
This is a list of integer values, one per channel. The widget interprets these numbers when deciding how to acquire signals. The interpretation depends entirely on the way the widget is programmed: the simplest way would be to interpret the numbers as indices of the pins from which signals should be read (for example, as arguments to <code>analogRead()</code> or <code>digitalRead()</code> in the Arduino language). The parameter takes its name from this idea. However, a more-sophisticated widget might be programmed to do its own digital signal processing, and/or to generate artificial signals in response to external sensor inputs, and the relationship between these signals and the '''SourceChPins''' values may be arbitrary, as long as the number of channels matches the number of '''SourceChPins''' values.<br />
<br />
==States==<br />
<br />
The ''SerialWidgetADC'' does not define any State Variables or Events of its own, but can create Events as directed by the widget, [[Contributions:SerialInterface#Defining_BCI2000_Parameters_and_Events_from_the_Widget|as described in the SerialInterface documentation]].<br />
<br />
<br />
==Widget Programming==<br />
<br />
The requirements for widget programming are somewhat more stringent than they were for compatibility with the SerialInterface Extension.<br />
An example SerialWidgetADC-compatible sketch is provided in [https://bci2000.org/svn/trunk/src/contrib/SignalSource/SerialWidget/ExampleSourceSketch/ the ExampleSourceSketch subdirectory] (programs in the Arduino IDE are called "sketches" for some reason). ''ExampleSourceSketch.ino'' makes use of the [https://www.arduino.cc/reference/en/libraries/signalacquisition SignalAcquisition] and [https://www.arduino.cc/reference/en/libraries/keyhole Keyhole] libraries, which can be installed via the IDE's library manager and which makes it easy for sketches to respond to serial-port commands and to allow their variables to be read and written. This sketch is an expanded version of the ''TTLExampleSketch.ino'' provided with the SerialInterface Extension, and it handles TTL input and output in the same way; however, courtesy of the ''SignalAcquisition'' library, the sketch also fulfills the following additional requirements for SerialWidgetADC compatibility:<br />
<br />
* To enable signal acquisition, the sketch must support the following commands, sent over the serial port (the specific numbers are just examples, but the variable names and syntax must be supported as shown):<br />
samplesPerSecond=1000\n<br />
samplesPerBlock=40\n<br />
sourcePins="26 27"\n<br />
<br />
// NB: in the SignalAcquisition library, the .exposeVariables() method ensures<br />
// that your sketch supports these, if called inside a Keyhole::begin() block<br />
<br />
* The widget is responsible for sample timing. When the widget has acquired a complete sample-block (the specified number of signal samples from all the specified pins) it must send a sample-block header, which is either <code>\x01\x00</code> or <code>\x00\x01</code> followed by a line-ending (<code>\n</code> or <code>\r\n</code>). Disregarding the line-ending, the header is actually the 16-bit binary representation of the number 1 (the former version is little-endian, the latter big-endian). Based on the header, the ADC will automatically determine whether the subsequent sample data need to be endian-swapped. The header can be sent easily using the following Arduino code:<br />
const uint16_t endianMarker = 1;<br />
Serial.write( (uint8_t*)&endianMarker, sizeof(endianMarker) );<br />
Serial.println(); // don't forget the line-ending<br />
<br />
// NB: in the SignalAcquisition library, the .acquire() method does this for you<br />
<br />
* Immediately after the sample-block header, the widget must send the raw sample data as packed 32-bit floats. The size of this payload is exactly (number of pins)*<code>samplesPerBlock</code>*<code>sizeof(float)</code> bytes. All the different channels' values for the first sample should be sent in the order specified by <code>sourcePins</code>, then all the channels' values for the second sample, and so on.<br />
Serial.write( (uint8_t *)data, numberOfBytes );<br />
Serial.println(); // a line-ending at this point is optional, but makes debugging easier in the Arduino IDE's Serial Monitor<br />
Serial.flush(); // important for good timing<br />
<br />
// NB: in the SignalAcquisition library, the .acquire() method does this for you<br />
<br />
* Between sample-blocks, the widget may send other messages provided they end with a line-ending (<code>\n</code> or <code>\r\n</code>) and do '''not''' begin with <code>\x01\x00</code> or <code>\x00\x01</code>. This allows it to send the same message types that the SerialInterface Extension allows, which are:<br />
** BCI2000 [[Programming_Reference:Events#Descriptor_Syntax|Event descriptor]] lines, to mark the timing of arbitrary events: BCI2000 will attempt to interpret any line that does not begin with <code>{</code> as an Event descriptor;<br />
** error messages: BCI2000 will issue a fatal error containing the text of any line it receives from the widget if that line begins with <code>{</code> and contains the substring <code>_ERROR_</code> (which is true of any error message sent by the Keyhole library);<br />
** any other JSON output: BCI2000 will simply ignore any other line beginning with the <code>{</code> character.<br />
** (You can also use the '''SerialInputs''' parameter to recognize strings that do not necessarily have to end with <code>\r\n</code> or <code>\n</code>, as long as you do not include entries beginning with <code>\x01\x00</code> or <code>\x00\x01</code> in the table. However, there's no real advantage to this; since you have control over the widget's firmware, it is better to program it to send event descriptors as text lines.)<br />
<br />
==Widget Timing==<br />
<br />
The particular implementation in the ''SignalAcquisition'' library contains features that will help you verify and debug your widget's timing.<br />
<br />
#. In the Serial Monitor of the Arduino IDE, first send the commands to set the acquisition parameters the way you want them. (NB: where you see <code>\n</code> above, do not literally type a backslash followed by an <code>n</code>: the <code>\n</code> stands for the newline character, which the Serial Monitor will append for you when you press return.)<br />
#. Then, additionally send <code>debugCommOverhead=1</code> to enable measurement of the serial-port overhead.<br />
#. Then send <code>mute=0</code> to begin sending sample-blocks.<br />
#. Send <code>mute=1;?</code> to stop the flow and examine variables.<br />
#. Repeatedly alternate <code>mute=0</code> with <code>mute=1;?</code> to take multiple readings.<br />
<br />
Verify the following:<br />
<br />
#. The <code>idleLoops</code> variable should be reliably greater than 0 when queried with <code>mute=1;?</code> . If it is 0, this indicates that your sketch may be unable to keep up with the desired sample rate. You need to reduce <code>samplesPerSecond</code>.<br />
#. The <code>debugCommOverhead</code> variable will now contain a timing measurement indicating the number of microseconds it took to send data over the serial port for the last sample-block. This will be roughly proportional to the number of channels and the number of samples per block. It should not exceed the sample period in microseconds (<code>1e6/samplesPerSecond</code>): if it does, your data will contain readings that were unevenly sampled in time. In that case, you should reduce <code>samplesPerSecond</code>, reduce <code>samplesPerBlock</code>, or reduce the number of channels in <code>sourcePins</code>.<br />
<br />
You can also probe the capabilities of your system by setting <code>debugSampleInterval=1</code>, then setting <code>samplesPerSecond</code> too high and repeatedly querying the <code>debugSampleInterval</code> variable. This gives you an empirical measurement of the interval between the sample before last and the last one in microseconds. (With <code>debugSampleInterval</code> set to non-zero you can also use BCI2000 to do something similar: set the <code>SamplingRate</code> parameter too high, and use the timing window to look at the difference between nominal and measured sample-block durations.) Remember to set <code>debugSampleInterval=0</code> when you have finished debugging - this will the system more responsive to, and allow more robust recovery from, transient timing hiccups (continued tolerance of overly long sample intervals will lead to data loss).<br />
<br />
''NB: the use of <code>debugCommOverhead</code> and <code>debugSampleInterval</code> assume you are working with version 1.4.0 or later of the ''SignalAcquisition'' Arduino-IDE library.''<br />
''In earlier versions, similar functionality was available under the names <code>commOverheadMicros</code> and <code>measuredMicrosPerSample</code> but we strongly recommend that you update your library to the latest version.''<br />
<br />
==See also==<br />
[[User Reference:DataIOFilter]], [[Programming Reference:GenericADC Class]], [[Contributions:SerialInterface]]<br />
<br />
[[Category:Filters]][[Category:Data Acquisition]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:SerialWidgetADC&diff=12301Contributions:SerialWidgetADC2026-01-26T00:35:00Z<p>Jhill: /* Widget Timing */</p>
<hr />
<div>==Synopsis==<br />
An ADC that allows signals to be acquired from programmable serial-port devices such as the Arduino, Teensy, Pico, etc.<br />
<br />
<br />
==Location==<br />
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/SerialWidget<br />
<br />
<br />
==Versioning==<br />
<br />
===Authors===<br />
Jeremy Hill (hill@neurotechcenter.org)<br />
<br />
===Version History===<br />
* 2023-09-22: Initial public release<br />
<br />
===Source Code Revisions===<br />
*Initial development: r7613<br />
*Known to compile under: r8888<br />
*Broken since: --<br />
<br />
==Functional Description==<br />
The ''SerialWidgetADC'' filter is the key component of the ''SerialWidget'' source module, and can acquire signals from a serial-port-equipped embedded system such as an Arduino, Teensy or Pico microcontroller (hereafter referred to as a "widget").<br />
<br />
This ADC includes all the functionality of the [[Contributions:SerialInterface|SerialInterface Extension]]<br />
(which allows widgets to be used alongside other source acquisition hardware, providing auxiliary input and output).<br />
The difference is that the ADC allows the primary signal to be acquired from the widget as well. This provides cheap platform possibilities for realtime testing during development of BCI2000 setups (as an alternative to the SignalGenerator, SoundcardSource or FilePlayback modules) and also allows BCI2000 to be used as a development tool in microcontroller programming (when you need higher data rates, better timing stability or greater flexibility than the Arduino IDE's Serial Plotter can provide).<br />
<br />
Developer note: the ''SerialInterface'' Extension and the ''SerialWidgetADC'' are aware of each other, and the Extension will automatically disable itself in the presence of the ADC, so there is no conflict if the Extension is turned on in CMake during the build.<br />
<br />
==Parameters==<br />
<br />
Parameters for handling widgets are described under [[Contributions:SerialInterface]].<br />
<br />
As in the ''SerialInterface'' Extension, the <code>--SerialPort</code> parameter must be supplied on the command-line and cannot be changed without relaunching BCI2000.<br />
For example, your [[User_Reference:Operator_Module_Scripting|BCI2000 script]] might contain the line:<br />
start executable SerialWidget --local --SerialPort=COM4:baud=9600,dtr=on<br />
The same is true of the <code>--PublishCommand</code> parameter, if used. <br />
<br />
The one departure from ''SerialInterface'' behavior is the handling of custom '''StartCommand''' and '''StopCommand''' messages. ADCs expect the signal to be delivered between runs as well as during runs. Therefore, if a '''StartCommand''' message is specified, the ADC sends it to the widget as soon as the user presses Set Config (whereas the ''SerialInterface'' Extension would wait until the user presses Start or Resume). Similarly, if a '''StopCommand''' message is specified, the ADC only sends it immediately prior to disconnecting and reconnecting on subsequent Set Config operations, and/or when BCI2000 quits (whereas the ''SerialInterface'' Extension would send it when the user presses Suspend).<br />
<br />
Additional Parameters may be defined by the widget itself, if you specify a <code>--PublishCommand</code> on the command-line and the widget is programmed to support the specified command, [[Contributions:SerialInterface#Defining_BCI2000_Parameters_and_Events_from_the_Widget|as described in the SerialInterface documentation]]. As also described there, the values of widget-defined parameters may optionally be updated by the widget when a run ends, if you specify a '''ParameterUpdateCommand''' that the widget supports.<br />
<br />
<br />
Parameters common to all source modules ('''SamplingRate''', '''SampleBlockSize''', '''SourceCh''', etc.) are described under [[User Reference:DataIOFilter]].<br />
''SerialWidgetADC'' adds only one parameter of its own:<br />
<br />
===SourceChPins===<br />
<br />
This is a list of integer values, one per channel. The widget interprets these numbers when deciding how to acquire signals. The interpretation depends entirely on the way the widget is programmed: the simplest way would be to interpret the numbers as indices of the pins from which signals should be read (for example, as arguments to <code>analogRead()</code> or <code>digitalRead()</code> in the Arduino language). The parameter takes its name from this idea. However, a more-sophisticated widget might be programmed to do its own digital signal processing, and/or to generate artificial signals in response to external sensor inputs, and the relationship between these signals and the '''SourceChPins''' values may be arbitrary, as long as the number of channels matches the number of '''SourceChPins''' values.<br />
<br />
==States==<br />
<br />
The ''SerialWidgetADC'' does not define any State Variables or Events of its own, but can create Events as directed by the widget, [[Contributions:SerialInterface#Defining_BCI2000_Parameters_and_Events_from_the_Widget|as described in the SerialInterface documentation]].<br />
<br />
<br />
==Widget Programming==<br />
<br />
The requirements for widget programming are somewhat more stringent than they were for compatibility with the SerialInterface Extension.<br />
An example SerialWidgetADC-compatible sketch is provided in [https://bci2000.org/svn/trunk/src/contrib/SignalSource/SerialWidget/ExampleSourceSketch/ the ExampleSourceSketch subdirectory] (programs in the Arduino IDE are called "sketches" for some reason). ''ExampleSourceSketch.ino'' makes use of the [https://www.arduino.cc/reference/en/libraries/signalacquisition SignalAcquisition] and [https://www.arduino.cc/reference/en/libraries/keyhole Keyhole] libraries, which can be installed via the IDE's library manager and which makes it easy for sketches to respond to serial-port commands and to allow their variables to be read and written. This sketch is an expanded version of the ''TTLExampleSketch.ino'' provided with the SerialInterface Extension, and it handles TTL input and output in the same way; however, courtesy of the ''SignalAcquisition'' library, the sketch also fulfills the following additional requirements for SerialWidgetADC compatibility:<br />
<br />
* To enable signal acquisition, the sketch must support the following commands, sent over the serial port (the specific numbers are just examples, but the variable names and syntax must be supported as shown):<br />
samplesPerSecond=1000\n<br />
samplesPerBlock=40\n<br />
sourcePins="26 27"\n<br />
<br />
// NB: in the SignalAcquisition library, the .exposeVariables() method ensures<br />
// that your sketch supports these, if called inside a Keyhole::begin() block<br />
<br />
* The widget is responsible for sample timing. When the widget has acquired a complete sample-block (the specified number of signal samples from all the specified pins) it must send a sample-block header, which is either <code>\x01\x00</code> or <code>\x00\x01</code> followed by a line-ending (<code>\n</code> or <code>\r\n</code>). Disregarding the line-ending, the header is actually the 16-bit binary representation of the number 1 (the former version is little-endian, the latter big-endian). Based on the header, the ADC will automatically determine whether the subsequent sample data need to be endian-swapped. The header can be sent easily using the following Arduino code:<br />
const uint16_t endianMarker = 1;<br />
Serial.write( (uint8_t*)&endianMarker, sizeof(endianMarker) );<br />
Serial.println(); // don't forget the line-ending<br />
<br />
// NB: in the SignalAcquisition library, the .acquire() method does this for you<br />
<br />
* Immediately after the sample-block header, the widget must send the raw sample data as packed 32-bit floats. The size of this payload is exactly (number of pins)*<code>samplesPerBlock</code>*<code>sizeof(float)</code> bytes. All the different channels' values for the first sample should be sent in the order specified by <code>sourcePins</code>, then all the channels' values for the second sample, and so on.<br />
Serial.write( (uint8_t *)data, numberOfBytes );<br />
Serial.println(); // a line-ending at this point is optional, but makes debugging easier in the Arduino IDE's Serial Monitor<br />
Serial.flush(); // important for good timing<br />
<br />
// NB: in the SignalAcquisition library, the .acquire() method does this for you<br />
<br />
* Between sample-blocks, the widget may send other messages provided they end with a line-ending (<code>\n</code> or <code>\r\n</code>) and do '''not''' begin with <code>\x01\x00</code> or <code>\x00\x01</code>. This allows it to send the same message types that the SerialInterface Extension allows, which are:<br />
** BCI2000 [[Programming_Reference:Events#Descriptor_Syntax|Event descriptor]] lines, to mark the timing of arbitrary events: BCI2000 will attempt to interpret any line that does not begin with <code>{</code> as an Event descriptor;<br />
** error messages: BCI2000 will issue a fatal error containing the text of any line it receives from the widget if that line begins with <code>{</code> and contains the substring <code>_ERROR_</code> (which is true of any error message sent by the Keyhole library);<br />
** any other JSON output: BCI2000 will simply ignore any other line beginning with the <code>{</code> character.<br />
** (You can also use the '''SerialInputs''' parameter to recognize strings that do not necessarily have to end with <code>\r\n</code> or <code>\n</code>, as long as you do not include entries beginning with <code>\x01\x00</code> or <code>\x00\x01</code> in the table. However, there's no real advantage to this; since you have control over the widget's firmware, it is better to program it to send event descriptors as text lines.)<br />
<br />
==Widget Timing==<br />
<br />
The particular implementation in the ''SignalAcquisition'' library contains features that will help you verify and debug your widget's timing.<br />
<br />
#. In the Serial Monitor of the Arduino IDE, first send the commands to set the acquisition parameters the way you want them. (NB: where you see <code>\n</code> above, do not literally type a backslash followed by an <code>n</code>: the <code>\n</code> stands for the newline character, which the Serial Monitor will append for you when you press return.)<br />
#. Then, additionally send <code>debugCommOverhead=1</code> to enable measurement of the serial-port overhead.<br />
#. Then send <code>mute=0</code> to begin sending sample-blocks.<br />
#. Send <code>mute=1;?</code> to stop the flow and examine variables.<br />
#. Repeatedly alternate <code>mute=0</code> with <code>mute=1;?</code> to take multiple readings.<br />
<br />
Verify the following:<br />
<br />
#. The <code>idleLoops</code> variable should be reliably greater than 0 when queried with <code>mute=1;?</code> . If it is 0, this indicates that your sketch may be unable to keep up with the desired sample rate. You need to reduce <code>samplesPerSecond</code>.<br />
#. The <code>debugCommOverhead</code> variable will now contain a timing measurement indicating the number of microseconds it took to send data over the serial port for the last sample-block. This will be roughly proportional to the number of channels and the number of samples per block. It should not exceed the sample period in microseconds (<code>1e6/samplesPerSecond</code>): if it does, your data will contain readings that were unevenly sampled in time. In that case, you should reduce <code>samplesPerSecond</code>, reduce <code>samplesPerBlock</code>, or reduce the number of channels in <code>sourcePins</code>.<br />
<br />
You can also probe the capabilities of your system by setting <code>debugSampleInterval=1</code>, then setting <code>samplesPerSecond</code> too high and repeatedly querying the <code>debugSampleInterval</code> variable. This gives you an empirical measurement of the interval between the sample before last and the last one in microseconds. (With <code>debugSampleInterval</code> set to non-zero you can also use BCI2000 to do something similar: set the <code>SamplingRate</code> parameter too high, and use the timing window to look at the difference between nominal and measured sample-block durations.) Remember to set <code>debugSampleInterval=0</code> when you have finished debugging - this will the system more responsive to, and allow more robust recovery from, transient timing hiccups (continued tolerance of overly long sample intervals will lead to data loss).<br />
<br />
''NB: the use of <code>debugCommOverhead</code> and <code>debugSampleInterval</code> assume you are working with version 1.4.0 or later of the ''SignalAcquisition'' Arduino-IDE library.<br />
In earlier versions, similar functionality was available under the names <code>commOverheadMicros</code> and <code>measuredMicrosPerSample</code> but we strongly recommend that you update your library to the latest version.''<br />
<br />
==See also==<br />
[[User Reference:DataIOFilter]], [[Programming Reference:GenericADC Class]], [[Contributions:SerialInterface]]<br />
<br />
[[Category:Filters]][[Category:Data Acquisition]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:SerialWidgetADC&diff=12300Contributions:SerialWidgetADC2026-01-26T00:22:07Z<p>Jhill: /* Widget Timing */</p>
<hr />
<div>==Synopsis==<br />
An ADC that allows signals to be acquired from programmable serial-port devices such as the Arduino, Teensy, Pico, etc.<br />
<br />
<br />
==Location==<br />
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/SerialWidget<br />
<br />
<br />
==Versioning==<br />
<br />
===Authors===<br />
Jeremy Hill (hill@neurotechcenter.org)<br />
<br />
===Version History===<br />
* 2023-09-22: Initial public release<br />
<br />
===Source Code Revisions===<br />
*Initial development: r7613<br />
*Known to compile under: r8888<br />
*Broken since: --<br />
<br />
==Functional Description==<br />
The ''SerialWidgetADC'' filter is the key component of the ''SerialWidget'' source module, and can acquire signals from a serial-port-equipped embedded system such as an Arduino, Teensy or Pico microcontroller (hereafter referred to as a "widget").<br />
<br />
This ADC includes all the functionality of the [[Contributions:SerialInterface|SerialInterface Extension]]<br />
(which allows widgets to be used alongside other source acquisition hardware, providing auxiliary input and output).<br />
The difference is that the ADC allows the primary signal to be acquired from the widget as well. This provides cheap platform possibilities for realtime testing during development of BCI2000 setups (as an alternative to the SignalGenerator, SoundcardSource or FilePlayback modules) and also allows BCI2000 to be used as a development tool in microcontroller programming (when you need higher data rates, better timing stability or greater flexibility than the Arduino IDE's Serial Plotter can provide).<br />
<br />
Developer note: the ''SerialInterface'' Extension and the ''SerialWidgetADC'' are aware of each other, and the Extension will automatically disable itself in the presence of the ADC, so there is no conflict if the Extension is turned on in CMake during the build.<br />
<br />
==Parameters==<br />
<br />
Parameters for handling widgets are described under [[Contributions:SerialInterface]].<br />
<br />
As in the ''SerialInterface'' Extension, the <code>--SerialPort</code> parameter must be supplied on the command-line and cannot be changed without relaunching BCI2000.<br />
For example, your [[User_Reference:Operator_Module_Scripting|BCI2000 script]] might contain the line:<br />
start executable SerialWidget --local --SerialPort=COM4:baud=9600,dtr=on<br />
The same is true of the <code>--PublishCommand</code> parameter, if used. <br />
<br />
The one departure from ''SerialInterface'' behavior is the handling of custom '''StartCommand''' and '''StopCommand''' messages. ADCs expect the signal to be delivered between runs as well as during runs. Therefore, if a '''StartCommand''' message is specified, the ADC sends it to the widget as soon as the user presses Set Config (whereas the ''SerialInterface'' Extension would wait until the user presses Start or Resume). Similarly, if a '''StopCommand''' message is specified, the ADC only sends it immediately prior to disconnecting and reconnecting on subsequent Set Config operations, and/or when BCI2000 quits (whereas the ''SerialInterface'' Extension would send it when the user presses Suspend).<br />
<br />
Additional Parameters may be defined by the widget itself, if you specify a <code>--PublishCommand</code> on the command-line and the widget is programmed to support the specified command, [[Contributions:SerialInterface#Defining_BCI2000_Parameters_and_Events_from_the_Widget|as described in the SerialInterface documentation]]. As also described there, the values of widget-defined parameters may optionally be updated by the widget when a run ends, if you specify a '''ParameterUpdateCommand''' that the widget supports.<br />
<br />
<br />
Parameters common to all source modules ('''SamplingRate''', '''SampleBlockSize''', '''SourceCh''', etc.) are described under [[User Reference:DataIOFilter]].<br />
''SerialWidgetADC'' adds only one parameter of its own:<br />
<br />
===SourceChPins===<br />
<br />
This is a list of integer values, one per channel. The widget interprets these numbers when deciding how to acquire signals. The interpretation depends entirely on the way the widget is programmed: the simplest way would be to interpret the numbers as indices of the pins from which signals should be read (for example, as arguments to <code>analogRead()</code> or <code>digitalRead()</code> in the Arduino language). The parameter takes its name from this idea. However, a more-sophisticated widget might be programmed to do its own digital signal processing, and/or to generate artificial signals in response to external sensor inputs, and the relationship between these signals and the '''SourceChPins''' values may be arbitrary, as long as the number of channels matches the number of '''SourceChPins''' values.<br />
<br />
==States==<br />
<br />
The ''SerialWidgetADC'' does not define any State Variables or Events of its own, but can create Events as directed by the widget, [[Contributions:SerialInterface#Defining_BCI2000_Parameters_and_Events_from_the_Widget|as described in the SerialInterface documentation]].<br />
<br />
<br />
==Widget Programming==<br />
<br />
The requirements for widget programming are somewhat more stringent than they were for compatibility with the SerialInterface Extension.<br />
An example SerialWidgetADC-compatible sketch is provided in [https://bci2000.org/svn/trunk/src/contrib/SignalSource/SerialWidget/ExampleSourceSketch/ the ExampleSourceSketch subdirectory] (programs in the Arduino IDE are called "sketches" for some reason). ''ExampleSourceSketch.ino'' makes use of the [https://www.arduino.cc/reference/en/libraries/signalacquisition SignalAcquisition] and [https://www.arduino.cc/reference/en/libraries/keyhole Keyhole] libraries, which can be installed via the IDE's library manager and which makes it easy for sketches to respond to serial-port commands and to allow their variables to be read and written. This sketch is an expanded version of the ''TTLExampleSketch.ino'' provided with the SerialInterface Extension, and it handles TTL input and output in the same way; however, courtesy of the ''SignalAcquisition'' library, the sketch also fulfills the following additional requirements for SerialWidgetADC compatibility:<br />
<br />
* To enable signal acquisition, the sketch must support the following commands, sent over the serial port (the specific numbers are just examples, but the variable names and syntax must be supported as shown):<br />
samplesPerSecond=1000\n<br />
samplesPerBlock=40\n<br />
sourcePins="26 27"\n<br />
<br />
// NB: in the SignalAcquisition library, the .exposeVariables() method ensures<br />
// that your sketch supports these, if called inside a Keyhole::begin() block<br />
<br />
* The widget is responsible for sample timing. When the widget has acquired a complete sample-block (the specified number of signal samples from all the specified pins) it must send a sample-block header, which is either <code>\x01\x00</code> or <code>\x00\x01</code> followed by a line-ending (<code>\n</code> or <code>\r\n</code>). Disregarding the line-ending, the header is actually the 16-bit binary representation of the number 1 (the former version is little-endian, the latter big-endian). Based on the header, the ADC will automatically determine whether the subsequent sample data need to be endian-swapped. The header can be sent easily using the following Arduino code:<br />
const uint16_t endianMarker = 1;<br />
Serial.write( (uint8_t*)&endianMarker, sizeof(endianMarker) );<br />
Serial.println(); // don't forget the line-ending<br />
<br />
// NB: in the SignalAcquisition library, the .acquire() method does this for you<br />
<br />
* Immediately after the sample-block header, the widget must send the raw sample data as packed 32-bit floats. The size of this payload is exactly (number of pins)*<code>samplesPerBlock</code>*<code>sizeof(float)</code> bytes. All the different channels' values for the first sample should be sent in the order specified by <code>sourcePins</code>, then all the channels' values for the second sample, and so on.<br />
Serial.write( (uint8_t *)data, numberOfBytes );<br />
Serial.println(); // a line-ending at this point is optional, but makes debugging easier in the Arduino IDE's Serial Monitor<br />
Serial.flush(); // important for good timing<br />
<br />
// NB: in the SignalAcquisition library, the .acquire() method does this for you<br />
<br />
* Between sample-blocks, the widget may send other messages provided they end with a line-ending (<code>\n</code> or <code>\r\n</code>) and do '''not''' begin with <code>\x01\x00</code> or <code>\x00\x01</code>. This allows it to send the same message types that the SerialInterface Extension allows, which are:<br />
** BCI2000 [[Programming_Reference:Events#Descriptor_Syntax|Event descriptor]] lines, to mark the timing of arbitrary events: BCI2000 will attempt to interpret any line that does not begin with <code>{</code> as an Event descriptor;<br />
** error messages: BCI2000 will issue a fatal error containing the text of any line it receives from the widget if that line begins with <code>{</code> and contains the substring <code>_ERROR_</code> (which is true of any error message sent by the Keyhole library);<br />
** any other JSON output: BCI2000 will simply ignore any other line beginning with the <code>{</code> character.<br />
** (You can also use the '''SerialInputs''' parameter to recognize strings that do not necessarily have to end with <code>\r\n</code> or <code>\n</code>, as long as you do not include entries beginning with <code>\x01\x00</code> or <code>\x00\x01</code> in the table. However, there's no real advantage to this; since you have control over the widget's firmware, it is better to program it to send event descriptors as text lines.)<br />
<br />
==Widget Timing==<br />
<br />
The particular implementation in the ''SignalAcquisition'' library contains features that will help you verify and debug your widget's timing.<br />
<br />
#. In the Serial Monitor of the Arduino IDE, first send the commands to set the acquisition parameters the way you want them. (NB: where you see <code>\n</code> above, do not literally type a backslash followed by an <code>n</code>: the <code>\n</code> stands for the newline character, which the Serial Monitor will append for you when you press return.)<br />
#. Then, additionally send <code>debugCommOverhead=1</code> to enable measurement of the serial-port overhead.<br />
#. Then send <code>mute=0</code> to begin sending sample-blocks.<br />
#. Send <code>mute=1;?</code> to stop the flow and examine variables.<br />
#. Repeatedly alternate <code>mute=0</code> with <code>mute=1;?</code> to take multiple readings.<br />
<br />
Verify the following:<br />
<br />
#. The <code>idleLoops</code> variable should be reliably greater than 0 when queried with <code>mute=1;?</code> . If it is 0, this indicates that your sketch may be unable to keep up with the desired sample rate. You need to reduce <code>samplesPerSecond</code>.<br />
#. The <code>debugCommOverhead</code> variable will now contain a timing measurement indicating the number of microseconds it took to send data over the serial port for the last sample-block. This will be roughly proportional to the number of channels and the number of samples per block. It should not exceed the sample period in microseconds (<code>1e6/samplesPerSecond</code>): if it does, your data will contain readings that were unevenly sampled in time. In that case, you should reduce <code>samplesPerSecond</code>, reduce <code>samplesPerBlock</code>, or reduce the number of channels in <code>sourcePins</code>.<br />
<br />
As of version 1.4.0 of the ''SignalAcquisition'' library, you can also probe the capabilities of your system by setting <code>debugSampleInterval=1</code>, then setting <code>samplesPerSecond</code> too high and repeatedly querying the <code>debugSampleInterval</code> variable. This gives you an empirical measurement of the interval between the sample before last and the last one in microseconds. (With <code>debugSampleInterval</code> set to non-zero you can also use BCI2000 to do something similar: set the <code>SamplingRate</code> parameter too high, and use the timing window to look at the difference between nominal and measured sample-block durations.) Remember to set <code>debugSampleInterval=0</code> when you have finished debugging - this will the system more responsive to, and allow more robust recovery from, transient timing hiccups (continued tolerance of overly long sample intervals will lead to data loss).<br />
<br />
==See also==<br />
[[User Reference:DataIOFilter]], [[Programming Reference:GenericADC Class]], [[Contributions:SerialInterface]]<br />
<br />
[[Category:Filters]][[Category:Data Acquisition]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12299User Reference:Custom GUI Commands2026-01-26T00:12:54Z<p>Jhill: /* CUSTOM DIALOG ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths one per line (<code>FOR ... IN ...</code> can iterate over these).<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to give the user the option of overriding the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>] [CATALOG <listVariableName>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>] [CATALOG <listVariableName>]</code></code><br />
: 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><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button. If the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding. The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). For most purposes, you will probably not need to override the button configuration explicitly. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
; <code>CACHEFILE <FILENAME></code><br />
: 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><br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
cachefile "${parent directory $0}/launcherDialogVars.bci"<br />
var subjectName "Subject ID:" {} default "$subjectName" minimum 1<br />
var runType "Run Type:" {Calibration|Free Selection}<br />
var condition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm}<br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window # unless you have some other remote-control mechanism for suspending/resuming runs<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]<br />
<br />
====Example of <code>CATALOG</code> usage====<br />
<br />
The <code>CATALOG</code> option allows you to keep track of one or more lists of variable names. It helps to cut down on boilerplate repetition in certain common patterns. Here is an example:<br />
<br />
<pre><br />
<br />
# Create some new parameters<br />
add parameter Application:Custom%20Stimuli float MinStimulusGap= 100ms 100ms 0 % // minimum gap to use in custom stimulus generation<br />
add parameter Application:Custom%20Stimuli float MaxStimulusGap= 400ms 400ms 0 % // maximum gap to use in custom stimulus generation<br />
<br />
<br />
# In the dialog, some entries will be environment variables with exactly<br />
# the same names as parameters - let's catalog these<br />
if [ ${<br />
custom dialog<br />
var SubjectName "Subject:" {} minimum 1 default "Nobody" catalog DialogParams<br />
var MaxStimulusGap "Minimum Gap:" {0ms|50ms|100ms|200ms|400ms} default "100ms" catalog DialogParams <br />
var MinStimulusGap "Maximum Gap:" {0ms|50ms|100ms|200ms|400ms} default "400ms" catalog DialogParams <br />
var RunType "Run Type:" {Calibration.prm|FreeSpelling.prm}<br />
<br />
cachefile "${parent directory $0}/launcherDialogVars.bci"<br />
<br />
} == "" ]; quit; end<br />
<br />
<br />
# ...<br />
<br />
# The catalog saves us from having to hard-code a list of the new parameter names a third time:<br />
for var in $DialogParams <br />
set parameter $var ${$var}<br />
# We chose the environment variable names to be the same as the corresponding parameter names.<br />
end<br />
<br />
# This dialog variable is handled differently, so we did not catalog it with the others:<br />
load parameterfile $RunType<br />
<br />
</pre><br />
<br />
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.<br />
<br />
====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"====<br />
<br />
Each <code>VAR</code> entry may also have a modifier that overrides its visibility and whether the user can actually change it.<br />
<br />
* 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).<br />
* 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).<br />
<br />
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).<br />
<br />
<pre><br />
# "wizard" example leveraging `visible=false` and `fixed=true` modifiers<br />
<br />
add parameter Application:Robot string TaskVariant= Active % % % // None or Passive or Active<br />
add parameter Application:Robot float ActivePulseDuration= 100ms % 50ms % // <br />
add parameter Application:Robot float ActivePulseISI= 100ms % 10ms % // <br />
add parameter Application:Robot float PassiveStandardDuration= 100ms % 50ms % // <br />
add parameter Application:Robot float PassiveDurationDelta= 100ms % 10ms % // <br />
<br />
wizardStage := 1<br />
set variable response "-"<br />
while [ $response != Launch ] && [ $response != "" ] # NB: QUIT will not succeed if placed inside the WHILE loop, and there is no BREAK<br />
if [ $wizardStage == 1 ]<br />
set environment TaskVariant ""<br />
set variable buttons {cancel|Next}<br />
set variable defaultButton Next<br />
elseif [ $wizardStage == 2 ]<br />
set variable buttons {cancel|Previous|Launch}<br />
set variable defaultButton Launch<br />
end<br />
set variable response ${<br />
custom dialog<br />
var SUBJECTNAME "Subject:" {} <br />
default "Nobody" minimum 1 <br />
var TaskVariant "Task Variant:" {None|Passive|Active} <br />
default "Active" minimum 1 catalog DialogParams fixed=${[ $wizardStage != 1 ]}<br />
var PassiveStandardDuration "Passive Standard Duration:" {50ms|100ms|150ms|200ms|250ms} <br />
default "100ms" minimum 1 catalog DialogParams visible=${[ $TaskVariant == "Passive" ]}<br />
var PassiveDurationDelta "Passive Duration Delta:" {0ms|10ms|20ms|30ms|40ms|50ms|60ms|70ms|80ms|90ms|100ms} <br />
default "100ms" minimum 1 catalog DialogParams visible=${[ $TaskVariant == "Passive" ]}<br />
var ActivePulseDuration "Active Pulse Duration:" {50ms|100ms|150ms|200ms|250ms} <br />
default "100ms" minimum 1 catalog DialogParams visible=${[ $TaskVariant == "Active" ]}<br />
var ActivePulseISI "Active Pulse ISI:" {0ms|10ms|20ms|30ms|40ms|50ms|60ms|70ms|80ms|90ms|100ms} <br />
default "100ms" minimum 1 catalog DialogParams visible=${[ $TaskVariant == "Active" ]}<br />
message "(no task-specific parameters)" visible=${[ $task == None ]}<br />
top 200<br />
width 400<br />
cachefile "${parent directory $0}/launcherDialogVars.bci"<br />
buttons $buttons default $defaultButton escape cancel<br />
}<br />
if [ $response == "Previous" ]; wizardStage := wizardStage - 1; end<br />
if [ $response == "Next" ]; wizardStage := wizardStage + 1; end<br />
end<br />
if [ $response == "" ]; quit; end<br />
<br />
for x in $DialogParams<br />
set parameter $x ${$x}<br />
end<br />
</pre></div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12283User Reference:Custom GUI Commands2026-01-08T00:31:03Z<p>Jhill: /* CUSTOM DIALOG ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths one per line (<code>FOR ... IN ...</code> can iterate over these).<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to give the user the option of overriding the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>] [CATALOG <listVariableName>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>] [CATALOG <listVariableName>]</code></code><br />
: 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><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button. If the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding. The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). For most purposes, you will probably not need to override the button configuration explicitly. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
; <code>CACHEFILE <FILENAME></code><br />
: 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><br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
cachefile "${parent directory $0}/launcherDialogVars.bci"<br />
var subjectName "Subject ID:" {} default "$subjectName" minimum 1<br />
var runType "Run Type:" {Calibration|Free Selection}<br />
var condition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm}<br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window # unless you have some other remote-control mechanism for suspending/resuming runs<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]<br />
<br />
====Example of <code>CATALOG</code> usage====<br />
<br />
The <code>CATALOG</code> option allows you to keep track of one or more lists of variable names. It helps to cut down on boilerplate repetition in certain common patterns. Here is an example:<br />
<br />
<pre><br />
<br />
# Create some new parameters<br />
add parameter Application:Custom%20Stimuli float MinStimulusGap= 100ms 100ms 0 % // minimum gap to use in custom stimulus generation<br />
add parameter Application:Custom%20Stimuli float MaxStimulusGap= 400ms 400ms 0 % // maximum gap to use in custom stimulus generation<br />
<br />
<br />
# In the dialog, some entries will be environment variables with exactly<br />
# the same names as parameters - let's catalog these<br />
if [ ${<br />
custom dialog<br />
var SubjectName "Subject:" {} minimum 1 default "Nobody" catalog DialogParams<br />
var MaxStimulusGap "Minimum Gap:" {0ms|50ms|100ms|200ms|400ms} default "100ms" catalog DialogParams <br />
var MinStimulusGap "Maximum Gap:" {0ms|50ms|100ms|200ms|400ms} default "400ms" catalog DialogParams <br />
var RunType "Run Type:" {Calibration.prm|FreeSpelling.prm}<br />
<br />
cachefile "${parent directory $0}/launcherDialogVars.bci"<br />
<br />
} == "" ]; quit; end<br />
<br />
<br />
# ...<br />
<br />
# The catalog saves us from having to hard-code a list of the new parameter names a third time:<br />
for var in $DialogParams <br />
set parameter $var ${$var}<br />
# We chose the environment variable names to be the same as the corresponding parameter names.<br />
end<br />
<br />
# This dialog variable is handled differently, so we did not catalog it with the others:<br />
load parameterfile $RunType<br />
<br />
</pre><br />
<br />
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.</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12282User Reference:Custom GUI Commands2026-01-07T16:03:07Z<p>Jhill: /* CUSTOM DIALOG ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths one per line (<code>FOR ... IN ...</code> can iterate over these).<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to give the user the option of overriding the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>] [CATALOG <listVariableName>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>] [CATALOG <listVariableName>]</code></code><br />
: 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><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button. If the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding. The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). For most purposes, you will probably not need to override the button configuration explicitly. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
; <code>CACHEFILE <FILENAME></code><br />
: 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><br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
cachefile "${parent directory $0}/launcherDialogVars.bci"<br />
var subjectName "Subject ID:" {} default "$subjectName" minimum 1<br />
var runType "Run Type:" {Calibration|Free Selection}<br />
var condition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm}<br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window # unless you have some other remote-control mechanism for suspending/resuming runs<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]<br />
<br />
====Example of <code>CATALOG</code> usage====<br />
<br />
The <code>CATALOG</code> option allows you to keep track of one or more lists of variable names. It helps to cut down on boilerplate repetition in certain common patterns. Here is an example:<br />
<br />
<pre><br />
<br />
# Create some new parameters<br />
add parameter Application:Custom%20Stimuli float MinStimulusGap= 100ms 100ms 0 % // minimum gap to use in custom stimulus generation<br />
add parameter Application:Custom%20Stimuli float MaxStimulusGap= 400ms 400ms 0 % // maximum gap to use in custom stimulus generation<br />
<br />
<br />
# In the dialog, some entries will be environment variables with exactly the<br />
# same names as parameters - let's catalog these<br />
if [ ${<br />
custom dialog<br />
var SubjectName "Subject:" {} minimum 1 default "Nobody" catalog DialogParams<br />
var MaxStimulusGap "Minimum Gap:" {0ms|50ms|100ms|200ms|400ms} default "100ms" catalog DialogParams <br />
var MinStimulusGap "Maximum Gap:" {0ms|50ms|100ms|200ms|400ms} default "400ms" catalog DialogParams <br />
var RunType "Run Type:" {Calibration.prm|FreeSpelling.prm}<br />
<br />
cachefile "${parent directory $0}/launcherDialogVars.bci"<br />
<br />
} == "" ]; quit; end<br />
<br />
<br />
# ...<br />
<br />
for var in $DialogParams # The catalog saves you from having to hard-code a list of the new parameter names a third time.<br />
set parameter $var ${$var} # We chose the environment variable names to be the same as the corresponding parameter names.<br />
end<br />
<br />
load parameterfile $RunType # This dialog variable is handled differently, so we did not catalog it with the others.<br />
<br />
<br />
</pre><br />
<br />
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.</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12131User Reference:Custom GUI Commands2025-10-10T15:59:26Z<p>Jhill: /* CUSTOM DIALOG ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths one per line (<code>FOR ... IN ...</code> can iterate over these).<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to give the user the option of overriding the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button. If the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding. The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). For most purposes, you will probably not need to override the button configuration explicitly. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
; <code>CACHEFILE <FILENAME></code><br />
: 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><br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
cachefile "${parent directory $0}/launcherDialogVars.bci"<br />
var subjectName "Subject ID:" {} default "$subjectName" minimum 1<br />
var runType "Run Type:" {Calibration|Free Selection}<br />
var condition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm}<br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window # unless you have some other remote-control mechanism for suspending/resuming runs<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12130User Reference:Custom GUI Commands2025-10-10T15:58:33Z<p>Jhill: /* CUSTOM DIALOG ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths one per line (<code>FOR ... IN ...</code> can iterate over these).<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to give the user the option of overriding the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button. If the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding. The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). For most purposes, you will probably not need to override the button configuration explicitly. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
; <code>CACHEFILE <FILENAME></code><br />
: 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><br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
cachefile "${parent directory $0}/launcherDialogVars.bci"<br />
var subjectName "Subject ID:" {} default "$subjectName" minimum 1<br />
var runType "Run Type:" {Calibration|Free Selection}<br />
var condition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm}<br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window # unless you have some other remote-control mechanism for suspending/resuming runs<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12128User Reference:Custom GUI Commands2025-10-09T02:08:59Z<p>Jhill: /* Integrated CUSTOM DIALOG example */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths one per line (<code>FOR ... IN ...</code> can iterate over these).<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to give the user the option of overriding the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button. If the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding. The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). For most purposes, you will probably not need to override the button configuration explicitly. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
; <code>CACHEFILE <FILENAME></code><br />
: 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><br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
cachefile "${parent directory $0}/launcherDialogVars.bci"<br />
var subjectName "Subject ID:" {} default "$subjectName" minimum 1<br />
var runType "Run Type:" {Calibration|Free Selection}<br />
var condition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm}<br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window # unless you have some other remote-control mechanism for suspending/resuming runs<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12127User Reference:Custom GUI Commands2025-10-08T23:33:23Z<p>Jhill: /* Integrated CUSTOM DIALOG example */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths one per line (<code>FOR ... IN ...</code> can iterate over these).<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to give the user the option of overriding the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button. If the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding. The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). For most purposes, you will probably not need to override the button configuration explicitly. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
; <code>CACHEFILE <FILENAME></code><br />
: 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><br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
cachefile "${parent directory $0}/launcherDialogVars.bci"<br />
var subjectName "Subject ID:" {} default "$subjectName" <br />
var runType "Run Type:" {Calibration|Free Selection}<br />
var condition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm}<br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window # unless you have some other remote-control mechanism for suspending/resuming runs<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12126User Reference:Custom GUI Commands2025-10-08T23:32:29Z<p>Jhill: /* CUSTOM DIALOG ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths one per line (<code>FOR ... IN ...</code> can iterate over these).<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to give the user the option of overriding the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button. If the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding. The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). For most purposes, you will probably not need to override the button configuration explicitly. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
; <code>CACHEFILE <FILENAME></code><br />
: 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><br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
cachefile "${parent directory $0}/launcherDialogVars.bci"<br />
var subjectName "Subject ID:" {} default "$subjectName" <br />
var runType "Run Type:" {Calibration|Free Selection}<br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm}<br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window # unless you have some other remote-control mechanism for suspending/resuming runs<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12125User Reference:Custom GUI Commands2025-10-08T03:31:16Z<p>Jhill: /* CUSTOM DIALOG ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths one per line (<code>FOR ... IN ...</code> can iterate over these).<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to give the user the option of overriding the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button. If the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding. The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). For most purposes, you will probably not need to override the button configuration explicitly. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
; <code>CACHEFILE <FILENAME></code><br />
: 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.<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
# [optionally, you could pre-initialize environment variables subjectName, runType and stimulusCondition]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window # unless you have some other remote-control mechanism for suspending/resuming runs<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12124User Reference:Custom GUI Commands2025-10-08T03:30:30Z<p>Jhill: /* CUSTOM DIALOG ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths one per line (<code>FOR ... IN ...</code> can iterate over these).<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to give the user the option of overriding the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button. If the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding. The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). For most purposes, you will probably not need to override the button configuration explicitly. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
; <code>CACHEFILE <FILENAME></code><br />
: 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.<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
# [optionally, you could pre-initialize environment variables subjectName, runType and stimulusCondition]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window # unless you have some other remote-control mechanism for suspending/resuming runs<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Operator_Module_Scripting&diff=12120User Reference:Operator Module Scripting2025-10-04T00:35:06Z<p>Jhill: /* Commands operating on Environment Variables */</p>
<hr />
<div>Operator scripts automate actions that the otherwise would be performed by the user, e.g. starting or suspending system operation.<br />
Scripts may be contained in script files, or given immediately in the operator module's preferences dialog.<br />
There is also an option to specify scripts from the [[User Reference:Module Command Line Options#Operator Module|command line]] when starting the operator module. When using the [[User_Reference:BCI2000Shell|BCI2000Shell]], or the [[Technical_Reference:Operator_Library|Operator Library]] from your own application, you may execute scripts at any time.<br />
<br />
In addition, the operator scripting language may be used to control an operator module over a [[User_Reference:Module_Command_Line_Options#--Telnet|Telnet]] or [[User_Reference:Module_Command_Line_Options#--WebSocket|WebSocket]] connection.<br />
===Syntax===<br />
'''Command separation.''' Scripts consist of sequences of the commands listed below. A command must be terminated with either a newline, or a semicolon (;).<br />
This allows to put multiple commands into one line, separated by semicolon characters.<br />
Commands are case-insensitive, variables and values may be case-sensitive, depending on context.<br />
<br />
'''Comments.''' Lines starting with a '#' character are ignored. Such lines may be used to hold comments. In addition, when any of the first two lines of a script contains "#!" (the Unix shell invocation sequence), it will be ignored. In conjunction with [[User Reference:BCI2000Shell|BCI2000Shell]], this may be used to write Operator scripts that may be treated as executables.<br />
<br />
'''Escaping.''' In order to resolve ambiguity about command arguments that contain white space, they must be included in double quotes, or the white space must be encoded in URL-fashion, e.g. ''%20'' instead of a space character. Similarly, when an argument contains a semicolon (;), it must be included in double quotes, or the semicolon must be encoded in URL-fashion, i.e. as ''%3B''. Also, "$" characters indicate command substitution, so they should be encoded as ''%24'' if substitution is not desired.<br />
<br />
'''Variable Substitution.''' When a command contains a dollar sign, alphanumeric characters following the dollar sign will be interpreted as the name of a variable: $NAME. The name will be matched against Expression variable names first, followed with Local variable names, and finally Environment variable names. When a match is found, $NAME will be replaced with the content of the matching variable. When no match is found, $NAME will be resolved to an empty string, without triggering an error.<br />
<br />
'''Command Substitution.''' When part of a command is enclosed with ${...}, this subexpression will be substituted with the result of its execution as a command. E.g.,<br />
LOG "Current system state is: ${GET SYSTEM STATE}"<br />
LOG "The path environment variable is: ${PATH}"<br />
Note that the last example uses the short form of the GET command, which will return the value of a PATH parameter or a PATH state if such exists. To make sure that only environment variables are matched, use the long form of the GET command:<br />
LOG MESSAGE "The path environment variable is: ${GET VARIABLE PATH}"<br />
Substitutions may be nested, i.e. the following will work as expected:<br />
SET MyVar "LIST STATES"; LOG "States are: ${$MyVar}"<br />
SET MyVar "LIST STATES"; LOG "States are: ${${GET VARIABLE MyVar}}"<br />
<br />
'''Mathematical Expressions.''' A command may consist of a single [[User Reference:Expression Syntax|mathematical expression]]. This expression is then evaluated, and its result is returned as the command's result. As a special case, this allows the use of expression variables in ${...} substitutions. Consider for example<br />
x:=0; WHILE x<10; LOG ${x:=x+1}; END<br />
There, the first command creates and initializes the expression variable x. In the WHILE condition, an expression is allowed as well as any command. In the LOG command, an expression appears in ${...}, which executes the expression in braces, and substitutes the result of the expression as an argument into the LOG command, which adds an entry to the Operator log. This results in a sequence of 10 log entries, containing the numbers from 1 to 10.<br />
<br />
===Commands===<br />
====Control commands====<br />
These commands allow conditional execution of parts of a script. When a condition is expected, any other scripting command may be given. Its result will be considered to represent a boolean value of "true" if it is empty, a nonzero number, or the string "true". It will be taken to represent a boolean value of "false" if it contains a numeric value of zero, or any string that does not evaluate to a nonzero number. Note that identification of an empty value with "true" differs from string handling in the EVALUATE CONDITION command. This is because most scripting commands return nothing on success, but an error message on failure.<br />
<br />
The output of the SYSTEM and START EXECUTABLE commands is handled specially. There, the result code of the created child process is translated into a boolean value in the ordinary manner, treating a result code of zero as "true", and any other result code as "false". This allows to use external commands in the same way as in a native shell.<br />
<br />
=====IF <condition>; <if commands>; [ ELSEIF <condition>; <elseif commands>;] ... [ ELSE; <else commands>;] END=====<br />
Executes ''if commands'' if ''condition'' evaluates to "true". Otherwise, the ''elseif commands'' of the first matching ''elseif condition'' are executed. When none of the ''elseif conditions'' evaluates to "true", ''else commands'' are executed. ELSEIF and ELSE blocks may be omitted.<br />
<br />
=====WHILE <condition>; <loop commands>; END=====<br />
Executes ''loop commands'' while ''condition'' evaluates to ''true''.<br />
=====DO; <loop commands>; UNTIL <condition>=====<br />
Executes ''loop commands'' until "condition" evaluates to ''true''.<br />
=====FOR <name> IN <item1> <item2> ... ; <loop commands>; END=====<br />
Creates a local variable with the specified name. Then, sequentially assigns each ''item'' to that variable, and executes ''loop commands''. If an ''item'' contains newline characters, it is split up into multiple items, corresponding to the lines contained in the ''item''. E.g.,<br />
FOR i IN top ${LIST FILES} bottom; LOG ${i}; END<br />
will first write a log entry "top". Then, it will create a log entry for each file in the current directory, and finally, it will create a log entry "bottom".<br />
=====RETURN [<value>]=====<br />
Finishes execution of the current script, and optionally returns a value to the caller.<br />
<br />
====Commands operating on Conditions====<br />
=====EVALUATE CONDITION <left> [<op> [<right>]]=====<br />
Evaluates a comparison between the ''left'' and ''right'' operands. As a comparison operator, the following may be specified: ==, !=, ~=, <, >, <=, >=. There, the != operator behaves identically to the ~= operator. When a test for equality is performed, the two operands are treated as strings, and compared in a case-insensitive manner. When any of the inequality tests is performed, the two operands are converted into floating-point numbers before comparison.<br />
<br />
The ''right'' operand may be omitted, in which case it is treated as if an empty string were specified. Also, the ''op'' operator may be omitted, in which case the following rules apply regarding the remaining operand: If it is an empty string, or equal to the string "false" in case-insensitive comparison, the result is "false". If entirely consists of the text representation of a floating-point number, the result is "false" if the number is 0, and "true" if the number is not 0.<br />
<br />
Inspired by the unix sh shells' <tt>test</tt> command, there exists a short form of the EVALUATE CONDITION command, where the arguments of EVALUATE CONDITION may appear within square brackets. This allows constructs such as<br />
IF [ ${MyVar} == MyValue ]; LOG Is equal; ELSE; LOG Is different; END<br />
Note that the arguments to EVALUATE CONDITION must always be separated by white space, no matter whether its long or short form is used.<br />
<br />
Conditions may be combined logically using the operators && and ||. These go ''outside'' the square brackets. Note also that whitespace around the comparison operators is critical, otherwise the conditional will be treated as a single string (which will always evaluate to "true")<br />
<br />
IF [ ${foo} == foo ] || [ ${bar} == bar ]; LOG got a match; END<br />
<br />
====Commands operating on Local Variables====<br />
Besides environment variables, there exist local variables in scripts. Local variables are inherited by sub-scripts executed with the EXECUTE SCRIPT command, but changes to the variable's values will not be propagated to the calling script.<br />
=====SET VARIABLE <name> <value>=====<br />
Sets the named variable to the specified value.<br />
=====CLEAR VARIABLE <name>=====<br />
Removes the named variable from memory.<br />
=====GET VARIABLE <name>=====<br />
Returns the variable's current value. When the variable does not exist, an empty value is returned rather than an error message generated.<br />
<br />
====Commands operating on Environment Variables====<br />
These scripting commands allow to read and modify environment variables. Changes to environment variables will be visible to child processes started with SYSTEM or START EXECUTABLE. Variable values are stored as strings. Variable names may not contain the equals sign.<br />
=====SET ENVIRONMENT <name> <value>=====<br />
Sets the named variable to the specified value.<br />
=====CLEAR ENVIRONMENT <name>=====<br />
Removes the named variable from memory.<br />
=====GET ENVIRONMENT <name>=====<br />
Returns the variable's current value. When the variable does not exist, an empty value is returned rather than an error message.<br />
=====WRITE ENVIRONMENT <fileName> <variableName1> <variableName2> ...=====<br />
Writes a series of SET ENVIRONMENT statements to the specified file, overwriting any previous file contents. This saves the values of the named variables in such a way that you can later load them back by calling EXECUTE SCRIPT <filename>. The variable names may refer to either local or environment variables at the time of writing, but when you execute the script they will all be loaded as environment variables.<br />
=====APPEND ENVIRONMENT <fileName> <variableName1> <variableName2> ...=====<br />
This is the same as WRITE ENVIRONMENT, except that the SET ENVIRONMENT statements are appended to the named file without overwriting its previous contents.<br />
<br />
====Commands operating on Scripts====<br />
=====SET SCRIPT <handler names> <scripting commands>=====<br />
Associates a sequence of scripting commands with the named handler. Handlers are specified by names as given [[#Handlers|below]]. Multiple handlers may be specified by concatenating their names with a pipe character, e.g. "OnStart|OnResume".<br />
<br />
Scripting commands must be included in double quotes, unless they consist of a single word.<br />
When specifying a sequence of scripting commands, they must be separated with a semicolon character: "SetConfig; Start". In order to use double quotes or semicolons within the commands themselves, encode these as you would in a URL, i.e. replace a double quote character with ''%22'', and a semicolon with ''%3B'': "Load Parameters %22my file%22".<br />
<br />
To use a script file rather than a literal script, use the EXECUTE SCRIPT command:<br />
SET SCRIPT OnConnect "EXECUTE SCRIPT myscript.txt"<br />
<br />
=====GET SCRIPT <handler name>=====<br />
Returns the script associated with the specified handler.<br />
<br />
=====CLEAR SCRIPT <handler names>=====<br />
Clears scripts for the given handlers. Equivalent to calling SET SCRIPT with an empty script.<br />
<br />
=====EXECUTE SCRIPT <file or handler name> [<Arg1> <Arg2> ... <Arg9>]=====<br />
Executes a script contained in a file, and optionally sets the script's local variables ''1'' to ''9'' to the specified values. To execute script commands already associated with a handler, provide a handler name rather than a file. When the script is executed successfully, the result of the last executed script command becomes the result of the EXECUTE SCRIPT command itself. Use "RETURN <value>" anywhere in a script in order to finish execution, and return a certain value.<br />
<br />
When you run a script through EXECUTE SCRIPT, it will inherit copies of variables from its calling script/command line. Modifications of variables will be local to the script, and will be lost when script execution is complete.<br />
<br />
The ''AbortOnError'' variable determines whether a script is aborted when any of its commands result in an error message. ''AbortOnError'' is not inherited but defaults to 1 in any script.<br />
<br />
====Commands operating on Parameters====<br />
=====LOAD PARAMETERFILE <file>, LOAD PARAMETERS <file>=====<br />
Loads a parameter file specified by its path and name. Relative paths are interpreted relative to the operator module's working directory at startup. Usually, this matches the executable's location in the <tt>prog</tt> directory.<br />
As the parameter file name must not contain white space, please use HTML-type encoding for white space characters, such as <tt>Documents%20and%20Settings</tt> when referring to a user's "Documents and Settings" folder.<br />
<br />
NOTE: Only those parameters will be loaded that do exist at the time when this command is called. In idle state, no parameters exist other than created by ADD PARAMETER. After modules are connected and have published their parameters to the Operator module, a full set of parameters exists.<br />
<br />
=====ADD PARAMETER <parameter definition>=====<br />
Adds a parameter to the system. The parameter is specified as a [[Technical_Reference:Parameter_Definition#Parameter_Lines|parameter line]]. This command may not be used after system initialization has completed, i.e. its use is restricted to the "Idle" and "Publishing" [[Technical_Reference:States_of_Operation#Publishing_Phase|phases of system operation]]. In terms of handlers, its use is restricted to the ''OnConnect'' handler.<br />
=====EXISTS PARAMETER <name>=====<br />
Returns "true" when the specified parameter exists in the system, and "false" otherwise.<br />
<br />
=====ISEMPTY PARAMETER <name>=====<br />
Returns "true" when the specified parameter exists and has no values, "false" if it exists and has values.<br />
<br />
=====SET PARAMETER <name>[( idx1, idx2 )] <value>=====<br />
Sets the named parameter to the specified value. Values that contain special characters, or whitespace must use the [[Technical_Reference:Parameter_Definition#Special_Characters|parameter value encoding]]. Use parentheses to specify indices or labels. Omitted indices default to 1.<br />
<br />
=====SET PARAMETER <parameter line>=====<br />
Replace a parameter's value and definition with the information given in the [[Technical_Reference:Parameter_Definition#Parameter_Lines|parameter line]]. The parameter must exist in the system when this command is executed.<br />
<br />
=====GET PARAMETER <name>[( idx1, idx2 )]=====<br />
Prints the value of the named parameter. Use parentheses to specify indices or labels.<br />
<br />
=====SET PARAMETERROWS <parameter name> <rows>=====<br />
Sets the number of rows in the named parameter.<br />
<br />
=====GET PARAMETERROWS <parameter name>=====<br />
Prints the number of rows in the named parameter.<br />
<br />
=====SET PARAMETERCOLS <parameter name>=====<br />
Sets the number of columns in the named parameter.<br />
<br />
=====GET PARAMETERCOLS <parameter name>=====<br />
Prints the number of columns in the named parameter.<br />
<br />
=====LIST PARAMETER <wildcard expression>, LIST PARAMETERS=====<br />
Prints all parameters with names matching the wildcard expression, in form of parameter lines.<br />
=====CLEAR PARAMETERS=====<br />
Clears the list of parameters in the system. May only be executed in ''Idle'' and ''Publishing'' system states.<br />
<br />
====Commands operating on States====<br />
In BCI2000, there are three types of States that differ in their alignment to brain signal data (see [[Technical_Reference:State_Definition#Kinds_of_States|Kinds of States]]). This section applies to both Stream States, and normal States.<br />
For Event States, see the next section.<br />
<br />
=====ADD STATE <name> <bit width> <initial value>=====<br />
Adds a state variable to the system. State variables are defined by name, bit width, and initial value (see [[Technical Reference:State Definition]]). This command may not be used after system initialization has completed, i.e. its use is restricted to the "Idle" and "Publishing" [[Technical_Reference:States_of_Operation#Publishing_Phase|phases of system operation]]. In terms of handlers, its use is restricted to the ''OnConnect'' handler.<br />
=====EXISTS STATE <name>=====<br />
Returns "true" when the specified state exists in the system, and "false" otherwise.<br />
<br />
=====SET STATE <name> <value>, SET STATES <name1> <value1> <name2> <value2> ...=====<br />
Sets the named state variable to the specified integer value by sending a state message to the source module.<br />
Setting the ''Running'' state to 1 will start system operation, setting it to 0 will suspend the system.<br />
<br />
<tt>SET STATES</tt> will atomically set the values of multiple states.<br />
<br />
=====GET STATE[(<sample>)] <name>=====<br />
Gets the value of the named state. Note that state values are not updated from the application module when the ''OperatorBackLink'' parameter is 0. In that case, GET STATE will return the state's initial value.<br />
<br />
An optional one-based sample index may be given to indicate that the state value should be retrieved at the given sample position. Sample positions range from 1 to the number of samples per block present in the state vector. The number of samples per block may be retrieved using GET STATEVECTOR SAMPLES.<br />
<br />
By default, the state's value is retrieved for sample index 1.<br />
<br />
=====LIST STATE <wildcard expression>, LIST STATES=====<br />
Lists all states, or states with names matching the given wildcard expression, in form of state lines.<br />
=====CLEAR STATES=====<br />
Clears the list of states in the system. May only be executed in ''Idle'' and ''Publishing'' system states.<br />
<br />
=====FREEZE STATES, THAW STATES=====<br />
Freezes/thaws the values of all states in the state vector, without interfering with system operation. "Freezing" creates, and "thawing" discards, a frozen snapshot of the state vector. For the duration of its existence, GET STATE calls will be diverted to the snapshot. This is useful for ensuring that multiple GET STATE commands actually retrieve mutually-consistent values from different state variables (i.e. values from the same sample-block).<br />
<br />
=====GET STATEVECTOR SAMPLES=====<br />
Returns the number of samples in the state vector per block of data. In the system's "Running" state, this matches the number of samples per block in the source data. Prior to the "Running" state, this command returns 1 because the state vector has not yet been updated from the application module.<br />
<br />
====Commands operating on Events====<br />
Events are a special type of state, which are recorded asynchronously, at single-sample resolution. Events may only be added while the system is in "idle" state. This kind of events is not related to [[#Handlers|Operator Events]] as defined below.<br />
=====ADD EVENT <name> <bit width> <initial value>=====<br />
Adds an event to the system. Like state variables, events are defined by name, bit width, and initial value (see [[Technical Reference:State Definition]]). This command may not be used after the system has started up, so it is typically executed in a batch file before ''STARTUP'' has been called.<br />
<br />
=====EXISTS EVENT <name>=====<br />
Returns "true" when the specified event exists in the system, and "false" otherwise.<br />
<br />
=====SET EVENT <name> <value>=====<br />
Asynchronously sets an event to the given value. Recording events requires the EventLink logger component to be present in the source module.<br />
<br />
'''NOTE:''' In versions prior to BCI2000 3.06, this command behaved as described for PULSE EVENT below, rather than as advertised. If you used SET EVENT in your scripts, it is recommended to replace it with PULSE EVENT in order to retain original behavior.<br />
<br />
=====PULSE EVENT <name> <value>=====<br />
Asynchronously sets an event to the given value for a single sample duration. Recording events requires the EventLink logger component to be present in the source module.<br />
<br />
=====SET EVENTS [<name> <value>] [<name2> <value2>] ... =====<br />
Asynchronously sets given events to their specified values. Using this command, rather than multiple SET EVENT commands in a row, ensures that all event changes are recorded at exactly the same point in time. Recording events requires the EventLink logger component to be present in the source module.<br />
<br />
=====PULSE EVENTS [<name> <value>] [<name2> <value2>] ... =====<br />
Asynchronously sets given events to their specified values for a single sample duration. Using this command, rather than multiple PULSE EVENT commands in a row, ensures that all event changes are recorded at exactly the same point in time. Recording events requires the EventLink logger component to be present in the source module.<br />
<br />
=====GET EVENT[(<sample>)] <name>=====<br />
Gets the value of the named event. Note that evemt values are not updated from the application module when the ''OperatorBackLink'' parameter is 0.<br />
<br />
An optional one-based sample index may be given to indicate that the event's value should be retrieved at the given sample position. Sample positions range from 1 to the number of samples per block present in the state vector. The number of samples per block may be retrieved using GET STATEVECTOR SAMPLES.<br />
<br />
By default, the event's value is retrieved for sample index 1.<br />
<br />
=====LIST EVENT <wildcard expression>, LIST EVENTS=====<br />
Lists all events, or events with names matching the given wildcard expression, in form of state lines.<br />
=====CLEAR EVENTS=====<br />
Clears the list of events in the system. May only be executed in ''Idle'' state.<br />
<br />
====Commands operating on VisProperties====<br />
=====SET VISPROPERTY <visID>.<name> <value>=====<br />
Sets the named [[Technical Reference:Visualization Properties|visualization property]] for the specified visualization ID to the given value. If the visualization ID contains a dot character, it must be encoded in [[Technical_Reference:Parameter_Definition#Special_Characters|parameter value encoding]]. E.g., setting the window width for the visualization ID "2.D1" would be written <code>SET VISPROPERTY 2%2ED1.Width 200</code>.<br />
<br />
=====RESET VISPROPERTY <visID>.<name>=====<br />
Removes the named visualization property with the specified visualization ID from the property store, effectively resetting its value to its default.<br />
<br />
=====GET VISPROPERTY <visID>.<name>=====<br />
Prints the value of the named [[Technical Reference:Visualization Properties|visualization property]] for the specified visualization ID.<br />
<br />
=====SET VISPROPERTIES <property set ID>=====<br />
Applies a set of visualization property values as given in the [[#VisPropertySets|VisPropertySets]] parameter. In that matrix-valued parameter, row labels specify visualization properties such as "SRCD.Left", and columns represent sets of property values. Column labels are IDs of the corresponding property sets.<br />
<br />
====Commands operating on the Control Signal====<br />
=====GET SIGNAL( <channel index>, <element index> )=====<br />
Prints the value of the control signal at the given indices. Indices are 1-based.<br />
=====GET SIGNAL CHANNELS=====<br />
Prints the number of channels in the control signal.<br />
=====GET SIGNAL ELEMENTS=====<br />
Prints the number of elements (samples) in the control signal.<br />
=====FREEZE SIGNAL, THAW SIGNAL=====<br />
Freezes/thaws the contents of the control signal, without interfering with system operation. "Freezing" creates, and "thawing" discards, a frozen snapshot of the control signal. For the duration of its existence, GET SIGNAL calls will be diverted to the snapshot. This is useful for ensuring that multiple GET SIGNAL commands actually retrieve mutually-consistent values from different elements in the control signal (i.e. values from the same sample-block).<br />
<br />
====Commands operating on Expressions====<br />
=====EVALUATE EXPRESSION <expression>=====<br />
This command treats the remainder of the command as a literal mathematical expression (for a description, see [[User Reference:Expression Syntax]]). An expression may contain assignments to variables; such variables may then be used in later expressions. Note that expression variables are different from local and environment variables that may be accessed by GET/SET VARIABLE/ENVIRONMENT. Expression variables hold numerical values, while local and environment variables hold string values. Also, environment variables are accessible to child processes started with SYSTEM or START EXECUTABLE, while expression variables are accessible only to scripts. When a script is executed using the EXECUTE SCRIPT command, it will inherit a copy of all expression variables present. Changes to these variables from the executed script will not be visible in the parent script.<br />
<br />
=====CLEAR EXPRESSION VARIABLE <name>=====<br />
Clears the named expression variable from storage.<br />
<br />
====Commands operating on Watches====<br />
A "Watch" is an object that consists of a set of expressions, and an action. Whenever the value of any of the expressions changes, the watch is "triggered", and the action is executed. Watches allow client applications to respond to BCI2000 state changes in a reliable manner. Rather than polling information from BCI2000, a client may create a watch to be notified about changes of interest. This avoids the problem of missing short-lived changes, which is inherent in the polling approach.<br />
<br />
For watches created through operator scripting, the action consists of dumping values of all the expressions to a UDP port.<br />
<br />
The intended use of a watch from a client application is to create a separate thread that reads from the watch's UDP port in a blocking mode, and calls an appropriate handler function whenever it receives data.<br />
The data sent will consist of a single UDP packet with a single line in ASCII format, terminated with a CRLF sequence. The line consists of tab-separated data fields, which contain the current values of the expressions specified when creating the watch. In addition, the first field contains a time stamp in milliseconds. This time stamp represents the point in time where the expression value changed, with an accuracy of a single sample.<br />
<br />
=====ADD WATCH [decimate <n>] <expression1> <expression2> ... [AT <ip:port>]=====<br />
Adds a watch for the listed expressions. Each expression's value will be reported in a separate field. When an address is specified in <tt>ip:port</tt> format, the watch tries to open that port for output, and creation fails if that port is taken. When no address is specified, a free port is chosen automatically. In both cases, successful creation of the watch is indicated by returning the output address in ASCII format. The address is also used to uniquely identify a watch in the context of a connection.<br />
<br />
When a ''decimate <n>'' clause is present, the watch will be created with decimation, i.e. it will only be evaluated for every ''n''th<br />
sample of the state vector.<br />
<br />
If a watch is created through a remote connection, it will use the remote host's external IP address for automatically chosen addresses. Otherwise, the output port will be associated with the machine's <tt>localhost</tt> address.<br />
<br />
Watches may be created even if the system is currently running. In this case, the watch is triggered immediately at creation, and sends its current expression values to its output port.<br />
<br />
=====ADD WATCH SYSTEM STATE [AT <address>]=====<br />
Similar to the first variant of ADD WATCH, but will watch the system's state as reported by GET SYSTEM STATE.<br />
<br />
=====CLEAR WATCH <address>, CLEAR WATCHES [<wildcard-expression>]=====<br />
Removes the watches specified by address, or those with their addresses matching a wildcard expression. If CLEAR WATCHES is called without argument, all watches will be deleted.<br />
<br />
=====TRIGGER WATCH <address>, TRIGGER WATCHES [<wildcard-expression>]=====<br />
Forces dumping of the watches' current expression values to their output ports. Mostly useful for testing purposes.<br />
<br />
=====LIST WATCHES [<wildcard-expression>]=====<br />
Displays a list of existing watches, and their addresses.<br />
<br />
=====COUNT WATCHES [<wildcard-expression>]=====<br />
Returns the number of existing watches, or the number of watches whose addresses match the optional wildcard expression.<br />
<br />
====Commands operating on Files, Directories, and Paths====<br />
=====EXTRACT DIRECTORY <path>, EXTRACT FILE <path>, EXTRACT FILE BASE <path>=====<br />
Extracts the directory or file portion of a given path. When the path specifies a non-existing directory, the directory name must be followed with a separator ("/") in order to be recognized as a directory. The EXTRACT DIRECTORY command always returns its result with a trailing separator. The EXTRACT FILE BASE command returns the file portion without extension.<br />
<br />
=====IS DIRECTORY <path>, IS FILE <path>, IS PATH <path>=====<br />
Determines whether the specified path points to an existing directory, file, or any of the two. The result is returned as one of the strings "true" or "false".<br />
=====PARENT DIRECTORY <path>=====<br />
Returns the parent directory of the specified path, independently of whether the path points to a directory, or to a file.<br />
=====CURRENT DIRECTORY=====<br />
Returns the current working directory. Note that working directories are per-script, i.e. multiple scripts running in parallel may have different working directories.<br />
<br />
=====CHANGE DIRECTORY <path>=====<br />
Changes the script's working directory. Note that working directories are per-script, i.e. multiple scripts running in parallel may have different working directories. Also, this command will only affect the default directory of scripting commands, not the application-global working directory as seen by the OS.<br />
<br />
=====MAKE DIRECTORY <path>=====<br />
Creates a new directory with the given path. The directory's parent must exist for the command to succeed.<br />
=====LIST DIRECTORY [<path> or <wildcard expression>]=====<br />
Returns a listing of the specified directory, or the current working directory if no path is specified. The listing is in long form. You may use wildcard expressions in order to restrict the output.<br />
=====LIST FILE <wildcard expression>=====<br />
Returns a list of file names matching ''wildcard expression'' in the current directory.<br />
=====LIST FILES [<directory> [<wildcard expression>]]=====<br />
Returns a list of file names from the specified directory, matching ''wildcard expression''. When ''wildcard expression'' is missing, all files are listed. When ''directory'' is missing, files in the current directory are listed.<br />
=====LIST DIRECTORIES [<directory> [<wildcard expression>]]=====<br />
Returns a list of directory names from the specified directory, matching ''wildcard expression''. When ''wildcard expression'' is missing, all directories are listed. When ''directory'' is missing, directories in the current directory are listed.<br />
<br />
=====RENAME FILE <current path> <new path>, RENAME DIRECTORY <current path> <new name>=====<br />
Renames a file resp. a directory. For files, a different path may be given in the second argument, resulting in that the file is moved to the location specified by the new path. For directories, the path up to the directory's name must stay the same.<br />
=====REMOVE FILE <path>, REMOVE DIRECTORY <path>=====<br />
Removes the specified file or directory. This command cannot be undone. The directory must be empty for the command to succeed.<br />
=====FORCEREMOVE DIRECTORY <path>=====<br />
Removes the specified directory and its contents. Symbolic links are treated as ordinary files, i.e. they are not followed. This command cannot be undone.<br />
=====NORMALIZED PATH <path>=====<br />
Returns <path>, with the following transformations applied:<br />
*Removes relative elements (<tt>..</tt> <tt>.</tt>) as far as possible. For absolute paths, the result will not contain any relative elements; for relative paths, double-dots may appear at the beginning of the result if necessary.<br />
If a relative path simplifies to the empty string, <tt>./</tt> is returned. Thus, the result of NORMALIZED PATH is never empty, unless its input was empty.<br />
*Replaces backward slashes with forward slashes to achieve uniformity across platforms.<br />
*On case-insensitive file systems, replaces the spelling of names with the one stored in the file system.<br />
*On Win32, replaces short (8.3) names with long ones.<br />
<br />
=====CANONICAL PATH <path>=====<br />
If <path> points to an existing file or directory, CANONICAL PATH returns a valid absolute file path, suitable as an unambiguous representation for the object pointed to. Especially, two non-empty canonical path strings will compare equal if and only if they refer to the same file system object.<br />
<br />
If <path> does not point to an existing file system object, construction of a canonical path is not possible due to lack of information about the named object, and CANONICAL PATH will return an empty string.<br />
<br />
'''NOTES:''' The need for an unambiguous, or canonical, representation arises due to ambiguities in the string representation of paths, and in file systems themselves.<br />
*Paths may contain relative elements: <tt>/mydir/../myfile</tt> points to the same object as <tt>/myfile</tt>.<br />
*A path that involves symbolic links will point to the same object as a path containing one or more of those links in resolved form.<br />
*File systems may be case-insensitive, or may even provide multiple distinct names for individual directory entries (Win32 short vs. long names).<br />
<br />
On '''Win32,''' CANONICAL PATH returns the short (8.3) representation of a path, using uppercase spelling, and backslashes as directory separators. Apart from efficiency considerations, this aesthetically unpleasing representation has been chosen to discourage its use for anything except comparing file system objects.<br />
<br />
On '''other systems,''' CANONICAL PATH will return the result of the POSIX <tt>realpath()</tt> function.<br />
<br />
In both cases, a CANONICAL PATH will end with a native directory separator if, and only if, the object pointed to is a directory.<br />
<br />
=====REAL PATH <path>=====<br />
On this command provides a work-alike for the POSIX <tt>realpath()</tt> function.<br />
If <path> is empty, or if <path> points to a non-existing object, the result will be empty. Otherwise, an absolute path will be returned, with symbolic links resolved, using forward slashes as directory separators, and with spelling normalized as described for NORMALIZED PATH. A forward slash will be appended if the path points to a directory.<br />
<br />
'''NOTE:''' In principle, the path returned by REAL PATH should be just as unambiguous as the result of CANONICAL PATH. However, there are a few caveats:<br />
* On case-insensitive file systems, two independently obtained results of REAL PATH might differ in case spelling even if referring to the same file system object. This should not be the case for CANONICAL PATH.<br />
* Determining the result of CANONICAL PATH is a fast operation. In contrast, REAL PATH may be expensive to determine, as for each directory on the path a listing needs to be obtained, and a canonical path needs to be formed, and compared, for half of the listed directory entries on average.<br />
* On Win32, quite some amount of complexity arises from backward compatibility layers, forbidden file names, multiple filesystem roots, etc. Internally calling <tt>GetShortPathName()</tt>, CANONICAL PATH does not need to handle that complexity, and may be considered more reliable for identifying file system objects than REAL PATH.<br />
<br />
=====READ FILE <filename>=====<br />
Returns the text content of the file indicated by <filename>.<br />
<br />
=====WRITE FILE <filename> <line>, OVERWRITE FILE <filename> <line>, APPEND TO FILE <filename> <line>=====<br />
These commands write the specified <line> of text to the file indicated by <filename>. They behave like the <tt>echo</tt> command of a typical shell, in the sense that a line-ending will be automatically added to the <line> if it does not already end with one. To suppress the automatic line-ending, you can say WRITE FILE <filename> <content> WITHOUT LINE ENDING (or equivalently, for short, you can say WITHOUT LF or WITHOUT CRLF). Any previous content in <file> will be lost if you use WRITE or OVERWRITE (they are the same, just synonyms for each other) whereas APPEND preserves previous content and adds the new <line> to the end.<br />
<br />
====Commands operating on executables====<br />
=====START EXECUTABLE <command line>=====<br />
Behaves identically to CREATE PROCESS, except that it does not report a process id for the new process. For details, see CREATE PROCESS.<br />
<br />
=====CATEGORIZE EXECUTABLE <name or path>=====<br />
BCI2000 keeps a list of executables/modules that have been built, and sorts them into categories. The CATEGORIZE EXECUTABLE command provides a way to retrieve that information. Given the name or path of an executable, it outputs one of the following categories:<br />
* SignalSource,<br />
* SignalProcessing,<br />
* Application,<br />
* Operator,<br />
* Tool,<br />
* Helper,<br />
* Unknown.<br />
<br />
====Commands operating on Lines of input/output====<br />
=====WRITE LINE <line>=====<br />
Writes a line of output. Destination depends on the context in which a script is executed. If the context is an Operator Handler, output is written as a log entry. If the context is a telnet session, output is written to the telnet connection. If the context is a [[User Reference:BCI2000Shell|BCI2000Shell]], output is written to the shell's stdout.<br />
<br />
=====READ LINE=====<br />
Reads a line of input from the current execution context's input. If the command is executed within an Operator Handler, it will fail. If executed within a telnet session, the other side of the connection is prompted for input. If executed from within a [[User Reference:BCI2000Shell|BCI2000Shell]], input is read from the shell's stdin.<br />
<br />
====Commands operating on Processes in the Operating System====<br />
=====CREATE PROCESS <command line>=====<br />
Starts the specified executable with options. This command returns after the started program has finished initialization, i.e. it will detect load time failures such as missing DLLs on Windows. If the process is still running when CREATE PROCESS returns, its result will be an operating system process id (pid). If the process has terminated, CREATE PROCESS will report its exit code marked with an <tt>ExitCode</tt> tag to allow distinction between a pid and an exit code.<br />
Please note that CREATE PROCESS requires quoting of arguments differently from other scripting commands. For details, see the SYSTEM command.<br />
<br />
=====TERMINATE PROCESS <pid>=====<br />
Tries to terminate the process with the given operating system pid, waiting for the process to terminate before returning. Will return <tt>false</tt> to indicate that a suitable process existed but could not be terminated.<br />
<br />
=====WAIT FOR PROCESS <pid> [<timeout seconds> = infinite]=====<br />
Waits for the process with the given operating system pid to terminate, or the timeout to expire. Returns <tt>false</tt> to indicate that the process is still executing.<br />
<br />
=====SHOW PROCESS <pid>=====<br />
Makes all windows visible which are associated with the process referred to by pid.<br />
In addition, brings one of the process' top level (desktop level) windows to the front for user interaction.<br />
<br />
=====HIDE PROCESS <pid>=====<br />
Makes all windows invisible which are associated with the process referred to by pid.<br />
<br />
====Global commands====<br />
=====HELP [<type>]=====<br />
When called with a type argument, lists commands that exist for the specified type (e.g., SYSTEM, or FILE). When called without argument, lists all commands in their main form. HELP ALL will list all commands, including synonyms.<br />
<br />
=====SET <name> <value>, GET <name>, <name>=====<br />
Allows to set or retrieve the value of local and environment variables. The name is matched against local and environment variables. When no variable with the given name is found, SET will create a local variable, while GET will result in an error. GET may be further abbreviated to only consist of a name.<br />
<br />
GET further allows evaluation of [[User_Reference:Expression_Syntax|mathematical expressions]]. When the expression is invalid, or contains an unknown variable, an error is triggered.<br />
<br />
=====GET SYSTEM STATE=====<br />
Prints the current system state. This will be one of Unavailable, Idle, Startup, Initialization, Resting, Suspended, ParamsModified, Running, Termination, Busy (for details, see the WAIT FOR command below).<br />
<br />
=====GET CURRENT RUN FILE=====<br />
Prints the full path to the current run file, or an empty string, if called outside Running state.<br />
<br />
=====WAIT FOR <system state> [<timeout seconds>]=====<br />
Waits until the system is in the specified state. This may be one of Idle, Startup, Connected, Resting, Suspended, ParamsModified, Running, Busy, or a combination of these, separated with a pipe character: "Resting|Suspended". When no timeout is given, this command waits indefinitely. If the wait is successful, i.e. system state matches one of the specified states, WAIT FOR will return a value of "true". If timeout occurred, WAIT FOR will return "false".<br />
<br />
If the BCI2000 system is shut down while a script is executing a WAIT FOR command, the script will be terminated with a "wait aborted" error message.<br />
<br />
In more detail, user visible states are:<br />
* Idle: System is shut down and does not do other processing than executing scripts.<br />
* Startup: System has started up and is listening for incoming connections.<br />
* Connected: All core modules have connected to the system.<br />
* Resting: The system has been initialized but is not running.<br />
* Suspended: The system has ended running and is behaving like in Resting.<br />
* ParamsModified: In Suspended mode, parameter changes have been published and will be applied at Resume.<br />
* Running: The system is running, processing brain signals, and displaying stimuli.<br />
* Busy: The system is performing a transition from one state to another.<br />
<br />
As a synonym for "Connected," "Initialization" is valid as well since it is compatible with the nomenclature in StateMachine.h. Still, it should be avoided because it is easily confused with, but very distinct from, the actions performed in the Initialize() phase.<br />
<br />
=====SLEEP &lt;time in seconds&gt;=====<br />
Waits (sleeps) for the given amount of time. Timing resolution is 50ms. Tends to sleep a little longer than specified, with the error growing with duration.<br />
<br />
=====GET SYSTEM VERSION=====<br />
Prints BCI2000 version information.<br />
=====SETCONFIG, SET CONFIG=====<br />
Applies current parameters to the system. Corresponds to the ''SetConfig'' button in the GUI version of the Operator module.<br />
<br />
=====START=====<br />
Starts or resumes system operation, corresponding to the ''Start/Resume'' button in the GUI version of the Operator module.<br />
=====STOP=====<br />
Stops system operation. Corresponds to the ''Stop'' button in the GUI version of the Operator.<br />
=====STARTUP SYSTEM=====<br />
When in idle state, starts up the system to wait for incoming connections from core modules. Additionally, the following arguments may be given: 1) an IP address on which to listen (default is to listen on all addresses), and 2) a list of generic core module names with ports. The default configuration corresponds to these arguments:<br />
STARTUP SYSTEM * SignalSource:4000 SignalProcessing:4001 Application:4002<br />
<br />
A system log file may optionally be specified on this line, by inserting the <code>--SystemLogFile</code> flag between the IP address and the module specifiers. For example:<br />
<br />
STARTUP SYSTEM * --SystemLogFile=SOME_FILE.TXT SignalSource:4000 SignalProcessing:4001 Application:4002<br />
<br />
The system log file will record all operator log window messages for the current launch, until the system shuts down. It may be helpful to use the variables <code>$YYYYMMDD</code> and <code>$HHMMSS</code> to specify the filename. Note that file name and path cannot contain spaces.<br />
<br />
=====SHUTDOWN SYSTEM=====<br />
Shuts down core modules, and enters idle system state.<br />
=====RESET SYSTEM=====<br />
Shuts down the system, and clears all parameter, state, and event information.<br />
<br />
=====QUIT, EXIT [<result>]=====<br />
Quits the operator module after terminating all BCI2000 modules. The optional ''result'' argument determines the result of the executed script.<br />
<br />
=====CLOSE CONNECTION, TERMINATE CONNECTION=====<br />
In the context of a telnet or websocket connection, this command will terminate the connection.<br />
In other contexts, such as event handlers, it will be ignored.<br />
<br />
=====SYSTEM <command line>=====<br />
Executes a shell command, redirecting any console output into the command's script result. E.g., to obtain a directory listing, under Windows, you would enter<br />
SYSTEM DIR<br />
'''NOTE:''' Arguments to the SYSTEM command are executed by the operating system's shell, and thus may require quoting different from the other scripting commands. E.g., writing<br />
SET mydir ${PARENT DIRECTORY $BCI2000LAUNCHDIR}; ECHO ${LIST FILES $mydir}<br />
will list files in the BCI2000 main directory, independently of whether the path to that directory contains space characters or not. However, to obtain a directory listing through the SYSTEM command, you would need to write<br />
ECHO ${SYSTEM DIR "$mydir"}<br />
to make sure the content of the variable ''mydir'' is interpreted as a single argument, independently of whether it contains space characters.<br />
<br />
=====LOG <message>=====<br />
Append the specified message to the system log.<br />
=====WARN <message>=====<br />
Append the specified message to the system log, formatted as a warning.<br />
=====ERROR <message>=====<br />
Append the specified message to the system log, formatted as an error message.<br />
<br />
=====CAPTURE MESSAGES <message types>=====<br />
Captures system log messages into a background buffer. When no message type is given, all messages are captured. When "None" is given as a message type, message capturing is disabled. Otherwise, the message type must be one of "Errors", "Warnings", "Debug", "Log". Multiple message types may be specified in a single command. When "None" appears within a single command, all preceding message types are ignored. Multiple CAPTURE MESSAGES commands are cumulative, except when "None" is specified as a message type.<br />
<br />
=====FLUSH MESSAGES=====<br />
Clears the background message buffer, and returns its previous content. Use CAPTURE MESSAGES to capture messages into the background message buffer.<br />
<br />
====Operator-module defined Commands====<br />
=====HIDE WINDOW [<name>], SHOW WINDOW [<name>]=====<br />
Hides or shows the specified window. When called without a window name, the Operator module's main window is hidden or shown. The window name may be one of Main, Configuration, Log, Watches, and Visualizations. When "Watches" is given, the window state refers to visibility of the Watches area in the Visualizations window.<br />
<br />
=====MOVE WINDOW <name> <x> <y>, RESIZE WINDOW <name> <width> <height>=====<br />
Moves resp. resizes the specified window with one of the above names.<br />
Window decorations (title bar, frame) are taken into consideration such that the total size of the window matches the given width and height.<br />
<br />
=====ARRANGE WINDOW <name> <rows> <cols> <row> <col> [<rowspan> <colspan>]=====<br />
Arranges the named window in a virtual ''rows'' x ''cols'' grid at grid position ''row, col''.<br />
<br />
Optional ''rowspan'' and ''colspan'' arguments may be given to specify the extension of the window across more than one row or column. <br />
Using a ''rowspan'' of 0 will result in the window assuming its minimum height.<br />
Likewise, a ''colspan'' of 0 will result in the window's minimum width.<br />
<br />
If multiple screens are present, windows are arranged on the screen that contains the Operator window.<br />
<br />
=====SET TITLE <title>=====<br />
Sets the title of the main Operator window.<br />
=====SET BUTTON <idx> <label> <commands>=====<br />
Configures the function button with 1-based index ''idx'' such that it is labelled ''label'' and executes ''commands''.<br />
<br />
=====VISUALIZE WATCH [decimate <n>] [range <min> <max>] <expression1> ...=====<br />
Adds a watch for the given expressions to the operator module's Watches window, and makes the Watches window visible if it is hidden. If the ''decimate'' clause is present, the command will create a watch which will be evaluated only for every ''n''th sample in the state vector. If the ''range'' clause is present, display minimum and maximum will not be adjusted automatically but will be fixed to the values given.<br />
<br />
By default, ''decimate'' has a value of "auto"; this means that there is no decimation of evaluation (i.e., all samples are evaluated) but changes that occur within 1ms will be shortened into their maximum and minimum, and thus reported as only two values.<br />
This has proven to be efficient for avoiding sluggishness from flooding the application with events.<br />
<br />
=====MOVE VISUALIZATON <visID> <x> <y>, RESIZE VISUALIZATION <visID> <width> <height>=====<br />
Moves resp. resizes the specified visualization window.<br />
Window decorations (title bar, frame) are taken into consideration such that the total size of the window matches the given width and height. If unknown, visualization IDs may be obtained from the Operator's ''Window->Visualizations'' menu.<br />
<br />
=====ARRANGE VISUALIZATION <visID> <rows> <cols> <row> <col> [<rowspan> <colspan>]=====<br />
Arranges the named visualization window in a virtual ''rows'' x ''cols'' grid at grid position ''row, col''.<br />
<br />
Optional ''rowspan'' and ''colspan'' arguments may be given to specify the extension of the window across more than one row or column. <br />
Using a ''rowspan'' of 0 will result in the window assuming its minimum height.<br />
Likewise, a ''colspan'' of 0 will result in the window's minimum width.<br />
<br />
If multiple screens are present, windows are arranged on the screen that contains the Operator window.<br />
<br />
=====RECORD VISUALIZATION <visID> [on|off]=====<br />
Registers the named visualization for recording. The visualization name must be the short name as displayed in the ''View->Visualizations'' menu. Switching a visualization recording to "on" is only possible in idle state (because an event for recording frame numbers must be registered in the system). When a visualization is registered for recording, its frames are stored immediately as they arrive at the operator module. Currently, only bitmap visualizations may be recorded.<br />
<br />
Example: Recording the application window<br />
RECORD VISUALIZATION ApplicationWindow on<br />
...<br />
# after parameters have been loaded<br />
Set parameter VisualizeApplicationWindow 1<br />
...<br />
<br />
=====PUT NOTE <note>=====<br />
Adds the given text to the [[User_Reference:Operator_Notes#Taking_Notes_during_recording_in_Operator|notes window]].<br />
If the system is in ''Running'' state, the text will also be added to the current notes file as described under<br />
[[User_Reference:Operator_Notes#Note_storage_and_file_format|"notes file"]].<br />
<br />
=====START TELNET <address>, STOP TELNET <address>=====<br />
Starts or stops a telnet server listening at the given address. The address is in <IP>:<port> format.<br />
<br />
'''IMPORTANT:''' You should not use this command on global internet addresses, as there is no authentication performed. Only use addresses in the local network, such as 10.x.x.x, 172.x.x.x, or 192.168.x.x.<br />
<br />
=====START WEBSOCKET <address>, STOP WEBSOCKET <address>=====<br />
Starts or stops a websocket server listening at the given address. The address is in <IP>:<port> format.<br />
<br />
'''IMPORTANT:''' You should not use this command on global internet addresses, as there is no authentication performed. Only use addresses in the local network, such as 10.x.x.x, 172.x.x.x, or 192.168.x.x.<br />
<br />
====Operator-module Commands for Soliciting Input from the User====<br />
<br />
<br />
<br />
=====CHOOSE [INPUT] FILE[S] [OF TYPE <.ext1> [<.ext2> ...]] [STARTING AT <dir>] [WITH PROMPT <message>]=====<br />
Via the Qt graphical user interface, prompt the user to select an existing file (or multiple files, if the keyword FILES is used). Print the resulting file path(s).<br />
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)<br />
<br />
=====CHOOSE [OUTPUT] FILE [OF TYPE <.ext1> [<.ext2> ...]] [STARTING AT <dir>] [WITH PROMPT <message>]=====<br />
Via the Qt graphical user interface, prompt the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists). Print the resulting file path.<br />
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)<br />
<br />
=====CHOOSE DIRECTORY [STARTING AT <dir>] [WITH PROMPT <message>]=====<br />
Via the Qt graphical user interface, prompt the user to specify a directory. Print the resulting directory path.<br />
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)<br />
<br />
=====CUSTOM DIALOG [MESSAGE <msg>] [VAR <varname> <label> {[<options>]} ] [BUTTONS {<buttons>}] ... =====<br />
Via the Qt graphical user interface, prompt the user with a modal dialog that can be flexibly customized.<br />
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)<br />
<br />
===Predefined Variables===<br />
The following variables exist when an Operator script is executed.<br />
Some of these variables are marked with ''local''. This means that they are not environment variables, i.e. they are invisible to child processes that are launched using the SYSTEM or START EXECUTABLE commands, and their values may be different between script invocations. In script code, they are accessed like ordinary variables.<br />
====BCI2000LAUNCHDIR====<br />
The full absolute path to the directory where the Operator module resides. This is also prepended to the PATH environment variable, such that executables from the current BCI2000 installation will have precedence over any other executable with the same name.<br />
<br />
On macOS, this is the path where the Operator module's application bundle resides. In the default configuration, this is the BCI2000 prog directory, both on macOS and on other platforms.<br />
<br />
====BCI2000BINARY====<br />
The full absolute path to the Operator module.<br />
====LogLevel (local)====<br />
Determines the amount of log information written to the Operator log. This variable only affects log messages originating from the current script. May be 2 (display all log messages), 1 (display fewer log messages), or 0 (suppress all log messages). Set to 1 by default. Changes to this local variable are not propagated to any sub-scripts called. ''NOTE:'' Only log messages are controlled by this variable. Error messages originating from a script with 'LogLevel 0' will still be displayed in the Operator log. When 'AbortOnError' is set to 0, you may set 'LogLevel' to -1 in order to display error messages. When 'AbortOnError' is 1 (the default), error messages will always be displayed to indicate the reason for failure.<br />
<br />
====AbortOnError (local)====<br />
Determines if a script is aborted when an error happens, or whether the error is silently ignored. Set to 1 by default (script is aborted on error). Changes to this local variable are not propagated to any sub-scripts called.<br />
<br />
====Result (local)====<br />
The result of the last executed scripting command. When a script is executed by calling EXECUTE SCRIPT, the script's last executed command determines the result of the EXECUTE SCRIPT command itself.<br />
<br />
====0, 1, ... 9 (local)====<br />
When a script file is being executed, these variables contain the arguments of the EXECUTE SCRIPT command.<br />
''$0'' resolves to the full absolute path to the current script file. Within scripts, all of the ''0-9'' variables are defined, and those that do not have a matching argument are empty.<br />
<br />
====YYYYMMDD (local)====<br />
Local time at execution of the current script, in YYYYMMDD format. In interactive sessions, reflects the time when the session was initiated.<br />
<br />
====HHMMSS (local)====<br />
Local time at execution of the current script, in HHMMSS format. In interactive sessions, reflects the time when the session was initiated.<br />
<br />
===Abbreviated commands and synonyms===<br />
To minimize the need of consulting documentation, as well as for backward compatibility, a number of '''synonymous commands''' are provided. E.g., states may be added by INSERT STATE as well as ADD STATE, and the existence of a file may be queried by IS FILE as well as EXISTS FILE. For an overview over all allowed forms of commands, use the HELP ALL command.<br />
<br />
To simplify operation in interactive sessions, '''abbreviated commands''' exist. Currently, these are:<br />
:'''cd''' for CHANGE DIRECTORY,<br />
:'''pwd''' and '''cd''' without argument for CURRENT DIRECTORY,<br />
:'''ls''' and '''dir''' for LIST DIRECTORY,<br />
:'''mkdir''' for MAKE DIRECTORY,<br />
:'''echo''' for WRITE LINE,<br />
:'''realpath''' for REAL PATH,<br />
:'''dirname''' for EXTRACT DIRECTORY,<br />
:'''basename''' for EXTRACT FILE BASE.<br />
<br />
===Handlers===<br />
In the Operator GUI, script execution is bound to a number of Operator Events (not to be confused with Event states, above) that occur during various [[Technical Reference:States of Operation|stages of BCI2000 system operation]]:<br />
====OnConnect====<br />
This handler runs at startup, as soon as all modules are connected to the operator module.<br />
====OnSetConfig====<br />
This handler runs each time a set of parameters is applied to the system. This happens when the user clicks the ''SetConfig'' button. Execution of the ''SETCONFIG'' command also runs this handler.<br />
<br />
====OnStart, OnResume====<br />
These handlers are triggered by the ''Start''/''Resume'' button. One of these handlers is also triggered when the ''Running'' state variable is set to 1 from a script. Whether ''OnStart'' or ''OnResume'' is triggered depends on whether the system has been running before with the current set of parameters.<br />
<br />
====OnStartRun====<br />
Similarly to OnStart and OnResume, this handler is triggered by the ''Start''/''Resume'' button. Unlike other event handlers, OnStartRun has an argument, which is the current run file.<br />
<br />
OnStart or OnResume are triggered immediately after ''Start''/''Resume'' has been pressed, whereas OnStartRun is deferred until modules have confirmed to be in Running state. This makes sure that the OnStartRun event handler receives a valid run file name.<br />
<br />
====OnNextFilePart====<br />
This handler is triggered during a run, whenever the ''FilePart'' event state is incremented. It allows scripts to know when a new<br />
partial file has begun. For further information, see the [[User_Reference:BCI2000FileWriter#FileSplittingCondition|FileSplittingCondition]] parameter.<br />
<br />
====OnSuspend/OnStopRun====<br />
Triggered when the system goes from running into suspended mode. This happens whenever the ''Running'' state variable changes from 1 to 0. This may happen when the user clicks ''Suspend'', when the application module switches the system into suspended mode, or when a script sets the ''Running'' state variable to 0.<br />
<br />
====OnShutdown====<br />
Triggered when the operator module shuts down connections, and switches into idle state.<br />
<br />
====OnExit====<br />
Triggered when the operator module exits. Execution of the QUIT command also triggers this handler. This handler is not available to the SET SCRIPT and CLEAR SCRIPT commands. Also, when both an OnShutdown and an OnExit script are defined, the OnExit script may be executed before the OnShutdown script.<br />
<br />
====Associating Scripts with Operator Events====<br />
In the operator module's preferences dialog, script commands may be entered for each of the handlers listed above.<br />
Scripts may be specified as paths to script files, or as immediate one-line scripts.<br />
Entries that start with a minus sign (-) are treated as one-line scripts, which may contain multiple commands separated with semicolons.<br />
<br />
Scripts may also be specified from the command line used to start up the operator module. There, handler names are followed with the content of the respective preference entry, enclosed in double quotes ("...").<br />
<br />
Finally, scripts may be specified using the SET SCRIPT command of the scripting language itself.<br />
<br />
===Examples===<br />
====Making use of the Operator module's Function Buttons====<br />
To add a state variable called "Artifact", and to set it using the operator's function buttons, do this:<br />
*Enter the following line under "After All Modules Connected" in the operator's preferences dialog (note the minus sign):<br />
-ADD STATE Artifact 1 0<br />
*Under "Function Buttons", enter "Set Artifact" as the name of button 1, and as its command, enter (note there is no minus sign):<br />
SET STATE Artifact 1<br />
*Enter "Clear Artifact" as the name of button 2, and as its command, enter<br />
SET STATE Artifact 0<br />
<br />
====A fully automated BCI2000 session====<br />
<pre><br />
Echo Please enter a subject ID:<br />
Set SubjectID ${Read line}<br />
<br />
Startup system<br />
Start executable SignalGenerator<br />
Start executable SpectralSignalProcessing<br />
Start executable CursorTask<br />
Wait for Connected<br />
Load parameterfile "../parms/examples/CursorTask_SignalGenerator.prm"<br />
For i in 1 2 3<br />
Load parameterfile "../parms/MyExperiment/Session$i.prm"<br />
Set parameter SubjectName $SubjectID<br />
Set parameter SubjectSession $i<br />
Set config<br />
Wait for Resting<br />
Start<br />
Wait for Suspended 1000<br />
End<br />
</pre><br />
<br />
====Automating BCI2000 by Operator command line arguments====<br />
The following example shows how to specify script commands from the command line.<br />
It fully automates BCI2000 operation by loading a parameter file, applying parameters, starting the system once the parameters are applied, and quitting the system once the run is over. For better readability, the example is broken across lines, using the ^ DOS line continuation character.<br />
<br />
operator.exe --OnConnect "-LOAD PARAMETERFILE ../parms/examples/CursorTask_SignalGenerator.prm; SETCONFIG" ^<br />
--OnSetConfig "-SET STATE Running 1" ^<br />
--OnSuspend "-QUIT"<br />
<br />
====Automatically arranging windows in a 4x2 grid====<br />
The following example arranges Source and Roundtrip visualizations on the left side of the screen.<br />
On the right side, a large area is dedicated to the Operator's log window, and the Operator's main window sits at the bottom right.<br />
<br />
Arrange Visualization SRCD 4 2 1 1 2 1<br />
Arrange Visualization RNDT 4 2 3 1<br />
Arrange Window Main 4 2 4 2<br />
Arrange Window Log 4 2 1 2 3 1<br />
<br />
[[File:Operator_Arrangement.PNG|center|640px|border]]<br />
<br />
==See also==<br />
[[User Reference:Module Command Line Options]], [[User Reference:Operator Module]], [[User Reference:BCI2000Shell]], [[Technical Reference:States of Operation]]<br />
<br />
[[Category:User Interface]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Operator_Module_Scripting&diff=12100User Reference:Operator Module Scripting2025-10-01T21:06:24Z<p>Jhill: /* Commands operating on Files, Directories, and Paths */</p>
<hr />
<div>Operator scripts automate actions that the otherwise would be performed by the user, e.g. starting or suspending system operation.<br />
Scripts may be contained in script files, or given immediately in the operator module's preferences dialog.<br />
There is also an option to specify scripts from the [[User Reference:Module Command Line Options#Operator Module|command line]] when starting the operator module. When using the [[User_Reference:BCI2000Shell|BCI2000Shell]], or the [[Technical_Reference:Operator_Library|Operator Library]] from your own application, you may execute scripts at any time.<br />
<br />
In addition, the operator scripting language may be used to control an operator module over a [[User_Reference:Module_Command_Line_Options#--Telnet|Telnet]] or [[User_Reference:Module_Command_Line_Options#--WebSocket|WebSocket]] connection.<br />
===Syntax===<br />
'''Command separation.''' Scripts consist of sequences of the commands listed below. A command must be terminated with either a newline, or a semicolon (;).<br />
This allows to put multiple commands into one line, separated by semicolon characters.<br />
Commands are case-insensitive, variables and values may be case-sensitive, depending on context.<br />
<br />
'''Comments.''' Lines starting with a '#' character are ignored. Such lines may be used to hold comments. In addition, when any of the first two lines of a script contains "#!" (the Unix shell invocation sequence), it will be ignored. In conjunction with [[User Reference:BCI2000Shell|BCI2000Shell]], this may be used to write Operator scripts that may be treated as executables.<br />
<br />
'''Escaping.''' In order to resolve ambiguity about command arguments that contain white space, they must be included in double quotes, or the white space must be encoded in URL-fashion, e.g. ''%20'' instead of a space character. Similarly, when an argument contains a semicolon (;), it must be included in double quotes, or the semicolon must be encoded in URL-fashion, i.e. as ''%3B''. Also, "$" characters indicate command substitution, so they should be encoded as ''%24'' if substitution is not desired.<br />
<br />
'''Variable Substitution.''' When a command contains a dollar sign, alphanumeric characters following the dollar sign will be interpreted as the name of a variable: $NAME. The name will be matched against Expression variable names first, followed with Local variable names, and finally Environment variable names. When a match is found, $NAME will be replaced with the content of the matching variable. When no match is found, $NAME will be resolved to an empty string, without triggering an error.<br />
<br />
'''Command Substitution.''' When part of a command is enclosed with ${...}, this subexpression will be substituted with the result of its execution as a command. E.g.,<br />
LOG "Current system state is: ${GET SYSTEM STATE}"<br />
LOG "The path environment variable is: ${PATH}"<br />
Note that the last example uses the short form of the GET command, which will return the value of a PATH parameter or a PATH state if such exists. To make sure that only environment variables are matched, use the long form of the GET command:<br />
LOG MESSAGE "The path environment variable is: ${GET VARIABLE PATH}"<br />
Substitutions may be nested, i.e. the following will work as expected:<br />
SET MyVar "LIST STATES"; LOG "States are: ${$MyVar}"<br />
SET MyVar "LIST STATES"; LOG "States are: ${${GET VARIABLE MyVar}}"<br />
<br />
'''Mathematical Expressions.''' A command may consist of a single [[User Reference:Expression Syntax|mathematical expression]]. This expression is then evaluated, and its result is returned as the command's result. As a special case, this allows the use of expression variables in ${...} substitutions. Consider for example<br />
x:=0; WHILE x<10; LOG ${x:=x+1}; END<br />
There, the first command creates and initializes the expression variable x. In the WHILE condition, an expression is allowed as well as any command. In the LOG command, an expression appears in ${...}, which executes the expression in braces, and substitutes the result of the expression as an argument into the LOG command, which adds an entry to the Operator log. This results in a sequence of 10 log entries, containing the numbers from 1 to 10.<br />
<br />
===Commands===<br />
====Control commands====<br />
These commands allow conditional execution of parts of a script. When a condition is expected, any other scripting command may be given. Its result will be considered to represent a boolean value of "true" if it is empty, a nonzero number, or the string "true". It will be taken to represent a boolean value of "false" if it contains a numeric value of zero, or any string that does not evaluate to a nonzero number. Note that identification of an empty value with "true" differs from string handling in the EVALUATE CONDITION command. This is because most scripting commands return nothing on success, but an error message on failure.<br />
<br />
The output of the SYSTEM and START EXECUTABLE commands is handled specially. There, the result code of the created child process is translated into a boolean value in the ordinary manner, treating a result code of zero as "true", and any other result code as "false". This allows to use external commands in the same way as in a native shell.<br />
<br />
=====IF <condition>; <if commands>; [ ELSEIF <condition>; <elseif commands>;] ... [ ELSE; <else commands>;] END=====<br />
Executes ''if commands'' if ''condition'' evaluates to "true". Otherwise, the ''elseif commands'' of the first matching ''elseif condition'' are executed. When none of the ''elseif conditions'' evaluates to "true", ''else commands'' are executed. ELSEIF and ELSE blocks may be omitted.<br />
<br />
=====WHILE <condition>; <loop commands>; END=====<br />
Executes ''loop commands'' while ''condition'' evaluates to ''true''.<br />
=====DO; <loop commands>; UNTIL <condition>=====<br />
Executes ''loop commands'' until "condition" evaluates to ''true''.<br />
=====FOR <name> IN <item1> <item2> ... ; <loop commands>; END=====<br />
Creates a local variable with the specified name. Then, sequentially assigns each ''item'' to that variable, and executes ''loop commands''. If an ''item'' contains newline characters, it is split up into multiple items, corresponding to the lines contained in the ''item''. E.g.,<br />
FOR i IN top ${LIST FILES} bottom; LOG ${i}; END<br />
will first write a log entry "top". Then, it will create a log entry for each file in the current directory, and finally, it will create a log entry "bottom".<br />
=====RETURN [<value>]=====<br />
Finishes execution of the current script, and optionally returns a value to the caller.<br />
<br />
====Commands operating on Conditions====<br />
=====EVALUATE CONDITION <left> [<op> [<right>]]=====<br />
Evaluates a comparison between the ''left'' and ''right'' operands. As a comparison operator, the following may be specified: ==, !=, ~=, <, >, <=, >=. There, the != operator behaves identically to the ~= operator. When a test for equality is performed, the two operands are treated as strings, and compared in a case-insensitive manner. When any of the inequality tests is performed, the two operands are converted into floating-point numbers before comparison.<br />
<br />
The ''right'' operand may be omitted, in which case it is treated as if an empty string were specified. Also, the ''op'' operator may be omitted, in which case the following rules apply regarding the remaining operand: If it is an empty string, or equal to the string "false" in case-insensitive comparison, the result is "false". If entirely consists of the text representation of a floating-point number, the result is "false" if the number is 0, and "true" if the number is not 0.<br />
<br />
Inspired by the unix sh shells' <tt>test</tt> command, there exists a short form of the EVALUATE CONDITION command, where the arguments of EVALUATE CONDITION may appear within square brackets. This allows constructs such as<br />
IF [ ${MyVar} == MyValue ]; LOG Is equal; ELSE; LOG Is different; END<br />
Note that the arguments to EVALUATE CONDITION must always be separated by white space, no matter whether its long or short form is used.<br />
<br />
Conditions may be combined logically using the operators && and ||. These go ''outside'' the square brackets. Note also that whitespace around the comparison operators is critical, otherwise the conditional will be treated as a single string (which will always evaluate to "true")<br />
<br />
IF [ ${foo} == foo ] || [ ${bar} == bar ]; LOG got a match; END<br />
<br />
====Commands operating on Local Variables====<br />
Besides environment variables, there exist local variables in scripts. Local variables are inherited by sub-scripts executed with the EXECUTE SCRIPT command, but changes to the variable's values will not be propagated to the calling script.<br />
=====SET VARIABLE <name> <value>=====<br />
Sets the named variable to the specified value.<br />
=====CLEAR VARIABLE <name>=====<br />
Removes the named variable from memory.<br />
=====GET VARIABLE <name>=====<br />
Returns the variable's current value. When the variable does not exist, an empty value is returned rather than an error message.<br />
<br />
====Commands operating on Environment Variables====<br />
These scripting commands allow to read and modify environment variables. Changes to environment variables will be visible to child processes started with SYSTEM or START EXECUTABLE. Variable values are stored as strings. Variable names may not contain the equals sign.<br />
=====SET ENVIRONMENT <name> <value>=====<br />
Sets the named variable to the specified value.<br />
=====CLEAR ENVIRONMENT <name>=====<br />
Removes the named variable from memory.<br />
=====GET ENVIRONMENT <name>=====<br />
Returns the variable's current value. When the variable does not exist, an empty value is returned rather than an error message.<br />
<br />
====Commands operating on Scripts====<br />
=====SET SCRIPT <handler names> <scripting commands>=====<br />
Associates a sequence of scripting commands with the named handler. Handlers are specified by names as given [[#Handlers|below]]. Multiple handlers may be specified by concatenating their names with a pipe character, e.g. "OnStart|OnResume".<br />
<br />
Scripting commands must be included in double quotes, unless they consist of a single word.<br />
When specifying a sequence of scripting commands, they must be separated with a semicolon character: "SetConfig; Start". In order to use double quotes or semicolons within the commands themselves, encode these as you would in a URL, i.e. replace a double quote character with ''%22'', and a semicolon with ''%3B'': "Load Parameters %22my file%22".<br />
<br />
To use a script file rather than a literal script, use the EXECUTE SCRIPT command:<br />
SET SCRIPT OnConnect "EXECUTE SCRIPT myscript.txt"<br />
<br />
=====GET SCRIPT <handler name>=====<br />
Returns the script associated with the specified handler.<br />
<br />
=====CLEAR SCRIPT <handler names>=====<br />
Clears scripts for the given handlers. Equivalent to calling SET SCRIPT with an empty script.<br />
<br />
=====EXECUTE SCRIPT <file or handler name> [<Arg1> <Arg2> ... <Arg9>]=====<br />
Executes a script contained in a file, and optionally sets the script's local variables ''1'' to ''9'' to the specified values. To execute script commands already associated with a handler, provide a handler name rather than a file. When the script is executed successfully, the result of the last executed script command becomes the result of the EXECUTE SCRIPT command itself. Use "SET Result <value>" as the last command in a script in order to return a certain value.<br />
<br />
When you run a script through EXECUTE SCRIPT, it will inherit copies of variables from its calling script/command line. Variable changes will be local to the script, and will be lost when script execution is complete.<br />
<br />
The ''AbortOnError'' variable determines whether a script is aborted when any of its commands result in an error message. ''AbortOnError'' is not inherited but defaults to 1 in any script.<br />
<br />
====Commands operating on Parameters====<br />
=====LOAD PARAMETERFILE <file>, LOAD PARAMETERS <file>=====<br />
Loads a parameter file specified by its path and name. Relative paths are interpreted relative to the operator module's working directory at startup. Usually, this matches the executable's location in the <tt>prog</tt> directory.<br />
As the parameter file name must not contain white space, please use HTML-type encoding for white space characters, such as <tt>Documents%20and%20Settings</tt> when referring to a user's "Documents and Settings" folder.<br />
<br />
NOTE: Only those parameters will be loaded that do exist at the time when this command is called. In idle state, no parameters exist other than created by ADD PARAMETER. After modules are connected and have published their parameters to the Operator module, a full set of parameters exist.<br />
<br />
=====ADD PARAMETER <parameter definition>=====<br />
Adds a parameter to the system. The parameter is specified as a [[Technical_Reference:Parameter_Definition#Parameter_Lines|parameter line]]. This command may not be used after system initialization has completed, i.e. its use is restricted to the "Idle" and "Publishing" [[Technical_Reference:States_of_Operation#Publishing_Phase|phases of system operation]]. In terms of handlers, its use is restricted to the ''OnConnect'' handler.<br />
=====EXISTS PARAMETER <name>=====<br />
Returns "true" when the specified parameter exists in the system, and "false" otherwise.<br />
<br />
=====ISEMPTY PARAMETER <name>=====<br />
Returns "true" when the specified parameter exists and has no values, "false" if it exists and has values.<br />
<br />
=====SET PARAMETER <name>[( idx1, idx2 )] <value>=====<br />
Sets the named parameter to the specified value. Values that contain special characters, or whitespace must use the [[Technical_Reference:Parameter_Definition#Special_Characters|parameter value encoding]]. Use parentheses to specify indices or labels. Omitted indices default to 1.<br />
<br />
=====SET PARAMETER <parameter line>=====<br />
Replace a parameter's value and definition with the information given in the [[Technical_Reference:Parameter_Definition#Parameter_Lines|parameter line]]. The parameter must exist in the system when this command is executed.<br />
<br />
=====GET PARAMETER <name>[( idx1, idx2 )]=====<br />
Prints the value of the named parameter. Use parentheses to specify indices or labels.<br />
<br />
=====SET PARAMETERROWS <parameter name> <rows>=====<br />
Sets the number of rows in the named parameter.<br />
<br />
=====GET PARAMETERROWS <parameter name>=====<br />
Prints the number of rows in the named parameter.<br />
<br />
=====SET PARAMETERCOLS <parameter name>=====<br />
Sets the number of columns in the named parameter.<br />
<br />
=====GET PARAMETERCOLS <parameter name>=====<br />
Prints the number of columns in the named parameter.<br />
<br />
=====LIST PARAMETER <wildcard expression>, LIST PARAMETERS=====<br />
Prints all parameters with names matching the wildcard expression, in form of parameter lines.<br />
=====CLEAR PARAMETERS=====<br />
Clears the list of parameters in the system. May only be executed in ''Idle'' and ''Publishing'' system states.<br />
<br />
====Commands operating on States====<br />
In BCI2000, there are three types of States that differ in their alignment to brain signal data (see [[Technical_Reference:State_Definition#Kinds_of_States|Kinds of States]]). This section applies to both Stream States, and normal States.<br />
For Event States, see the next section.<br />
<br />
=====ADD STATE <name> <bit width> <initial value>=====<br />
Adds a state variable to the system. State variables are defined by name, bit width, and initial value (see [[Technical Reference:State Definition]]). This command may not be used after system initialization has completed, i.e. its use is restricted to the "Idle" and "Publishing" [[Technical_Reference:States_of_Operation#Publishing_Phase|phases of system operation]]. In terms of handlers, its use is restricted to the ''OnConnect'' handler.<br />
=====EXISTS STATE <name>=====<br />
Returns "true" when the specified state exists in the system, and "false" otherwise.<br />
<br />
=====SET STATE <name> <value>, SET STATES <name1> <value1> <name2> <value2> ...=====<br />
Sets the named state variable to the specified integer value by sending a state message to the source module.<br />
Setting the ''Running'' state to 1 will start system operation, setting it to 0 will suspend the system.<br />
<br />
<tt>SET STATES</tt> will atomically set the values of multiple states.<br />
<br />
=====GET STATE[(<sample>)] <name>=====<br />
Gets the value of the named state. Note that state values are not updated from the application module when the ''OperatorBackLink'' parameter is 0. In that case, GET STATE will return the state's initial value.<br />
<br />
An optional one-based sample index may be given to indicate that the state value should be retrieved at the given sample position. Sample positions range from 1 to the number of samples per block present in the state vector. The number of samples per block may be retrieved using GET STATEVECTOR SAMPLES.<br />
<br />
By default, the state's value is retrieved for sample index 1.<br />
<br />
=====LIST STATE <wildcard expression>, LIST STATES=====<br />
Lists all states, or states with names matching the given wildcard expression, in form of state lines.<br />
=====CLEAR STATES=====<br />
Clears the list of states in the system. May only be executed in ''Idle'' and ''Publishing'' system states.<br />
<br />
=====FREEZE STATES, THAW STATES=====<br />
Freezes/thaws the values of all states in the state vector, without interfering with system operation. "Freezing" creates, and "thawing" discards, a frozen snapshot of the state vector. For the duration of its existence, GET STATE calls will be diverted to the snapshot. This is useful for ensuring that multiple GET STATE commands actually retrieve mutually-consistent values from different state variables (i.e. values from the same sample-block).<br />
<br />
=====GET STATEVECTOR SAMPLES=====<br />
Returns the number of samples in the state vector per block of data. In the system's "Running" state, this matches the number of samples per block in the source data. Prior to the "Running" state, this is 1 because the state vector has not yet been updated from the application module.<br />
<br />
====Commands operating on Events====<br />
Events are a special type of state, which are recorded asynchronously, at single-sample resolution. Events may only be added while the system is in "idle" state. This kind of events is not related to [[#Handlers|Operator Events]] as defined below.<br />
=====ADD EVENT <name> <bit width> <initial value>=====<br />
Adds an event to the system. Like state variables, events are defined by name, bit width, and initial value (see [[Technical Reference:State Definition]]). This command may not be used after the system has started up, so it is typically executed within a telnet session before ''STARTUP'' has been called.<br />
=====EXISTS EVENT <name>=====<br />
Returns "true" when the specified event exists in the system, and "false" otherwise.<br />
<br />
=====SET EVENT <name> <value>=====<br />
Asynchronously sets an event to the given value. Recording events requires the EventLink logger component to be present in the source module.<br />
<br />
'''NOTE:''' In versions prior to BCI2000 3.06, this command behaved as described for PULSE EVENT below, rather than as advertised. If you used SET EVENT in your scripts, it is recommended to replace it with PULSE EVENT in order to retain original behavior.<br />
<br />
=====PULSE EVENT <name> <value>=====<br />
Asynchronously sets an event to the given value for a single sample duration. Recording events requires the EventLink logger component to be present in the source module.<br />
<br />
=====SET EVENTS [<name> <value>] [<name2> <value2>] ... =====<br />
Asynchronously sets given events to their specified values. Using this command, rather than multiple SET EVENT commands in a row, ensures that all event changes are recorded at exactly the same point in time. Recording events requires the EventLink logger component to be present in the source module.<br />
<br />
=====PULSE EVENTS [<name> <value>] [<name2> <value2>] ... =====<br />
Asynchronously sets given events to their specified values for a single sample duration. Using this command, rather than multiple PULSE EVENT commands in a row, ensures that all event changes are recorded at exactly the same point in time. Recording events requires the EventLink logger component to be present in the source module.<br />
<br />
=====GET EVENT[(<sample>)] <name>=====<br />
Gets the value of the named event. Note that evemt values are not updated from the application module when the ''OperatorBackLink'' parameter is 0.<br />
<br />
An optional one-based sample index may be given to indicate that the event's value should be retrieved at the given sample position. Sample positions range from 1 to the number of samples per block present in the state vector. The number of samples per block may be retrieved using GET STATEVECTOR SAMPLES.<br />
<br />
By default, the event's value is retrieved for sample index 1.<br />
<br />
=====LIST EVENT <wildcard expression>, LIST EVENTS=====<br />
Lists all events, or events with names matching the given wildcard expression, in form of state lines.<br />
=====CLEAR EVENTS=====<br />
Clears the list of events in the system. May only be executed in ''Idle'' state.<br />
<br />
====Commands operating on VisProperties====<br />
=====SET VISPROPERTY <visID>.<name> <value>=====<br />
Sets the named [[Technical Reference:Visualization Properties|visualization property]] for the specified visualization ID to the given value. If the visualization ID contains a dot character, it must be encoded in [[Technical_Reference:Parameter_Definition#Special_Characters|parameter value encoding]]. E.g., setting the window width for the visualization ID "2.D1" would be written <code>SET VISPROPERTY 2%2ED1.Width 200</code>.<br />
<br />
=====RESET VISPROPERTY <visID>.<name>=====<br />
Removes the named visualization property fro the specified visualization ID from the property store, effectively resetting its value to its default.<br />
<br />
=====GET VISPROPERTY <visID>.<name>=====<br />
Prints the value of the named [[Technical Reference:Visualization Properties|visualization property]] for the specified visualization ID.<br />
<br />
=====SET VISPROPERTIES <property set ID>=====<br />
Applies a set of visualization property values as given in the [[#VisPropertySets|VisPropertySets]] parameter. In that matrix-valued parameter, row labels specify visualization properties such as "SRCD.Left", and columns represent sets of property values. Column labels are IDs of the corresponding property sets.<br />
<br />
====Commands operating on the Control Signal====<br />
=====GET SIGNAL( <channel index>, <element index> )=====<br />
Prints the value of the control signal at the given indices. Indices are 1-based.<br />
=====GET SIGNAL CHANNELS=====<br />
Prints the number of channels in the control signal.<br />
=====GET SIGNAL ELEMENTS=====<br />
Prints the number of elements (samples) in the control signal.<br />
=====FREEZE SIGNAL, THAW SIGNAL=====<br />
Freezes/thaws the contents of the control signal, without interfering with system operation. "Freezing" creates, and "thawing" discards, a frozen snapshot of the control signal. For the duration of its existence, GET SIGNAL calls will be diverted to the snapshot. This is useful for ensuring that multiple GET SIGNAL commands actually retrieve mutually-consistent values from different elements in the control signal (i.e. values from the same sample-block).<br />
<br />
====Commands operating on Expressions====<br />
=====EVALUATE EXPRESSION <expression>=====<br />
This command treats the remainder of the command as a literal mathematical expression (for a description, see [[User Reference:Expression Syntax]]. An expression may contain variable assignments; such variables may then be used in later expressions. Note that expression variables are different from local and environment variables that may be accessed by GET/SET VARIABLE/ENVIRONMENT. Expression variables hold numerical values, while local and environment variables hold string values. Also, environment variables are accessible to child processes started with SYSTEM or START EXECUTABLE, while expression variables are accessible only to scripts. When a script is executed using the EXECUTE SCRIPT command, it will inherit a copy of all expression variables present. Changes to these variables from the executed script will not be visible in the parent script.<br />
<br />
=====CLEAR EXPRESSION VARIABLE <name>=====<br />
Clears the named expression variable from storage.<br />
<br />
====Commands operating on Watches====<br />
A "Watch" is an object that consists of a set of expressions, and an action. Whenever the value of any of the expressions changes, the watch is "triggered", and the action is executed. Watches allow client applications to respond to BCI2000 state changes in a reliable manner. Rather than polling information from BCI2000, a client may create a watch to be notified about changes of interest. This avoids the problem of missing short-lived changes, which is inherent in the polling approach.<br />
<br />
For watches created through operator scripting, the action consists of dumping values of all the expressions to a UDP port.<br />
<br />
The intended use of a watch from a client application is to create a separate thread that reads from the watch's UDP port in a blocking mode, and calls an appropriate handler function whenever it receives data.<br />
The data sent will consist of a single UDP packet with a single line in ASCII format, terminated with a CRLF sequence. The line consists of tab-separated data fields, which contain the current values of the expressions specified when creating the watch. In addition, the first field contains a time stamp in the same time base as the <tt>SourceTime</tt> state, wrapping around every 65536 ms. This time stamp represents the point in time where the expression value changed, with an accuracy of a single sample.<br />
<br />
=====ADD WATCH [decimate <n>] <expression1> <expression2> ... [AT <ip:port>]=====<br />
Adds a watch for the listed expressions. Each expression's value will be reported in a separate field. When an address is specified in <tt>ip:port</tt> format, the watch tries to open that port for output, and creation fails if that port is taken. Otherwise, a free port is chosen automatically. In both cases, successful creation of the watch is indicated by returning the output address in ASCII format. The address is also used to uniquely identify a watch in the context of a connection.<br />
<br />
When a ''decimate <n>'' clause is present, the watch will be created with decimation, i.e. it will only be evaluated for every ''n''th<br />
sample of the state vector.<br />
<br />
If a watch is created through a remote connection, it will use the remote host's external IP address for automatically chosen addresses. Otherwise, the output port will be associated with the machine's <tt>localhost</tt> address.<br />
<br />
Watches may be created even if the system is currently running. In this case, the watch is triggered immediately, and sends its current expression values to its output port.<br />
<br />
=====ADD WATCH SYSTEM STATE [AT <address>]=====<br />
Similar to the first variant of ADD WATCH, but will watch the system's state as reported by GET SYSTEM STATE.<br />
<br />
=====CLEAR WATCH <address>, CLEAR WATCHES [<wildcard-expression>]=====<br />
Removes the watches specified by address, or those with their addresses matching a wildcard expression. If CLEAR WATCHES is called without argument, all watches will be deleted.<br />
<br />
=====TRIGGER WATCH <address>, TRIGGER WATCHES [<wildcard-expression>]=====<br />
Forces dumping of the watches' current expression values to their output ports. Mostly useful for testing purposes.<br />
<br />
=====LIST WATCHES [<wildcard-expression>]=====<br />
Displays a list of existing watches, and their addresses.<br />
<br />
=====COUNT WATCHES [<wildcard-expression>]=====<br />
Returns the number of existing watches, or the number of watches whose addresses match the optional wildcard expression.<br />
<br />
====Commands operating on Files, Directories, and Paths====<br />
=====EXTRACT DIRECTORY <path>, EXTRACT FILE <path>, EXTRACT FILE BASE <path>=====<br />
Extracts the directory or file portion of a given path. When the path specifies a non-existing directory, the directory name must be followed with a separator ("/") in order to be recognized as a directory. The EXTRACT DIRECTORY command always returns its result with a trailing separator. The EXTRACT FILE BASE command returns the file portion without extension.<br />
<br />
=====IS DIRECTORY <path>, IS FILE <path>, IS PATH <path>=====<br />
Determines whether the specified path points to an existing directory, file, or any of the two. The result is returned as one of the strings "true" or "false".<br />
=====PARENT DIRECTORY <path>=====<br />
Returns the parent directory of the specified path, independently of whether the path points to a directory, or to a file.<br />
=====CURRENT DIRECTORY=====<br />
Returns the current working directory.<br />
=====CHANGE DIRECTORY <path>=====<br />
Changes the working directory.<br />
=====MAKE DIRECTORY <path>=====<br />
Creates a new directory with the given path. The directory's parent must exist for the command to succeed.<br />
=====LIST DIRECTORY [<path> or <wildcard expression>]=====<br />
Returns a listing of the specified directory, or the current working directory if no path is specified. The listing is in long form. You may use wildcard expressions in order to restrict the output.<br />
=====LIST FILE <wildcard expression>=====<br />
Returns a list of file names matching ''wildcard expression'' in the current directory.<br />
=====LIST FILES [<directory> [<wildcard expression>]]=====<br />
Returns a list of file names from the specified directory, matching ''wildcard expression''. When ''wildcard expression'' is missing, all files are listed. When ''directory'' is missing, files in the current directory are listed.<br />
=====LIST DIRECTORIES [<directory> [<wildcard expression>]]=====<br />
Returns a list of directory names from the specified directory, matching ''wildcard expression''. When ''wildcard expression'' is missing, all directories are listed. When ''directory'' is missing, directories in the current directory are listed.<br />
<br />
=====RENAME FILE <current path> <new path>, RENAME DIRECTORY <current path> <new name>=====<br />
Renames a file resp. a directory. For files, a different path may be given in the second argument, resulting in that the file is moved to the location specified by the new path. For directories, the path up to the directory's name must stay the same.<br />
=====REMOVE FILE <path>, REMOVE DIRECTORY <path>=====<br />
Removes the specified file or directory. This command cannot be undone. The directory must be empty for the command to succeed.<br />
=====FORCEREMOVE DIRECTORY <path>=====<br />
Removes the specified directory and its contents. Symbolic links are treated as ordinary files, i.e. they are not followed. This command cannot be undone.<br />
=====NORMALIZED PATH <path>=====<br />
Returns <path>, with the following transformations applied:<br />
*Removes relative elements (<tt>..</tt> <tt>.</tt>) as far as possible. For absolute paths, the result will not contain any relative elements; for relative paths, double-dots may appear at the beginning of the result if necessary.<br />
If a relative path simplifies to the empty string, <tt>./</tt> is returned. Thus, the result of NORMALIZED PATH is never empty, unless its input was empty.<br />
*Replaces backward slashes with forward slashes to achieve uniformity across platforms.<br />
*On case-insensitive file systems, replaces the spelling of names with the one stored in the file system.<br />
*On Win32, replaces short (8.3) names with long ones.<br />
<br />
=====CANONICAL PATH <path>=====<br />
If <path> points to an existing file or directory, CANONICAL PATH returns a valid absolute file path, suitable as an unambiguous representation for the object pointed to. Especially, two non-empty canonical path strings will compare equal if and only if they refer to the same file system object.<br />
<br />
If <path> does not point to an existing file system object, construction of a canonical path is not possible due to lack of information about the named object, and CANONICAL PATH will return an empty string.<br />
<br />
'''NOTES:''' The need for an unambiguous, or canonical, representation arises due to ambiguities in the string representation of paths, and in file systems themselves.<br />
*Paths may contain relative elements: <tt>/mydir/../myfile</tt> points to the same object as <tt>/myfile</tt>.<br />
*A path that involves symbolic links will point to the same object as a path containing one or more of those links in resolved form.<br />
*File systems may be case-insensitive, or may even provide multiple distinct names for individual directory entries (Win32 short vs. long names).<br />
<br />
On '''Win32,''' CANONICAL PATH returns the short (8.3) representation of a path, using uppercase spelling, and backslashes as directory separators. Apart from efficiency considerations, this aesthetically unpleasing representation has been chosen to discourage its use for anything except comparing file system objects.<br />
<br />
On '''other systems,''' CANONICAL PATH will return the result of the POSIX <tt>realpath()</tt> function.<br />
<br />
In both cases, a CANONICAL PATH will end with a native directory separator if, and only if, the object pointed to is a directory.<br />
<br />
=====REAL PATH <path>=====<br />
On this command provides a work-alike for the POSIX <tt>realpath()</tt> function.<br />
If <path> is empty, or if <path> points to a non-existing object, the result will be empty. Otherwise, an absolute path will be returned, with symbolic links resolved, using forward slashes as directory separators, and with spelling normalized as described for NORMALIZED PATH. A forward slash will be appended if the path points to a directory.<br />
<br />
'''NOTE:''' In principle, the path returned by REAL PATH should be just as unambiguous as the result of CANONICAL PATH. However, there are a few caveats:<br />
* On case-insensitive file systems, two independently obtained results of REAL PATH might differ in case spelling even if referring to the same file system object. This should not be the case for CANONICAL PATH.<br />
* Determining the result of CANONICAL PATH is a fast operation. In contrast, REAL PATH may be expensive to determine, as for each directory on the path a listing needs to be obtained, and a canonical path needs to be formed, and compared, for half of the listed directory entries on average.<br />
* On Win32, quite some amount of complexity arises from backward compatibility layers, forbidden file names, multiple filesystem roots, etc. Internally calling <tt>GetShortPathName()</tt>, CANONICAL PATH does not need to handle that complexity, and may be considered more reliable for identifying file system objects than REAL PATH.<br />
<br />
=====READ FILE <filename>=====<br />
Returns the text content of the file indicated by <filename>.<br />
<br />
=====WRITE FILE <filename> <line>, OVERWRITE FILE <filename> <line>, APPEND TO FILE <filename> <line>=====<br />
These commands write the specified <line> of text to the file indicated by <filename>. They behave like the <tt>echo</tt> command of a typical shell, in the sense that a line-ending will be automatically added to the <line> if it does not already end with one. To suppress the automatic line-ending, you can say WRITE FILE <filename> <content> WITHOUT LINE ENDING (or equivalently, for short, you can say WITHOUT LF or WITHOUT CRLF). Any previous content in <file> will be lost if you use WRITE or OVERWRITE (they are the same, just synonyms for each other) whereas APPEND preserves previous content and adds the new <line> to the end.<br />
<br />
====Commands operating on executables====<br />
=====START EXECUTABLE <command line>=====<br />
Behaves identically to CREATE PROCESS, except that it does not report a process id for the new process. For details, see CREATE PROCESS.<br />
<br />
=====CATEGORIZE EXECUTABLE <name or path>=====<br />
BCI2000 keeps a list of executables/modules that have been built, and sorts them into categories. The CATEGORIZE EXECUTABLE command provides a way to retrieve that information. Given the name or path of an executable, it outputs one of the following categories:<br />
* SignalSource,<br />
* SignalProcessing,<br />
* Application,<br />
* Operator,<br />
* Tool,<br />
* Helper,<br />
* Unknown.<br />
<br />
====Commands operating on Lines of input/output====<br />
=====WRITE LINE <line>=====<br />
Writes a line of output. Destination depends on the context in which a script is executed. If the context is an Operator Handler, output is written as a log entry. If the context is a telnet session, output is written to the telnet connection. If the context is a [[User Reference:BCI2000Shell|BCI2000Shell]], output is written to the shell's stdout.<br />
<br />
=====READ LINE=====<br />
Reads a line of input from the current execution context's input. If the command is executed within an Operator Handler, it will fail. If executed within a telnet session, the other side of the connection is prompted for input. If executed from within a [[User Reference:BCI2000Shell|BCI2000Shell]], input is read from the shell's stdin.<br />
<br />
====Commands operating on Processes in the Operating System====<br />
=====CREATE PROCESS <command line>=====<br />
Starts the specified executable with options. This command returns after the started program has finished initialization, i.e. it will detect load time failures such as missing DLLs on Windows. If the process is still running when CREATE PROCESS returns, its result will be an operating system process id (pid). If the process has terminated, CREATE PROCESS will report its exit code marked with an <tt>ExitCode</tt> tag to allow distinction between a pid and an exit code.<br />
Please note that CREATE PROCESS requires quoting of arguments differently from other scripting commands. For details, see the SYSTEM command.<br />
<br />
=====TERMINATE PROCESS <pid>=====<br />
Tries to terminate the process with the given operating system pid, waiting for the process to terminate before returning. Will return <tt>false</tt> to indicate that a suitable process existed but could not be terminated.<br />
<br />
=====WAIT FOR PROCESS <pid> [<timeout seconds> = infinite]=====<br />
Waits for the process with the given operating system pid to terminate, or the timeout to expire. Returns <tt>false</tt> to indicate that the process is still executing.<br />
<br />
=====SHOW PROCESS <pid>=====<br />
Makes all windows visible which are associated with the process referred to by pid.<br />
In addition, brings one of the process' top level (desktop level) windows to the front for user interaction.<br />
<br />
=====HIDE PROCESS <pid>=====<br />
Makes all windows invisible which are associated with the process referred to by pid.<br />
<br />
====Global commands====<br />
=====HELP [<type>]=====<br />
When called with a type argument, lists commands that exist for the specified type (e.g., SYSTEM, or FILE). When called without argument, lists all commands in their main form. HELP ALL will list all commands, including synonyms.<br />
<br />
=====SET <name> <value>, GET <name>, <name>=====<br />
Allows to set or retrieve the value of local and environment variables. The name is matched against local and environment variables. When no variable with the given name is found, SET will create a local variable, while GET will result in an error. GET may be further abbreviated to only consist of a name.<br />
<br />
GET further allows evaluation of [[User_Reference:Expression_Syntax|mathematical expressions]]. When the expression is invalid, or contains an unknown variable, an error is triggered.<br />
<br />
=====GET SYSTEM STATE=====<br />
Prints the current system state. This will be one of Unavailable, Idle, Startup, Initialization, Resting, Suspended, ParamsModified, Running, Termination, Busy.<br />
<br />
=====GET CURRENT RUN FILE=====<br />
Prints the full path to the current run file, or an empty string, if called outside Running state.<br />
<br />
=====WAIT FOR <system state> [<timeout seconds>]=====<br />
Waits until the system is in the specified state. This may be one of Idle, Startup, Connected, Resting, Suspended, ParamsModified, Running, Busy, or a combination of these, separated with a pipe character: "Resting|Suspended". When no timeout is given, this command waits indefinitely. If the wait is successful, i.e. system state matches one of the specified states, WAIT FOR will return a value of "true". If timeout occurred, WAIT FOR will return "false".<br />
<br />
If the BCI2000 system is shut down while a script is executing a WAIT FOR command, the script will be terminated with a "wait aborted" error message.<br />
<br />
In more detail, user visible states are:<br />
* Idle: System is shut down and does not do other processing than executing scripts.<br />
* Startup: System has started up and is listening for incoming connections.<br />
* Connected: All core modules have connected to the system.<br />
* Resting: The system has been initialized but is not running.<br />
* Suspended: The system has ended running and is behaving like in Resting.<br />
* ParamsModified: In Suspended mode, parameter changes have been published and will be applied at Resume.<br />
* Running: The system is running, processing brain signals, and displaying stimuli.<br />
* Busy: The system is performing a transition from one state to another.<br />
<br />
As a synonym for "Connected," "Initialization" is valid as well since it is compatible with the nomenclature in StateMachine.h. Still, it should be avoided because it is easily confused with, but very distinct from, the actions performed in the Initialize() phase.<br />
<br />
=====SLEEP &lt;time in seconds&gt;=====<br />
Waits (sleeps) for the given amount of time. Timing resolution is 50ms. Tends to sleep a little longer than specified, with the error growing with duration.<br />
<br />
=====GET SYSTEM VERSION=====<br />
Prints BCI2000 version information.<br />
=====SETCONFIG, SET CONFIG=====<br />
Applies current parameters to the system. Corresponds to the ''SetConfig'' button in the GUI version of the Operator module.<br />
<br />
=====START=====<br />
Starts or resumes system operation, corresponding to the ''Start/Resume'' button in the GUI version of the Operator module.<br />
=====STOP=====<br />
Stops system operation. Corresponds to the ''Stop'' button in the GUI version of the Operator.<br />
=====STARTUP SYSTEM=====<br />
When in idle state, starts up the system to wait for incoming connections from core modules. Additionally, the following arguments may be given: 1) an IP address on which to listen (default is to listen on all addresses), and 2) a list of generic core module names with ports. The default configuration corresponds to these arguments:<br />
STARTUP SYSTEM * SignalSource:4000 SignalProcessing:4001 Application:4002<br />
<br />
A system log file may optionally be specified on this line, by inserting the <code>--SystemLogFile</code> flag between the IP address and the module specifiers. For example:<br />
<br />
STARTUP SYSTEM * --SystemLogFile=SOME_FILE.TXT SignalSource:4000 SignalProcessing:4001 Application:4002<br />
<br />
The system log file will record all operator log window messages for the current launch, until the system shuts down. It may be helpful to use the variables <code>$YYYYMMDD</code> and <code>$HHMMSS</code> to specify the filename. Note that file name and path cannot contain spaces.<br />
<br />
=====SHUTDOWN SYSTEM=====<br />
Shuts down core modules, and enters idle system state.<br />
=====RESET SYSTEM=====<br />
Shuts down the system, and clears all parameter, state, and event information.<br />
<br />
=====QUIT, EXIT [<result>]=====<br />
Quits the operator module after terminating all BCI2000 modules. The optional ''result'' argument determines the result of the executed script.<br />
<br />
=====CLOSE CONNECTION, TERMINATE CONNECTION=====<br />
In the context of a telnet or websocket connection, this command will terminate the connection.<br />
In other contexts, such as event handlers, it will be ignored.<br />
<br />
=====SYSTEM <command line>=====<br />
Executes a shell command, redirecting any console output into the command's script result. E.g., to obtain a directory listing, under Windows, you would enter<br />
SYSTEM DIR<br />
'''NOTE:''' Arguments to the SYSTEM command are executed by the operating system's shell, and thus may require quoting different from the other scripting commands. E.g., writing<br />
SET mydir ${PARENT DIRECTORY $BCI2000LAUNCHDIR}; ECHO ${LIST FILES $mydir}<br />
will list files in the BCI2000 main directory, independently of whether the path to that directory contains space characters or not. However, to obtain a directory listing through the SYSTEM command, you would need to write<br />
ECHO ${SYSTEM DIR "$mydir"}<br />
to make sure the content of the variable ''mydir'' is interpreted as a single argument, independently of whether it contains space characters.<br />
<br />
=====LOG <message>=====<br />
Append the specified message to the system log.<br />
=====WARN <message>=====<br />
Append the specified message to the system log, formatted as a warning.<br />
=====ERROR <message>=====<br />
Append the specified message to the system log, formatted as an error message.<br />
<br />
=====CAPTURE MESSAGES <message types>=====<br />
Captures system log messages into a background buffer. When no message type is given, all messages are captured. When "None" is given as a message type, message capturing is disabled. Otherwise, the message type must be one of "Errors", "Warnings", "Debug", "Log". Multiple message types may be specified in a single command. When "None" appears within a single command, all preceding message types are ignored. Multiple CAPTURE MESSAGES commands are cumulative, except when "None" is specified as a message type.<br />
<br />
=====FLUSH MESSAGES=====<br />
Clears the background message buffer, and returns its previous content. Use CAPTURE MESSAGES to capture messages into the background message buffer.<br />
<br />
====Operator-module defined Commands====<br />
=====HIDE WINDOW [<name>], SHOW WINDOW [<name>]=====<br />
Hides or shows the specified window. When called without a window name, the Operator module's main window is hidden or shown. The window name may be one of Main, Configuration, Log, Watches, and Visualizations. When "Watches" is given, the window state refers to visibility of the Watches area in the Visualizations window.<br />
<br />
=====MOVE WINDOW <name> <x> <y>, RESIZE WINDOW <name> <width> <height>=====<br />
Moves resp. resizes the specified window with one of the above names.<br />
Window decorations (title bar, frame) are taken into consideration such that the total size of the window matches the given width and height.<br />
<br />
=====ARRANGE WINDOW <name> <rows> <cols> <row> <col> [<rowspan> <colspan>]=====<br />
Arranges the named window in a virtual ''rows'' x ''cols'' grid at grid position ''row, col''.<br />
<br />
Optional ''rowspan'' and ''colspan'' arguments may be given to specify the extension of the window across more than one row or column. <br />
Using a ''rowspan'' of 0 will result in the window assuming its minimum height.<br />
Likewise, a ''colspan'' of 0 will result in the window's minimum width.<br />
<br />
If multiple screens are present, windows are arranged on the screen that contains the Operator window.<br />
<br />
=====SET TITLE <title>=====<br />
Sets the title of the main Operator window.<br />
=====SET BUTTON <idx> <label> <commands>=====<br />
Configures the function button with 1-based index ''idx'' such that it is labelled ''label'' and executes ''commands''.<br />
<br />
=====VISUALIZE WATCH [decimate <n>] [range <min> <max>] <expression1> ...=====<br />
Adds a watch for the given expressions to the operator module's Watches window, and makes the Watches window visible if it is hidden. If the ''decimate'' clause is present, the command will create a watch which will be evaluated only for every ''n''th sample in the state vector. If the ''range'' clause is present, display minimum and maximum will not be adjusted automatically but will be fixed to the values given.<br />
<br />
By default, ''decimate'' has a value of "auto"; this means that there is no decimation of evaluation (i.e., all samples are evaluated) but changes that occur within 1ms will be shortened into their maximum and minimum, and thus reported as only two values.<br />
This has proven to be efficient for avoiding sluggishness from flooding the application with events.<br />
<br />
=====MOVE VISUALIZATON <visID> <x> <y>, RESIZE VISUALIZATION <visID> <width> <height>=====<br />
Moves resp. resizes the specified visualization window.<br />
Window decorations (title bar, frame) are taken into consideration such that the total size of the window matches the given width and height. If unknown, visualization IDs may be obtained from the Operator's ''Window->Visualizations'' menu.<br />
<br />
=====ARRANGE VISUALIZATION <visID> <rows> <cols> <row> <col> [<rowspan> <colspan>]=====<br />
Arranges the named visualization window in a virtual ''rows'' x ''cols'' grid at grid position ''row, col''.<br />
<br />
Optional ''rowspan'' and ''colspan'' arguments may be given to specify the extension of the window across more than one row or column. <br />
Using a ''rowspan'' of 0 will result in the window assuming its minimum height.<br />
Likewise, a ''colspan'' of 0 will result in the window's minimum width.<br />
<br />
If multiple screens are present, windows are arranged on the screen that contains the Operator window.<br />
<br />
=====RECORD VISUALIZATION <visID> [on|off]=====<br />
Registers the named visualization for recording. The visualization name must be the short name as displayed in the ''View->Visualizations'' menu. Switching a visualization recording to "on" is only possible in idle state (because an event for recording frame numbers must be registered in the system). When a visualization is registered for recording, its frames are stored immediately as they arrive at the operator module. Currently, only bitmap visualizations may be recorded.<br />
<br />
Example: Recording the application window<br />
RECORD VISUALIZATION ApplicationWindow on<br />
...<br />
# after parameters have been loaded<br />
Set parameter VisualizeApplicationWindow 1<br />
...<br />
<br />
=====PUT NOTE <note>=====<br />
Adds the given text to the [[User_Reference:Operator_Notes#Taking_Notes_during_recording_in_Operator|notes window]].<br />
If the system is in ''Running'' state, the text will also be added to the current notes file as described under<br />
[[User_Reference:Operator_Notes#Note_storage_and_file_format|"notes file"]].<br />
<br />
=====START TELNET <address>, STOP TELNET <address>=====<br />
Starts or stops a telnet server listening at the given address. The address is in <IP>:<port> format.<br />
<br />
'''IMPORTANT:''' You should not use this command on global internet addresses, as there is no authentication performed.<br />
<br />
=====START WEBSOCKET <address>, STOP WEBSOCKET <address>=====<br />
Starts or stops a websocket server listening at the given address. The address is in <IP>:<port> format.<br />
<br />
'''IMPORTANT:''' You should not use this command on global internet addresses, as there is no authentication performed.<br />
<br />
====Operator-module Commands for Soliciting Input from the User====<br />
<br />
<br />
<br />
=====CHOOSE [INPUT] FILE[S] [OF TYPE <.ext1> [<.ext2> ...]] [STARTING AT <dir>] [WITH PROMPT <message>]=====<br />
Via the Qt graphical user interface, prompt the user to select an existing file (or multiple files, if the keyword FILES is used). Print the resulting file path(s).<br />
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)<br />
<br />
=====CHOOSE [OUTPUT] FILE [OF TYPE <.ext1> [<.ext2> ...]] [STARTING AT <dir>] [WITH PROMPT <message>]=====<br />
Via the Qt graphical user interface, prompt the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists). Print the resulting file path.<br />
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)<br />
<br />
=====CHOOSE DIRECTORY [STARTING AT <dir>] [WITH PROMPT <message>]=====<br />
Via the Qt graphical user interface, prompt the user to specify a directory. Print the resulting directory path.<br />
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)<br />
<br />
=====CUSTOM DIALOG [MESSAGE <msg>] [VAR <varname> <label> {[<options>]} ] [BUTTONS {<buttons>}] ... =====<br />
Via the Qt graphical user interface, prompt the user with a modal dialog that can be flexibly customized.<br />
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)<br />
<br />
===Predefined Variables===<br />
The following variables exist when an Operator script is executed.<br />
Some of these variables are marked with ''local''. This means that they are not environment variables, i.e. they are invisible to child processes that are launched using the SYSTEM or START EXECUTABLE commands, and their values may be different between script invocations. In script code, they are accessed like ordinary variables.<br />
====BCI2000LAUNCHDIR====<br />
The full absolute path to the directory where the Operator module resides. This is also prepended to the PATH environment variable, such that executables from the current BCI2000 installation will have precedence over any other executable with the same name.<br />
<br />
On macOS, this is the path where the Operator module's application bundle resides. In the default configuration, this is the BCI2000 prog directory, both on macOS and on other platforms.<br />
<br />
====BCI2000BINARY====<br />
The full absolute path to the Operator module.<br />
====LogLevel (local)====<br />
Determines the amount of log information written to the Operator log. This variable only affects log messages originating from the current script. May be 2 (display all log messages), 1 (display fewer log messages), or 0 (suppress all log messages). Set to 1 by default. Changes to this local variable are not propagated to any sub-scripts called. ''NOTE:'' Only log messages are controlled by this variable. Error messages originating from a script with 'LogLevel 0' will still be displayed in the Operator log. When 'AbortOnError' is set to 0, you may set 'LogLevel' to -1 in order to display error messages. When 'AbortOnError' is 1 (the default), error messages will always be displayed to indicate the reason for failure.<br />
<br />
====AbortOnError (local)====<br />
Determines if a script is aborted when an error happens, or whether the error is silently ignored. Set to 1 by default (script is aborted on error). Changes to this local variable are not propagated to any sub-scripts called.<br />
<br />
====Result (local)====<br />
The result of the last executed scripting command. When a script is executed by calling EXECUTE SCRIPT, the script's last executed command determines the result of the EXECUTE SCRIPT command itself.<br />
<br />
====0, 1, ... 9 (local)====<br />
When a script file is being executed, these variables contain the arguments of the EXECUTE SCRIPT command.<br />
''$0'' resolves to the full absolute path to the current script file. Within scripts, all of the ''0-9'' variables are defined, and those that do not have a matching argument are empty.<br />
<br />
====YYYYMMDD (local)====<br />
Local time at execution of the current script, in YYYYMMDD format. In interactive sessions, reflects the time when the session was initiated.<br />
<br />
====HHMMSS (local)====<br />
Local time at execution of the current script, in HHMMSS format. In interactive sessions, reflects the time when the session was initiated.<br />
<br />
===Abbreviated commands and synonyms===<br />
To minimize the need of consulting documentation, as well as for backward compatibility, a number of '''synonymous commands''' are provided. E.g., states may be added by INSERT STATE as well as ADD STATE, and the existence of a file may be queried by IS FILE as well as EXISTS FILE. For an overview over all allowed forms of commands, use the HELP ALL command.<br />
<br />
To simplify operation in interactive sessions, '''abbreviated commands''' exist. Currently, these are:<br />
:'''cd''' for CHANGE DIRECTORY,<br />
:'''pwd''' and '''cd''' without argument for CURRENT DIRECTORY,<br />
:'''ls''' and '''dir''' for LIST DIRECTORY,<br />
:'''mkdir''' for MAKE DIRECTORY,<br />
:'''echo''' for WRITE LINE,<br />
:'''realpath''' for REAL PATH,<br />
:'''dirname''' for EXTRACT DIRECTORY,<br />
:'''basename''' for EXTRACT FILE BASE.<br />
<br />
===Handlers===<br />
In the Operator GUI, script execution is bound to a number of Operator Events (not to be confused with Event states, above) that occur during various [[Technical Reference:States of Operation|stages of BCI2000 system operation]]:<br />
====OnConnect====<br />
This handler runs at startup, as soon as all modules are connected to the operator module.<br />
====OnSetConfig====<br />
This handler runs each time a set of parameters is applied to the system. This happens when the user clicks the ''SetConfig'' button. Execution of the ''SETCONFIG'' command also runs this handler.<br />
<br />
====OnStart, OnResume====<br />
These handlers are triggered by the ''Start''/''Resume'' button. One of these handlers is also triggered when the ''Running'' state variable is set to 1 from a script. Whether ''OnStart'' or ''OnResume'' is triggered depends on whether the system has been running before with the current set of parameters.<br />
<br />
====OnStartRun====<br />
Similarly to OnStart and OnResume, this handler is triggered by the ''Start''/''Resume'' button. Unlike other event handlers, OnStartRun has an argument, which is the current run file.<br />
<br />
OnStart or OnResume are triggered immediately after ''Start''/''Resume'' has been pressed, whereas OnStartRun is deferred until modules have confirmed to be in Running state. This makes sure that the OnStartRun event handler receives a valid run file name.<br />
<br />
====OnNextFilePart====<br />
This handler is triggered during a run, whenever the ''FilePart'' event state is incremented. It allows scripts to know when a new<br />
partial file has begun. For further information, see the [[User_Reference:BCI2000FileWriter#FileSplittingCondition|FileSplittingCondition]] parameter.<br />
<br />
====OnSuspend/OnStopRun====<br />
Triggered when the system goes from running into suspended mode. This happens whenever the ''Running'' state variable changes from 1 to 0. This may happen when the user clicks ''Suspend'', when the application module switches the system into suspended mode, or when a script sets the ''Running'' state variable to 0.<br />
<br />
====OnShutdown====<br />
Triggered when the operator module shuts down connections, and switches into idle state.<br />
<br />
====OnExit====<br />
Triggered when the operator module exits. Execution of the QUIT command also triggers this handler. This handler is not available to the SET SCRIPT and CLEAR SCRIPT commands. Also, when both an OnShutdown and an OnExit script are defined, the OnExit script may be executed before the OnShutdown script.<br />
<br />
====Associating Scripts with Operator Events====<br />
In the operator module's preferences dialog, script commands may be entered for each of the handlers listed above.<br />
Scripts may be specified as paths to script files, or as immediate one-line scripts.<br />
Entries that start with a minus sign (-) are treated as one-line scripts, which may contain multiple commands separated with semicolons.<br />
<br />
Scripts may also be specified from the command line used to start up the operator module. There, handler names are followed with the content of the respective preference entry, enclosed in double quotes ("...").<br />
<br />
Finally, scripts may be specified using the SET SCRIPT command of the scripting language itself.<br />
<br />
===Examples===<br />
====Making use of the Operator module's Function Buttons====<br />
To add a state variable called "Artifact", and to set it using the operator's function buttons, do this:<br />
*Enter the following line under "After All Modules Connected" in the operator's preferences dialog (note the minus sign):<br />
-ADD STATE Artifact 1 0<br />
*Under "Function Buttons", enter "Set Artifact" as the name of button 1, and as its command, enter (note there is no minus sign):<br />
SET STATE Artifact 1<br />
*Enter "Clear Artifact" as the name of button 2, and as its command, enter<br />
SET STATE Artifact 0<br />
<br />
====A fully automated BCI2000 session====<br />
<pre><br />
Echo Please enter a subject ID:<br />
Set SubjectID ${Read line}<br />
<br />
Startup system<br />
Start executable SignalGenerator<br />
Start executable SpectralSignalProcessing<br />
Start executable CursorTask<br />
Wait for Connected<br />
Load parameterfile "../parms/examples/CursorTask_SignalGenerator.prm"<br />
For i in 1 2 3<br />
Load parameterfile "../parms/MyExperiment/Session$i.prm"<br />
Set parameter SubjectName $SubjectID<br />
Set parameter SubjectSession $i<br />
Set config<br />
Wait for Resting<br />
Start<br />
Wait for Suspended 1000<br />
End<br />
</pre><br />
<br />
====Automating BCI2000 by Operator command line arguments====<br />
The following example shows how to specify script commands from the command line.<br />
It fully automates BCI2000 operation by loading a parameter file, applying parameters, starting the system once the parameters are applied, and quitting the system once the run is over. For better readability, the example is broken across lines, using the ^ DOS line continuation character.<br />
<br />
operator.exe --OnConnect "-LOAD PARAMETERFILE ../parms/examples/CursorTask_SignalGenerator.prm; SETCONFIG" ^<br />
--OnSetConfig "-SET STATE Running 1" ^<br />
--OnSuspend "-QUIT"<br />
<br />
====Automatically arranging windows in a 4x2 grid====<br />
The following example arranges Source and Roundtrip visualizations on the left side of the screen.<br />
On the right side, a large area is dedicated to the Operator's log window, and the Operator's main window sits at the bottom right.<br />
<br />
Arrange Visualization SRCD 4 2 1 1 2 1<br />
Arrange Visualization RNDT 4 2 3 1<br />
Arrange Window Main 4 2 4 2<br />
Arrange Window Log 4 2 1 2 3 1<br />
<br />
[[File:Operator_Arrangement.PNG|center|640px|border]]<br />
<br />
==See also==<br />
[[User Reference:Module Command Line Options]], [[User Reference:Operator Module]], [[User Reference:BCI2000Shell]], [[Technical Reference:States of Operation]]<br />
<br />
[[Category:User Interface]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12093User Reference:Custom GUI Commands2025-09-04T18:59:29Z<p>Jhill: /* CUSTOM DIALOG ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths one per line (<code>FOR ... IN ...</code> can iterate over these).<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to give the user the option of overriding the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button. If the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding. The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). For most purposes, you will probably not need to override the button configuration explicitly. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
# [optionally, you could pre-initialize environment variables subjectName, runType and stimulusCondition]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window # unless you have some other remote-control mechanism for suspending/resuming runs<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12092User Reference:Custom GUI Commands2025-09-02T14:39:25Z<p>Jhill: /* CHOOSE ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths one per line (<code>FOR ... IN ...</code> can iterate over these).<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to give the user the option of overriding the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
# [optionally, you could pre-initialize environment variables subjectName, runType and stimulusCondition]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window # unless you have some other remote-control mechanism for suspending/resuming runs<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12091User Reference:Custom GUI Commands2025-09-01T18:05:07Z<p>Jhill: /* Integrated CUSTOM DIALOG example */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths one per line (<code>FOR ... IN ...</code> can iterate over these).<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to allow the user to override the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
# [optionally, you could pre-initialize environment variables subjectName, runType and stimulusCondition]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window # unless you have some other remote-control mechanism for suspending/resuming runs<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12090User Reference:Custom GUI Commands2025-09-01T18:01:12Z<p>Jhill: /* CUSTOM DIALOG ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths one per line (<code>FOR ... IN ...</code> can iterate over these).<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to allow the user to override the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
# [optionally, you could pre-initialize environment variables subjectName, runType and stimulusCondition]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12089User Reference:Custom GUI Commands2025-09-01T17:48:17Z<p>Jhill: /* CHOOSE ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths one per line (<code>FOR ... IN ...</code> can iterate over these).<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to allow the user to override the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example (note the leading <code>|</code> character inside the braces): <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
# [optionally, you could pre-initialize environment variables subjectName, runType and stimulusCondition]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12088User Reference:Custom GUI Commands2025-08-29T16:34:07Z<p>Jhill: /* CUSTOM DIALOG ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to allow the user to override the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example (note the leading <code>|</code> character inside the braces): <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
# [optionally, you could pre-initialize environment variables subjectName, runType and stimulusCondition]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12087User Reference:Custom GUI Commands2025-08-29T16:05:37Z<p>Jhill: /* Integrated CUSTOM DIALOG example */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to allow the user to override the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1 # note the leading | character inside the braces</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
# [optionally, you could pre-initialize environment variables subjectName, runType and stimulusCondition]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12086User Reference:Custom GUI Commands2025-08-29T15:44:23Z<p>Jhill: /* CUSTOM DIALOG ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to allow the user to override the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1 # note the leading | character inside the braces</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum height of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
# [if you want, you can pre-initialize environment variables subjectName, runType and stimulusCondition]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12085User Reference:Custom GUI Commands2025-08-29T15:41:52Z<p>Jhill: /* CUSTOM DIALOG ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to allow the user to override the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1 # note the leading | character inside the braces</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
# [if you want, you can pre-initialize environment variables subjectName, runType and stimulusCondition]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12084User Reference:Custom GUI Commands2025-08-29T15:38:12Z<p>Jhill: /* CHOOSE ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to allow the user to override the limitation.<br />
<br />
; <code>[STARTING] AT <dir></code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
# [if you want, you can pre-initialize environment variables subjectName, runType and stimulusCondition]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12083User Reference:Custom GUI Commands2025-08-29T15:28:12Z<p>Jhill: </p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include <code>*</code> (or equivalently <code>*.*</code>) in the list if you want to allow the user to override the limitation.<br />
<br />
; <code>[STARTING] AT <dir> ...]</code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
# [if you want, you can pre-initialize environment variables subjectName, runType and stimulusCondition]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12082User Reference:Custom GUI Commands2025-08-29T15:20:00Z<p>Jhill: /* CHOOSE ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
If the user cancels the dialog, the commands print nothing.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star).<br />
<br />
; <code>[STARTING] AT <dir> ...]</code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
# [if you want, you can pre-initialize environment variables subjectName, runType and stimulusCondition]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12081User Reference:Custom GUI Commands2025-08-29T15:06:42Z<p>Jhill: /* Integrated CUSTOM DIALOG example */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star).<br />
<br />
; <code>[STARTING] AT <dir> ...]</code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load baseline parameters for this BCI]<br />
# [if you want, you can pre-initialize environment variables subjectName, runType and stimulusCondition]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12080User Reference:Custom GUI Commands2025-08-29T15:05:55Z<p>Jhill: /* Integrated CUSTOM DIALOG example */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star).<br />
<br />
; <code>[STARTING] AT <dir> ...]</code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load common parameters]<br />
# [if you want, you can pre-initialize environment variables subjectName, runType and stimulusCondition]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12079User Reference:Custom GUI Commands2025-08-29T15:04:55Z<p>Jhill: /* Integrated CUSTOM DIALOG example */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star).<br />
<br />
; <code>[STARTING] AT <dir> ...]</code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load common parameters]<br />
# [pre-initialize environment variables subjectName, runType and stimulusCondition if you want]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=File:CustomDialogExample.png&diff=12078File:CustomDialogExample.png2025-08-29T15:02:53Z<p>Jhill: Jhill uploaded a new version of File:CustomDialogExample.png</p>
<hr />
<div></div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12077User Reference:Custom GUI Commands2025-08-29T15:02:32Z<p>Jhill: /* Integrated CUSTOM DIALOG example */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star).<br />
<br />
; <code>[STARTING] AT <dir> ...]</code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<br />
The following partial listing illustrates one way <code>CUSTOM DIALOG</code> might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.<br />
<pre><br />
# [initialize system]<br />
# [start up modules]<br />
# [load common parameters]<br />
# [pre-initialize environment variables subjectName, runType and stimulusCondition if you want]<br />
<br />
<br />
set environment launcherAction ${<br />
custom dialog <br />
title "Auditory BCI Launcher" <br />
var subjectName "Subject ID:" {} default $subjectName minimum 1 <br />
var runType "Run Type:" {Calibration|Free Selection} default $runType <br />
var stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition <br />
message "NB: each condition should be calibrated separately." <br />
buttons {Quit|Launch} default Launch escape Quit<br />
}<br />
<br />
if [ $launcherAction == "" ]<br />
quit<br />
end<br />
<br />
if [ $runType == Calibration ]<br />
load parameterfile ../parms/calib.prm # let's assume you have created this<br />
else<br />
load parameterfile ../parms/free.prm # and this<br />
end<br />
load parameterfile ../parms/$stimulusCondition # and these<br />
set parameter SubjectName $subjectName<br />
setconfig<br />
show window<br />
set state Running 1<br />
</pre><br />
<br />
The resulting dialog looks like this:<br />
<br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12076User Reference:Custom GUI Commands2025-08-28T22:40:51Z<p>Jhill: /* Integrated example: */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star).<br />
<br />
; <code>[STARTING] AT <dir> ...]</code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated <code>CUSTOM DIALOG</code> example====<br />
<pre><br />
set environment launcherAction ${custom dialog title "Auditory BCI Launcher" var subjectName "Subject ID:" {} default $subjectName minimum 1 var runType "Run Type:" {Calibration|Free Selection} default $runType var condition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $condition message "NB: each condition should be calibrated separately." buttons {quit|Launch} default Launch escape quit}<br />
</pre><br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12075User Reference:Custom GUI Commands2025-08-28T22:38:51Z<p>Jhill: </p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star).<br />
<br />
; <code>[STARTING] AT <dir> ...]</code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
====Integrated example:====<br />
<pre><br />
set environment launcherAction ${custom dialog title "Auditory BCI Launcher" var subjectName "Subject ID:" {} default $subjectName minimum 1 var runType "Run Type:" {Calibration|Free Selection} default $runType var condition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $condition message "NB: each condition should be calibrated separately." buttons {quit|Launch} default Launch escape quit}<br />
</pre><br />
[[File:CustomDialogExample.png]]</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=File:CustomDialogExample.png&diff=12074File:CustomDialogExample.png2025-08-28T22:37:00Z<p>Jhill: </p>
<hr />
<div></div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12073User Reference:Custom GUI Commands2025-08-28T21:09:49Z<p>Jhill: </p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star).<br />
<br />
; <code>[STARTING] AT <dir> ...]</code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.<br />
<br />
<br />
Integrated example:<br />
<pre><br />
set environment launcherAction ${custom dialog title "Auditory BCI Launcher" var subjectName "Subject ID:" {} default $subjectName minimum 1 var runType "Run Type:" {Calibration|Free Selection} default $runType var condition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $condition message "NB: each condition should be calibrated separately." buttons {quit|Launch} default Launch escape quit}<br />
</pre></div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12072User Reference:Custom GUI Commands2025-08-28T20:54:34Z<p>Jhill: </p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file, and prints the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files, and prints the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists) and prints the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory, and prints the resulting directory path.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star).<br />
<br />
; <code>[STARTING] AT <dir> ...]</code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12071User Reference:Custom GUI Commands2025-08-28T20:43:13Z<p>Jhill: </p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
__FORCETOC__<br />
<br />
===CHOOSE ...===<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file. Print the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files. Print the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists). Print the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory. Print the resulting directory path.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star).<br />
<br />
; <code>[STARTING] AT <dir> ...]</code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
===CUSTOM DIALOG ...===<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide. Possible clauses are:<br />
<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases. In dialogs without <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12070User Reference:Custom GUI Commands2025-08-28T20:36:29Z<p>Jhill: </p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
==CHOOSE ...==<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file. Print the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files. Print the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists). Print the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory. Print the resulting directory path.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star).<br />
<br />
; <code>[STARTING] AT <dir> ...]</code> (equivalently you can say <code>IN</code> or <code>FROM</code> if it reads better)<br />
: This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
==CUSTOM DIALOG ...==<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide.<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched).<br />
: You will probably not need to configure the buttons explicitly in most cases. In dialogs with no <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12069User Reference:Custom GUI Commands2025-08-28T20:34:27Z<p>Jhill: </p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
==CHOOSE ...==<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file. Print the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files. Print the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists). Print the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory. Print the resulting directory path.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star).<br />
<br />
; <code>[STARTING] AT <dir> ...]</code> (or equivalently <code>IN</code> or <code>FROM</code>)<br />
: This specifies where the dialog's file-system navigation should start (by default, it<br />
will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
==CUSTOM DIALOG ...==<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide.<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched).<br />
: You will probably not need to configure the buttons explicitly in most cases. In dialogs with no <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12068User Reference:Custom GUI Commands2025-08-28T20:33:34Z<p>Jhill: </p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
=====CHOOSE ...=====<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>)<br />
: Prompts the user to select a single existing file. Print the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>)<br />
: Prompts the user to select one or more existing files. Print the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>)<br />
: Prompts the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists). Print the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code><br />
: Prompts the user to specify a directory. Print the resulting directory path.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: This limits the view (via a drop-down file-type selector) to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star).<br />
<br />
; <code>[STARTING] AT <dir> ...]</code> (or equivalently <code>IN</code> or <code>FROM</code>)<br />
: This specifies where the dialog's file-system navigation should start (by default, it<br />
will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: This specifies the text prompt at the top of the dialog.<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory:"<br />
</pre><br />
<br />
=====CUSTOM DIALOG ...=====<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide.<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched).<br />
: You will probably not need to configure the buttons explicitly in most cases. In dialogs with no <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12067User Reference:Custom GUI Commands2025-08-28T20:29:38Z<p>Jhill: </p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
=====CHOOSE ...=====<br />
<br />
The <code>CHOOSE</code> family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.<br />
<br />
; <code>CHOOSE INPUT FILE</code> (or equivalently <code>CHOOSE FILE</code>, or <code>CHOOSE INPUT</code>) : Prompt the user to select a single existing file. Print the resulting file path.<br />
<br />
; <code>CHOOSE INPUT FILES</code> (or equivalently<code>CHOOSE FILES</code>) : Prompt the user to select one or more existing files. Print the resulting file paths.<br />
<br />
; <code>CHOOSE OUTPUT FILE</code> (or equivalently<code>CHOOSE OUTPUT</code>) : Prompt the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists). Print the resulting file path.<br />
<br />
; <code>CHOOSE DIRECTORY</code> : Prompt the user to specify a directory. Print the resulting directory path.<br />
<br />
The commands may be followed by one or more of the following optional clauses (they must appear in this order):<br />
<br />
; <code>[OF] TYPE[S] <.ext1> [<.ext2> ...]</code><br />
: Limit the choice, by default, to files that have the specified extension(s). This clause cannot be used with <code>CHOOSE DIRECTORY</code>. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star).<br />
<br />
; <code>[STARTING] AT <dir> ...]</code> (or equivalently <code>IN</code> or <code>FROM</code>)<br />
: Specify where the dialog's file-system navigation should start (by default, it<br />
will start in the current working directory).<br />
<br />
; <code>[WITH] PROMPT <msg></code><br />
: Specify the text prompt at the top of the dialog.<br />
<br />
Examples:<br />
<pre><br />
choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"<br />
<br />
choose output file of type .prm in ../parms with prompt "Save parameters as..."<br />
<br />
choose directory starting at ../data with prompt "Select a subject directory"<br />
</pre><br />
<br />
=====CUSTOM DIALOG ...=====<br />
<br />
This command assembles a flexibly customizable modal dialog for communicating with the user. The command returns (prints) a string denoting which button the user pressed to complete the dialog, and as a side effect it may set any environment variables that the command specifies. If the user cancels the dialog, the command does nothing (prints nothing, does not change any environment variables).<br />
<br />
The <code>CUSTOM DIALOG</code> command can be followed by as many clauses as you like. The main types of clause are <code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog, in the order you provide.<br />
<br />
; <code>MESSAGE <msg></code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, will be the one that gets highlighted by default and bound to the enter/return keystroke. If you do not specify a default, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke, and pressing this button is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched).<br />
: You will probably not need to configure the buttons explicitly in most cases. In dialogs with no <code>VAR</code> clauses (where you are simply displaying messages to the user), the <code>BUTTONS {Ok} DEFAULT Ok</code> configuration is assumed. In dialogs with one or more <code>VAR</code> clauses (where you are asking the user for information), the <code>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel</code> configuration is assumed.<br />
<br />
; <code>TITLE <text></code><br />
: This overrides the default dialog title "BCI2000".<br />
<br />
; <code>SPACING <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical spacing between successive <code>MESSAGE</code> and/or <code>VAR</code> elements.<br />
<br />
; <code>WIDTH <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>HEIGHT <N></code><br />
: Supply an integer value <code>N</code> to specify the minimum width of the dialog in pixels.<br />
<br />
; <code>LEFT <N></code><br />
: Supply an integer value <code>N</code> to specify the horizontal coordinate of the dialog's left edge, in pixels.<br />
<br />
; <code>TOP <N></code><br />
: Supply an integer value <code>N</code> to specify the vertical coordinate of the dialog's top edge, in pixels.</div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Custom_GUI_Commands&diff=12066User Reference:Custom GUI Commands2025-08-28T18:37:52Z<p>Jhill: /* CUSTOM DIALOG [MESSAGE ] [VAR {[]} ] [BUTTONS {}] ... */</p>
<hr />
<div>BCI2000's [[User_Reference:Operator_Module_Scripting|Operator Module Scripting]] capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.<br />
<br />
<br />
The expanded form of this documentation is still under construction. For now, here is the short summary:<br />
<br />
<br />
=====CHOOSE [INPUT] FILE[S] [OF TYPE <.ext1> [<.ext2> ...]] [STARTING AT <dir>] [WITH PROMPT <message>]=====<br />
Via the Qt graphical user interface, prompt the user to select an existing file (or multiple files, if the keyword FILES is used). Print the resulting file path(s).<br />
<br />
=====CHOOSE [OUTPUT] FILE [OF TYPE <.ext1> [<.ext2> ...]] [STARTING AT <dir>] [WITH PROMPT <message>]=====<br />
Via the Qt graphical user interface, prompt the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists). Print the resulting file path.<br />
<br />
=====CHOOSE DIRECTORY [STARTING AT <dir>] [WITH PROMPT <message>]=====<br />
Via the Qt graphical user interface, prompt the user to specify a directory. Print the resulting directory path.<br />
<br />
=====CUSTOM DIALOG [MESSAGE <msg>] [VAR <varname> <label> {[<options>]} ] [BUTTONS {<buttons>}] ... =====<br />
Via the Qt graphical user interface, prompt the user with a modal dialog that can be flexibly customized.<br />
<br />
<br />
<code>CUSTOM DIALOG</code> can be followed by as many clauses as you like. The main types of clause are<br />
<code>MESSAGE</code> and <code>VAR</code> clauses, which are rendered from top to bottom in the dialog,<br />
in the order you provide.<br />
<br />
; <code>MESSAGE <msg></code> (e.g. <code>MESSAGE "Hello there!"</code>)<br />
: The 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.<br />
<br />
; <code>VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]</code><br />
: 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><br />
<br />
; <code>VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]</code><br />
: 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. For example: <pre>custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1</pre><br />
<br />
; <code>BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]</code><br />
: This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as <code>DEFAULT</code>, if any, is the one that is highlighted by default and bound to the enter/return keystroke (if you do not specify this, then "Ok" will be assumed to be the default button; if the designated default does not appear in the list of buttons, the buttons will all have equal status with no default and no return-keystroke binding). The button label designated as <code>ESCAPE</code>, if any, is the one that is bound to the escape keystroke and is equivalent to closing the dialog without making a selection (the <code>CUSTOM DIALOG</code> command will return the empty string in that case, and no environment variables will be touched). You will probably not need to configure the buttons explicitly in most cases - the following configurations are assumed, if you do not explicitly override them: <pre>BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel # in cases where you are asking the user for information, i.e. you have at least one VAR</pre><pre>BUTTONS {Ok} DEFAULT Ok # in cases with no VAR clauses, where the dialog is just a message to the user</pre></div>Jhillhttps://www.bci2000.org/mediawiki/index.php?title=User_Reference:Operator_Module_Scripting&diff=12065User Reference:Operator Module Scripting2025-08-28T17:59:22Z<p>Jhill: /* Operator-module Commands for Soliciting Input from the User */</p>
<hr />
<div>Operator scripts automate actions that the otherwise would be performed by the user, e.g. starting or suspending system operation.<br />
Scripts may be contained in script files, or given immediately in the operator module's preferences dialog.<br />
There is also an option to specify scripts from the [[User Reference:Module Command Line Options#Operator Module|command line]] when starting the operator module. When using the [[User_Reference:BCI2000Shell|BCI2000Shell]], or the [[Technical_Reference:Operator_Library|Operator Library]] from your own application, you may execute scripts at any time.<br />
<br />
In addition, the operator scripting language may be used to control an operator module over a [[User_Reference:Module_Command_Line_Options#--Telnet|Telnet]] or [[User_Reference:Module_Command_Line_Options#--WebSocket|WebSocket]] connection.<br />
===Syntax===<br />
'''Command separation.''' Scripts consist of sequences of the commands listed below. A command must be terminated with either a newline, or a semicolon (;).<br />
This allows to put multiple commands into one line, separated by semicolon characters.<br />
Commands are case-insensitive, variables and values may be case-sensitive, depending on context.<br />
<br />
'''Comments.''' Lines starting with a '#' character are ignored. Such lines may be used to hold comments. In addition, when any of the first two lines of a script contains "#!" (the Unix shell invocation sequence), it will be ignored. In conjunction with [[User Reference:BCI2000Shell|BCI2000Shell]], this may be used to write Operator scripts that may be treated as executables.<br />
<br />
'''Escaping.''' In order to resolve ambiguity about command arguments that contain white space, they must be included in double quotes, or the white space must be encoded in URL-fashion, e.g. ''%20'' instead of a space character. Similarly, when an argument contains a semicolon (;), it must be included in double quotes, or the semicolon must be encoded in URL-fashion, i.e. as ''%3B''. Also, "$" characters indicate command substitution, so they should be encoded as ''%24'' if substitution is not desired.<br />
<br />
'''Variable Substitution.''' When a command contains a dollar sign, alphanumeric characters following the dollar sign will be interpreted as the name of a variable: $NAME. The name will be matched against Expression variable names first, followed with Local variable names, and finally Environment variable names. When a match is found, $NAME will be replaced with the content of the matching variable. When no match is found, $NAME will be resolved to an empty string, without triggering an error.<br />
<br />
'''Command Substitution.''' When part of a command is enclosed with ${...}, this subexpression will be substituted with the result of its execution as a command. E.g.,<br />
LOG "Current system state is: ${GET SYSTEM STATE}"<br />
LOG "The path environment variable is: ${PATH}"<br />
Note that the last example uses the short form of the GET command, which will return the value of a PATH parameter or a PATH state if such exists. To make sure that only environment variables are matched, use the long form of the GET command:<br />
LOG MESSAGE "The path environment variable is: ${GET VARIABLE PATH}"<br />
Substitutions may be nested, i.e. the following will work as expected:<br />
SET MyVar "LIST STATES"; LOG "States are: ${$MyVar}"<br />
SET MyVar "LIST STATES"; LOG "States are: ${${GET VARIABLE MyVar}}"<br />
<br />
'''Mathematical Expressions.''' A command may consist of a single [[User Reference:Expression Syntax|mathematical expression]]. This expression is then evaluated, and its result is returned as the command's result. As a special case, this allows the use of expression variables in ${...} substitutions. Consider for example<br />
x:=0; WHILE x<10; LOG ${x:=x+1}; END<br />
There, the first command creates and initializes the expression variable x. In the WHILE condition, an expression is allowed as well as any command. In the LOG command, an expression appears in ${...}, which executes the expression in braces, and substitutes the result of the expression as an argument into the LOG command, which adds an entry to the Operator log. This results in a sequence of 10 log entries, containing the numbers from 1 to 10.<br />
<br />
===Commands===<br />
====Control commands====<br />
These commands allow conditional execution of parts of a script. When a condition is expected, any other scripting command may be given. Its result will be considered to represent a boolean value of "true" if it is empty, a nonzero number, or the string "true". It will be taken to represent a boolean value of "false" if it contains a numeric value of zero, or any string that does not evaluate to a nonzero number. Note that identification of an empty value with "true" differs from string handling in the EVALUATE CONDITION command. This is because most scripting commands return nothing on success, but an error message on failure.<br />
<br />
The output of the SYSTEM and START EXECUTABLE commands is handled specially. There, the result code of the created child process is translated into a boolean value in the ordinary manner, treating a result code of zero as "true", and any other result code as "false". This allows to use external commands in the same way as in a native shell.<br />
<br />
=====IF <condition>; <if commands>; [ ELSEIF <condition>; <elseif commands>;] ... [ ELSE; <else commands>;] END=====<br />
Executes ''if commands'' if ''condition'' evaluates to "true". Otherwise, the ''elseif commands'' of the first matching ''elseif condition'' are executed. When none of the ''elseif conditions'' evaluates to "true", ''else commands'' are executed. ELSEIF and ELSE blocks may be omitted.<br />
<br />
=====WHILE <condition>; <loop commands>; END=====<br />
Executes ''loop commands'' while ''condition'' evaluates to ''true''.<br />
=====DO; <loop commands>; UNTIL <condition>=====<br />
Executes ''loop commands'' until "condition" evaluates to ''true''.<br />
=====FOR <name> IN <item1> <item2> ... ; <loop commands>; END=====<br />
Creates a local variable with the specified name. Then, sequentially assigns each ''item'' to that variable, and executes ''loop commands''. If an ''item'' contains newline characters, it is split up into multiple items, corresponding to the lines contained in the ''item''. E.g.,<br />
FOR i IN top ${LIST FILES} bottom; LOG ${i}; END<br />
will first write a log entry "top". Then, it will create a log entry for each file in the current directory, and finally, it will create a log entry "bottom".<br />
<br />
====Commands operating on Conditions====<br />
=====EVALUATE CONDITION <left> [<op> [<right>]]=====<br />
Evaluates a comparison between the ''left'' and ''right'' operands. As a comparison operator, the following may be specified: ==, !=, ~=, <, >, <=, >=. There, the != operator behaves identically to the ~= operator. When a test for equality is performed, the two operands are treated as strings, and compared in a case-insensitive manner. When any of the inequality tests is performed, the two operands are converted into floating-point numbers before comparison.<br />
<br />
The ''right'' operand may be omitted, in which case it is treated as if an empty string were specified. Also, the ''op'' operator may be omitted, in which case the following rules apply regarding the remaining operand: If it is an empty string, or equal to the string "false" in case-insensitive comparison, the result is "false". If entirely consists of the text representation of a floating-point number, the result is "false" if the number is 0, and "true" if the number is not 0.<br />
<br />
Inspired by the unix sh shells' <tt>test</tt> command, there exists a short form of the EVALUATE CONDITION command, where the arguments of EVALUATE CONDITION may appear within square brackets. This allows constructs such as<br />
IF [ ${MyVar} == MyValue ]; LOG Is equal; ELSE; LOG Is different; END<br />
Note that the arguments to EVALUATE CONDITION must always be separated by white space, no matter whether its long or short form is used.<br />
<br />
Conditions may be combined logically using the operators && and ||. These go ''outside'' the square brackets. Note also that whitespace around the comparison operators is critical, otherwise the conditional will be treated as a single string (which will always evaluate to "true")<br />
<br />
IF [ ${foo} == foo ] || [ ${bar} == bar ]; LOG got a match; END<br />
<br />
====Commands operating on Local Variables====<br />
Besides environment variables, there exist local variables in scripts. Local variables are inherited by sub-scripts executed with the EXECUTE SCRIPT command, but changes to the variable's values will not be propagated to the calling script.<br />
=====SET VARIABLE <name> <value>=====<br />
Sets the named variable to the specified value.<br />
=====CLEAR VARIABLE <name>=====<br />
Removes the named variable from memory.<br />
=====GET VARIABLE <name>=====<br />
Returns the variable's current value. When the variable does not exist, an empty value is returned rather than an error message.<br />
<br />
====Commands operating on Environment Variables====<br />
These scripting commands allow to read and modify environment variables. Changes to environment variables will be visible to child processes started with SYSTEM or START EXECUTABLE. Variable values are stored as strings. Variable names may not contain the equals sign.<br />
=====SET ENVIRONMENT <name> <value>=====<br />
Sets the named variable to the specified value.<br />
=====CLEAR ENVIRONMENT <name>=====<br />
Removes the named variable from memory.<br />
=====GET ENVIRONMENT <name>=====<br />
Returns the variable's current value. When the variable does not exist, an empty value is returned rather than an error message.<br />
<br />
====Commands operating on Scripts====<br />
=====SET SCRIPT <handler names> <scripting commands>=====<br />
Associates a sequence of scripting commands with the named handler. Handlers are specified by names as given [[#Handlers|below]]. Multiple handlers may be specified by concatenating their names with a pipe character, e.g. "OnStart|OnResume".<br />
<br />
Scripting commands must be included in double quotes, unless they consist of a single word.<br />
When specifying a sequence of scripting commands, they must be separated with a semicolon character: "SetConfig; Start". In order to use double quotes or semicolons within the commands themselves, encode these as you would in a URL, i.e. replace a double quote character with ''%22'', and a semicolon with ''%3B'': "Load Parameters %22my file%22".<br />
<br />
To use a script file rather than a literal script, use the EXECUTE SCRIPT command:<br />
SET SCRIPT OnConnect "EXECUTE SCRIPT myscript.txt"<br />
<br />
=====GET SCRIPT <handler name>=====<br />
Returns the script associated with the specified handler.<br />
<br />
=====CLEAR SCRIPT <handler names>=====<br />
Clears scripts for the given handlers. Equivalent to calling SET SCRIPT with an empty script.<br />
<br />
=====EXECUTE SCRIPT <file or handler name> [<Arg1> <Arg2> ... <Arg9>]=====<br />
Executes a script contained in a file, and optionally sets the script's local variables ''1'' to ''9'' to the specified values. To execute script commands already associated with a handler, provide a handler name rather than a file. When the script is executed successfully, the result of the last executed script command becomes the result of the EXECUTE SCRIPT command itself. Use "SET Result <value>" as the last command in a script in order to return a certain value.<br />
<br />
When you run a script through EXECUTE SCRIPT, it will inherit copies of variables from its calling script/command line. Variable changes will be local to the script, and will be lost when script execution is complete.<br />
<br />
The ''AbortOnError'' variable determines whether a script is aborted when any of its commands result in an error message. ''AbortOnError'' is not inherited but defaults to 1 in any script.<br />
<br />
====Commands operating on Parameters====<br />
=====LOAD PARAMETERFILE <file>, LOAD PARAMETERS <file>=====<br />
Loads a parameter file specified by its path and name. Relative paths are interpreted relative to the operator module's working directory at startup. Usually, this matches the executable's location in the <tt>prog</tt> directory.<br />
As the parameter file name must not contain white space, please use HTML-type encoding for white space characters, such as <tt>Documents%20and%20Settings</tt> when referring to a user's "Documents and Settings" folder.<br />
<br />
NOTE: Only those parameters will be loaded that do exist at the time when this command is called. In idle state, no parameters exist other than created by ADD PARAMETER. After modules are connected and have published their parameters to the Operator module, a full set of parameters exist.<br />
<br />
=====ADD PARAMETER <parameter definition>=====<br />
Adds a parameter to the system. The parameter is specified as a [[Technical_Reference:Parameter_Definition#Parameter_Lines|parameter line]]. This command may not be used after system initialization has completed, i.e. its use is restricted to the "Idle" and "Publishing" [[Technical_Reference:States_of_Operation#Publishing_Phase|phases of system operation]]. In terms of handlers, its use is restricted to the ''OnConnect'' handler.<br />
=====EXISTS PARAMETER <name>=====<br />
Returns "true" when the specified parameter exists in the system, and "false" otherwise.<br />
<br />
=====ISEMPTY PARAMETER <name>=====<br />
Returns "true" when the specified parameter exists and has no values, "false" if it exists and has values.<br />
<br />
=====SET PARAMETER <name>[( idx1, idx2 )] <value>=====<br />
Sets the named parameter to the specified value. Values that contain special characters, or whitespace must use the [[Technical_Reference:Parameter_Definition#Special_Characters|parameter value encoding]]. Use parentheses to specify indices or labels. Omitted indices default to 1.<br />
<br />
=====SET PARAMETER <parameter line>=====<br />
Replace a parameter's value and definition with the information given in the [[Technical_Reference:Parameter_Definition#Parameter_Lines|parameter line]]. The parameter must exist in the system when this command is executed.<br />
<br />
=====GET PARAMETER <name>[( idx1, idx2 )]=====<br />
Prints the value of the named parameter. Use parentheses to specify indices or labels.<br />
<br />
=====SET PARAMETERROWS <parameter name> <rows>=====<br />
Sets the number of rows in the named parameter.<br />
<br />
=====GET PARAMETERROWS <parameter name>=====<br />
Prints the number of rows in the named parameter.<br />
<br />
=====SET PARAMETERCOLS <parameter name>=====<br />
Sets the number of columns in the named parameter.<br />
<br />
=====GET PARAMETERCOLS <parameter name>=====<br />
Prints the number of columns in the named parameter.<br />
<br />
=====LIST PARAMETER <wildcard expression>, LIST PARAMETERS=====<br />
Prints all parameters with names matching the wildcard expression, in form of parameter lines.<br />
=====CLEAR PARAMETERS=====<br />
Clears the list of parameters in the system. May only be executed in ''Idle'' and ''Publishing'' system states.<br />
<br />
====Commands operating on States====<br />
In BCI2000, there are three types of States that differ in their alignment to brain signal data (see [[Technical_Reference:State_Definition#Kinds_of_States|Kinds of States]]). This section applies to both Stream States, and normal States.<br />
For Event States, see the next section.<br />
<br />
=====ADD STATE <name> <bit width> <initial value>=====<br />
Adds a state variable to the system. State variables are defined by name, bit width, and initial value (see [[Technical Reference:State Definition]]). This command may not be used after system initialization has completed, i.e. its use is restricted to the "Idle" and "Publishing" [[Technical_Reference:States_of_Operation#Publishing_Phase|phases of system operation]]. In terms of handlers, its use is restricted to the ''OnConnect'' handler.<br />
=====EXISTS STATE <name>=====<br />
Returns "true" when the specified state exists in the system, and "false" otherwise.<br />
<br />
=====SET STATE <name> <value>, SET STATES <name1> <value1> <name2> <value2> ...=====<br />
Sets the named state variable to the specified integer value by sending a state message to the source module.<br />
Setting the ''Running'' state to 1 will start system operation, setting it to 0 will suspend the system.<br />
<br />
<tt>SET STATES</tt> will atomically set the values of multiple states.<br />
<br />
=====GET STATE[(<sample>)] <name>=====<br />
Gets the value of the named state. Note that state values are not updated from the application module when the ''OperatorBackLink'' parameter is 0. In that case, GET STATE will return the state's initial value.<br />
<br />
An optional one-based sample index may be given to indicate that the state value should be retrieved at the given sample position. Sample positions range from 1 to the number of samples per block present in the state vector. The number of samples per block may be retrieved using GET STATEVECTOR SAMPLES.<br />
<br />
By default, the state's value is retrieved for sample index 1.<br />
<br />
=====LIST STATE <wildcard expression>, LIST STATES=====<br />
Lists all states, or states with names matching the given wildcard expression, in form of state lines.<br />
=====CLEAR STATES=====<br />
Clears the list of states in the system. May only be executed in ''Idle'' and ''Publishing'' system states.<br />
<br />
=====FREEZE STATES, THAW STATES=====<br />
Freezes/thaws the values of all states in the state vector, without interfering with system operation. "Freezing" creates, and "thawing" discards, a frozen snapshot of the state vector. For the duration of its existence, GET STATE calls will be diverted to the snapshot. This is useful for ensuring that multiple GET STATE commands actually retrieve mutually-consistent values from different state variables (i.e. values from the same sample-block).<br />
<br />
=====GET STATEVECTOR SAMPLES=====<br />
Returns the number of samples in the state vector per block of data. In the system's "Running" state, this matches the number of samples per block in the source data. Prior to the "Running" state, this is 1 because the state vector has not yet been updated from the application module.<br />
<br />
====Commands operating on Events====<br />
Events are a special type of state, which are recorded asynchronously, at single-sample resolution. Events may only be added while the system is in "idle" state. This kind of events is not related to [[#Handlers|Operator Events]] as defined below.<br />
=====ADD EVENT <name> <bit width> <initial value>=====<br />
Adds an event to the system. Like state variables, events are defined by name, bit width, and initial value (see [[Technical Reference:State Definition]]). This command may not be used after the system has started up, so it is typically executed within a telnet session before ''STARTUP'' has been called.<br />
=====EXISTS EVENT <name>=====<br />
Returns "true" when the specified event exists in the system, and "false" otherwise.<br />
<br />
=====SET EVENT <name> <value>=====<br />
Asynchronously sets an event to the given value. Recording events requires the EventLink logger component to be present in the source module.<br />
<br />
'''NOTE:''' In versions prior to BCI2000 3.06, this command behaved as described for PULSE EVENT below, rather than as advertised. If you used SET EVENT in your scripts, it is recommended to replace it with PULSE EVENT in order to retain original behavior.<br />
<br />
=====PULSE EVENT <name> <value>=====<br />
Asynchronously sets an event to the given value for a single sample duration. Recording events requires the EventLink logger component to be present in the source module.<br />
<br />
=====SET EVENTS [<name> <value>] [<name2> <value2>] ... =====<br />
Asynchronously sets given events to their specified values. Using this command, rather than multiple SET EVENT commands in a row, ensures that all event changes are recorded at exactly the same point in time. Recording events requires the EventLink logger component to be present in the source module.<br />
<br />
=====PULSE EVENTS [<name> <value>] [<name2> <value2>] ... =====<br />
Asynchronously sets given events to their specified values for a single sample duration. Using this command, rather than multiple PULSE EVENT commands in a row, ensures that all event changes are recorded at exactly the same point in time. Recording events requires the EventLink logger component to be present in the source module.<br />
<br />
=====GET EVENT[(<sample>)] <name>=====<br />
Gets the value of the named event. Note that evemt values are not updated from the application module when the ''OperatorBackLink'' parameter is 0.<br />
<br />
An optional one-based sample index may be given to indicate that the event's value should be retrieved at the given sample position. Sample positions range from 1 to the number of samples per block present in the state vector. The number of samples per block may be retrieved using GET STATEVECTOR SAMPLES.<br />
<br />
By default, the event's value is retrieved for sample index 1.<br />
<br />
=====LIST EVENT <wildcard expression>, LIST EVENTS=====<br />
Lists all events, or events with names matching the given wildcard expression, in form of state lines.<br />
=====CLEAR EVENTS=====<br />
Clears the list of events in the system. May only be executed in ''Idle'' state.<br />
<br />
====Commands operating on VisProperties====<br />
=====SET VISPROPERTY <visID>.<name> <value>=====<br />
Sets the named [[Technical Reference:Visualization Properties|visualization property]] for the specified visualization ID to the given value. If the visualization ID contains a dot character, it must be encoded in [[Technical_Reference:Parameter_Definition#Special_Characters|parameter value encoding]]. E.g., setting the window width for the visualization ID "2.D1" would be written <code>SET VISPROPERTY 2%2ED1.Width 200</code>.<br />
<br />
=====RESET VISPROPERTY <visID>.<name>=====<br />
Removes the named visualization property fro the specified visualization ID from the property store, effectively resetting its value to its default.<br />
<br />
=====GET VISPROPERTY <visID>.<name>=====<br />
Prints the value of the named [[Technical Reference:Visualization Properties|visualization property]] for the specified visualization ID.<br />
<br />
=====SET VISPROPERTIES <property set ID>=====<br />
Applies a set of visualization property values as given in the [[#VisPropertySets|VisPropertySets]] parameter. In that matrix-valued parameter, row labels specify visualization properties such as "SRCD.Left", and columns represent sets of property values. Column labels are IDs of the corresponding property sets.<br />
<br />
====Commands operating on the Control Signal====<br />
=====GET SIGNAL( <channel index>, <element index> )=====<br />
Prints the value of the control signal at the given indices. Indices are 1-based.<br />
=====GET SIGNAL CHANNELS=====<br />
Prints the number of channels in the control signal.<br />
=====GET SIGNAL ELEMENTS=====<br />
Prints the number of elements (samples) in the control signal.<br />
=====FREEZE SIGNAL, THAW SIGNAL=====<br />
Freezes/thaws the contents of the control signal, without interfering with system operation. "Freezing" creates, and "thawing" discards, a frozen snapshot of the control signal. For the duration of its existence, GET SIGNAL calls will be diverted to the snapshot. This is useful for ensuring that multiple GET SIGNAL commands actually retrieve mutually-consistent values from different elements in the control signal (i.e. values from the same sample-block).<br />
<br />
====Commands operating on Expressions====<br />
=====EVALUATE EXPRESSION <expression>=====<br />
This command treats the remainder of the command as a literal mathematical expression (for a description, see [[User Reference:Expression Syntax]]. An expression may contain variable assignments; such variables may then be used in later expressions. Note that expression variables are different from local and environment variables that may be accessed by GET/SET VARIABLE/ENVIRONMENT. Expression variables hold numerical values, while local and environment variables hold string values. Also, environment variables are accessible to child processes started with SYSTEM or START EXECUTABLE, while expression variables are accessible only to scripts. When a script is executed using the EXECUTE SCRIPT command, it will inherit a copy of all expression variables present. Changes to these variables from the executed script will not be visible in the parent script.<br />
<br />
=====CLEAR EXPRESSION VARIABLE <name>=====<br />
Clears the named expression variable from storage.<br />
<br />
====Commands operating on Watches====<br />
A "Watch" is an object that consists of a set of expressions, and an action. Whenever the value of any of the expressions changes, the watch is "triggered", and the action is executed. Watches allow client applications to respond to BCI2000 state changes in a reliable manner. Rather than polling information from BCI2000, a client may create a watch to be notified about changes of interest. This avoids the problem of missing short-lived changes, which is inherent in the polling approach.<br />
<br />
For watches created through operator scripting, the action consists of dumping values of all the expressions to a UDP port.<br />
<br />
The intended use of a watch from a client application is to create a separate thread that reads from the watch's UDP port in a blocking mode, and calls an appropriate handler function whenever it receives data.<br />
The data sent will consist of a single UDP packet with a single line in ASCII format, terminated with a CRLF sequence. The line consists of tab-separated data fields, which contain the current values of the expressions specified when creating the watch. In addition, the first field contains a time stamp in the same time base as the <tt>SourceTime</tt> state, wrapping around every 65536 ms. This time stamp represents the point in time where the expression value changed, with an accuracy of a single sample.<br />
<br />
=====ADD WATCH [decimate <n>] <expression1> <expression2> ... [AT <ip:port>]=====<br />
Adds a watch for the listed expressions. Each expression's value will be reported in a separate field. When an address is specified in <tt>ip:port</tt> format, the watch tries to open that port for output, and creation fails if that port is taken. Otherwise, a free port is chosen automatically. In both cases, successful creation of the watch is indicated by returning the output address in ASCII format. The address is also used to uniquely identify a watch in the context of a connection.<br />
<br />
When a ''decimate <n>'' clause is present, the watch will be created with decimation, i.e. it will only be evaluated for every ''n''th<br />
sample of the state vector.<br />
<br />
If a watch is created through a remote connection, it will use the remote host's external IP address for automatically chosen addresses. Otherwise, the output port will be associated with the machine's <tt>localhost</tt> address.<br />
<br />
Watches may be created even if the system is currently running. In this case, the watch is triggered immediately, and sends its current expression values to its output port.<br />
<br />
=====ADD WATCH SYSTEM STATE [AT <address>]=====<br />
Similar to the first variant of ADD WATCH, but will watch the system's state as reported by GET SYSTEM STATE.<br />
<br />
=====CLEAR WATCH <address>, CLEAR WATCHES [<wildcard-expression>]=====<br />
Removes the watches specified by address, or those with their addresses matching a wildcard expression. If CLEAR WATCHES is called without argument, all watches will be deleted.<br />
<br />
=====TRIGGER WATCH <address>, TRIGGER WATCHES [<wildcard-expression>]=====<br />
Forces dumping of the watches' current expression values to their output ports. Mostly useful for testing purposes.<br />
<br />
=====LIST WATCHES [<wildcard-expression>]=====<br />
Displays a list of existing watches, and their addresses.<br />
<br />
=====COUNT WATCHES [<wildcard-expression>]=====<br />
Returns the number of existing watches, or the number of watches whose addresses match the optional wildcard expression.<br />
<br />
====Commands operating on Files, Directories, and Paths====<br />
=====EXTRACT DIRECTORY <path>, EXTRACT FILE <path>, EXTRACT FILE BASE <path>=====<br />
Extracts the directory or file portion of a given path. When the path specifies a non-existing directory, the directory name must be followed with a separator ("/") in order to be recognized as a directory. The EXTRACT DIRECTORY command always returns its result with a trailing separator. The EXTRACT FILE BASE command returns the file portion without extension.<br />
<br />
=====IS DIRECTORY <path>, IS FILE <path>, IS PATH <path>=====<br />
Determines whether the specified path points to an existing directory, file, or any of the two. The result is returned as one of the strings "true" or "false".<br />
=====PARENT DIRECTORY <path>=====<br />
Returns the parent directory of the specified path, independently of whether the path points to a directory, or to a file.<br />
=====CURRENT DIRECTORY=====<br />
Returns the current working directory.<br />
=====CHANGE DIRECTORY <path>=====<br />
Changes the working directory.<br />
=====MAKE DIRECTORY <path>=====<br />
Creates a new directory with the given path. The directory's parent must exist for the command to succeed.<br />
=====LIST DIRECTORY [<path> or <wildcard expression>]=====<br />
Returns a listing of the specified directory, or the current working directory if no path is specified. The listing is in long form. You may use wildcard expressions in order to restrict the output.<br />
=====LIST FILE <wildcard expression>=====<br />
Returns a list of file names matching ''wildcard expression'' in the current directory.<br />
=====LIST FILES [<directory> [<wildcard expression>]]=====<br />
Returns a list of file names from the specified directory, matching ''wildcard expression''. When ''wildcard expression'' is missing, all files are listed. When ''directory'' is missing, files in the current directory are listed.<br />
=====LIST DIRECTORIES [<directory> [<wildcard expression>]]=====<br />
Returns a list of directory names from the specified directory, matching ''wildcard expression''. When ''wildcard expression'' is missing, all directories are listed. When ''directory'' is missing, directories in the current directory are listed.<br />
<br />
=====RENAME FILE <current path> <new path>, RENAME DIRECTORY <current path> <new name>=====<br />
Renames a file resp. a directory. For files, a different path may be given in the second argument, resulting in that the file is moved to the location specified by the new path. For directories, the path up to the directory's name must stay the same.<br />
=====REMOVE FILE <path>, REMOVE DIRECTORY <path>=====<br />
Removes the specified file or directory. This command cannot be undone. The directory must be empty for the command to succeed.<br />
=====FORCEREMOVE DIRECTORY <path>=====<br />
Removes the specified directory and its contents. Symbolic links are treated as ordinary files, i.e. they are not followed. This command cannot be undone.<br />
=====NORMALIZED PATH <path>=====<br />
Returns <path>, with the following transformations applied:<br />
*Removes relative elements (<tt>..</tt> <tt>.</tt>) as far as possible. For absolute paths, the result will not contain any relative elements; for relative paths, double-dots may appear at the beginning of the result if necessary.<br />
If a relative path simplifies to the empty string, <tt>./</tt> is returned. Thus, the result of NORMALIZED PATH is never empty, unless its input was empty.<br />
*Replaces backward slashes with forward slashes to achieve uniformity across platforms.<br />
*On case-insensitive file systems, replaces the spelling of names with the one stored in the file system.<br />
*On Win32, replaces short (8.3) names with long ones.<br />
<br />
=====CANONICAL PATH <path>=====<br />
If <path> points to an existing file or directory, CANONICAL PATH returns a valid absolute file path, suitable as an unambiguous representation for the object pointed to. Especially, two non-empty canonical path strings will compare equal if and only if they refer to the same file system object.<br />
<br />
If <path> does not point to an existing file system object, construction of a canonical path is not possible due to lack of information about the named object, and CANONICAL PATH will return an empty string.<br />
<br />
'''NOTES:''' The need for an unambiguous, or canonical, representation arises due to ambiguities in the string representation of paths, and in file systems themselves.<br />
*Paths may contain relative elements: <tt>/mydir/../myfile</tt> points to the same object as <tt>/myfile</tt>.<br />
*A path that involves symbolic links will point to the same object as a path containing one or more of those links in resolved form.<br />
*File systems may be case-insensitive, or may even provide multiple distinct names for individual directory entries (Win32 short vs. long names).<br />
<br />
On '''Win32,''' CANONICAL PATH returns the short (8.3) representation of a path, using uppercase spelling, and backslashes as directory separators. Apart from efficiency considerations, this aesthetically unpleasing representation has been chosen to discourage its use for anything except comparing file system objects.<br />
<br />
On '''other systems,''' CANONICAL PATH will return the result of the POSIX <tt>realpath()</tt> function.<br />
<br />
In both cases, a CANONICAL PATH will end with a native directory separator if, and only if, the object pointed to is a directory.<br />
<br />
=====REAL PATH <path>=====<br />
On this command provides a work-alike for the POSIX <tt>realpath()</tt> function.<br />
If <path> is empty, or if <path> points to a non-existing object, the result will be empty. Otherwise, an absolute path will be returned, with symbolic links resolved, using forward slashes as directory separators, and with spelling normalized as described for NORMALIZED PATH. A forward slash will be appended if the path points to a directory.<br />
<br />
'''NOTE:''' In principle, the path returned by REAL PATH should be just as unambiguous as the result of CANONICAL PATH. However, there are a few caveats:<br />
* On case-insensitive file systems, two independently obtained results of REAL PATH might differ in case spelling even if referring to the same file system object. This should not be the case for CANONICAL PATH.<br />
* Determining the result of CANONICAL PATH is a fast operation. In contrast, REAL PATH may be expensive to determine, as for each directory on the path a listing needs to be obtained, and a canonical path needs to be formed, and compared, for half of the listed directory entries on average.<br />
* On Win32, quite some amount of complexity arises from backward compatibility layers, forbidden file names, multiple filesystem roots, etc. Internally calling <tt>GetShortPathName()</tt>, CANONICAL PATH does not need to handle that complexity, and may be considered more reliable for identifying file system objects than REAL PATH.<br />
<br />
====Commands operating on executables====<br />
=====START EXECUTABLE <command line>=====<br />
Behaves identically to CREATE PROCESS, except that it does not report a process id for the new process. For details, see CREATE PROCESS.<br />
<br />
=====CATEGORIZE EXECUTABLE <name or path>=====<br />
BCI2000 keeps a list of executables/modules that have been built, and sorts them into categories. The CATEGORIZE EXECUTABLE command provides a way to retrieve that information. Given the name or path of an executable, it outputs one of the following categories:<br />
* SignalSource,<br />
* SignalProcessing,<br />
* Application,<br />
* Operator,<br />
* Tool,<br />
* Helper,<br />
* Unknown.<br />
<br />
====Commands operating on Lines of input/output====<br />
=====WRITE LINE <line>=====<br />
Writes a line of output. Destination depends on the context in which a script is executed. If the context is an Operator Handler, output is written as a log entry. If the context is a telnet session, output is written to the telnet connection. If the context is a [[User Reference:BCI2000Shell|BCI2000Shell]], output is written to the shell's stdout.<br />
<br />
=====READ LINE=====<br />
Reads a line of input from the current execution context's input. If the command is executed within an Operator Handler, it will fail. If executed within a telnet session, the other side of the connection is prompted for input. If executed from within a [[User Reference:BCI2000Shell|BCI2000Shell]], input is read from the shell's stdin.<br />
<br />
====Commands operating on Processes in the Operating System====<br />
=====CREATE PROCESS <command line>=====<br />
Starts the specified executable with options. This command returns after the started program has finished initialization, i.e. it will detect load time failures such as missing DLLs on Windows. If the process is still running when CREATE PROCESS returns, its result will be an operating system process id (pid). If the process has terminated, CREATE PROCESS will report its exit code marked with an <tt>ExitCode</tt> tag to allow distinction between a pid and an exit code.<br />
Please note that CREATE PROCESS requires quoting of arguments differently from other scripting commands. For details, see the SYSTEM command.<br />
<br />
=====TERMINATE PROCESS <pid>=====<br />
Tries to terminate the process with the given operating system pid, waiting for the process to terminate before returning. Will return <tt>false</tt> to indicate that a suitable process existed but could not be terminated.<br />
<br />
=====WAIT FOR PROCESS <pid> [<timeout seconds> = infinite]=====<br />
Waits for the process with the given operating system pid to terminate, or the timeout to expire. Returns <tt>false</tt> to indicate that the process is still executing.<br />
<br />
=====SHOW PROCESS <pid>=====<br />
Makes all windows visible which are associated with the process referred to by pid.<br />
In addition, brings one of the process' top level (desktop level) windows to the front for user interaction.<br />
<br />
=====HIDE PROCESS <pid>=====<br />
Makes all windows invisible which are associated with the process referred to by pid.<br />
<br />
====Global commands====<br />
=====HELP [<type>]=====<br />
When called with a type argument, lists commands that exist for the specified type (e.g., SYSTEM, or FILE). When called without argument, lists all commands in their main form. HELP ALL will list all commands, including synonyms.<br />
<br />
=====SET <name> <value>, GET <name>, <name>=====<br />
Allows to set or retrieve the value of local and environment variables. The name is matched against local and environment variables. When no variable with the given name is found, SET will create a local variable, while GET will result in an error. GET may be further abbreviated to only consist of a name.<br />
<br />
GET further allows evaluation of [[User_Reference:Expression_Syntax|mathematical expressions]]. When the expression is invalid, or contains an unknown variable, an error is triggered.<br />
<br />
=====GET SYSTEM STATE=====<br />
Prints the current system state. This will be one of Unavailable, Idle, Startup, Initialization, Resting, Suspended, ParamsModified, Running, Termination, Busy.<br />
<br />
=====GET CURRENT RUN FILE=====<br />
Prints the full path to the current run file, or an empty string, if called outside Running state.<br />
<br />
=====WAIT FOR <system state> [<timeout seconds>]=====<br />
Waits until the system is in the specified state. This may be one of Idle, Startup, Connected, Resting, Suspended, ParamsModified, Running, Busy, or a combination of these, separated with a pipe character: "Resting|Suspended". When no timeout is given, this command waits indefinitely. If the wait is successful, i.e. system state matches one of the specified states, WAIT FOR will return a value of "true". If timeout occurred, WAIT FOR will return "false".<br />
<br />
If the BCI2000 system is shut down while a script is executing a WAIT FOR command, the script will be terminated with a "wait aborted" error message.<br />
<br />
In more detail, user visible states are:<br />
* Idle: System is shut down and does not do other processing than executing scripts.<br />
* Startup: System has started up and is listening for incoming connections.<br />
* Connected: All core modules have connected to the system.<br />
* Resting: The system has been initialized but is not running.<br />
* Suspended: The system has ended running and is behaving like in Resting.<br />
* ParamsModified: In Suspended mode, parameter changes have been published and will be applied at Resume.<br />
* Running: The system is running, processing brain signals, and displaying stimuli.<br />
* Busy: The system is performing a transition from one state to another.<br />
<br />
As a synonym for "Connected," "Initialization" is valid as well since it is compatible with the nomenclature in StateMachine.h. Still, it should be avoided because it is easily confused with, but very distinct from, the actions performed in the Initialize() phase.<br />
<br />
=====SLEEP &lt;time in seconds&gt;=====<br />
Waits (sleeps) for the given amount of time. Timing resolution is 50ms. Tends to sleep a little longer than specified, with the error growing with duration.<br />
<br />
=====GET SYSTEM VERSION=====<br />
Prints BCI2000 version information.<br />
=====SETCONFIG, SET CONFIG=====<br />
Applies current parameters to the system. Corresponds to the ''SetConfig'' button in the GUI version of the Operator module.<br />
<br />
=====START=====<br />
Starts or resumes system operation, corresponding to the ''Start/Resume'' button in the GUI version of the Operator module.<br />
=====STOP=====<br />
Stops system operation. Corresponds to the ''Stop'' button in the GUI version of the Operator.<br />
=====STARTUP SYSTEM=====<br />
When in idle state, starts up the system to wait for incoming connections from core modules. Additionally, the following arguments may be given: 1) an IP address on which to listen (default is to listen on all addresses), and 2) a list of generic core module names with ports. The default configuration corresponds to these arguments:<br />
STARTUP SYSTEM * SignalSource:4000 SignalProcessing:4001 Application:4002<br />
<br />
A system log file may optionally be specified on this line, by inserting the <code>--SystemLogFile</code> flag between the IP address and the module specifiers. For example:<br />
<br />
STARTUP SYSTEM * --SystemLogFile=SOME_FILE.TXT SignalSource:4000 SignalProcessing:4001 Application:4002<br />
<br />
The system log file will record all operator log window messages for the current launch, until the system shuts down. It may be helpful to use the variables <code>$YYYYMMDD</code> and <code>$HHMMSS</code> to specify the filename. Note that file name and path cannot contain spaces.<br />
<br />
=====SHUTDOWN SYSTEM=====<br />
Shuts down core modules, and enters idle system state.<br />
=====RESET SYSTEM=====<br />
Shuts down the system, and clears all parameter, state, and event information.<br />
<br />
=====QUIT, EXIT [<result>]=====<br />
Quits the operator module after terminating all BCI2000 modules. The optional ''result'' argument determines the result of the executed script.<br />
<br />
=====CLOSE CONNECTION, TERMINATE CONNECTION=====<br />
In the context of a telnet or websocket connection, this command will terminate the connection.<br />
In other contexts, such as event handlers, it will be ignored.<br />
<br />
=====SYSTEM <command line>=====<br />
Executes a shell command, redirecting any console output into the command's script result. E.g., to obtain a directory listing, under Windows, you would enter<br />
SYSTEM DIR<br />
'''NOTE:''' Arguments to the SYSTEM command are executed by the operating system's shell, and thus may require quoting different from the other scripting commands. E.g., writing<br />
SET mydir ${PARENT DIRECTORY $BCI2000LAUNCHDIR}; ECHO ${LIST FILES $mydir}<br />
will list files in the BCI2000 main directory, independently of whether the path to that directory contains space characters or not. However, to obtain a directory listing through the SYSTEM command, you would need to write<br />
ECHO ${SYSTEM DIR "$mydir"}<br />
to make sure the content of the variable ''mydir'' is interpreted as a single argument, independently of whether it contains space characters.<br />
<br />
=====LOG <message>=====<br />
Append the specified message to the system log.<br />
=====WARN <message>=====<br />
Append the specified message to the system log, formatted as a warning.<br />
=====ERROR <message>=====<br />
Append the specified message to the system log, formatted as an error message.<br />
<br />
=====CAPTURE MESSAGES <message types>=====<br />
Captures system log messages into a background buffer. When no message type is given, all messages are captured. When "None" is given as a message type, message capturing is disabled. Otherwise, the message type must be one of "Errors", "Warnings", "Debug", "Log". Multiple message types may be specified in a single command. When "None" appears within a single command, all preceding message types are ignored. Multiple CAPTURE MESSAGES commands are cumulative, except when "None" is specified as a message type.<br />
<br />
=====FLUSH MESSAGES=====<br />
Clears the background message buffer, and returns its previous content. Use CAPTURE MESSAGES to capture messages into the background message buffer.<br />
<br />
====Operator-module defined Commands====<br />
=====HIDE WINDOW [<name>], SHOW WINDOW [<name>]=====<br />
Hides or shows the specified window. When called without a window name, the Operator module's main window is hidden or shown. The window name may be one of Main, Configuration, Log, Watches, and Visualizations. When "Watches" is given, the window state refers to visibility of the Watches area in the Visualizations window.<br />
<br />
=====MOVE WINDOW <name> <x> <y>, RESIZE WINDOW <name> <width> <height>=====<br />
Moves resp. resizes the specified window with one of the above names.<br />
Window decorations (title bar, frame) are taken into consideration such that the total size of the window matches the given width and height.<br />
<br />
=====ARRANGE WINDOW <name> <rows> <cols> <row> <col> [<rowspan> <colspan>]=====<br />
Arranges the named window in a virtual ''rows'' x ''cols'' grid at grid position ''row, col''.<br />
<br />
Optional ''rowspan'' and ''colspan'' arguments may be given to specify the extension of the window across more than one row or column. <br />
Using a ''rowspan'' of 0 will result in the window assuming its minimum height.<br />
Likewise, a ''colspan'' of 0 will result in the window's minimum width.<br />
<br />
If multiple screens are present, windows are arranged on the screen that contains the Operator window.<br />
<br />
=====SET TITLE <title>=====<br />
Sets the title of the main Operator window.<br />
=====SET BUTTON <idx> <label> <commands>=====<br />
Configures the function button with 1-based index ''idx'' such that it is labelled ''label'' and executes ''commands''.<br />
<br />
=====VISUALIZE WATCH [decimate <n>] [range <min> <max>] <expression1> ...=====<br />
Adds a watch for the given expressions to the operator module's Watches window, and makes the Watches window visible if it is hidden. If the ''decimate'' clause is present, the command will create a watch which will be evaluated only for every ''n''th sample in the state vector. If the ''range'' clause is present, display minimum and maximum will not be adjusted automatically but will be fixed to the values given.<br />
<br />
By default, ''decimate'' has a value of "auto"; this means that there is no decimation of evaluation (i.e., all samples are evaluated) but changes that occur within 1ms will be shortened into their maximum and minimum, and thus reported as only two values.<br />
This has proven to be efficient for avoiding sluggishness from flooding the application with events.<br />
<br />
=====MOVE VISUALIZATON <visID> <x> <y>, RESIZE VISUALIZATION <visID> <width> <height>=====<br />
Moves resp. resizes the specified visualization window.<br />
Window decorations (title bar, frame) are taken into consideration such that the total size of the window matches the given width and height. If unknown, visualization IDs may be obtained from the Operator's ''Window->Visualizations'' menu.<br />
<br />
=====ARRANGE VISUALIZATION <visID> <rows> <cols> <row> <col> [<rowspan> <colspan>]=====<br />
Arranges the named visualization window in a virtual ''rows'' x ''cols'' grid at grid position ''row, col''.<br />
<br />
Optional ''rowspan'' and ''colspan'' arguments may be given to specify the extension of the window across more than one row or column. <br />
Using a ''rowspan'' of 0 will result in the window assuming its minimum height.<br />
Likewise, a ''colspan'' of 0 will result in the window's minimum width.<br />
<br />
If multiple screens are present, windows are arranged on the screen that contains the Operator window.<br />
<br />
=====RECORD VISUALIZATION <visID> [on|off]=====<br />
Registers the named visualization for recording. The visualization name must be the short name as displayed in the ''View->Visualizations'' menu. Switching a visualization recording to "on" is only possible in idle state (because an event for recording frame numbers must be registered in the system). When a visualization is registered for recording, its frames are stored immediately as they arrive at the operator module. Currently, only bitmap visualizations may be recorded.<br />
<br />
Example: Recording the application window<br />
RECORD VISUALIZATION ApplicationWindow on<br />
...<br />
# after parameters have been loaded<br />
Set parameter VisualizeApplicationWindow 1<br />
...<br />
<br />
=====PUT NOTE <note>=====<br />
Adds the given text to the [[User_Reference:Operator_Notes#Taking_Notes_during_recording_in_Operator|notes window]].<br />
If the system is in ''Running'' state, the text will also be added to the current notes file as described under<br />
[[User_Reference:Operator_Notes#Note_storage_and_file_format|"notes file"]].<br />
<br />
=====START TELNET <address>, STOP TELNET <address>=====<br />
Starts or stops a telnet server listening at the given address. The address is in <IP>:<port> format.<br />
<br />
'''IMPORTANT:''' You should not use this command on global internet addresses, as there is no authentication performed.<br />
<br />
=====START WEBSOCKET <address>, STOP WEBSOCKET <address>=====<br />
Starts or stops a websocket server listening at the given address. The address is in <IP>:<port> format.<br />
<br />
'''IMPORTANT:''' You should not use this command on global internet addresses, as there is no authentication performed.<br />
<br />
====Operator-module Commands for Soliciting Input from the User====<br />
<br />
<br />
<br />
=====CHOOSE [INPUT] FILE[S] [OF TYPE <.ext1> [<.ext2> ...]] [STARTING AT <dir>] [WITH PROMPT <message>]=====<br />
Via the Qt graphical user interface, prompt the user to select an existing file (or multiple files, if the keyword FILES is used). Print the resulting file path(s).<br />
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)<br />
<br />
=====CHOOSE [OUTPUT] FILE [OF TYPE <.ext1> [<.ext2> ...]] [STARTING AT <dir>] [WITH PROMPT <message>]=====<br />
Via the Qt graphical user interface, prompt the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists). Print the resulting file path.<br />
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)<br />
<br />
=====CHOOSE DIRECTORY [STARTING AT <dir>] [WITH PROMPT <message>]=====<br />
Via the Qt graphical user interface, prompt the user to specify a directory. Print the resulting directory path.<br />
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)<br />
<br />
=====CUSTOM DIALOG [MESSAGE <msg>] [VAR <varname> <label> {[<options>]} ] [BUTTONS {<buttons>}] ... =====<br />
Via the Qt graphical user interface, prompt the user with a modal dialog that can be flexibly customized.<br />
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)<br />
<br />
===Predefined Variables===<br />
The following variables exist when an Operator script is executed.<br />
Some of these variables are marked with ''local''. This means that they are not environment variables, i.e. they are invisible to child processes that are launched using the SYSTEM or START EXECUTABLE commands, and their values may be different between script invocations. In script code, they are accessed like ordinary variables.<br />
====BCI2000LAUNCHDIR====<br />
The full absolute path to the directory where the Operator module resides. This is also prepended to the PATH environment variable, such that executables from the current BCI2000 installation will have precedence over any other executable with the same name.<br />
<br />
On macOS, this is the path where the Operator module's application bundle resides. In the default configuration, this is the BCI2000 prog directory, both on macOS and on other platforms.<br />
<br />
====BCI2000BINARY====<br />
The full absolute path to the Operator module.<br />
====LogLevel (local)====<br />
Determines the amount of log information written to the Operator log. This variable only affects log messages originating from the current script. May be 2 (display all log messages), 1 (display fewer log messages), or 0 (suppress all log messages). Set to 1 by default. Changes to this local variable are not propagated to any sub-scripts called. ''NOTE:'' Only log messages are controlled by this variable. Error messages originating from a script with 'LogLevel 0' will still be displayed in the Operator log. When 'AbortOnError' is set to 0, you may set 'LogLevel' to -1 in order to display error messages. When 'AbortOnError' is 1 (the default), error messages will always be displayed to indicate the reason for failure.<br />
<br />
====AbortOnError (local)====<br />
Determines if a script is aborted when an error happens, or whether the error is silently ignored. Set to 1 by default (script is aborted on error). Changes to this local variable are not propagated to any sub-scripts called.<br />
<br />
====Result (local)====<br />
The result of the last executed scripting command. When a script is executed by calling EXECUTE SCRIPT, the script's last executed command determines the result of the EXECUTE SCRIPT command itself.<br />
<br />
====0, 1, ... 9 (local)====<br />
When a script file is being executed, these variables contain the arguments of the EXECUTE SCRIPT command.<br />
''$0'' resolves to the full absolute path to the current script file. Within scripts, all of the ''0-9'' variables are defined, and those that do not have a matching argument are empty.<br />
<br />
====YYYYMMDD (local)====<br />
Local time at execution of the current script, in YYYYMMDD format. In interactive sessions, reflects the time when the session was initiated.<br />
<br />
====HHMMSS (local)====<br />
Local time at execution of the current script, in HHMMSS format. In interactive sessions, reflects the time when the session was initiated.<br />
<br />
===Abbreviated commands and synonyms===<br />
To minimize the need of consulting documentation, as well as for backward compatibility, a number of '''synonymous commands''' are provided. E.g., states may be added by INSERT STATE as well as ADD STATE, and the existence of a file may be queried by IS FILE as well as EXISTS FILE. For an overview over all allowed forms of commands, use the HELP ALL command.<br />
<br />
To simplify operation in interactive sessions, '''abbreviated commands''' exist. Currently, these are:<br />
:'''cd''' for CHANGE DIRECTORY,<br />
:'''pwd''' and '''cd''' without argument for CURRENT DIRECTORY,<br />
:'''ls''' and '''dir''' for LIST DIRECTORY,<br />
:'''mkdir''' for MAKE DIRECTORY,<br />
:'''echo''' for WRITE LINE,<br />
:'''realpath''' for REAL PATH,<br />
:'''dirname''' for EXTRACT DIRECTORY,<br />
:'''basename''' for EXTRACT FILE BASE.<br />
<br />
===Handlers===<br />
In the Operator GUI, script execution is bound to a number of Operator Events (not to be confused with Event states, above) that occur during various [[Technical Reference:States of Operation|stages of BCI2000 system operation]]:<br />
====OnConnect====<br />
This handler runs at startup, as soon as all modules are connected to the operator module.<br />
====OnSetConfig====<br />
This handler runs each time a set of parameters is applied to the system. This happens when the user clicks the ''SetConfig'' button. Execution of the ''SETCONFIG'' command also runs this handler.<br />
<br />
====OnStart, OnResume====<br />
These handlers are triggered by the ''Start''/''Resume'' button. One of these handlers is also triggered when the ''Running'' state variable is set to 1 from a script. Whether ''OnStart'' or ''OnResume'' is triggered depends on whether the system has been running before with the current set of parameters.<br />
<br />
====OnStartRun====<br />
Similarly to OnStart and OnResume, this handler is triggered by the ''Start''/''Resume'' button. Unlike other event handlers, OnStartRun has an argument, which is the current run file.<br />
<br />
OnStart or OnResume are triggered immediately after ''Start''/''Resume'' has been pressed, whereas OnStartRun is deferred until modules have confirmed to be in Running state. This makes sure that the OnStartRun event handler receives a valid run file name.<br />
<br />
====OnNextFilePart====<br />
This handler is triggered during a run, whenever the ''FilePart'' event state is incremented. It allows scripts to know when a new<br />
partial file has begun. For further information, see the [[User_Reference:BCI2000FileWriter#FileSplittingCondition|FileSplittingCondition]] parameter.<br />
<br />
====OnSuspend/OnStopRun====<br />
Triggered when the system goes from running into suspended mode. This happens whenever the ''Running'' state variable changes from 1 to 0. This may happen when the user clicks ''Suspend'', when the application module switches the system into suspended mode, or when a script sets the ''Running'' state variable to 0.<br />
<br />
====OnShutdown====<br />
Triggered when the operator module shuts down connections, and switches into idle state.<br />
<br />
====OnExit====<br />
Triggered when the operator module exits. Execution of the QUIT command also triggers this handler. This handler is not available to the SET SCRIPT and CLEAR SCRIPT commands. Also, when both an OnShutdown and an OnExit script are defined, the OnExit script may be executed before the OnShutdown script.<br />
<br />
====Associating Scripts with Operator Events====<br />
In the operator module's preferences dialog, script commands may be entered for each of the handlers listed above.<br />
Scripts may be specified as paths to script files, or as immediate one-line scripts.<br />
Entries that start with a minus sign (-) are treated as one-line scripts, which may contain multiple commands separated with semicolons.<br />
<br />
Scripts may also be specified from the command line used to start up the operator module. There, handler names are followed with the content of the respective preference entry, enclosed in double quotes ("...").<br />
<br />
Finally, scripts may be specified using the SET SCRIPT command of the scripting language itself.<br />
<br />
===Examples===<br />
====Making use of the Operator module's Function Buttons====<br />
To add a state variable called "Artifact", and to set it using the operator's function buttons, do this:<br />
*Enter the following line under "After All Modules Connected" in the operator's preferences dialog (note the minus sign):<br />
-ADD STATE Artifact 1 0<br />
*Under "Function Buttons", enter "Set Artifact" as the name of button 1, and as its command, enter (note there is no minus sign):<br />
SET STATE Artifact 1<br />
*Enter "Clear Artifact" as the name of button 2, and as its command, enter<br />
SET STATE Artifact 0<br />
<br />
====A fully automated BCI2000 session====<br />
<pre><br />
Echo Please enter a subject ID:<br />
Set SubjectID ${Read line}<br />
<br />
Startup system<br />
Start executable SignalGenerator<br />
Start executable SpectralSignalProcessing<br />
Start executable CursorTask<br />
Wait for Connected<br />
Load parameterfile "../parms/examples/CursorTask_SignalGenerator.prm"<br />
For i in 1 2 3<br />
Load parameterfile "../parms/MyExperiment/Session$i.prm"<br />
Set parameter SubjectName $SubjectID<br />
Set parameter SubjectSession $i<br />
Set config<br />
Wait for Resting<br />
Start<br />
Wait for Suspended 1000<br />
End<br />
</pre><br />
<br />
====Automating BCI2000 by Operator command line arguments====<br />
The following example shows how to specify script commands from the command line.<br />
It fully automates BCI2000 operation by loading a parameter file, applying parameters, starting the system once the parameters are applied, and quitting the system once the run is over. For better readability, the example is broken across lines, using the ^ DOS line continuation character.<br />
<br />
operator.exe --OnConnect "-LOAD PARAMETERFILE ../parms/examples/CursorTask_SignalGenerator.prm; SETCONFIG" ^<br />
--OnSetConfig "-SET STATE Running 1" ^<br />
--OnSuspend "-QUIT"<br />
<br />
====Automatically arranging windows in a 4x2 grid====<br />
The following example arranges Source and Roundtrip visualizations on the left side of the screen.<br />
On the right side, a large area is dedicated to the Operator's log window, and the Operator's main window sits at the bottom right.<br />
<br />
Arrange Visualization SRCD 4 2 1 1 2 1<br />
Arrange Visualization RNDT 4 2 3 1<br />
Arrange Window Main 4 2 4 2<br />
Arrange Window Log 4 2 1 2 3 1<br />
<br />
[[File:Operator_Arrangement.PNG|center|640px|border]]<br />
<br />
==See also==<br />
[[User Reference:Module Command Line Options]], [[User Reference:Operator Module]], [[User Reference:BCI2000Shell]], [[Technical Reference:States of Operation]]<br />
<br />
[[Category:User Interface]]</div>Jhill