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/structure/SGReferenced.hxx>
35 #include <simgear/structure/SGSharedPtr.hxx>
37 // XXX This whole file should be in the simgear namespace, but I don't
38 // have the guts yet...
43 std::istream& readFrom(std::istream& stream, T& result)
50 * Parse a string as an object of a given type.
51 * XXX no error behavior yet.
53 * @tparam T the return type
54 * @param str the string
58 inline T parseString(const std::string& str)
60 std::istringstream stream(str);
62 readFrom(stream, result);
67 * Property value types.
71 #pragma warn A sloppy coder has defined NONE as a macro!
76 #pragma warn A sloppy coder has defined ALIAS as a macro!
81 #pragma warn A sloppy coder has defined UNSPECIFIED as a macro!
86 #pragma warn A sloppy coder has defined BOOL as a macro!
91 #pragma warn A sloppy coder has defined INT as a macro!
96 #pragma warn A sloppy coder has defined LONG as a macro!
101 #pragma warn A sloppy coder has defined FLOAT as a macro!
106 #pragma warn A sloppy coder has defined DOUBLE as a macro!
111 #pragma warn A sloppy coder has defined STRING as a macro!
118 * The possible types of an SGPropertyNode. Types that appear after
119 * EXTENDED are not stored in the SGPropertyNode itself.
122 NONE = 0, /**< The node hasn't been assigned a value yet. */
123 ALIAS, /**< The node "points" to another node. */
131 EXTENDED, /**< The node's value is not stored in the property;
132 * the actual value and type is retrieved from an
133 * SGRawValue node. This type is never returned by @see
134 * SGPropertyNode::getType.
136 // Extended properties
141 template<typename T> struct PropertyTraits;
143 #define DEFINTERNALPROP(TYPE, PROP) \
145 struct PropertyTraits<TYPE> \
147 static const Type type_tag = PROP; \
148 enum { Internal = 1 }; \
151 DEFINTERNALPROP(bool, BOOL);
152 DEFINTERNALPROP(int, INT);
153 DEFINTERNALPROP(long, LONG);
154 DEFINTERNALPROP(float, FLOAT);
155 DEFINTERNALPROP(double, DOUBLE);
156 DEFINTERNALPROP(const char *, STRING);
157 DEFINTERNALPROP(const char[], STRING);
158 #undef DEFINTERNALPROP
166 ////////////////////////////////////////////////////////////////////////
169 // This is the mechanism that information-providing routines can
170 // use to link their own values to the property manager. Any
171 // SGValue can be tied to a raw value and then untied again.
173 // Note: we are forced to use inlined methods here to ensure
174 // that the templates will be instantiated. We're probably taking
175 // a small performance hit for that.
176 ////////////////////////////////////////////////////////////////////////
179 * Base class for SGRawValue classes that holds no type
180 * information. This allows some generic manipulation of the
187 * Get the type enumeration for the raw value.
191 virtual simgear::props::Type getType() const = 0;
195 * Create a new deep copy of this raw value.
197 * The copy will contain its own version of the underlying value
198 * as well, and will be the same type.
200 * @return A deep copy of the current object.
202 virtual SGRaw* clone() const = 0;
206 class SGRawExtended : public SGRaw
210 * Make an SGRawValueContainer from the SGRawValue.
212 * This is a virtual function of SGRawExtended so that
213 * SGPropertyNode::untie doesn't need to know the type of an
216 virtual SGRawExtended* makeContainer() const = 0;
218 * Write value out to a stream
220 virtual std::ostream& printOn(std::ostream& stream) const = 0;
222 * Read value from a stream and store it.
224 virtual std::istream& readFrom(std::istream& stream) = 0;
227 // Choose between different base classes based on whether the value is
228 // stored internal to the property node. This frees us from defining
229 // the virtual functions in the SGRawExtended interface where they
230 // don't make sense, e.g. readFrom for the const char* type.
231 template<typename T, int internal = simgear::props::PropertyTraits<T>::Internal>
235 class SGRawBase<T, 1> : public SGRaw
240 class SGRawBase<T, 0> : public SGRawExtended
242 virtual SGRawExtended* makeContainer() const;
243 virtual std::ostream& printOn(std::ostream& stream) const;
244 virtual std::istream& readFrom(std::istream& stream);
248 * Abstract base class for a raw value.
250 * <p>The property manager is implemented in two layers. The {@link
251 * SGPropertyNode} is the highest and most abstract layer,
252 * representing an LValue/RValue pair: it records the position of the
253 * property in the property tree and contains facilities for
254 * navigation to other nodes. It is guaranteed to be persistent: the
255 * {@link SGPropertyNode} will not change during a session, even if
256 * the property is bound and unbound multiple times.</p>
258 * <p>When the property value is not managed internally in the
259 * SGPropertyNode, the SGPropertyNode will contain a reference to an
260 * SGRawValue (this class), which provides an abstract way to get,
261 * set, and clone the underlying value. The SGRawValue may change
262 * frequently during a session as a value is retyped or bound and
263 * unbound to various data source, but the abstract SGPropertyNode
264 * layer insulates the application from those changes.
266 * <p>The SGPropertyNode class always keeps a *copy* of a raw value,
267 * not the original one passed to it; if you override a derived class
268 * but do not replace the {@link #clone} method, strange things will
271 * <p>All derived SGRawValue classes must implement {@link #getValue},
272 * {@link #setValue}, and {@link #clone} for the appropriate type.</p>
274 * @see SGPropertyNode
275 * @see SGRawValuePointer
276 * @see SGRawValueFunctions
277 * @see SGRawValueFunctionsIndexed
278 * @see SGRawValueMethods
279 * @see SGRawValueMethodsIndexed
280 * @see SGRawValueContainer
283 class SGRawValue : public SGRawBase<T>
288 * The default underlying value for this type.
290 * Every raw value has a default; the default is false for a
291 * boolean, 0 for the various numeric values, and "" for a string.
292 * If additional types of raw values are added in the future, they
293 * may need different kinds of default values (such as epoch for a
294 * date type). The default value is used when creating new values.
296 static T DefaultValue()
305 * Use the default value for this type.
313 virtual ~SGRawValue () {}
317 * Return the underlying value.
319 * @return The actual value for the property.
322 virtual T getValue () const = 0;
326 * Assign a new underlying value.
328 * If the new value cannot be set (because this is a read-only
329 * raw value, or because the new value is not acceptable for
330 * some reason) this method returns false and leaves the original
333 * @param value The actual value for the property.
334 * @return true if the value was set successfully, false otherwise.
337 virtual bool setValue (T value) = 0;
341 * Return the type tag for this raw value type.
343 virtual simgear::props::Type getType() const
345 return simgear::props::PropertyTraits<T>::type_tag;
351 ////////////////////////////////////////////////////////////////////////
352 // Default values for every type.
353 ////////////////////////////////////////////////////////////////////////
355 template<> inline bool SGRawValue<bool>::DefaultValue()
360 template<> inline const char * SGRawValue<const char *>::DefaultValue()
366 * A raw value bound to a pointer.
368 * This is the most efficient way to tie an external value, but also
369 * the most dangerous, because there is no way for the supplier to
370 * perform bounds checking and derived calculations except by polling
371 * the variable to see if it has changed. There is no default
372 * constructor, because this class would be meaningless without a
376 class SGRawValuePointer : public SGRawValue<T>
381 * Explicit pointer constructor.
383 * Create a new raw value bound to the value of the variable
384 * referenced by the pointer.
386 * @param ptr The pointer to the variable to which this raw value
389 SGRawValuePointer (T * ptr) : _ptr(ptr) {}
394 virtual ~SGRawValuePointer () {}
397 * Get the underlying value.
399 * This method will dereference the pointer and return the
402 virtual T getValue () const { return *_ptr; }
405 * Set the underlying value.
407 * This method will dereference the pointer and change the
410 virtual bool setValue (T value) { *_ptr = value; return true; }
413 * Create a copy of this raw value.
415 * The copy will use the same external pointer as the original.
417 virtual SGRaw* clone () const {
418 return new SGRawValuePointer(_ptr);
427 * A value managed through static functions.
429 * A read-only value will not have a setter; a write-only value will
433 class SGRawValueFunctions : public SGRawValue<T>
438 * The template type of a static getter function.
440 typedef T (*getter_t)();
443 * The template type of a static setter function.
445 typedef void (*setter_t)(T);
448 * Explicit constructor.
450 * Create a new raw value bound to the getter and setter supplied.
452 * @param getter A static function for getting a value, or 0
453 * to read-disable the value.
454 * @param setter A static function for setting a value, or 0
455 * to write-disable the value.
457 SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
458 : _getter(getter), _setter(setter) {}
463 virtual ~SGRawValueFunctions () {}
466 * Get the underlying value.
468 * This method will invoke the getter function to get a value.
469 * If no getter function was supplied, this method will always
470 * return the default value for the type.
472 virtual T getValue () const {
473 if (_getter) return (*_getter)();
474 else return SGRawValue<T>::DefaultValue();
478 * Set the underlying value.
480 * This method will invoke the setter function to change the
481 * underlying value. If no setter function was supplied, this
482 * method will return false.
484 virtual bool setValue (T value) {
485 if (_setter) { (*_setter)(value); return true; }
490 * Create a copy of this raw value, bound to the same functions.
492 virtual SGRaw* clone () const {
493 return new SGRawValueFunctions(_getter,_setter);
503 * An indexed value bound to static functions.
505 * A read-only value will not have a setter; a write-only value will
506 * not have a getter. An indexed value is useful for binding one
507 * of a list of possible values (such as multiple engines for a
508 * plane). The index is hard-coded at creation time.
513 class SGRawValueFunctionsIndexed : public SGRawValue<T>
516 typedef T (*getter_t)(int);
517 typedef void (*setter_t)(int,T);
518 SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
519 : _index(index), _getter(getter), _setter(setter) {}
520 virtual ~SGRawValueFunctionsIndexed () {}
521 virtual T getValue () const {
522 if (_getter) return (*_getter)(_index);
523 else return SGRawValue<T>::DefaultValue();
525 virtual bool setValue (T value) {
526 if (_setter) { (*_setter)(_index, value); return true; }
529 virtual SGRaw* clone () const {
530 return new SGRawValueFunctionsIndexed(_index, _getter, _setter);
540 * A value managed through an object and access methods.
542 * A read-only value will not have a setter; a write-only value will
545 template <class C, class T>
546 class SGRawValueMethods : public SGRawValue<T>
549 typedef T (C::*getter_t)() const;
550 typedef void (C::*setter_t)(T);
551 SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
552 : _obj(obj), _getter(getter), _setter(setter) {}
553 virtual ~SGRawValueMethods () {}
554 virtual T getValue () const {
555 if (_getter) { return (_obj.*_getter)(); }
556 else { return SGRawValue<T>::DefaultValue(); }
558 virtual bool setValue (T value) {
559 if (_setter) { (_obj.*_setter)(value); return true; }
562 virtual SGRaw* clone () const {
563 return new SGRawValueMethods(_obj, _getter, _setter);
573 * An indexed 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 SGRawValueMethodsIndexed : public SGRawValue<T>
582 typedef T (C::*getter_t)(int) const;
583 typedef void (C::*setter_t)(int, T);
584 SGRawValueMethodsIndexed (C &obj, int index,
585 getter_t getter = 0, setter_t setter = 0)
586 : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
587 virtual ~SGRawValueMethodsIndexed () {}
588 virtual T getValue () const {
589 if (_getter) { return (_obj.*_getter)(_index); }
590 else { return SGRawValue<T>::DefaultValue(); }
592 virtual bool setValue (T value) {
593 if (_setter) { (_obj.*_setter)(_index, value); return true; }
596 virtual SGRaw* clone () const {
597 return new SGRawValueMethodsIndexed(_obj, _index, _getter, _setter);
607 * A raw value that contains its value. This provides a way for
608 * property nodes to contain values that shouldn't be stored in the
609 * property node itself.
612 class SGRawValueContainer : public SGRawValue<T>
617 * Explicit constructor.
619 SGRawValueContainer(const T& obj) : _obj(obj) {}
624 virtual ~SGRawValueContainer() {}
627 * Get the underlying value.
629 virtual T getValue() const { return _obj; }
632 * Set the underlying value.
634 * This method will dereference the pointer and change the
637 virtual bool setValue (T value) { _obj = value; return true; }
640 * Create a copy of this raw value.
642 virtual SGRaw* clone () const {
643 return new SGRawValueContainer(_obj);
651 SGRawExtended* SGRawBase<T, 0>::makeContainer() const
653 return new SGRawValueContainer<T>(static_cast<const SGRawValue<T>*>(this)
658 std::ostream& SGRawBase<T, 0>::printOn(std::ostream& stream) const
660 return stream << static_cast<SGRawValue<T>*>(this)->getValue();
664 std::istream& SGRawBase<T, 0>::readFrom(std::istream& stream)
667 simgear::readFrom(stream, value);
668 static_cast<SGRawValue<T>*>(this)->setValue(value);
674 * The smart pointer that manage reference counting
676 class SGPropertyNode;
677 typedef SGSharedPtr<SGPropertyNode> SGPropertyNode_ptr;
678 typedef SGSharedPtr<const SGPropertyNode> SGConstPropertyNode_ptr;
682 typedef std::vector<SGPropertyNode_ptr> PropertyList;
687 * The property change listener interface.
689 * <p>Any class that needs to listen for property changes must implement
690 * this interface.</p>
692 class SGPropertyChangeListener
695 virtual ~SGPropertyChangeListener ();
696 virtual void valueChanged (SGPropertyNode * node);
697 virtual void childAdded (SGPropertyNode * parent, SGPropertyNode * child);
698 virtual void childRemoved (SGPropertyNode * parent, SGPropertyNode * child);
701 friend class SGPropertyNode;
702 virtual void register_property (SGPropertyNode * node);
703 virtual void unregister_property (SGPropertyNode * node);
706 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 child node after the last node with the same name.
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 * Get a child node by name and index.
871 SGPropertyNode * getChild (const char* name, int index = 0,
872 bool create = false);
873 SGPropertyNode * getChild (const std::string& name, int index = 0,
874 bool create = false);
876 * Get a const child node by name and index.
878 const SGPropertyNode * getChild (const char * name, int index = 0) const;
881 * Get a const child node by name and index.
883 const SGPropertyNode * getChild (const std::string& name, int index = 0) const
884 { return getChild(name.c_str(), index); }
888 * Get a vector of all children with the specified name.
890 simgear::PropertyList getChildren (const char * name) const;
893 * Get a vector of all children with the specified name.
895 simgear::PropertyList getChildren (const std::string& name) const
896 { return getChildren(name.c_str()); }
899 * Remove child by position.
901 SGPropertyNode_ptr removeChild (int pos, bool keep = true);
905 * Remove a child node
907 SGPropertyNode_ptr removeChild (const char * name, int index = 0,
911 * Remove a child node
913 SGPropertyNode_ptr removeChild (const std::string& name, int index = 0,
915 { return removeChild(name.c_str(), index, keep); }
918 * Remove all children with the specified name.
920 simgear::PropertyList removeChildren (const char * name, bool keep = true);
923 * Remove all children with the specified name.
925 simgear::PropertyList removeChildren (const std::string& name,
927 { return removeChildren(name.c_str(), keep); }
935 * Alias this node's leaf value to another's.
937 bool alias (SGPropertyNode * target);
941 * Alias this node's leaf value to another's by relative path.
943 bool alias (const char * path);
946 * Alias this node's leaf value to another's by relative path.
948 bool alias (const std::string& path)
949 { return alias(path.c_str()); }
953 * Remove any alias for this node.
959 * Test whether the node's leaf value is aliased to another's.
961 bool isAlias () const { return (_type == simgear::props::ALIAS); }
965 * Get a non-const pointer to the current alias target, if any.
967 SGPropertyNode * getAliasTarget ();
971 * Get a const pointer to the current alias target, if any.
973 const SGPropertyNode * getAliasTarget () const;
982 * Get the path to this node from the root.
984 std::string getPath (bool simplify = false) const;
988 * Get a pointer to the root node.
990 SGPropertyNode * getRootNode ();
994 * Get a const pointer to the root node.
996 const SGPropertyNode * getRootNode () const;
1000 * Get a pointer to another node by relative path.
1002 SGPropertyNode * getNode (const char * relative_path, bool create = false);
1005 * Get a pointer to another node by relative path.
1007 SGPropertyNode * getNode (const std::string& relative_path, bool create = false)
1008 { return getNode(relative_path.c_str(), create); }
1011 * Get a pointer to another node by relative path.
1013 * This method leaves the index off the last member of the path,
1014 * so that the user can specify it separately (and save some
1015 * string building). For example, getNode("/bar[1]/foo", 3) is
1016 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
1017 * provided overrides any given in the path itself for the last
1020 SGPropertyNode * getNode (const char * relative_path, int index,
1021 bool create = false);
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 std::string& relative_path, int index,
1034 bool create = false)
1035 { return getNode(relative_path.c_str(), index, create); }
1038 * Get a const pointer to another node by relative path.
1040 const SGPropertyNode * getNode (const char * relative_path) const;
1043 * Get a const pointer to another node by relative path.
1045 const SGPropertyNode * getNode (const std::string& relative_path) const
1046 { return getNode(relative_path.c_str()); }
1050 * Get a const pointer to another node by relative path.
1052 * This method leaves the index off the last member of the path,
1053 * so that the user can specify it separate.
1055 const SGPropertyNode * getNode (const char * relative_path,
1059 * Get a const pointer to another node by relative path.
1061 * This method leaves the index off the last member of the path,
1062 * so that the user can specify it separate.
1064 const SGPropertyNode * getNode (const std::string& relative_path,
1066 { return getNode(relative_path.c_str(), index); }
1073 * Check a single mode attribute for the property node.
1075 bool getAttribute (Attribute attr) const { return ((_attr & attr) != 0); }
1079 * Set a single mode attribute for the property node.
1081 void setAttribute (Attribute attr, bool state) {
1082 (state ? _attr |= attr : _attr &= ~attr);
1087 * Get all of the mode attributes for the property node.
1089 int getAttributes () const { return _attr; }
1093 * Set all of the mode attributes for the property node.
1095 void setAttributes (int attr) { _attr = attr; }
1099 // Leaf Value (primitive).
1104 * Get the type of leaf value, if any, for this node.
1106 simgear::props::Type getType () const;
1110 * Get a bool value for this node.
1112 bool getBoolValue () const;
1116 * Get an int value for this node.
1118 int getIntValue () const;
1122 * Get a long int value for this node.
1124 long getLongValue () const;
1128 * Get a float value for this node.
1130 float getFloatValue () const;
1134 * Get a double value for this node.
1136 double getDoubleValue () const;
1140 * Get a string value for this node.
1142 const char * getStringValue () const;
1145 * Get a value from a node. If the actual type of the node doesn't
1146 * match the desired type, a conversion isn't guaranteed.
1148 template<typename T>
1149 T getValue(typename boost::enable_if_c<simgear::props::PropertyTraits<T>::Internal>
1150 ::type* dummy = 0) const;
1151 // Getter for extended property
1152 template<typename T>
1153 T getValue(typename boost::disable_if_c<simgear::props::PropertyTraits<T>::Internal>
1154 ::type* dummy = 0) const;
1157 * Set a bool value for this node.
1159 bool setBoolValue (bool value);
1163 * Set an int value for this node.
1165 bool setIntValue (int value);
1169 * Set a long int value for this node.
1171 bool setLongValue (long value);
1175 * Set a float value for this node.
1177 bool setFloatValue (float value);
1181 * Set a double value for this node.
1183 bool setDoubleValue (double value);
1187 * Set a string value for this node.
1189 bool setStringValue (const char * value);
1192 * Set a string value for this node.
1194 bool setStringValue (const std::string& value)
1195 { return setStringValue(value.c_str()); }
1199 * Set a value of unspecified type for this node.
1201 bool setUnspecifiedValue (const char * value);
1203 template<typename T>
1204 bool setValue(const T& val,
1205 typename boost::enable_if_c<simgear::props::PropertyTraits<T>::Internal>
1208 template<typename T>
1209 bool setValue(const T& val,
1210 typename boost::disable_if_c<simgear::props::PropertyTraits<T>::Internal>
1214 bool setValue(const char (&val)[N])
1216 return setValue(&val[0]);
1220 * Print the value of the property to a stream.
1222 std::ostream& printOn(std::ostream& stream) const;
1230 * Test whether this node is bound to an external data source.
1232 bool isTied () const { return _tied; }
1235 * Bind this node to an external source.
1237 template<typename T>
1238 bool tie(const SGRawValue<T> &rawValue, bool useDefault = true);
1241 * Unbind this node from any external data source.
1247 // Convenience methods using paths.
1248 // TODO: add attribute methods
1253 * Get another node's type.
1255 simgear::props::Type getType (const char * relative_path) const;
1258 * Get another node's type.
1260 simgear::props::Type getType (const std::string& relative_path) const
1261 { return getType(relative_path.c_str()); }
1264 * Test whether another node has a leaf value.
1266 bool hasValue (const char * relative_path) const;
1269 * Test whether another node has a leaf value.
1271 bool hasValue (const std::string& relative_path) const
1272 { return hasValue(relative_path.c_str()); }
1275 * Get another node's value as a bool.
1277 bool getBoolValue (const char * relative_path,
1278 bool defaultValue = false) const;
1281 * Get another node's value as a bool.
1283 bool getBoolValue (const std::string& relative_path,
1284 bool defaultValue = false) const
1285 { return getBoolValue(relative_path.c_str(), defaultValue); }
1288 * Get another node's value as an int.
1290 int getIntValue (const char * relative_path,
1291 int defaultValue = 0) const;
1294 * Get another node's value as an int.
1296 int getIntValue (const std::string& relative_path,
1297 int defaultValue = 0) const
1298 { return getIntValue(relative_path.c_str(), defaultValue); }
1302 * Get another node's value as a long int.
1304 long getLongValue (const char * relative_path,
1305 long defaultValue = 0L) const;
1308 * Get another node's value as a long int.
1310 long getLongValue (const std::string& relative_path,
1311 long defaultValue = 0L) const
1312 { return getLongValue(relative_path.c_str(), defaultValue); }
1315 * Get another node's value as a float.
1317 float getFloatValue (const char * relative_path,
1318 float defaultValue = 0.0f) const;
1321 * Get another node's value as a float.
1323 float getFloatValue (const std::string& relative_path,
1324 float defaultValue = 0.0f) const
1325 { return getFloatValue(relative_path.c_str(), defaultValue); }
1329 * Get another node's value as a double.
1331 double getDoubleValue (const char * relative_path,
1332 double defaultValue = 0.0) const;
1335 * Get another node's value as a double.
1337 double getDoubleValue (const std::string& relative_path,
1338 double defaultValue = 0.0) const
1339 { return getDoubleValue(relative_path.c_str(), defaultValue); }
1342 * Get another node's value as a string.
1344 const char * getStringValue (const char * relative_path,
1345 const char * defaultValue = "") const;
1349 * Get another node's value as a string.
1351 const char * getStringValue (const std::string& relative_path,
1352 const char * defaultValue = "") const
1353 { return getStringValue(relative_path.c_str(), defaultValue); }
1357 * Set another node's value as a bool.
1359 bool setBoolValue (const char * relative_path, bool value);
1362 * Set another node's value as a bool.
1364 bool setBoolValue (const std::string& relative_path, bool value)
1365 { return setBoolValue(relative_path.c_str(), value); }
1369 * Set another node's value as an int.
1371 bool setIntValue (const char * relative_path, int value);
1374 * Set another node's value as an int.
1376 bool setIntValue (const std::string& relative_path, int value)
1377 { return setIntValue(relative_path.c_str(), value); }
1381 * Set another node's value as a long int.
1383 bool setLongValue (const char * relative_path, long value);
1386 * Set another node's value as a long int.
1388 bool setLongValue (const std::string& relative_path, long value)
1389 { return setLongValue(relative_path.c_str(), value); }
1393 * Set another node's value as a float.
1395 bool setFloatValue (const char * relative_path, float value);
1398 * Set another node's value as a float.
1400 bool setFloatValue (const std::string& relative_path, float value)
1401 { return setFloatValue(relative_path.c_str(), value); }
1405 * Set another node's value as a double.
1407 bool setDoubleValue (const char * relative_path, double value);
1410 * Set another node's value as a double.
1412 bool setDoubleValue (const std::string& relative_path, double value)
1413 { return setDoubleValue(relative_path.c_str(), value); }
1417 * Set another node's value as a string.
1419 bool setStringValue (const char * relative_path, const char * value);
1421 bool setStringValue(const char * relative_path, const std::string& value)
1422 { return setStringValue(relative_path, value.c_str()); }
1424 * Set another node's value as a string.
1426 bool setStringValue (const std::string& relative_path, const char * value)
1427 { return setStringValue(relative_path.c_str(), value); }
1429 bool setStringValue (const std::string& relative_path,
1430 const std::string& value)
1431 { return setStringValue(relative_path.c_str(), value.c_str()); }
1434 * Set another node's value with no specified type.
1436 bool setUnspecifiedValue (const char * relative_path, const char * value);
1440 * Test whether another node is bound to an external data source.
1442 bool isTied (const char * relative_path) const;
1445 * Test whether another node is bound to an external data source.
1447 bool isTied (const std::string& relative_path) const
1448 { return isTied(relative_path.c_str()); }
1451 * Bind another node to an external bool source.
1453 bool tie (const char * relative_path, const SGRawValue<bool> &rawValue,
1454 bool useDefault = true);
1457 * Bind another node to an external bool source.
1459 bool tie (const std::string& relative_path, const SGRawValue<bool> &rawValue,
1460 bool useDefault = true)
1461 { return tie(relative_path.c_str(), rawValue, useDefault); }
1465 * Bind another node to an external int source.
1467 bool tie (const char * relative_path, const SGRawValue<int> &rawValue,
1468 bool useDefault = true);
1471 * Bind another node to an external int source.
1473 bool tie (const std::string& relative_path, const SGRawValue<int> &rawValue,
1474 bool useDefault = true)
1475 { return tie(relative_path.c_str(), rawValue, useDefault); }
1479 * Bind another node to an external long int source.
1481 bool tie (const char * relative_path, const SGRawValue<long> &rawValue,
1482 bool useDefault = true);
1485 * Bind another node to an external long int source.
1487 bool tie (const std::string& relative_path, const SGRawValue<long> &rawValue,
1488 bool useDefault = true)
1489 { return tie(relative_path.c_str(), rawValue, useDefault); }
1493 * Bind another node to an external float source.
1495 bool tie (const char * relative_path, const SGRawValue<float> &rawValue,
1496 bool useDefault = true);
1499 * Bind another node to an external float source.
1501 bool tie (const std::string& relative_path, const SGRawValue<float> &rawValue,
1502 bool useDefault = true)
1503 { return tie(relative_path.c_str(), rawValue, useDefault); }
1507 * Bind another node to an external double source.
1509 bool tie (const char * relative_path, const SGRawValue<double> &rawValue,
1510 bool useDefault = true);
1513 * Bind another node to an external double source.
1515 bool tie (const std::string& relative_path, const SGRawValue<double> &rawValue,
1516 bool useDefault = true)
1517 { return tie(relative_path.c_str(), rawValue, useDefault); }
1521 * Bind another node to an external string source.
1523 bool tie (const char * relative_path, const SGRawValue<const char *> &rawValue,
1524 bool useDefault = true);
1527 * Bind another node to an external string source.
1529 bool tie (const std::string& relative_path, const SGRawValue<const char*> &rawValue,
1530 bool useDefault = true)
1531 { return tie(relative_path.c_str(), rawValue, useDefault); }
1535 * Unbind another node from any external data source.
1537 bool untie (const char * relative_path);
1540 * Unbind another node from any external data source.
1542 bool untie (const std::string& relative_path)
1543 { return untie(relative_path.c_str()); }
1547 * Add a change listener to the property. If "initial" is set call the
1548 * listener initially.
1550 void addChangeListener (SGPropertyChangeListener * listener,
1551 bool initial = false);
1555 * Remove a change listener from the property.
1557 void removeChangeListener (SGPropertyChangeListener * listener);
1561 * Get the number of listeners.
1563 int nListeners () const { return _listeners ? (int)_listeners->size() : 0; }
1567 * Fire a value change event to all listeners.
1569 void fireValueChanged ();
1573 * Fire a child-added event to all listeners.
1575 void fireChildAdded (SGPropertyNode * child);
1579 * Fire a child-removed event to all listeners.
1581 void fireChildRemoved (SGPropertyNode * child);
1585 * Clear any existing value and set the type to NONE.
1590 * Compare two property trees. The property trees are equal if: 1)
1591 * They have no children, and have the same type and the values are
1592 * equal, or 2) have the same number of children, and the
1593 * corresponding children in each tree are equal. "corresponding"
1594 * means have the same name and index.
1596 * Attributes, removed children, and aliases aren't considered.
1598 static bool compare (const SGPropertyNode& lhs, const SGPropertyNode& rhs);
1602 void fireValueChanged (SGPropertyNode * node);
1603 void fireChildAdded (SGPropertyNode * parent, SGPropertyNode * child);
1604 void fireChildRemoved (SGPropertyNode * parent, SGPropertyNode * child);
1607 * Protected constructor for making new nodes on demand.
1609 SGPropertyNode (const std::string& name, int index, SGPropertyNode * parent);
1610 template<typename Itr>
1611 SGPropertyNode (Itr begin, Itr end, int index, SGPropertyNode * parent);
1615 // Get the raw value
1616 bool get_bool () const;
1617 int get_int () const;
1618 long get_long () const;
1619 float get_float () const;
1620 double get_double () const;
1621 const char * get_string () const;
1623 // Set the raw value
1624 bool set_bool (bool value);
1625 bool set_int (int value);
1626 bool set_long (long value);
1627 bool set_float (float value);
1628 bool set_double (double value);
1629 bool set_string (const char * value);
1633 * Get the value as a string.
1635 const char * make_string () const;
1638 * Trace a read access.
1640 void trace_read () const;
1644 * Trace a write access.
1646 void trace_write () const;
1650 /// To avoid cyclic reference counting loops this shall not be a reference
1652 SGPropertyNode * _parent;
1653 simgear::PropertyList _children;
1654 simgear::PropertyList _removedChildren;
1655 mutable std::string _buffer;
1656 simgear::props::Type _type;
1660 // The right kind of pointer...
1662 SGPropertyNode * alias;
1675 std::vector<SGPropertyChangeListener *> * _listeners;
1678 // Pass name as a pair of iterators
1679 template<typename Itr>
1680 SGPropertyNode * getChildImpl (Itr begin, Itr end, int index = 0, bool create = false);
1681 // very internal method
1682 template<typename Itr>
1683 SGPropertyNode* getExistingChild (Itr begin, Itr end, int index, bool create);
1684 // very internal path parsing function
1685 template<typename SplitItr>
1686 friend SGPropertyNode* find_node_aux(SGPropertyNode * current, SplitItr& itr,
1687 bool create, int last_index);
1689 friend size_t hash_value(const SGPropertyNode& node);
1692 // Convenience functions for use in templates
1693 template<typename T>
1694 T getValue(const SGPropertyNode*);
1697 inline bool getValue<bool>(const SGPropertyNode* node) { return node->getBoolValue(); }
1700 inline int getValue<int>(const SGPropertyNode* node) { return node->getIntValue(); }
1703 inline long getValue<long>(const SGPropertyNode* node) { return node->getLongValue(); }
1706 inline float getValue<float>(const SGPropertyNode* node)
1708 return node->getFloatValue();
1712 inline double getValue<double>(const SGPropertyNode* node)
1714 return node->getDoubleValue();
1718 inline const char * getValue<const char*>(const SGPropertyNode* node)
1720 return node->getStringValue ();
1723 inline bool setValue(SGPropertyNode* node, bool value)
1725 return node->setBoolValue(value);
1728 inline bool setValue(SGPropertyNode* node, int value)
1730 return node->setIntValue(value);
1733 inline bool setValue(SGPropertyNode* node, long value)
1735 return node->setLongValue(value);
1738 inline bool setValue(SGPropertyNode* node, float value)
1740 return node->setFloatValue(value);
1743 inline bool setValue(SGPropertyNode* node, double value)
1745 return node->setDoubleValue(value);
1748 inline bool setValue(SGPropertyNode* node, const char* value)
1750 return node->setStringValue(value);
1753 inline bool setValue (SGPropertyNode* node, const std::string& value)
1755 return node->setStringValue(value.c_str());
1758 template<typename T>
1759 bool SGPropertyNode::tie(const SGRawValue<T> &rawValue, bool useDefault)
1761 using namespace simgear::props;
1762 if (_type == ALIAS || _tied)
1765 useDefault = useDefault && hasValue();
1766 T old_val = SGRawValue<T>::DefaultValue();
1768 old_val = getValue<T>(this);
1770 if (PropertyTraits<T>::Internal)
1771 _type = PropertyTraits<T>::type_tag;
1775 _value.val = rawValue.clone();
1777 int save_attributes = getAttributes();
1778 setAttribute( WRITE, true );
1780 setAttributes( save_attributes );
1786 bool SGPropertyNode::tie (const SGRawValue<const char *> &rawValue,
1789 template<typename T>
1790 T SGPropertyNode::getValue(typename boost::disable_if_c<simgear::props
1791 ::PropertyTraits<T>::Internal>::type* dummy) const
1793 using namespace simgear::props;
1794 if (_attr == (READ|WRITE) && _type == EXTENDED
1795 && _value.val->getType() == PropertyTraits<T>::type_tag) {
1796 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
1798 if (getAttribute(TRACE_READ))
1800 if (!getAttribute(READ))
1801 return SGRawValue<T>::DefaultValue();
1804 if (_value.val->getType() == PropertyTraits<T>::type_tag)
1805 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
1809 return simgear::parseString<T>(make_string());
1811 default: // avoid compiler warning
1814 return SGRawValue<T>::DefaultValue();
1817 template<typename T>
1818 inline T SGPropertyNode::getValue(typename boost::enable_if_c<simgear::props
1819 ::PropertyTraits<T>::Internal>::type* dummy) const
1821 return ::getValue<T>(this);
1824 template<typename T>
1825 bool SGPropertyNode::setValue(const T& val,
1826 typename boost::disable_if_c<simgear::props
1827 ::PropertyTraits<T>::Internal>::type* dummy)
1829 using namespace simgear::props;
1830 if (_attr == (READ|WRITE) && _type == EXTENDED
1831 && _value.val->getType() == PropertyTraits<T>::type_tag) {
1832 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
1835 if (getAttribute(WRITE)
1836 && ((_type == EXTENDED
1837 && _value.val->getType() == PropertyTraits<T>::type_tag)
1838 || _type == NONE || _type == UNSPECIFIED)) {
1839 if (_type == NONE || _type == UNSPECIFIED) {
1842 _value.val = new SGRawValueContainer<T>(val);
1844 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
1846 if (getAttribute(TRACE_WRITE))
1853 template<typename T>
1854 inline bool SGPropertyNode::setValue(const T& val,
1855 typename boost::enable_if_c<simgear::props
1856 ::PropertyTraits<T>::Internal>::type* dummy)
1858 return ::setValue(this, val);
1862 * Utility function for creation of a child property node.
1864 inline SGPropertyNode* makeChild(SGPropertyNode* parent, const char* name,
1867 return parent->getChild(name, index, true);
1871 * Utility function for creation of a child property node using a
1876 template<typename StringType>
1877 inline SGPropertyNode* makeNode(SGPropertyNode* parent, const StringType& name)
1879 return parent->getNode(name, true);
1884 size_t hash_value(const SGPropertyNode& node);
1886 // Helper comparison and hash functions for common cases
1894 bool operator()(const SGPropertyNode* lhs, const SGPropertyNode* rhs) const
1896 return SGPropertyNode::compare(*lhs, *rhs);
1898 bool operator()(SGPropertyNode_ptr lhs, const SGPropertyNode* rhs) const
1900 return SGPropertyNode::compare(*lhs, *rhs);
1902 bool operator()(const SGPropertyNode* lhs, SGPropertyNode_ptr rhs) const
1904 return SGPropertyNode::compare(*lhs, *rhs);
1906 bool operator()(SGPropertyNode_ptr lhs, SGPropertyNode_ptr rhs) const
1908 return SGPropertyNode::compare(*lhs, *rhs);
1914 size_t operator()(const SGPropertyNode* node) const
1916 return hash_value(*node);
1918 size_t operator()(SGPropertyNode_ptr node) const
1920 return hash_value(*node);
1926 /** Convenience class for change listener callbacks without
1927 * creating a derived class implementing a "valueChanged" method.
1928 * Also removes listener on destruction automatically.
1931 class SGPropertyChangeCallback
1932 : public SGPropertyChangeListener
1935 SGPropertyChangeCallback(T* obj, void (T::*method)(SGPropertyNode*),
1936 SGPropertyNode_ptr property,bool initial=false)
1937 : _obj(obj), _callback(method), _property(property)
1939 _property->addChangeListener(this,initial);
1941 virtual ~SGPropertyChangeCallback()
1943 _property->removeChangeListener(this);
1945 void valueChanged (SGPropertyNode * node)
1947 (_obj->*_callback)(node);
1951 void (T::*_callback)(SGPropertyNode*);
1952 SGPropertyNode_ptr _property;
1955 #endif // __PROPS_HXX