OpenWalnut  1.2.5
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
WProperties.h
1 //---------------------------------------------------------------------------
2 //
3 // Project: OpenWalnut ( http://www.openwalnut.org )
4 //
5 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
6 // For more information see http://www.openwalnut.org/copying
7 //
8 // This file is part of OpenWalnut.
9 //
10 // OpenWalnut is free software: you can redistribute it and/or modify
11 // it under the terms of the GNU Lesser General Public License as published by
12 // the Free Software Foundation, either version 3 of the License, or
13 // (at your option) any later version.
14 //
15 // OpenWalnut is distributed in the hope that it will be useful,
16 // but WITHOUT ANY WARRANTY; without even the implied warranty of
17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 // GNU Lesser General Public License for more details.
19 //
20 // You should have received a copy of the GNU Lesser General Public License
21 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
22 //
23 //---------------------------------------------------------------------------
24 
25 #ifndef WPROPERTIES_H
26 #define WPROPERTIES_H
27 
28 #include <map>
29 #include <string>
30 #include <vector>
31 
32 #include <boost/thread/thread.hpp>
33 #include <boost/thread/mutex.hpp>
34 #include <boost/thread/locks.hpp>
35 #include <boost/thread.hpp>
36 
37 #include "WConditionSet.h"
38 #include "WPropertyBase.h"
39 #include "WPropertyTypes.h"
40 #include "WPropertyVariable.h"
41 #include "WSharedSequenceContainer.h"
42 #include "exceptions/WPropertyNotUnique.h"
43 
44 #include "WExportCommon.h"
45 
46 /**
47  * Class to manage properties of an object and to provide convenience methods for easy access and manipulation. It also allows
48  * thread safe iteration on its elements. The main purpose of this class is to group properties together and to allow searching properties by a
49  * 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
50  * is the property with the name "property" in the group "you" which against is in the group "hello".
51  * \note The root group of each module does not have a name.
52  */
53 class OWCOMMON_EXPORT WProperties: public WPropertyBase
54 {
55 friend class WPropertiesTest;
56 public:
57 
58  // the following typedefs are for convenience.
59  typedef boost::shared_ptr< WProperties > SPtr; //!< shared pointer to object of this type
60  typedef boost::shared_ptr< const WProperties > ConstSPtr; //!< const shared pointer to object of this type
61  typedef WProperties* Ptr; //!< pointer to object of this type
62  typedef const WProperties* ConstPtr; //!< const pointer to object of this type
63  typedef WProperties& Ref; //!< ref to object of this type
64  typedef const WProperties& ConstRef; //!< const ref to object of this type
65 
66  /**
67  * For shortening: a type defining a shared vector of WSubject pointers.
68  */
69  typedef std::vector< boost::shared_ptr< WPropertyBase > > PropertyContainerType;
70 
71  /**
72  * The alias for a shared container.
73  */
75 
76  /**
77  * The const iterator type of the container.
78  */
79  typedef PropertyContainerType::const_iterator PropertyConstIterator;
80 
81  /**
82  * The iterator type of the container.
83  */
84  typedef PropertyContainerType::iterator PropertyIterator;
85 
86  /**
87  * Constructor. Creates an empty list of properties.
88  *
89  * \note WModule::getProperties always returns an unnamed instance.
90  *
91  * \param name the name of the property group. The GUI is using this name for naming the tabs/group boxes
92  * \param description the description of the group.
93  */
94  WProperties( std::string name = "unnamed group", std::string description = "an unnamed group of properties" );
95 
96  /**
97  * Copy constructor. Creates a deep copy of this property. As boost::signals2 and condition variables are non-copyable, new instances get
98  * created. The subscriptions to a signal are LOST as well as all listeners to a condition.
99  * The conditions you can grab using getValueChangeConditon and getCondition are not the same as in the original! This is because
100  * the class corresponds to the observer/observable pattern. You won't expect a clone to fire a condition if a original flag is changed
101  * (which after cloning is completely decoupled from the clone).
102  *
103  * \note the properties inside this list are also copied deep
104  *
105  * \param from the instance to copy.
106  */
107  explicit WProperties( const WProperties& from );
108 
109  /**
110  * destructor
111  */
112  virtual ~WProperties();
113 
114  /**
115  * 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
116  * correct type without explicitly requiring the user to specify it. It creates a NEW change condition and change signal. This means, alls
117  * subscribed signal handlers are NOT copied.
118  *
119  * \note this simply ensures the copy constructor of the runtime type is issued.
120  *
121  * \return the deep clone of this property.
122  */
123  virtual boost::shared_ptr< WPropertyBase > clone();
124 
125  /**
126  * Simply insert the specified property to the list.
127  *
128  * \param prop the property to add
129  *
130  * \return The given prop.
131  */
132  template< typename PropType >
133  PropType addProperty( PropType prop );
134 
135  /**
136  * Simply remove the specified property from the list. If the given property is not in the list, nothing happens.
137  *
138  * \param prop the property to remove.
139  */
140  void removeProperty( boost::shared_ptr< WPropertyBase > prop );
141 
142  /**
143  * Helper function that finds a property by its name. Use this method to find out whether the property exists or not, since
144  * findProperty throws an exception.
145  *
146  * \param name name of searched property.
147  *
148  * \return Answer to the question whether the property exists.
149  */
150  bool existsProperty( std::string name );
151 
152  /**
153  * Function searches the property. If it does not exists, it throws an exception.
154  *
155  * \param name the name of the property
156  *
157  * \return a WProperty object
158  */
159  boost::shared_ptr< WPropertyBase > getProperty( std::string name );
160 
161  /**
162  * Returns a read ticket for read-access to the list of properties.
163  *
164  * \return the read ticket.
165  */
166  PropertySharedContainerType::ReadTicket getProperties() const;
167 
168  /**
169  * Returns an read ticket for the properties. This, and only this, has to be used for external iteration of properties.
170  *
171  * \see WSharedObjectTicketRead
172  * \return the read ticket.
173  */
174  PropertySharedContainerType::ReadTicket getReadTicket() const;
175 
176  /**
177  * Searches the property with a given name. It does not throw any exception. It simply returns NULL if it can't be found.
178  *
179  * \param name the name of the property to search
180  *
181  * \return the property or NULL if not found.
182  */
183  boost::shared_ptr< WPropertyBase > findProperty( std::string name ) const;
184 
185  /**
186  * Removes all properties from the list.
187  */
188  virtual void clear();
189 
190  ///////////////////////////////////////////////////////////////////////////////////////////////////
191  // Convenience methods to create and add properties
192  ///////////////////////////////////////////////////////////////////////////////////////////////////
193 
194  /**
195  * Create and add a new property group. Use these groups to structure your properties.
196  *
197  * \param name the name of the group.
198  * \param description the description of the group.
199  * \param hide true if group should be completely hidden.
200  *
201  * \return The newly created property group.
202  */
203  WPropGroup addPropertyGroup( std::string name, std::string description, bool hide = false );
204 
205  /**
206  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
207  *
208  * \see WPropertyVariable
209  *
210  * \param name the property name
211  * \param description the property description
212  * \param initial the initial value
213  * \param hide set to true to set the hide flag directly.
214  *
215  * \return the newly created property variable instance.
216  */
217  template< typename T>
218  boost::shared_ptr< WPropertyVariable< T > > addProperty( std::string name, std::string description, const T& initial, bool hide = false );
219 
220  /**
221  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
222  *
223  * \see WPropertyVariable
224  *
225  * \param name the property name
226  * \param description the property description
227  * \param initial the initial value
228  * \param condition use this external condition for notification.
229  * \param hide set to true to set the hide flag directly.
230  *
231  * \return the newly created property variable instance.
232  */
233  template< typename T>
234  boost::shared_ptr< WPropertyVariable< T > > addProperty( std::string name, std::string description, const T& initial,
235  boost::shared_ptr< WCondition > condition, bool hide = false );
236 
237  /**
238  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
239  *
240  * \see WPropertyVariable
241  *
242  * \param name the property name
243  * \param description the property description
244  * \param initial the initial value
245  * \param notifier use this notifier for change callbacks.
246  * \param hide set to true to set the hide flag directly.
247  *
248  * \return the newly created property variable instance.
249  */
250  template< typename T>
251  boost::shared_ptr< WPropertyVariable< T > > addProperty( std::string name, std::string description, const T& initial,
252  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
253 
254  /**
255  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
256  *
257  * \see WPropertyVariable
258  *
259  * \param name the property name
260  * \param description the property description
261  * \param initial the initial value
262  * \param notifier use this notifier for change callbacks.
263  * \param condition use this external condition for notification
264  * \param hide set to true to set the hide flag directly.
265  *
266  * \return the newly created property variable instance.
267  */
268  template< typename T>
269  boost::shared_ptr< WPropertyVariable< T > > addProperty( std::string name, std::string description, const T& initial,
270  boost::shared_ptr< WCondition > condition,
271  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
272 
273  /**
274  * Gets the real type of this instance. In this case, PV_GROUP.
275  *
276  * \return the real type.
277  */
278  virtual PROPERTY_TYPE getType() const;
279 
280  /**
281  * 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.
282  *
283  * \param value the new value to set. IGNORED.
284  *
285  * \return always true
286  */
287  virtual bool setAsString( std::string value );
288 
289  /**
290  * Returns the current value as a string. This is useful for debugging or project files. It is not implemented as << operator, since the <<
291  * should also print min/max constraints and so on. This simply is the value.
292  *
293  * \return the value as a string.
294  */
295  virtual std::string getAsString();
296 
297  /**
298  * Sets the value from the specified property to this one. This is especially useful to copy a value without explicitly casting/knowing the
299  * dynamic type of the property.
300  *
301  * \note for WProperties, this actually does nothing an.
302  *
303  * \param value the new value.
304  *
305  * \return true, always.
306  */
307  virtual bool set( boost::shared_ptr< WPropertyBase > value );
308 
309  /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
310  // Convenience methods to create and add properties
311  // NOTE: these methods use the type of the initial parameter to automatically use the proper type.
312  // This works, since the compiler always calls the function with the best matching parameter types.
313  /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
314 
315 
316  /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
317  // convenience methods for
318  // template< typename T>
319  // boost::shared_ptr< WPropertyVariable< T > > addProperty( std::string name, std::string description, const T& initial, bool hide = false );
320  /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
321 
322  /**
323  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
324  *
325  * \see WPropertyVariable
326  *
327  * \param name the property name
328  * \param description the property description
329  * \param initial the initial value
330  * \param hide set to true to set the hide flag directly.
331  *
332  * \return the newly created property variable instance.
333  */
334  WPropBool addProperty( std::string name, std::string description, const WPVBaseTypes::PV_BOOL& initial, bool hide = false );
335 
336  /**
337  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
338  * It also sets the min and max constraint to [0,100].
339  *
340  * \see WPropertyVariable
341  *
342  * \param name the property name
343  * \param description the property description
344  * \param initial the initial value
345  * \param hide set to true to set the hide flag directly.
346  *
347  * \return the newly created property variable instance.
348  */
349  WPropInt addProperty( std::string name, std::string description, const WPVBaseTypes::PV_INT& initial, bool hide = false );
350 
351  /**
352  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
353  * It also sets the min and max constraint to [0,100].
354  *
355  * \see WPropertyVariable
356  *
357  * \param name the property name
358  * \param description the property description
359  * \param initial the initial value
360  * \param hide set to true to set the hide flag directly.
361  *
362  * \return the newly created property variable instance.
363  */
364  WPropDouble addProperty( std::string name, std::string description, const WPVBaseTypes::PV_DOUBLE& initial, bool hide = false );
365 
366  /**
367  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
368  *
369  * \see WPropertyVariable
370  *
371  * \param name the property name
372  * \param description the property description
373  * \param initial the initial value
374  * \param hide set to true to set the hide flag directly.
375  *
376  * \return the newly created property variable instance.
377  */
378  WPropString addProperty( std::string name, std::string description, const WPVBaseTypes::PV_STRING& initial, bool hide = false );
379 
380  /**
381  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
382  *
383  * \see WPropertyVariable
384  *
385  * \param name the property name
386  * \param description the property description
387  * \param initial the initial value
388  * \param hide set to true to set the hide flag directly.
389  *
390  * \return the newly created property variable instance.
391  */
392  WPropFilename addProperty( std::string name, std::string description, const WPVBaseTypes::PV_PATH& initial, bool hide = false );
393 
394  /**
395  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
396  *
397  * \see WPropertyVariable
398  *
399  * \param name the property name
400  * \param description the property description
401  * \param initial the initial value
402  * \param hide set to true to set the hide flag directly.
403  *
404  * \return the newly created property variable instance.
405  */
406  WPropSelection addProperty( std::string name, std::string description, const WPVBaseTypes::PV_SELECTION& initial, bool hide = false );
407 
408  /**
409  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
410  *
411  * \see WPropertyVariable
412  *
413  * \param name the property name
414  * \param description the property description
415  * \param initial the initial value
416  * \param hide set to true to set the hide flag directly.
417  *
418  * \return the newly created property variable instance.
419  */
420  WPropPosition addProperty( std::string name, std::string description, const WPVBaseTypes::PV_POSITION& initial, bool hide = false );
421 
422  /**
423  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
424  *
425  * \see WPropertyVariable
426  *
427  * \param name the property name
428  * \param description the property description
429  * \param initial the initial value
430  * \param hide set to true to set the hide flag directly.
431  *
432  * \return the newly created property variable instance.
433  */
434  WPropColor addProperty( std::string name, std::string description, const WPVBaseTypes::PV_COLOR& initial, bool hide = false );
435 
436  /**
437  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
438  *
439  * \see WPropertyVariable
440  *
441  * \param name the property name
442  * \param description the property description
443  * \param initial the initial value
444  * \param hide set to true to set the hide flag directly.
445  *
446  * \return the newly created property variable instance.
447  */
448  WPropTrigger addProperty( std::string name, std::string description, const WPVBaseTypes::PV_TRIGGER& initial, bool hide = false );
449 
450  /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
451  // convenience methods for
452  // template< typename T>
453  // boost::shared_ptr< WPropertyVariable< T > > addProperty( std::string name, std::string description, const T& initial,
454  // boost::shared_ptr< WCondition > condition, bool hide = false );
455  /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
456 
457  /**
458  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
459  *
460  * \see WPropertyVariable
461  *
462  * \param name the property name
463  * \param description the property description
464  * \param initial the initial value
465  * \param condition use this external condition for notification.
466  * \param hide set to true to set the hide flag directly.
467  *
468  * \return the newly created property variable instance.
469  */
470  WPropBool addProperty( std::string name, std::string description, const WPVBaseTypes::PV_BOOL& initial,
471  boost::shared_ptr< WCondition > condition, bool hide = false );
472 
473  /**
474  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
475  * It also sets the min and max constraint to [0,100].
476  *
477  * \see WPropertyVariable
478  *
479  * \param name the property name
480  * \param description the property description
481  * \param initial the initial value
482  * \param condition use this external condition for notification.
483  * \param hide set to true to set the hide flag directly.
484  *
485  * \return the newly created property variable instance.
486  */
487  WPropInt addProperty( std::string name, std::string description, const WPVBaseTypes::PV_INT& initial,
488  boost::shared_ptr< WCondition > condition, bool hide = false );
489 
490  /**
491  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
492  * It also sets the min and max constraint to [0,100].
493  *
494  * \see WPropertyVariable
495  *
496  * \param name the property name
497  * \param description the property description
498  * \param initial the initial value
499  * \param condition use this external condition for notification.
500  * \param hide set to true to set the hide flag directly.
501  *
502  * \return the newly created property variable instance.
503  */
504  WPropDouble addProperty( std::string name, std::string description, const WPVBaseTypes::PV_DOUBLE& initial,
505  boost::shared_ptr< WCondition > condition, bool hide = false );
506 
507  /**
508  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
509  *
510  * \see WPropertyVariable
511  *
512  * \param name the property name
513  * \param description the property description
514  * \param initial the initial value
515  * \param condition use this external condition for notification.
516  * \param hide set to true to set the hide flag directly.
517  *
518  * \return the newly created property variable instance.
519  */
520  WPropString addProperty( std::string name, std::string description, const WPVBaseTypes::PV_STRING& initial,
521  boost::shared_ptr< WCondition > condition, bool hide = false );
522 
523  /**
524  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
525  *
526  * \see WPropertyVariable
527  *
528  * \param name the property name
529  * \param description the property description
530  * \param initial the initial value
531  * \param condition use this external condition for notification.
532  * \param hide set to true to set the hide flag directly.
533  *
534  * \return the newly created property variable instance.
535  */
536  WPropFilename addProperty( std::string name, std::string description, const WPVBaseTypes::PV_PATH& initial,
537  boost::shared_ptr< WCondition > condition, bool hide = false );
538 
539  /**
540  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
541  *
542  * \see WPropertyVariable
543  *
544  * \param name the property name
545  * \param description the property description
546  * \param initial the initial value
547  * \param condition use this external condition for notification.
548  * \param hide set to true to set the hide flag directly.
549  *
550  * \return the newly created property variable instance.
551  */
552  WPropSelection addProperty( std::string name, std::string description, const WPVBaseTypes::PV_SELECTION& initial,
553  boost::shared_ptr< WCondition > condition, bool hide = false );
554 
555  /**
556  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
557  *
558  * \see WPropertyVariable
559  *
560  * \param name the property name
561  * \param description the property description
562  * \param initial the initial value
563  * \param condition use this external condition for notification.
564  * \param hide set to true to set the hide flag directly.
565  *
566  * \return the newly created property variable instance.
567  */
568  WPropPosition addProperty( std::string name, std::string description, const WPVBaseTypes::PV_POSITION& initial,
569  boost::shared_ptr< WCondition > condition, bool hide = false );
570 
571  /**
572  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
573  *
574  * \see WPropertyVariable
575  *
576  * \param name the property name
577  * \param description the property description
578  * \param initial the initial value
579  * \param condition use this external condition for notification.
580  * \param hide set to true to set the hide flag directly.
581  *
582  * \return the newly created property variable instance.
583  */
584  WPropColor addProperty( std::string name, std::string description, const WPVBaseTypes::PV_COLOR& initial,
585  boost::shared_ptr< WCondition > condition, bool hide = false );
586 
587  /**
588  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
589  *
590  * \see WPropertyVariable
591  *
592  * \param name the property name
593  * \param description the property description
594  * \param initial the initial value
595  * \param condition use this external condition for notification.
596  * \param hide set to true to set the hide flag directly.
597  *
598  * \return the newly created property variable instance.
599  */
600  WPropTrigger addProperty( std::string name, std::string description, const WPVBaseTypes::PV_TRIGGER& initial,
601  boost::shared_ptr< WCondition > condition, bool hide = false );
602 
603  /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
604  // convenience methods for
605  // template< typename T>
606  // boost::shared_ptr< WPropertyVariable< T > > addProperty( std::string name, std::string description, const T& initial,
607  // WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
608  /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
609 
610  /**
611  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
612  *
613  * \see WPropertyVariable
614  *
615  * \param name the property name
616  * \param description the property description
617  * \param initial the initial value
618  * \param notifier use this notifier for change callbacks.
619  * \param hide set to true to set the hide flag directly.
620  *
621  * \return the newly created property variable instance.
622  */
623  WPropBool addProperty( std::string name, std::string description, const WPVBaseTypes::PV_BOOL& initial,
624  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
625 
626  /**
627  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
628  * It also sets the min and max constraint to [0,100].
629  *
630  * \see WPropertyVariable
631  *
632  * \param name the property name
633  * \param description the property description
634  * \param initial the initial value
635  * \param notifier use this notifier for change callbacks.
636  * \param hide set to true to set the hide flag directly.
637  *
638  * \return the newly created property variable instance.
639  */
640  WPropInt addProperty( std::string name, std::string description, const WPVBaseTypes::PV_INT& initial,
641  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
642 
643  /**
644  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
645  * It also sets the min and max constraint to [0,100].
646  *
647  * \see WPropertyVariable
648  *
649  * \param name the property name
650  * \param description the property description
651  * \param initial the initial value
652  * \param notifier use this notifier for change callbacks.
653  * \param hide set to true to set the hide flag directly.
654  *
655  * \return the newly created property variable instance.
656  */
657  WPropDouble addProperty( std::string name, std::string description, const WPVBaseTypes::PV_DOUBLE& initial,
658  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
659 
660  /**
661  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
662  *
663  * \see WPropertyVariable
664  *
665  * \param name the property name
666  * \param description the property description
667  * \param initial the initial value
668  * \param notifier use this notifier for change callbacks.
669  * \param hide set to true to set the hide flag directly.
670  *
671  * \return the newly created property variable instance.
672  */
673  WPropString addProperty( std::string name, std::string description, const WPVBaseTypes::PV_STRING& initial,
674  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
675 
676  /**
677  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
678  *
679  * \see WPropertyVariable
680  *
681  * \param name the property name
682  * \param description the property description
683  * \param initial the initial value
684  * \param notifier use this notifier for change callbacks.
685  * \param hide set to true to set the hide flag directly.
686  *
687  * \return the newly created property variable instance.
688  */
689  WPropFilename addProperty( std::string name, std::string description, const WPVBaseTypes::PV_PATH& initial,
690  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
691 
692  /**
693  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
694  *
695  * \see WPropertyVariable
696  *
697  * \param name the property name
698  * \param description the property description
699  * \param initial the initial value
700  * \param notifier use this notifier for change callbacks.
701  * \param hide set to true to set the hide flag directly.
702  *
703  * \return the newly created property variable instance.
704  */
705  WPropSelection addProperty( std::string name, std::string description, const WPVBaseTypes::PV_SELECTION& initial,
706  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
707 
708  /**
709  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
710  *
711  * \see WPropertyVariable
712  *
713  * \param name the property name
714  * \param description the property description
715  * \param initial the initial value
716  * \param notifier use this notifier for change callbacks.
717  * \param hide set to true to set the hide flag directly.
718  *
719  * \return the newly created property variable instance.
720  */
721  WPropPosition addProperty( std::string name, std::string description, const WPVBaseTypes::PV_POSITION& initial,
722  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
723 
724  /**
725  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
726  *
727  * \see WPropertyVariable
728  *
729  * \param name the property name
730  * \param description the property description
731  * \param initial the initial value
732  * \param notifier use this notifier for change callbacks.
733  * \param hide set to true to set the hide flag directly.
734  *
735  * \return the newly created property variable instance.
736  */
737  WPropColor addProperty( std::string name, std::string description, const WPVBaseTypes::PV_COLOR& initial,
738  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
739 
740  /**
741  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
742  *
743  * \see WPropertyVariable
744  *
745  * \param name the property name
746  * \param description the property description
747  * \param initial the initial value
748  * \param notifier use this notifier for change callbacks.
749  * \param hide set to true to set the hide flag directly.
750  *
751  * \return the newly created property variable instance.
752  */
753  WPropTrigger addProperty( std::string name, std::string description, const WPVBaseTypes::PV_TRIGGER& initial,
754  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
755 
756  /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
757  // convenience methods for
758  // template< typename T>
759  // boost::shared_ptr< WPropertyVariable< T > > addProperty( std::string name, std::string description, const T& initial,
760  // boost::shared_ptr< WCondition > condition,
761  // WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
762  /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
763 
764  /**
765  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
766  *
767  * \see WPropertyVariable
768  *
769  * \param name the property name
770  * \param description the property description
771  * \param initial the initial value
772  * \param notifier use this notifier for change callbacks.
773  * \param condition use this external condition for notification
774  * \param hide set to true to set the hide flag directly.
775  *
776  * \return the newly created property variable instance.
777  */
778  WPropBool addProperty( std::string name, std::string description, const WPVBaseTypes::PV_BOOL& initial,
779  boost::shared_ptr< WCondition > condition,
780  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
781 
782  /**
783  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
784  * It also sets the min and max constraint to [0,100].
785  *
786  * \see WPropertyVariable
787  *
788  * \param name the property name
789  * \param description the property description
790  * \param initial the initial value
791  * \param notifier use this notifier for change callbacks.
792  * \param condition use this external condition for notification
793  * \param hide set to true to set the hide flag directly.
794  *
795  * \return the newly created property variable instance.
796  */
797  WPropInt addProperty( std::string name, std::string description, const WPVBaseTypes::PV_INT& initial,
798  boost::shared_ptr< WCondition > condition,
799  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
800 
801  /**
802  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
803  * It also sets the min and max constraint to [0,100].
804  *
805  * \see WPropertyVariable
806  *
807  * \param name the property name
808  * \param description the property description
809  * \param initial the initial value
810  * \param notifier use this notifier for change callbacks.
811  * \param condition use this external condition for notification
812  * \param hide set to true to set the hide flag directly.
813  *
814  * \return the newly created property variable instance.
815  */
816  WPropDouble addProperty( std::string name, std::string description, const WPVBaseTypes::PV_DOUBLE& initial,
817  boost::shared_ptr< WCondition > condition,
818  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
819 
820 
821  /**
822  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
823  *
824  * \see WPropertyVariable
825  *
826  * \param name the property name
827  * \param description the property description
828  * \param initial the initial value
829  * \param notifier use this notifier for change callbacks.
830  * \param condition use this external condition for notification
831  * \param hide set to true to set the hide flag directly.
832  *
833  * \return the newly created property variable instance.
834  */
835  WPropString addProperty( std::string name, std::string description, const WPVBaseTypes::PV_STRING& initial,
836  boost::shared_ptr< WCondition > condition,
837  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
838 
839  /**
840  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
841  *
842  * \see WPropertyVariable
843  *
844  * \param name the property name
845  * \param description the property description
846  * \param initial the initial value
847  * \param notifier use this notifier for change callbacks.
848  * \param condition use this external condition for notification
849  * \param hide set to true to set the hide flag directly.
850  *
851  * \return the newly created property variable instance.
852  */
853  WPropFilename addProperty( std::string name, std::string description, const WPVBaseTypes::PV_PATH& initial,
854  boost::shared_ptr< WCondition > condition,
855  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
856 
857  /**
858  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
859  *
860  * \see WPropertyVariable
861  *
862  * \param name the property name
863  * \param description the property description
864  * \param initial the initial value
865  * \param notifier use this notifier for change callbacks.
866  * \param condition use this external condition for notification
867  * \param hide set to true to set the hide flag directly.
868  *
869  * \return the newly created property variable instance.
870  */
871  WPropSelection addProperty( std::string name, std::string description, const WPVBaseTypes::PV_SELECTION& initial,
872  boost::shared_ptr< WCondition > condition,
873  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
874 
875  /**
876  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
877  *
878  * \see WPropertyVariable
879  *
880  * \param name the property name
881  * \param description the property description
882  * \param initial the initial value
883  * \param notifier use this notifier for change callbacks.
884  * \param condition use this external condition for notification
885  * \param hide set to true to set the hide flag directly.
886  *
887  * \return the newly created property variable instance.
888  */
889  WPropPosition addProperty( std::string name, std::string description, const WPVBaseTypes::PV_POSITION& initial,
890  boost::shared_ptr< WCondition > condition,
891  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
892 
893  /**
894  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
895  *
896  * \see WPropertyVariable
897  *
898  * \param name the property name
899  * \param description the property description
900  * \param initial the initial value
901  * \param notifier use this notifier for change callbacks.
902  * \param condition use this external condition for notification
903  * \param hide set to true to set the hide flag directly.
904  *
905  * \return the newly created property variable instance.
906  */
907  WPropColor addProperty( std::string name, std::string description, const WPVBaseTypes::PV_COLOR& initial,
908  boost::shared_ptr< WCondition > condition,
909  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
910 
911  /**
912  * Create and add a new property of the template type. For more details see appropriate constructor ow WPropertyVariable.
913  *
914  * \see WPropertyVariable
915  *
916  * \param name the property name
917  * \param description the property description
918  * \param initial the initial value
919  * \param notifier use this notifier for change callbacks.
920  * \param condition use this external condition for notification
921  * \param hide set to true to set the hide flag directly.
922  *
923  * \return the newly created property variable instance.
924  */
925  WPropTrigger addProperty( std::string name, std::string description, const WPVBaseTypes::PV_TRIGGER& initial,
926  boost::shared_ptr< WCondition > condition,
927  WPropertyBase::PropertyChangeNotifierType notifier, bool hide = false );
928 
929  /**
930  * This returns the condition fired whenever one children fires its update condition. Useful to get notified about all changes that happen.
931  *
932  * \return the condition fired if a child fires its update condition.
933  */
934  virtual boost::shared_ptr< WCondition > getChildUpdateCondition() const;
935 
936 protected:
937 
938  /**
939  * Helping function to find a property inside a specific group. It does not recursively find properties nested inside other property groups.
940  *
941  * \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
942  * findProperty as it is contained in this or a nested properties instance.
943  * \param name the name of the property inside THIS group.
944  *
945  * \return the property if found, else NULL.
946  */
947  boost::shared_ptr< WPropertyBase > findProperty( const WProperties* const props, std::string name ) const;
948 
949 private:
950 
951  /**
952  * The set of proerties. This uses the operators ==,<,> WProperty to determine equalness.
953  */
955 
956  /**
957  * Condition notified whenever a property inside this group fires its WPropertyBase::m_updateCondition. This is especially useful to get a
958  * notification if something updates without further knowledge what changed. Useful if you want to listen for updates in modules for example.
959  *
960  * \see getChildUpdateCondition
961  */
962  boost::shared_ptr< WConditionSet > m_childUpdateCondition;
963 
964  /**
965  * Compares the names of two properties and returns true if they are equal.
966  *
967  * \param prop1 the first prop.
968  * \param prop2 the second prop.
969  *
970  * \return Are the names of the two properties equal?
971  */
972  bool propNamePredicate( boost::shared_ptr< WPropertyBase > prop1, boost::shared_ptr< WPropertyBase > prop2 ) const;
973 };
974 
975 template< typename PropType >
976 PropType WProperties::addProperty( PropType prop )
977 {
978  // lock, unlocked if l looses focus
980 
981  // NOTE: WPropertyBase already prohibits invalid property names -> no check needed here
982 
983  // check uniqueness:
984  if( std::count_if( l->get().begin(), l->get().end(),
985  boost::bind( boost::mem_fn( &WProperties::propNamePredicate ), this, prop, _1 ) ) )
986  {
987  // unlock explicitly
988  l.reset();
989 
990  // oh oh, this property name is not unique in this group
991  if( !getName().empty() )
992  {
993  throw WPropertyNotUnique( std::string( "Property \"" + prop->getName() + "\" is not unique in this group (\"" + getName() + "\")." ) );
994  }
995  else
996  {
997  throw WPropertyNotUnique( std::string( "Property \"" + prop->getName() + "\" is not unique in this group (unnamed root)." ) );
998  }
999  }
1000 
1001  // PV_PURPOSE_INFORMATION groups do not allow PV_PURPOSE_PARAMETER properties but vice versa.
1002  if( getPurpose() == PV_PURPOSE_INFORMATION )
1003  {
1004  prop->setPurpose( PV_PURPOSE_INFORMATION );
1005  }
1006  // INFORMATION properties are allowed inside PARAMETER groups -> do not set the properties purpose.
1007 
1008  l->get().push_back( prop );
1009 
1010  // add the child's update condition to the list
1011  m_childUpdateCondition->add( prop->getUpdateCondition() );
1012 
1013  return prop;
1014 }
1015 
1016 template< typename T>
1017 boost::shared_ptr< WPropertyVariable< T > > WProperties::addProperty( std::string name, std::string description, const T& initial, bool hide )
1018 {
1019  boost::shared_ptr< WPropertyVariable< T > > p = boost::shared_ptr< WPropertyVariable< T > >(
1020  new WPropertyVariable< T >( name, description, initial )
1021  );
1022  p->setHidden( hide );
1023  addProperty( p );
1024  return p;
1025 }
1026 
1027 template< typename T>
1028 boost::shared_ptr< WPropertyVariable< T > > WProperties::addProperty( std::string name, std::string description, const T& initial,
1029  boost::shared_ptr< WCondition > condition, bool hide )
1030 {
1031  boost::shared_ptr< WPropertyVariable< T > > p = boost::shared_ptr< WPropertyVariable< T > >(
1032  new WPropertyVariable< T >( name, description, initial, condition )
1033  );
1034  p->setHidden( hide );
1035  addProperty( p );
1036  return p;
1037 }
1038 
1039 template< typename T>
1040 boost::shared_ptr< WPropertyVariable< T > > WProperties::addProperty( std::string name, std::string description, const T& initial,
1041  WPropertyBase::PropertyChangeNotifierType notifier, bool hide )
1042 {
1043  boost::shared_ptr< WPropertyVariable< T > > p = boost::shared_ptr< WPropertyVariable< T > >(
1044  new WPropertyVariable< T >( name, description, initial, notifier )
1045  );
1046  p->setHidden( hide );
1047  addProperty( p );
1048  return p;
1049 }
1050 
1051 template< typename T>
1052 boost::shared_ptr< WPropertyVariable< T > > WProperties::addProperty( std::string name, std::string description, const T& initial,
1053  boost::shared_ptr< WCondition > condition,
1054  WPropertyBase::PropertyChangeNotifierType notifier, bool hide )
1055 {
1056  boost::shared_ptr< WPropertyVariable< T > > p = boost::shared_ptr< WPropertyVariable< T > >(
1057  new WPropertyVariable< T >( name, description, initial, condition, notifier )
1058  );
1059  p->setHidden( hide );
1060  addProperty( p );
1061  return p;
1062 }
1063 
1064 #endif // WPROPERTIES_H