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

Timestamp:

Oct 8, 2008, 12:45:52 AM (17 years ago)

Author:

landauf

Comment:

—

code/doc/ConfigValueIncludes

@@ +1 @@
+= !ConfigValueIncludes =
+[[TracNav(TracNav/TOC_Development)]]
+[[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 configuers another value.
+
+'''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.
+
+=== 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 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
+}}}
+