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 #ifndef NO_OPENSCENEGRAPH_INTERFACE
67 // Extended properties
69 std::istream& readFrom<SGVec3d>(std::istream& stream, SGVec3d& result);
71 std::istream& readFrom<SGVec4d>(std::istream& stream, SGVec4d& result);
75 * Property value types.
79 #pragma warn A sloppy coder has defined NONE as a macro!
84 #pragma warn A sloppy coder has defined ALIAS as a macro!
89 #pragma warn A sloppy coder has defined UNSPECIFIED as a macro!
94 #pragma warn A sloppy coder has defined BOOL as a macro!
99 #pragma warn A sloppy coder has defined INT as a macro!
104 #pragma warn A sloppy coder has defined LONG as a macro!
109 #pragma warn A sloppy coder has defined FLOAT as a macro!
114 #pragma warn A sloppy coder has defined DOUBLE as a macro!
119 #pragma warn A sloppy coder has defined STRING as a macro!
126 * The possible types of an SGPropertyNode. Types that appear after
127 * EXTENDED are not stored in the SGPropertyNode itself.
130 NONE = 0, /**< The node hasn't been assigned a value yet. */
131 ALIAS, /**< The node "points" to another node. */
139 EXTENDED, /**< The node's value is not stored in the property;
140 * the actual value and type is retrieved from an
141 * SGRawValue node. This type is never returned by @see
142 * SGPropertyNode::getType.
144 // Extended properties
149 template<typename T> struct PropertyTraits;
151 #define DEFINTERNALPROP(TYPE, PROP) \
153 struct PropertyTraits<TYPE> \
155 static const Type type_tag = PROP; \
156 enum { Internal = 1 }; \
159 DEFINTERNALPROP(bool, BOOL);
160 DEFINTERNALPROP(int, INT);
161 DEFINTERNALPROP(long, LONG);
162 DEFINTERNALPROP(float, FLOAT);
163 DEFINTERNALPROP(double, DOUBLE);
164 DEFINTERNALPROP(const char *, STRING);
165 DEFINTERNALPROP(const char[], STRING);
166 #undef DEFINTERNALPROP
168 #ifndef NO_OPENSCENEGRAPH_INTERFACE
170 struct PropertyTraits<SGVec3d>
172 static const Type type_tag = VEC3D;
173 enum { Internal = 0 };
177 struct PropertyTraits<SGVec4d>
179 static const Type type_tag = VEC4D;
180 enum { Internal = 0 };
190 ////////////////////////////////////////////////////////////////////////
193 // This is the mechanism that information-providing routines can
194 // use to link their own values to the property manager. Any
195 // SGValue can be tied to a raw value and then untied again.
197 // Note: we are forced to use inlined methods here to ensure
198 // that the templates will be instantiated. We're probably taking
199 // a small performance hit for that.
200 ////////////////////////////////////////////////////////////////////////
203 * Base class for SGRawValue classes that holds no type
204 * information. This allows some generic manipulation of the
211 * Get the type enumeration for the raw value.
215 virtual simgear::props::Type getType() const = 0;
219 * Create a new deep copy of this raw value.
221 * The copy will contain its own version of the underlying value
222 * as well, and will be the same type.
224 * @return A deep copy of the current object.
226 virtual SGRaw* clone() const = 0;
230 class SGRawExtended : public SGRaw
234 * Make an SGRawValueContainer from the SGRawValue.
236 * This is a virtual function of SGRawExtended so that
237 * SGPropertyNode::untie doesn't need to know the type of an
240 virtual SGRawExtended* makeContainer() const = 0;
242 * Write value out to a stream
244 virtual std::ostream& printOn(std::ostream& stream) const = 0;
246 * Read value from a stream and store it.
248 virtual std::istream& readFrom(std::istream& stream) = 0;
251 // Choose between different base classes based on whether the value is
252 // stored internal to the property node. This frees us from defining
253 // the virtual functions in the SGRawExtended interface where they
254 // don't make sense, e.g. readFrom for the const char* type.
255 template<typename T, int internal = simgear::props::PropertyTraits<T>::Internal>
259 class SGRawBase<T, 1> : public SGRaw
264 class SGRawBase<T, 0> : public SGRawExtended
266 virtual SGRawExtended* makeContainer() const;
267 virtual std::ostream& printOn(std::ostream& stream) const;
268 virtual std::istream& readFrom(std::istream& stream);
272 * Abstract base class for a raw value.
274 * <p>The property manager is implemented in two layers. The {@link
275 * SGPropertyNode} is the highest and most abstract layer,
276 * representing an LValue/RValue pair: it records the position of the
277 * property in the property tree and contains facilities for
278 * navigation to other nodes. It is guaranteed to be persistent: the
279 * {@link SGPropertyNode} will not change during a session, even if
280 * the property is bound and unbound multiple times.</p>
282 * <p>When the property value is not managed internally in the
283 * SGPropertyNode, the SGPropertyNode will contain a reference to an
284 * SGRawValue (this class), which provides an abstract way to get,
285 * set, and clone the underlying value. The SGRawValue may change
286 * frequently during a session as a value is retyped or bound and
287 * unbound to various data source, but the abstract SGPropertyNode
288 * layer insulates the application from those changes.
290 * <p>The SGPropertyNode class always keeps a *copy* of a raw value,
291 * not the original one passed to it; if you override a derived class
292 * but do not replace the {@link #clone} method, strange things will
295 * <p>All derived SGRawValue classes must implement {@link #getValue},
296 * {@link #setValue}, and {@link #clone} for the appropriate type.</p>
298 * @see SGPropertyNode
299 * @see SGRawValuePointer
300 * @see SGRawValueFunctions
301 * @see SGRawValueFunctionsIndexed
302 * @see SGRawValueMethods
303 * @see SGRawValueMethodsIndexed
304 * @see SGRawValueContainer
307 class SGRawValue : public SGRawBase<T>
312 * The default underlying value for this type.
314 * Every raw value has a default; the default is false for a
315 * boolean, 0 for the various numeric values, and "" for a string.
316 * If additional types of raw values are added in the future, they
317 * may need different kinds of default values (such as epoch for a
318 * date type). The default value is used when creating new values.
320 static T DefaultValue()
329 * Use the default value for this type.
337 virtual ~SGRawValue () {}
341 * Return the underlying value.
343 * @return The actual value for the property.
346 virtual T getValue () const = 0;
350 * Assign a new underlying value.
352 * If the new value cannot be set (because this is a read-only
353 * raw value, or because the new value is not acceptable for
354 * some reason) this method returns false and leaves the original
357 * @param value The actual value for the property.
358 * @return true if the value was set successfully, false otherwise.
361 virtual bool setValue (T value) = 0;
365 * Return the type tag for this raw value type.
367 virtual simgear::props::Type getType() const
369 return simgear::props::PropertyTraits<T>::type_tag;
375 ////////////////////////////////////////////////////////////////////////
376 // Default values for every type.
377 ////////////////////////////////////////////////////////////////////////
379 template<> inline bool SGRawValue<bool>::DefaultValue()
384 template<> inline const char * SGRawValue<const char *>::DefaultValue()
390 * A raw value bound to a pointer.
392 * This is the most efficient way to tie an external value, but also
393 * the most dangerous, because there is no way for the supplier to
394 * perform bounds checking and derived calculations except by polling
395 * the variable to see if it has changed. There is no default
396 * constructor, because this class would be meaningless without a
400 class SGRawValuePointer : public SGRawValue<T>
405 * Explicit pointer constructor.
407 * Create a new raw value bound to the value of the variable
408 * referenced by the pointer.
410 * @param ptr The pointer to the variable to which this raw value
413 SGRawValuePointer (T * ptr) : _ptr(ptr) {}
418 virtual ~SGRawValuePointer () {}
421 * Get the underlying value.
423 * This method will dereference the pointer and return the
426 virtual T getValue () const { return *_ptr; }
429 * Set the underlying value.
431 * This method will dereference the pointer and change the
434 virtual bool setValue (T value) { *_ptr = value; return true; }
437 * Create a copy of this raw value.
439 * The copy will use the same external pointer as the original.
441 virtual SGRaw* clone () const {
442 return new SGRawValuePointer(_ptr);
451 * A value managed through static functions.
453 * A read-only value will not have a setter; a write-only value will
457 class SGRawValueFunctions : public SGRawValue<T>
462 * The template type of a static getter function.
464 typedef T (*getter_t)();
467 * The template type of a static setter function.
469 typedef void (*setter_t)(T);
472 * Explicit constructor.
474 * Create a new raw value bound to the getter and setter supplied.
476 * @param getter A static function for getting a value, or 0
477 * to read-disable the value.
478 * @param setter A static function for setting a value, or 0
479 * to write-disable the value.
481 SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
482 : _getter(getter), _setter(setter) {}
487 virtual ~SGRawValueFunctions () {}
490 * Get the underlying value.
492 * This method will invoke the getter function to get a value.
493 * If no getter function was supplied, this method will always
494 * return the default value for the type.
496 virtual T getValue () const {
497 if (_getter) return (*_getter)();
498 else return SGRawValue<T>::DefaultValue();
502 * Set the underlying value.
504 * This method will invoke the setter function to change the
505 * underlying value. If no setter function was supplied, this
506 * method will return false.
508 virtual bool setValue (T value) {
509 if (_setter) { (*_setter)(value); return true; }
514 * Create a copy of this raw value, bound to the same functions.
516 virtual SGRaw* clone () const {
517 return new SGRawValueFunctions(_getter,_setter);
527 * An indexed value bound to static functions.
529 * A read-only value will not have a setter; a write-only value will
530 * not have a getter. An indexed value is useful for binding one
531 * of a list of possible values (such as multiple engines for a
532 * plane). The index is hard-coded at creation time.
537 class SGRawValueFunctionsIndexed : public SGRawValue<T>
540 typedef T (*getter_t)(int);
541 typedef void (*setter_t)(int,T);
542 SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
543 : _index(index), _getter(getter), _setter(setter) {}
544 virtual ~SGRawValueFunctionsIndexed () {}
545 virtual T getValue () const {
546 if (_getter) return (*_getter)(_index);
547 else return SGRawValue<T>::DefaultValue();
549 virtual bool setValue (T value) {
550 if (_setter) { (*_setter)(_index, value); return true; }
553 virtual SGRaw* clone () const {
554 return new SGRawValueFunctionsIndexed(_index, _getter, _setter);
564 * A value managed through an object and access methods.
566 * A read-only value will not have a setter; a write-only value will
569 template <class C, class T>
570 class SGRawValueMethods : public SGRawValue<T>
573 typedef T (C::*getter_t)() const;
574 typedef void (C::*setter_t)(T);
575 SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
576 : _obj(obj), _getter(getter), _setter(setter) {}
577 virtual ~SGRawValueMethods () {}
578 virtual T getValue () const {
579 if (_getter) { return (_obj.*_getter)(); }
580 else { return SGRawValue<T>::DefaultValue(); }
582 virtual bool setValue (T value) {
583 if (_setter) { (_obj.*_setter)(value); return true; }
586 virtual SGRaw* clone () const {
587 return new SGRawValueMethods(_obj, _getter, _setter);
597 * An indexed value managed through an object and access methods.
599 * A read-only value will not have a setter; a write-only value will
602 template <class C, class T>
603 class SGRawValueMethodsIndexed : public SGRawValue<T>
606 typedef T (C::*getter_t)(int) const;
607 typedef void (C::*setter_t)(int, T);
608 SGRawValueMethodsIndexed (C &obj, int index,
609 getter_t getter = 0, setter_t setter = 0)
610 : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
611 virtual ~SGRawValueMethodsIndexed () {}
612 virtual T getValue () const {
613 if (_getter) { return (_obj.*_getter)(_index); }
614 else { return SGRawValue<T>::DefaultValue(); }
616 virtual bool setValue (T value) {
617 if (_setter) { (_obj.*_setter)(_index, value); return true; }
620 virtual SGRaw* clone () const {
621 return new SGRawValueMethodsIndexed(_obj, _index, _getter, _setter);
631 * A raw value that contains its value. This provides a way for
632 * property nodes to contain values that shouldn't be stored in the
633 * property node itself.
636 class SGRawValueContainer : public SGRawValue<T>
641 * Explicit constructor.
643 SGRawValueContainer(const T& obj) : _obj(obj) {}
648 virtual ~SGRawValueContainer() {}
651 * Get the underlying value.
653 virtual T getValue() const { return _obj; }
656 * Set the underlying value.
658 * This method will dereference the pointer and change the
661 virtual bool setValue (T value) { _obj = value; return true; }
664 * Create a copy of this raw value.
666 virtual SGRaw* clone () const {
667 return new SGRawValueContainer(_obj);
675 SGRawExtended* SGRawBase<T, 0>::makeContainer() const
677 return new SGRawValueContainer<T>(static_cast<const SGRawValue<T>*>(this)
682 std::ostream& SGRawBase<T, 0>::printOn(std::ostream& stream) const
684 return stream << static_cast<SGRawValue<T>*>(this)->getValue();
688 std::istream& SGRawBase<T, 0>::readFrom(std::istream& stream)
691 simgear::readFrom(stream, value);
692 static_cast<SGRawValue<T>*>(this)->setValue(value);
696 #ifndef NO_OPENSCENEGRAPH_INTERFACE
698 std::ostream& SGRawBase<SGVec3d>::printOn(std::ostream& stream) const;
700 std::ostream& SGRawBase<SGVec4d>::printOn(std::ostream& stream) const;
705 * The smart pointer that manage reference counting
707 class SGPropertyNode;
708 typedef SGSharedPtr<SGPropertyNode> SGPropertyNode_ptr;
709 typedef SGSharedPtr<const SGPropertyNode> SGConstPropertyNode_ptr;
713 typedef std::vector<SGPropertyNode_ptr> PropertyList;
718 * The property change listener interface.
720 * <p>Any class that needs to listen for property changes must implement
721 * this interface.</p>
723 class SGPropertyChangeListener
726 virtual ~SGPropertyChangeListener ();
727 virtual void valueChanged (SGPropertyNode * node);
728 virtual void childAdded (SGPropertyNode * parent, SGPropertyNode * child);
729 virtual void childRemoved (SGPropertyNode * parent, SGPropertyNode * child);
732 friend class SGPropertyNode;
733 virtual void register_property (SGPropertyNode * node);
734 virtual void unregister_property (SGPropertyNode * node);
737 std::vector<SGPropertyNode *> _properties;
743 * A node in a property tree.
745 class SGPropertyNode : public SGReferenced
753 MAX_STRING_LEN = 1024
757 * Access mode attributes.
759 * <p>The ARCHIVE attribute is strictly advisory, and controls
760 * whether the property should normally be saved and restored.</p>
771 // beware: if you add another attribute here,
772 // also update value of "LAST_USED_ATTRIBUTE".
777 * Last used attribute
778 * Update as needed when enum Attribute is changed
780 static const int LAST_USED_ATTRIBUTE;
784 * Default constructor.
792 SGPropertyNode (const SGPropertyNode &node);
798 virtual ~SGPropertyNode ();
807 * Test whether this node contains a primitive leaf value.
809 bool hasValue () const { return (_type != simgear::props::NONE); }
813 * Get the node's simple (XML) name.
815 const char * getName () const { return _name.c_str(); }
818 * Get the node's simple name as a string.
820 const std::string& getNameString () const { return _name; }
823 * Get the node's pretty display name, with subscript when needed.
825 std::string getDisplayName (bool simplify = false) const;
829 * Get the node's integer index.
831 int getIndex () const { return _index; }
835 * Get a non-const pointer to the node's parent.
837 SGPropertyNode * getParent () { return _parent; }
841 * Get a const pointer to the node's parent.
843 const SGPropertyNode * getParent () const { return _parent; }
852 * Get the number of child nodes.
854 int nChildren () const { return (int)_children.size(); }
858 * Get a child node by position (*NOT* index).
860 SGPropertyNode * getChild (int position);
864 * Get a const child node by position (*NOT* index).
866 const SGPropertyNode * getChild (int position) const;
870 * Test whether a named child exists.
872 bool hasChild (const char * name, int index = 0) const
874 return (getChild(name, index) != 0);
878 * Test whether a named child exists.
880 bool hasChild (const std::string& name, int index = 0) const
882 return (getChild(name, index) != 0);
886 * Create a child node after the last node with the same name.
888 SGPropertyNode * addChild (const char * name);
891 * Get a child node by name and index.
893 SGPropertyNode * getChild (const char* name, int index = 0,
894 bool create = false);
895 SGPropertyNode * getChild (const std::string& name, int index = 0,
896 bool create = false);
898 * Get a const child node by name and index.
900 const SGPropertyNode * getChild (const char * name, int index = 0) const;
903 * Get a const child node by name and index.
905 const SGPropertyNode * getChild (const std::string& name, int index = 0) const
906 { return getChild(name.c_str(), index); }
910 * Get a vector of all children with the specified name.
912 simgear::PropertyList getChildren (const char * name) const;
915 * Get a vector of all children with the specified name.
917 simgear::PropertyList getChildren (const std::string& name) const
918 { return getChildren(name.c_str()); }
921 * Remove child by position.
923 SGPropertyNode_ptr removeChild (int pos, bool keep = true);
927 * Remove a child node
929 SGPropertyNode_ptr removeChild (const char * name, int index = 0,
933 * Remove a child node
935 SGPropertyNode_ptr removeChild (const std::string& name, int index = 0,
937 { return removeChild(name.c_str(), index, keep); }
940 * Remove all children with the specified name.
942 simgear::PropertyList removeChildren (const char * name, bool keep = true);
945 * Remove all children with the specified name.
947 simgear::PropertyList removeChildren (const std::string& name,
949 { return removeChildren(name.c_str(), keep); }
957 * Alias this node's leaf value to another's.
959 bool alias (SGPropertyNode * target);
963 * Alias this node's leaf value to another's by relative path.
965 bool alias (const char * path);
968 * Alias this node's leaf value to another's by relative path.
970 bool alias (const std::string& path)
971 { return alias(path.c_str()); }
975 * Remove any alias for this node.
981 * Test whether the node's leaf value is aliased to another's.
983 bool isAlias () const { return (_type == simgear::props::ALIAS); }
987 * Get a non-const pointer to the current alias target, if any.
989 SGPropertyNode * getAliasTarget ();
993 * Get a const pointer to the current alias target, if any.
995 const SGPropertyNode * getAliasTarget () const;
1004 * Get the path to this node from the root.
1006 std::string getPath (bool simplify = false) const;
1010 * Get a pointer to the root node.
1012 SGPropertyNode * getRootNode ();
1016 * Get a const pointer to the root node.
1018 const SGPropertyNode * getRootNode () const;
1022 * Get a pointer to another node by relative path.
1024 SGPropertyNode * getNode (const char * relative_path, bool create = false);
1027 * Get a pointer to another node by relative path.
1029 SGPropertyNode * getNode (const std::string& relative_path, bool create = false)
1030 { return getNode(relative_path.c_str(), create); }
1033 * Get a pointer to another node by relative path.
1035 * This method leaves the index off the last member of the path,
1036 * so that the user can specify it separately (and save some
1037 * string building). For example, getNode("/bar[1]/foo", 3) is
1038 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
1039 * provided overrides any given in the path itself for the last
1042 SGPropertyNode * getNode (const char * relative_path, int index,
1043 bool create = false);
1046 * Get a pointer to another node by relative path.
1048 * This method leaves the index off the last member of the path,
1049 * so that the user can specify it separately (and save some
1050 * string building). For example, getNode("/bar[1]/foo", 3) is
1051 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
1052 * provided overrides any given in the path itself for the last
1055 SGPropertyNode * getNode (const std::string& relative_path, int index,
1056 bool create = false)
1057 { return getNode(relative_path.c_str(), index, create); }
1060 * Get a const pointer to another node by relative path.
1062 const SGPropertyNode * getNode (const char * relative_path) const;
1065 * Get a const pointer to another node by relative path.
1067 const SGPropertyNode * getNode (const std::string& relative_path) const
1068 { return getNode(relative_path.c_str()); }
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 char * relative_path,
1081 * Get a const pointer to another node by relative path.
1083 * This method leaves the index off the last member of the path,
1084 * so that the user can specify it separate.
1086 const SGPropertyNode * getNode (const std::string& relative_path,
1088 { return getNode(relative_path.c_str(), index); }
1095 * Check a single mode attribute for the property node.
1097 bool getAttribute (Attribute attr) const { return ((_attr & attr) != 0); }
1101 * Set a single mode attribute for the property node.
1103 void setAttribute (Attribute attr, bool state) {
1104 (state ? _attr |= attr : _attr &= ~attr);
1109 * Get all of the mode attributes for the property node.
1111 int getAttributes () const { return _attr; }
1115 * Set all of the mode attributes for the property node.
1117 void setAttributes (int attr) { _attr = attr; }
1121 // Leaf Value (primitive).
1126 * Get the type of leaf value, if any, for this node.
1128 simgear::props::Type getType () const;
1132 * Get a bool value for this node.
1134 bool getBoolValue () const;
1138 * Get an int value for this node.
1140 int getIntValue () const;
1144 * Get a long int value for this node.
1146 long getLongValue () const;
1150 * Get a float value for this node.
1152 float getFloatValue () const;
1156 * Get a double value for this node.
1158 double getDoubleValue () const;
1162 * Get a string value for this node.
1164 const char * getStringValue () const;
1167 * Get a value from a node. If the actual type of the node doesn't
1168 * match the desired type, a conversion isn't guaranteed.
1170 template<typename T>
1171 T getValue(typename boost::enable_if_c<simgear::props::PropertyTraits<T>::Internal>
1172 ::type* dummy = 0) const;
1173 // Getter for extended property
1174 template<typename T>
1175 T getValue(typename boost::disable_if_c<simgear::props::PropertyTraits<T>::Internal>
1176 ::type* dummy = 0) const;
1179 * Set a bool value for this node.
1181 bool setBoolValue (bool value);
1185 * Set an int value for this node.
1187 bool setIntValue (int value);
1191 * Set a long int value for this node.
1193 bool setLongValue (long value);
1197 * Set a float value for this node.
1199 bool setFloatValue (float value);
1203 * Set a double value for this node.
1205 bool setDoubleValue (double value);
1209 * Set a string value for this node.
1211 bool setStringValue (const char * value);
1214 * Set a string value for this node.
1216 bool setStringValue (const std::string& value)
1217 { return setStringValue(value.c_str()); }
1221 * Set a value of unspecified type for this node.
1223 bool setUnspecifiedValue (const char * value);
1225 template<typename T>
1226 bool setValue(const T& val,
1227 typename boost::enable_if_c<simgear::props::PropertyTraits<T>::Internal>
1230 template<typename T>
1231 bool setValue(const T& val,
1232 typename boost::disable_if_c<simgear::props::PropertyTraits<T>::Internal>
1236 bool setValue(const char (&val)[N])
1238 return setValue(&val[0]);
1242 * Print the value of the property to a stream.
1244 std::ostream& printOn(std::ostream& stream) const;
1252 * Test whether this node is bound to an external data source.
1254 bool isTied () const { return _tied; }
1257 * Bind this node to an external source.
1259 template<typename T>
1260 bool tie(const SGRawValue<T> &rawValue, bool useDefault = true);
1263 * Unbind this node from any external data source.
1269 // Convenience methods using paths.
1270 // TODO: add attribute methods
1275 * Get another node's type.
1277 simgear::props::Type getType (const char * relative_path) const;
1280 * Get another node's type.
1282 simgear::props::Type getType (const std::string& relative_path) const
1283 { return getType(relative_path.c_str()); }
1286 * Test whether another node has a leaf value.
1288 bool hasValue (const char * relative_path) const;
1291 * Test whether another node has a leaf value.
1293 bool hasValue (const std::string& relative_path) const
1294 { return hasValue(relative_path.c_str()); }
1297 * Get another node's value as a bool.
1299 bool getBoolValue (const char * relative_path,
1300 bool defaultValue = false) const;
1303 * Get another node's value as a bool.
1305 bool getBoolValue (const std::string& relative_path,
1306 bool defaultValue = false) const
1307 { return getBoolValue(relative_path.c_str(), defaultValue); }
1310 * Get another node's value as an int.
1312 int getIntValue (const char * relative_path,
1313 int defaultValue = 0) const;
1316 * Get another node's value as an int.
1318 int getIntValue (const std::string& relative_path,
1319 int defaultValue = 0) const
1320 { return getIntValue(relative_path.c_str(), defaultValue); }
1324 * Get another node's value as a long int.
1326 long getLongValue (const char * relative_path,
1327 long defaultValue = 0L) const;
1330 * Get another node's value as a long int.
1332 long getLongValue (const std::string& relative_path,
1333 long defaultValue = 0L) const
1334 { return getLongValue(relative_path.c_str(), defaultValue); }
1337 * Get another node's value as a float.
1339 float getFloatValue (const char * relative_path,
1340 float defaultValue = 0.0f) const;
1343 * Get another node's value as a float.
1345 float getFloatValue (const std::string& relative_path,
1346 float defaultValue = 0.0f) const
1347 { return getFloatValue(relative_path.c_str(), defaultValue); }
1351 * Get another node's value as a double.
1353 double getDoubleValue (const char * relative_path,
1354 double defaultValue = 0.0) const;
1357 * Get another node's value as a double.
1359 double getDoubleValue (const std::string& relative_path,
1360 double defaultValue = 0.0) const
1361 { return getDoubleValue(relative_path.c_str(), defaultValue); }
1364 * Get another node's value as a string.
1366 const char * getStringValue (const char * relative_path,
1367 const char * defaultValue = "") const;
1371 * Get another node's value as a string.
1373 const char * getStringValue (const std::string& relative_path,
1374 const char * defaultValue = "") const
1375 { return getStringValue(relative_path.c_str(), defaultValue); }
1379 * Set another node's value as a bool.
1381 bool setBoolValue (const char * relative_path, bool value);
1384 * Set another node's value as a bool.
1386 bool setBoolValue (const std::string& relative_path, bool value)
1387 { return setBoolValue(relative_path.c_str(), value); }
1391 * Set another node's value as an int.
1393 bool setIntValue (const char * relative_path, int value);
1396 * Set another node's value as an int.
1398 bool setIntValue (const std::string& relative_path, int value)
1399 { return setIntValue(relative_path.c_str(), value); }
1403 * Set another node's value as a long int.
1405 bool setLongValue (const char * relative_path, long value);
1408 * Set another node's value as a long int.
1410 bool setLongValue (const std::string& relative_path, long value)
1411 { return setLongValue(relative_path.c_str(), value); }
1415 * Set another node's value as a float.
1417 bool setFloatValue (const char * relative_path, float value);
1420 * Set another node's value as a float.
1422 bool setFloatValue (const std::string& relative_path, float value)
1423 { return setFloatValue(relative_path.c_str(), value); }
1427 * Set another node's value as a double.
1429 bool setDoubleValue (const char * relative_path, double value);
1432 * Set another node's value as a double.
1434 bool setDoubleValue (const std::string& relative_path, double value)
1435 { return setDoubleValue(relative_path.c_str(), value); }
1439 * Set another node's value as a string.
1441 bool setStringValue (const char * relative_path, const char * value);
1443 bool setStringValue(const char * relative_path, const std::string& value)
1444 { return setStringValue(relative_path, value.c_str()); }
1446 * Set another node's value as a string.
1448 bool setStringValue (const std::string& relative_path, const char * value)
1449 { return setStringValue(relative_path.c_str(), value); }
1451 bool setStringValue (const std::string& relative_path,
1452 const std::string& value)
1453 { return setStringValue(relative_path.c_str(), value.c_str()); }
1456 * Set another node's value with no specified type.
1458 bool setUnspecifiedValue (const char * relative_path, const char * value);
1462 * Test whether another node is bound to an external data source.
1464 bool isTied (const char * relative_path) const;
1467 * Test whether another node is bound to an external data source.
1469 bool isTied (const std::string& relative_path) const
1470 { return isTied(relative_path.c_str()); }
1473 * Bind another node to an external bool source.
1475 bool tie (const char * relative_path, const SGRawValue<bool> &rawValue,
1476 bool useDefault = true);
1479 * Bind another node to an external bool source.
1481 bool tie (const std::string& relative_path, const SGRawValue<bool> &rawValue,
1482 bool useDefault = true)
1483 { return tie(relative_path.c_str(), rawValue, useDefault); }
1487 * Bind another node to an external int source.
1489 bool tie (const char * relative_path, const SGRawValue<int> &rawValue,
1490 bool useDefault = true);
1493 * Bind another node to an external int source.
1495 bool tie (const std::string& relative_path, const SGRawValue<int> &rawValue,
1496 bool useDefault = true)
1497 { return tie(relative_path.c_str(), rawValue, useDefault); }
1501 * Bind another node to an external long int source.
1503 bool tie (const char * relative_path, const SGRawValue<long> &rawValue,
1504 bool useDefault = true);
1507 * Bind another node to an external long int source.
1509 bool tie (const std::string& relative_path, const SGRawValue<long> &rawValue,
1510 bool useDefault = true)
1511 { return tie(relative_path.c_str(), rawValue, useDefault); }
1515 * Bind another node to an external float source.
1517 bool tie (const char * relative_path, const SGRawValue<float> &rawValue,
1518 bool useDefault = true);
1521 * Bind another node to an external float source.
1523 bool tie (const std::string& relative_path, const SGRawValue<float> &rawValue,
1524 bool useDefault = true)
1525 { return tie(relative_path.c_str(), rawValue, useDefault); }
1529 * Bind another node to an external double source.
1531 bool tie (const char * relative_path, const SGRawValue<double> &rawValue,
1532 bool useDefault = true);
1535 * Bind another node to an external double source.
1537 bool tie (const std::string& relative_path, const SGRawValue<double> &rawValue,
1538 bool useDefault = true)
1539 { return tie(relative_path.c_str(), rawValue, useDefault); }
1543 * Bind another node to an external string source.
1545 bool tie (const char * relative_path, const SGRawValue<const char *> &rawValue,
1546 bool useDefault = true);
1549 * Bind another node to an external string source.
1551 bool tie (const std::string& relative_path, const SGRawValue<const char*> &rawValue,
1552 bool useDefault = true)
1553 { return tie(relative_path.c_str(), rawValue, useDefault); }
1557 * Unbind another node from any external data source.
1559 bool untie (const char * relative_path);
1562 * Unbind another node from any external data source.
1564 bool untie (const std::string& relative_path)
1565 { return untie(relative_path.c_str()); }
1569 * Add a change listener to the property. If "initial" is set call the
1570 * listener initially.
1572 void addChangeListener (SGPropertyChangeListener * listener,
1573 bool initial = false);
1577 * Remove a change listener from the property.
1579 void removeChangeListener (SGPropertyChangeListener * listener);
1583 * Get the number of listeners.
1585 int nListeners () const { return _listeners ? (int)_listeners->size() : 0; }
1589 * Fire a value change event to all listeners.
1591 void fireValueChanged ();
1595 * Fire a child-added event to all listeners.
1597 void fireChildAdded (SGPropertyNode * child);
1601 * Fire a child-removed event to all listeners.
1603 void fireChildRemoved (SGPropertyNode * child);
1607 * Clear any existing value and set the type to NONE.
1612 * Compare two property trees. The property trees are equal if: 1)
1613 * They have no children, and have the same type and the values are
1614 * equal, or 2) have the same number of children, and the
1615 * corresponding children in each tree are equal. "corresponding"
1616 * means have the same name and index.
1618 * Attributes, removed children, and aliases aren't considered.
1620 static bool compare (const SGPropertyNode& lhs, const SGPropertyNode& rhs);
1624 void fireValueChanged (SGPropertyNode * node);
1625 void fireChildAdded (SGPropertyNode * parent, SGPropertyNode * child);
1626 void fireChildRemoved (SGPropertyNode * parent, SGPropertyNode * child);
1629 * Protected constructor for making new nodes on demand.
1631 SGPropertyNode (const std::string& name, int index, SGPropertyNode * parent);
1632 template<typename Itr>
1633 SGPropertyNode (Itr begin, Itr end, int index, SGPropertyNode * parent);
1637 // Get the raw value
1638 bool get_bool () const;
1639 int get_int () const;
1640 long get_long () const;
1641 float get_float () const;
1642 double get_double () const;
1643 const char * get_string () const;
1645 // Set the raw value
1646 bool set_bool (bool value);
1647 bool set_int (int value);
1648 bool set_long (long value);
1649 bool set_float (float value);
1650 bool set_double (double value);
1651 bool set_string (const char * value);
1655 * Get the value as a string.
1657 const char * make_string () const;
1660 * Trace a read access.
1662 void trace_read () const;
1666 * Trace a write access.
1668 void trace_write () const;
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 mutable std::string _buffer;
1678 simgear::props::Type _type;
1682 // The right kind of pointer...
1684 SGPropertyNode * alias;
1697 std::vector<SGPropertyChangeListener *> * _listeners;
1700 // Pass name as a pair of iterators
1701 template<typename Itr>
1702 SGPropertyNode * getChildImpl (Itr begin, Itr end, int index = 0, bool create = false);
1703 // very internal method
1704 template<typename Itr>
1705 SGPropertyNode* getExistingChild (Itr begin, Itr end, int index, bool create);
1706 // very internal path parsing function
1707 template<typename SplitItr>
1708 friend SGPropertyNode* find_node_aux(SGPropertyNode * current, SplitItr& itr,
1709 bool create, int last_index);
1711 friend size_t hash_value(const SGPropertyNode& node);
1714 // Convenience functions for use in templates
1715 template<typename T>
1716 T getValue(const SGPropertyNode*);
1719 inline bool getValue<bool>(const SGPropertyNode* node) { return node->getBoolValue(); }
1722 inline int getValue<int>(const SGPropertyNode* node) { return node->getIntValue(); }
1725 inline long getValue<long>(const SGPropertyNode* node) { return node->getLongValue(); }
1728 inline float getValue<float>(const SGPropertyNode* node)
1730 return node->getFloatValue();
1734 inline double getValue<double>(const SGPropertyNode* node)
1736 return node->getDoubleValue();
1740 inline const char * getValue<const char*>(const SGPropertyNode* node)
1742 return node->getStringValue ();
1745 inline bool setValue(SGPropertyNode* node, bool value)
1747 return node->setBoolValue(value);
1750 inline bool setValue(SGPropertyNode* node, int value)
1752 return node->setIntValue(value);
1755 inline bool setValue(SGPropertyNode* node, long value)
1757 return node->setLongValue(value);
1760 inline bool setValue(SGPropertyNode* node, float value)
1762 return node->setFloatValue(value);
1765 inline bool setValue(SGPropertyNode* node, double value)
1767 return node->setDoubleValue(value);
1770 inline bool setValue(SGPropertyNode* node, const char* value)
1772 return node->setStringValue(value);
1775 inline bool setValue (SGPropertyNode* node, const std::string& value)
1777 return node->setStringValue(value.c_str());
1780 template<typename T>
1781 bool SGPropertyNode::tie(const SGRawValue<T> &rawValue, bool useDefault)
1783 using namespace simgear::props;
1784 if (_type == ALIAS || _tied)
1787 useDefault = useDefault && hasValue();
1788 T old_val = SGRawValue<T>::DefaultValue();
1790 old_val = getValue<T>(this);
1792 if (PropertyTraits<T>::Internal)
1793 _type = PropertyTraits<T>::type_tag;
1797 _value.val = rawValue.clone();
1799 int save_attributes = getAttributes();
1800 setAttribute( WRITE, true );
1802 setAttributes( save_attributes );
1808 bool SGPropertyNode::tie (const SGRawValue<const char *> &rawValue,
1811 template<typename T>
1812 T SGPropertyNode::getValue(typename boost::disable_if_c<simgear::props
1813 ::PropertyTraits<T>::Internal>::type* dummy) const
1815 using namespace simgear::props;
1816 if (_attr == (READ|WRITE) && _type == EXTENDED
1817 && _value.val->getType() == PropertyTraits<T>::type_tag) {
1818 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
1820 if (getAttribute(TRACE_READ))
1822 if (!getAttribute(READ))
1823 return SGRawValue<T>::DefaultValue();
1826 if (_value.val->getType() == PropertyTraits<T>::type_tag)
1827 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
1831 return simgear::parseString<T>(make_string());
1833 default: // avoid compiler warning
1836 return SGRawValue<T>::DefaultValue();
1839 template<typename T>
1840 inline T SGPropertyNode::getValue(typename boost::enable_if_c<simgear::props
1841 ::PropertyTraits<T>::Internal>::type* dummy) const
1843 return ::getValue<T>(this);
1846 template<typename T>
1847 bool SGPropertyNode::setValue(const T& val,
1848 typename boost::disable_if_c<simgear::props
1849 ::PropertyTraits<T>::Internal>::type* dummy)
1851 using namespace simgear::props;
1852 if (_attr == (READ|WRITE) && _type == EXTENDED
1853 && _value.val->getType() == PropertyTraits<T>::type_tag) {
1854 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
1857 if (getAttribute(WRITE)
1858 && ((_type == EXTENDED
1859 && _value.val->getType() == PropertyTraits<T>::type_tag)
1860 || _type == NONE || _type == UNSPECIFIED)) {
1861 if (_type == NONE || _type == UNSPECIFIED) {
1864 _value.val = new SGRawValueContainer<T>(val);
1866 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
1868 if (getAttribute(TRACE_WRITE))
1875 template<typename T>
1876 inline bool SGPropertyNode::setValue(const T& val,
1877 typename boost::enable_if_c<simgear::props
1878 ::PropertyTraits<T>::Internal>::type* dummy)
1880 return ::setValue(this, val);
1884 * Utility function for creation of a child property node.
1886 inline SGPropertyNode* makeChild(SGPropertyNode* parent, const char* name,
1889 return parent->getChild(name, index, true);
1893 * Utility function for creation of a child property node using a
1898 template<typename StringType>
1899 inline SGPropertyNode* makeNode(SGPropertyNode* parent, const StringType& name)
1901 return parent->getNode(name, true);
1906 size_t hash_value(const SGPropertyNode& node);
1908 // Helper comparison and hash functions for common cases
1916 bool operator()(const SGPropertyNode* lhs, const SGPropertyNode* rhs) const
1918 return SGPropertyNode::compare(*lhs, *rhs);
1920 bool operator()(SGPropertyNode_ptr lhs, const SGPropertyNode* rhs) const
1922 return SGPropertyNode::compare(*lhs, *rhs);
1924 bool operator()(const SGPropertyNode* lhs, SGPropertyNode_ptr rhs) const
1926 return SGPropertyNode::compare(*lhs, *rhs);
1928 bool operator()(SGPropertyNode_ptr lhs, SGPropertyNode_ptr rhs) const
1930 return SGPropertyNode::compare(*lhs, *rhs);
1936 size_t operator()(const SGPropertyNode* node) const
1938 return hash_value(*node);
1940 size_t operator()(SGPropertyNode_ptr node) const
1942 return hash_value(*node);
1948 /** Convenience class for change listener callbacks without
1949 * creating a derived class implementing a "valueChanged" method.
1950 * Also removes listener on destruction automatically.
1953 class SGPropertyChangeCallback
1954 : public SGPropertyChangeListener
1957 SGPropertyChangeCallback(T* obj, void (T::*method)(SGPropertyNode*),
1958 SGPropertyNode_ptr property,bool initial=false)
1959 : _obj(obj), _callback(method), _property(property)
1961 _property->addChangeListener(this,initial);
1963 virtual ~SGPropertyChangeCallback()
1965 _property->removeChangeListener(this);
1967 void valueChanged (SGPropertyNode * node)
1969 (_obj->*_callback)(node);
1973 void (T::*_callback)(SGPropertyNode*);
1974 SGPropertyNode_ptr _property;
1977 #endif // __PROPS_HXX