ConfigValueContainer

TracNav(TracNav/TOC_Documentation)?

Description

The 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 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 ConfigValueContainer. The container is stored in a map inside the Identifier of the corresponding class. That way it's possible to iterate through all ConfigValueContainers of a class.

Calling setConfigValues() of an object causes all 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 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:

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

The config-file

The config-file (usually orxonox.ini) has a clear structure, split into sections, where each section belongs to one class. A new section is introduced by a line containing the name of the class in square brackets:

[ClassName]

The following lines contain all config-values of the class in the following form:

varname=value

The config file adds missing variables or sections and repairs unreadable values by resetting them to the default value, but it doesn't change or remove needless entries. This allows you to add comments or funny ASCII-art. Whitespaces are ignored, so you can format your config-file in every way you like.

You can begin a line with a comment-symbol to ignore a line. If this removes an entry, a new one gets added to the end of the section, but you could add two versions of a line and comment one (for example when you want to test different settings without losing the previous value). There are four different comment-symbols:

• #comment: script-language style
• %comment: matlab style
• ;comment: unreal tournament config-file style
• comment: code style

Different variable-types have different formattings in the config file. There are three different cases:

• Primitives: varname=value
• Strings: varname="string"
• Complex types (like vectors): varname=(value1, …, valueN)

• Additionally booleans can be denoted by using true or false.

There are four cases causing the parser to change the config-file:

1. Case: A config-value is set, but can't be parsed (wrong formatting) or can't be converted to the wanted type:
   • Change: The value is set back to the default
2. Case: A config-value is missing but the section of the corresponding class exists:
   • Change: The value is added at the end of the section
3. Case: The whole section is missing or can't be found because the [ClassName]-line is missing:
   • Change: The whole section is added at the end of the file
4. Case: The config-file is missing:
   • Change: The config-file is created and all sections and values are written to the file.

Example of a valid config-file:

[MyClass] <-- This name is stupid
firstValue_  = 1.000000
secondValue_ = 1.0
thirdValue_  = 1

[OtherClass] <-- This name is even worse
//teststring = "test"
teststring = "teeeeeeeeeeeest"

[StupidNamedClass] <-- This name rocks
position1_=(1.0, 2.0, 3.0)
position2_ = ( 1.000000 , 2.000000 , 3.000000 )
    position3_ =      (1,2,3)

gagagugubleeeeeeeeeep!

[LastClass] <-- Where did you know...? Now this is scary...
moo_ = "Oh yes they do!"
bTheyMoo_ = true