= !ConfigValueContainer =

== Description ==

The [wiki:ConfigValueContainer] is a class that manages config-values. A config-value is a member-variable of a class that can be changed through the config-file. The config-file is usually ''orxonox.ini''. A new config-value can be defined by using the !SetConfigValue(varname, defvalue) macro (you have to include [wiki:CoreIncludes CoreIncludes.h] to use it), where ''varname'' is a member variable of a class. The macro-call must take place in the setConfigValues() function of this class. This allows the user to change the value of the variable ingame by using console-commands or the menu.

Every config-value has it's own [wiki:ConfigValueContainer]. The container is stored in a map inside the [wiki:Identifier] of the corresponding class. That way it's possible to iterate through all [wiki:ConfigValueContainers] of a class.

Calling setConfigValues() of an object causes all [wiki:ConfigValueContainers] of it's class to assign the stored values to the variables of the object. The values are initially read from the config-file but can be changed during the game by using console-commands or the menu. It's possible to change variables only temporary without saving the new value in the config-file, but usually changes are saved.

== Functions ==

 * '''!ConfigValueContainer('''''classname''''', '''''varname''''', '''''defvalue''''')''': The constructor creates a new config-value with given name and default value of a class with the given name.
 * '''getValue('''''pointer''''')''': Assigns the stored value to the ''pointer''. ''pointer'' must point to a variable of the same type as stored in the container. This functions is used to assign the values to all instances of a class.
 * '''description('''''string''''')''': Adds a description to the config-value. The description gets exported to the [wiki:Language]-file and can be localised.
 * '''resetConfigValue()''': Sets the config-value and the entry in the config-file back to the default value.

== Macros ==

 * '''!SetConfigValue('''''varname''''', '''''defvalue''''')''': Defines a new config-value with a default value. ''varname'' must be a member-variable of a class and the macro should only be used in the setConfigValues() function of this class to allow ingame-changes of the values. A description can be set by adding '''.description('''''string''''')''' at the end of the macro.
 * '''!ResetConfigValue('''''varname''''')''': Sets the given config-value back to the default value.

== 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
}}}

== The config-file ==