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