= HowTo: ConfigValue =
[[TracNav(TracNav/TOC_Development)]]
[[TOC]]

== Description ==
Config-values are member variables of a class that can be configured in the [wiki:howto/ConfigFile 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 [wiki:OrxonoxClass] or a derivative
 1. Then you have to add {{{void setConfigValues()}}} to the class
 1. Include [wiki:ConfigValueIncludes core/ConfigValueIncludes.h] in the source file
 1. Add '''SetConfigValue('''''variable, defaultvalue''''')''' macro-calls into {{{setConfigValues()}}}
 1. 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:
 * [wiki:ConfigValueIncludes]