3 * Interface definition for a property list.
4 * Started Fall 2000 by David Megginson, david@megginson.com
5 * This code is released into the Public Domain.
7 * See props.html for documentation [replace with URL when available].
15 #ifndef PROPS_STANDALONE
16 #define PROPS_STANDALONE 0
25 #include <boost/utility.hpp>
26 #include <boost/type_traits/is_enum.hpp>
30 #include <simgear/compiler.h>
31 #include <simgear/debug/logstream.hxx>
35 #include <simgear/math/SGMathFwd.hxx>
36 #include <simgear/math/sg_types.hxx>
37 #include <simgear/structure/SGReferenced.hxx>
38 #include <simgear/structure/SGSharedPtr.hxx>
40 // XXX This whole file should be in the simgear namespace, but I don't
41 // have the guts yet...
46 class PropertyInterpolationMgr;
49 std::istream& readFrom(std::istream& stream, T& result)
56 * Parse a string as an object of a given type.
57 * XXX no error behavior yet.
59 * @tparam T the return type
60 * @param str the string
64 inline T parseString(const std::string& str)
66 std::istringstream stream(str);
68 readFrom(stream, result);
73 * Property value types.
77 #pragma warn A sloppy coder has defined NONE as a macro!
82 #pragma warn A sloppy coder has defined ALIAS as a macro!
87 #pragma warn A sloppy coder has defined UNSPECIFIED as a macro!
92 #pragma warn A sloppy coder has defined BOOL as a macro!
97 #pragma warn A sloppy coder has defined INT as a macro!
102 #pragma warn A sloppy coder has defined LONG as a macro!
107 #pragma warn A sloppy coder has defined FLOAT as a macro!
112 #pragma warn A sloppy coder has defined DOUBLE as a macro!
117 #pragma warn A sloppy coder has defined STRING as a macro!
124 * The possible types of an SGPropertyNode. Types that appear after
125 * EXTENDED are not stored in the SGPropertyNode itself.
128 NONE = 0, /**< The node hasn't been assigned a value yet. */
129 ALIAS, /**< The node "points" to another node. */
137 EXTENDED, /**< The node's value is not stored in the property;
138 * the actual value and type is retrieved from an
139 * SGRawValue node. This type is never returned by @see
140 * SGPropertyNode::getType.
142 // Extended properties
147 template<typename T> struct PropertyTraits;
149 #define DEFINTERNALPROP(TYPE, PROP) \
151 struct PropertyTraits<TYPE> \
153 static const Type type_tag = PROP; \
154 enum { Internal = 1 }; \
157 DEFINTERNALPROP(bool, BOOL);
158 DEFINTERNALPROP(int, INT);
159 DEFINTERNALPROP(long, LONG);
160 DEFINTERNALPROP(float, FLOAT);
161 DEFINTERNALPROP(double, DOUBLE);
162 DEFINTERNALPROP(const char *, STRING);
163 DEFINTERNALPROP(const char[], STRING);
164 #undef DEFINTERNALPROP
171 ////////////////////////////////////////////////////////////////////////
174 // This is the mechanism that information-providing routines can
175 // use to link their own values to the property manager. Any
176 // SGValue can be tied to a raw value and then untied again.
178 // Note: we are forced to use inlined methods here to ensure
179 // that the templates will be instantiated. We're probably taking
180 // a small performance hit for that.
181 ////////////////////////////////////////////////////////////////////////
184 * Base class for SGRawValue classes that holds no type
185 * information. This allows some generic manipulation of the
192 * Get the type enumeration for the raw value.
196 virtual simgear::props::Type getType() const = 0;
200 * Create a new deep copy of this raw value.
202 * The copy will contain its own version of the underlying value
203 * as well, and will be the same type.
205 * @return A deep copy of the current object.
207 virtual SGRaw* clone() const = 0;
211 class SGRawExtended : public SGRaw
215 * Make an SGRawValueContainer from the SGRawValue.
217 * This is a virtual function of SGRawExtended so that
218 * SGPropertyNode::untie doesn't need to know the type of an
221 virtual SGRawExtended* makeContainer() const = 0;
223 * Write value out to a stream
225 virtual std::ostream& printOn(std::ostream& stream) const = 0;
227 * Read value from a stream and store it.
229 virtual std::istream& readFrom(std::istream& stream) = 0;
232 // Choose between different base classes based on whether the value is
233 // stored internal to the property node. This frees us from defining
234 // the virtual functions in the SGRawExtended interface where they
235 // don't make sense, e.g. readFrom for the const char* type.
236 template<typename T, int internal = simgear::props::PropertyTraits<T>::Internal>
240 class SGRawBase<T, 1> : public SGRaw
245 class SGRawBase<T, 0> : public SGRawExtended
247 virtual SGRawExtended* makeContainer() const;
248 virtual std::ostream& printOn(std::ostream& stream) const;
249 virtual std::istream& readFrom(std::istream& stream);
253 * Abstract base class for a raw value.
255 * <p>The property manager is implemented in two layers. The {@link
256 * SGPropertyNode} is the highest and most abstract layer,
257 * representing an LValue/RValue pair: it records the position of the
258 * property in the property tree and contains facilities for
259 * navigation to other nodes. It is guaranteed to be persistent: the
260 * {@link SGPropertyNode} will not change during a session, even if
261 * the property is bound and unbound multiple times.</p>
263 * <p>When the property value is not managed internally in the
264 * SGPropertyNode, the SGPropertyNode will contain a reference to an
265 * SGRawValue (this class), which provides an abstract way to get,
266 * set, and clone the underlying value. The SGRawValue may change
267 * frequently during a session as a value is retyped or bound and
268 * unbound to various data source, but the abstract SGPropertyNode
269 * layer insulates the application from those changes.
271 * <p>The SGPropertyNode class always keeps a *copy* of a raw value,
272 * not the original one passed to it; if you override a derived class
273 * but do not replace the {@link #clone} method, strange things will
276 * <p>All derived SGRawValue classes must implement {@link #getValue},
277 * {@link #setValue}, and {@link #clone} for the appropriate type.</p>
279 * @see SGPropertyNode
280 * @see SGRawValuePointer
281 * @see SGRawValueFunctions
282 * @see SGRawValueFunctionsIndexed
283 * @see SGRawValueMethods
284 * @see SGRawValueMethodsIndexed
285 * @see SGRawValueContainer
288 class SGRawValue : public SGRawBase<T>
293 * The default underlying value for this type.
295 * Every raw value has a default; the default is false for a
296 * boolean, 0 for the various numeric values, and "" for a string.
297 * If additional types of raw values are added in the future, they
298 * may need different kinds of default values (such as epoch for a
299 * date type). The default value is used when creating new values.
301 static T DefaultValue()
310 * Use the default value for this type.
318 virtual ~SGRawValue () {}
322 * Return the underlying value.
324 * @return The actual value for the property.
327 virtual T getValue () const = 0;
331 * Assign a new underlying value.
333 * If the new value cannot be set (because this is a read-only
334 * raw value, or because the new value is not acceptable for
335 * some reason) this method returns false and leaves the original
338 * @param value The actual value for the property.
339 * @return true if the value was set successfully, false otherwise.
342 virtual bool setValue (T value) = 0;
346 * Return the type tag for this raw value type.
348 virtual simgear::props::Type getType() const
350 return simgear::props::PropertyTraits<T>::type_tag;
356 ////////////////////////////////////////////////////////////////////////
357 // Default values for every type.
358 ////////////////////////////////////////////////////////////////////////
360 template<> inline bool SGRawValue<bool>::DefaultValue()
365 template<> inline const char * SGRawValue<const char *>::DefaultValue()
371 * A raw value bound to a pointer.
373 * This is the most efficient way to tie an external value, but also
374 * the most dangerous, because there is no way for the supplier to
375 * perform bounds checking and derived calculations except by polling
376 * the variable to see if it has changed. There is no default
377 * constructor, because this class would be meaningless without a
381 class SGRawValuePointer : public SGRawValue<T>
386 * Explicit pointer constructor.
388 * Create a new raw value bound to the value of the variable
389 * referenced by the pointer.
391 * @param ptr The pointer to the variable to which this raw value
394 SGRawValuePointer (T * ptr) : _ptr(ptr) {}
399 virtual ~SGRawValuePointer () {}
402 * Get the underlying value.
404 * This method will dereference the pointer and return the
407 virtual T getValue () const { return *_ptr; }
410 * Set the underlying value.
412 * This method will dereference the pointer and change the
415 virtual bool setValue (T value) { *_ptr = value; return true; }
418 * Create a copy of this raw value.
420 * The copy will use the same external pointer as the original.
422 virtual SGRaw* clone () const {
423 return new SGRawValuePointer(_ptr);
432 * A value managed through static functions.
434 * A read-only value will not have a setter; a write-only value will
438 class SGRawValueFunctions : public SGRawValue<T>
443 * The template type of a static getter function.
445 typedef T (*getter_t)();
448 * The template type of a static setter function.
450 typedef void (*setter_t)(T);
453 * Explicit constructor.
455 * Create a new raw value bound to the getter and setter supplied.
457 * @param getter A static function for getting a value, or 0
458 * to read-disable the value.
459 * @param setter A static function for setting a value, or 0
460 * to write-disable the value.
462 SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
463 : _getter(getter), _setter(setter) {}
468 virtual ~SGRawValueFunctions () {}
471 * Get the underlying value.
473 * This method will invoke the getter function to get a value.
474 * If no getter function was supplied, this method will always
475 * return the default value for the type.
477 virtual T getValue () const {
478 if (_getter) return (*_getter)();
479 else return SGRawValue<T>::DefaultValue();
483 * Set the underlying value.
485 * This method will invoke the setter function to change the
486 * underlying value. If no setter function was supplied, this
487 * method will return false.
489 virtual bool setValue (T value) {
490 if (_setter) { (*_setter)(value); return true; }
495 * Create a copy of this raw value, bound to the same functions.
497 virtual SGRaw* clone () const {
498 return new SGRawValueFunctions(_getter,_setter);
508 * An indexed value bound to static functions.
510 * A read-only value will not have a setter; a write-only value will
511 * not have a getter. An indexed value is useful for binding one
512 * of a list of possible values (such as multiple engines for a
513 * plane). The index is hard-coded at creation time.
518 class SGRawValueFunctionsIndexed : public SGRawValue<T>
521 typedef T (*getter_t)(int);
522 typedef void (*setter_t)(int,T);
523 SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
524 : _index(index), _getter(getter), _setter(setter) {}
525 virtual ~SGRawValueFunctionsIndexed () {}
526 virtual T getValue () const {
527 if (_getter) return (*_getter)(_index);
528 else return SGRawValue<T>::DefaultValue();
530 virtual bool setValue (T value) {
531 if (_setter) { (*_setter)(_index, value); return true; }
534 virtual SGRaw* clone () const {
535 return new SGRawValueFunctionsIndexed(_index, _getter, _setter);
545 * A value managed through an object and access methods.
547 * A read-only value will not have a setter; a write-only value will
550 template <class C, class T>
551 class SGRawValueMethods : public SGRawValue<T>
554 typedef T (C::*getter_t)() const;
555 typedef void (C::*setter_t)(T);
556 SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
557 : _obj(obj), _getter(getter), _setter(setter) {}
558 virtual ~SGRawValueMethods () {}
559 virtual T getValue () const {
560 if (_getter) { return (_obj.*_getter)(); }
561 else { return SGRawValue<T>::DefaultValue(); }
563 virtual bool setValue (T value) {
564 if (_setter) { (_obj.*_setter)(value); return true; }
567 virtual SGRaw* clone () const {
568 return new SGRawValueMethods(_obj, _getter, _setter);
578 * An indexed value managed through an object and access methods.
580 * A read-only value will not have a setter; a write-only value will
583 template <class C, class T>
584 class SGRawValueMethodsIndexed : public SGRawValue<T>
587 typedef T (C::*getter_t)(int) const;
588 typedef void (C::*setter_t)(int, T);
589 SGRawValueMethodsIndexed (C &obj, int index,
590 getter_t getter = 0, setter_t setter = 0)
591 : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
592 virtual ~SGRawValueMethodsIndexed () {}
593 virtual T getValue () const {
594 if (_getter) { return (_obj.*_getter)(_index); }
595 else { return SGRawValue<T>::DefaultValue(); }
597 virtual bool setValue (T value) {
598 if (_setter) { (_obj.*_setter)(_index, value); return true; }
601 virtual SGRaw* clone () const {
602 return new SGRawValueMethodsIndexed(_obj, _index, _getter, _setter);
612 * A raw value that contains its value. This provides a way for
613 * property nodes to contain values that shouldn't be stored in the
614 * property node itself.
617 class SGRawValueContainer : public SGRawValue<T>
622 * Explicit constructor.
624 SGRawValueContainer(const T& obj) : _obj(obj) {}
629 virtual ~SGRawValueContainer() {}
632 * Get the underlying value.
634 virtual T getValue() const { return _obj; }
637 * Set the underlying value.
639 * This method will dereference the pointer and change the
642 virtual bool setValue (T value) { _obj = value; return true; }
645 * Create a copy of this raw value.
647 virtual SGRaw* clone () const {
648 return new SGRawValueContainer(_obj);
656 SGRawExtended* SGRawBase<T, 0>::makeContainer() const
658 return new SGRawValueContainer<T>(static_cast<const SGRawValue<T>*>(this)
663 std::ostream& SGRawBase<T, 0>::printOn(std::ostream& stream) const
665 return stream << static_cast<SGRawValue<T>*>(this)->getValue();
669 std::istream& SGRawBase<T, 0>::readFrom(std::istream& stream)
672 simgear::readFrom(stream, value);
673 static_cast<SGRawValue<T>*>(this)->setValue(value);
678 * The smart pointer that manage reference counting
680 class SGPropertyNode;
681 typedef SGSharedPtr<SGPropertyNode> SGPropertyNode_ptr;
682 typedef SGSharedPtr<const SGPropertyNode> SGConstPropertyNode_ptr;
686 typedef std::vector<SGPropertyNode_ptr> PropertyList;
690 * The property change listener interface.
692 * <p>Any class that needs to listen for property changes must implement
693 * this interface.</p>
695 class SGPropertyChangeListener
698 virtual ~SGPropertyChangeListener ();
699 virtual void valueChanged (SGPropertyNode * node);
700 virtual void childAdded (SGPropertyNode * parent, SGPropertyNode * child);
701 virtual void childRemoved (SGPropertyNode * parent, SGPropertyNode * child);
704 friend class SGPropertyNode;
705 virtual void register_property (SGPropertyNode * node);
706 virtual void unregister_property (SGPropertyNode * node);
709 std::vector<SGPropertyNode *> _properties;
714 * A node in a property tree.
716 class SGPropertyNode : public SGReferenced
724 MAX_STRING_LEN = 1024
728 * Access mode attributes.
730 * <p>The ARCHIVE attribute is strictly advisory, and controls
731 * whether the property should normally be saved and restored.</p>
743 // beware: if you add another attribute here,
744 // also update value of "LAST_USED_ATTRIBUTE".
749 * Last used attribute
750 * Update as needed when enum Attribute is changed
752 static const int LAST_USED_ATTRIBUTE;
755 * Default constructor.
763 SGPropertyNode (const SGPropertyNode &node);
769 virtual ~SGPropertyNode ();
778 * Test whether this node contains a primitive leaf value.
780 bool hasValue () const { return (_type != simgear::props::NONE); }
784 * Get the node's simple (XML) name.
786 const char * getName () const { return _name.c_str(); }
789 * Get the node's simple name as a string.
791 const std::string& getNameString () const { return _name; }
794 * Get the node's pretty display name, with subscript when needed.
796 std::string getDisplayName (bool simplify = false) const;
800 * Get the node's integer index.
802 int getIndex () const { return _index; }
806 * Get a non-const pointer to the node's parent.
808 SGPropertyNode * getParent () { return _parent; }
812 * Get a const pointer to the node's parent.
814 const SGPropertyNode * getParent () const { return _parent; }
823 * Get the number of child nodes.
825 int nChildren () const { return (int)_children.size(); }
829 * Get a child node by position (*NOT* index).
831 SGPropertyNode * getChild (int position);
835 * Get a const child node by position (*NOT* index).
837 const SGPropertyNode * getChild (int position) const;
841 * Test whether a named child exists.
843 bool hasChild (const char * name, int index = 0) const
845 return (getChild(name, index) != 0);
849 * Test whether a named child exists.
851 bool hasChild (const std::string& name, int index = 0) const
853 return (getChild(name, index) != 0);
857 * Create a new child node with the given name and an unused index
859 * @param min_index Minimal index for new node (skips lower indices)
860 * @param append Whether to simply use the index after the last used index
861 * or use a lower, unused index if it exists
863 SGPropertyNode * addChild ( const char* name,
865 bool append = true );
866 SGPropertyNode * addChild ( const std::string& name,
869 { return addChild(name.c_str(), min_index, append); }
872 * Create multiple child nodes with the given name an unused indices
874 * @param count The number of nodes create
875 * @param min_index Minimal index for new nodes (skips lower indices)
876 * @param append Whether to simply use the index after the last used index
877 * or use a lower, unused index if it exists
879 simgear::PropertyList addChildren ( const std::string& name,
882 bool append = true );
885 * Get a child node by name and index.
887 SGPropertyNode * getChild (const char* name, int index = 0,
888 bool create = false);
889 SGPropertyNode * getChild (const std::string& name, int index = 0,
890 bool create = false);
892 * Get a const child node by name and index.
894 const SGPropertyNode * getChild (const char * name, int index = 0) const;
897 * Get a const child node by name and index.
899 const SGPropertyNode * getChild (const std::string& name, int index = 0) const
900 { return getChild(name.c_str(), index); }
904 * Get a vector of all children with the specified name.
906 simgear::PropertyList getChildren (const char * name) const;
909 * Get a vector of all children with the specified name.
911 simgear::PropertyList getChildren (const std::string& name) const
912 { return getChildren(name.c_str()); }
915 * Remove child by pointer (if it is a child of this node).
917 * @return true, if the node was deleted.
919 bool removeChild(SGPropertyNode* node);
921 // TODO do we need the removeXXX methods to return the deleted nodes?
923 * Remove child by position.
925 SGPropertyNode_ptr removeChild(int pos);
929 * Remove a child node
931 SGPropertyNode_ptr removeChild(const char * name, int index = 0);
934 * Remove a child node
936 SGPropertyNode_ptr removeChild(const std::string& name, int index = 0)
937 { return removeChild(name.c_str(), index); }
940 * Remove all children with the specified name.
942 simgear::PropertyList removeChildren(const char * name);
945 * Remove all children with the specified name.
947 simgear::PropertyList removeChildren(const std::string& name)
948 { return removeChildren(name.c_str()); }
951 * Remove all children (does not change the value of the node)
953 void removeAllChildren();
961 * Alias this node's leaf value to another's.
963 bool alias (SGPropertyNode * target);
967 * Alias this node's leaf value to another's by relative path.
969 bool alias (const char * path);
972 * Alias this node's leaf value to another's by relative path.
974 bool alias (const std::string& path)
975 { return alias(path.c_str()); }
979 * Remove any alias for this node.
985 * Test whether the node's leaf value is aliased to another's.
987 bool isAlias () const { return (_type == simgear::props::ALIAS); }
991 * Get a non-const pointer to the current alias target, if any.
993 SGPropertyNode * getAliasTarget ();
997 * Get a const pointer to the current alias target, if any.
999 const SGPropertyNode * getAliasTarget () const;
1003 // Path information.
1008 * Get the path to this node from the root.
1010 std::string getPath (bool simplify = false) const;
1014 * Get a pointer to the root node.
1016 SGPropertyNode * getRootNode ();
1020 * Get a const pointer to the root node.
1022 const SGPropertyNode * getRootNode () const;
1026 * Get a pointer to another node by relative path.
1028 SGPropertyNode * getNode (const char * relative_path, bool create = false);
1031 * Get a pointer to another node by relative path.
1033 SGPropertyNode * getNode (const std::string& relative_path, bool create = false)
1034 { return getNode(relative_path.c_str(), create); }
1037 * Get a pointer to another node by relative path.
1039 * This method leaves the index off the last member of the path,
1040 * so that the user can specify it separately (and save some
1041 * string building). For example, getNode("/bar[1]/foo", 3) is
1042 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
1043 * provided overrides any given in the path itself for the last
1046 SGPropertyNode * getNode (const char * relative_path, int index,
1047 bool create = false);
1050 * Get a pointer to another node by relative path.
1052 * This method leaves the index off the last member of the path,
1053 * so that the user can specify it separately (and save some
1054 * string building). For example, getNode("/bar[1]/foo", 3) is
1055 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
1056 * provided overrides any given in the path itself for the last
1059 SGPropertyNode * getNode (const std::string& relative_path, int index,
1060 bool create = false)
1061 { return getNode(relative_path.c_str(), index, create); }
1064 * Get a const pointer to another node by relative path.
1066 const SGPropertyNode * getNode (const char * relative_path) const;
1069 * Get a const pointer to another node by relative path.
1071 const SGPropertyNode * getNode (const std::string& relative_path) const
1072 { return getNode(relative_path.c_str()); }
1076 * Get a const pointer to another node by relative path.
1078 * This method leaves the index off the last member of the path,
1079 * so that the user can specify it separate.
1081 const SGPropertyNode * getNode (const char * relative_path,
1085 * Get a const pointer to another node by relative path.
1087 * This method leaves the index off the last member of the path,
1088 * so that the user can specify it separate.
1090 const SGPropertyNode * getNode (const std::string& relative_path,
1092 { return getNode(relative_path.c_str(), index); }
1099 * Check a single mode attribute for the property node.
1101 bool getAttribute (Attribute attr) const { return ((_attr & attr) != 0); }
1105 * Set a single mode attribute for the property node.
1107 void setAttribute (Attribute attr, bool state) {
1108 (state ? _attr |= attr : _attr &= ~attr);
1113 * Get all of the mode attributes for the property node.
1115 int getAttributes () const { return _attr; }
1119 * Set all of the mode attributes for the property node.
1121 void setAttributes (int attr) { _attr = attr; }
1125 // Leaf Value (primitive).
1130 * Get the type of leaf value, if any, for this node.
1132 simgear::props::Type getType () const;
1136 * Get a bool value for this node.
1138 bool getBoolValue () const;
1142 * Get an int value for this node.
1144 int getIntValue () const;
1148 * Get a long int value for this node.
1150 long getLongValue () const;
1154 * Get a float value for this node.
1156 float getFloatValue () const;
1160 * Get a double value for this node.
1162 double getDoubleValue () const;
1166 * Get a string value for this node.
1168 const char * getStringValue () const;
1171 * Get a value from a node. If the actual type of the node doesn't
1172 * match the desired type, a conversion isn't guaranteed.
1174 template<typename T>
1175 T getValue(typename boost::enable_if_c<simgear::props::PropertyTraits<T>::Internal>
1176 ::type* dummy = 0) const;
1177 // Getter for extended property
1178 template<typename T>
1179 T getValue(typename boost::disable_if_c<simgear::props::PropertyTraits<T>::Internal>
1180 ::type* dummy = 0) const;
1183 * Get a list of values from all children with the given name
1185 template<typename T, typename T_get /* = T */> // TODO use C++11 or traits
1186 std::vector<T> getChildValues(const std::string& name) const;
1189 * Get a list of values from all children with the given name
1191 template<typename T>
1192 std::vector<T> getChildValues(const std::string& name) const;
1195 * Set a bool value for this node.
1197 bool setBoolValue (bool value);
1201 * Set an int value for this node.
1203 bool setIntValue (int value);
1207 * Set a long int value for this node.
1209 bool setLongValue (long value);
1213 * Set a float value for this node.
1215 bool setFloatValue (float value);
1219 * Set a double value for this node.
1221 bool setDoubleValue (double value);
1225 * Set a string value for this node.
1227 bool setStringValue (const char * value);
1230 * Set a string value for this node.
1232 bool setStringValue (const std::string& value)
1233 { return setStringValue(value.c_str()); }
1237 * Set a value of unspecified type for this node.
1239 bool setUnspecifiedValue (const char * value);
1241 template<typename T>
1242 bool setValue(const T& val,
1243 typename boost::enable_if_c<simgear::props::PropertyTraits<T>::Internal>
1246 template<typename T>
1247 bool setValue(const T& val,
1248 typename boost::disable_if_c<simgear::props::PropertyTraits<T>::Internal>
1252 bool setValue(const char (&val)[N])
1254 return setValue(&val[0]);
1258 * Set relative node to given value and afterwards make read only.
1260 * @param relative_path Path to node
1261 * @param value Value to set
1263 * @return whether value could be set
1265 template<typename T>
1266 bool setValueReadOnly(const std::string& relative_path, const T& value)
1268 SGPropertyNode* node = getNode(relative_path, true);
1269 bool ret = node->setValue(value);
1270 node->setAttributes(READ);
1275 * Interpolate current value to target value within given time.
1277 * @param type Type of interpolation ("numeric", "color", etc.)
1278 * @param target Node containing target value
1279 * @param duration Duration of interpolation (in seconds)
1280 * @param easing Easing function (http://easings.net/)
1282 bool interpolate( const std::string& type,
1283 const SGPropertyNode& target,
1284 double duration = 0.6,
1285 const std::string& easing = "swing" );
1288 * Interpolate current value to a series of values within given durations.
1290 * @param type Type of interpolation ("numeric", "color", etc.)
1291 * @param values Nodes containing intermediate and target values
1292 * @param duration Durations for each interpolation step (in seconds)
1293 * @param easing Easing function (http://easings.net/)
1295 bool interpolate( const std::string& type,
1296 const simgear::PropertyList& values,
1297 const double_list& deltas,
1298 const std::string& easing = "swing" );
1301 * Set the interpolation manager used by the interpolate methods.
1303 static void setInterpolationMgr(simgear::PropertyInterpolationMgr* mgr);
1306 * Get the interpolation manager
1308 static simgear::PropertyInterpolationMgr* getInterpolationMgr();
1311 * Print the value of the property to a stream.
1313 std::ostream& printOn(std::ostream& stream) const;
1321 * Test whether this node is bound to an external data source.
1323 bool isTied () const { return _tied; }
1326 * Bind this node to an external source.
1328 template<typename T>
1329 bool tie(const SGRawValue<T> &rawValue, bool useDefault = true);
1332 * Unbind this node from any external data source.
1338 // Convenience methods using paths.
1339 // TODO: add attribute methods
1344 * Get another node's type.
1346 simgear::props::Type getType (const char * relative_path) const;
1349 * Get another node's type.
1351 simgear::props::Type getType (const std::string& relative_path) const
1352 { return getType(relative_path.c_str()); }
1355 * Test whether another node has a leaf value.
1357 bool hasValue (const char * relative_path) const;
1360 * Test whether another node has a leaf value.
1362 bool hasValue (const std::string& relative_path) const
1363 { return hasValue(relative_path.c_str()); }
1366 * Get another node's value as a bool.
1368 bool getBoolValue (const char * relative_path,
1369 bool defaultValue = false) const;
1372 * Get another node's value as a bool.
1374 bool getBoolValue (const std::string& relative_path,
1375 bool defaultValue = false) const
1376 { return getBoolValue(relative_path.c_str(), defaultValue); }
1379 * Get another node's value as an int.
1381 int getIntValue (const char * relative_path,
1382 int defaultValue = 0) const;
1385 * Get another node's value as an int.
1387 int getIntValue (const std::string& relative_path,
1388 int defaultValue = 0) const
1389 { return getIntValue(relative_path.c_str(), defaultValue); }
1393 * Get another node's value as a long int.
1395 long getLongValue (const char * relative_path,
1396 long defaultValue = 0L) const;
1399 * Get another node's value as a long int.
1401 long getLongValue (const std::string& relative_path,
1402 long defaultValue = 0L) const
1403 { return getLongValue(relative_path.c_str(), defaultValue); }
1406 * Get another node's value as a float.
1408 float getFloatValue (const char * relative_path,
1409 float defaultValue = 0.0f) const;
1412 * Get another node's value as a float.
1414 float getFloatValue (const std::string& relative_path,
1415 float defaultValue = 0.0f) const
1416 { return getFloatValue(relative_path.c_str(), defaultValue); }
1420 * Get another node's value as a double.
1422 double getDoubleValue (const char * relative_path,
1423 double defaultValue = 0.0) const;
1426 * Get another node's value as a double.
1428 double getDoubleValue (const std::string& relative_path,
1429 double defaultValue = 0.0) const
1430 { return getDoubleValue(relative_path.c_str(), defaultValue); }
1433 * Get another node's value as a string.
1435 const char * getStringValue (const char * relative_path,
1436 const char * defaultValue = "") const;
1440 * Get another node's value as a string.
1442 const char * getStringValue (const std::string& relative_path,
1443 const char * defaultValue = "") const
1444 { return getStringValue(relative_path.c_str(), defaultValue); }
1448 * Set another node's value as a bool.
1450 bool setBoolValue (const char * relative_path, bool value);
1453 * Set another node's value as a bool.
1455 bool setBoolValue (const std::string& relative_path, bool value)
1456 { return setBoolValue(relative_path.c_str(), value); }
1460 * Set another node's value as an int.
1462 bool setIntValue (const char * relative_path, int value);
1465 * Set another node's value as an int.
1467 bool setIntValue (const std::string& relative_path, int value)
1468 { return setIntValue(relative_path.c_str(), value); }
1472 * Set another node's value as a long int.
1474 bool setLongValue (const char * relative_path, long value);
1477 * Set another node's value as a long int.
1479 bool setLongValue (const std::string& relative_path, long value)
1480 { return setLongValue(relative_path.c_str(), value); }
1484 * Set another node's value as a float.
1486 bool setFloatValue (const char * relative_path, float value);
1489 * Set another node's value as a float.
1491 bool setFloatValue (const std::string& relative_path, float value)
1492 { return setFloatValue(relative_path.c_str(), value); }
1496 * Set another node's value as a double.
1498 bool setDoubleValue (const char * relative_path, double value);
1501 * Set another node's value as a double.
1503 bool setDoubleValue (const std::string& relative_path, double value)
1504 { return setDoubleValue(relative_path.c_str(), value); }
1508 * Set another node's value as a string.
1510 bool setStringValue (const char * relative_path, const char * value);
1512 bool setStringValue(const char * relative_path, const std::string& value)
1513 { return setStringValue(relative_path, value.c_str()); }
1515 * Set another node's value as a string.
1517 bool setStringValue (const std::string& relative_path, const char * value)
1518 { return setStringValue(relative_path.c_str(), value); }
1520 bool setStringValue (const std::string& relative_path,
1521 const std::string& value)
1522 { return setStringValue(relative_path.c_str(), value.c_str()); }
1525 * Set another node's value with no specified type.
1527 bool setUnspecifiedValue (const char * relative_path, const char * value);
1531 * Test whether another node is bound to an external data source.
1533 bool isTied (const char * relative_path) const;
1536 * Test whether another node is bound to an external data source.
1538 bool isTied (const std::string& relative_path) const
1539 { return isTied(relative_path.c_str()); }
1542 * Bind another node to an external bool source.
1544 bool tie (const char * relative_path, const SGRawValue<bool> &rawValue,
1545 bool useDefault = true);
1548 * Bind another node to an external bool source.
1550 bool tie (const std::string& relative_path, const SGRawValue<bool> &rawValue,
1551 bool useDefault = true)
1552 { return tie(relative_path.c_str(), rawValue, useDefault); }
1556 * Bind another node to an external int source.
1558 bool tie (const char * relative_path, const SGRawValue<int> &rawValue,
1559 bool useDefault = true);
1562 * Bind another node to an external int source.
1564 bool tie (const std::string& relative_path, const SGRawValue<int> &rawValue,
1565 bool useDefault = true)
1566 { return tie(relative_path.c_str(), rawValue, useDefault); }
1570 * Bind another node to an external long int source.
1572 bool tie (const char * relative_path, const SGRawValue<long> &rawValue,
1573 bool useDefault = true);
1576 * Bind another node to an external long int source.
1578 bool tie (const std::string& relative_path, const SGRawValue<long> &rawValue,
1579 bool useDefault = true)
1580 { return tie(relative_path.c_str(), rawValue, useDefault); }
1584 * Bind another node to an external float source.
1586 bool tie (const char * relative_path, const SGRawValue<float> &rawValue,
1587 bool useDefault = true);
1590 * Bind another node to an external float source.
1592 bool tie (const std::string& relative_path, const SGRawValue<float> &rawValue,
1593 bool useDefault = true)
1594 { return tie(relative_path.c_str(), rawValue, useDefault); }
1598 * Bind another node to an external double source.
1600 bool tie (const char * relative_path, const SGRawValue<double> &rawValue,
1601 bool useDefault = true);
1604 * Bind another node to an external double source.
1606 bool tie (const std::string& relative_path, const SGRawValue<double> &rawValue,
1607 bool useDefault = true)
1608 { return tie(relative_path.c_str(), rawValue, useDefault); }
1612 * Bind another node to an external string source.
1614 bool tie (const char * relative_path, const SGRawValue<const char *> &rawValue,
1615 bool useDefault = true);
1618 * Bind another node to an external string source.
1620 bool tie (const std::string& relative_path, const SGRawValue<const char*> &rawValue,
1621 bool useDefault = true)
1622 { return tie(relative_path.c_str(), rawValue, useDefault); }
1626 * Unbind another node from any external data source.
1628 bool untie (const char * relative_path);
1631 * Unbind another node from any external data source.
1633 bool untie (const std::string& relative_path)
1634 { return untie(relative_path.c_str()); }
1638 * Add a change listener to the property. If "initial" is set call the
1639 * listener initially.
1641 void addChangeListener (SGPropertyChangeListener * listener,
1642 bool initial = false);
1646 * Remove a change listener from the property.
1648 void removeChangeListener (SGPropertyChangeListener * listener);
1652 * Get the number of listeners.
1654 int nListeners () const { return _listeners ? (int)_listeners->size() : 0; }
1658 * Fire a value change event to all listeners.
1660 void fireValueChanged ();
1664 * Fire a child-added event to all listeners.
1666 void fireChildAdded (SGPropertyNode * child);
1669 * Trigger a child-added and value-changed event for every child (Unlimited
1672 * @param fire_self Whether to trigger the events also for the node itself.
1674 * It can be used to simulating the creation of a property tree, eg. for
1675 * (re)initializing a subsystem which is controlled through the property tree.
1677 void fireCreatedRecursive(bool fire_self = false);
1680 * Fire a child-removed event to all listeners.
1682 void fireChildRemoved (SGPropertyNode * child);
1685 * Fire a child-removed event for every child of this node (Unlimited depth)
1687 * Upon removal of a child node only for this single node a child-removed
1688 * event is triggered. If eg. resource cleanup relies on receiving a
1689 * child-removed event for every child this method can be used.
1691 void fireChildrenRemovedRecursive();
1695 * Clear any existing value and set the type to NONE.
1700 * Compare two property trees. The property trees are equal if: 1)
1701 * They have no children, and have the same type and the values are
1702 * equal, or 2) have the same number of children, and the
1703 * corresponding children in each tree are equal. "corresponding"
1704 * means have the same name and index.
1706 * Attributes, removed children, and aliases aren't considered.
1708 static bool compare (const SGPropertyNode& lhs, const SGPropertyNode& rhs);
1712 void fireValueChanged (SGPropertyNode * node);
1713 void fireChildAdded (SGPropertyNode * parent, SGPropertyNode * child);
1714 void fireChildRemoved (SGPropertyNode * parent, SGPropertyNode * child);
1716 SGPropertyNode_ptr eraseChild(simgear::PropertyList::iterator child);
1719 * Protected constructor for making new nodes on demand.
1721 SGPropertyNode (const std::string& name, int index, SGPropertyNode * parent);
1722 template<typename Itr>
1723 SGPropertyNode (Itr begin, Itr end, int index, SGPropertyNode * parent);
1725 static simgear::PropertyInterpolationMgr* _interpolation_mgr;
1729 // Get the raw value
1730 bool get_bool () const;
1731 int get_int () const;
1732 long get_long () const;
1733 float get_float () const;
1734 double get_double () const;
1735 const char * get_string () const;
1737 // Set the raw value
1738 bool set_bool (bool value);
1739 bool set_int (int value);
1740 bool set_long (long value);
1741 bool set_float (float value);
1742 bool set_double (double value);
1743 bool set_string (const char * value);
1747 * Get the value as a string.
1749 const char * make_string () const;
1752 * Trace a read access.
1754 void trace_read () const;
1758 * Trace a write access.
1760 void trace_write () const;
1764 /// To avoid cyclic reference counting loops this shall not be a reference
1766 SGPropertyNode * _parent;
1767 simgear::PropertyList _children;
1768 mutable std::string _buffer;
1769 simgear::props::Type _type;
1773 // The right kind of pointer...
1775 SGPropertyNode * alias;
1788 std::vector<SGPropertyChangeListener *> * _listeners;
1790 // Pass name as a pair of iterators
1791 template<typename Itr>
1792 SGPropertyNode * getChildImpl (Itr begin, Itr end, int index = 0, bool create = false);
1793 // very internal method
1794 template<typename Itr>
1795 SGPropertyNode* getExistingChild (Itr begin, Itr end, int index);
1796 // very internal path parsing function
1797 template<typename SplitItr>
1798 friend SGPropertyNode* find_node_aux(SGPropertyNode * current, SplitItr& itr,
1799 bool create, int last_index);
1801 friend size_t hash_value(const SGPropertyNode& node);
1804 // Convenience functions for use in templates
1805 template<typename T>
1806 typename boost::disable_if<boost::is_enum<T>, T>::type
1807 getValue(const SGPropertyNode*);
1810 inline bool getValue<bool>(const SGPropertyNode* node) { return node->getBoolValue(); }
1813 inline int getValue<int>(const SGPropertyNode* node) { return node->getIntValue(); }
1816 inline long getValue<long>(const SGPropertyNode* node) { return node->getLongValue(); }
1819 inline float getValue<float>(const SGPropertyNode* node)
1821 return node->getFloatValue();
1825 inline double getValue<double>(const SGPropertyNode* node)
1827 return node->getDoubleValue();
1831 inline const char * getValue<const char*>(const SGPropertyNode* node)
1833 return node->getStringValue ();
1837 inline std::string getValue<std::string>(const SGPropertyNode* node)
1839 return node->getStringValue();
1845 * Default trait for extracting enum values from SGPropertyNode. Create your
1846 * own specialization for specific enum types to enable validation of values.
1852 * Typename of the enum
1854 static const char* name() { return typeid(T).name(); }
1857 * @return Default value (will be used if validation fails)
1859 static T defVal() { return T(); }
1862 * @return Whether the given integer value has an enum value defined
1864 static bool validate(int) { return true; }
1866 } // namespace simgear
1868 /** Extract enum from SGPropertyNode */
1869 template<typename T>
1870 inline typename boost::enable_if<boost::is_enum<T>, T>::type
1871 getValue(const SGPropertyNode* node)
1873 typedef simgear::enum_traits<T> Traits;
1874 int val = node->getIntValue();
1875 if( !Traits::validate(val) )
1881 "Invalid value for enum (" << Traits::name() << ", val = " << val << ")"
1883 return Traits::defVal();
1885 return static_cast<T>(node->getIntValue());
1888 inline bool setValue(SGPropertyNode* node, bool value)
1890 return node->setBoolValue(value);
1893 inline bool setValue(SGPropertyNode* node, int value)
1895 return node->setIntValue(value);
1898 inline bool setValue(SGPropertyNode* node, long value)
1900 return node->setLongValue(value);
1903 inline bool setValue(SGPropertyNode* node, float value)
1905 return node->setFloatValue(value);
1908 inline bool setValue(SGPropertyNode* node, double value)
1910 return node->setDoubleValue(value);
1913 inline bool setValue(SGPropertyNode* node, const char* value)
1915 return node->setStringValue(value);
1918 inline bool setValue (SGPropertyNode* node, const std::string& value)
1920 return node->setStringValue(value.c_str());
1923 template<typename T>
1924 bool SGPropertyNode::tie(const SGRawValue<T> &rawValue, bool useDefault)
1926 using namespace simgear::props;
1927 if (_type == ALIAS || _tied)
1930 useDefault = useDefault && hasValue();
1931 T old_val = SGRawValue<T>::DefaultValue();
1933 old_val = getValue<T>(this);
1935 if (PropertyTraits<T>::Internal)
1936 _type = PropertyTraits<T>::type_tag;
1940 _value.val = rawValue.clone();
1942 int save_attributes = getAttributes();
1943 setAttribute( WRITE, true );
1945 setAttributes( save_attributes );
1951 bool SGPropertyNode::tie (const SGRawValue<const char *> &rawValue,
1954 template<typename T>
1955 T SGPropertyNode::getValue(typename boost::disable_if_c<simgear::props
1956 ::PropertyTraits<T>::Internal>::type* dummy) const
1958 using namespace simgear::props;
1959 if (_attr == (READ|WRITE) && _type == EXTENDED
1960 && _value.val->getType() == PropertyTraits<T>::type_tag) {
1961 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
1963 if (getAttribute(TRACE_READ))
1965 if (!getAttribute(READ))
1966 return SGRawValue<T>::DefaultValue();
1969 if (_value.val->getType() == PropertyTraits<T>::type_tag)
1970 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
1974 return simgear::parseString<T>(make_string());
1976 default: // avoid compiler warning
1979 return SGRawValue<T>::DefaultValue();
1982 template<typename T>
1983 inline T SGPropertyNode::getValue(typename boost::enable_if_c<simgear::props
1984 ::PropertyTraits<T>::Internal>::type* dummy) const
1986 return ::getValue<T>(this);
1989 template<typename T, typename T_get /* = T */> // TODO use C++11 or traits
1990 std::vector<T> SGPropertyNode::getChildValues(const std::string& name) const
1992 const simgear::PropertyList& props = getChildren(name);
1993 std::vector<T> values( props.size() );
1995 for( size_t i = 0; i < props.size(); ++i )
1996 values[i] = props[i]->getValue<T_get>();
2001 template<typename T>
2003 std::vector<T> SGPropertyNode::getChildValues(const std::string& name) const
2005 return getChildValues<T, T>(name);
2008 template<typename T>
2009 bool SGPropertyNode::setValue(const T& val,
2010 typename boost::disable_if_c<simgear::props
2011 ::PropertyTraits<T>::Internal>::type* dummy)
2013 using namespace simgear::props;
2014 if (_attr == (READ|WRITE) && _type == EXTENDED
2015 && _value.val->getType() == PropertyTraits<T>::type_tag) {
2016 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
2019 if (getAttribute(WRITE)
2020 && ((_type == EXTENDED
2021 && _value.val->getType() == PropertyTraits<T>::type_tag)
2022 || _type == NONE || _type == UNSPECIFIED)) {
2023 if (_type == NONE || _type == UNSPECIFIED) {
2026 _value.val = new SGRawValueContainer<T>(val);
2028 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
2030 if (getAttribute(TRACE_WRITE))
2037 template<typename T>
2038 inline bool SGPropertyNode::setValue(const T& val,
2039 typename boost::enable_if_c<simgear::props
2040 ::PropertyTraits<T>::Internal>::type* dummy)
2042 return ::setValue(this, val);
2046 * Utility function for creation of a child property node.
2048 inline SGPropertyNode* makeChild(SGPropertyNode* parent, const char* name,
2051 return parent->getChild(name, index, true);
2055 * Utility function for creation of a child property node using a
2060 template<typename StringType>
2061 inline SGPropertyNode* makeNode(SGPropertyNode* parent, const StringType& name)
2063 return parent->getNode(name, true);
2068 size_t hash_value(const SGPropertyNode& node);
2070 // Helper comparison and hash functions for common cases
2078 bool operator()(const SGPropertyNode* lhs, const SGPropertyNode* rhs) const
2080 return SGPropertyNode::compare(*lhs, *rhs);
2082 bool operator()(SGPropertyNode_ptr lhs, const SGPropertyNode* rhs) const
2084 return SGPropertyNode::compare(*lhs, *rhs);
2086 bool operator()(const SGPropertyNode* lhs, SGPropertyNode_ptr rhs) const
2088 return SGPropertyNode::compare(*lhs, *rhs);
2090 bool operator()(SGPropertyNode_ptr lhs, SGPropertyNode_ptr rhs) const
2092 return SGPropertyNode::compare(*lhs, *rhs);
2098 size_t operator()(const SGPropertyNode* node) const
2100 return hash_value(*node);
2102 size_t operator()(SGPropertyNode_ptr node) const
2104 return hash_value(*node);
2110 /** Convenience class for change listener callbacks without
2111 * creating a derived class implementing a "valueChanged" method.
2112 * Also removes listener on destruction automatically.
2115 class SGPropertyChangeCallback
2116 : public SGPropertyChangeListener
2119 SGPropertyChangeCallback(T* obj, void (T::*method)(SGPropertyNode*),
2120 SGPropertyNode_ptr property,bool initial=false)
2121 : _obj(obj), _callback(method), _property(property)
2123 _property->addChangeListener(this,initial);
2126 SGPropertyChangeCallback(const SGPropertyChangeCallback<T>& other) :
2127 _obj(other._obj), _callback(other._callback), _property(other._property)
2129 _property->addChangeListener(this,false);
2132 virtual ~SGPropertyChangeCallback()
2134 _property->removeChangeListener(this);
2136 void valueChanged (SGPropertyNode * node)
2138 (_obj->*_callback)(node);
2142 void (T::*_callback)(SGPropertyNode*);
2143 SGPropertyNode_ptr _property;
2146 #endif // __PROPS_HXX