OpenWalnut
1.2.5
|
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