WProperties.h

00001 //---------------------------------------------------------------------------
00002 //
00003 // Project: OpenWalnut ( http://www.openwalnut.org )
00004 //
00005 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
00006 // For more information see http://www.openwalnut.org/copying
00007 //
00008 // This file is part of OpenWalnut.
00009 //
00010 // OpenWalnut is free software: you can redistribute it and/or modify
00011 // it under the terms of the GNU Lesser General Public License as published by
00012 // the Free Software Foundation, either version 3 of the License, or
00013 // (at your option) any later version.
00014 //
00015 // OpenWalnut is distributed in the hope that it will be useful,
00016 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00018 // GNU Lesser General Public License for more details.
00019 //
00020 // You should have received a copy of the GNU Lesser General Public License
00021 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
00022 //
00023 //---------------------------------------------------------------------------
00024 
00025 #ifndef WPROPERTIES_H
00026 #define WPROPERTIES_H
00027 
00028 #include <map>
00029 #include <string>
00030 #include <vector>
00031 
00032 #include <boost/thread/thread.hpp>
00033 #include <boost/thread/mutex.hpp>
00034 #include <boost/thread/locks.hpp>
00035 #include <boost/thread.hpp>
00036 
00037 #include "WConditionSet.h"
00038 #include "WPropertyBase.h"
00039 #include "WPropertyTypes.h"
00040 #include "WPropertyVariable.h"
00041 #include "WSharedSequenceContainer.h"
00042 #include "exceptions/WPropertyNotUnique.h"
00043 
00044 #include "WExportCommon.h"
00045 
00046 /**
00047  * Class to manage properties of an object and to provide convenience methods for easy access and manipulation. It also allows
00048  * thread safe iteration on its elements. The main purpose of this class is to group properties together and to allow searching properties by a
00049  * given name. The name of each property in a group has to be unique and is constructed using the group names containing them: hello/you/property
00050  * is the property with the name "property" in the group "you" which against is in the group "hello".
00051  * \note The root group of each module does not have a name.
00052  */
00053 class OWCOMMON_EXPORT WProperties: public WPropertyBase
00054 {
00055 friend class WPropertiesTest;
00056 public:
00057 
00058     // the following typedefs are for convenience.
00059     typedef boost::shared_ptr< WProperties > SPtr; //!< shared pointer to object of this type
00060     typedef boost::shared_ptr< const WProperties > ConstSPtr; //!< const shared pointer to object of this type
00061     typedef WProperties* Ptr; //!< pointer to object of this type
00062     typedef const WProperties* ConstPtr; //!< const pointer to object of this type
00063     typedef WProperties& Ref; //!< ref to object of this type
00064     typedef const WProperties& ConstRef; //!< const ref to object of this type
00065 
00066     /**
00067      * For shortening: a type defining a shared vector of WSubject pointers.
00068      */
00069     typedef std::vector< boost::shared_ptr< WPropertyBase > > PropertyContainerType;
00070 
00071     /**
00072      * The alias for a shared container.
00073      */
00074     typedef WSharedSequenceContainer< PropertyContainerType > PropertySharedContainerType;
00075 
00076     /**
00077      * The const iterator type of the container.
00078      */
00079     typedef PropertyContainerType::const_iterator PropertyConstIterator;
00080 
00081     /**
00082      * The iterator type of the container.
00083      */
00084     typedef PropertyContainerType::iterator PropertyIterator;
00085 
00086     /**
00087      * Constructor. Creates an empty list of properties.
00088      *
00089      * \note WModule::getProperties always returns an unnamed instance.
00090      *
00091      * \param name the name of the property group. The GUI is using this name for naming the tabs/group boxes
00092      * \param description the description of the group.
00093      */
00094     WProperties( std::string name = "unnamed group", std::string description = "an unnamed group of properties" );
00095 
00096     /**
00097      * Copy constructor. Creates a deep copy of this property. As boost::signals2 and condition variables are non-copyable, new instances get
00098      * created. The subscriptions to a signal are LOST as well as all listeners to a condition.
00099      * The conditions you can grab using getValueChangeConditon and getCondition are not the same as in the original! This is because
00100      * the class corresponds to the observer/observable pattern. You won't expect a clone to fire a condition if a original flag is changed
00101      * (which after cloning is completely decoupled from the clone).
00102      *
00103      * \note the properties inside this list are also copied deep
00104      *
00105      * \param from the instance to copy.
00106      */
00107     explicit WProperties( const WProperties& from );
00108 
00109     /**
00110      * destructor
00111      */
00112     virtual ~WProperties();
00113 
00114     /**
00115      * This method clones a property and returns the clone. It does a deep copy and, in contrast to a copy constructor, creates property with the
00116      * correct type without explicitly requiring the user to specify it. It creates a NEW change condition and change signal. This means, alls
00117      * subscribed signal handlers are NOT copied.
00118      *
00119      * \note this simply ensures the copy constructor of the runtime type is issued.
00120      *
00121      * \return the deep clone of this property.
00122      */
00123     virtual boost::shared_ptr< WPropertyBase > clone();
00124 
00125     /**
00126      * Simply insert the specified property to the list.
00127      *
00128      * \param prop the property to add
00129      *
00130      * \return The given prop.
00131      */
00132     template< typename PropType >
00133     PropType addProperty( PropType prop );
00134 
00135     /**
00136      * Simply remove the specified property from the list. If the given property is not in the list, nothing happens.
00137      *
00138      * \param prop the property to remove.
00139      */
00140     void removeProperty( boost::shared_ptr< WPropertyBase > prop );
00141 
00142     /**
00143      * Helper function that finds a property by its name. Use this method to find out whether the property exists or not, since
00144      * findProperty throws an exception.
00145      *
00146      * \param name name of searched property.
00147      *
00148      * \return Answer to the question whether the property exists.
00149      */
00150     bool existsProperty( std::string name );
00151 
00152     /**
00153      * Function searches the property. If it does not exists, it throws an exception.
00154      *
00155      * \param name the name of the property
00156      *
00157      * \return a WProperty object
00158      */
00159     boost::shared_ptr< WPropertyBase > getProperty( std::string name );
00160 
00161     /**
00162      * Returns a read ticket for read-access to the list of properties.
00163      *
00164      * \return the read ticket.
00165      */
00166     PropertySharedContainerType::ReadTicket getProperties() const;
00167 
00168     /**
00169      * Returns an read ticket for the properties. This, and only this, has to be used for external iteration of properties.
00170      *
00171      * \see WSharedObjectTicketRead
00172      * \return the read ticket.
00173      */
00174     PropertySharedContainerType::ReadTicket getReadTicket() const;
00175 
00176     /**
00177      * Searches the property with a given name. It does not throw any exception. It simply returns NULL if it can't be found.
00178      *
00179      * \param name the name of the property to search
00180      *
00181      * \return the property or NULL if not found.
00182      */
00183     boost::shared_ptr< WPropertyBase > findProperty( std::string name ) const;
00184 
00185     /**
00186      * Removes all properties from the list.
00187      */
00188     virtual void clear();
00189 
00190     ///////////////////////////////////////////////////////////////////////////////////////////////////
00191     // Convenience methods to create and add properties
00192     ///////////////////////////////////////////////////////////////////////////////////////////////////
00193 
00194     /**
00195      * Create and add a new property group. Use these groups to structure your properties.
00196      *
00197      * \param name the name of the group.
00198      * \param description the description of the group.
00199      * \param hide true if group should be completely hidden.
00200      *
00201      * \return The newly created property group.
00202      */
00203     WPropGroup addPropertyGroup( std::string name, std::string description, bool hide = false );
00204 
00205     /**
00206      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00207      *
00208      * \see WPropertyVariable
00209      *
00210      * \param name  the property name
00211      * \param description the property description
00212      * \param initial the initial value
00213      * \param hide set to true to set the hide flag directly.
00214      *
00215      * \return the newly created property variable instance.
00216      */
00217     template< typename T>
00218     boost::shared_ptr< WPropertyVariable< T > > addProperty( std::string name, std::string description, const T& initial, bool hide = false );
00219 
00220     /**
00221      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00222      *
00223      * \see WPropertyVariable
00224      *
00225      * \param name  the property name
00226      * \param description the property description
00227      * \param initial the initial value
00228      * \param condition use this external condition for notification.
00229      * \param hide set to true to set the hide flag directly.
00230      *
00231      * \return the newly created property variable instance.
00232      */
00233     template< typename T>
00234     boost::shared_ptr< WPropertyVariable< T > > addProperty( std::string name, std::string description, const T& initial,
00235                                                              boost::shared_ptr< WCondition > condition, bool hide = false );
00236 
00237     /**
00238      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00239      *
00240      * \see WPropertyVariable
00241      *
00242      * \param name  the property name
00243      * \param description the property description
00244      * \param initial the initial value
00245      * \param notifier use this notifier for change callbacks.
00246      * \param hide set to true to set the hide flag directly.
00247      *
00248      * \return the newly created property variable instance.
00249      */
00250     template< typename T>
00251     boost::shared_ptr< WPropertyVariable< T > > addProperty( std::string name, std::string description, const T& initial,
00252                                                              WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00253 
00254     /**
00255      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00256      *
00257      * \see WPropertyVariable
00258      *
00259      * \param name  the property name
00260      * \param description the property description
00261      * \param initial the initial value
00262      * \param notifier use this notifier for change callbacks.
00263      * \param condition use this external condition for notification
00264      * \param hide set to true to set the hide flag directly.
00265      *
00266      * \return the newly created property variable instance.
00267      */
00268     template< typename T>
00269     boost::shared_ptr< WPropertyVariable< T > > addProperty( std::string name, std::string description, const T& initial,
00270                                                              boost::shared_ptr< WCondition > condition,
00271                                                              WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00272 
00273     /**
00274      * Gets the real type of this instance. In this case, PV_GROUP.
00275      *
00276      * \return the real type.
00277      */
00278     virtual PROPERTY_TYPE getType() const;
00279 
00280     /**
00281      * This methods allows properties to be set by a string value. This method does nothing here, as groups can not be set in any kind.
00282      *
00283      * \param value the new value to set. IGNORED.
00284      *
00285      * \return always true
00286      */
00287     virtual bool setAsString( std::string value );
00288 
00289     /**
00290      * Returns the current value as a string. This is useful for debugging or project files. It is not implemented as << operator, since the <<
00291      * should also print min/max constraints and so on. This simply is the value.
00292      *
00293      * \return the value as a string.
00294      */
00295     virtual std::string getAsString();
00296 
00297     /**
00298      * Sets the value from the specified property to this one. This is especially useful to copy a value without explicitly casting/knowing the
00299      * dynamic type of the property.
00300      *
00301      * \note for WProperties, this actually does nothing an.
00302      *
00303      * \param value the new value.
00304      *
00305      * \return true, always.
00306      */
00307     virtual bool set( boost::shared_ptr< WPropertyBase > value );
00308 
00309     /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00310     // Convenience methods to create and add properties
00311     // NOTE: these methods use the type of the initial parameter to automatically use the proper type.
00312     // This works, since the compiler always calls the function with the best matching parameter types.
00313     /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00314 
00315 
00316     /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00317     // convenience methods for
00318     // template< typename T>
00319     // boost::shared_ptr< WPropertyVariable< T > > addProperty( std::string name, std::string description, const T& initial, bool hide = false );
00320     /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00321 
00322     /**
00323      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00324      *
00325      * \see WPropertyVariable
00326      *
00327      * \param name  the property name
00328      * \param description the property description
00329      * \param initial the initial value
00330      * \param hide set to true to set the hide flag directly.
00331      *
00332      * \return the newly created property variable instance.
00333      */
00334     WPropBool      addProperty( std::string name, std::string description, const WPVBaseTypes::PV_BOOL&   initial, bool hide = false );
00335 
00336     /**
00337      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00338      * It also sets the min and max constraint to [0,100].
00339      *
00340      * \see WPropertyVariable
00341      *
00342      * \param name  the property name
00343      * \param description the property description
00344      * \param initial the initial value
00345      * \param hide set to true to set the hide flag directly.
00346      *
00347      * \return the newly created property variable instance.
00348      */
00349     WPropInt       addProperty( std::string name, std::string description, const WPVBaseTypes::PV_INT&    initial, bool hide = false );
00350 
00351     /**
00352      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00353      * It also sets the min and max constraint to [0,100].
00354      *
00355      * \see WPropertyVariable
00356      *
00357      * \param name  the property name
00358      * \param description the property description
00359      * \param initial the initial value
00360      * \param hide set to true to set the hide flag directly.
00361      *
00362      * \return the newly created property variable instance.
00363      */
00364     WPropDouble    addProperty( std::string name, std::string description, const WPVBaseTypes::PV_DOUBLE& initial, bool hide = false );
00365 
00366     /**
00367      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00368      *
00369      * \see WPropertyVariable
00370      *
00371      * \param name  the property name
00372      * \param description the property description
00373      * \param initial the initial value
00374      * \param hide set to true to set the hide flag directly.
00375      *
00376      * \return the newly created property variable instance.
00377      */
00378     WPropString    addProperty( std::string name, std::string description, const WPVBaseTypes::PV_STRING& initial, bool hide = false );
00379 
00380     /**
00381      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00382      *
00383      * \see WPropertyVariable
00384      *
00385      * \param name  the property name
00386      * \param description the property description
00387      * \param initial the initial value
00388      * \param hide set to true to set the hide flag directly.
00389      *
00390      * \return the newly created property variable instance.
00391      */
00392     WPropFilename  addProperty( std::string name, std::string description, const WPVBaseTypes::PV_PATH&   initial, bool hide = false );
00393 
00394     /**
00395      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00396      *
00397      * \see WPropertyVariable
00398      *
00399      * \param name  the property name
00400      * \param description the property description
00401      * \param initial the initial value
00402      * \param hide set to true to set the hide flag directly.
00403      *
00404      * \return the newly created property variable instance.
00405      */
00406     WPropSelection      addProperty( std::string name, std::string description, const WPVBaseTypes::PV_SELECTION&   initial, bool hide = false );
00407 
00408     /**
00409      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00410      *
00411      * \see WPropertyVariable
00412      *
00413      * \param name  the property name
00414      * \param description the property description
00415      * \param initial the initial value
00416      * \param hide set to true to set the hide flag directly.
00417      *
00418      * \return the newly created property variable instance.
00419      */
00420     WPropPosition      addProperty( std::string name, std::string description, const WPVBaseTypes::PV_POSITION&   initial, bool hide = false );
00421 
00422     /**
00423      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00424      *
00425      * \see WPropertyVariable
00426      *
00427      * \param name  the property name
00428      * \param description the property description
00429      * \param initial the initial value
00430      * \param hide set to true to set the hide flag directly.
00431      *
00432      * \return the newly created property variable instance.
00433      */
00434     WPropColor         addProperty( std::string name, std::string description, const WPVBaseTypes::PV_COLOR&  initial, bool hide = false );
00435 
00436     /**
00437      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00438      *
00439      * \see WPropertyVariable
00440      *
00441      * \param name  the property name
00442      * \param description the property description
00443      * \param initial the initial value
00444      * \param hide set to true to set the hide flag directly.
00445      *
00446      * \return the newly created property variable instance.
00447      */
00448     WPropTrigger       addProperty( std::string name, std::string description, const WPVBaseTypes::PV_TRIGGER&  initial, bool hide = false );
00449 
00450     /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00451     // convenience methods for
00452     // template< typename T>
00453     // boost::shared_ptr< WPropertyVariable< T > > addProperty( std::string name, std::string description, const T& initial,
00454     //                                                          boost::shared_ptr< WCondition > condition, bool hide = false );
00455     /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00456 
00457     /**
00458      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00459      *
00460      * \see WPropertyVariable
00461      *
00462      * \param name  the property name
00463      * \param description the property description
00464      * \param initial the initial value
00465      * \param condition use this external condition for notification.
00466      * \param hide set to true to set the hide flag directly.
00467      *
00468      * \return the newly created property variable instance.
00469      */
00470     WPropBool      addProperty( std::string name, std::string description, const WPVBaseTypes::PV_BOOL&   initial,
00471                                 boost::shared_ptr< WCondition > condition, bool hide = false );
00472 
00473     /**
00474      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00475      * It also sets the min and max constraint to [0,100].
00476      *
00477      * \see WPropertyVariable
00478      *
00479      * \param name  the property name
00480      * \param description the property description
00481      * \param initial the initial value
00482      * \param condition use this external condition for notification.
00483      * \param hide set to true to set the hide flag directly.
00484      *
00485      * \return the newly created property variable instance.
00486      */
00487     WPropInt       addProperty( std::string name, std::string description, const WPVBaseTypes::PV_INT&    initial,
00488                                 boost::shared_ptr< WCondition > condition, bool hide = false );
00489 
00490     /**
00491      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00492      * It also sets the min and max constraint to [0,100].
00493      *
00494      * \see WPropertyVariable
00495      *
00496      * \param name  the property name
00497      * \param description the property description
00498      * \param initial the initial value
00499      * \param condition use this external condition for notification.
00500      * \param hide set to true to set the hide flag directly.
00501      *
00502      * \return the newly created property variable instance.
00503      */
00504     WPropDouble    addProperty( std::string name, std::string description, const WPVBaseTypes::PV_DOUBLE& initial,
00505                                 boost::shared_ptr< WCondition > condition, bool hide = false );
00506 
00507     /**
00508      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00509      *
00510      * \see WPropertyVariable
00511      *
00512      * \param name  the property name
00513      * \param description the property description
00514      * \param initial the initial value
00515      * \param condition use this external condition for notification.
00516      * \param hide set to true to set the hide flag directly.
00517      *
00518      * \return the newly created property variable instance.
00519      */
00520     WPropString    addProperty( std::string name, std::string description, const WPVBaseTypes::PV_STRING& initial,
00521                                 boost::shared_ptr< WCondition > condition, bool hide = false );
00522 
00523     /**
00524      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00525      *
00526      * \see WPropertyVariable
00527      *
00528      * \param name  the property name
00529      * \param description the property description
00530      * \param initial the initial value
00531      * \param condition use this external condition for notification.
00532      * \param hide set to true to set the hide flag directly.
00533      *
00534      * \return the newly created property variable instance.
00535      */
00536     WPropFilename  addProperty( std::string name, std::string description, const WPVBaseTypes::PV_PATH&   initial,
00537                                 boost::shared_ptr< WCondition > condition, bool hide = false );
00538 
00539     /**
00540      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00541      *
00542      * \see WPropertyVariable
00543      *
00544      * \param name  the property name
00545      * \param description the property description
00546      * \param initial the initial value
00547      * \param condition use this external condition for notification.
00548      * \param hide set to true to set the hide flag directly.
00549      *
00550      * \return the newly created property variable instance.
00551      */
00552     WPropSelection addProperty( std::string name, std::string description, const WPVBaseTypes::PV_SELECTION&   initial,
00553                                 boost::shared_ptr< WCondition > condition, bool hide = false );
00554 
00555     /**
00556      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00557      *
00558      * \see WPropertyVariable
00559      *
00560      * \param name  the property name
00561      * \param description the property description
00562      * \param initial the initial value
00563      * \param condition use this external condition for notification.
00564      * \param hide set to true to set the hide flag directly.
00565      *
00566      * \return the newly created property variable instance.
00567      */
00568     WPropPosition  addProperty( std::string name, std::string description, const WPVBaseTypes::PV_POSITION&   initial,
00569                                 boost::shared_ptr< WCondition > condition, bool hide = false );
00570 
00571     /**
00572      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00573      *
00574      * \see WPropertyVariable
00575      *
00576      * \param name  the property name
00577      * \param description the property description
00578      * \param initial the initial value
00579      * \param condition use this external condition for notification.
00580      * \param hide set to true to set the hide flag directly.
00581      *
00582      * \return the newly created property variable instance.
00583      */
00584     WPropColor     addProperty( std::string name, std::string description, const WPVBaseTypes::PV_COLOR&   initial,
00585                                 boost::shared_ptr< WCondition > condition, bool hide = false );
00586 
00587     /**
00588      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00589      *
00590      * \see WPropertyVariable
00591      *
00592      * \param name  the property name
00593      * \param description the property description
00594      * \param initial the initial value
00595      * \param condition use this external condition for notification.
00596      * \param hide set to true to set the hide flag directly.
00597      *
00598      * \return the newly created property variable instance.
00599      */
00600     WPropTrigger   addProperty( std::string name, std::string description, const WPVBaseTypes::PV_TRIGGER&   initial,
00601                                 boost::shared_ptr< WCondition > condition, bool hide = false );
00602 
00603     /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00604     // convenience methods for
00605     // template< typename T>
00606     // boost::shared_ptr< WPropertyVariable< T > > addProperty( std::string name, std::string description, const T& initial,
00607     //                                                          WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00608     /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00609 
00610     /**
00611      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00612      *
00613      * \see WPropertyVariable
00614      *
00615      * \param name  the property name
00616      * \param description the property description
00617      * \param initial the initial value
00618      * \param notifier use this notifier for change callbacks.
00619      * \param hide set to true to set the hide flag directly.
00620      *
00621      * \return the newly created property variable instance.
00622      */
00623     WPropBool      addProperty( std::string name, std::string description, const WPVBaseTypes::PV_BOOL&   initial,
00624                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00625 
00626     /**
00627      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00628      * It also sets the min and max constraint to [0,100].
00629      *
00630      * \see WPropertyVariable
00631      *
00632      * \param name  the property name
00633      * \param description the property description
00634      * \param initial the initial value
00635      * \param notifier use this notifier for change callbacks.
00636      * \param hide set to true to set the hide flag directly.
00637      *
00638      * \return the newly created property variable instance.
00639      */
00640     WPropInt       addProperty( std::string name, std::string description, const WPVBaseTypes::PV_INT&    initial,
00641                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00642 
00643     /**
00644      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00645      * It also sets the min and max constraint to [0,100].
00646      *
00647      * \see WPropertyVariable
00648      *
00649      * \param name  the property name
00650      * \param description the property description
00651      * \param initial the initial value
00652      * \param notifier use this notifier for change callbacks.
00653      * \param hide set to true to set the hide flag directly.
00654      *
00655      * \return the newly created property variable instance.
00656      */
00657     WPropDouble    addProperty( std::string name, std::string description, const WPVBaseTypes::PV_DOUBLE& initial,
00658                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00659 
00660     /**
00661      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00662      *
00663      * \see WPropertyVariable
00664      *
00665      * \param name  the property name
00666      * \param description the property description
00667      * \param initial the initial value
00668      * \param notifier use this notifier for change callbacks.
00669      * \param hide set to true to set the hide flag directly.
00670      *
00671      * \return the newly created property variable instance.
00672      */
00673     WPropString    addProperty( std::string name, std::string description, const WPVBaseTypes::PV_STRING& initial,
00674                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00675 
00676     /**
00677      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00678      *
00679      * \see WPropertyVariable
00680      *
00681      * \param name  the property name
00682      * \param description the property description
00683      * \param initial the initial value
00684      * \param notifier use this notifier for change callbacks.
00685      * \param hide set to true to set the hide flag directly.
00686      *
00687      * \return the newly created property variable instance.
00688      */
00689     WPropFilename  addProperty( std::string name, std::string description, const WPVBaseTypes::PV_PATH&   initial,
00690                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00691 
00692     /**
00693      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00694      *
00695      * \see WPropertyVariable
00696      *
00697      * \param name  the property name
00698      * \param description the property description
00699      * \param initial the initial value
00700      * \param notifier use this notifier for change callbacks.
00701      * \param hide set to true to set the hide flag directly.
00702      *
00703      * \return the newly created property variable instance.
00704      */
00705     WPropSelection addProperty( std::string name, std::string description, const WPVBaseTypes::PV_SELECTION&   initial,
00706                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00707 
00708     /**
00709      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00710      *
00711      * \see WPropertyVariable
00712      *
00713      * \param name  the property name
00714      * \param description the property description
00715      * \param initial the initial value
00716      * \param notifier use this notifier for change callbacks.
00717      * \param hide set to true to set the hide flag directly.
00718      *
00719      * \return the newly created property variable instance.
00720      */
00721     WPropPosition  addProperty( std::string name, std::string description, const WPVBaseTypes::PV_POSITION& initial,
00722                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00723 
00724     /**
00725      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00726      *
00727      * \see WPropertyVariable
00728      *
00729      * \param name  the property name
00730      * \param description the property description
00731      * \param initial the initial value
00732      * \param notifier use this notifier for change callbacks.
00733      * \param hide set to true to set the hide flag directly.
00734      *
00735      * \return the newly created property variable instance.
00736      */
00737     WPropColor     addProperty( std::string name, std::string description, const WPVBaseTypes::PV_COLOR&  initial,
00738                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00739 
00740     /**
00741      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00742      *
00743      * \see WPropertyVariable
00744      *
00745      * \param name  the property name
00746      * \param description the property description
00747      * \param initial the initial value
00748      * \param notifier use this notifier for change callbacks.
00749      * \param hide set to true to set the hide flag directly.
00750      *
00751      * \return the newly created property variable instance.
00752      */
00753     WPropTrigger   addProperty( std::string name, std::string description, const WPVBaseTypes::PV_TRIGGER&  initial,
00754                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00755 
00756     /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00757     // convenience methods for
00758     // template< typename T>
00759     // boost::shared_ptr< WPropertyVariable< T > > addProperty( std::string name, std::string description, const T& initial,
00760     //                                                          boost::shared_ptr< WCondition > condition,
00761     //                                                          WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00762     /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00763 
00764     /**
00765      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00766      *
00767      * \see WPropertyVariable
00768      *
00769      * \param name  the property name
00770      * \param description the property description
00771      * \param initial the initial value
00772      * \param notifier use this notifier for change callbacks.
00773      * \param condition use this external condition for notification
00774      * \param hide set to true to set the hide flag directly.
00775      *
00776      * \return the newly created property variable instance.
00777      */
00778     WPropBool      addProperty( std::string name, std::string description, const WPVBaseTypes::PV_BOOL&   initial,
00779                                 boost::shared_ptr< WCondition > condition,
00780                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00781 
00782     /**
00783      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00784      * It also sets the min and max constraint to [0,100].
00785      *
00786      * \see WPropertyVariable
00787      *
00788      * \param name  the property name
00789      * \param description the property description
00790      * \param initial the initial value
00791      * \param notifier use this notifier for change callbacks.
00792      * \param condition use this external condition for notification
00793      * \param hide set to true to set the hide flag directly.
00794      *
00795      * \return the newly created property variable instance.
00796      */
00797     WPropInt       addProperty( std::string name, std::string description, const WPVBaseTypes::PV_INT&    initial,
00798                                 boost::shared_ptr< WCondition > condition,
00799                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00800 
00801     /**
00802      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00803      * It also sets the min and max constraint to [0,100].
00804      *
00805      * \see WPropertyVariable
00806      *
00807      * \param name  the property name
00808      * \param description the property description
00809      * \param initial the initial value
00810      * \param notifier use this notifier for change callbacks.
00811      * \param condition use this external condition for notification
00812      * \param hide set to true to set the hide flag directly.
00813      *
00814      * \return the newly created property variable instance.
00815      */
00816     WPropDouble    addProperty( std::string name, std::string description, const WPVBaseTypes::PV_DOUBLE& initial,
00817                                 boost::shared_ptr< WCondition > condition,
00818                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00819 
00820 
00821     /**
00822      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00823      *
00824      * \see WPropertyVariable
00825      *
00826      * \param name  the property name
00827      * \param description the property description
00828      * \param initial the initial value
00829      * \param notifier use this notifier for change callbacks.
00830      * \param condition use this external condition for notification
00831      * \param hide set to true to set the hide flag directly.
00832      *
00833      * \return the newly created property variable instance.
00834      */
00835     WPropString    addProperty( std::string name, std::string description, const WPVBaseTypes::PV_STRING& initial,
00836                                 boost::shared_ptr< WCondition > condition,
00837                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00838 
00839     /**
00840      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00841      *
00842      * \see WPropertyVariable
00843      *
00844      * \param name  the property name
00845      * \param description the property description
00846      * \param initial the initial value
00847      * \param notifier use this notifier for change callbacks.
00848      * \param condition use this external condition for notification
00849      * \param hide set to true to set the hide flag directly.
00850      *
00851      * \return the newly created property variable instance.
00852      */
00853     WPropFilename  addProperty( std::string name, std::string description, const WPVBaseTypes::PV_PATH&   initial,
00854                                 boost::shared_ptr< WCondition > condition,
00855                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00856 
00857     /**
00858      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00859      *
00860      * \see WPropertyVariable
00861      *
00862      * \param name  the property name
00863      * \param description the property description
00864      * \param initial the initial value
00865      * \param notifier use this notifier for change callbacks.
00866      * \param condition use this external condition for notification
00867      * \param hide set to true to set the hide flag directly.
00868      *
00869      * \return the newly created property variable instance.
00870      */
00871     WPropSelection addProperty( std::string name, std::string description, const WPVBaseTypes::PV_SELECTION&   initial,
00872                                 boost::shared_ptr< WCondition > condition,
00873                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00874 
00875     /**
00876      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00877      *
00878      * \see WPropertyVariable
00879      *
00880      * \param name  the property name
00881      * \param description the property description
00882      * \param initial the initial value
00883      * \param notifier use this notifier for change callbacks.
00884      * \param condition use this external condition for notification
00885      * \param hide set to true to set the hide flag directly.
00886      *
00887      * \return the newly created property variable instance.
00888      */
00889     WPropPosition  addProperty( std::string name, std::string description, const WPVBaseTypes::PV_POSITION&   initial,
00890                                 boost::shared_ptr< WCondition > condition,
00891                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00892 
00893     /**
00894      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00895      *
00896      * \see WPropertyVariable
00897      *
00898      * \param name  the property name
00899      * \param description the property description
00900      * \param initial the initial value
00901      * \param notifier use this notifier for change callbacks.
00902      * \param condition use this external condition for notification
00903      * \param hide set to true to set the hide flag directly.
00904      *
00905      * \return the newly created property variable instance.
00906      */
00907     WPropColor     addProperty( std::string name, std::string description, const WPVBaseTypes::PV_COLOR&   initial,
00908                                 boost::shared_ptr< WCondition > condition,
00909                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00910 
00911     /**
00912      * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
00913      *
00914      * \see WPropertyVariable
00915      *
00916      * \param name  the property name
00917      * \param description the property description
00918      * \param initial the initial value
00919      * \param notifier use this notifier for change callbacks.
00920      * \param condition use this external condition for notification
00921      * \param hide set to true to set the hide flag directly.
00922      *
00923      * \return the newly created property variable instance.
00924      */
00925     WPropTrigger   addProperty( std::string name, std::string description, const WPVBaseTypes::PV_TRIGGER&   initial,
00926                                 boost::shared_ptr< WCondition > condition,
00927                                 WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
00928 
00929     /**
00930      * This returns the condition fired whenever one children fires its update condition. Useful to get notified about all changes that happen.
00931      *
00932      * \return the condition fired if a child fires its update condition.
00933      */
00934     virtual boost::shared_ptr< WCondition > getChildUpdateCondition() const;
00935 
00936 protected:
00937 
00938    /**
00939     * Helping function to find a property inside a specific group. It does not recursively find properties nested inside other property groups.
00940     *
00941     * \param props the group to search in. This is not a shared pointer since it is not needed. It simply can't happen that it is freed during
00942     * findProperty as it is contained in this or a nested properties instance.
00943     * \param name the name of the property inside THIS group.
00944     *
00945     * \return the property if found, else NULL.
00946     */
00947     boost::shared_ptr< WPropertyBase > findProperty( const WProperties* const props, std::string name ) const;
00948 
00949 private:
00950 
00951     /**
00952      * The set of proerties. This uses the operators ==,<,> WProperty to determine equalness.
00953      */
00954     PropertySharedContainerType m_properties;
00955 
00956     /**
00957      * Condition notified whenever a property inside this group fires its WPropertyBase::m_updateCondition. This is especially useful to get a
00958      * notification if something updates without further knowledge what changed. Useful if you want to listen for updates in modules for example.
00959      *
00960      * \see getChildUpdateCondition
00961      */
00962     boost::shared_ptr< WConditionSet > m_childUpdateCondition;
00963 
00964     /**
00965      * Compares the names of two properties and returns true if they are equal.
00966      *
00967      * \param prop1 the first prop.
00968      * \param prop2 the second prop.
00969      *
00970      * \return Are the names of the two properties equal?
00971      */
00972     bool propNamePredicate( boost::shared_ptr< WPropertyBase > prop1, boost::shared_ptr< WPropertyBase > prop2 ) const;
00973 };
00974 
00975 template< typename PropType >
00976 PropType WProperties::addProperty( PropType prop )
00977 {
00978     // lock, unlocked if l looses focus
00979     PropertySharedContainerType::WriteTicket l = m_properties.getWriteTicket();
00980 
00981     // NOTE: WPropertyBase already prohibits invalid property names -> no check needed here
00982 
00983     // check uniqueness:
00984     if( std::count_if( l->get().begin(), l->get().end(),
00985             boost::bind( boost::mem_fn( &WProperties::propNamePredicate ), this, prop, _1 ) ) )
00986     {
00987         // unlock explicitly
00988         l.reset();
00989 
00990         // oh oh, this property name is not unique in this group
00991         if( !getName().empty() )
00992         {
00993             throw WPropertyNotUnique( std::string( "Property \"" + prop->getName() + "\" is not unique in this group (\"" + getName() + "\")." ) );
00994         }
00995         else
00996         {
00997             throw WPropertyNotUnique( std::string( "Property \"" + prop->getName() + "\" is not unique in this group (unnamed root)." ) );
00998         }
00999     }
01000 
01001     // PV_PURPOSE_INFORMATION groups do not allow PV_PURPOSE_PARAMETER properties but vice versa.
01002     if( getPurpose() == PV_PURPOSE_INFORMATION )
01003     {
01004         prop->setPurpose( PV_PURPOSE_INFORMATION );
01005     }
01006     // INFORMATION properties are allowed inside PARAMETER groups -> do not set the properties purpose.
01007 
01008     l->get().push_back( prop );
01009 
01010     // add the child's update condition to the list
01011     m_childUpdateCondition->add( prop->getUpdateCondition() );
01012 
01013     return prop;
01014 }
01015 
01016 template< typename T>
01017 boost::shared_ptr< WPropertyVariable< T > > WProperties::addProperty( std::string name, std::string description, const T& initial, bool hide )
01018 {
01019     boost::shared_ptr< WPropertyVariable< T > > p = boost::shared_ptr< WPropertyVariable< T > >(
01020             new WPropertyVariable< T >( name, description, initial )
01021     );
01022     p->setHidden( hide );
01023     addProperty( p );
01024     return p;
01025 }
01026 
01027 template< typename T>
01028 boost::shared_ptr< WPropertyVariable< T > > WProperties::addProperty( std::string name, std::string description, const T& initial,
01029                                                                        boost::shared_ptr< WCondition > condition, bool hide )
01030 {
01031     boost::shared_ptr< WPropertyVariable< T > > p = boost::shared_ptr< WPropertyVariable< T > >(
01032             new WPropertyVariable< T >( name, description, initial, condition )
01033     );
01034     p->setHidden( hide );
01035     addProperty( p );
01036     return p;
01037 }
01038 
01039 template< typename T>
01040 boost::shared_ptr< WPropertyVariable< T > > WProperties::addProperty( std::string name, std::string description, const T& initial,
01041                                                                        WPropertyBase::PropertyChangeNotifierType notifier, bool hide )
01042 {
01043     boost::shared_ptr< WPropertyVariable< T > > p = boost::shared_ptr< WPropertyVariable< T > >(
01044             new WPropertyVariable< T >( name, description, initial, notifier )
01045     );
01046     p->setHidden( hide );
01047     addProperty( p );
01048     return p;
01049 }
01050 
01051 template< typename T>
01052 boost::shared_ptr< WPropertyVariable< T > > WProperties::addProperty( std::string name, std::string description, const T& initial,
01053                                                                        boost::shared_ptr< WCondition > condition,
01054                                                                        WPropertyBase::PropertyChangeNotifierType notifier, bool hide )
01055 {
01056     boost::shared_ptr< WPropertyVariable< T > > p = boost::shared_ptr< WPropertyVariable< T > >(
01057             new WPropertyVariable< T >( name, description, initial, condition, notifier )
01058     );
01059     p->setHidden( hide );
01060     addProperty( p );
01061     return p;
01062 }
01063 
01064 #endif  // WPROPERTIES_H
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends