Document Types
Document version: 1.0
Author(s): Sven Gijsen
Date: July 2015
Introduction
Depending of the currently opened active document type (which is automatically resolved by the file extension) BrainStim can adapt its file handling and user interface to optimize the view and editing capabilities for that document type. This feature makes BrainStim a very flexible editor for various document types. These pre-registered document types and defined file handling and user interface are automatically loaded at startup and can even be custom implemented by a Plugin. Each change manually made to the user interface is saved for each document type separately, making it possible for the user to do some small layout changes that are automatically saved for the next session where you open a certain document of that type again.
Main document types
BrainStim implements some standard document types, these are:
| Document type(extension) | Description |
|---|---|
| QtScript (*.qs) |
QtScript
code (which is based on the ECMAScript standard (like
JavaScript) with
a more few extensions). If this document executed (F5 key) then internal Script Engine from BrainStim will interpret and run the documents content. |
The ExperimentManager plugin implements the following custom document types:
| Document type(extension) | Description |
|---|---|
| QML (*.qml) |
QML
code (a user interface markup language. It is a
JavaScript-based, declarative language for designing user
interface-centric applications). If this document executed (F5 key) then the QML engine from the ExperimentManager plugin will interpret and run the documents content. |
| Experiment (*.exml) |
XML-based
code that specifies an experiment structure and flow,
read this document to learn more about this document type. If this document executed (F5 key) then the Experiment engine from the ExperimentManager plugin will interpret and run the documents content. |
Example
Let's examine some of the above document types:
- Start BrainStim.
- Open the (QtScript) file Functions.qs that is located in the Main Program Directory subfolder \Examples\BrainStim\QtScript Functions\. The script code of this file is explained in this document in more detail.
- Examine the QtScript file and validate that:
- different text formatting is automatically applied and automatically updated for the coding syntax of this type of document (*.qs). You can edit some formatted text and see how the text formatting is automatically updated.
- automatic code hints and completion are enabled. You can test this by placing the cursor at the end of the document and then begin start typing a known (or used word) like 'sayHello', and see what happens. - Notice that, now we have opened a QtScript file, that the green
Execute
button in the ToolBar (also the
Document > Execute MenuBar item) is enabled
and therefore its possible for
us to execute the documents content by the internal QtScript engine. Let's
try that, press the Execute button and notice how the BrainStim
'default' OutputLog Tab
changes due to the executed script. - Close the document (CTRL + Shift + c) and notice how the Execute button is automatically disabled if no executable document is activated.
-
Open the (QML) file Helloworld.qml that is located in the
Main Program Directory subfolder
\Examples\BrainStim\QML Basics\. The script code of this file is explained in
this document in more
detail.
Notice that again automatic text formatting and code hints/completion is in use. Because this document is of a different type and has a different syntax the rules applied for the formatting and code hints/completion is not the same as in the above example. The rules for this are defined in small (*.api) files that are stored in the Main Program Directory subfolder named Apis.
The green Execute
button in the ToolBar is again enabled, allowing us to execute the
document. This time this is handled by a QML engine which is
implemented inside the
ExperimentManager plugin. Important!
Remember that after executing this type of document you can close the full-screen
window that will popup again by pressing CTRL + a (abort)
key combination.
Let's try that, press the Execute button and notice what happens, when you're ready you can close/abort the window again by pressing CTRL + a (abort) key combination. - Open the (EXML) file PolarAngle.exml that is located in the Main Program Directory subfolder \Examples\BrainStim\Retinotopy Basics\. This document is explained in this document in more detail.
- Notice that the user interface completely changed after opening this document type. Activate (by using the menu Window > Helloworld.qml), or re-open again the previous (QML) file Helloworld.qml that is located in the Main Program Directory subfolder \Examples\BrainStim\QML Basics\. Notice how the user interface changes back to suit that of the QML file type.
- Activate (CTRL + TAB) the PolarAngle.exml file again
and notice that the green
Execute button in the ToolBar (also the
Document > Execute MenuBar item) stays
enabled and therefore its again possible for us to execute this
document type. The document execution is handled by the Experiment
engine which is implemented inside the
ExperimentManager plugin. Important!
Remember that after executing this type of document you can close the full-screen
window that will popup again by pressing CTRL + a (abort)
key combination.
Let's try
that, press the Execute button and notice what
happens. After a full-screen popup window appears you can press the
ALT key to proceed and see what happens.
If you like then you can close/abort the window again by pressing CTRL + a (abort) key combination.
Aside the new dockable widgets that appeared for supporting the editing of this type of document you might also have noticed the appearance of the custom menu entry View > Switch to plain text view menu entry. If you click this menu entry then the document type is reloaded but then viewed as plain text making it also possible to edit this document using the internal code editor. The underlying syntax of the EXML file is XML-based code and therefore can also be edited inside a code editor. You can revert to the extended visual editor by reloading (File > Reload) the document again. - Close all open documents (CTRL + Shift + F4).
Additional supported document types
BrainStim can also be used for the editing of some additional document types. For most of them the text formatting and code hints/completion is implemented for the syntax used for that document type. Currently these document types are supported:
| Document type(extension) | Handling |
|---|---|
| Unknown or Text Files (*.*, *.txt) | All files are treated as standard text files when they have an unknown file extension. These files can be edited in the internal code editor of BrainStim but features like automatic text formatting and code completion/hints are disabled. |
| C(++) Files (*.c, *.cpp, *.h) Javascript Files (*.js) Perl Files (*.py) Python Files (*.py) XML Files (*.xml) HTML Files (*.html) |
These files can be edited in the internal code editor of BrainStim with features like automatic text formatting and code completion/hints enabled. |
| Scalable Vector Graphics (*.svg, *.gz, *.svgz) | These files can be edited in the internal code editor of BrainStim with features like automatic text formatting and code completion/hints enabled. Furthermore you can execute these files, see the (SVG) file Helloworld.svg that is located in the Main Program Directory subfolder \Examples\BrainStim\SVG Examples\. |