QIfConfiguration Class

QIfConfiguration provides settings for QIfAbstractFeature, QIfServiceObject and QIfSimulationEngine. More...

Header: #include <QIfConfiguration>
qmake: QT += interfaceframework
Since: Qt 6.5
Instantiated By: InterfaceFrameworkConfiguration
Inherits: QObject and QQmlParserStatus

Properties

Public Functions

QIfConfiguration(const QString &name = QString(), QObject *parent = nullptr)
QIfAbstractFeature::DiscoveryMode discoveryMode() const
bool ignoreOverrideWarnings() const
bool isValid() const
QString name() const
QStringList preferredBackends() const
QIfServiceObject *serviceObject() const
QVariantMap serviceSettings() const
QString simulationDataFile() const
QString simulationFile() const

Public Slots

bool setDiscoveryMode(QIfAbstractFeature::DiscoveryMode discoveryMode)
void setIgnoreOverrideWarnings(bool ignoreOverrideWarnings)
bool setName(const QString &name)
bool setPreferredBackends(const QStringList &preferredBackends)
bool setServiceObject(QIfServiceObject *serviceObject)
bool setServiceSettings(const QVariantMap &serviceSettings)
bool setSimulationDataFile(const QString &simulationDataFile)
bool setSimulationFile(const QString &simulationFile)

Signals

void discoveryModeChanged(QIfAbstractFeature::DiscoveryMode discoveryMode)
void ignoreOverrideWarningsChanged(bool ignoreOverrideWarnings)
void isValidChanged(bool isValid)
void nameChanged(const QString &name)
void preferredBackendsChanged(const QStringList &preferredBackends)
void serviceObjectChanged(const QIfServiceObject *serviceObject)
void serviceSettingsChanged(const QVariantMap &serviceSettings)
void simulationDataFileChanged(const QString &simulationDataFile)
void simulationFileChanged(const QString &simulationFile)

Static Public Members

bool arePreferredBackendsSet(const QString &group)
bool areServiceSettingsSet(const QString &group)
QIfAbstractFeature::DiscoveryMode discoveryMode(const QString &group)
bool exists(const QString &group)
bool isDiscoveryModeSet(const QString &group)
bool isServiceObjectSet(const QString &group)
bool isSimulationDataFileSet(const QString &group)
bool isSimulationFileSet(const QString &group)
QStringList preferredBackends(const QString &group)
QIfServiceObject *serviceObject(const QString &group)
QVariantMap serviceSettings(const QString &group)
bool setDiscoveryMode(const QString &group, QIfAbstractFeature::DiscoveryMode discoveryMode)
bool setPreferredBackends(const QString &group, const QStringList &preferredBackends)
bool setServiceObject(const QString &group, QIfServiceObject *serviceObject)
bool setServiceSettings(const QString &group, const QVariantMap &serviceSettings)
bool setSimulationDataFile(const QString &group, const QString &simulationDataFile)
bool setSimulationFile(const QString &group, const QString &simulationFile)
QString simulationDataFile(const QString &group)
QString simulationFile(const QString &group)

Detailed Description

QIfConfiguration provides settings for QIfAbstractFeature, QIfServiceObject and QIfSimulationEngine. All settings configured with QIfConfiguration are applied to all objects with a matching configurationId. For QIfSimulationEngine the identifier acts as configurationId.

Once a new instance of any of the supported classes is created, and its configurationId matches with a configuration which has been created before, all settings within the configuration are also applied to the new instance.

Note: Reading values from QIfConfiguration does NOT read the current values of all instances matching the configurationId. It only returns the value stored in the configuration, which can be different, as it is still possible to change values directly without involving QIfConfiguration. It acts as a WRITE ONLY interface towards all matching instances.

The following snippet shows how a configuration can be created:

// Create a class based on QIfAbstractFeature and set it's configuration id to "group1"
auto feature1 = new AbstractFeatureBasedClass;
feature1.setConfigurationId("group1");

// Create another one, but with configuration id "group2"
auto feature2 = new AbstractFeatureBasedClass;
feature2.setConfigurationId("group2");

// The discoveryMode of all feature based instances in "group1" should be LoadOnlyProductionBackends
QIfConfiguration::setDiscoveryMode("group1", QIfAbstractFeature::LoadOnlyProductionBackends);

qDebug() << feature1.discoveryMode() << feature2.discoveryMode();

The configuration is only applied to 'feature1' and NOT to 'feature2', because the latter is NOT in 'group1' and 'group2' doesn't have any configured value (yet).

By adding an additional configuration the feature2 can be changed as well:

QIfConfiguration config("group2");
config.setDiscoeryMode(QIfAbstractFeature::LoadOnlyProductionBackends);

qDebug() << feature1.discoveryMode() << feature2.discoveryMode();

Now 'feature1' and 'feature2' have the same discoveryMode. Using an instance of QIfConfiguration is an alternative way instead of using the static functions.

Note: Destroying a QIfConfiguration doesn't reset the configured values.

QML integration

A configuration can be created from QML by instantiating the InterfaceFrameworkConfiguration element and assigning a name to it. Without a name the configuration is not valid and the assigned values will have no effect.

Settings file

In addition to creating configurations at runtime, it is also possible to provide the initial configuration values in a configuration file.

If it exists, the following file is parsed at startup:

[QLibraryInfo::DataPath]/qtifconfig.ini

The configuration file uses the INI format and is applicable for all types which can also be saved as a string. This excludes the serviceObject setting for example. See Settings Overview for a list of all settings and how they can be set/overwritten.

Following an example, which configures group1 and group2:

[group1]
preferredBackends=backend1,backend2
serviceSettings/key1=value1
serviceSettings/key2=value2
[group2]
discoveryMode=LoadOnlySimulationBackends

For the serviceSettings setting, multiple values cannot be assigned in one statement. Instead every key-value pair needs to be assigned separately. The key follows the serviceSettings keyword followed by a slash as separator. In a similar fashion, nested key-value pairs can be created:

[group1]
serviceSettings/key1/nested1=value1
serviceSettings/key1/nested2=value2

Environment Overrides

For testing scenarios it is sometimes useful to overwrite certain settings. This can be done by using one of the OVERRIDE environment variables. Once an override has been set, the value cannot be changed at runtime anymore and a warning will be shown when trying to change it. See the ignoreOverrideWarnings property on how this can be turned off.

All OVERRIDE environment variables always have to be in the following form:

OVERRIDE=<CONFIGURATIONID>=<VALUE>[;<CONFIGURATIONID>=<VALUE>]

See Settings Overview for a list of all settings and how they can be set/overwritten.

Settings Overview

SettingAffected ClassesSupports Initial ValuesOverride Environment Variable
serviceSettingsQIfServiceObjectyes-
simulationFileQIfSimulationEngineyesQTIF_SIMULATION_OVERRIDE
simulationDataFileQIfSimulationEngineyesQTIF_SIMULATION_DATA_OVERRIDE
discoveryModeQIfAbstractFeature QIfAbstractFeatureListModelyesQTIF_DISCOVERY_MODE_OVERRIDE
preferredBackendsQIfAbstractFeature QIfAbstractFeatureListModelyesQTIF_PREFERRED_BACKENDS_OVERRIDE
serviceObjectQIfAbstractFeature QIfAbstractFeatureListModelno-

Property Documentation

discoveryMode : QIfAbstractFeature::DiscoveryMode

Holds the discoveryMode of the configuration. The discoveryMode is applied to all QIfAbstractFeature or QIfAbstractFeatureListModel instances with a matching configurationId. The discoveryMode is applied when a new matching instance is created and they are also applied to all existing instances.

See Settings Overview for how to provide initial values and overrides.

Access functions:

QIfAbstractFeature::DiscoveryMode discoveryMode() const
QIfAbstractFeature::DiscoveryMode discoveryMode(const QString &group)
bool setDiscoveryMode(QIfAbstractFeature::DiscoveryMode discoveryMode)
bool setDiscoveryMode(const QString &group, QIfAbstractFeature::DiscoveryMode discoveryMode)

Notifier signal:

void discoveryModeChanged(QIfAbstractFeature::DiscoveryMode discoveryMode)

See also QIfAbstractFeature::discoveryMode and QIfAbstractFeatureListModel::discoveryMode.

ignoreOverrideWarnings : bool

When enabled, all override warnings will be ignored and not logged.

Access functions:

bool ignoreOverrideWarnings() const
void setIgnoreOverrideWarnings(bool ignoreOverrideWarnings)

Notifier signal:

void ignoreOverrideWarningsChanged(bool ignoreOverrideWarnings)

See also Environment Overrides.

name : QString

Holds the name of the configuration. The name is used to find objects with a matching configurationId in order to apply settings to them.

Note: Once a name has been set, it cannot be changed afterwards.

Access functions:

QString name() const
bool setName(const QString &name)

Notifier signal:

void nameChanged(const QString &name)

preferredBackends : QStringList

Holds the preferredBackends of the configuration. The preferredBackends are applied to all QIfAbstractFeature or QIfAbstractFeatureListModel instances with a matching configurationId. The preferredBackends are applied when a new matching instance is created and it is also applied to all existing instances.

See Settings Overview for how to provide initial values and overrides.

Access functions:

QStringList preferredBackends() const
QStringList preferredBackends(const QString &group)
bool setPreferredBackends(const QStringList &preferredBackends)
bool setPreferredBackends(const QString &group, const QStringList &preferredBackends)

Notifier signal:

void preferredBackendsChanged(const QStringList &preferredBackends)

See also QIfAbstractFeature::preferredBackends and QIfAbstractFeatureListModel::preferredBackends.

serviceObject : QIfServiceObject*

Holds the serviceObject of the configuration. The serviceObject is applied to all QIfAbstractFeature or QIfAbstractFeatureListModel instances with a matching configurationId. The serviceObject is applied when a new matching instance is created and it is also applied to all existing instances.

See Settings Overview for how to provide initial values and overrides.

Access functions:

QIfServiceObject *serviceObject() const
QIfServiceObject *serviceObject(const QString &group)
bool setServiceObject(QIfServiceObject *serviceObject)
bool setServiceObject(const QString &group, QIfServiceObject *serviceObject)

Notifier signal:

void serviceObjectChanged(const QIfServiceObject *serviceObject)

See also QIfAbstractFeature::serviceObject and QIfAbstractFeatureListModel::serviceObject.

serviceSettings : QVariantMap

Holds the serviceSettings of the configuration. The serviceSettings are applied to all QIfServiceObject instances with a matching configurationId. The serviceSettings are applied when a new matching QIfServiceObject instance is created and they are also applied to all existing QIfServiceObject instances.

See Settings Overview for how to provide initial values and overrides.

Access functions:

QVariantMap serviceSettings() const
QVariantMap serviceSettings(const QString &group)
bool setServiceSettings(const QVariantMap &serviceSettings)
bool setServiceSettings(const QString &group, const QVariantMap &serviceSettings)

Notifier signal:

void serviceSettingsChanged(const QVariantMap &serviceSettings)

See also QIfServiceObject::serviceSettings.

simulationDataFile : QString

Holds the simulationDataFile of the configuration. The simulationDataFile is set as override for all matching QIfSimulationEngine instances.

If the matching QIfSimulationeEngine is already running, updating the value doesn't have any effect and the simulation will continue to run as it is.

See Settings Overview for how to provide initial values and overrides.

Access functions:

QString simulationDataFile() const
QString simulationDataFile(const QString &group)
bool setSimulationDataFile(const QString &simulationDataFile)
bool setSimulationDataFile(const QString &group, const QString &simulationDataFile)

Notifier signal:

void simulationDataFileChanged(const QString &simulationDataFile)

See also QIfSimulationEngine::loadSimulationData().

simulationFile : QString

Holds the simulationFile of the configuration. The simulationFile is set as override for all matching QIfSimulationEngine instances.

If the matching QIfSimulationeEngine is already running, updating the value doesn't have any effect and the simulation will continue to run as it is.

See Settings Overview for how to provide initial values and overrides.

Access functions:

QString simulationFile() const
QString simulationFile(const QString &group)
bool setSimulationFile(const QString &simulationFile)
bool setSimulationFile(const QString &group, const QString &simulationFile)

Notifier signal:

void simulationFileChanged(const QString &simulationFile)

See also QIfSimulationEngine::loadSimulation().

[read-only] valid : const bool

Returns true when the configuration instance is valid.

A configuration is only valid if it was created with a name.

Access functions:

bool isValid() const

Notifier signal:

void isValidChanged(bool isValid)

Member Function Documentation

[explicit] QIfConfiguration::QIfConfiguration(const QString &name = QString(), QObject *parent = nullptr)

Constructs a QIfConfiguration instance with a name and a parent

[static] bool QIfConfiguration::arePreferredBackendsSet(const QString &group)

Returns true when the preferred backends have been set in the configuration named group and false otherwise.

A value is considered as "set" when the corresponding setter was called, a valid value was set in the global ini file or the corresponding override is active.

See also Settings file.

[static] bool QIfConfiguration::areServiceSettingsSet(const QString &group)

Returns true when service settings have been set in the configuration named group and false otherwise.

A value is considered as "set" when the corresponding setter was called, a valid value was set in the global ini file or the corresponding override is active.

See also Settings file.

[static] QIfAbstractFeature::DiscoveryMode QIfConfiguration::discoveryMode(const QString &group)

Returns the current discovery mode of the configuration group.

Note: The returned value is what is stored inside the configuration, not the current value of all QIfAbstractFeature or QIfAbstractFeatureListModel instances with a matching configurationId.

Note: Getter function for property discoveryMode.

[static] bool QIfConfiguration::exists(const QString &group)

Returns true if the configuration group exists.

A configuration is created once a single value has been set in it.

[static] bool QIfConfiguration::isDiscoveryModeSet(const QString &group)

Returns true when the discovery mode have been set in the configuration named group and false otherwise.

A value is considered as "set" when the corresponding setter was called, a valid value was set in the global ini file or the corresponding override is active.

See also Settings file.

[static] bool QIfConfiguration::isServiceObjectSet(const QString &group)

Returns true when the service object have been set in the configuration named group and false otherwise.

A value is considered as "set" when the corresponding setter was called, a valid value was set in the global ini file or the corresponding override is active.

See also Settings file.

[static] bool QIfConfiguration::isSimulationDataFileSet(const QString &group)

Returns true when the simulation data file have been set in the configuration named group and false otherwise.

A value is considered as "set" when the corresponding setter was called, a valid value was set in the global ini file or the corresponding override is active.

See also Settings file.

[static] bool QIfConfiguration::isSimulationFileSet(const QString &group)

Returns true when the simulation file have been set in the configuration named group and false otherwise.

A value is considered as "set" when the corresponding setter was called, a valid value was set in the global ini file or the corresponding override is active.

See also Settings file.

[static] QStringList QIfConfiguration::preferredBackends(const QString &group)

Returns the current preferred backends of the configuration group.

Note: The returned value is what is stored inside the configuration, not the current value of all QIfAbstractFeature or QIfAbstractFeatureListModel instances with a matching configurationId.

Note: Getter function for property preferredBackends.

[static] QIfServiceObject *QIfConfiguration::serviceObject(const QString &group)

Returns the current service object of the configuration group.

Note: The returned value is what is stored inside the configuration, not the current value of all QIfAbstractFeature or QIfAbstractFeatureListModel instances with a matching configurationId.

Note: Getter function for property serviceObject.

[static] QVariantMap QIfConfiguration::serviceSettings(const QString &group)

Returns the current service settings of the configuration group.

Note: The returned value is what is stored inside the configuration, not the current value of all QIfServiceObject instances with a matching configurationId.

Note: Getter function for property serviceSettings.

[slot] bool QIfConfiguration::setDiscoveryMode(QIfAbstractFeature::DiscoveryMode discoveryMode)

Sets the discoveryMode of this configuration and applies it to all QIfAbstractFeature or QIfAbstractFeatureListModel instances with a matching configurationId.

Returns false if setting the discoveryMode failed because an override was active, returns true otherwise.

Note: Setter function for property discoveryMode.

See also discoveryMode() and Environment Overrides.

[static] bool QIfConfiguration::setDiscoveryMode(const QString &group, QIfAbstractFeature::DiscoveryMode discoveryMode)

Sets the discoveryMode of the configuration group and applies it to all QIfAbstractFeature or QIfAbstractFeatureListModel instances with a matching configurationId.

Returns false if setting the serviceObject failed because an override was active, returns true otherwise.

Note: Setter function for property discoveryMode.

See also Environment Overrides.

[slot] bool QIfConfiguration::setName(const QString &name)

Sets the name of the configuration.

The name is used to find objects with a matching configurationId in order to apply all settings of this configuration to them.

Returns false if setting the name failed e.g. when a instance with this name already exists or when the instance already has a name set. The name of an instance can't be changed once it has been set. Returns true otherwise.

Note: Setter function for property name.

See also name().

[slot] bool QIfConfiguration::setPreferredBackends(const QStringList &preferredBackends)

Sets the preferredBackends of this configuration and applies it to all QIfAbstractFeature or QIfAbstractFeatureListModel instances with a matching configurationId.

Returns false if setting the preferredBackends failed because an override was active, returns true otherwise.

Note: Setter function for property preferredBackends.

See also preferredBackends() and Environment Overrides.

[static] bool QIfConfiguration::setPreferredBackends(const QString &group, const QStringList &preferredBackends)

Sets the preferredBackends of the configuration group and applies it to all QIfAbstractFeature or QIfAbstractFeatureListModel instances with a matching configurationId.

Returns false if setting the serviceObject failed because an override was active, returns true otherwise.

Note: Setter function for property preferredBackends.

See also Environment Overrides.

[slot] bool QIfConfiguration::setServiceObject(QIfServiceObject *serviceObject)

Sets the serviceObject of this configuration and applies it to all QIfAbstractFeature or QIfAbstractFeatureListModel instances with a matching configurationId.

Returns false if setting the serviceObject failed because an override was active, returns true otherwise.

Note: Setter function for property serviceObject.

See also serviceObject() and Environment Overrides.

[static] bool QIfConfiguration::setServiceObject(const QString &group, QIfServiceObject *serviceObject)

Sets the serviceObject of the configuration group and applies it to all QIfAbstractFeature or QIfAbstractFeatureListModel instances with a matching configurationId.

Returns false if setting the serviceObject failed because an override was active, returns true otherwise.

Note: Setter function for property serviceObject.

See also Environment Overrides.

[slot] bool QIfConfiguration::setServiceSettings(const QVariantMap &serviceSettings)

Sets the serviceSettings of this configuration and applies it to all QIfServiceObject instances with a matching configurationId.

Returns false if setting the serviceObject failed because an override was active, returns true otherwise.

Note: Setter function for property serviceSettings.

See also serviceSettings() and Environment Overrides.

[static] bool QIfConfiguration::setServiceSettings(const QString &group, const QVariantMap &serviceSettings)

Sets the serviceSettings of the configuration group and applies it to all QIfServiceObject instances with a matching configurationId.

Returns false if setting the serviceObject failed because an override was active, returns true otherwise.

Note: Setter function for property serviceSettings.

See also Environment Overrides.

[slot] bool QIfConfiguration::setSimulationDataFile(const QString &simulationDataFile)

Sets the simulationDataFile of this configuration and applies it to all QIfSimulationEngine instances with a matching configurationId.

Returns false if setting the simulationDataFile failed because an override was active, returns true otherwise.

Note: Setter function for property simulationDataFile.

See also simulationDataFile() and Environment Overrides.

[static] bool QIfConfiguration::setSimulationDataFile(const QString &group, const QString &simulationDataFile)

Sets the simulationDataFile of the configuration group and applies it to all QIfSimulationEngine instances with a matching configurationId.

Returns false if setting the simulationDataFile failed because an override was active, returns true otherwise.

Note: Setter function for property simulationDataFile.

See also Environment Overrides.

[slot] bool QIfConfiguration::setSimulationFile(const QString &simulationFile)

Sets the simulationFile of this configuration and applies it to all QIfSimulationEngine instances with a matching configurationId.

Returns false if setting the simulationFile failed because an override was active, returns true otherwise.

Note: Setter function for property simulationFile.

See also simulationFile() and Environment Overrides.

[static] bool QIfConfiguration::setSimulationFile(const QString &group, const QString &simulationFile)

Sets the simulationFile of the configuration group and applies it to all QIfSimulationEngine instances with a matching configurationId.

Returns false if setting the simulationDataFile failed because an override was active, returns true otherwise.

Note: Setter function for property simulationFile.

See also Environment Overrides.

[static] QString QIfConfiguration::simulationDataFile(const QString &group)

Returns the current simulation data file of the configuration group.

Note: The returned value is what is stored inside the configuration, not the current value of all QIfSimulationEngine instances with a matching configurationId.

Note: Getter function for property simulationDataFile.

[static] QString QIfConfiguration::simulationFile(const QString &group)

Returns the current simulation file of the configuration group.

Note: The returned value is what is stored inside the configuration, not the current value of all QIfSimulationEngine instances with a matching configurationId.

Note: Getter function for property simulationFile.

© 2023 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.