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.

CHOOSE ...

The CHOOSE family of commands prompt the user to specify file or directory paths, via the Qt graphical user interface.

CHOOSE INPUT FILE (or equivalently CHOOSE FILE, or CHOOSE INPUT)

Prompts the user to select a single existing file, and prints the resulting file path.

CHOOSE INPUT FILES (or equivalentlyCHOOSE FILES)

Prompts the user to select one or more existing files, and prints the resulting file paths one per line (FOR ... IN ... can iterate over these).

CHOOSE OUTPUT FILE (or equivalentlyCHOOSE OUTPUT)

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.

CHOOSE DIRECTORY

Prompts the user to specify a directory, and prints the resulting directory path.

If the user cancels the dialog, the commands print nothing.

The commands may be followed by one or more of the following optional clauses (they must appear in this order):

[OF] TYPE[S] <.ext1> [<.ext2> ...]

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 CHOOSE DIRECTORY. Instead of a file extension (starting with a dot) you can alternatively specify a glob pattern (containing a star). You can include * (or equivalently *.*) in the list if you want to give the user the option of overriding the limitation.

[STARTING] AT <dir> (equivalently you can say IN or FROM if it reads better)

This specifies where the dialog's file-system navigation should start (by default, it will start in the current working directory).

[WITH] PROMPT <msg>

This specifies the text prompt at the top of the dialog.

Examples:

choose file of type .dat from ../data/samplefiles with prompt "Choose a data file for playback:"

choose output file of type .prm in ../parms with prompt "Save parameters as..."

choose directory starting at ../data with prompt "Select a subject directory:"

CUSTOM DIALOG ...

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

The CUSTOM DIALOG command 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. Possible clauses are:

MESSAGE <msg>

Each 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. Simplest example:

custom dialog message "Hello world!"

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, as in the following example (note the leading | character inside the braces):

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, 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 ESCAPE, 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 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. In dialogs without VAR clauses (where you are simply displaying messages to the user), the BUTTONS {Ok} DEFAULT Ok configuration is assumed. In dialogs with one or more VAR clauses (where you are asking the user for information), the BUTTONS {cancel|Ok} DEFAULT Ok ESCAPE cancel configuration is assumed.

TITLE <text>

This overrides the default dialog title "BCI2000".

SPACING <N>

Supply an integer value N to specify the vertical spacing between successive MESSAGE and/or VAR elements.

WIDTH <N>

Supply an integer value N to specify the minimum width of the dialog in pixels.

HEIGHT <N>

Supply an integer value N to specify the minimum height of the dialog in pixels.

LEFT <N>

Supply an integer value N to specify the horizontal coordinate of the dialog's left edge, in pixels.

TOP <N>

Supply an integer value N to specify the vertical coordinate of the dialog's top edge, in pixels.

Integrated CUSTOM DIALOG example

The following partial listing illustrates one way CUSTOM DIALOG might be used to implement a simplified launcher GUI, for a hypothetical auditory BCI experiment.

# [initialize system]
# [start up modules]
# [load baseline parameters for this BCI]
# [optionally, you could pre-initialize environment variables subjectName, runType and stimulusCondition]


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 stimulusCondition "Stimulus Condition:" {SlowStimuli.prm|FastStimuli.prm} default $stimulusCondition 
        message "NB: each condition should be calibrated separately." 
        buttons {Quit|Launch} default Launch escape Quit
}

if [ $launcherAction == "" ]
    quit
end

if [ $runType == Calibration ]
    load parameterfile ../parms/calib.prm       # let's assume you have created this
else
    load parameterfile ../parms/free.prm        # and this
end
load parameterfile ../parms/$stimulusCondition  # and these
set parameter SubjectName $subjectName
setconfig
show window   # unless you have some other remote-control mechanism for suspending/resuming runs
set state Running 1

The resulting dialog looks like this: