VIDA provides an Extension facility to allow users to modify and extend the user interface and general functionality of the program using Python scripting. VIDA extensions can expose functionality of all the OpenEye Toolkits (with appropriate licenses) or third party applications, and can also be used to customize VIDA’s user experience. They provide a convenient way to carry out regular tasks, streamline corporate workflows, and connect VIDA to other systems. A simple example might be the ability to search a corporate database by corporate compound ID and load that molecule into VIDA.
An individual extension is implemented as a Python module which, once installed, is imported into VIDA at startup. Extensions can be added, removed, updated, and/or disabled from the Extension Manager.
A number of example extensions are available in the VIDA distribution for use as-is or as starting points for writing custom extensions (Python source code for these is included). The provided extensions are:
Although these extensions are distributed with VIDA, you will need to install them with the Extension Manager before using them.
The Extension Manager is accessed under Edit > Extensions, and provides a way to add, activate, and remove extensions. Its use is illustrated here for the example extensions that ship with VIDA.
To “subscribe” to the set of example extensions, open the Extension Manager, and click on the Manage Subscriptions... button to open the Manage Subscriptions dialog, then click the folder icon to browse to the directory where the example extensions are located. This will be under the OpenEye installation directory, in the subdirectory examples/vida/[version]/extensions.
There is a file in this directory named examples.pyxs. This type of file is called a subscription, and simply contains a list of URLs pointing to available extensions. Select this file, then click the Open button to install all of the subscription’s extensions. The list of extensions in the subscription will be shown in the Manage Subscriptions dialog. You can disable individual extensions using the checkboxes that appear beside each extension name.
Once a subscription has been added, an entry for each available extension will be displayed. Every extension has a name and a version (to enable updates), as well as a brief description and a list of any other required OpenEye toolkits for the extension to run. Additionally, each extension appears with four buttons: Info, Refresh, Delete, and Enable.
All of the example extensions, once added, will appear in the Extensions menu in VIDA’s main window, although custom extensions can be made to show up in other menus, as buttons in toolbars, or as other user interface elements.
The Installed Extensions list can be seen in Figure: Installed Extensions. It provides the user with the ability to view which extensions are installed as well as to update, uninstall, or disable the extension.
Clicking on the About button for an extension will display more detailed information about the extension than is seen in this section. Clicking on the Update button will cause VIDA to check for an updated version of the extension and if found, install it. Clicking on the Delete button will cause the extension to be uninstalled when VIDA exits. Clicking on the Disable button will prevent this extension from being imported the next time VIDA is run. A disabled extension will still be listed in the Installed Extensions section and can be reenabled by clicking on the Enable button.
VIDA checks for extension updates at startup and will install the updates directly if found. Extensions can also be manually updated using the Update buttons in the Installed Extensions list.
The Manage Subscriptions... button opens a dialog with a list of your current subscriptions. In this dialog you can add or remove a subscription. Removing a subscription will uninstall all of its extensions. You can also renew a subscription, which will update all of its extensions at once. In the Existing Subscriptions list, you can enable or disable individual extensions using the checkboxes next to the extension names.
Creating an extension for VIDA is very easy. At its simplest level, a VIDA extension is simply a directory containing an __init__.py file and any associated data files or additional scripts. Once this directory is installed, the Python interpreter will import this extension every time the application starts. The process of importing the extension will cause all the code in the __init__.py file to be run.
Using the OEVidaExtension base class can simplify the creation of an extension script. When an extension is derived from OEVidaExtension, the following are automatically handled for you:
The basic steps for creating an extension using OEVidaExtension are:
The following script illustrates basic use of the OEVidaExtension class:
from openeye.vidaExtension import * class ExampleExtension(OEVidaExtension): def InitializeUI(self): # Your subclass must have an InitializeUI() function. # This will be called when the extension is loaded, and should # perform one-time initialization of the user interface, including # connecting any Qt signals and slots. ui = self.ui QObject.connect(ui.myPushButton, SIGNAL("clicked()"), self.DoSomethingInteresting) def DoSomethingInteresting(self): PromptMessage("Hello World") # Create the extension. It will automatically be added to the Extensions menu, # and will get a dockable window if a .ui file was provided. myExtension = ExampleExtension(__file__)
The constructor for OEVidaExtension accepts the following arguments:
The constructor will create two member variables that may be useful:
A class derived from OEVidaExtension must implement a method called InitializeUI(), which performs one-time initialization of the class. This method is also responsible for connecting the Qt widgets in the user interface to the methods in your class.
Some extensions won’t need a .ui file (for example, a menu item that performs an action directly). In such a case, be sure to provide a command argument to the constructor, since the default menu action is to display the extension’s (in this case nonexistent) window.
The OEVidaExtension class provides several methods for managing preferences for extensions. This allows extensions to remember values from one VIDA session to the next. These preferences are stored as key-value pairs, and are preserved in state (.oes) files so that extensions can be set to a particular starting point when a state file is loaded. Preferences can be private to an individual extension, or can be “shared” among all extensions. The methods for managing preferences are:
The OEVidaExtension class provides two methods to allow extensions to be notified when VIDA is finished starting and when it is about to close. The default implementations of these methods do nothing, but you can reimplement them in derived classes to perform actions on startup and shutdown. These methods are:
Extensions are distributed as directory archives (e.g. tar or zip files) coupled with a meta-file containing detailed information about the extension. The meta-file is a simple plain text file named with a .pyx file extension. This file is intended to provide all the associated details about the extension in an easily accessible way. The data contained in the file includes:
Listing 1: A simple example of an extension meta-file (.pyx)
Author: OpenEye Scientific Software, Inc. Title: Example Extension Description: Simple extension to highlight how easy extensions are Version: 1.0.0 Package Name: example Required App: vida 4.3.0 Required Toolkits: OEChem TK Archive URL: http://www.eyesopen.com/vida/extensions/example.tar.gz Extension URL: http://www.eyesopen.com/vida/extensions/example.pyx Load Order: 1
When distributing multiple independent extensions it may be useful to organize them together into groups called Extension Sources or subscriptions. VIDA may subscribe to an Extension Source to get a list of available extensions for installation. The Extension Source itself (as described in Add Extensions) is a simple plain text file named with a .pyxs file extension which contains a title followed by a list of URLs to a collection of extension meta-files. These URLs can be simple file names, in which case VIDA will assume these reside in the same location as the .pyxs file.
Listing 2: A simple example of an extension source file (.pyxs)
Simple Extension Examples http://www.eyesopen.com/vida/extensions/example1.pyx http://www.eyesopen.com/vida/extensions/example2.pyx http://www.eyesopen.com/vida/extensions/example3.pyx example4.pyx example5.pyx
Users can be automatically subscribed to an extension source through the environment variable VIDA_EXTENSIONS_URL. When this environment variable is set to the URL of a .pyxs file, VIDA will install the full set of contained extensions without requiring any user intervention. To automatically subscribe to multiple extension sources, set the VIDA_EXTENSIONS_URL variable to a comma-separated list of URLs.