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);
66 // Extended properties
68 std::istream& readFrom<SGVec3d>(std::istream& stream, SGVec3d& result);
70 std::istream& readFrom<SGVec4d>(std::istream& stream, SGVec4d& result);
74 * Property value types.
78 #pragma warn A sloppy coder has defined NONE as a macro!
83 #pragma warn A sloppy coder has defined ALIAS as a macro!
88 #pragma warn A sloppy coder has defined UNSPECIFIED as a macro!
93 #pragma warn A sloppy coder has defined BOOL as a macro!
98 #pragma warn A sloppy coder has defined INT as a macro!
103 #pragma warn A sloppy coder has defined LONG as a macro!
108 #pragma warn A sloppy coder has defined FLOAT as a macro!
113 #pragma warn A sloppy coder has defined DOUBLE as a macro!
118 #pragma warn A sloppy coder has defined STRING as a macro!
125 * The possible types of an SGPropertyNode. Types that appear after
126 * EXTENDED are not stored in the SGPropertyNode itself.
129 NONE = 0, /**< The node hasn't been assigned a value yet. */
130 ALIAS, /**< The node "points" to another node. */
138 EXTENDED, /**< The node's value is not stored in the property;
139 * the actual value and type is retrieved from an
140 * SGRawValue node. This type is never returned by @see
141 * SGPropertyNode::getType.
143 // Extended properties
148 template<typename T> struct PropertyTraits;
150 #define DEFINTERNALPROP(TYPE, PROP) \
152 struct PropertyTraits<TYPE> \
154 static const Type type_tag = PROP; \
155 enum { Internal = 1 }; \
158 DEFINTERNALPROP(bool, BOOL);
159 DEFINTERNALPROP(int, INT);
160 DEFINTERNALPROP(long, LONG);
161 DEFINTERNALPROP(float, FLOAT);
162 DEFINTERNALPROP(double, DOUBLE);
163 DEFINTERNALPROP(const char *, STRING);
164 DEFINTERNALPROP(const char[], STRING);
165 #undef DEFINTERNALPROP
168 struct PropertyTraits<SGVec3d>
170 static const Type type_tag = VEC3D;
171 enum { Internal = 0 };
175 struct PropertyTraits<SGVec4d>
177 static const Type type_tag = VEC4D;
178 enum { Internal = 0 };
186 ////////////////////////////////////////////////////////////////////////
189 // This is the mechanism that information-providing routines can
190 // use to link their own values to the property manager. Any
191 // SGValue can be tied to a raw value and then untied again.
193 // Note: we are forced to use inlined methods here to ensure
194 // that the templates will be instantiated. We're probably taking
195 // a small performance hit for that.
196 ////////////////////////////////////////////////////////////////////////
199 * Base class for SGRawValue classes that holds no type
200 * information. This allows some generic manipulation of the
207 * Get the type enumeration for the raw value.
211 virtual simgear::props::Type getType() const = 0;
215 * Create a new deep copy of this raw value.
217 * The copy will contain its own version of the underlying value
218 * as well, and will be the same type.
220 * @return A deep copy of the current object.
222 virtual SGRaw* clone() const = 0;
226 class SGRawExtended : public SGRaw
230 * Make an SGRawValueContainer from the SGRawValue.
232 * This is a virtual function of SGRawExtended so that
233 * SGPropertyNode::untie doesn't need to know the type of an
236 virtual SGRawExtended* makeContainer() const = 0;
238 * Write value out to a stream
240 virtual std::ostream& printOn(std::ostream& stream) const = 0;
242 * Read value from a stream and store it.
244 virtual std::istream& readFrom(std::istream& stream) = 0;
247 // Choose between different base classes based on whether the value is
248 // stored internal to the property node. This frees us from defining
249 // the virtual functions in the SGRawExtended interface where they
250 // don't make sense, e.g. readFrom for the const char* type.
251 template<typename T, int internal = simgear::props::PropertyTraits<T>::Internal>
255 class SGRawBase<T, 1> : public SGRaw
260 class SGRawBase<T, 0> : public SGRawExtended
262 virtual SGRawExtended* makeContainer() const;
263 virtual std::ostream& printOn(std::ostream& stream) const;
264 virtual std::istream& readFrom(std::istream& stream);
268 * Abstract base class for a raw value.
270 * <p>The property manager is implemented in two layers. The {@link
271 * SGPropertyNode} is the highest and most abstract layer,
272 * representing an LValue/RValue pair: it records the position of the
273 * property in the property tree and contains facilities for
274 * navigation to other nodes. It is guaranteed to be persistent: the
275 * {@link SGPropertyNode} will not change during a session, even if
276 * the property is bound and unbound multiple times.</p>
278 * <p>When the property value is not managed internally in the
279 * SGPropertyNode, the SGPropertyNode will contain a reference to an
280 * SGRawValue (this class), which provides an abstract way to get,
281 * set, and clone the underlying value. The SGRawValue may change
282 * frequently during a session as a value is retyped or bound and
283 * unbound to various data source, but the abstract SGPropertyNode
284 * layer insulates the application from those changes.
286 * <p>The SGPropertyNode class always keeps a *copy* of a raw value,
287 * not the original one passed to it; if you override a derived class
288 * but do not replace the {@link #clone} method, strange things will
291 * <p>All derived SGRawValue classes must implement {@link #getValue},
292 * {@link #setValue}, and {@link #clone} for the appropriate type.</p>
294 * @see SGPropertyNode
295 * @see SGRawValuePointer
296 * @see SGRawValueFunctions
297 * @see SGRawValueFunctionsIndexed
298 * @see SGRawValueMethods
299 * @see SGRawValueMethodsIndexed
300 * @see SGRawValueContainer
303 class SGRawValue : public SGRawBase<T>
308 * The default underlying value for this type.
310 * Every raw value has a default; the default is false for a
311 * boolean, 0 for the various numeric values, and "" for a string.
312 * If additional types of raw values are added in the future, they
313 * may need different kinds of default values (such as epoch for a
314 * date type). The default value is used when creating new values.
316 static T DefaultValue()
325 * Use the default value for this type.
333 virtual ~SGRawValue () {}
337 * Return the underlying value.
339 * @return The actual value for the property.
342 virtual T getValue () const = 0;
346 * Assign a new underlying value.
348 * If the new value cannot be set (because this is a read-only
349 * raw value, or because the new value is not acceptable for
350 * some reason) this method returns false and leaves the original
353 * @param value The actual value for the property.
354 * @return true if the value was set successfully, false otherwise.
357 virtual bool setValue (T value) = 0;
361 * Return the type tag for this raw value type.
363 virtual simgear::props::Type getType() const
365 return simgear::props::PropertyTraits<T>::type_tag;
371 ////////////////////////////////////////////////////////////////////////
372 // Default values for every type.
373 ////////////////////////////////////////////////////////////////////////
375 template<> inline bool SGRawValue<bool>::DefaultValue()
380 template<> inline const char * SGRawValue<const char *>::DefaultValue()
386 * A raw value bound to a pointer.
388 * This is the most efficient way to tie an external value, but also
389 * the most dangerous, because there is no way for the supplier to
390 * perform bounds checking and derived calculations except by polling
391 * the variable to see if it has changed. There is no default
392 * constructor, because this class would be meaningless without a
396 class SGRawValuePointer : public SGRawValue<T>
401 * Explicit pointer constructor.
403 * Create a new raw value bound to the value of the variable
404 * referenced by the pointer.
406 * @param ptr The pointer to the variable to which this raw value
409 SGRawValuePointer (T * ptr) : _ptr(ptr) {}
414 virtual ~SGRawValuePointer () {}
417 * Get the underlying value.
419 * This method will dereference the pointer and return the
422 virtual T getValue () const { return *_ptr; }
425 * Set the underlying value.
427 * This method will dereference the pointer and change the
430 virtual bool setValue (T value) { *_ptr = value; return true; }
433 * Create a copy of this raw value.
435 * The copy will use the same external pointer as the original.
437 virtual SGRaw* clone () const {
438 return new SGRawValuePointer(_ptr);
447 * A value managed through static functions.
449 * A read-only value will not have a setter; a write-only value will
453 class SGRawValueFunctions : public SGRawValue<T>
458 * The template type of a static getter function.
460 typedef T (*getter_t)();
463 * The template type of a static setter function.
465 typedef void (*setter_t)(T);
468 * Explicit constructor.
470 * Create a new raw value bound to the getter and setter supplied.
472 * @param getter A static function for getting a value, or 0
473 * to read-disable the value.
474 * @param setter A static function for setting a value, or 0
475 * to write-disable the value.
477 SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
478 : _getter(getter), _setter(setter) {}
483 virtual ~SGRawValueFunctions () {}
486 * Get the underlying value.
488 * This method will invoke the getter function to get a value.
489 * If no getter function was supplied, this method will always
490 * return the default value for the type.
492 virtual T getValue () const {
493 if (_getter) return (*_getter)();
494 else return SGRawValue<T>::DefaultValue();
498 * Set the underlying value.
500 * This method will invoke the setter function to change the
501 * underlying value. If no setter function was supplied, this
502 * method will return false.
504 virtual bool setValue (T value) {
505 if (_setter) { (*_setter)(value); return true; }
510 * Create a copy of this raw value, bound to the same functions.
512 virtual SGRaw* clone () const {
513 return new SGRawValueFunctions(_getter,_setter);
523 * An indexed value bound to static functions.
525 * A read-only value will not have a setter; a write-only value will
526 * not have a getter. An indexed value is useful for binding one
527 * of a list of possible values (such as multiple engines for a
528 * plane). The index is hard-coded at creation time.
533 class SGRawValueFunctionsIndexed : public SGRawValue<T>
536 typedef T (*getter_t)(int);
537 typedef void (*setter_t)(int,T);
538 SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
539 : _index(index), _getter(getter), _setter(setter) {}
540 virtual ~SGRawValueFunctionsIndexed () {}
541 virtual T getValue () const {
542 if (_getter) return (*_getter)(_index);
543 else return SGRawValue<T>::DefaultValue();
545 virtual bool setValue (T value) {
546 if (_setter) { (*_setter)(_index, value); return true; }
549 virtual SGRaw* clone () const {
550 return new SGRawValueFunctionsIndexed(_index, _getter, _setter);
560 * A value managed through an object and access methods.
562 * A read-only value will not have a setter; a write-only value will
565 template <class C, class T>
566 class SGRawValueMethods : public SGRawValue<T>
569 typedef T (C::*getter_t)() const;
570 typedef void (C::*setter_t)(T);
571 SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
572 : _obj(obj), _getter(getter), _setter(setter) {}
573 virtual ~SGRawValueMethods () {}
574 virtual T getValue () const {
575 if (_getter) { return (_obj.*_getter)(); }
576 else { return SGRawValue<T>::DefaultValue(); }
578 virtual bool setValue (T value) {
579 if (_setter) { (_obj.*_setter)(value); return true; }
582 virtual SGRaw* clone () const {
583 return new SGRawValueMethods(_obj, _getter, _setter);
593 * An indexed value managed through an object and access methods.
595 * A read-only value will not have a setter; a write-only value will
598 template <class C, class T>
599 class SGRawValueMethodsIndexed : public SGRawValue<T>
602 typedef T (C::*getter_t)(int) const;
603 typedef void (C::*setter_t)(int, T);
604 SGRawValueMethodsIndexed (C &obj, int index,
605 getter_t getter = 0, setter_t setter = 0)
606 : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
607 virtual ~SGRawValueMethodsIndexed () {}
608 virtual T getValue () const {
609 if (_getter) { return (_obj.*_getter)(_index); }
610 else { return SGRawValue<T>::DefaultValue(); }
612 virtual bool setValue (T value) {
613 if (_setter) { (_obj.*_setter)(_index, value); return true; }
616 virtual SGRaw* clone () const {
617 return new SGRawValueMethodsIndexed(_obj, _index, _getter, _setter);
627 * A raw value that contains its value. This provides a way for
628 * property nodes to contain values that shouldn't be stored in the
629 * property node itself.
632 class SGRawValueContainer : public SGRawValue<T>
637 * Explicit constructor.
639 SGRawValueContainer(const T& obj) : _obj(obj) {}
644 virtual ~SGRawValueContainer() {}
647 * Get the underlying value.
649 virtual T getValue() const { return _obj; }
652 * Set the underlying value.
654 * This method will dereference the pointer and change the
657 virtual bool setValue (T value) { _obj = value; return true; }
660 * Create a copy of this raw value.
662 virtual SGRaw* clone () const {
663 return new SGRawValueContainer(_obj);
671 SGRawExtended* SGRawBase<T, 0>::makeContainer() const
673 return new SGRawValueContainer<T>(static_cast<const SGRawValue<T>*>(this)
678 std::ostream& SGRawBase<T, 0>::printOn(std::ostream& stream) const
680 return stream << static_cast<SGRawValue<T>*>(this)->getValue();
684 std::istream& SGRawBase<T, 0>::readFrom(std::istream& stream)
687 simgear::readFrom(stream, value);
688 static_cast<SGRawValue<T>*>(this)->setValue(value);
693 std::ostream& SGRawBase<SGVec3d>::printOn(std::ostream& stream) const;
695 std::ostream& SGRawBase<SGVec4d>::printOn(std::ostream& stream) const;
699 * The smart pointer that manage reference counting
701 class SGPropertyNode;
702 typedef SGSharedPtr<SGPropertyNode> SGPropertyNode_ptr;
703 typedef SGSharedPtr<const SGPropertyNode> SGConstPropertyNode_ptr;
707 typedef std::vector<SGPropertyNode_ptr> PropertyList;
712 * The property change listener interface.
714 * <p>Any class that needs to listen for property changes must implement
715 * this interface.</p>
717 class SGPropertyChangeListener
720 virtual ~SGPropertyChangeListener ();
721 virtual void valueChanged (SGPropertyNode * node);
722 virtual void childAdded (SGPropertyNode * parent, SGPropertyNode * child);
723 virtual void childRemoved (SGPropertyNode * parent, SGPropertyNode * child);
726 friend class SGPropertyNode;
727 virtual void register_property (SGPropertyNode * node);
728 virtual void unregister_property (SGPropertyNode * node);
731 std::vector<SGPropertyNode *> _properties;
737 * A node in a property tree.
739 class SGPropertyNode : public SGReferenced
747 MAX_STRING_LEN = 1024
751 * Access mode attributes.
753 * <p>The ARCHIVE attribute is strictly advisory, and controls
754 * whether the property should normally be saved and restored.</p>
768 * Last used attribute
769 * Update as needed when enum Attribute is changed
771 static const int LAST_USED_ATTRIBUTE;
775 * Default constructor.
783 SGPropertyNode (const SGPropertyNode &node);
789 virtual ~SGPropertyNode ();
798 * Test whether this node contains a primitive leaf value.
800 bool hasValue () const { return (_type != simgear::props::NONE); }
804 * Get the node's simple (XML) name.
806 const char * getName () const { return _name.c_str(); }
809 * Get the node's simple name as a string.
811 const std::string& getNameString () const { return _name; }
814 * Get the node's pretty display name, with subscript when needed.
816 std::string getDisplayName (bool simplify = false) const;
820 * Get the node's integer index.
822 int getIndex () const { return _index; }
826 * Get a non-const pointer to the node's parent.
828 SGPropertyNode * getParent () { return _parent; }
832 * Get a const pointer to the node's parent.
834 const SGPropertyNode * getParent () const { return _parent; }
843 * Get the number of child nodes.
845 int nChildren () const { return (int)_children.size(); }
849 * Get a child node by position (*NOT* index).
851 SGPropertyNode * getChild (int position);
855 * Get a const child node by position (*NOT* index).
857 const SGPropertyNode * getChild (int position) const;
861 * Test whether a named child exists.
863 bool hasChild (const char * name, int index = 0) const
865 return (getChild(name, index) != 0);
869 * Test whether a named child exists.
871 bool hasChild (const std::string& name, int index = 0) const
873 return (getChild(name, index) != 0);
877 * Create a child node after the last node with the same name.
879 SGPropertyNode * addChild (const char * name);
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 * Set a bool value for this node.
1172 bool setBoolValue (bool value);
1176 * Set an int value for this node.
1178 bool setIntValue (int value);
1182 * Set a long int value for this node.
1184 bool setLongValue (long value);
1188 * Set a float value for this node.
1190 bool setFloatValue (float value);
1194 * Set a double value for this node.
1196 bool setDoubleValue (double value);
1200 * Set a string value for this node.
1202 bool setStringValue (const char * value);
1205 * Set a string value for this node.
1207 bool setStringValue (const std::string& value)
1208 { return setStringValue(value.c_str()); }
1212 * Set a value of unspecified type for this node.
1214 bool setUnspecifiedValue (const char * value);
1216 template<typename T>
1217 bool setValue(const T& val,
1218 typename boost::enable_if_c<simgear::props::PropertyTraits<T>::Internal>
1221 template<typename T>
1222 bool setValue(const T& val,
1223 typename boost::disable_if_c<simgear::props::PropertyTraits<T>::Internal>
1227 bool setValue(const char (&val)[N])
1229 return setValue(&val[0]);
1233 * Print the value of the property to a stream.
1235 std::ostream& printOn(std::ostream& stream) const;
1243 * Test whether this node is bound to an external data source.
1245 bool isTied () const { return _tied; }
1248 * Bind this node to an external source.
1250 template<typename T>
1251 bool tie(const SGRawValue<T> &rawValue, bool useDefault = true);
1254 * Unbind this node from any external data source.
1260 // Convenience methods using paths.
1261 // TODO: add attribute methods
1266 * Get another node's type.
1268 simgear::props::Type getType (const char * relative_path) const;
1271 * Get another node's type.
1273 simgear::props::Type getType (const std::string& relative_path) const
1274 { return getType(relative_path.c_str()); }
1277 * Test whether another node has a leaf value.
1279 bool hasValue (const char * relative_path) const;
1282 * Test whether another node has a leaf value.
1284 bool hasValue (const std::string& relative_path) const
1285 { return hasValue(relative_path.c_str()); }
1288 * Get another node's value as a bool.
1290 bool getBoolValue (const char * relative_path,
1291 bool defaultValue = false) const;
1294 * Get another node's value as a bool.
1296 bool getBoolValue (const std::string& relative_path,
1297 bool defaultValue = false) const
1298 { return getBoolValue(relative_path.c_str(), defaultValue); }
1301 * Get another node's value as an int.
1303 int getIntValue (const char * relative_path,
1304 int defaultValue = 0) const;
1307 * Get another node's value as an int.
1309 int getIntValue (const std::string& relative_path,
1310 int defaultValue = 0) const
1311 { return getIntValue(relative_path.c_str(), defaultValue); }
1315 * Get another node's value as a long int.
1317 long getLongValue (const char * relative_path,
1318 long defaultValue = 0L) const;
1321 * Get another node's value as a long int.
1323 long getLongValue (const std::string& relative_path,
1324 long defaultValue = 0L) const
1325 { return getLongValue(relative_path.c_str(), defaultValue); }
1328 * Get another node's value as a float.
1330 float getFloatValue (const char * relative_path,
1331 float defaultValue = 0.0f) const;
1334 * Get another node's value as a float.
1336 float getFloatValue (const std::string& relative_path,
1337 float defaultValue = 0.0f) const
1338 { return getFloatValue(relative_path.c_str(), defaultValue); }
1342 * Get another node's value as a double.
1344 double getDoubleValue (const char * relative_path,
1345 double defaultValue = 0.0) const;
1348 * Get another node's value as a double.
1350 double getDoubleValue (const std::string& relative_path,
1351 double defaultValue = 0.0) const
1352 { return getDoubleValue(relative_path.c_str(), defaultValue); }
1355 * Get another node's value as a string.
1357 const char * getStringValue (const char * relative_path,
1358 const char * defaultValue = "") const;
1362 * Get another node's value as a string.
1364 const char * getStringValue (const std::string& relative_path,
1365 const char * defaultValue = "") const
1366 { return getStringValue(relative_path.c_str(), defaultValue); }
1370 * Set another node's value as a bool.
1372 bool setBoolValue (const char * relative_path, bool value);
1375 * Set another node's value as a bool.
1377 bool setBoolValue (const std::string& relative_path, bool value)
1378 { return setBoolValue(relative_path.c_str(), value); }
1382 * Set another node's value as an int.
1384 bool setIntValue (const char * relative_path, int value);
1387 * Set another node's value as an int.
1389 bool setIntValue (const std::string& relative_path, int value)
1390 { return setIntValue(relative_path.c_str(), value); }
1394 * Set another node's value as a long int.
1396 bool setLongValue (const char * relative_path, long value);
1399 * Set another node's value as a long int.
1401 bool setLongValue (const std::string& relative_path, long value)
1402 { return setLongValue(relative_path.c_str(), value); }
1406 * Set another node's value as a float.
1408 bool setFloatValue (const char * relative_path, float value);
1411 * Set another node's value as a float.
1413 bool setFloatValue (const std::string& relative_path, float value)
1414 { return setFloatValue(relative_path.c_str(), value); }
1418 * Set another node's value as a double.
1420 bool setDoubleValue (const char * relative_path, double value);
1423 * Set another node's value as a double.
1425 bool setDoubleValue (const std::string& relative_path, double value)
1426 { return setDoubleValue(relative_path.c_str(), value); }
1430 * Set another node's value as a string.
1432 bool setStringValue (const char * relative_path, const char * value);
1434 bool setStringValue(const char * relative_path, const std::string& value)
1435 { return setStringValue(relative_path, value.c_str()); }
1437 * Set another node's value as a string.
1439 bool setStringValue (const std::string& relative_path, const char * value)
1440 { return setStringValue(relative_path.c_str(), value); }
1442 bool setStringValue (const std::string& relative_path,
1443 const std::string& value)
1444 { return setStringValue(relative_path.c_str(), value.c_str()); }
1447 * Set another node's value with no specified type.
1449 bool setUnspecifiedValue (const char * relative_path, const char * value);
1453 * Test whether another node is bound to an external data source.
1455 bool isTied (const char * relative_path) const;
1458 * Test whether another node is bound to an external data source.
1460 bool isTied (const std::string& relative_path) const
1461 { return isTied(relative_path.c_str()); }
1464 * Bind another node to an external bool source.
1466 bool tie (const char * relative_path, const SGRawValue<bool> &rawValue,
1467 bool useDefault = true);
1470 * Bind another node to an external bool source.
1472 bool tie (const std::string& relative_path, const SGRawValue<bool> &rawValue,
1473 bool useDefault = true)
1474 { return tie(relative_path.c_str(), rawValue, useDefault); }
1478 * Bind another node to an external int source.
1480 bool tie (const char * relative_path, const SGRawValue<int> &rawValue,
1481 bool useDefault = true);
1484 * Bind another node to an external int source.
1486 bool tie (const std::string& relative_path, const SGRawValue<int> &rawValue,
1487 bool useDefault = true)
1488 { return tie(relative_path.c_str(), rawValue, useDefault); }
1492 * Bind another node to an external long int source.
1494 bool tie (const char * relative_path, const SGRawValue<long> &rawValue,
1495 bool useDefault = true);
1498 * Bind another node to an external long int source.
1500 bool tie (const std::string& relative_path, const SGRawValue<long> &rawValue,
1501 bool useDefault = true)
1502 { return tie(relative_path.c_str(), rawValue, useDefault); }
1506 * Bind another node to an external float source.
1508 bool tie (const char * relative_path, const SGRawValue<float> &rawValue,
1509 bool useDefault = true);
1512 * Bind another node to an external float source.
1514 bool tie (const std::string& relative_path, const SGRawValue<float> &rawValue,
1515 bool useDefault = true)
1516 { return tie(relative_path.c_str(), rawValue, useDefault); }
1520 * Bind another node to an external double source.
1522 bool tie (const char * relative_path, const SGRawValue<double> &rawValue,
1523 bool useDefault = true);
1526 * Bind another node to an external double source.
1528 bool tie (const std::string& relative_path, const SGRawValue<double> &rawValue,
1529 bool useDefault = true)
1530 { return tie(relative_path.c_str(), rawValue, useDefault); }
1534 * Bind another node to an external string source.
1536 bool tie (const char * relative_path, const SGRawValue<const char *> &rawValue,
1537 bool useDefault = true);
1540 * Bind another node to an external string source.
1542 bool tie (const std::string& relative_path, const SGRawValue<const char*> &rawValue,
1543 bool useDefault = true)
1544 { return tie(relative_path.c_str(), rawValue, useDefault); }
1548 * Unbind another node from any external data source.
1550 bool untie (const char * relative_path);
1553 * Unbind another node from any external data source.
1555 bool untie (const std::string& relative_path)
1556 { return untie(relative_path.c_str()); }
1560 * Add a change listener to the property. If "initial" is set call the
1561 * listener initially.
1563 void addChangeListener (SGPropertyChangeListener * listener,
1564 bool initial = false);
1568 * Remove a change listener from the property.
1570 void removeChangeListener (SGPropertyChangeListener * listener);
1574 * Get the number of listeners.
1576 int nListeners () const { return _listeners ? (int)_listeners->size() : 0; }
1580 * Fire a value change event to all listeners.
1582 void fireValueChanged ();
1586 * Fire a child-added event to all listeners.
1588 void fireChildAdded (SGPropertyNode * child);
1592 * Fire a child-removed event to all listeners.
1594 void fireChildRemoved (SGPropertyNode * child);
1598 * Clear any existing value and set the type to NONE.
1603 * Compare two property trees. The property trees are equal if: 1)
1604 * They have no children, and have the same type and the values are
1605 * equal, or 2) have the same number of children, and the
1606 * corresponding children in each tree are equal. "corresponding"
1607 * means have the same name and index.
1609 * Attributes, removed children, and aliases aren't considered.
1611 static bool compare (const SGPropertyNode& lhs, const SGPropertyNode& rhs);
1615 void fireValueChanged (SGPropertyNode * node);
1616 void fireChildAdded (SGPropertyNode * parent, SGPropertyNode * child);
1617 void fireChildRemoved (SGPropertyNode * parent, SGPropertyNode * child);
1620 * Protected constructor for making new nodes on demand.
1622 SGPropertyNode (const std::string& name, int index, SGPropertyNode * parent);
1623 template<typename Itr>
1624 SGPropertyNode (Itr begin, Itr end, int index, SGPropertyNode * parent);
1628 // Get the raw value
1629 bool get_bool () const;
1630 int get_int () const;
1631 long get_long () const;
1632 float get_float () const;
1633 double get_double () const;
1634 const char * get_string () const;
1636 // Set the raw value
1637 bool set_bool (bool value);
1638 bool set_int (int value);
1639 bool set_long (long value);
1640 bool set_float (float value);
1641 bool set_double (double value);
1642 bool set_string (const char * value);
1646 * Get the value as a string.
1648 const char * make_string () const;
1651 * Trace a read access.
1653 void trace_read () const;
1657 * Trace a write access.
1659 void trace_write () const;
1663 * Remove this node from all nodes that link to it in their path cache.
1665 void remove_from_path_caches();
1672 /// To avoid cyclic reference counting loops this shall not be a reference
1674 SGPropertyNode * _parent;
1675 simgear::PropertyList _children;
1676 simgear::PropertyList _removedChildren;
1677 std::vector<hash_table *> _linkedNodes;
1678 mutable std::string _buffer;
1679 hash_table * _path_cache;
1680 simgear::props::Type _type;
1684 // The right kind of pointer...
1686 SGPropertyNode * alias;
1699 std::vector<SGPropertyChangeListener *> * _listeners;
1703 * Register/unregister node that links to this node in its path cache.
1705 void add_linked_node (hash_table * node) { _linkedNodes.push_back(node); }
1706 bool remove_linked_node (hash_table * node);
1711 * A very simple hash table.
1717 * An entry in a bucket in a hash table.
1723 const char * get_key () { return _key.c_str(); }
1724 void set_key (const char * key);
1725 SGPropertyNode * get_value () { return _value; }
1726 void set_value (SGPropertyNode * value);
1729 SGSharedPtr<SGPropertyNode> _value;
1734 * A bucket in a hash table.
1740 entry * get_entry (const char * key, bool create = false);
1741 bool erase (SGPropertyNode * node);
1742 void clear (hash_table * owner);
1748 friend class bucket;
1752 SGPropertyNode * get (const char * key);
1753 void put (const char * key, SGPropertyNode * value);
1754 bool erase (SGPropertyNode * node);
1757 unsigned int hashcode (const char * key);
1758 unsigned int _data_length;
1761 // Pass name as a pair of iterators
1762 template<typename Itr>
1763 SGPropertyNode * getChildImpl (Itr begin, Itr end, int index = 0, bool create = false);
1764 // very internal method
1765 template<typename Itr>
1766 SGPropertyNode* getExistingChild (Itr begin, Itr end, int index, bool create);
1767 // very internal path parsing function
1768 template<typename SplitItr>
1769 friend SGPropertyNode* find_node_aux(SGPropertyNode * current, SplitItr& itr,
1770 bool create, int last_index);
1772 friend size_t hash_value(const SGPropertyNode& node);
1775 // Convenience functions for use in templates
1776 template<typename T>
1777 T getValue(const SGPropertyNode*);
1780 inline bool getValue<bool>(const SGPropertyNode* node) { return node->getBoolValue(); }
1783 inline int getValue<int>(const SGPropertyNode* node) { return node->getIntValue(); }
1786 inline long getValue<long>(const SGPropertyNode* node) { return node->getLongValue(); }
1789 inline float getValue<float>(const SGPropertyNode* node)
1791 return node->getFloatValue();
1795 inline double getValue<double>(const SGPropertyNode* node)
1797 return node->getDoubleValue();
1801 inline const char * getValue<const char*>(const SGPropertyNode* node)
1803 return node->getStringValue ();
1806 inline bool setValue(SGPropertyNode* node, bool value)
1808 return node->setBoolValue(value);
1811 inline bool setValue(SGPropertyNode* node, int value)
1813 return node->setIntValue(value);
1816 inline bool setValue(SGPropertyNode* node, long value)
1818 return node->setLongValue(value);
1821 inline bool setValue(SGPropertyNode* node, float value)
1823 return node->setFloatValue(value);
1826 inline bool setValue(SGPropertyNode* node, double value)
1828 return node->setDoubleValue(value);
1831 inline bool setValue(SGPropertyNode* node, const char* value)
1833 return node->setStringValue(value);
1836 inline bool setValue (SGPropertyNode* node, const std::string& value)
1838 return node->setStringValue(value.c_str());
1841 template<typename T>
1842 bool SGPropertyNode::tie(const SGRawValue<T> &rawValue, bool useDefault)
1844 using namespace simgear::props;
1845 if (_type == ALIAS || _tied)
1848 useDefault = useDefault && hasValue();
1849 T old_val = SGRawValue<T>::DefaultValue();
1851 old_val = getValue<T>(this);
1853 if (PropertyTraits<T>::Internal)
1854 _type = PropertyTraits<T>::type_tag;
1858 _value.val = rawValue.clone();
1865 bool SGPropertyNode::tie (const SGRawValue<const char *> &rawValue,
1868 template<typename T>
1869 T SGPropertyNode::getValue(typename boost::disable_if_c<simgear::props
1870 ::PropertyTraits<T>::Internal>::type* dummy) const
1872 using namespace simgear::props;
1873 if (_attr == (READ|WRITE) && _type == EXTENDED
1874 && _value.val->getType() == PropertyTraits<T>::type_tag) {
1875 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
1877 if (getAttribute(TRACE_READ))
1879 if (!getAttribute(READ))
1880 return SGRawValue<T>::DefaultValue();
1883 if (_value.val->getType() == PropertyTraits<T>::type_tag)
1884 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
1888 return simgear::parseString<T>(make_string());
1890 default: // avoid compiler warning
1893 return SGRawValue<T>::DefaultValue();
1896 template<typename T>
1897 inline T SGPropertyNode::getValue(typename boost::enable_if_c<simgear::props
1898 ::PropertyTraits<T>::Internal>::type* dummy) const
1900 return ::getValue<T>(this);
1903 template<typename T>
1904 bool SGPropertyNode::setValue(const T& val,
1905 typename boost::disable_if_c<simgear::props
1906 ::PropertyTraits<T>::Internal>::type* dummy)
1908 using namespace simgear::props;
1909 if (_attr == (READ|WRITE) && _type == EXTENDED
1910 && _value.val->getType() == PropertyTraits<T>::type_tag) {
1911 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
1914 if (getAttribute(WRITE)
1915 && ((_type == EXTENDED
1916 && _value.val->getType() == PropertyTraits<T>::type_tag)
1917 || _type == NONE || _type == UNSPECIFIED)) {
1918 if (_type == NONE || _type == UNSPECIFIED) {
1921 _value.val = new SGRawValueContainer<T>(val);
1923 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
1925 if (getAttribute(TRACE_WRITE))
1932 template<typename T>
1933 inline bool SGPropertyNode::setValue(const T& val,
1934 typename boost::enable_if_c<simgear::props
1935 ::PropertyTraits<T>::Internal>::type* dummy)
1937 return ::setValue(this, val);
1941 * Utility function for creation of a child property node.
1943 inline SGPropertyNode* makeChild(SGPropertyNode* parent, const char* name,
1946 return parent->getChild(name, index, true);
1950 * Utility function for creation of a child property node using a
1955 template<typename StringType>
1956 inline SGPropertyNode* makeNode(SGPropertyNode* parent, const StringType& name)
1958 return parent->getNode(name, true);
1963 size_t hash_value(const SGPropertyNode& node);
1965 // Helper comparison and hash functions for common cases
1973 bool operator()(const SGPropertyNode* lhs, const SGPropertyNode* rhs) const
1975 return SGPropertyNode::compare(*lhs, *rhs);
1977 bool operator()(SGPropertyNode_ptr lhs, const SGPropertyNode* rhs) const
1979 return SGPropertyNode::compare(*lhs, *rhs);
1981 bool operator()(const SGPropertyNode* lhs, SGPropertyNode_ptr rhs) const
1983 return SGPropertyNode::compare(*lhs, *rhs);
1985 bool operator()(SGPropertyNode_ptr lhs, SGPropertyNode_ptr rhs) const
1987 return SGPropertyNode::compare(*lhs, *rhs);
1993 size_t operator()(const SGPropertyNode* node) const
1995 return hash_value(*node);
1997 size_t operator()(SGPropertyNode_ptr node) const
1999 return hash_value(*node);
2004 #endif // __PROPS_HXX