[ADD] - some doc in the template module concerning information properties.

src/common/WProperties.cpp

@@ -91,6 +91,13 @@ void WProperties::addProperty( boost::shared_ptr< WPropertyBase > prop )
         }
     }
 
+    // PV_PURPOSE_INFORMATION groups do not allow PV_PURPOSE_PARAMETER properties but vice versa.
+    if ( getPurpose() == PV_PURPOSE_INFORMATION )
+    {
+        prop->setPurpose( PV_PURPOSE_INFORMATION );
+    }
+    // INFORMATION properties are allowed inside PARAMETER groups -> do not set the properties purpose.
+
     m_propAccess->get().push_back( prop );
     m_propAccess->endWrite();
 }

src/kernel/WModule.cpp

@@ -66,6 +66,7 @@ WModule::WModule():
     // initialize members
     m_properties = boost::shared_ptr< WProperties >( new WProperties( "Properties", "Module's properties" ) );
     m_infoProperties = boost::shared_ptr< WProperties >( new WProperties( "Informational Properties", "Module's information properties" ) );
+    m_infoProperties->setPurpose( PV_PURPOSE_INFORMATION );
 
     m_active = m_properties->addProperty( "active", "Determines whether the module should be activated.", true, true );
     m_active->getCondition()->subscribeSignal( boost::bind( &WModule::activate, this ) );

src/modules/template/WMTemplate.cpp

@@ -233,9 +233,21 @@ void WMTemplate::properties()
     // Additionally, your can also use the m_active variable directly in your update callbacks to en-/disable some OSG nodes.
     // This template module uses method number 1. This might be the easiest and most commonly used way.
 
-    // TODO(ebaum): write
+    // Sometimes it is desirable to provide some values, statistics, counts, times, ... to the user. This would be possible by using a property
+    // and set the value to the value you want to show the user. Nice, but the user can change this value. PropertyConstraints can't help here,
+    // as they would forbid writing any value to the property (regardless if the module or the user wants to set it). In other words, these
+    // special properties serve another purpose. They are used for information output. Your module already provides another property list only
+    // for these kind of properties. m_infoProperties can be used in the same way as m_properties. The only difference is that each property and
+    // property group added here can't be modified from the outside world. Here is an example:
     m_aIntegerOutput = m_infoProperties->addProperty( "Run Count", "Number of run cycles the module made so far.", 0 );
-    m_aIntegerOutput->setPurpose( PV_PURPOSE_INFORMATION );
+    // Later on, we will use this property to provide the number of run cycles to the user.
+    // In more detail, the purpose type of the property gets set to PV_PURPOSE_INFORMATION automatically by m_infoProperties. You can, of course,
+    // add information properties to your custom groups or m_properties too. There, you need to set the purpose flag of the property manually:
+    m_aStringOutput = m_group1a->addProperty( "Hello World in C", "The hello world command in C.", std::string( "printf(\"Hello World!\");" ) );
+    m_aStringOutput->setPurpose( PV_PURPOSE_INFORMATION );
+    // This adds the property m_aStringOutput to your group and sets its purpose. The default purpose for all properties is always
+    // "PV_PURPOSE_PARAMETER". It simply denotes the meaning of the property - its meant to be used as modifier for the module's behaviour; a
+    // parameter.
 }
 
 void WMTemplate::moduleMain()

src/modules/template/WMTemplate.h

@@ -191,6 +191,11 @@ private:
      */
     WPropInt      m_aIntegerOutput;
 
+    /**
+     * A property simply providing some text to the outside world.
+     */
+    WPropString   m_aStringOutput;
+
     /**
      * Node callback to change the color of the shapes inside the root node. For more details on this class, refer to the documentation in
      * moduleMain().