OpenWalnut 1.2.5

WPropertyBase.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 WPROPERTYBASE_H
00026 #define WPROPERTYBASE_H
00027 
00028 #include <string>
00029 
00030 #include <boost/function.hpp>
00031 #include <boost/signals2/signal.hpp>
00032 
00033 #include <boost/shared_ptr.hpp>
00034 #include <boost/enable_shared_from_this.hpp>
00035 
00036 #include "WProperties_Fwd.h"
00037 #include "WCondition.h"
00038 #include "WConditionSet.h"
00039 #include "WExportCommon.h"
00040 
00041 /**
00042  * Abstract base class for all properties. Simply provides name and type information.
00043  */
00044 class OWCOMMON_EXPORT WPropertyBase: public boost::enable_shared_from_this< WPropertyBase >
00045 {
00046 public:
00047     /**
00048      * Convenience typedef for a boost::shared_ptr< WPropertyBase >
00049      */
00050     typedef boost::shared_ptr< WPropertyBase > SPtr;
00051 
00052     /**
00053      * Convenience typedef for a  boost::shared_ptr< const WPropertyBase >
00054      */
00055     typedef boost::shared_ptr< const WPropertyBase > ConstSPtr;
00056 
00057     /**
00058      * Create an empty named property.
00059      *
00060      * \param name  the name of the property
00061      * \param description the description of the property
00062      */
00063     WPropertyBase( std::string name, std::string description );
00064 
00065     /**
00066      * Copy constructor. Creates a deep copy of this property. As boost::signals2 and condition variables are non-copyable, new instances get
00067      * created. The subscriptions to a signal are LOST as well as all listeners to a condition.
00068      *
00069      * \param from the instance to copy.
00070      */
00071     explicit WPropertyBase( const WPropertyBase& from );
00072 
00073     /**
00074      * Destructor.
00075      */
00076     virtual ~WPropertyBase();
00077 
00078     /**
00079      * 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
00080      * correct type without explicitly requiring the user to specify it. It creates a NEW change condition and change signal. This means, alls
00081      * subscribed signal handlers are NOT copied.
00082      *
00083      * \note this simply ensures the copy constructor of the runtime type is issued.
00084      *
00085      * \return the deep clone of this property.
00086      */
00087     virtual boost::shared_ptr< WPropertyBase > clone() = 0;
00088 
00089     /**
00090      * Gets the name of the class.
00091      *
00092      * \return the name.
00093      */
00094     std::string getName() const;
00095 
00096     /**
00097      * Gets the description of the property.
00098      *
00099      * \return the description
00100      */
00101     std::string getDescription() const;
00102 
00103     /**
00104      * Determines whether the property is hidden or not.
00105      *
00106      * \return true if hidden
00107      */
00108     bool isHidden() const;
00109 
00110     /**
00111      * Sets the property hidden. This flag is especially used by the GUI.
00112      *
00113      * \param hidden true if it should be hidden.
00114      */
00115     void setHidden( bool hidden = true );
00116 
00117     /**
00118      * Gets the real WPropertyVariable type of this instance.
00119      *
00120      * \return the real type.
00121      */
00122     virtual PROPERTY_TYPE getType() const;
00123 
00124     /**
00125      * Gets the purpose of a property. See PROPERTY_PURPOSE for more details. For short: it helps the GUI and others to understand what a module
00126      * (or whomever created this property) intents with this property. Typically this value is PV_PURPOSE_PARAMETER, meaning that it is used to
00127      * tune the behaviour of a module.
00128      *
00129      * \note always assume this to be a hint. It does not actually prevent someone from writing or interpreting a parameter property as an
00130      * information property.
00131      *
00132      * \see PROPERTY_PURPOSE
00133      * \return the purpose.
00134      */
00135     virtual PROPERTY_PURPOSE getPurpose() const;
00136 
00137     /**
00138      * Sets the purpose of the property. See \ref getPurpose for more details. You generally should avoid setting this value after
00139      * initialization.
00140      *
00141      * \param purpose the purpose to set.
00142      */
00143     virtual void setPurpose( PROPERTY_PURPOSE purpose );
00144 
00145     /**
00146      * This methods allows properties to be set by a string value. This is especially useful when a property is only available as string and the
00147      * real type of the property is unknown. This is a shortcut for casting the property and then setting the lexically casted value.
00148      *
00149      * \param value the new value to set.
00150      *
00151      * \return true if value could be set.
00152      */
00153     virtual bool setAsString( std::string value ) = 0;
00154 
00155     /**
00156      * Returns the current value as a string. This is useful for debugging or project files. It is not implemented as << operator, since the <<
00157      * should also print min/max constraints and so on. This simply is the value.
00158      *
00159      * \return the value as a string.
00160      */
00161     virtual std::string getAsString() = 0;
00162 
00163     /**
00164      * This method returns a condition which gets fired whenever the property changes somehow. It is fired when:
00165      * \li \ref setHidden is called and the hidden state changes
00166      * \li \ref setAsString is called and the value changes
00167      * \li WPropertyVariable::set is called and the value changes (regardless of suppression during set)
00168      * \li WPropertyVariable::setMin/setMax is called and the value changes
00169      * \li WPropertyVariable::addConstraint is called
00170      * \li WPropertyVariable::removeConstraints is called
00171      * \li WProperties::addProperty is called
00172      * \li WProperties::removeProperty is called
00173      * \li WProperties::addPropertyGroup is called
00174      * This is especially useful if you simply want to know that something has happened.
00175      *
00176      * \return a condition notified whenever something changes.
00177      */
00178     virtual boost::shared_ptr< WCondition > getUpdateCondition() const;
00179 
00180     /**
00181      * Sets the value from the specified property to this one. This is especially useful to copy a value without explicitly casting/knowing the
00182      * dynamic type of the property.
00183      *
00184      * \param value the new value.
00185      *
00186      * \return true if the value has been accepted.
00187      */
00188     virtual bool set( boost::shared_ptr< WPropertyBase > value ) = 0;
00189 
00190     /////////////////////////////////////////////////////////////////////////////////////////////
00191     // Helpers for easy conversion to the possible types
00192     /////////////////////////////////////////////////////////////////////////////////////////////
00193 
00194     /**
00195      * Helper converts this instance to its native type.
00196      *
00197      * \return the property as integer property
00198      */
00199     WPropInt toPropInt();
00200 
00201     /**
00202      * Helper converts this instance to its native type.
00203      *
00204      * \return the property as double property
00205      */
00206     WPropDouble toPropDouble();
00207 
00208     /**
00209      * Helper converts this instance to its native type.
00210      *
00211      * \return the property as bool property
00212      */
00213     WPropBool toPropBool();
00214 
00215     /**
00216      * Helper converts this instance to its native type.
00217      *
00218      * \return the property as string property
00219      */
00220     WPropString toPropString();
00221 
00222     /**
00223      * Helper converts this instance to its native type.
00224      *
00225      * \return the property as path property
00226      */
00227     WPropFilename toPropFilename();
00228 
00229     /**
00230      * Helper converts this instance to its native type.
00231      *
00232      * \return the property as selection property
00233      */
00234     WPropSelection toPropSelection();
00235 
00236     /**
00237      * Helper converts this instance to its native type.
00238      *
00239      * \return the property as color property
00240      */
00241     WPropColor toPropColor();
00242 
00243     /**
00244      * Helper converts this instance to its native type.
00245      *
00246      * \return the property as position property
00247      */
00248     WPropPosition toPropPosition();
00249 
00250     /**
00251      * Helper converts this instance to its native type.
00252      *
00253      * \return the property as trigger property
00254      */
00255     WPropTrigger toPropTrigger();
00256 
00257     /**
00258      * Helper converts this instance to its native type.
00259      *
00260      * \return the property as matrix4x4 property
00261      */
00262     WPropMatrix4X4 toPropMatrix4X4();
00263 
00264     /**
00265      * Helper converts this instance to its native type.
00266      *
00267      * \return the property as group
00268      */
00269     WPropGroup toPropGroup();
00270 
00271     /**
00272      * Helper converts this instance to an arbitrary type.
00273      *
00274      * \return the property of given type of NULL if not valid type
00275      */
00276     template< typename T >
00277     boost::shared_ptr< WPropertyVariable< T > > toPropertyVariable();
00278 
00279     /**
00280      * Signal signature emitted during set operations
00281      */
00282     typedef boost::function<void ( boost::shared_ptr< WPropertyBase > )> PropertyChangeNotifierType;
00283 
00284 protected:
00285 
00286     /**
00287      * Name of the property.
00288      */
00289     std::string m_name;
00290 
00291     /**
00292      * Description of the property.
00293      */
00294     std::string m_description;
00295 
00296     /**
00297      * Flag denoting whether the property is hidden or not.
00298      */
00299     bool m_hidden;
00300 
00301     /**
00302      * Type of the PropertyVariable instance
00303      */
00304     PROPERTY_TYPE m_type;
00305 
00306     /**
00307      * The purpose of this property. PropertyBase always initializes it with PV_PURPOSE_PARAMETER.
00308      */
00309     PROPERTY_PURPOSE m_purpose;
00310 
00311     /**
00312      * Calculates the type of the property. This has to be done by the implementing class.
00313      */
00314     virtual void updateType();
00315 
00316     /**
00317      * Signal used for firing change signals
00318      */
00319     typedef boost::signals2::signal<void ( boost::shared_ptr< WPropertyBase >  )>  PropertyChangeSignalType;
00320 
00321     /**
00322      * Signal getting fired whenever the property changes.
00323      */
00324     PropertyChangeSignalType signal_PropertyChange;
00325 
00326     /**
00327      * Condition notified whenever something changes. See getUpdateCondition for more details.
00328      * \see getUpdateCondition
00329      */
00330     boost::shared_ptr< WConditionSet > m_updateCondition;
00331 
00332 private:
00333 };
00334 
00335 template< typename T >
00336 boost::shared_ptr< WPropertyVariable< T > > WPropertyBase::toPropertyVariable()
00337 {
00338     return boost::shared_dynamic_cast< WPropertyVariable< T > >( shared_from_this() );
00339 }
00340 
00341 #endif  // WPROPERTYBASE_H
00342 
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends