Write Python scripts for BALLView
The easiest way to access objects in BALLView is to use the interface to the ModularWidgets. Every major widget in BALLView, like the Scene or the MolecularControl is such a ModularWidget. To get the instance of a ModularWidget in a running BALLView session, call e.g.
The MainControl manages almost all loaded objects, like Molecules or Representations. The documentation of the BALL library gives detailed information on the syntax of this class. Examples for Python script for usage with BALLView can be found in the folder BALL/source/EXAMPLES/PYTHON. See also below for an other code example.
Users can start scripts, which are stored as external files, either by calling 'runScript("filename")'in the Python widget or by using the menu entry.
Caveat: Not all methods, which are defined in the C++ library are also exported to the Python interface.
If a method, which you want to use does not seem to work, have a look at the *.sip files in
BALL/source/PYTHON/EXTENSIONS to make sure, this method is exported.
Completion and context sensitive help
To ease and accelerate the development with Python we implemented a command completion, such that a combobox pops up with all possible completions. This can e.g. be used to show all members of a BALL class. To use this feature in the "Instant Mode", press the right cursor key at the end of the edit line. In the "Scripting Mode", press the right cursor key together with the Shift key:
To get context sensitive help for the current line, write your line of code and press "Enter" (from the numlock block) or "Shift-F1" after the name of the method (like above). This pops up a window with the BALL documentation for the class and member.
Setup a Python startup script
BALLView loads a standard Python script, every time it is started. This script is located in BALL/data/startup.py and defines some shortcuts for obtaining objects and widgets at runtime. Furthermore a user can load an additional Python script at startup. In this script the user can define variables and methods to further simplify usage of the Python interface. The location of the additional startup script is set in the Preferences:
An example for a startup script:
BALLView can bind any Python command to an hotkey for the F-keys. By using the Shift-modifier, BALLView can have up to 24 different hotkeys additional to the standard hotkeys for menu entries. This enables the user to accelerate repetitive tasks dramatically. Furthermore all Python Hotkeys are show as entries in the "User" menu. The standard startup Python Scripts defines many different shortcuts, which can be mapped to any F-key. Thereby a user can e.g. remove all water molecules in the loaded Systems with one key press. Of course, it is also possible to start methods defined in the user startup script or external Python scripts with a hotkey: Just add an hotkey entry with runScript("filename").