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 <simgear/compiler.h>
27 // taken from: boost/utility/enable_if.hpp
32 # define SG_LOG(type, level, message) (type) ? (std::cerr <<message << endl) : (std::cout <<message << endl)
35 template <bool B, class T = void>
41 struct enable_if_c<false, T> {};
43 template <class Cond, class T = void>
44 struct enable_if : public enable_if_c<Cond::value, T> {};
46 template <bool B, class T = void>
52 struct disable_if_c<true, T> {};
54 template <class Cond, class T = void>
55 struct disable_if : public disable_if_c<Cond::value, T> {};
58 # include <boost/utility.hpp>
59 # include <boost/type_traits/is_enum.hpp>
61 # include <simgear/debug/logstream.hxx>
62 # include <simgear/math/SGMathFwd.hxx>
63 # include <simgear/math/sg_types.hxx>
65 #include <simgear/structure/SGReferenced.hxx>
66 #include <simgear/structure/SGSharedPtr.hxx>
68 // XXX This whole file should be in the simgear namespace, but I don't
69 // have the guts yet...
76 class PropertyInterpolationMgr;
79 std::istream& readFrom(std::istream& stream, T& result)
86 * Parse a string as an object of a given type.
87 * XXX no error behavior yet.
89 * @tparam T the return type
90 * @param str the string
94 inline T parseString(const std::string& str)
96 std::istringstream stream(str);
98 readFrom(stream, result);
103 * Property value types.
107 #pragma warn A sloppy coder has defined NONE as a macro!
112 #pragma warn A sloppy coder has defined ALIAS as a macro!
117 #pragma warn A sloppy coder has defined UNSPECIFIED as a macro!
122 #pragma warn A sloppy coder has defined BOOL as a macro!
127 #pragma warn A sloppy coder has defined INT as a macro!
132 #pragma warn A sloppy coder has defined LONG as a macro!
137 #pragma warn A sloppy coder has defined FLOAT as a macro!
142 #pragma warn A sloppy coder has defined DOUBLE as a macro!
147 #pragma warn A sloppy coder has defined STRING as a macro!
154 * The possible types of an SGPropertyNode. Types that appear after
155 * EXTENDED are not stored in the SGPropertyNode itself.
158 NONE = 0, /**< The node hasn't been assigned a value yet. */
159 ALIAS, /**< The node "points" to another node. */
167 EXTENDED, /**< The node's value is not stored in the property;
168 * the actual value and type is retrieved from an
169 * SGRawValue node. This type is never returned by @see
170 * SGPropertyNode::getType.
172 // Extended properties
177 template<typename T> struct PropertyTraits;
179 #define DEFINTERNALPROP(TYPE, PROP) \
181 struct PropertyTraits<TYPE> \
183 static const Type type_tag = PROP; \
184 enum { Internal = 1 }; \
187 DEFINTERNALPROP(bool, BOOL);
188 DEFINTERNALPROP(int, INT);
189 DEFINTERNALPROP(long, LONG);
190 DEFINTERNALPROP(float, FLOAT);
191 DEFINTERNALPROP(double, DOUBLE);
192 DEFINTERNALPROP(const char *, STRING);
193 DEFINTERNALPROP(const char[], STRING);
194 #undef DEFINTERNALPROP
201 ////////////////////////////////////////////////////////////////////////
204 // This is the mechanism that information-providing routines can
205 // use to link their own values to the property manager. Any
206 // SGValue can be tied to a raw value and then untied again.
208 // Note: we are forced to use inlined methods here to ensure
209 // that the templates will be instantiated. We're probably taking
210 // a small performance hit for that.
211 ////////////////////////////////////////////////////////////////////////
214 * Base class for SGRawValue classes that holds no type
215 * information. This allows some generic manipulation of the
222 * Get the type enumeration for the raw value.
226 virtual simgear::props::Type getType() const = 0;
230 * Create a new deep copy of this raw value.
232 * The copy will contain its own version of the underlying value
233 * as well, and will be the same type.
235 * @return A deep copy of the current object.
237 virtual SGRaw* clone() const = 0;
241 class SGRawExtended : public SGRaw
245 * Make an SGRawValueContainer from the SGRawValue.
247 * This is a virtual function of SGRawExtended so that
248 * SGPropertyNode::untie doesn't need to know the type of an
251 virtual SGRawExtended* makeContainer() const = 0;
253 * Write value out to a stream
255 virtual std::ostream& printOn(std::ostream& stream) const = 0;
257 * Read value from a stream and store it.
259 virtual std::istream& readFrom(std::istream& stream) = 0;
262 // Choose between different base classes based on whether the value is
263 // stored internal to the property node. This frees us from defining
264 // the virtual functions in the SGRawExtended interface where they
265 // don't make sense, e.g. readFrom for the const char* type.
266 template<typename T, int internal = simgear::props::PropertyTraits<T>::Internal>
270 class SGRawBase<T, 1> : public SGRaw
275 class SGRawBase<T, 0> : public SGRawExtended
277 virtual SGRawExtended* makeContainer() const;
278 virtual std::ostream& printOn(std::ostream& stream) const;
279 virtual std::istream& readFrom(std::istream& stream);
283 * Abstract base class for a raw value.
285 * The property manager is implemented in two layers. The SGPropertyNode is the
286 * highest and most abstract layer, representing an LValue/RValue pair: it
287 * records the position of the property in the property tree and contains
288 * facilities for navigation to other nodes. It is guaranteed to be persistent:
289 * the SGPropertyNode will not change during a session, even if the property is
290 * bound and unbound multiple times.
292 * When the property value is not managed internally in the
293 * SGPropertyNode, the SGPropertyNode will contain a reference to an
294 * SGRawValue (this class), which provides an abstract way to get,
295 * set, and clone the underlying value. The SGRawValue may change
296 * frequently during a session as a value is retyped or bound and
297 * unbound to various data source, but the abstract SGPropertyNode
298 * layer insulates the application from those changes.
300 * The SGPropertyNode class always keeps a *copy* of a raw value, not the
301 * original one passed to it; if you override a derived class but do not replace
302 * the {@link SGRaw::clone clone()} method, strange things will happen.
304 * All derived SGRawValue classes must implement getValue(), setValue(), and
305 * {@link SGRaw::clone clone()} for the appropriate type.
307 * @see SGPropertyNode
308 * @see SGRawValuePointer
309 * @see SGRawValueFunctions
310 * @see SGRawValueFunctionsIndexed
311 * @see SGRawValueMethods
312 * @see SGRawValueMethodsIndexed
313 * @see SGRawValueContainer
316 class SGRawValue : public SGRawBase<T>
321 * The default underlying value for this type.
323 * Every raw value has a default; the default is false for a
324 * boolean, 0 for the various numeric values, and "" for a string.
325 * If additional types of raw values are added in the future, they
326 * may need different kinds of default values (such as epoch for a
327 * date type). The default value is used when creating new values.
329 static T DefaultValue()
338 * Use the default value for this type.
346 virtual ~SGRawValue () {}
350 * Return the underlying value.
352 * @return The actual value for the property.
355 virtual T getValue () const = 0;
359 * Assign a new underlying value.
361 * If the new value cannot be set (because this is a read-only
362 * raw value, or because the new value is not acceptable for
363 * some reason) this method returns false and leaves the original
366 * @param value The actual value for the property.
367 * @return true if the value was set successfully, false otherwise.
370 virtual bool setValue (T value) = 0;
374 * Return the type tag for this raw value type.
376 virtual simgear::props::Type getType() const
378 return simgear::props::PropertyTraits<T>::type_tag;
384 ////////////////////////////////////////////////////////////////////////
385 // Default values for every type.
386 ////////////////////////////////////////////////////////////////////////
388 template<> inline bool SGRawValue<bool>::DefaultValue()
393 template<> inline const char * SGRawValue<const char *>::DefaultValue()
399 * A raw value bound to a pointer.
401 * This is the most efficient way to tie an external value, but also
402 * the most dangerous, because there is no way for the supplier to
403 * perform bounds checking and derived calculations except by polling
404 * the variable to see if it has changed. There is no default
405 * constructor, because this class would be meaningless without a
409 class SGRawValuePointer : public SGRawValue<T>
414 * Explicit pointer constructor.
416 * Create a new raw value bound to the value of the variable
417 * referenced by the pointer.
419 * @param ptr The pointer to the variable to which this raw value
422 SGRawValuePointer (T * ptr) : _ptr(ptr) {}
427 virtual ~SGRawValuePointer () {}
430 * Get the underlying value.
432 * This method will dereference the pointer and return the
435 virtual T getValue () const { return *_ptr; }
438 * Set the underlying value.
440 * This method will dereference the pointer and change the
443 virtual bool setValue (T value) { *_ptr = value; return true; }
446 * Create a copy of this raw value.
448 * The copy will use the same external pointer as the original.
450 virtual SGRaw* clone () const {
451 return new SGRawValuePointer(_ptr);
460 * A value managed through static functions.
462 * A read-only value will not have a setter; a write-only value will
466 class SGRawValueFunctions : public SGRawValue<T>
471 * The template type of a static getter function.
473 typedef T (*getter_t)();
476 * The template type of a static setter function.
478 typedef void (*setter_t)(T);
481 * Explicit constructor.
483 * Create a new raw value bound to the getter and setter supplied.
485 * @param getter A static function for getting a value, or 0
486 * to read-disable the value.
487 * @param setter A static function for setting a value, or 0
488 * to write-disable the value.
490 SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
491 : _getter(getter), _setter(setter) {}
496 virtual ~SGRawValueFunctions () {}
499 * Get the underlying value.
501 * This method will invoke the getter function to get a value.
502 * If no getter function was supplied, this method will always
503 * return the default value for the type.
505 virtual T getValue () const {
506 if (_getter) return (*_getter)();
507 else return SGRawValue<T>::DefaultValue();
511 * Set the underlying value.
513 * This method will invoke the setter function to change the
514 * underlying value. If no setter function was supplied, this
515 * method will return false.
517 virtual bool setValue (T value) {
518 if (_setter) { (*_setter)(value); return true; }
523 * Create a copy of this raw value, bound to the same functions.
525 virtual SGRaw* clone () const {
526 return new SGRawValueFunctions(_getter,_setter);
536 * An indexed value bound to static functions.
538 * A read-only value will not have a setter; a write-only value will
539 * not have a getter. An indexed value is useful for binding one
540 * of a list of possible values (such as multiple engines for a
541 * plane). The index is hard-coded at creation time.
546 class SGRawValueFunctionsIndexed : public SGRawValue<T>
549 typedef T (*getter_t)(int);
550 typedef void (*setter_t)(int,T);
551 SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
552 : _index(index), _getter(getter), _setter(setter) {}
553 virtual ~SGRawValueFunctionsIndexed () {}
554 virtual T getValue () const {
555 if (_getter) return (*_getter)(_index);
556 else return SGRawValue<T>::DefaultValue();
558 virtual bool setValue (T value) {
559 if (_setter) { (*_setter)(_index, value); return true; }
562 virtual SGRaw* clone () const {
563 return new SGRawValueFunctionsIndexed(_index, _getter, _setter);
573 * A value managed through an object and access methods.
575 * A read-only value will not have a setter; a write-only value will
578 template <class C, class T>
579 class SGRawValueMethods : public SGRawValue<T>
582 typedef T (C::*getter_t)() const;
583 typedef void (C::*setter_t)(T);
584 SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
585 : _obj(obj), _getter(getter), _setter(setter) {}
586 virtual ~SGRawValueMethods () {}
587 virtual T getValue () const {
588 if (_getter) { return (_obj.*_getter)(); }
589 else { return SGRawValue<T>::DefaultValue(); }
591 virtual bool setValue (T value) {
592 if (_setter) { (_obj.*_setter)(value); return true; }
595 virtual SGRaw* clone () const {
596 return new SGRawValueMethods(_obj, _getter, _setter);
606 * An indexed value managed through an object and access methods.
608 * A read-only value will not have a setter; a write-only value will
611 template <class C, class T>
612 class SGRawValueMethodsIndexed : public SGRawValue<T>
615 typedef T (C::*getter_t)(int) const;
616 typedef void (C::*setter_t)(int, T);
617 SGRawValueMethodsIndexed (C &obj, int index,
618 getter_t getter = 0, setter_t setter = 0)
619 : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
620 virtual ~SGRawValueMethodsIndexed () {}
621 virtual T getValue () const {
622 if (_getter) { return (_obj.*_getter)(_index); }
623 else { return SGRawValue<T>::DefaultValue(); }
625 virtual bool setValue (T value) {
626 if (_setter) { (_obj.*_setter)(_index, value); return true; }
629 virtual SGRaw* clone () const {
630 return new SGRawValueMethodsIndexed(_obj, _index, _getter, _setter);
640 * A raw value that contains its value. This provides a way for
641 * property nodes to contain values that shouldn't be stored in the
642 * property node itself.
645 class SGRawValueContainer : public SGRawValue<T>
650 * Explicit constructor.
652 SGRawValueContainer(const T& obj) : _obj(obj) {}
657 virtual ~SGRawValueContainer() {}
660 * Get the underlying value.
662 virtual T getValue() const { return _obj; }
665 * Set the underlying value.
667 * This method will dereference the pointer and change the
670 virtual bool setValue (T value) { _obj = value; return true; }
673 * Create a copy of this raw value.
675 virtual SGRaw* clone () const {
676 return new SGRawValueContainer(_obj);
684 SGRawExtended* SGRawBase<T, 0>::makeContainer() const
686 return new SGRawValueContainer<T>(static_cast<const SGRawValue<T>*>(this)
691 std::ostream& SGRawBase<T, 0>::printOn(std::ostream& stream) const
693 return stream << static_cast<SGRawValue<T>*>(this)->getValue();
697 std::istream& SGRawBase<T, 0>::readFrom(std::istream& stream)
700 simgear::readFrom(stream, value);
701 static_cast<SGRawValue<T>*>(this)->setValue(value);
706 * The smart pointer that manage reference counting
708 class SGPropertyNode;
709 typedef SGSharedPtr<SGPropertyNode> SGPropertyNode_ptr;
710 typedef SGSharedPtr<const SGPropertyNode> SGConstPropertyNode_ptr;
714 typedef std::vector<SGPropertyNode_ptr> PropertyList;
718 * The property change listener interface.
720 * <p>Any class that needs to listen for property changes must implement
721 * this interface.</p>
723 class SGPropertyChangeListener
726 virtual ~SGPropertyChangeListener ();
728 /// Called if value of \a node has changed.
729 virtual void valueChanged(SGPropertyNode * node);
731 /// Called if \a child has been added to the given \a parent.
732 virtual void childAdded(SGPropertyNode * parent, SGPropertyNode * child);
734 /// Called if \a child has been removed from its \a parent.
735 virtual void childRemoved(SGPropertyNode * parent, SGPropertyNode * child);
738 friend class SGPropertyNode;
739 virtual void register_property (SGPropertyNode * node);
740 virtual void unregister_property (SGPropertyNode * node);
743 std::vector<SGPropertyNode *> _properties;
748 * A node in a property tree.
750 class SGPropertyNode : public SGReferenced
758 MAX_STRING_LEN = 1024
762 * Access mode attributes.
764 * <p>The ARCHIVE attribute is strictly advisory, and controls
765 * whether the property should normally be saved and restored.</p>
777 // beware: if you add another attribute here,
778 // also update value of "LAST_USED_ATTRIBUTE".
783 * Last used attribute
784 * Update as needed when enum Attribute is changed
786 static const int LAST_USED_ATTRIBUTE;
789 * Default constructor.
797 SGPropertyNode (const SGPropertyNode &node);
803 virtual ~SGPropertyNode ();
812 * Test whether this node contains a primitive leaf value.
814 bool hasValue () const { return (_type != simgear::props::NONE); }
818 * Get the node's simple (XML) name.
820 const char * getName () const { return _name.c_str(); }
823 * Get the node's simple name as a string.
825 const std::string& getNameString () const { return _name; }
828 * Get the node's pretty display name, with subscript when needed.
830 std::string getDisplayName (bool simplify = false) const;
834 * Get the node's integer index.
836 int getIndex () const { return _index; }
840 * Get a non-const pointer to the node's parent.
842 SGPropertyNode * getParent () { return _parent; }
846 * Get a const pointer to the node's parent.
848 const SGPropertyNode * getParent () const { return _parent; }
857 * Get the number of child nodes.
859 int nChildren () const { return (int)_children.size(); }
863 * Get a child node by position (*NOT* index).
865 SGPropertyNode * getChild (int position);
869 * Get a const child node by position (*NOT* index).
871 const SGPropertyNode * getChild (int position) const;
875 * Test whether a named child exists.
877 bool hasChild (const char * name, int index = 0) const
879 return (getChild(name, index) != 0);
883 * Test whether a named child exists.
885 bool hasChild (const std::string& name, int index = 0) const
887 return (getChild(name, index) != 0);
891 * Create a new child node with the given name and an unused index
893 * @param min_index Minimal index for new node (skips lower indices)
894 * @param append Whether to simply use the index after the last used index
895 * or use a lower, unused index if it exists
897 SGPropertyNode * addChild ( const char* name,
899 bool append = true );
900 SGPropertyNode * addChild ( const std::string& name,
903 { return addChild(name.c_str(), min_index, append); }
906 * Create multiple child nodes with the given name an unused indices
908 * @param count The number of nodes create
909 * @param min_index Minimal index for new nodes (skips lower indices)
910 * @param append Whether to simply use the index after the last used index
911 * or use a lower, unused index if it exists
913 simgear::PropertyList addChildren ( const std::string& name,
916 bool append = true );
919 * Get a child node by name and index.
921 SGPropertyNode * getChild (const char* name, int index = 0,
922 bool create = false);
923 SGPropertyNode * getChild (const std::string& name, int index = 0,
924 bool create = false);
926 * Get a const child node by name and index.
928 const SGPropertyNode * getChild (const char * name, int index = 0) const;
931 * Get a const child node by name and index.
933 const SGPropertyNode * getChild (const std::string& name, int index = 0) const
934 { return getChild(name.c_str(), index); }
938 * Get a vector of all children with the specified name.
940 simgear::PropertyList getChildren (const char * name) const;
943 * Get a vector of all children with the specified name.
945 simgear::PropertyList getChildren (const std::string& name) const
946 { return getChildren(name.c_str()); }
949 * Remove child by pointer (if it is a child of this node).
951 * @return true, if the node was deleted.
953 bool removeChild(SGPropertyNode* node);
955 // TODO do we need the removeXXX methods to return the deleted nodes?
957 * Remove child by position.
959 SGPropertyNode_ptr removeChild(int pos);
963 * Remove a child node
965 SGPropertyNode_ptr removeChild(const char * name, int index = 0);
968 * Remove a child node
970 SGPropertyNode_ptr removeChild(const std::string& name, int index = 0)
971 { return removeChild(name.c_str(), index); }
974 * Remove all children with the specified name.
976 simgear::PropertyList removeChildren(const char * name);
979 * Remove all children with the specified name.
981 simgear::PropertyList removeChildren(const std::string& name)
982 { return removeChildren(name.c_str()); }
985 * Remove all children (does not change the value of the node)
987 void removeAllChildren();
995 * Alias this node's leaf value to another's.
997 bool alias (SGPropertyNode * target);
1001 * Alias this node's leaf value to another's by relative path.
1003 bool alias (const char * path);
1006 * Alias this node's leaf value to another's by relative path.
1008 bool alias (const std::string& path)
1009 { return alias(path.c_str()); }
1013 * Remove any alias for this node.
1019 * Test whether the node's leaf value is aliased to another's.
1021 bool isAlias () const { return (_type == simgear::props::ALIAS); }
1025 * Get a non-const pointer to the current alias target, if any.
1027 SGPropertyNode * getAliasTarget ();
1031 * Get a const pointer to the current alias target, if any.
1033 const SGPropertyNode * getAliasTarget () const;
1037 // Path information.
1042 * Get the path to this node from the root.
1044 std::string getPath (bool simplify = false) const;
1048 * Get a pointer to the root node.
1050 SGPropertyNode * getRootNode ();
1054 * Get a const pointer to the root node.
1056 const SGPropertyNode * getRootNode () const;
1060 * Get a pointer to another node by relative path.
1062 SGPropertyNode * getNode (const char * relative_path, bool create = false);
1065 * Get a pointer to another node by relative path.
1067 SGPropertyNode * getNode (const std::string& relative_path, bool create = false)
1068 { return getNode(relative_path.c_str(), create); }
1071 * Get a pointer to another node by relative path.
1073 * This method leaves the index off the last member of the path,
1074 * so that the user can specify it separately (and save some
1075 * string building). For example, getNode("/bar[1]/foo", 3) is
1076 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
1077 * provided overrides any given in the path itself for the last
1080 SGPropertyNode * getNode (const char * relative_path, int index,
1081 bool create = false);
1084 * Get a pointer to another node by relative path.
1086 * This method leaves the index off the last member of the path,
1087 * so that the user can specify it separately (and save some
1088 * string building). For example, getNode("/bar[1]/foo", 3) is
1089 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
1090 * provided overrides any given in the path itself for the last
1093 SGPropertyNode * getNode (const std::string& relative_path, int index,
1094 bool create = false)
1095 { return getNode(relative_path.c_str(), index, create); }
1098 * Get a const pointer to another node by relative path.
1100 const SGPropertyNode * getNode (const char * relative_path) const;
1103 * Get a const pointer to another node by relative path.
1105 const SGPropertyNode * getNode (const std::string& relative_path) const
1106 { return getNode(relative_path.c_str()); }
1110 * Get a const pointer to another node by relative path.
1112 * This method leaves the index off the last member of the path,
1113 * so that the user can specify it separate.
1115 const SGPropertyNode * getNode (const char * relative_path,
1119 * Get a const pointer to another node by relative path.
1121 * This method leaves the index off the last member of the path,
1122 * so that the user can specify it separate.
1124 const SGPropertyNode * getNode (const std::string& relative_path,
1126 { return getNode(relative_path.c_str(), index); }
1133 * Check a single mode attribute for the property node.
1135 bool getAttribute (Attribute attr) const { return ((_attr & attr) != 0); }
1139 * Set a single mode attribute for the property node.
1141 void setAttribute (Attribute attr, bool state) {
1142 (state ? _attr |= attr : _attr &= ~attr);
1147 * Get all of the mode attributes for the property node.
1149 int getAttributes () const { return _attr; }
1153 * Set all of the mode attributes for the property node.
1155 void setAttributes (int attr) { _attr = attr; }
1159 // Leaf Value (primitive).
1164 * Get the type of leaf value, if any, for this node.
1166 simgear::props::Type getType () const;
1170 * Get a bool value for this node.
1172 bool getBoolValue () const;
1176 * Get an int value for this node.
1178 int getIntValue () const;
1182 * Get a long int value for this node.
1184 long getLongValue () const;
1188 * Get a float value for this node.
1190 float getFloatValue () const;
1194 * Get a double value for this node.
1196 double getDoubleValue () const;
1200 * Get a string value for this node.
1202 const char * getStringValue () const;
1205 * Get a value from a node. If the actual type of the node doesn't
1206 * match the desired type, a conversion isn't guaranteed.
1208 template<typename T>
1209 T getValue(typename boost::enable_if_c<simgear::props::PropertyTraits<T>::Internal>
1210 ::type* dummy = 0) const;
1211 // Getter for extended property
1212 template<typename T>
1213 T getValue(typename boost::disable_if_c<simgear::props::PropertyTraits<T>::Internal>
1214 ::type* dummy = 0) const;
1217 * Get a list of values from all children with the given name
1219 template<typename T, typename T_get /* = T */> // TODO use C++11 or traits
1220 std::vector<T> getChildValues(const std::string& name) const;
1223 * Get a list of values from all children with the given name
1225 template<typename T>
1226 std::vector<T> getChildValues(const std::string& name) const;
1229 * Set a bool value for this node.
1231 bool setBoolValue (bool value);
1235 * Set an int value for this node.
1237 bool setIntValue (int value);
1241 * Set a long int value for this node.
1243 bool setLongValue (long value);
1247 * Set a float value for this node.
1249 bool setFloatValue (float value);
1253 * Set a double value for this node.
1255 bool setDoubleValue (double value);
1259 * Set a string value for this node.
1261 bool setStringValue (const char * value);
1264 * Set a string value for this node.
1266 bool setStringValue (const std::string& value)
1267 { return setStringValue(value.c_str()); }
1271 * Set a value of unspecified type for this node.
1273 bool setUnspecifiedValue (const char * value);
1275 template<typename T>
1276 bool setValue(const T& val,
1277 typename boost::enable_if_c<simgear::props::PropertyTraits<T>::Internal>
1280 template<typename T>
1281 bool setValue(const T& val,
1282 typename boost::disable_if_c<simgear::props::PropertyTraits<T>::Internal>
1286 bool setValue(const char (&val)[N])
1288 return setValue(&val[0]);
1292 * Set relative node to given value and afterwards make read only.
1294 * @param relative_path Path to node
1295 * @param value Value to set
1297 * @return whether value could be set
1299 template<typename T>
1300 bool setValueReadOnly(const std::string& relative_path, const T& value)
1302 SGPropertyNode* node = getNode(relative_path, true);
1303 bool ret = node->setValue(value);
1304 node->setAttributes(READ);
1308 #if !PROPS_STANDALONE
1310 * Interpolate current value to target value within given time.
1312 * @param type Type of interpolation ("numeric", "color", etc.)
1313 * @param target Node containing target value
1314 * @param duration Duration of interpolation (in seconds)
1315 * @param easing Easing function (http://easings.net/)
1317 bool interpolate( const std::string& type,
1318 const SGPropertyNode& target,
1319 double duration = 0.6,
1320 const std::string& easing = "swing" );
1323 * Interpolate current value to a series of values within given durations.
1325 * @param type Type of interpolation ("numeric", "color", etc.)
1326 * @param values Nodes containing intermediate and target values
1327 * @param deltas Durations for each interpolation step (in seconds)
1328 * @param easing Easing function (http://easings.net/)
1330 bool interpolate( const std::string& type,
1331 const simgear::PropertyList& values,
1332 const double_list& deltas,
1333 const std::string& easing = "swing" );
1336 * Set the interpolation manager used by the interpolate methods.
1338 static void setInterpolationMgr(simgear::PropertyInterpolationMgr* mgr);
1341 * Get the interpolation manager
1343 static simgear::PropertyInterpolationMgr* getInterpolationMgr();
1347 * Print the value of the property to a stream.
1349 std::ostream& printOn(std::ostream& stream) const;
1357 * Test whether this node is bound to an external data source.
1359 bool isTied () const { return _tied; }
1362 * Bind this node to an external source.
1364 template<typename T>
1365 bool tie(const SGRawValue<T> &rawValue, bool useDefault = true);
1368 * Unbind this node from any external data source.
1374 // Convenience methods using paths.
1375 // TODO: add attribute methods
1380 * Get another node's type.
1382 simgear::props::Type getType (const char * relative_path) const;
1385 * Get another node's type.
1387 simgear::props::Type getType (const std::string& relative_path) const
1388 { return getType(relative_path.c_str()); }
1391 * Test whether another node has a leaf value.
1393 bool hasValue (const char * relative_path) const;
1396 * Test whether another node has a leaf value.
1398 bool hasValue (const std::string& relative_path) const
1399 { return hasValue(relative_path.c_str()); }
1402 * Get another node's value as a bool.
1404 bool getBoolValue (const char * relative_path,
1405 bool defaultValue = false) const;
1408 * Get another node's value as a bool.
1410 bool getBoolValue (const std::string& relative_path,
1411 bool defaultValue = false) const
1412 { return getBoolValue(relative_path.c_str(), defaultValue); }
1415 * Get another node's value as an int.
1417 int getIntValue (const char * relative_path,
1418 int defaultValue = 0) const;
1421 * Get another node's value as an int.
1423 int getIntValue (const std::string& relative_path,
1424 int defaultValue = 0) const
1425 { return getIntValue(relative_path.c_str(), defaultValue); }
1429 * Get another node's value as a long int.
1431 long getLongValue (const char * relative_path,
1432 long defaultValue = 0L) const;
1435 * Get another node's value as a long int.
1437 long getLongValue (const std::string& relative_path,
1438 long defaultValue = 0L) const
1439 { return getLongValue(relative_path.c_str(), defaultValue); }
1442 * Get another node's value as a float.
1444 float getFloatValue (const char * relative_path,
1445 float defaultValue = 0.0f) const;
1448 * Get another node's value as a float.
1450 float getFloatValue (const std::string& relative_path,
1451 float defaultValue = 0.0f) const
1452 { return getFloatValue(relative_path.c_str(), defaultValue); }
1456 * Get another node's value as a double.
1458 double getDoubleValue (const char * relative_path,
1459 double defaultValue = 0.0) const;
1462 * Get another node's value as a double.
1464 double getDoubleValue (const std::string& relative_path,
1465 double defaultValue = 0.0) const
1466 { return getDoubleValue(relative_path.c_str(), defaultValue); }
1469 * Get another node's value as a string.
1471 const char * getStringValue (const char * relative_path,
1472 const char * defaultValue = "") const;
1476 * Get another node's value as a string.
1478 const char * getStringValue (const std::string& relative_path,
1479 const char * defaultValue = "") const
1480 { return getStringValue(relative_path.c_str(), defaultValue); }
1484 * Set another node's value as a bool.
1486 bool setBoolValue (const char * relative_path, bool value);
1489 * Set another node's value as a bool.
1491 bool setBoolValue (const std::string& relative_path, bool value)
1492 { return setBoolValue(relative_path.c_str(), value); }
1496 * Set another node's value as an int.
1498 bool setIntValue (const char * relative_path, int value);
1501 * Set another node's value as an int.
1503 bool setIntValue (const std::string& relative_path, int value)
1504 { return setIntValue(relative_path.c_str(), value); }
1508 * Set another node's value as a long int.
1510 bool setLongValue (const char * relative_path, long value);
1513 * Set another node's value as a long int.
1515 bool setLongValue (const std::string& relative_path, long value)
1516 { return setLongValue(relative_path.c_str(), value); }
1520 * Set another node's value as a float.
1522 bool setFloatValue (const char * relative_path, float value);
1525 * Set another node's value as a float.
1527 bool setFloatValue (const std::string& relative_path, float value)
1528 { return setFloatValue(relative_path.c_str(), value); }
1532 * Set another node's value as a double.
1534 bool setDoubleValue (const char * relative_path, double value);
1537 * Set another node's value as a double.
1539 bool setDoubleValue (const std::string& relative_path, double value)
1540 { return setDoubleValue(relative_path.c_str(), value); }
1544 * Set another node's value as a string.
1546 bool setStringValue (const char * relative_path, const char * value);
1548 bool setStringValue(const char * relative_path, const std::string& value)
1549 { return setStringValue(relative_path, value.c_str()); }
1551 * Set another node's value as a string.
1553 bool setStringValue (const std::string& relative_path, const char * value)
1554 { return setStringValue(relative_path.c_str(), value); }
1556 bool setStringValue (const std::string& relative_path,
1557 const std::string& value)
1558 { return setStringValue(relative_path.c_str(), value.c_str()); }
1561 * Set another node's value with no specified type.
1563 bool setUnspecifiedValue (const char * relative_path, const char * value);
1567 * Test whether another node is bound to an external data source.
1569 bool isTied (const char * relative_path) const;
1572 * Test whether another node is bound to an external data source.
1574 bool isTied (const std::string& relative_path) const
1575 { return isTied(relative_path.c_str()); }
1578 * Bind another node to an external bool source.
1580 bool tie (const char * relative_path, const SGRawValue<bool> &rawValue,
1581 bool useDefault = true);
1584 * Bind another node to an external bool source.
1586 bool tie (const std::string& relative_path, const SGRawValue<bool> &rawValue,
1587 bool useDefault = true)
1588 { return tie(relative_path.c_str(), rawValue, useDefault); }
1592 * Bind another node to an external int source.
1594 bool tie (const char * relative_path, const SGRawValue<int> &rawValue,
1595 bool useDefault = true);
1598 * Bind another node to an external int source.
1600 bool tie (const std::string& relative_path, const SGRawValue<int> &rawValue,
1601 bool useDefault = true)
1602 { return tie(relative_path.c_str(), rawValue, useDefault); }
1606 * Bind another node to an external long int source.
1608 bool tie (const char * relative_path, const SGRawValue<long> &rawValue,
1609 bool useDefault = true);
1612 * Bind another node to an external long int source.
1614 bool tie (const std::string& relative_path, const SGRawValue<long> &rawValue,
1615 bool useDefault = true)
1616 { return tie(relative_path.c_str(), rawValue, useDefault); }
1620 * Bind another node to an external float source.
1622 bool tie (const char * relative_path, const SGRawValue<float> &rawValue,
1623 bool useDefault = true);
1626 * Bind another node to an external float source.
1628 bool tie (const std::string& relative_path, const SGRawValue<float> &rawValue,
1629 bool useDefault = true)
1630 { return tie(relative_path.c_str(), rawValue, useDefault); }
1634 * Bind another node to an external double source.
1636 bool tie (const char * relative_path, const SGRawValue<double> &rawValue,
1637 bool useDefault = true);
1640 * Bind another node to an external double source.
1642 bool tie (const std::string& relative_path, const SGRawValue<double> &rawValue,
1643 bool useDefault = true)
1644 { return tie(relative_path.c_str(), rawValue, useDefault); }
1648 * Bind another node to an external string source.
1650 bool tie (const char * relative_path, const SGRawValue<const char *> &rawValue,
1651 bool useDefault = true);
1654 * Bind another node to an external string source.
1656 bool tie (const std::string& relative_path, const SGRawValue<const char*> &rawValue,
1657 bool useDefault = true)
1658 { return tie(relative_path.c_str(), rawValue, useDefault); }
1662 * Unbind another node from any external data source.
1664 bool untie (const char * relative_path);
1667 * Unbind another node from any external data source.
1669 bool untie (const std::string& relative_path)
1670 { return untie(relative_path.c_str()); }
1674 * Add a change listener to the property. If "initial" is set call the
1675 * listener initially.
1677 void addChangeListener (SGPropertyChangeListener * listener,
1678 bool initial = false);
1682 * Remove a change listener from the property.
1684 void removeChangeListener (SGPropertyChangeListener * listener);
1688 * Get the number of listeners.
1690 int nListeners () const { return _listeners ? (int)_listeners->size() : 0; }
1694 * Fire a value change event to all listeners.
1696 void fireValueChanged ();
1700 * Fire a child-added event to all listeners.
1702 void fireChildAdded (SGPropertyNode * child);
1705 * Trigger a child-added and value-changed event for every child (Unlimited
1708 * @param fire_self Whether to trigger the events also for the node itself.
1710 * It can be used to simulating the creation of a property tree, eg. for
1711 * (re)initializing a subsystem which is controlled through the property tree.
1713 void fireCreatedRecursive(bool fire_self = false);
1716 * Fire a child-removed event to all listeners.
1718 void fireChildRemoved (SGPropertyNode * child);
1721 * Fire a child-removed event for every child of this node (Unlimited depth)
1723 * Upon removal of a child node only for this single node a child-removed
1724 * event is triggered. If eg. resource cleanup relies on receiving a
1725 * child-removed event for every child this method can be used.
1727 void fireChildrenRemovedRecursive();
1731 * Clear any existing value and set the type to NONE.
1736 * Compare two property trees. The property trees are equal if: 1)
1737 * They have no children, and have the same type and the values are
1738 * equal, or 2) have the same number of children, and the
1739 * corresponding children in each tree are equal. "corresponding"
1740 * means have the same name and index.
1742 * Attributes, removed children, and aliases aren't considered.
1744 static bool compare (const SGPropertyNode& lhs, const SGPropertyNode& rhs);
1748 void fireValueChanged (SGPropertyNode * node);
1749 void fireChildAdded (SGPropertyNode * parent, SGPropertyNode * child);
1750 void fireChildRemoved (SGPropertyNode * parent, SGPropertyNode * child);
1752 SGPropertyNode_ptr eraseChild(simgear::PropertyList::iterator child);
1755 * Protected constructor for making new nodes on demand.
1757 SGPropertyNode (const std::string& name, int index, SGPropertyNode * parent);
1758 template<typename Itr>
1759 SGPropertyNode (Itr begin, Itr end, int index, SGPropertyNode * parent);
1761 static simgear::PropertyInterpolationMgr* _interpolation_mgr;
1765 // Get the raw value
1766 bool get_bool () const;
1767 int get_int () const;
1768 long get_long () const;
1769 float get_float () const;
1770 double get_double () const;
1771 const char * get_string () const;
1773 // Set the raw value
1774 bool set_bool (bool value);
1775 bool set_int (int value);
1776 bool set_long (long value);
1777 bool set_float (float value);
1778 bool set_double (double value);
1779 bool set_string (const char * value);
1783 * Get the value as a string.
1785 const char * make_string () const;
1788 * Trace a read access.
1790 void trace_read () const;
1794 * Trace a write access.
1796 void trace_write () const;
1800 /// To avoid cyclic reference counting loops this shall not be a reference
1802 SGPropertyNode * _parent;
1803 simgear::PropertyList _children;
1804 mutable std::string _buffer;
1805 simgear::props::Type _type;
1809 // The right kind of pointer...
1811 SGPropertyNode * alias;
1824 std::vector<SGPropertyChangeListener *> * _listeners;
1826 // Pass name as a pair of iterators
1827 template<typename Itr>
1828 SGPropertyNode * getChildImpl (Itr begin, Itr end, int index = 0, bool create = false);
1829 // very internal method
1830 template<typename Itr>
1831 SGPropertyNode* getExistingChild (Itr begin, Itr end, int index);
1832 // very internal path parsing function
1833 template<typename SplitItr>
1834 friend SGPropertyNode* find_node_aux(SGPropertyNode * current, SplitItr& itr,
1835 bool create, int last_index);
1837 friend size_t hash_value(const SGPropertyNode& node);
1840 // Convenience functions for use in templates
1841 template<typename T>
1842 #if PROPS_STANDALONE
1845 typename boost::disable_if<boost::is_enum<T>, T>::type
1847 getValue(const SGPropertyNode*);
1850 inline bool getValue<bool>(const SGPropertyNode* node) { return node->getBoolValue(); }
1853 inline int getValue<int>(const SGPropertyNode* node) { return node->getIntValue(); }
1856 inline long getValue<long>(const SGPropertyNode* node) { return node->getLongValue(); }
1859 inline float getValue<float>(const SGPropertyNode* node)
1861 return node->getFloatValue();
1865 inline double getValue<double>(const SGPropertyNode* node)
1867 return node->getDoubleValue();
1871 inline const char * getValue<const char*>(const SGPropertyNode* node)
1873 return node->getStringValue ();
1877 inline std::string getValue<std::string>(const SGPropertyNode* node)
1879 return node->getStringValue();
1885 * Default trait for extracting enum values from SGPropertyNode. Create your
1886 * own specialization for specific enum types to enable validation of values.
1892 * Typename of the enum
1894 static const char* name() { return typeid(T).name(); }
1897 * @return Default value (will be used if validation fails)
1899 static T defVal() { return T(); }
1902 * @return Whether the given integer value has an enum value defined
1904 static bool validate(int) { return true; }
1906 } // namespace simgear
1908 /** Extract enum from SGPropertyNode */
1909 template<typename T>
1910 #if PROPS_STANDALONE
1913 inline typename boost::enable_if<boost::is_enum<T>, T>::type
1915 getValue(const SGPropertyNode* node)
1917 typedef simgear::enum_traits<T> Traits;
1918 int val = node->getIntValue();
1919 if( !Traits::validate(val) )
1925 "Invalid value for enum (" << Traits::name() << ", val = " << val << ")"
1927 return Traits::defVal();
1929 return static_cast<T>(node->getIntValue());
1932 inline bool setValue(SGPropertyNode* node, bool value)
1934 return node->setBoolValue(value);
1937 inline bool setValue(SGPropertyNode* node, int value)
1939 return node->setIntValue(value);
1942 inline bool setValue(SGPropertyNode* node, long value)
1944 return node->setLongValue(value);
1947 inline bool setValue(SGPropertyNode* node, float value)
1949 return node->setFloatValue(value);
1952 inline bool setValue(SGPropertyNode* node, double value)
1954 return node->setDoubleValue(value);
1957 inline bool setValue(SGPropertyNode* node, const char* value)
1959 return node->setStringValue(value);
1962 inline bool setValue (SGPropertyNode* node, const std::string& value)
1964 return node->setStringValue(value.c_str());
1967 template<typename T>
1968 bool SGPropertyNode::tie(const SGRawValue<T> &rawValue, bool useDefault)
1970 using namespace simgear::props;
1971 if (_type == ALIAS || _tied)
1974 useDefault = useDefault && hasValue();
1975 T old_val = SGRawValue<T>::DefaultValue();
1977 old_val = getValue<T>(this);
1979 if (PropertyTraits<T>::Internal)
1980 _type = PropertyTraits<T>::type_tag;
1984 _value.val = rawValue.clone();
1986 int save_attributes = getAttributes();
1987 setAttribute( WRITE, true );
1989 setAttributes( save_attributes );
1995 bool SGPropertyNode::tie (const SGRawValue<const char *> &rawValue,
1998 template<typename T>
1999 T SGPropertyNode::getValue(typename boost::disable_if_c<simgear::props
2000 ::PropertyTraits<T>::Internal>::type* dummy) const
2002 using namespace simgear::props;
2003 if (_attr == (READ|WRITE) && _type == EXTENDED
2004 && _value.val->getType() == PropertyTraits<T>::type_tag) {
2005 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
2007 if (getAttribute(TRACE_READ))
2009 if (!getAttribute(READ))
2010 return SGRawValue<T>::DefaultValue();
2013 if (_value.val->getType() == PropertyTraits<T>::type_tag)
2014 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
2018 return simgear::parseString<T>(make_string());
2020 default: // avoid compiler warning
2023 return SGRawValue<T>::DefaultValue();
2026 template<typename T>
2027 inline T SGPropertyNode::getValue(typename boost::enable_if_c<simgear::props
2028 ::PropertyTraits<T>::Internal>::type* dummy) const
2030 return ::getValue<T>(this);
2033 template<typename T, typename T_get /* = T */> // TODO use C++11 or traits
2034 std::vector<T> SGPropertyNode::getChildValues(const std::string& name) const
2036 const simgear::PropertyList& props = getChildren(name);
2037 std::vector<T> values( props.size() );
2039 for( size_t i = 0; i < props.size(); ++i )
2040 values[i] = props[i]->getValue<T_get>();
2045 template<typename T>
2047 std::vector<T> SGPropertyNode::getChildValues(const std::string& name) const
2049 return getChildValues<T, T>(name);
2052 template<typename T>
2053 bool SGPropertyNode::setValue(const T& val,
2054 typename boost::disable_if_c<simgear::props
2055 ::PropertyTraits<T>::Internal>::type* dummy)
2057 using namespace simgear::props;
2058 if (_attr == (READ|WRITE) && _type == EXTENDED
2059 && _value.val->getType() == PropertyTraits<T>::type_tag) {
2060 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
2063 if (getAttribute(WRITE)
2064 && ((_type == EXTENDED
2065 && _value.val->getType() == PropertyTraits<T>::type_tag)
2066 || _type == NONE || _type == UNSPECIFIED)) {
2067 if (_type == NONE || _type == UNSPECIFIED) {
2070 _value.val = new SGRawValueContainer<T>(val);
2072 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
2074 if (getAttribute(TRACE_WRITE))
2081 template<typename T>
2082 inline bool SGPropertyNode::setValue(const T& val,
2083 typename boost::enable_if_c<simgear::props
2084 ::PropertyTraits<T>::Internal>::type* dummy)
2086 return ::setValue(this, val);
2090 * Utility function for creation of a child property node.
2092 inline SGPropertyNode* makeChild(SGPropertyNode* parent, const char* name,
2095 return parent->getChild(name, index, true);
2099 * Utility function for creation of a child property node using a
2104 template<typename StringType>
2105 inline SGPropertyNode* makeNode(SGPropertyNode* parent, const StringType& name)
2107 return parent->getNode(name, true);
2112 size_t hash_value(const SGPropertyNode& node);
2114 // Helper comparison and hash functions for common cases
2122 bool operator()(const SGPropertyNode* lhs, const SGPropertyNode* rhs) const
2124 return SGPropertyNode::compare(*lhs, *rhs);
2126 bool operator()(SGPropertyNode_ptr lhs, const SGPropertyNode* rhs) const
2128 return SGPropertyNode::compare(*lhs, *rhs);
2130 bool operator()(const SGPropertyNode* lhs, SGPropertyNode_ptr rhs) const
2132 return SGPropertyNode::compare(*lhs, *rhs);
2134 bool operator()(SGPropertyNode_ptr lhs, SGPropertyNode_ptr rhs) const
2136 return SGPropertyNode::compare(*lhs, *rhs);
2142 size_t operator()(const SGPropertyNode* node) const
2144 return hash_value(*node);
2146 size_t operator()(SGPropertyNode_ptr node) const
2148 return hash_value(*node);
2154 /** Convenience class for change listener callbacks without
2155 * creating a derived class implementing a "valueChanged" method.
2156 * Also removes listener on destruction automatically.
2159 class SGPropertyChangeCallback
2160 : public SGPropertyChangeListener
2163 SGPropertyChangeCallback(T* obj, void (T::*method)(SGPropertyNode*),
2164 SGPropertyNode_ptr property,bool initial=false)
2165 : _obj(obj), _callback(method), _property(property)
2167 _property->addChangeListener(this,initial);
2170 SGPropertyChangeCallback(const SGPropertyChangeCallback<T>& other) :
2171 _obj(other._obj), _callback(other._callback), _property(other._property)
2173 _property->addChangeListener(this,false);
2176 virtual ~SGPropertyChangeCallback()
2178 _property->removeChangeListener(this);
2180 void valueChanged (SGPropertyNode * node)
2182 (_obj->*_callback)(node);
2186 void (T::*_callback)(SGPropertyNode*);
2187 SGPropertyNode_ptr _property;
2190 #endif // __PROPS_HXX