Plugins

Table of Contents Developing Viewer Plugins Creating a Plugin File Installing Plugin File Adding a Custom Action to Viewer

Developing Viewer Plugins

Creating a Plugin File

Your plugin must have the extension .py and be a normally import-able module with these 3 functions:

• name
• author
• description
• action

name(), author() and description() take no parameters and simply return the name of the plugin, and the author respectively. action() takes 2 parameters: a constant to describe the action that has happened, and an object that is relevant. Here are the constants and objects that will be passed to action():

constant	object
pluginmanager.PLUGIN_ACTION_INIT	GeolinkedViewers
pluginmanager.PLUGIN_ACTION_NEWVIEWER	ViewerWindow
pluginmanager.PLUGIN_ACTION_NEWQUERY	QueryDockWidget

Information on the internal classes of TuiView can be found at the Developer's Documentation page.

Installing Plugin File

Viewer searched for plugins in 3 locations upon startup:

1. a 'plugins' directory under where the 'tuiview' script is running
2. Any directories listed in the TUIVIEW_PLUGINS_PATH environment variable. Multiple directories can be listed and separated by ':' on Unix or ';' on Windows.
3. Under ~/.tuiview/plugins where ~ is the user's home directory, or c:\Users\username\ .tuiview\plugins on Windows

Note that these directories are searched in the order listed. Plugins with the same name found later will override those found first.

Adding a Custom Action to Viewer

Here is an example of adding a custom action and a new menu to Viewer via a plugin:

...
# event handler class - must be derived from QObject
# so Qt's signal and slots system works
class MyEventHandler(QObject):
    def __init__(self, viewer):
        QObject.__init__(self)
        self.viewer = viewer

    # this function gets called when action triggered
    def myEvent(self):
        QMessageBox.information(self.viewer, "Viewer", "My Plugin")

def action(actioncode, viewer):
    # check for the code we are interested in 
    if actioncode == pluginmanager.PLUGIN_ACTION_NEWVIEWER:

        # create a handler class
        handler = MyEventHandler(viewer)
        # create an action class
        myaction = QAction(viewer, triggered=handler.myEvent)
        myaction.setText("My plugin Action")

        # create a new menu and install the action
        mymenu = viewer.menuBar().addMenu("&My Menu")
        mymenu.addAction(myaction)

        # make sure the object isn't garbage collected
        app = QApplication.instance()
        app.savePluginHandler(handler)