BaseConfigurableClass
¶

-
class
BaseConfigurableClass
(**kwargs)[source]¶ Bases:
object
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 (seeapplyConfig()
).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 usingregisterConfigDelegate()
.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()
andapplyConfig()
methods use a dictionary for passing the configuration, butBaseConfigurableClass
also provides some other convenience methods for working with files (saveConfigFile()
andloadConfigFile()
) or as QByteArrays (createQConfig()
andapplyQConfig()
)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.-
applyConfig
(configdict, depth=None)[source]¶ applies the settings stored in a configdict to the current object.
In most usual situations, using
registerConfigProperty()
andregisterConfigDelegate()
, should be enough to cover all needs using this method, although it can be reimplemented in children classes to support very specific configurations.Parameters: - configdict (
dict
) – - depth (
int
) – If depth = 0, applyConfig will only be called for this object, and not for any other object registered viaregisterConfigurableItem()
. If depth > 0, applyConfig will be called recursively as many times as the depth value. If depth < 0 (default, see note), no limit is imposed to recursion (i.e., it will recurse for as deep as there are registered items).
Note
the default recursion depth can be tweaked in derived classes by changing the class property defaultConfigRecursionDepth
See also
- configdict (
-
applyQConfig
(qstate)[source]¶ restores the configuration from a qstate generated by
getQState()
.Parameters: qstate ( QByteArray
) –See also
-
checkConfigVersion
(configdict, showDialog=False, supportedVersions=None)[source]¶ 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: - configdict (
dict
) – configuration dictionary to check - showDialog (
bool
) – whether to show a QtWarning dialog if check failed (false by default) - supportedVersions (
sequence
<str
> orNone
) – supported version numbers, if None given, the versions supported by this widget will be used (i.e., those defined in self._supportedConfigVersions)
Return type: bool
Returns: returns True if the configdict is of the right version
- configdict (
-
createConfig
(allowUnpickable=False)[source]¶ Returns a dictionary containing configuration information about the current state of the object.
In most usual situations, using
registerConfigProperty()
andregisterConfigDelegate()
, 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 ( 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: dict
<str
,object
>Returns: configurations (which can be loaded with applyConfig()
).
-
createQConfig
()[source]¶ returns the current configuration status encoded as a QByteArray. This state can therefore be easily stored using QSettings
Return type: QByteArray
Returns: (in the current implementation this is just a pickled configdict encoded as a QByteArray See also
restoreQConfig()
-
defaultConfigRecursionDepth
= -1¶
-
getConfigurableItemNames
()[source]¶ returns an ordered list of the names of currently registered configuration items (delegates and properties)
Return type: list
<unicode
>Returns:
-
static
isTaurusConfig
(x)[source]¶ Checks if the given argument has the structure of a configdict
Parameters: x ( object
) – object to testReturn type: bool
Returns: True if it is a configdict, False otherwise.
-
loadConfigFile
(ifile=None)[source]¶ Reads a file stored by
saveConfig()
and applies the settingsParameters: ifile ( file
orstring
) – file or filename from where to read the configurationReturn type: str
Returns: file name used
-
registerConfigDelegate
(delegate, name=None)[source]¶ 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: - delegate (
BaseConfigurableClass
) – The delegate object to be registered. - name (
str
) – The name to be used as a key for this item in the configuration dictionary. If None given, the object name is used by default.
Note
the registration order will be used when restoring configurations
-
registerConfigProperty
(fget, fset, name)[source]¶ 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: - fget (
method
orstr
) – method (or name of a method) that gets no arguments and returns the value of a property. - fset (
method
orstr
) – method (or name of a method) that gets as an argument the value of a property, and sets it - name (
str
) – The name to be used as a key for this property in the configuration dictionary
Note
the registration order will be used when restoring configurations
- fget (
-
resetConfigurableItems
()[source]¶ clears the record of configurable items depending of this object
See also
-
saveConfigFile
(ofile=None)[source]¶ Stores the current configuration on a file
Parameters: ofile ( file
orstring
) – file or filename to store the configurationReturn type: str
Returns: file name used
-
unregisterConfigurableItem
(item, raiseOnError=True)[source]¶ 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: - item (
object
orstr
) – The object that should be unregistered. Alternatively, the name under which the object was registered can be passed as a python string. - raiseOnError (
bool
) – If True (default), it raises a KeyError exception if item was not registered. If False, it just logs a debug message
- item (
-