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')
self.registerConfigDelegate(self.form) #the TaurusForm already handles its own configuration!
...
#and we can retrieve the configuration doing:
b1 = MyBox()
b1.setChecked(True) #checked is a registered property of MyBox class
b1.form.setModifiableByUser(True) #modifiableByUser is a registered property of a TaurusForm
cfg = b1.createConfig() #we get the configuration as a dictionary
...
b2 = MyBox()
b2.applyConfig(cfg) #now b2 has the same configuration as b1 when cfg was created
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.
applies the settings stored in a configdict to the current object.
In most usual situations, using registerConfigProperty() and registerConfigDelegate(), should be enough to cover all needs using this method, although it can be reimplemented in children classes to support very specific configurations.
Parameters: |
|
---|
Note
the default recursion depth can be tweaked in derived classes by changing the class property defaultConfigRecursionDepth
See also
restores the configuration from a qstate generated by getQState().
Parameters: | qstate (:class:~`QByteArray`) – |
---|
See also
Check if the version of configdict is supported. By default, the BaseConfigurableClass objects have [“__UNVERSIONED__”] as their list of supported versions, so unversioned config dicts will be accepted.
Parameters: |
|
---|---|
Return type: | :class:~`bool` |
Returns: | returns True if the configdict is of the right version |
Returns a dictionary containing configuration information about the current state of the object.
In most usual situations, using registerConfigProperty() and registerConfigDelegate(), should be enough to cover all needs using this method, although it can be reimplemented in children classes to support very specific configurations.
By default, meth:createQConfig and meth:saveConfigFile call to this method for obtaining the data.
Hint: The following code allows you to serialize the configuration dictionary as a string (which you can store as a QSetting, or as a Tango Attribute, provided that allowUnpickable==False):
import pickle
s = pickle.dumps(widget.createConfig()) #s is a string that can be stored
Parameters: | alllowUnpickable (:class:~`bool`) – if False the returned dict is guaranteed to be a pickable object. This is the default and preferred option because it allows the serialization as a string that can be directly stored in a QSetting. If True, this limitation is not enforced, which allows to use more complex objects as values (but limits its persistence). |
---|---|
Return type: | :class:~`dict` <:class:~`str`, :class:~`object`> |
Returns: | configurations (which can be loaded with applyConfig()). |
returns the current configuration status encoded as a QByteArray. This state can therefore be easily stored using QSettings
Return type: | :class:~`QByteArray` |
---|---|
Returns: | (in the current implementation this is just a pickled configdict encoded as a QByteArray |
See also
restoreQConfig()
returns an ordered list of the names of currently registered configuration items (delegates and properties)
Return type: | :class:~`list` <:class:~`unicode`> |
---|---|
Returns: |
Checks if the given argument has the structure of a configdict
Parameters: | x (:class:~`object`) – object to test |
---|---|
Return type: | :class:~`bool` |
Returns: | True if it is a configdict, False otherwise. |
Reads a file stored by saveConfig() and applies the settings
Parameters: | ifile (:class:~`file` or :class:~`string`) – file or filename from where to read the configuration |
---|---|
Return type: | :class:~`str` |
Returns: | file name used |
Registers the given object as a delegate for configuration. Delegates are typically other objects inheriting from BaseConfigurableClass (or at least they must provide the following methods:
- createConfig (as provided by, e.g., BaseConfigurableClass)
- applyConfig (as provided by, e.g., BaseConfigurableClass)
- objectName (as provided by, e.g., QObject)
Parameters: |
|
---|
Note
the registration order will be used when restoring configurations
Registers a certain property to be included in the config dictionary.
In this context a “property” is some named value that can be obtained via a getter method and can be set via a setter method.
Parameters: |
|
---|
Note
the registration order will be used when restoring configurations
clears the record of configurable items depending of this object
See also
Stores the current configuration on a file
Parameters: | ofile (:class:~`file` or :class:~`string`) – file or filename to store the configuration |
---|---|
Return type: | :class:~`str` |
Returns: | file name used |
unregisters the given item (either a delegate or a property) from the configurable items record. It raises an exception if the item is not registered
Parameters: |
|
---|