[ADD #174] added tutorial to template module for this issue and added some convenience methods.

src/core/common/WItemSelectionItem.h

@@ -25,6 +25,8 @@
 #ifndef WITEMSELECTIONITEM_H
 #define WITEMSELECTIONITEM_H
 
+#include <boost/shared_ptr.hpp>
+
 #include <string>
 
 /**
@@ -33,6 +35,16 @@
 class WItemSelectionItem // NOLINT
 {
 public:
+    /**
+     * Abbreviation for a shared pointer.
+     */
+    typedef boost::shared_ptr< WItemSelectionItem > SPtr;
+
+    /**
+     * Abbreviation for a const shared pointer.
+     */
+    typedef boost::shared_ptr< const WItemSelectionItem > ConstSPtr;
+
     /**
      * Constructs a new item with the specified values.
      *

src/core/common/WItemSelectionItemTyped.h

@@ -28,6 +28,8 @@
 #include <cstddef>
 #include <string>
 
+#include <boost/shared_ptr.hpp>
+
 #include "WItemSelectionItem.h"
 
 /**
@@ -41,6 +43,21 @@ template< typename T >
 class WItemSelectionItemTyped: public WItemSelectionItem // NOLINT
 {
 public:
+    /**
+     * Abbreviation for a shared pointer.
+     */
+    typedef boost::shared_ptr< WItemSelectionItemTyped< T > > SPtr;
+
+    /**
+     * Abbreviation for a const shared pointer.
+     */
+    typedef boost::shared_ptr< const WItemSelectionItemTyped< T > > ConstSPtr;
+
+    /**
+     * The type of the value stored in here.
+     */
+    typedef T ValueType;
+
     /**
      * Constructs a new item with the specified values.
      *
@@ -62,6 +79,21 @@ public:
     {
     }
 
+    /**
+     * Create a instance of the item. This shortens the rather long call which would be needed to create a shared pointer of this class.
+     *
+     * \param value the value to store in the instance
+     * \param name the name of item
+     * \param description Description of the item. Can be empty.
+     * \param icon the icon of the item. Can be NULL.
+     *
+     * \return a new instance pointer
+     */
+    static SPtr create( T value, std::string name, std::string description = "", const char** icon = NULL )
+    {
+        return SPtr( new WItemSelectionItemTyped< T >( value, name, description, icon ) );
+    }
+
     /**
      * Returns the value. This const version is especially useful when using reference types for T.
      *

src/modules/template/WMTemplate.cpp

@@ -65,6 +65,10 @@
 #include "core/common/WColor.h"
 #include "core/common/WPathHelper.h"
 #include "core/common/WPropertyHelper.h"
+#include "core/common/WItemSelection.h"
+#include "core/common/WItemSelectionItem.h"
+#include "core/common/WItemSelectionItemTyped.h"
+#include "core/common/WItemSelector.h"
 #include "core/graphicsEngine/WGEUtils.h"
 #include "core/graphicsEngine/WGERequirement.h"
 
@@ -234,6 +238,29 @@ void WMTemplate::properties()
     m_aMultiSelection  = m_properties->addProperty( "I like", "What do you like.", m_possibleSelections->getSelectorAll(),
                                                     m_propCondition );
 
+    // The last examples showed you how to create more or less complex selections. You where able to define a name, description and some icon for
+    // each selectable item. But maybe you want to store additional information, a class implementing some function (like a strategy pattern),
+    // and similar. To achieve this, we provide a special item class called WItemSelectionItemTyped. It is a templatized class which allows you
+    // to add a value of an arbitrary type to each item. This value of an arbitrary type might be a pointer, string, int, or a custom class'
+    // instance.
+    m_possibleSelectionsUsingTypes = WItemSelection::SPtr( new WItemSelection() );
+    m_possibleSelectionsUsingTypes->addItem( MyItemType::create(
+                "The value 1",  // this is the value for the type we specified: std::string.
+                "Option 1",
+                "Description for the first option"
+        )
+    );
+    m_possibleSelectionsUsingTypes->addItem( MyItemType::create(
+                "The value 2",  // this is the value for the type we specified: std::string.
+                "Option 2",
+                "Description for the second option"
+        )
+    );
+    // This now created the selections. We store a string inside each item. But remember again: this can by ANY type.
+    // Finally, add a property by specifying the selector of the selection:
+    m_aSingleSelectionUsingTypes = m_properties->addProperty( "Choose one", "Choose on of these and watch the console output.",
+                                                              m_possibleSelectionsUsingTypes->getSelectorFirst(), m_propCondition );
+
     // Adding a lot of properties might confuse the user. Using WPropGroup, you have the possibility to group your properties together. A
     // WPropGroup needs a name and can provide a description. As with properties, the name should not contain any "/" and must be unique.
 
@@ -282,6 +309,8 @@ void WMTemplate::properties()
     // element to be selected:
     WPropertyHelper::PC_SELECTONLYONE::addTo( m_aSingleSelection );
     WPropertyHelper::PC_NOTEMPTY::addTo( m_aSingleSelection );
+    WPropertyHelper::PC_SELECTONLYONE::addTo( m_aSingleSelectionUsingTypes );
+    WPropertyHelper::PC_NOTEMPTY::addTo( m_aSingleSelectionUsingTypes );
     WPropertyHelper::PC_NOTEMPTY::addTo( m_aMultiSelection );
 
     // The most amazing feature is: custom constraints. Similar to OSG update callbacks, you just need to write your own PropertyConstraint class
@@ -654,6 +683,21 @@ void WMTemplate::moduleMain()
             }
         }
 
+        // This checks the selections with our additional value.
+        if( m_aSingleSelectionUsingTypes->changed() )
+        {
+            // The single selector allows only one selected item and requires one item to be selected all the time. So accessing it by index
+            // is trivial:
+            WItemSelector s = m_aSingleSelectionUsingTypes->get( true );
+            infoLog() << "The item value is: " << s.at( 0 )->getAs< MyItemType >()->getValue() <<
+                         ". Length: " << s.at( 0 )->getAs< MyItemType >()->getValue().length();
+
+            // This showed that you can add values of your arbitrary type into the selection. Assume this is an object providing a ()-operator.
+            // You can then use s.at( 0 )->getAs< MyItemType >()->getValue()() to call this operator. This< is very handy for implementing
+            // strategies. But before you get too excited about this, for strategies with automatic, complex property handling, you should have
+            // a look at WStrategyHelper!
+        }
+
         // Trigger an exception? We do this whenever the user pressed the exception-button
         if( m_exceptionTrigger->get( true ) == WPVBaseTypes::PV_TRIGGER_TRIGGERED )
         {

src/modules/template/WMTemplate.h

@@ -210,6 +210,11 @@ private:
      */
     WPropSelection m_aSingleSelection;
 
+    /**
+     * A property allowing the user to select ONE item. This additionally demonstrates how to use your own types/classes in selections.
+     */
+    WPropSelection m_aSingleSelectionUsingTypes;
+
     /**
      * A property allowing the user to select multiple elements of a list.
      */
@@ -267,6 +272,16 @@ private:
      */
     boost::shared_ptr< WItemSelection > m_possibleSelections;
 
+    /**
+     * You should typedef the item type you use. This shortens some code later. We encapsulate a string into an item.
+     */
+    typedef WItemSelectionItemTyped< std::string > MyItemType;
+
+    /**
+     * A list of items that can be selected using m_aSingleSelectionUsingTypes property.
+     */
+    boost::shared_ptr< WItemSelection > m_possibleSelectionsUsingTypes;
+
     /**
      * A Property used to show the callback mechanism avoiding the thread wake up on change.
      */