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
24 #include <boost/utility.hpp>
28 #include <simgear/compiler.h>
29 #include <simgear/debug/logstream.hxx>
33 #include <simgear/math/SGMathFwd.hxx>
34 #include <simgear/math/sg_types.hxx>
35 #include <simgear/structure/SGReferenced.hxx>
36 #include <simgear/structure/SGSharedPtr.hxx>
38 // XXX This whole file should be in the simgear namespace, but I don't
39 // have the guts yet...
44 class PropertyInterpolationMgr;
47 std::istream& readFrom(std::istream& stream, T& result)
54 * Parse a string as an object of a given type.
55 * XXX no error behavior yet.
57 * @tparam T the return type
58 * @param str the string
62 inline T parseString(const std::string& str)
64 std::istringstream stream(str);
66 readFrom(stream, result);
71 * Property value types.
75 #pragma warn A sloppy coder has defined NONE as a macro!
80 #pragma warn A sloppy coder has defined ALIAS as a macro!
85 #pragma warn A sloppy coder has defined UNSPECIFIED as a macro!
90 #pragma warn A sloppy coder has defined BOOL as a macro!
95 #pragma warn A sloppy coder has defined INT as a macro!
100 #pragma warn A sloppy coder has defined LONG as a macro!
105 #pragma warn A sloppy coder has defined FLOAT as a macro!
110 #pragma warn A sloppy coder has defined DOUBLE as a macro!
115 #pragma warn A sloppy coder has defined STRING as a macro!
122 * The possible types of an SGPropertyNode. Types that appear after
123 * EXTENDED are not stored in the SGPropertyNode itself.
126 NONE = 0, /**< The node hasn't been assigned a value yet. */
127 ALIAS, /**< The node "points" to another node. */
135 EXTENDED, /**< The node's value is not stored in the property;
136 * the actual value and type is retrieved from an
137 * SGRawValue node. This type is never returned by @see
138 * SGPropertyNode::getType.
140 // Extended properties
145 template<typename T> struct PropertyTraits;
147 #define DEFINTERNALPROP(TYPE, PROP) \
149 struct PropertyTraits<TYPE> \
151 static const Type type_tag = PROP; \
152 enum { Internal = 1 }; \
155 DEFINTERNALPROP(bool, BOOL);
156 DEFINTERNALPROP(int, INT);
157 DEFINTERNALPROP(long, LONG);
158 DEFINTERNALPROP(float, FLOAT);
159 DEFINTERNALPROP(double, DOUBLE);
160 DEFINTERNALPROP(const char *, STRING);
161 DEFINTERNALPROP(const char[], STRING);
162 #undef DEFINTERNALPROP
169 ////////////////////////////////////////////////////////////////////////
172 // This is the mechanism that information-providing routines can
173 // use to link their own values to the property manager. Any
174 // SGValue can be tied to a raw value and then untied again.
176 // Note: we are forced to use inlined methods here to ensure
177 // that the templates will be instantiated. We're probably taking
178 // a small performance hit for that.
179 ////////////////////////////////////////////////////////////////////////
182 * Base class for SGRawValue classes that holds no type
183 * information. This allows some generic manipulation of the
190 * Get the type enumeration for the raw value.
194 virtual simgear::props::Type getType() const = 0;
198 * Create a new deep copy of this raw value.
200 * The copy will contain its own version of the underlying value
201 * as well, and will be the same type.
203 * @return A deep copy of the current object.
205 virtual SGRaw* clone() const = 0;
209 class SGRawExtended : public SGRaw
213 * Make an SGRawValueContainer from the SGRawValue.
215 * This is a virtual function of SGRawExtended so that
216 * SGPropertyNode::untie doesn't need to know the type of an
219 virtual SGRawExtended* makeContainer() const = 0;
221 * Write value out to a stream
223 virtual std::ostream& printOn(std::ostream& stream) const = 0;
225 * Read value from a stream and store it.
227 virtual std::istream& readFrom(std::istream& stream) = 0;
230 // Choose between different base classes based on whether the value is
231 // stored internal to the property node. This frees us from defining
232 // the virtual functions in the SGRawExtended interface where they
233 // don't make sense, e.g. readFrom for the const char* type.
234 template<typename T, int internal = simgear::props::PropertyTraits<T>::Internal>
238 class SGRawBase<T, 1> : public SGRaw
243 class SGRawBase<T, 0> : public SGRawExtended
245 virtual SGRawExtended* makeContainer() const;
246 virtual std::ostream& printOn(std::ostream& stream) const;
247 virtual std::istream& readFrom(std::istream& stream);
251 * Abstract base class for a raw value.
253 * <p>The property manager is implemented in two layers. The {@link
254 * SGPropertyNode} is the highest and most abstract layer,
255 * representing an LValue/RValue pair: it records the position of the
256 * property in the property tree and contains facilities for
257 * navigation to other nodes. It is guaranteed to be persistent: the
258 * {@link SGPropertyNode} will not change during a session, even if
259 * the property is bound and unbound multiple times.</p>
261 * <p>When the property value is not managed internally in the
262 * SGPropertyNode, the SGPropertyNode will contain a reference to an
263 * SGRawValue (this class), which provides an abstract way to get,
264 * set, and clone the underlying value. The SGRawValue may change
265 * frequently during a session as a value is retyped or bound and
266 * unbound to various data source, but the abstract SGPropertyNode
267 * layer insulates the application from those changes.
269 * <p>The SGPropertyNode class always keeps a *copy* of a raw value,
270 * not the original one passed to it; if you override a derived class
271 * but do not replace the {@link #clone} method, strange things will
274 * <p>All derived SGRawValue classes must implement {@link #getValue},
275 * {@link #setValue}, and {@link #clone} for the appropriate type.</p>
277 * @see SGPropertyNode
278 * @see SGRawValuePointer
279 * @see SGRawValueFunctions
280 * @see SGRawValueFunctionsIndexed
281 * @see SGRawValueMethods
282 * @see SGRawValueMethodsIndexed
283 * @see SGRawValueContainer
286 class SGRawValue : public SGRawBase<T>
291 * The default underlying value for this type.
293 * Every raw value has a default; the default is false for a
294 * boolean, 0 for the various numeric values, and "" for a string.
295 * If additional types of raw values are added in the future, they
296 * may need different kinds of default values (such as epoch for a
297 * date type). The default value is used when creating new values.
299 static T DefaultValue()
308 * Use the default value for this type.
316 virtual ~SGRawValue () {}
320 * Return the underlying value.
322 * @return The actual value for the property.
325 virtual T getValue () const = 0;
329 * Assign a new underlying value.
331 * If the new value cannot be set (because this is a read-only
332 * raw value, or because the new value is not acceptable for
333 * some reason) this method returns false and leaves the original
336 * @param value The actual value for the property.
337 * @return true if the value was set successfully, false otherwise.
340 virtual bool setValue (T value) = 0;
344 * Return the type tag for this raw value type.
346 virtual simgear::props::Type getType() const
348 return simgear::props::PropertyTraits<T>::type_tag;
354 ////////////////////////////////////////////////////////////////////////
355 // Default values for every type.
356 ////////////////////////////////////////////////////////////////////////
358 template<> inline bool SGRawValue<bool>::DefaultValue()
363 template<> inline const char * SGRawValue<const char *>::DefaultValue()
369 * A raw value bound to a pointer.
371 * This is the most efficient way to tie an external value, but also
372 * the most dangerous, because there is no way for the supplier to
373 * perform bounds checking and derived calculations except by polling
374 * the variable to see if it has changed. There is no default
375 * constructor, because this class would be meaningless without a
379 class SGRawValuePointer : public SGRawValue<T>
384 * Explicit pointer constructor.
386 * Create a new raw value bound to the value of the variable
387 * referenced by the pointer.
389 * @param ptr The pointer to the variable to which this raw value
392 SGRawValuePointer (T * ptr) : _ptr(ptr) {}
397 virtual ~SGRawValuePointer () {}
400 * Get the underlying value.
402 * This method will dereference the pointer and return the
405 virtual T getValue () const { return *_ptr; }
408 * Set the underlying value.
410 * This method will dereference the pointer and change the
413 virtual bool setValue (T value) { *_ptr = value; return true; }
416 * Create a copy of this raw value.
418 * The copy will use the same external pointer as the original.
420 virtual SGRaw* clone () const {
421 return new SGRawValuePointer(_ptr);
430 * A value managed through static functions.
432 * A read-only value will not have a setter; a write-only value will
436 class SGRawValueFunctions : public SGRawValue<T>
441 * The template type of a static getter function.
443 typedef T (*getter_t)();
446 * The template type of a static setter function.
448 typedef void (*setter_t)(T);
451 * Explicit constructor.
453 * Create a new raw value bound to the getter and setter supplied.
455 * @param getter A static function for getting a value, or 0
456 * to read-disable the value.
457 * @param setter A static function for setting a value, or 0
458 * to write-disable the value.
460 SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
461 : _getter(getter), _setter(setter) {}
466 virtual ~SGRawValueFunctions () {}
469 * Get the underlying value.
471 * This method will invoke the getter function to get a value.
472 * If no getter function was supplied, this method will always
473 * return the default value for the type.
475 virtual T getValue () const {
476 if (_getter) return (*_getter)();
477 else return SGRawValue<T>::DefaultValue();
481 * Set the underlying value.
483 * This method will invoke the setter function to change the
484 * underlying value. If no setter function was supplied, this
485 * method will return false.
487 virtual bool setValue (T value) {
488 if (_setter) { (*_setter)(value); return true; }
493 * Create a copy of this raw value, bound to the same functions.
495 virtual SGRaw* clone () const {
496 return new SGRawValueFunctions(_getter,_setter);
506 * An indexed value bound to static functions.
508 * A read-only value will not have a setter; a write-only value will
509 * not have a getter. An indexed value is useful for binding one
510 * of a list of possible values (such as multiple engines for a
511 * plane). The index is hard-coded at creation time.
516 class SGRawValueFunctionsIndexed : public SGRawValue<T>
519 typedef T (*getter_t)(int);
520 typedef void (*setter_t)(int,T);
521 SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
522 : _index(index), _getter(getter), _setter(setter) {}
523 virtual ~SGRawValueFunctionsIndexed () {}
524 virtual T getValue () const {
525 if (_getter) return (*_getter)(_index);
526 else return SGRawValue<T>::DefaultValue();
528 virtual bool setValue (T value) {
529 if (_setter) { (*_setter)(_index, value); return true; }
532 virtual SGRaw* clone () const {
533 return new SGRawValueFunctionsIndexed(_index, _getter, _setter);
543 * A value managed through an object and access methods.
545 * A read-only value will not have a setter; a write-only value will
548 template <class C, class T>
549 class SGRawValueMethods : public SGRawValue<T>
552 typedef T (C::*getter_t)() const;
553 typedef void (C::*setter_t)(T);
554 SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
555 : _obj(obj), _getter(getter), _setter(setter) {}
556 virtual ~SGRawValueMethods () {}
557 virtual T getValue () const {
558 if (_getter) { return (_obj.*_getter)(); }
559 else { return SGRawValue<T>::DefaultValue(); }
561 virtual bool setValue (T value) {
562 if (_setter) { (_obj.*_setter)(value); return true; }
565 virtual SGRaw* clone () const {
566 return new SGRawValueMethods(_obj, _getter, _setter);
576 * An indexed value managed through an object and access methods.
578 * A read-only value will not have a setter; a write-only value will
581 template <class C, class T>
582 class SGRawValueMethodsIndexed : public SGRawValue<T>
585 typedef T (C::*getter_t)(int) const;
586 typedef void (C::*setter_t)(int, T);
587 SGRawValueMethodsIndexed (C &obj, int index,
588 getter_t getter = 0, setter_t setter = 0)
589 : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
590 virtual ~SGRawValueMethodsIndexed () {}
591 virtual T getValue () const {
592 if (_getter) { return (_obj.*_getter)(_index); }
593 else { return SGRawValue<T>::DefaultValue(); }
595 virtual bool setValue (T value) {
596 if (_setter) { (_obj.*_setter)(_index, value); return true; }
599 virtual SGRaw* clone () const {
600 return new SGRawValueMethodsIndexed(_obj, _index, _getter, _setter);
610 * A raw value that contains its value. This provides a way for
611 * property nodes to contain values that shouldn't be stored in the
612 * property node itself.
615 class SGRawValueContainer : public SGRawValue<T>
620 * Explicit constructor.
622 SGRawValueContainer(const T& obj) : _obj(obj) {}
627 virtual ~SGRawValueContainer() {}
630 * Get the underlying value.
632 virtual T getValue() const { return _obj; }
635 * Set the underlying value.
637 * This method will dereference the pointer and change the
640 virtual bool setValue (T value) { _obj = value; return true; }
643 * Create a copy of this raw value.
645 virtual SGRaw* clone () const {
646 return new SGRawValueContainer(_obj);
654 SGRawExtended* SGRawBase<T, 0>::makeContainer() const
656 return new SGRawValueContainer<T>(static_cast<const SGRawValue<T>*>(this)
661 std::ostream& SGRawBase<T, 0>::printOn(std::ostream& stream) const
663 return stream << static_cast<SGRawValue<T>*>(this)->getValue();
667 std::istream& SGRawBase<T, 0>::readFrom(std::istream& stream)
670 simgear::readFrom(stream, value);
671 static_cast<SGRawValue<T>*>(this)->setValue(value);
676 * The smart pointer that manage reference counting
678 class SGPropertyNode;
679 typedef SGSharedPtr<SGPropertyNode> SGPropertyNode_ptr;
680 typedef SGSharedPtr<const SGPropertyNode> SGConstPropertyNode_ptr;
684 typedef std::vector<SGPropertyNode_ptr> PropertyList;
688 * The property change listener interface.
690 * <p>Any class that needs to listen for property changes must implement
691 * this interface.</p>
693 class SGPropertyChangeListener
696 virtual ~SGPropertyChangeListener ();
697 virtual void valueChanged (SGPropertyNode * node);
698 virtual void childAdded (SGPropertyNode * parent, SGPropertyNode * child);
699 virtual void childRemoved (SGPropertyNode * parent, SGPropertyNode * child);
702 friend class SGPropertyNode;
703 virtual void register_property (SGPropertyNode * node);
704 virtual void unregister_property (SGPropertyNode * node);
707 std::vector<SGPropertyNode *> _properties;
712 * A node in a property tree.
714 class SGPropertyNode : public SGReferenced
722 MAX_STRING_LEN = 1024
726 * Access mode attributes.
728 * <p>The ARCHIVE attribute is strictly advisory, and controls
729 * whether the property should normally be saved and restored.</p>
740 // beware: if you add another attribute here,
741 // also update value of "LAST_USED_ATTRIBUTE".
746 * Last used attribute
747 * Update as needed when enum Attribute is changed
749 static const int LAST_USED_ATTRIBUTE;
752 * Default constructor.
760 SGPropertyNode (const SGPropertyNode &node);
766 virtual ~SGPropertyNode ();
775 * Test whether this node contains a primitive leaf value.
777 bool hasValue () const { return (_type != simgear::props::NONE); }
781 * Get the node's simple (XML) name.
783 const char * getName () const { return _name.c_str(); }
786 * Get the node's simple name as a string.
788 const std::string& getNameString () const { return _name; }
791 * Get the node's pretty display name, with subscript when needed.
793 std::string getDisplayName (bool simplify = false) const;
797 * Get the node's integer index.
799 int getIndex () const { return _index; }
803 * Get a non-const pointer to the node's parent.
805 SGPropertyNode * getParent () { return _parent; }
809 * Get a const pointer to the node's parent.
811 const SGPropertyNode * getParent () const { return _parent; }
820 * Get the number of child nodes.
822 int nChildren () const { return (int)_children.size(); }
826 * Get a child node by position (*NOT* index).
828 SGPropertyNode * getChild (int position);
832 * Get a const child node by position (*NOT* index).
834 const SGPropertyNode * getChild (int position) const;
838 * Test whether a named child exists.
840 bool hasChild (const char * name, int index = 0) const
842 return (getChild(name, index) != 0);
846 * Test whether a named child exists.
848 bool hasChild (const std::string& name, int index = 0) const
850 return (getChild(name, index) != 0);
854 * Create a new child node with the given name and an unused index
856 * @param min_index Minimal index for new node (skips lower indices)
857 * @param append Whether to simply use the index after the last used index
858 * or use a lower, unused index if it exists
860 SGPropertyNode * addChild ( const char* name,
862 bool append = true );
863 SGPropertyNode * addChild ( const std::string& name,
866 { return addChild(name.c_str(), min_index, append); }
869 * Create multiple child nodes with the given name an unused indices
871 * @param count The number of nodes create
872 * @param min_index Minimal index for new nodes (skips lower indices)
873 * @param append Whether to simply use the index after the last used index
874 * or use a lower, unused index if it exists
876 simgear::PropertyList addChildren ( const std::string& name,
879 bool append = true );
882 * Get a child node by name and index.
884 SGPropertyNode * getChild (const char* name, int index = 0,
885 bool create = false);
886 SGPropertyNode * getChild (const std::string& name, int index = 0,
887 bool create = false);
889 * Get a const child node by name and index.
891 const SGPropertyNode * getChild (const char * name, int index = 0) const;
894 * Get a const child node by name and index.
896 const SGPropertyNode * getChild (const std::string& name, int index = 0) const
897 { return getChild(name.c_str(), index); }
901 * Get a vector of all children with the specified name.
903 simgear::PropertyList getChildren (const char * name) const;
906 * Get a vector of all children with the specified name.
908 simgear::PropertyList getChildren (const std::string& name) const
909 { return getChildren(name.c_str()); }
912 * Remove child by position.
914 SGPropertyNode_ptr removeChild (int pos, bool keep = true);
918 * Remove a child node
920 SGPropertyNode_ptr removeChild (const char * name, int index = 0,
924 * Remove a child node
926 SGPropertyNode_ptr removeChild (const std::string& name, int index = 0,
928 { return removeChild(name.c_str(), index, keep); }
931 * Remove all children with the specified name.
933 simgear::PropertyList removeChildren (const char * name, bool keep = true);
936 * Remove all children with the specified name.
938 simgear::PropertyList removeChildren (const std::string& name,
940 { return removeChildren(name.c_str(), keep); }
948 * Alias this node's leaf value to another's.
950 bool alias (SGPropertyNode * target);
954 * Alias this node's leaf value to another's by relative path.
956 bool alias (const char * path);
959 * Alias this node's leaf value to another's by relative path.
961 bool alias (const std::string& path)
962 { return alias(path.c_str()); }
966 * Remove any alias for this node.
972 * Test whether the node's leaf value is aliased to another's.
974 bool isAlias () const { return (_type == simgear::props::ALIAS); }
978 * Get a non-const pointer to the current alias target, if any.
980 SGPropertyNode * getAliasTarget ();
984 * Get a const pointer to the current alias target, if any.
986 const SGPropertyNode * getAliasTarget () const;
995 * Get the path to this node from the root.
997 std::string getPath (bool simplify = false) const;
1001 * Get a pointer to the root node.
1003 SGPropertyNode * getRootNode ();
1007 * Get a const pointer to the root node.
1009 const SGPropertyNode * getRootNode () const;
1013 * Get a pointer to another node by relative path.
1015 SGPropertyNode * getNode (const char * relative_path, bool create = false);
1018 * Get a pointer to another node by relative path.
1020 SGPropertyNode * getNode (const std::string& relative_path, bool create = false)
1021 { return getNode(relative_path.c_str(), create); }
1024 * Get a pointer to another node by relative path.
1026 * This method leaves the index off the last member of the path,
1027 * so that the user can specify it separately (and save some
1028 * string building). For example, getNode("/bar[1]/foo", 3) is
1029 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
1030 * provided overrides any given in the path itself for the last
1033 SGPropertyNode * getNode (const char * relative_path, int index,
1034 bool create = false);
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 std::string& relative_path, int index,
1047 bool create = false)
1048 { return getNode(relative_path.c_str(), index, create); }
1051 * Get a const pointer to another node by relative path.
1053 const SGPropertyNode * getNode (const char * relative_path) const;
1056 * Get a const pointer to another node by relative path.
1058 const SGPropertyNode * getNode (const std::string& relative_path) const
1059 { return getNode(relative_path.c_str()); }
1063 * Get a const pointer to another node by relative path.
1065 * This method leaves the index off the last member of the path,
1066 * so that the user can specify it separate.
1068 const SGPropertyNode * getNode (const char * relative_path,
1072 * Get a const pointer to another node by relative path.
1074 * This method leaves the index off the last member of the path,
1075 * so that the user can specify it separate.
1077 const SGPropertyNode * getNode (const std::string& relative_path,
1079 { return getNode(relative_path.c_str(), index); }
1086 * Check a single mode attribute for the property node.
1088 bool getAttribute (Attribute attr) const { return ((_attr & attr) != 0); }
1092 * Set a single mode attribute for the property node.
1094 void setAttribute (Attribute attr, bool state) {
1095 (state ? _attr |= attr : _attr &= ~attr);
1100 * Get all of the mode attributes for the property node.
1102 int getAttributes () const { return _attr; }
1106 * Set all of the mode attributes for the property node.
1108 void setAttributes (int attr) { _attr = attr; }
1112 // Leaf Value (primitive).
1117 * Get the type of leaf value, if any, for this node.
1119 simgear::props::Type getType () const;
1123 * Get a bool value for this node.
1125 bool getBoolValue () const;
1129 * Get an int value for this node.
1131 int getIntValue () const;
1135 * Get a long int value for this node.
1137 long getLongValue () const;
1141 * Get a float value for this node.
1143 float getFloatValue () const;
1147 * Get a double value for this node.
1149 double getDoubleValue () const;
1153 * Get a string value for this node.
1155 const char * getStringValue () const;
1158 * Get a value from a node. If the actual type of the node doesn't
1159 * match the desired type, a conversion isn't guaranteed.
1161 template<typename T>
1162 T getValue(typename boost::enable_if_c<simgear::props::PropertyTraits<T>::Internal>
1163 ::type* dummy = 0) const;
1164 // Getter for extended property
1165 template<typename T>
1166 T getValue(typename boost::disable_if_c<simgear::props::PropertyTraits<T>::Internal>
1167 ::type* dummy = 0) const;
1170 * Get a list of values from all children with the given name
1172 template<typename T, typename T_get /* = T */> // TODO use C++11 or traits
1173 std::vector<T> getChildValues(const std::string& name) const;
1176 * Get a list of values from all children with the given name
1178 template<typename T>
1179 std::vector<T> getChildValues(const std::string& name) const;
1182 * Set a bool value for this node.
1184 bool setBoolValue (bool value);
1188 * Set an int value for this node.
1190 bool setIntValue (int value);
1194 * Set a long int value for this node.
1196 bool setLongValue (long value);
1200 * Set a float value for this node.
1202 bool setFloatValue (float value);
1206 * Set a double value for this node.
1208 bool setDoubleValue (double value);
1212 * Set a string value for this node.
1214 bool setStringValue (const char * value);
1217 * Set a string value for this node.
1219 bool setStringValue (const std::string& value)
1220 { return setStringValue(value.c_str()); }
1224 * Set a value of unspecified type for this node.
1226 bool setUnspecifiedValue (const char * value);
1228 template<typename T>
1229 bool setValue(const T& val,
1230 typename boost::enable_if_c<simgear::props::PropertyTraits<T>::Internal>
1233 template<typename T>
1234 bool setValue(const T& val,
1235 typename boost::disable_if_c<simgear::props::PropertyTraits<T>::Internal>
1239 bool setValue(const char (&val)[N])
1241 return setValue(&val[0]);
1245 * Set relative node to given value and afterwards make read only.
1247 * @param relative_path Path to node
1248 * @param value Value to set
1250 * @return whether value could be set
1252 template<typename T>
1253 bool setValueReadOnly(const std::string& relative_path, const T& value)
1255 SGPropertyNode* node = getNode(relative_path, true);
1256 bool ret = node->setValue(value);
1257 node->setAttributes(READ);
1262 * Interpolate current value to target value within given time.
1264 * @param type Type of interpolation ("numeric", "color", etc.)
1265 * @param target Node containing target value
1266 * @param duration Duration of interpolation (in seconds)
1267 * @param easing Easing function (http://easings.net/)
1269 bool interpolate( const std::string& type,
1270 const SGPropertyNode& target,
1271 double duration = 0.6,
1272 const std::string& easing = "swing" );
1275 * Interpolate current value to a series of values within given durations.
1277 * @param type Type of interpolation ("numeric", "color", etc.)
1278 * @param values Nodes containing intermediate and target values
1279 * @param duration Durations for each interpolation step (in seconds)
1280 * @param easing Easing function (http://easings.net/)
1282 bool interpolate( const std::string& type,
1283 const simgear::PropertyList& values,
1284 const double_list& deltas,
1285 const std::string& easing = "swing" );
1288 * Set the interpolation manager used by the interpolate methods.
1290 static void setInterpolationMgr(simgear::PropertyInterpolationMgr* mgr);
1293 * Print the value of the property to a stream.
1295 std::ostream& printOn(std::ostream& stream) const;
1303 * Test whether this node is bound to an external data source.
1305 bool isTied () const { return _tied; }
1308 * Bind this node to an external source.
1310 template<typename T>
1311 bool tie(const SGRawValue<T> &rawValue, bool useDefault = true);
1314 * Unbind this node from any external data source.
1320 // Convenience methods using paths.
1321 // TODO: add attribute methods
1326 * Get another node's type.
1328 simgear::props::Type getType (const char * relative_path) const;
1331 * Get another node's type.
1333 simgear::props::Type getType (const std::string& relative_path) const
1334 { return getType(relative_path.c_str()); }
1337 * Test whether another node has a leaf value.
1339 bool hasValue (const char * relative_path) const;
1342 * Test whether another node has a leaf value.
1344 bool hasValue (const std::string& relative_path) const
1345 { return hasValue(relative_path.c_str()); }
1348 * Get another node's value as a bool.
1350 bool getBoolValue (const char * relative_path,
1351 bool defaultValue = false) const;
1354 * Get another node's value as a bool.
1356 bool getBoolValue (const std::string& relative_path,
1357 bool defaultValue = false) const
1358 { return getBoolValue(relative_path.c_str(), defaultValue); }
1361 * Get another node's value as an int.
1363 int getIntValue (const char * relative_path,
1364 int defaultValue = 0) const;
1367 * Get another node's value as an int.
1369 int getIntValue (const std::string& relative_path,
1370 int defaultValue = 0) const
1371 { return getIntValue(relative_path.c_str(), defaultValue); }
1375 * Get another node's value as a long int.
1377 long getLongValue (const char * relative_path,
1378 long defaultValue = 0L) const;
1381 * Get another node's value as a long int.
1383 long getLongValue (const std::string& relative_path,
1384 long defaultValue = 0L) const
1385 { return getLongValue(relative_path.c_str(), defaultValue); }
1388 * Get another node's value as a float.
1390 float getFloatValue (const char * relative_path,
1391 float defaultValue = 0.0f) const;
1394 * Get another node's value as a float.
1396 float getFloatValue (const std::string& relative_path,
1397 float defaultValue = 0.0f) const
1398 { return getFloatValue(relative_path.c_str(), defaultValue); }
1402 * Get another node's value as a double.
1404 double getDoubleValue (const char * relative_path,
1405 double defaultValue = 0.0) const;
1408 * Get another node's value as a double.
1410 double getDoubleValue (const std::string& relative_path,
1411 double defaultValue = 0.0) const
1412 { return getDoubleValue(relative_path.c_str(), defaultValue); }
1415 * Get another node's value as a string.
1417 const char * getStringValue (const char * relative_path,
1418 const char * defaultValue = "") const;
1422 * Get another node's value as a string.
1424 const char * getStringValue (const std::string& relative_path,
1425 const char * defaultValue = "") const
1426 { return getStringValue(relative_path.c_str(), defaultValue); }
1430 * Set another node's value as a bool.
1432 bool setBoolValue (const char * relative_path, bool value);
1435 * Set another node's value as a bool.
1437 bool setBoolValue (const std::string& relative_path, bool value)
1438 { return setBoolValue(relative_path.c_str(), value); }
1442 * Set another node's value as an int.
1444 bool setIntValue (const char * relative_path, int value);
1447 * Set another node's value as an int.
1449 bool setIntValue (const std::string& relative_path, int value)
1450 { return setIntValue(relative_path.c_str(), value); }
1454 * Set another node's value as a long int.
1456 bool setLongValue (const char * relative_path, long value);
1459 * Set another node's value as a long int.
1461 bool setLongValue (const std::string& relative_path, long value)
1462 { return setLongValue(relative_path.c_str(), value); }
1466 * Set another node's value as a float.
1468 bool setFloatValue (const char * relative_path, float value);
1471 * Set another node's value as a float.
1473 bool setFloatValue (const std::string& relative_path, float value)
1474 { return setFloatValue(relative_path.c_str(), value); }
1478 * Set another node's value as a double.
1480 bool setDoubleValue (const char * relative_path, double value);
1483 * Set another node's value as a double.
1485 bool setDoubleValue (const std::string& relative_path, double value)
1486 { return setDoubleValue(relative_path.c_str(), value); }
1490 * Set another node's value as a string.
1492 bool setStringValue (const char * relative_path, const char * value);
1494 bool setStringValue(const char * relative_path, const std::string& value)
1495 { return setStringValue(relative_path, value.c_str()); }
1497 * Set another node's value as a string.
1499 bool setStringValue (const std::string& relative_path, const char * value)
1500 { return setStringValue(relative_path.c_str(), value); }
1502 bool setStringValue (const std::string& relative_path,
1503 const std::string& value)
1504 { return setStringValue(relative_path.c_str(), value.c_str()); }
1507 * Set another node's value with no specified type.
1509 bool setUnspecifiedValue (const char * relative_path, const char * value);
1513 * Test whether another node is bound to an external data source.
1515 bool isTied (const char * relative_path) const;
1518 * Test whether another node is bound to an external data source.
1520 bool isTied (const std::string& relative_path) const
1521 { return isTied(relative_path.c_str()); }
1524 * Bind another node to an external bool source.
1526 bool tie (const char * relative_path, const SGRawValue<bool> &rawValue,
1527 bool useDefault = true);
1530 * Bind another node to an external bool source.
1532 bool tie (const std::string& relative_path, const SGRawValue<bool> &rawValue,
1533 bool useDefault = true)
1534 { return tie(relative_path.c_str(), rawValue, useDefault); }
1538 * Bind another node to an external int source.
1540 bool tie (const char * relative_path, const SGRawValue<int> &rawValue,
1541 bool useDefault = true);
1544 * Bind another node to an external int source.
1546 bool tie (const std::string& relative_path, const SGRawValue<int> &rawValue,
1547 bool useDefault = true)
1548 { return tie(relative_path.c_str(), rawValue, useDefault); }
1552 * Bind another node to an external long int source.
1554 bool tie (const char * relative_path, const SGRawValue<long> &rawValue,
1555 bool useDefault = true);
1558 * Bind another node to an external long int source.
1560 bool tie (const std::string& relative_path, const SGRawValue<long> &rawValue,
1561 bool useDefault = true)
1562 { return tie(relative_path.c_str(), rawValue, useDefault); }
1566 * Bind another node to an external float source.
1568 bool tie (const char * relative_path, const SGRawValue<float> &rawValue,
1569 bool useDefault = true);
1572 * Bind another node to an external float source.
1574 bool tie (const std::string& relative_path, const SGRawValue<float> &rawValue,
1575 bool useDefault = true)
1576 { return tie(relative_path.c_str(), rawValue, useDefault); }
1580 * Bind another node to an external double source.
1582 bool tie (const char * relative_path, const SGRawValue<double> &rawValue,
1583 bool useDefault = true);
1586 * Bind another node to an external double source.
1588 bool tie (const std::string& relative_path, const SGRawValue<double> &rawValue,
1589 bool useDefault = true)
1590 { return tie(relative_path.c_str(), rawValue, useDefault); }
1594 * Bind another node to an external string source.
1596 bool tie (const char * relative_path, const SGRawValue<const char *> &rawValue,
1597 bool useDefault = true);
1600 * Bind another node to an external string source.
1602 bool tie (const std::string& relative_path, const SGRawValue<const char*> &rawValue,
1603 bool useDefault = true)
1604 { return tie(relative_path.c_str(), rawValue, useDefault); }
1608 * Unbind another node from any external data source.
1610 bool untie (const char * relative_path);
1613 * Unbind another node from any external data source.
1615 bool untie (const std::string& relative_path)
1616 { return untie(relative_path.c_str()); }
1620 * Add a change listener to the property. If "initial" is set call the
1621 * listener initially.
1623 void addChangeListener (SGPropertyChangeListener * listener,
1624 bool initial = false);
1628 * Remove a change listener from the property.
1630 void removeChangeListener (SGPropertyChangeListener * listener);
1634 * Get the number of listeners.
1636 int nListeners () const { return _listeners ? (int)_listeners->size() : 0; }
1640 * Fire a value change event to all listeners.
1642 void fireValueChanged ();
1646 * Fire a child-added event to all listeners.
1648 void fireChildAdded (SGPropertyNode * child);
1651 * Trigger a child-added and value-changed event for every child (Unlimited
1654 * @param fire_self Whether to trigger the events also for the node itself.
1656 * It can be used to simulating the creation of a property tree, eg. for
1657 * (re)initializing a subsystem which is controlled through the property tree.
1659 void fireCreatedRecursive(bool fire_self = false);
1662 * Fire a child-removed event to all listeners.
1664 void fireChildRemoved (SGPropertyNode * child);
1667 * Fire a child-removed event for every child of this node (Unlimited depth)
1669 * Upon removal of a child node only for this single node a child-removed
1670 * event is triggered. If eg. resource cleanup relies on receiving a
1671 * child-removed event for every child this method can be used.
1673 void fireChildrenRemovedRecursive();
1677 * Clear any existing value and set the type to NONE.
1682 * Compare two property trees. The property trees are equal if: 1)
1683 * They have no children, and have the same type and the values are
1684 * equal, or 2) have the same number of children, and the
1685 * corresponding children in each tree are equal. "corresponding"
1686 * means have the same name and index.
1688 * Attributes, removed children, and aliases aren't considered.
1690 static bool compare (const SGPropertyNode& lhs, const SGPropertyNode& rhs);
1694 void fireValueChanged (SGPropertyNode * node);
1695 void fireChildAdded (SGPropertyNode * parent, SGPropertyNode * child);
1696 void fireChildRemoved (SGPropertyNode * parent, SGPropertyNode * child);
1699 * Protected constructor for making new nodes on demand.
1701 SGPropertyNode (const std::string& name, int index, SGPropertyNode * parent);
1702 template<typename Itr>
1703 SGPropertyNode (Itr begin, Itr end, int index, SGPropertyNode * parent);
1705 static simgear::PropertyInterpolationMgr* _interpolation_mgr;
1709 // Get the raw value
1710 bool get_bool () const;
1711 int get_int () const;
1712 long get_long () const;
1713 float get_float () const;
1714 double get_double () const;
1715 const char * get_string () const;
1717 // Set the raw value
1718 bool set_bool (bool value);
1719 bool set_int (int value);
1720 bool set_long (long value);
1721 bool set_float (float value);
1722 bool set_double (double value);
1723 bool set_string (const char * value);
1727 * Get the value as a string.
1729 const char * make_string () const;
1732 * Trace a read access.
1734 void trace_read () const;
1738 * Trace a write access.
1740 void trace_write () const;
1744 /// To avoid cyclic reference counting loops this shall not be a reference
1746 SGPropertyNode * _parent;
1747 simgear::PropertyList _children;
1748 simgear::PropertyList _removedChildren;
1749 mutable std::string _buffer;
1750 simgear::props::Type _type;
1754 // The right kind of pointer...
1756 SGPropertyNode * alias;
1769 std::vector<SGPropertyChangeListener *> * _listeners;
1771 // Pass name as a pair of iterators
1772 template<typename Itr>
1773 SGPropertyNode * getChildImpl (Itr begin, Itr end, int index = 0, bool create = false);
1774 // very internal method
1775 template<typename Itr>
1776 SGPropertyNode* getExistingChild (Itr begin, Itr end, int index, bool create);
1777 // very internal path parsing function
1778 template<typename SplitItr>
1779 friend SGPropertyNode* find_node_aux(SGPropertyNode * current, SplitItr& itr,
1780 bool create, int last_index);
1782 friend size_t hash_value(const SGPropertyNode& node);
1785 // Convenience functions for use in templates
1786 template<typename T>
1787 T getValue(const SGPropertyNode*);
1790 inline bool getValue<bool>(const SGPropertyNode* node) { return node->getBoolValue(); }
1793 inline int getValue<int>(const SGPropertyNode* node) { return node->getIntValue(); }
1796 inline long getValue<long>(const SGPropertyNode* node) { return node->getLongValue(); }
1799 inline float getValue<float>(const SGPropertyNode* node)
1801 return node->getFloatValue();
1805 inline double getValue<double>(const SGPropertyNode* node)
1807 return node->getDoubleValue();
1811 inline const char * getValue<const char*>(const SGPropertyNode* node)
1813 return node->getStringValue ();
1817 inline std::string getValue<std::string>(const SGPropertyNode* node)
1819 return node->getStringValue();
1822 inline bool setValue(SGPropertyNode* node, bool value)
1824 return node->setBoolValue(value);
1827 inline bool setValue(SGPropertyNode* node, int value)
1829 return node->setIntValue(value);
1832 inline bool setValue(SGPropertyNode* node, long value)
1834 return node->setLongValue(value);
1837 inline bool setValue(SGPropertyNode* node, float value)
1839 return node->setFloatValue(value);
1842 inline bool setValue(SGPropertyNode* node, double value)
1844 return node->setDoubleValue(value);
1847 inline bool setValue(SGPropertyNode* node, const char* value)
1849 return node->setStringValue(value);
1852 inline bool setValue (SGPropertyNode* node, const std::string& value)
1854 return node->setStringValue(value.c_str());
1857 template<typename T>
1858 bool SGPropertyNode::tie(const SGRawValue<T> &rawValue, bool useDefault)
1860 using namespace simgear::props;
1861 if (_type == ALIAS || _tied)
1864 useDefault = useDefault && hasValue();
1865 T old_val = SGRawValue<T>::DefaultValue();
1867 old_val = getValue<T>(this);
1869 if (PropertyTraits<T>::Internal)
1870 _type = PropertyTraits<T>::type_tag;
1874 _value.val = rawValue.clone();
1876 int save_attributes = getAttributes();
1877 setAttribute( WRITE, true );
1879 setAttributes( save_attributes );
1885 bool SGPropertyNode::tie (const SGRawValue<const char *> &rawValue,
1888 template<typename T>
1889 T SGPropertyNode::getValue(typename boost::disable_if_c<simgear::props
1890 ::PropertyTraits<T>::Internal>::type* dummy) const
1892 using namespace simgear::props;
1893 if (_attr == (READ|WRITE) && _type == EXTENDED
1894 && _value.val->getType() == PropertyTraits<T>::type_tag) {
1895 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
1897 if (getAttribute(TRACE_READ))
1899 if (!getAttribute(READ))
1900 return SGRawValue<T>::DefaultValue();
1903 if (_value.val->getType() == PropertyTraits<T>::type_tag)
1904 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
1908 return simgear::parseString<T>(make_string());
1910 default: // avoid compiler warning
1913 return SGRawValue<T>::DefaultValue();
1916 template<typename T>
1917 inline T SGPropertyNode::getValue(typename boost::enable_if_c<simgear::props
1918 ::PropertyTraits<T>::Internal>::type* dummy) const
1920 return ::getValue<T>(this);
1923 template<typename T, typename T_get /* = T */> // TODO use C++11 or traits
1924 std::vector<T> SGPropertyNode::getChildValues(const std::string& name) const
1926 const simgear::PropertyList& props = getChildren(name);
1927 std::vector<T> values( props.size() );
1929 for( size_t i = 0; i < props.size(); ++i )
1930 values[i] = props[i]->getValue<T_get>();
1935 template<typename T>
1937 std::vector<T> SGPropertyNode::getChildValues(const std::string& name) const
1939 return getChildValues<T, T>(name);
1942 template<typename T>
1943 bool SGPropertyNode::setValue(const T& val,
1944 typename boost::disable_if_c<simgear::props
1945 ::PropertyTraits<T>::Internal>::type* dummy)
1947 using namespace simgear::props;
1948 if (_attr == (READ|WRITE) && _type == EXTENDED
1949 && _value.val->getType() == PropertyTraits<T>::type_tag) {
1950 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
1953 if (getAttribute(WRITE)
1954 && ((_type == EXTENDED
1955 && _value.val->getType() == PropertyTraits<T>::type_tag)
1956 || _type == NONE || _type == UNSPECIFIED)) {
1957 if (_type == NONE || _type == UNSPECIFIED) {
1960 _value.val = new SGRawValueContainer<T>(val);
1962 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
1964 if (getAttribute(TRACE_WRITE))
1971 template<typename T>
1972 inline bool SGPropertyNode::setValue(const T& val,
1973 typename boost::enable_if_c<simgear::props
1974 ::PropertyTraits<T>::Internal>::type* dummy)
1976 return ::setValue(this, val);
1980 * Utility function for creation of a child property node.
1982 inline SGPropertyNode* makeChild(SGPropertyNode* parent, const char* name,
1985 return parent->getChild(name, index, true);
1989 * Utility function for creation of a child property node using a
1994 template<typename StringType>
1995 inline SGPropertyNode* makeNode(SGPropertyNode* parent, const StringType& name)
1997 return parent->getNode(name, true);
2002 size_t hash_value(const SGPropertyNode& node);
2004 // Helper comparison and hash functions for common cases
2012 bool operator()(const SGPropertyNode* lhs, const SGPropertyNode* rhs) const
2014 return SGPropertyNode::compare(*lhs, *rhs);
2016 bool operator()(SGPropertyNode_ptr lhs, const SGPropertyNode* rhs) const
2018 return SGPropertyNode::compare(*lhs, *rhs);
2020 bool operator()(const SGPropertyNode* lhs, SGPropertyNode_ptr rhs) const
2022 return SGPropertyNode::compare(*lhs, *rhs);
2024 bool operator()(SGPropertyNode_ptr lhs, SGPropertyNode_ptr rhs) const
2026 return SGPropertyNode::compare(*lhs, *rhs);
2032 size_t operator()(const SGPropertyNode* node) const
2034 return hash_value(*node);
2036 size_t operator()(SGPropertyNode_ptr node) const
2038 return hash_value(*node);
2044 /** Convenience class for change listener callbacks without
2045 * creating a derived class implementing a "valueChanged" method.
2046 * Also removes listener on destruction automatically.
2049 class SGPropertyChangeCallback
2050 : public SGPropertyChangeListener
2053 SGPropertyChangeCallback(T* obj, void (T::*method)(SGPropertyNode*),
2054 SGPropertyNode_ptr property,bool initial=false)
2055 : _obj(obj), _callback(method), _property(property)
2057 _property->addChangeListener(this,initial);
2060 SGPropertyChangeCallback(const SGPropertyChangeCallback<T>& other) :
2061 _obj(other._obj), _callback(other._callback), _property(other._property)
2063 _property->addChangeListener(this,false);
2066 virtual ~SGPropertyChangeCallback()
2068 _property->removeChangeListener(this);
2070 void valueChanged (SGPropertyNode * node)
2072 (_obj->*_callback)(node);
2076 void (T::*_callback)(SGPropertyNode*);
2077 SGPropertyNode_ptr _property;
2080 #endif // __PROPS_HXX