# `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)