Changes between Initial Version and Version 1 of code/doc/ConfigValueContainer

Timestamp:

Feb 27, 2008, 7:17:38 PM (16 years ago)

Author:

landauf

Comment:

—

code/doc/ConfigValueContainer

@@ +1 @@
+= !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 ==
+
+