User Reference:Custom GUI Commands

BCI2000's Operator Module Scripting capabilities include the ability to prompt the user for specific pieces of information via modal Qt dialogs.

The expanded form of this documentation is still under construction. For now, here is the short summary:

CHOOSE [INPUT] FILE[S] [OF TYPE <.ext1> [<.ext2> ...]] [STARTING AT <dir>] [WITH PROMPT <message>]

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

CHOOSE [OUTPUT] FILE [OF TYPE <.ext1> [<.ext2> ...]] [STARTING AT <dir>] [WITH PROMPT <message>]

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.

CHOOSE DIRECTORY [STARTING AT <dir>] [WITH PROMPT <message>]

Via the Qt graphical user interface, prompt the user to specify a directory. Print the resulting directory path.

CUSTOM DIALOG [MESSAGE <msg>] [VAR <varname> <label> {[<options>]} ] [BUTTONS {<buttons>}] ...

Via the Qt graphical user interface, prompt the user with a modal dialog that can be flexibly customized.

CUSTOM DIALOG can be followed by as many clauses as you like. The main types of clause are MESSAGE and VAR clauses, which are rendered from top to bottom in the dialog, in the order you provide.

MESSAGE <msg> (e.g. MESSAGE "Hello there!")

The message is rendered as text, word-wrapped to the width of the dialog window. MESSAGE "" can be used to create blank vertical space. Any message that consists only of dashes (e.g. MESSAGE ---) will be turned into a horizontal rule.

VAR <variableName> <visibleLabel> {} [DEFAULT <defaultText>] [MINIMUM <nChars>]

This creates a text field that the user can fill in. If you supply a DEFAULT subclause, the specified default text is pre-filled. If you specify a MINIMUM number of characters, the dialog buttons (except for the designated ESCAPE 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 ESCAPE button) then the environment variable designated by <variableName> will be set to the contents of the text field. For example:

custom dialog var subjectName "Subject Name:" {} default test minimum 1

VAR <variableName> <visibleLabel> {<opt1>|<opt2>|...} [DEFAULT <defaultOption>] [MINIMUM <nChars>]

This is almost the same as the text-field VAR example above, except that the braces are not empty: the |-delimited option labels inside the braces are then rendered as a drop-down menu with the specified limited set of options. The DEFAULT subclause, if provided, determines which option is pre-selected (if it is omitted, or the <defaultOption> does not match any of the options, then the first option is pre-selected). The MINIMUM subclause can be used in conjunction with an empty first/default option, to force the user to make an explicit selection. For example:

custom dialog var runType "Run Type:" {|Calibration|Free Spelling} minimum 1

BUTTONS {<button1>|<button2>|...} [DEFAULT <defaultButton>] [ESCAPE <escapeButton>]

This explicitly overrides the sequence of buttons at the bottom of the dialog. The button label designated as DEFAULT, 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 ESCAPE, if any, is the one that is bound to the escape keystroke and is equivalent to closing the dialog without making a selection (the CUSTOM DIALOG 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:

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

BUTTONS {Ok} DEFAULT Ok                      # in cases with no VAR clauses, where the dialog is just a message to the user