OpenWalnut  1.4.0
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 
00040 
00041 /**
00042  * Abstract base class for all properties. Simply provides name and type information.
00043  */
00044 class 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      * \param recommendedOnly if true, property types which support recommended values apply the given value as recommendation.
00186      *
00187      * \return true if the value has been accepted.
00188      */
00189     virtual bool set( boost::shared_ptr< WPropertyBase > value, bool recommendedOnly = false ) = 0;
00190 
00191     /////////////////////////////////////////////////////////////////////////////////////////////
00192     // Helpers for easy conversion to the possible types
00193     /////////////////////////////////////////////////////////////////////////////////////////////
00194 
00195     /**
00196      * Helper converts this instance to its native type.
00197      *
00198      * \return the property as integer property
00199      */
00200     WPropInt toPropInt();
00201 
00202     /**
00203      * Helper converts this instance to its native type.
00204      *
00205      * \return the property as double property
00206      */
00207     WPropDouble toPropDouble();
00208 
00209     /**
00210      * Helper converts this instance to its native type.
00211      *
00212      * \return the property as bool property
00213      */
00214     WPropBool toPropBool();
00215 
00216     /**
00217      * Helper converts this instance to its native type.
00218      *
00219      * \return the property as string property
00220      */
00221     WPropString toPropString();
00222 
00223     /**
00224      * Helper converts this instance to its native type.
00225      *
00226      * \return the property as path property
00227      */
00228     WPropFilename toPropFilename();
00229 
00230     /**
00231      * Helper converts this instance to its native type.
00232      *
00233      * \return the property as selection property
00234      */
00235     WPropSelection toPropSelection();
00236 
00237     /**
00238      * Helper converts this instance to its native type.
00239      *
00240      * \return the property as color property
00241      */
00242     WPropColor toPropColor();
00243 
00244     /**
00245      * Helper converts this instance to its native type.
00246      *
00247      * \return the property as position property
00248      */
00249     WPropPosition toPropPosition();
00250 
00251     /**
00252      * Helper converts this instance to its native type.
00253      *
00254      * \return the property as trigger property
00255      */
00256     WPropTrigger toPropTrigger();
00257 
00258     /**
00259      * Helper converts this instance to its native type.
00260      *
00261      * \return the property as matrix4x4 property
00262      */
00263     WPropMatrix4X4 toPropMatrix4X4();
00264 
00265     /**
00266      * Helper converts this instance to its native type.
00267      *
00268      * \return the property as transfer function property
00269      */
00270     WPropTransferFunction toPropTransferFunction();
00271 
00272     /**
00273      * Helper converts this instance to its native type.
00274      *
00275      * \return the property as group
00276      */
00277     WPropGroup toPropGroup();
00278 
00279     /**
00280      * Helper converts this instance to its native type.
00281      *
00282      * \return the property as interval property
00283      */
00284     WPropInterval toPropInterval();
00285 
00286     /**
00287      * Convert the property to a WPropertyGroupBase. This can be done with property structs and groups-
00288      *
00289      * \return the property as base group.
00290      */
00291     boost::shared_ptr< WPropertyGroupBase > toPropGroupBase();
00292 
00293     /**
00294      * Helper converts this instance to an arbitrary type.
00295      *
00296      * \return the property of given type of NULL if not valid type
00297      */
00298     template< typename T >
00299     boost::shared_ptr< WPropertyVariable< T > > toPropertyVariable();
00300 
00301     /**
00302      * Signal signature emitted during set operations
00303      */
00304     typedef boost::function<void ( boost::shared_ptr< WPropertyBase > )> PropertyChangeNotifierType;
00305 
00306 protected:
00307     /**
00308      * Name of the property.
00309      */
00310     std::string m_name;
00311 
00312     /**
00313      * Description of the property.
00314      */
00315     std::string m_description;
00316 
00317     /**
00318      * Flag denoting whether the property is hidden or not.
00319      */
00320     bool m_hidden;
00321 
00322     /**
00323      * Type of the PropertyVariable instance
00324      */
00325     PROPERTY_TYPE m_type;
00326 
00327     /**
00328      * The purpose of this property. PropertyBase always initializes it with PV_PURPOSE_PARAMETER.
00329      */
00330     PROPERTY_PURPOSE m_purpose;
00331 
00332     /**
00333      * Calculates the type of the property. This has to be done by the implementing class.
00334      */
00335     virtual void updateType();
00336 
00337     /**
00338      * Signal used for firing change signals
00339      */
00340     typedef boost::signals2::signal<void ( boost::shared_ptr< WPropertyBase >  )>  PropertyChangeSignalType;
00341 
00342     /**
00343      * Signal getting fired whenever the property changes.
00344      */
00345     PropertyChangeSignalType signal_PropertyChange;
00346 
00347     /**
00348      * Condition notified whenever something changes. See getUpdateCondition for more details.
00349      * \see getUpdateCondition
00350      */
00351     boost::shared_ptr< WConditionSet > m_updateCondition;
00352 
00353 private:
00354 };
00355 
00356 template< typename T >
00357 boost::shared_ptr< WPropertyVariable< T > > WPropertyBase::toPropertyVariable()
00358 {
00359     return boost::dynamic_pointer_cast< WPropertyVariable< T > >( shared_from_this() );
00360 }
00361 
00362 #endif  // WPROPERTYBASE_H
00363