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