# `BaseConfigurableClass`

digraph inheritancef41db5ca11 { bgcolor=transparent; rankdir=UD; ratio=compress; size="8.0, 12.0"; "BaseConfigurableClass" [URL="#taurus.qt.qtcore.configuration.BaseConfigurableClass",color=dodgerblue1,fillcolor=white,fontcolor=black,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.5,shape=box,style=rounded,target="_top",tooltip="A base class defining the API for configurable objects."]; }

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.

  Import from `taurus.qt.qtcore.configuration` as:

      from taurus.qt.qtcore.configuration import BaseConfigurableClass

  applyConfig(configdict, depth=None)

    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:

      - configdict (dict)

      - depth (int) – If depth = 0, applyConfig will only be called for this object, and not for any other object registered via `registerConfigurableItem()`. 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

    `createConfig()`

  applyQConfig(qstate)

    restores the configuration from a qstate generated by `getQState()`.

    Parameters:

      qstate (QByteArray)

    See also

    `createQConfig()`

  checkConfigVersion(configdict, showDialog=False, supportedVersions=None)

    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>, or None) – supported version numbers, if None given, the versions supported by this widget will be used (i.e., those defined in self._supportedConfigVersions)

    Returns:

      returns True if the configdict is of the right version

    Return type:

      bool

  createConfig(allowUnpickable=False)

    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())

    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).

    Returns:

      configurations (which can be loaded with `applyConfig()`).

    Return type:

      dict<str,object>

  createQConfig()

    returns the current configuration status encoded as a QByteArray. This state can therefore be easily stored using QSettings

    Returns:

      (in the current implementation this is just a pickled configdict encoded as a QByteArray

    Return type:

      QByteArray

    See also

    `restoreQConfig()`

  defaultConfigRecursionDepth = -1
  getConfigurableItemNames()

    returns an ordered list of the names of currently registered configuration items (delegates and properties)

    Returns:

    Return type:

      list<unicode>

  static isTaurusConfig(x)

    Checks if the given argument has the structure of a configdict

    Parameters:

      x (object) – object to test

    Returns:

      True if it is a configdict, False otherwise.

    Return type:

      bool

  loadConfigFile(ifile=None)

    Reads a file stored by `saveConfig()` and applies the settings

    Parameters:

      ifile (file or string) – file or filename from where to read the configuration

    Returns:

      file name used

    Return type:

      str

  registerConfigDelegate(delegate, name=None)

    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

    See also

    `unregisterConfigurableItem()`, `registerConfigProperty()`, `createConfig()`

  registerConfigProperty(fget, fset, name)

    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 or str) – method (or name of a method) that gets no arguments and returns the value of a property.

      - fset (method or str) – 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

    See also

    `unregisterConfigurableItem()`, `registerConfigDelegate()`, `createConfig()`

  registerConfigurableItem(item, name=None)
  resetConfigurableItems()

    clears the record of configurable items depending of this object

    See also

    `registerConfigurableItem()`

  saveConfigFile(ofile=None)

    Stores the current configuration on a file

    Parameters:

      ofile (file or string) – file or filename to store the configuration

    Returns:

      file name used

    Return type:

      str

  unregisterConfigurableItem(item, raiseOnError=True)

    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 or str) – 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

    See also

    `registerConfigProperty()`, `registerConfigDelegate()`