= !ConfigValueIncludes =
[[TOC]]

== Description ==
core/ConfigValueIncludes.h is a header file, defining several useful macros to create and modify config-values.

Related pages:
 * How to create a config-value: [wiki:howto/ConfigValue]
 * How to use the config-file: [wiki:howto/ConfigFile]

== Macros ==
=== SetConfigValue ===

'''SetConfigValue('''''varname, defvalue''''')''' defines a new config-value with a default value. ''varname'' must be a member-variable of a class. ''defvalue'' is the default value that will be initially used until the user configures another value. The type of the value can be everything supportet by [wiki:MultiType].

'''Important''': SetConfigValue '''must''' be used within setConfigValues(). This is a function that gets called to assign the configured values to an object. Additionally setConfigValues() '''must''' be called within the constructor of the class.

It's possible to overwrite config-values in derived classes by just declaring the value again with SetConfigValue.

You can describe a config-value by adding '''.description('''''string''''')''' at the end of the macro.

You can set a callback function that gets called as soon as the config-value changes by adding '''.callback('''''this, &classname::functionname''''')''' at the end of the macro.


=== SetConfigValueVector ===
'''SetConfigValueVector('''''varname, defvalue''''')''' defines a new configurable vector with a default value. Value and default value must be a std::vector<type> where type can be everything supportet by [wiki:MultiType].

Otherwise SetConfigValueVector is just like SetConfigValue; the same features, the same restrictions.

In the config-file a vector is slightly different to a simple config-value. The vector entries are named "varname[index]" where ''index'' goes from zero until the vectors size. If the user adds a new entry with ''index > vector.size()'' the numbers between are added too but without a value.

=== ResetConfigValue ===
'''ResetConfigValue('''''varname''''')''' sets the given config-value '''and''' the value in the config-file back to the default value. ''varname'' is the name of the config-value.

=== ModifyConfigValue ===
'''ModifyConfigValue('''''varname, modifier, ...''''')''' modifies a given config-value.  ''varname'' is the name of the config-value. ''modifier'' is a function of [wiki:ConfigValueContainer]. By calling this macro, the specified function get's called in the container of the given config-value. ''...'' are arguments passed to the modifier-function.

Possible modifier functions are:
 * Simple config-values:
  * '''set''', ''value'': Sets the config-value to a given value, changes the entry in the config-file and assigns the value to all existing instances of the values class.
  * '''tset''', ''value'': Does the same like '''set''' but without changing the config-file (therefore the change will be lost if you restart Orxonox).

 * Vectors:
  * '''set''', ''index'', ''value'': Does the same like '''set''' for simple config-values but only for a given element of the vector
  * '''tset''', ''index'', ''value'': Does the same like '''tset''' for simple config-values but only for a given element of the vector
  * '''add''', ''value'': Adds a new element with a given value to the end of the vector 
  * '''remove''', ''index'': Removes a given element from the vector

 * Both:
  * '''reset''': Sets the given config-value '''and''' the value in the config-file back to the default value (just like [wiki:ConfigValueIncludes#ResetConfigValue ResetConfigValue]).
  * '''update''': Reloads the config-value from the config-file and assigns the value to all existing instances of the values class.

== Example ==
Definition of a class in the header-file:
{{{
#!cpp
class MyClass : public BaseObject
{
  public:
    MyClass();              // Constructor
    void setConfigValues(); // Inherited function

    const std::string& getName()
      { return this->name_; }

    float getVersion()
      { return this->version_; }

  private:
    std::string name_;
    float version_;    
};
}}}

Implementation of the class source-file:
{{{
#!cpp
MyClass::MyClass()
{
  // Macro call to create an Identifier
  RegisterObject(MyClass);

  // Function call to assign the config-values to the new object
  this->setConfigValues();
}

void MyClass::setConfigValues()
{
  SetConfigValue(name_, "Orxonox").description("The name of the game");
  SetConfigValue(version_, "1.0").description("The version-number");
}
}}}

Extract of orxonox.ini:
{{{
[MyClass]
name_="Orxonox"
version_=1.1 // We have changed this value from 1.0 to 1.1
}}}

Some other code:
{{{
#!cpp
MyObject orxonoxobject;
std::cout << "Name:    " << orxonoxobject.getName() << std::endl;
std::cout << "Version: " << orxonoxobject.getVersion() << std::endl;
}}}

Output:
{{{
Name:    Orxonox
Version: 1.1
}}}

== Inheritance ==
Read [wiki:howto/ConfigValue#Inheritance] to learn more about the three possible ways of using inheritance and config-values.