BrainVoyager Python Developer Guide 0.9

Introduction

Python support in BrainVoyager is powerful since it allows to call BrainVoyager commands and to incorporate custom functionality. Developed scrips and plugins can be further enrichted by flexible user interfaces such as dialogs. Since almost the full Qt library is accessible from Python, user interfaces can be easily developed using Python code. It is also possible to build GUI widgets in Qt Designer (or Qt Creator) and to load prepared .ui files to create dialogs. Since it is easy to code user interfaces directly in Python code, this approach is described in this guide.

In order to create and use Qt GUI objects, a Python script simply needs to include the line:

from PythonQt.QtGui import *

After this import statement, GUI elements can be created easily; to create for example a push button, the statement

push_btn =  QPushButton()

can be used. It is also easy to respond to actions on user interface elements such as when a button is clicked since the signal "clicked()" is emitted in this case. In order to call a defined function "changeButtonText()" every time the button "push" is clicked, the following code can be used:

push_btn.connect('clicked(bool)', changeButtonText)

In order to arrange GUI elements in a dialog, they need to be placed in layouts. such as a vertical box layout. It is also noteworthy that GUI elements ("widgets") have a hierarchical relationship, e.g. a group box can be a child of a dialog and can itself have children such as buttons. In order to help getting started with these user interface concepts, simple GUI example scripts are placed in the "Documents/PythonScripts" folder after installation of BrainVoyager 20 (or later), including:

example_gui1.py: A simple script creating a dialog with 2 push buttons and a check box inside a vertical layout.
example_gui2.py: Same as above but shows how the push button calls a function when clicked.
example_gui3.py: Based on the scripts above but encapsulating the creation of a dialog in a function as usually done in production code. The script also shows how to find GUI elements that are "children" of other GUI elements, e.g. how to find a button with a specific name inside a dialog.

The Qt tools provide more functionality than GUI creation. In order to import all available modules, the import statement

import PythonQt.Qt as qt

can be used. The "as qt" part makes objects and functions available under the namespace "qt", i.e. to create a button one would write

qt.push_btn = QPushButton()

This has the advantage that names of the Qt library are kept separate from classes and functions defined in the script and in other imported libraries.