BrainVoyager v23.0
The BV Notebook User Interface
The user interface (UI) of the BV Notebook main window allows to enter and run code and author notebook documents interactively. The Menu and Toolbar at the top of the main window are used to trigger general actions. Hovering over a toolbar button will reveal its name that will be used to describe triggered actions in subsequent sections. The Notebook Area below the toolbar contains the cells defining the notebook document. Actions in the menu or toolbar operating on a cell are applied to the currently active cell (see below) that is usually highlighted with a blue frame.
Navigating the Cell Sequence
At a general level, a BV notebook document consists of a sequence of cells containing Python code, Markdown text, images and interactive viewers. Code or text is entered in the currently active cell. A cell can be made the active cell simply by clicking on its contents. Another way to change the active cell is by navigating through the cell sequence upwards or downwards by pressing the CURSOR UP
and DOWN
keys while holding down the CTRL
key on Windows and Linux or the CMD
key on macOS; this will make the previous or next cell the new current cell as indicated by the blue highlight frame.
Document and File Actions
The following actions operate on notebook documents and files:
- The File > New menu item or the Create New Notebook toolbar button can be used to create a new notebook. The new notebook will be named 'untitled.bvnb' and it will contain one empty Python code cell.
- The File > Open menu item or the Open Notebook From Disk toolbar button can be used to open an existing notebook from disk. Depending on the length of the notebook, the loading and cell visualization process may last a few seconds.
- The File > Save menu item or the Save Current Notebook To Disk toolbar button save the current document to disk, i.e. after some important changes have been made. The program also asks to save the current document when the BV Notebook main window is closed.
- The File > Save As menu item is used to save the current notebook under a different name.
- The File > Reveal in Explorer (Windows) or File > Reveal in Finder (macOS) menu item locates the file of the current notebook on disk.
- Hovering over the File > Open Recent menu item opens a list of up to 10 recently opened files; clicking one of the files will open it; if the current notebook has modifications that have not been saved to disk, a dialog will pop-up to allow saving changes before the current document is closed.
Rearranging Order of Cells
The following editing commands can be used to change the position of cells in the document:
- The Edit > Cut Current Cell menu item or the Cut Current Cell toolbar button can be used to cut the current cell out of the sequence of cells; the cut out cell will be available for a paste operation.
- The Edit > Copy Current Cell menu item or the Copy Current Cell toolbar button can be used to copy the current cell into a buffer without changing the sequence of cells; the copied cell will be available for a paste operation.
- The Edit > Paste Cell Above menu item can be used to paste the last cut or copied cell above the currently active cell.
- The Edit > Paste Cell Below menu item or the Paste Cell Below toolbar button can bue used to paste the last cut or copied cell below the currently active cell.
- The Edit > Move Current Cell Down menu item or the Move Current Cell Down toolbar button moves the current cell below the next cell in the cells list.
- The Edit > Move Current Cell Up menu item or the Move Current Cell Up toolbar button moves the current cell above the cell coming before the current cell in the cells list.
Adding and Removing Cells
The following actions can be used to add new cells to the notebook and to clean the output of code cells:
- The Cells > Insert Code Cell Above menu item inserts a new empty Python code cell above the current cell.
- The Cells > Insert Code Cell Below menu item inserts a new empty Python code cell below the current cell. This can be achieved more easily by clicking the + button in the Toolbar (or the Python Cell entry in the pop-up window that can be opened by pressing the down-pointing triangle on the right side of the + button).
- The Cells > Clear Current Cell Outputs menu item clears any output (text, images, viewers) in the current code cell. If the current cell is not a code cell, nothing happens.
- The Cells > Clear All Cells Outputs menu item clears any output (text, images, viewers) in all code cells of the notebook. It also resets the evaluation counter to zero, which might be useful to produce a clear sequential order by rerunning (all) cells; the first cell evaluated after this action will get the input 1 ('In [1]') counter, the second evaluated cell the 'In [2]' counter and so on.
- The Cells > Insert Markdown Cell Above menu item inserts an empty Markdown text cell above the current cell.
- The Cells > Insert Markdown Cell Below menu item inserts an empty Markdown text cell below the current cell. This action can also be triggered by clicking the Markdown Cell entry in the pop-up window that can be opened by clicking the down-pointing triangle on the right side of the + button in the Toolbar .
- The Cells > Insert Image Cell Above menu item inserts an image cell above the current cell; the image cell will show a small placeholder image that can be clicked to replace it with an image on disk.
- The Cells > Insert Image Cell Below menu item inserts an image cell below the current cell; the image cell will show a small placeholder image that can be clicked to replace it with an image on disk. This action can also be triggered by clicking the Image Cell entry in the pop-up window that can be opened by clicking the down-pointing triangle on the right side of the + button in the Toolbar .
- The Cells > Insert Animation Cell Above menu item inserts an animation cell above the current cell; the animation cell will show a small placeholder animation that can be clicked to replace it with an animation on disk.
- The Cells > Insert Animation Cell Below menu item inserts an animation cell below the current cell; the animation cell will show a small placeholder animation that can be clicked to replace it with an animation on disk. This action can also be triggered by clicking the Animation Cell entry in the pop-up window that can be opened by clicking the down-pointing triangle on the right side of the + button in the Toolbar .
- The Cells > Remove Current Cell menu item can be used to remove the current cell from the notebook.
Display Settings
The following actions can be used to change the notebook display and behavior:
- The Cells > Max Code Cell Output Lines allows to limit the maximum number of text lines in the output section of code cells. The default value is 20. If text output does not fit in the specified number of lines, a vertical scrollbar is automatically added to the output section allowing to inspect the full content.
- The Options > Show/Hide Cell Run Buttons can be used to toggle visibility of the Cell Run buttons that are usually shown on the left upper corner of Python code cells. Not showing these icons may lead to nicer visualization of (finalized) notebooks.
- The Options > Hide Current Cell Selection removes the blue marker indicating the current cell. This may lead to nicer looking (finalized) notebooks or for screenshots, but this option is acting only temporarily: as soon as a cell is clicked, the blue marker is shown again.
- The Options > Render All Markdown Cells switches all Markdown cells from editing to rendered (display) mode (if needed). For individual Markdown cells, this switch can also be performed by clicking the View buton in the left upper corner of the cell (if shown, see below).
- The Options > Show/Hide Scrollbar menu item can be used to toggle visibility of the srollbar on the right side of the BV Notebook main window. Navigation is still possilbe via keyboard commands (see 'Navigating the Cell Sequence' section), the mouse scrolling wheel or via mouse/finger swiping.
- Clicking the Options > Image Display Settings menu item invokes the Image Settings dialog that can be used to set a global scale factor for displayed images and animations in the notebook.
- The Options > Log BV GUI Actions as Code menu item or the Log BV GUI Actions As Code toolbar toggle button can be used to turn on or off the automatic addition of code for (basic) routines called in the user interface of BrainVoyager.
GUI Adjustments
The following actions allow changing the user interface and operation of the BV Notebook window:
- The View > Show Toolbar toggle menu item can be used to show or hide the Toolbar below the menu bar.
- The View > Enable Type Completion toggle menu item can be used to turn off or on the display of the completion list that is usually shown and updated while typing names of object functions or properties; if a single completed name is shown, it can be inserted by pressing the
TAB
button; if a list is shown, the desired completed name can be selected using the up/down cursor keys followed byTab
orReturn
. While type completion is a useful feature, it might respond slow on some system and this option allows to turn it off if issues are encountered. - The View > Show API Help Panel toggle menu item can be used to show or hide the API Help Panel . If shown, it appears at the bottom of the main window as default. The panel can be, however, dragged out from its docked position and moved as a floating panel to a desired position. The API Help Panel presents a short documentation of BrainVoyager-specific functions including parameters when hovering over a (known) command or when tab-completing a (known) command.
- The Auto-Show API Help Panel on Hover toggle menu item can be used to turn on the automatic diaplay mode of the API Help Panel (see previous action description). If auto-show mode is on (default), the API Help Panel is shown even when it is currently hidden in case that one hovers over a (known) command or when tab-completing a (known) BrainVoyager API command.
Copyright © 2023 Rainer Goebel. All rights reserved.