ConfigValueIncludes

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: howto/ConfigValue
• How to use the config-file: 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 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 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 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 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:

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:

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:

MyObject orxonoxobject;
std::cout << "Name:    " << orxonoxobject.getName() << std::endl;
std::cout << "Version: " << orxonoxobject.getVersion() << std::endl;

Output:

Name:    Orxonox
Version: 1.1

Inheritance

Read howto/ConfigValue to learn more about the three possible ways of using inheritance and config-values.