Module Configuration Example

A module configuration widget is a widget that is shown in the module configuration panel (of the Tools window) when a user selects a module. For many modules, there is no specific configuration widget, and the panel informs users to set parameters via the Module Information panel (on the right side of the main window). However, other built-in modules like PythonSource have custom widgets. Any module may specify its own configuration widget via the configureWidgetType setting.

The current StandardConfigurationWidget requires only a couple of methods (saveTriggered and resetTriggered), but it is not very clear what needs to be implemented and where. Below, we have written a ModuleConfigurationWidgetBase that attempts to abstract much of the common code that developers may wish to use. Then, the MyConfigurationWidget focuses on the specifics for a particular configuration widget. Note that one of the tricky pieces that ModuleConfigurationWidgetBase takes care of is locating and transforming parameter values. Any "function" in VisTrails may store multiple parameter values; for example, "SetCameraPosition" might have three parameters (x,y,z). Thus, we use lists of values throughout the code. In addition, the parameter values are serialized in order to ensure their storage, but each Constant subclass must provide translate_to_python and translate_to_string methods. We use these methods to serialize and deserialize values. The heavy lifting is done by the self.controller.update_functions which persists all of the changes to the vistrail. We use refresh_module to make sure the changes are reflected in the GUI.

Also, note that the example shows how the fruitport's visibility can be programmatically set using Module.visible_input_ports. However, such changes are not persisted across sessions. The state_was_changed and state_was_reset provide some cleanup code to make sure that VisTrails is aware when there are unsaved changes; you should link any widget state changes to this method.

In future versions of VisTrails, we expect to streamline the process and make the API cleaner. Expect a per-module _settings field that allows settings like the configuration widget to be specified with the module definition as well as support for named arguments so that port and settings definitions are more understandable.

Example Code for VisTrails 2.0+

init.py

from core.modules.vistrails_module import Module
from widgets import MyConfigurationWidget

class MyConfigureModule(Module):
    _input_ports = [("order", "(edu.utah.sci.vistrails.basic:Integer)"),
                    ("rating", "(edu.utah.sci.vistrails.basic:Integer)"),
                    ("fruit", "(edu.utah.sci.vistrails.basic:String)",
                     {"optional": True}),]
    _output_ports = [("value", "(edu.utah.sci.vistrails.basic:String)")]

_modules = [(MyConfigureModule, {"configureWidgetType": MyConfigurationWidget})]

widgets.py

from PyQt4 import QtCore, QtGui
from itertools import izip

from gui.modules.module_configure import StandardModuleConfigurationWidget
from core import debug

class ModuleConfigurationWidgetBase(StandardModuleConfigurationWidget):
    """ModuleConfigurationWidgetBase provides more scaffolding over
    StandardModuleConfigurationWidget so developers do not have to
    comb through the source code to determine what needs to be implemented

    """
    def __init__(self, module, controller, parent=None):
        StandardModuleConfigurationWidget.__init__(self, module, controller, 
                                                   parent)
        self.has_button_layout = False
        self.create_widget()
        self.set_gui_values()

    def create_widget(self):
        raise NotImplementedError('Subclass needs to implement'
                                  '"create_widget"')

    def set_vistrails_values(self):
        raise NotImplementedError('Subclass needs to implement '
                                  '"set_vistrails_values"')

    def set_gui_values(self):
        raise NotImplementedError('Subclass needs to implement '
                                  '"set_gui_values"')

    def create_button_layout(self):
        self.has_button_layout = True

        button_layout = QtGui.QHBoxLayout()
        self.reset_button = QtGui.QPushButton('&Reset')
        self.reset_button.setEnabled(False)
        self.save_button = QtGui.QPushButton('&Save')
        self.save_button.setDefault(True)
        self.save_button.setEnabled(False)
        button_layout.addStretch(1)
        button_layout.addWidget(self.reset_button)
        button_layout.addWidget(self.save_button)

        self.connect(self.reset_button, QtCore.SIGNAL("clicked()"),
                     self.resetTriggered)
        self.connect(self.save_button, QtCore.SIGNAL("clicked()"),
                     self.saveTriggered)

        return button_layout

    def state_was_changed(self, *args, **kwargs):
        if self.has_button_layout:
            self.save_button.setEnabled(True)
            self.reset_button.setEnabled(True)
        self.state_changed = True

    def state_was_reset(self):
        if self.has_button_layout:
            self.save_button.setEnabled(False)
            self.reset_button.setEnabled(False)
        self.state_changed = False        

    def get_function_by_name(self, function_name):
        """Given its name, returns a ModuleFunction object if it exists
        otherwise None.  If two or more functions exist for the same
        port, it writes a warning and returns the first.

        """
        found = []
        for function in self.module.functions:
            if function.name == function_name:
                found.append(function)

        if len(found) > 1:
            debug.warning("Found more than one function named '%s'" % \
                          function_name)
        if len(found) < 1:
            return None
        return found[0]

    def get_function_values(self, function_name):
        """Takes a function name and returns a list of (python) values on that
        function.  Note that this is a list because there can be
        multiple parameter values per function if we have a compound
        port.

        """
        f = self.get_function_by_name(function_name)
        if f is None:
            return None

        str_values = [p.strValue for p in f.params]

        ps = self.module.get_port_spec(function_name, 'input')
        descriptors = ps.descriptors()
        if len(str_values) != len(descriptors):
            debug.critical("Parameters for '%s' do not match specification" % \
                           function_name)
            return None

        values = []
        for str_value, desc in izip(str_values, descriptors):
            value = desc.module.translate_to_python(str_value)
            values.append(value)

        return values

    def get_function_str_values(self, function_name, values):
        """Takes a function name and a list of (python) values and serializes
        them, returning a list of string values.  Note that this is a
        list because there can be multiple parameter values per
        function if we have a compound port.

        """
        ps = self.module.get_port_spec(function_name, 'input')
        descriptors = ps.descriptors()
        if len(values) != len(descriptors):
            debug.critical("Values for '%s' do not match specification" % \
                           function_name)
            return None
        
        str_values = []
        for value, desc in izip(values, descriptors):
            str_value = desc.module.translate_to_string(value)
            str_values.append(str_value)

        return str_values

    def refresh_module(self):
        self.controller.flush_delayed_actions()

        # need to check this for 2.0 versus 2.1:
        if hasattr(self.controller, 'current_pipeline_scene'):
            scene = self.controller.current_pipeline_scene
        else:
            scene = self.controller.current_pipeline_view
        scene.recreate_module(self.controller.current_pipeline, self.module.id)
        
    def saveTriggered(self):
        self.set_vistrail_values()

    def resetTriggered(self):
        self.set_gui_values()


class MyConfigurationWidget(ModuleConfigurationWidgetBase):
    def create_widget(self):
        grid_layout = QtGui.QGridLayout()
        slider_label = QtGui.QLabel("Order:")
        self.slider_widget = QtGui.QSlider()
        self.slider_widget.setTracking(False)
        self.slider_widget.setOrientation(QtCore.Qt.Horizontal)
        self.slider_widget.setMinimum(0)
        self.slider_widget.setMaximum(100)
        grid_layout.addWidget(slider_label, 1, 1)
        grid_layout.addWidget(self.slider_widget, 1, 2)
        
        spin_label = QtGui.QLabel("Rating:")
        self.spin_box = QtGui.QSpinBox()
        self.spin_box.setRange(-10,10)
        grid_layout.addWidget(spin_label, 2, 1)
        grid_layout.addWidget(self.spin_box, 2, 2)

        list_label = QtGui.QLabel("Fruit:")
        self.list_widget = QtGui.QListWidget()
        self.list_widget.setSelectionMode(
            QtGui.QAbstractItemView.SingleSelection)
        self.list_widget.addItem("Apple")
        self.list_widget.addItem("Banana")
        self.list_widget.addItem("Cherry")
        grid_layout.addWidget(list_label, 3, 1, 1, 2)
        grid_layout.addWidget(self.list_widget, 4, 1, 1, 2)

        button_layout = self.create_button_layout()
        grid_layout.addLayout(button_layout, 6, 1, 1, 2)

        self.setLayout(grid_layout)

        self.connect(self.slider_widget, QtCore.SIGNAL("valueChanged(int)"),
                     self.state_was_changed)
        self.connect(self.spin_box, QtCore.SIGNAL("valueChanged(int)"),
                     self.state_was_changed)
        self.connect(self.list_widget, QtCore.SIGNAL("itemSelectionChanged()"),
                     self.state_was_changed)

        # setting port visibility
        self.checkbox = QtGui.QCheckBox("Show Fruit Port")
        grid_layout.addWidget(self.checkbox, 5, 1, 1, 2)
        if "fruit" in self.module.visible_input_ports:
            self.checkbox.setChecked(True)
        self.connect(self.checkbox, QtCore.SIGNAL("toggled(bool)"),
                     self.toggle_fruit_visibility)

    # setting port visibility
    def toggle_fruit_visibility(self, *args, **kwargs):
        if self.checkbox.isChecked():
            self.module.visible_input_ports.add("fruit")
        else:
            self.module.visible_input_ports.discard("fruit")
        self.refresh_module()

    def set_gui_values(self):
        # each value will either be None or a list (usually with only
        # a single value)
        order = self.get_function_values("order")
        rating = self.get_function_values("rating")
        fruit = self.get_function_values("fruit")

        if order is not None:
            self.slider_widget.setValue(order[0])
        else:
            self.slider_widget.setValue(0)
        if rating is not None:
            self.spin_box.setValue(rating[0])
        else:
            self.spin_box.setValue(0)
        if fruit:
            items = self.list_widget.findItems(fruit[0], QtCore.Qt.MatchExactly)
            if len(items) > 0:
                self.list_widget.setCurrentItem(items[0])
            else:
                self.list_widget.setCurrentRow(-1)            
        else:
            self.list_widget.setCurrentRow(-1)

        # call reset since the setting above likely triggered
        # state_was_changed
        self.state_was_reset()    

    def set_vistrail_values(self):
        order = self.slider_widget.value()
        rating = self.spin_box.value()
        fruit = ''
        selected_items = self.list_widget.selectedItems()
        if len(selected_items) > 0:
            fruit = selected_items[0].text()
        
        # update_functions takes a list of tuples; each tupe is of the
        # form (function name, <list of param str values>)
        functions = [(f_name,self. get_function_str_values(f_name, f_val))
                     for (f_name, f_val) in [("order", [order]),
                                             ("rating", [rating]),
                                             ("fruit", [fruit])]]
        self.controller.update_functions(self.module,
                                         functions)

        # need to reset state before refreshing the module
        self.state_was_reset()

        # refresh the module so any parameter changes are visible
        self.refresh_module()