taurus.qt.qtcore.configuration

This module provides the set of base classes designed to provide configuration features to the classes that inherit from them

Classes

class BaseConfigurableClass(**kwargs)

A base class defining the API for configurable objects.

Note

One implicit requisite is that a configurable object must also provide a meth:`objectName method which returns the object name. This is typically fulfilled by inheriting from QObject.

Using objects that inherit from BaseConfigurableClass automates saving and restoring of application settings and also enables the use of perspectives in Taurus GUIs.

The basic idea is that each object/widget in your application is responsible for providing a dictionary containing information on its properties (see createConfig()). The same object/widget is also responsible for restoring such properties when provided with a configuration dictionary (see applyConfig()).

For a certain property to be saved/restored it is usually enough to register it using registerConfigProperty(). When the objects are structured in a hierarchical way (e.g. as the widgets in a Qt application), the parent widget can (should) delegate the save/restore of its children to the children themselves. This delegation is done by registering the children using registerConfigDelegate().

Consider the following example: I am creating a groupbox container which contains a TaurusForm and I want to save/restore the state of the checkbox and the properties of the form:

# The class looks like this:
class MyBox(Qt.QGroupBox, BaseConfigurableClass):
    def __init__(self):
        ...
        self.form = TaurusForm()
        ...
        self.registerConfigProperty(
            self.isChecked,
            self.setChecked,
            'checked'
        )
        # the TaurusForm already handles its own configuration!
        self.registerConfigDelegate(self.form)
        ...

# and we can retrieve the configuration doing:
b1 = MyBox()
# checked is a registered property of MyBox class
b1.setChecked(True)
# modifiableByUser is a registered property of a TaurusForm
b1.form.setModifiableByUser(True)
# we get the configuration as a dictionary
cfg = b1.createConfig()
...
b2 = MyBox()
# now b2 has the same configuration as b1 when cfg was created
b2.applyConfig(cfg)

createConfig() and applyConfig() methods use a dictionary for passing the configuration, but BaseConfigurableClass also provides some other convenience methods for working with files (saveConfigFile() and loadConfigFile()) or as QByteArrays (createQConfig() and applyQConfig())

Finally, we recommend to use TaurusMainWindow for all Taurus GUIs since it automates all the steps for saving properties when closing and restoring the settings on startup. It also provides a mechanism for implementing “perspectives” in your application.

(more info)

class configurableProperty(name, fget, fset, obj=None)

A dummy class used to handle properties with the configuration API

Warning

this class is intended for internal use by the configuration package. Do not instantiate it directly in your code. Use BaseConfigurableClass.registerConfigProperty() instead.

(more info)

class ConfigurationError

(more info)