OpenWalnut  1.4.0
WPropertyBase.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 WPROPERTYBASE_H
26 #define WPROPERTYBASE_H
27 
28 #include <string>
29 
30 #ifndef Q_MOC_RUN
31 #include <boost/function.hpp>
32 #endif
33 #ifndef Q_MOC_RUN
34 #include <boost/signals2/signal.hpp>
35 #endif
36 
37 #ifndef Q_MOC_RUN
38 #include <boost/shared_ptr.hpp>
39 #endif
40 #ifndef Q_MOC_RUN
41 #include <boost/enable_shared_from_this.hpp>
42 #endif
43 
44 #include "WProperties_Fwd.h"
45 #include "WCondition.h"
46 #include "WConditionSet.h"
47 
48 
49 /**
50  * Abstract base class for all properties. Simply provides name and type information.
51  */
52 class WPropertyBase: public boost::enable_shared_from_this< WPropertyBase >
53 {
54 public:
55  /**
56  * Convenience typedef for a boost::shared_ptr< WPropertyBase >
57  */
58  typedef boost::shared_ptr< WPropertyBase > SPtr;
59 
60  /**
61  * Convenience typedef for a boost::shared_ptr< const WPropertyBase >
62  */
63  typedef boost::shared_ptr< const WPropertyBase > ConstSPtr;
64 
65  /**
66  * Create an empty named property.
67  *
68  * \param name the name of the property
69  * \param description the description of the property
70  */
71  WPropertyBase( std::string name, std::string description );
72 
73  /**
74  * Copy constructor. Creates a deep copy of this property. As boost::signals2 and condition variables are non-copyable, new instances get
75  * created. The subscriptions to a signal are LOST as well as all listeners to a condition.
76  *
77  * \param from the instance to copy.
78  */
79  explicit WPropertyBase( const WPropertyBase& from );
80 
81  /**
82  * Destructor.
83  */
84  virtual ~WPropertyBase();
85 
86  /**
87  * 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
88  * correct type without explicitly requiring the user to specify it. It creates a NEW change condition and change signal. This means, alls
89  * subscribed signal handlers are NOT copied.
90  *
91  * \note this simply ensures the copy constructor of the runtime type is issued.
92  *
93  * \return the deep clone of this property.
94  */
95  virtual boost::shared_ptr< WPropertyBase > clone() = 0;
96 
97  /**
98  * Gets the name of the class.
99  *
100  * \return the name.
101  */
102  std::string getName() const;
103 
104  /**
105  * Gets the description of the property.
106  *
107  * \return the description
108  */
109  std::string getDescription() const;
110 
111  /**
112  * Determines whether the property is hidden or not.
113  *
114  * \return true if hidden
115  */
116  bool isHidden() const;
117 
118  /**
119  * Sets the property hidden. This flag is especially used by the GUI.
120  *
121  * \param hidden true if it should be hidden.
122  */
123  void setHidden( bool hidden = true );
124 
125  /**
126  * Gets the real WPropertyVariable type of this instance.
127  *
128  * \return the real type.
129  */
130  virtual PROPERTY_TYPE getType() const;
131 
132  /**
133  * Gets the purpose of a property. See PROPERTY_PURPOSE for more details. For short: it helps the GUI and others to understand what a module
134  * (or whomever created this property) intents with this property. Typically this value is PV_PURPOSE_PARAMETER, meaning that it is used to
135  * tune the behaviour of a module.
136  *
137  * \note always assume this to be a hint. It does not actually prevent someone from writing or interpreting a parameter property as an
138  * information property.
139  *
140  * \see PROPERTY_PURPOSE
141  * \return the purpose.
142  */
143  virtual PROPERTY_PURPOSE getPurpose() const;
144 
145  /**
146  * Sets the purpose of the property. See \ref getPurpose for more details. You generally should avoid setting this value after
147  * initialization.
148  *
149  * \param purpose the purpose to set.
150  */
151  virtual void setPurpose( PROPERTY_PURPOSE purpose );
152 
153  /**
154  * This methods allows properties to be set by a string value. This is especially useful when a property is only available as string and the
155  * real type of the property is unknown. This is a shortcut for casting the property and then setting the lexically casted value.
156  *
157  * \param value the new value to set.
158  *
159  * \return true if value could be set.
160  */
161  virtual bool setAsString( std::string value ) = 0;
162 
163  /**
164  * Returns the current value as a string. This is useful for debugging or project files. It is not implemented as << operator, since the <<
165  * should also print min/max constraints and so on. This simply is the value.
166  *
167  * \return the value as a string.
168  */
169  virtual std::string getAsString() = 0;
170 
171  /**
172  * This method returns a condition which gets fired whenever the property changes somehow. It is fired when:
173  * \li \ref setHidden is called and the hidden state changes
174  * \li \ref setAsString is called and the value changes
175  * \li WPropertyVariable::set is called and the value changes (regardless of suppression during set)
176  * \li WPropertyVariable::setMin/setMax is called and the value changes
177  * \li WPropertyVariable::addConstraint is called
178  * \li WPropertyVariable::removeConstraints is called
179  * \li WProperties::addProperty is called
180  * \li WProperties::removeProperty is called
181  * \li WProperties::addPropertyGroup is called
182  * This is especially useful if you simply want to know that something has happened.
183  *
184  * \return a condition notified whenever something changes.
185  */
186  virtual boost::shared_ptr< WCondition > getUpdateCondition() const;
187 
188  /**
189  * Sets the value from the specified property to this one. This is especially useful to copy a value without explicitly casting/knowing the
190  * dynamic type of the property.
191  *
192  * \param value the new value.
193  * \param recommendedOnly if true, property types which support recommended values apply the given value as recommendation.
194  *
195  * \return true if the value has been accepted.
196  */
197  virtual bool set( boost::shared_ptr< WPropertyBase > value, bool recommendedOnly = false ) = 0;
198 
199  /////////////////////////////////////////////////////////////////////////////////////////////
200  // Helpers for easy conversion to the possible types
201  /////////////////////////////////////////////////////////////////////////////////////////////
202 
203  /**
204  * Helper converts this instance to its native type.
205  *
206  * \return the property as integer property
207  */
208  WPropInt toPropInt();
209 
210  /**
211  * Helper converts this instance to its native type.
212  *
213  * \return the property as double property
214  */
215  WPropDouble toPropDouble();
216 
217  /**
218  * Helper converts this instance to its native type.
219  *
220  * \return the property as bool property
221  */
222  WPropBool toPropBool();
223 
224  /**
225  * Helper converts this instance to its native type.
226  *
227  * \return the property as string property
228  */
229  WPropString toPropString();
230 
231  /**
232  * Helper converts this instance to its native type.
233  *
234  * \return the property as path property
235  */
236  WPropFilename toPropFilename();
237 
238  /**
239  * Helper converts this instance to its native type.
240  *
241  * \return the property as selection property
242  */
243  WPropSelection toPropSelection();
244 
245  /**
246  * Helper converts this instance to its native type.
247  *
248  * \return the property as color property
249  */
250  WPropColor toPropColor();
251 
252  /**
253  * Helper converts this instance to its native type.
254  *
255  * \return the property as position property
256  */
257  WPropPosition toPropPosition();
258 
259  /**
260  * Helper converts this instance to its native type.
261  *
262  * \return the property as trigger property
263  */
264  WPropTrigger toPropTrigger();
265 
266  /**
267  * Helper converts this instance to its native type.
268  *
269  * \return the property as matrix4x4 property
270  */
271  WPropMatrix4X4 toPropMatrix4X4();
272 
273  /**
274  * Helper converts this instance to its native type.
275  *
276  * \return the property as transfer function property
277  */
278  WPropTransferFunction toPropTransferFunction();
279 
280  /**
281  * Helper converts this instance to its native type.
282  *
283  * \return the property as group
284  */
285  WPropGroup toPropGroup();
286 
287  /**
288  * Helper converts this instance to its native type.
289  *
290  * \return the property as interval property
291  */
292  WPropInterval toPropInterval();
293 
294  /**
295  * Convert the property to a WPropertyGroupBase. This can be done with property structs and groups-
296  *
297  * \return the property as base group.
298  */
299  boost::shared_ptr< WPropertyGroupBase > toPropGroupBase();
300 
301  /**
302  * Helper converts this instance to an arbitrary type.
303  *
304  * \return the property of given type of NULL if not valid type
305  */
306  template< typename T >
307  boost::shared_ptr< WPropertyVariable< T > > toPropertyVariable();
308 
309  /**
310  * Signal signature emitted during set operations
311  */
312  typedef boost::function<void ( boost::shared_ptr< WPropertyBase > )> PropertyChangeNotifierType;
313 
314 protected:
315  /**
316  * Name of the property.
317  */
318  std::string m_name;
319 
320  /**
321  * Description of the property.
322  */
323  std::string m_description;
324 
325  /**
326  * Flag denoting whether the property is hidden or not.
327  */
328  bool m_hidden;
329 
330  /**
331  * Type of the PropertyVariable instance
332  */
333  PROPERTY_TYPE m_type;
334 
335  /**
336  * The purpose of this property. PropertyBase always initializes it with PV_PURPOSE_PARAMETER.
337  */
338  PROPERTY_PURPOSE m_purpose;
339 
340  /**
341  * Calculates the type of the property. This has to be done by the implementing class.
342  */
343  virtual void updateType();
344 
345  /**
346  * Signal used for firing change signals
347  */
348  typedef boost::signals2::signal<void ( boost::shared_ptr< WPropertyBase > )> PropertyChangeSignalType;
349 
350  /**
351  * Signal getting fired whenever the property changes.
352  */
354 
355  /**
356  * Condition notified whenever something changes. See getUpdateCondition for more details.
357  * \see getUpdateCondition
358  */
359  boost::shared_ptr< WConditionSet > m_updateCondition;
360 
361 private:
362 };
363 
364 template< typename T >
365 boost::shared_ptr< WPropertyVariable< T > > WPropertyBase::toPropertyVariable()
366 {
367  return boost::dynamic_pointer_cast< WPropertyVariable< T > >( shared_from_this() );
368 }
369 
370 #endif // WPROPERTYBASE_H
371 
WPropTransferFunction toPropTransferFunction()
Helper converts this instance to its native type.
WPropMatrix4X4 toPropMatrix4X4()
Helper converts this instance to its native type.
WPropertyBase(std::string name, std::string description)
Create an empty named property.
boost::signals2::signal< void(boost::shared_ptr< WPropertyBase >)> PropertyChangeSignalType
Signal used for firing change signals.
virtual boost::shared_ptr< WCondition > getUpdateCondition() const
This method returns a condition which gets fired whenever the property changes somehow.
boost::shared_ptr< WPropertyVariable< T > > toPropertyVariable()
Helper converts this instance to an arbitrary type.
WPropSelection toPropSelection()
Helper converts this instance to its native type.
WPropColor toPropColor()
Helper converts this instance to its native type.
virtual ~WPropertyBase()
Destructor.
A named property class with a concrete type.
boost::shared_ptr< const WPropertyBase > ConstSPtr
Convenience typedef for a boost::shared_ptr< const WPropertyBase >
Definition: WPropertyBase.h:63
boost::function< void(boost::shared_ptr< WPropertyBase >)> PropertyChangeNotifierType
Signal signature emitted during set operations.
WPropTrigger toPropTrigger()
Helper converts this instance to its native type.
virtual void setPurpose(PROPERTY_PURPOSE purpose)
Sets the purpose of the property.
virtual PROPERTY_TYPE getType() const
Gets the real WPropertyVariable type of this instance.
PROPERTY_TYPE m_type
Type of the PropertyVariable instance.
WPropGroup toPropGroup()
Helper converts this instance to its native type.
WPropInt toPropInt()
Helper converts this instance to its native type.
boost::shared_ptr< WConditionSet > m_updateCondition
Condition notified whenever something changes.
boost::shared_ptr< WPropertyGroupBase > toPropGroupBase()
Convert the property to a WPropertyGroupBase.
virtual PROPERTY_PURPOSE getPurpose() const
Gets the purpose of a property.
std::string m_name
Name of the property.
virtual bool setAsString(std::string value)=0
This methods allows properties to be set by a string value.
virtual std::string getAsString()=0
Returns the current value as a string.
WPropDouble toPropDouble()
Helper converts this instance to its native type.
virtual bool set(boost::shared_ptr< WPropertyBase > value, bool recommendedOnly=false)=0
Sets the value from the specified property to this one.
bool m_hidden
Flag denoting whether the property is hidden or not.
PROPERTY_PURPOSE m_purpose
The purpose of this property.
WPropBool toPropBool()
Helper converts this instance to its native type.
std::string m_description
Description of the property.
void setHidden(bool hidden=true)
Sets the property hidden.
PropertyChangeSignalType signal_PropertyChange
Signal getting fired whenever the property changes.
Abstract base class for all properties.
Definition: WPropertyBase.h:52
virtual boost::shared_ptr< WPropertyBase > clone()=0
This method clones a property and returns the clone.
boost::shared_ptr< WPropertyBase > SPtr
Convenience typedef for a boost::shared_ptr< WPropertyBase >
Definition: WPropertyBase.h:58
bool isHidden() const
Determines whether the property is hidden or not.
WPropFilename toPropFilename()
Helper converts this instance to its native type.
WPropInterval toPropInterval()
Helper converts this instance to its native type.
WPropPosition toPropPosition()
Helper converts this instance to its native type.
WPropString toPropString()
Helper converts this instance to its native type.
virtual void updateType()
Calculates the type of the property.
std::string getName() const
Gets the name of the class.
std::string getDescription() const
Gets the description of the property.