HowTo: ConfigValue

Description

Config-values are member variables of a class that can be configured in the config-file. The configured value will be assigned to every instance of this class.

To use config-values in your class, you have to follow those steps:

1. Inherit from doc/OrxonoxClass or a derivative
2. Then you have to add void setConfigValues() to the class
3. Include core/ConfigValueIncludes.h in the source file
4. Add SetConfigValue(variable, defaultvalue) macro-calls into setConfigValues()
5. Call setConfigValues() from the constructor of your class

Example

*.h file:

class MyClass : public SomeObject     (1)
{
    public:
        MyClass();
        void setConfigValues();       (2)

        ...

    private:
        float value_;
};

*.cc file:

#include "core/CoreIncludes.h"
#include "core/ConfigValueIncludes.h" (3)

// Constructor:
MyClass::MyClass()
{
    RegisterObject(MyClass);

    this->setConfigValues();          (5)
}

void MyClass::setConfigValues()
{
    SetConfigValue(value_, 123.4);    (4)
}

Inheritance

There are three possible ways to deal with inheritance and config-values. This section explains how to use them.

Note: Examples in this section aren't complete. Read the section above for a complete example (with the constructor, the call of setConfigValues() in the constructor, including header files, calling RegisterObject).

Use a config-value in derived classes

If a config-value is defined for a base-class, all derived classes will be configured by this value.

Example:

BaseClass implements a config value:

class BaseClass : public OrxonoxClass
{
    public:
        ...
        void setConfigValues();

    protected:
        float value_;
};

void BaseClass::setConfigValues()
{
    SetConfigValue(value_, 123.4);
}

DerivedClass inherits from BaseClass without implementing setConfigValues again:

class DerivedClass : public BaseClass
{
};

In the config-file this will look like this:

[BaseClass]
value_=123.4

Then BaseClass::value_ and DerivedClass::value_ are both set by the config-value of BaseClass (and therefore 123.4).

Implementing a config-value only in a derived class

It's possible to define a config-value for a variable which was inherited from a base class.

Example:

BaseClass declares a variable but no config-value:

class BaseClass : public OrxonoxClass
{
    ...

    protected:
        float baseValue_;
};

DerivedClass derives from BaseClass and implements the config-value:

class DerivedClass : public BaseClass
{
    public:
        ...
        void setConfigValues();
};

void DerivedClass::setConfigValues()
{
    SetConfigValue(baseValue_, 10.1);
}

In the config-file this will look like this:

[DerivedClass]
value_=10.1

Then DerivedClass::baseValue_ is set by the config-value (and therefore 10.1) but BaseClass::baseValue_ isn't configurable.

Overwriting config-values in a derived class

If both, a base class and a derived class, implement the same value, instances of the base class use the configured value from the config-value-section of the base class while instances of the derived class (and further derived classes) use the overwritten value.

Example:

BaseClass implements a config value:

class BaseClass : public OrxonoxClass
{
    public:
        ...
        void setConfigValues();

    protected:
        float value_;
};

void BaseClass::setConfigValues()
{
    SetConfigValue(value_, 123.4);
}

DerivedClass derives from BaseClass and implements the config-value again:

class DerivedClass : public BaseClass
{
    public:
        ...
        void setConfigValues();
};

void DerivedClass::setConfigValues()
{
    SetConfigValue(value_, 10.1);
}

In the config-file this will look like this:

[BaseClass]
value_=123.4

[DerivedClass]
value_=10.1

Then BaseClass::value_ is set by the config-value of BaseClass (and therefore 123.4) but DerivedClass::value_ uses the config-value of DerivedClass (and therefore 10.1).

More

There are many other features that come with config-values, for example configurable arrays or modifier functions. Read the related wiki page to learn more:

• doc/ConfigValueIncludes