Changes between Initial Version and Version 1 of code/howto/ConfigValue

Timestamp:

Oct 11, 2008, 2:35:05 AM (16 years ago)

Author:

landauf

Comment:

—

code/howto/ConfigValue

@@ +1 @@
+= HowTo: ConfigValue =
+[[TracNav(TracNav/TOC_Development)]]
+
+== Description ==
+Config-values are member variables of a class that can be configured in the [wiki:howto/ConfigFile config-file]. The configured value will be assigned to every instance of this class.
+
+To use config-values in your class, you have to follow those steps:
+ 1. Inherit from [wiki:OrxonoxClass] or a derivative
+ 1. Then you have to add {{{void setConfigValues()}}} to the class
+ 1. Include [wiki:ConfigValueIncludes core/ConfigValueIncludes.h] in the source file
+ 1. Add '''SetConfigValue('''''variable, defaultvalue''''')''' macro-calls into {{{setConfigValues()}}}
+ 1. Call {{{setConfigValues()}}} from the constructor of your class
+
+== Example ==
+
+*.h file:
+{{{
+class MyClass : public SomeObject     (1)
+{
+    public:
+        MyClass();
+        void setConfigValues();       (2)
+
+        ...
+
+    private:
+        float value_;
+};
+}}}
+
+*.cc file:
+{{{
+#include "core/CoreIncludes.h"
+#include "core/ConfigValueIncludes.h" (3)
+
+// Constructor:
+MyClass::MyClass()
+{
+    RegisterObject(MyClass);
+
+    this->setConfigValues();          (5)
+}
+
+void MyClass::setConfigValues()
+{
+    SetConfigValue(value_, 123.4);    (4)
+}
+}}}
+
+== Inheritance ==
+There are three possible ways to deal with inheritance and config-values:
+=== Use a config-value in derived classes ===
+If a config-value is defined for a base-class, all derived classes will be configured by this value.
+
+'''Example''':
+
+{{{BaseClass}}} implements a config value:
+{{{
+class BaseClass : public OrxonoxClass
+{
+    public:
+        ...
+        void setConfigValues();
+
+    protected:
+        float value_;
+};
+
+void BaseClass::setConfigValues()
+{
+    SetConfigValue(value_, 123.4);
+}
+}}}
+
+{{{DerivedClass}}} inherits from {{{BaseClass}}} without implementing {{{setConfigValues}}} again:
+{{{
+class DerivedClass : public BaseClass
+{
+};
+}}}
+
+In the config-file this will look like this:
+{{{
+[BaseClass]
+value_=123.4
+}}}
+Then {{{BaseClass::value_}}} and {{{DerivedClass::value_}}} are both set by the config-value of {{{BaseClass}}} (and therefore 123.4).
+
+=== Implementing a config-value only in a derived class ===
+It's possible to define a config-value for a variable which was inherited from a base class.
+
+'''Example''':
+
+{{{BaseClass}}} declares a variable but no config-value:
+{{{
+class BaseClass : public OrxonoxClass
+{
+    ...
+
+    protected:
+        float baseValue_;
+};
+}}}
+
+{{{DerivedClass}}} derives from {{{BaseClass}}} and implements the config-value:
+{{{
+class DerivedClass : public BaseClass
+{
+    public:
+        ...
+        void setConfigValues();
+};
+
+void DerivedClass::setConfigValues()
+{
+    SetConfigValue(baseValue_, 10.1);
+}
+}}}
+
+In the config-file this will look like this:
+{{{
+[DerivedClass]
+value_=10.1
+}}}
+
+Then {{{DerivedClass::baseValue_}}} is set by the config-value (and therefore 10.1) but {{{BaseClass::baseValue_}}} isn't configurable.
+
+=== Overwriting config-values in a derived class ===
+If both, a base class and a derived class, implement the same value, instances of the base class use the configured value from the config-value-section of the base class while instances of the derived class (and further derived classes) use the overwritten value.
+
+'''Example''':
+
+{{{BaseClass}}} implements a config value:
+{{{
+class BaseClass : public OrxonoxClass
+{
+    public:
+        ...
+        void setConfigValues();
+
+    protected:
+        float value_;
+};
+
+void BaseClass::setConfigValues()
+{
+    SetConfigValue(value_, 123.4);
+}
+}}}
+
+{{{DerivedClass}}} derives from {{{BaseClass}}} and implements the config-value again:
+{{{
+class DerivedClass : public BaseClass
+{
+    public:
+        ...
+        void setConfigValues();
+};
+
+void DerivedClass::setConfigValues()
+{
+    SetConfigValue(value_, 10.1);
+}
+}}}
+
+In the config-file this will look like this:
+{{{
+[BaseClass]
+value_=123.4
+
+[DerivedClass]
+value_=10.1
+}}}
+
+Then {{{BaseClass::value_}}} is set by the config-value of {{{BaseClass}}} (and therefore 123.4) but {{{DerivedClass::value_}}} uses the config-value of {{{DerivedClass}}} (and therefore 10.1).