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 #undef DEFINTERNALPROP
167 struct PropertyTraits<SGVec3d>
169 static const Type type_tag = VEC3D;
170 enum { Internal = 0 };
174 struct PropertyTraits<SGVec4d>
176 static const Type type_tag = VEC4D;
177 enum { Internal = 0 };
185 ////////////////////////////////////////////////////////////////////////
188 // This is the mechanism that information-providing routines can
189 // use to link their own values to the property manager. Any
190 // SGValue can be tied to a raw value and then untied again.
192 // Note: we are forced to use inlined methods here to ensure
193 // that the templates will be instantiated. We're probably taking
194 // a small performance hit for that.
195 ////////////////////////////////////////////////////////////////////////
198 * Base class for SGRawValue classes that holds no type
199 * information. This allows some generic manipulation of the
206 * Get the type enumeration for the raw value.
210 virtual simgear::props::Type getType() const = 0;
214 * Create a new deep copy of this raw value.
216 * The copy will contain its own version of the underlying value
217 * as well, and will be the same type.
219 * @return A deep copy of the current object.
221 virtual SGRaw* clone() const = 0;
225 class SGRawExtended : public SGRaw
229 * Make an SGRawValueContainer from the SGRawValue.
231 * This is a virtual function of SGRawExtended so that
232 * SGPropertyNode::untie doesn't need to know the type of an
235 virtual SGRawExtended* makeContainer() const = 0;
237 * Write value out to a stream
239 virtual std::ostream& printOn(std::ostream& stream) const = 0;
241 * Read value from a stream and store it.
243 virtual std::istream& readFrom(std::istream& stream) = 0;
246 // Choose between different base classes based on whether the value is
247 // stored internal to the property node. This frees us from defining
248 // the virtual functions in the SGRawExtended interface where they
249 // don't make sense, e.g. readFrom for the const char* type.
250 template<typename T, int internal = simgear::props::PropertyTraits<T>::Internal>
254 class SGRawBase<T, 1> : public SGRaw
259 class SGRawBase<T, 0> : public SGRawExtended
261 virtual SGRawExtended* makeContainer() const;
262 virtual std::ostream& printOn(std::ostream& stream) const;
263 virtual std::istream& readFrom(std::istream& stream);
267 * Abstract base class for a raw value.
269 * <p>The property manager is implemented in two layers. The {@link
270 * SGPropertyNode} is the highest and most abstract layer,
271 * representing an LValue/RValue pair: it records the position of the
272 * property in the property tree and contains facilities for
273 * navigation to other nodes. It is guaranteed to be persistent: the
274 * {@link SGPropertyNode} will not change during a session, even if
275 * the property is bound and unbound multiple times.</p>
277 * <p>When the property value is not managed internally in the
278 * SGPropertyNode, the SGPropertyNode will contain a reference to an
279 * SGRawValue (this class), which provides an abstract way to get,
280 * set, and clone the underlying value. The SGRawValue may change
281 * frequently during a session as a value is retyped or bound and
282 * unbound to various data source, but the abstract SGPropertyNode
283 * layer insulates the application from those changes.
285 * <p>The SGPropertyNode class always keeps a *copy* of a raw value,
286 * not the original one passed to it; if you override a derived class
287 * but do not replace the {@link #clone} method, strange things will
290 * <p>All derived SGRawValue classes must implement {@link #getValue},
291 * {@link #setValue}, and {@link #clone} for the appropriate type.</p>
293 * @see SGPropertyNode
294 * @see SGRawValuePointer
295 * @see SGRawValueFunctions
296 * @see SGRawValueFunctionsIndexed
297 * @see SGRawValueMethods
298 * @see SGRawValueMethodsIndexed
299 * @see SGRawValueContainer
302 class SGRawValue : public SGRawBase<T>
307 * The default underlying value for this type.
309 * Every raw value has a default; the default is false for a
310 * boolean, 0 for the various numeric values, and "" for a string.
311 * If additional types of raw values are added in the future, they
312 * may need different kinds of default values (such as epoch for a
313 * date type). The default value is used when creating new values.
315 static const T DefaultValue; // Default for this kind of raw value.
321 * Use the default value for this type.
329 virtual ~SGRawValue () {}
333 * Return the underlying value.
335 * @return The actual value for the property.
338 virtual T getValue () const = 0;
342 * Assign a new underlying value.
344 * If the new value cannot be set (because this is a read-only
345 * raw value, or because the new value is not acceptable for
346 * some reason) this method returns false and leaves the original
349 * @param value The actual value for the property.
350 * @return true if the value was set successfully, false otherwise.
353 virtual bool setValue (T value) = 0;
357 * Return the type tag for this raw value type.
359 virtual simgear::props::Type getType() const
361 return simgear::props::PropertyTraits<T>::type_tag;
367 ////////////////////////////////////////////////////////////////////////
368 // Default values for every type.
369 ////////////////////////////////////////////////////////////////////////
371 template<> const bool SGRawValue<bool>::DefaultValue;
372 template<> const int SGRawValue<int>::DefaultValue;
373 template<> const long SGRawValue<long>::DefaultValue;
374 template<> const float SGRawValue<float>::DefaultValue;
375 template<> const double SGRawValue<double>::DefaultValue;
376 template<> const char * const SGRawValue<const char *>::DefaultValue;
377 template<> const SGVec3d SGRawValue<SGVec3d>::DefaultValue;
378 template<> const SGVec4d SGRawValue<SGVec4d>::DefaultValue;
381 * A raw value bound to a pointer.
383 * This is the most efficient way to tie an external value, but also
384 * the most dangerous, because there is no way for the supplier to
385 * perform bounds checking and derived calculations except by polling
386 * the variable to see if it has changed. There is no default
387 * constructor, because this class would be meaningless without a
391 class SGRawValuePointer : public SGRawValue<T>
396 * Explicit pointer constructor.
398 * Create a new raw value bound to the value of the variable
399 * referenced by the pointer.
401 * @param ptr The pointer to the variable to which this raw value
404 SGRawValuePointer (T * ptr) : _ptr(ptr) {}
409 virtual ~SGRawValuePointer () {}
412 * Get the underlying value.
414 * This method will dereference the pointer and return the
417 virtual T getValue () const { return *_ptr; }
420 * Set the underlying value.
422 * This method will dereference the pointer and change the
425 virtual bool setValue (T value) { *_ptr = value; return true; }
428 * Create a copy of this raw value.
430 * The copy will use the same external pointer as the original.
432 virtual SGRaw* clone () const {
433 return new SGRawValuePointer(_ptr);
442 * A value managed through static functions.
444 * A read-only value will not have a setter; a write-only value will
448 class SGRawValueFunctions : public SGRawValue<T>
453 * The template type of a static getter function.
455 typedef T (*getter_t)();
458 * The template type of a static setter function.
460 typedef void (*setter_t)(T);
463 * Explicit constructor.
465 * Create a new raw value bound to the getter and setter supplied.
467 * @param getter A static function for getting a value, or 0
468 * to read-disable the value.
469 * @param setter A static function for setting a value, or 0
470 * to write-disable the value.
472 SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
473 : _getter(getter), _setter(setter) {}
478 virtual ~SGRawValueFunctions () {}
481 * Get the underlying value.
483 * This method will invoke the getter function to get a value.
484 * If no getter function was supplied, this method will always
485 * return the default value for the type.
487 virtual T getValue () const {
488 if (_getter) return (*_getter)();
489 else return SGRawValue<T>::DefaultValue;
493 * Set the underlying value.
495 * This method will invoke the setter function to change the
496 * underlying value. If no setter function was supplied, this
497 * method will return false.
499 virtual bool setValue (T value) {
500 if (_setter) { (*_setter)(value); return true; }
505 * Create a copy of this raw value, bound to the same functions.
507 virtual SGRaw* clone () const {
508 return new SGRawValueFunctions(_getter,_setter);
518 * An indexed value bound to static functions.
520 * A read-only value will not have a setter; a write-only value will
521 * not have a getter. An indexed value is useful for binding one
522 * of a list of possible values (such as multiple engines for a
523 * plane). The index is hard-coded at creation time.
528 class SGRawValueFunctionsIndexed : public SGRawValue<T>
531 typedef T (*getter_t)(int);
532 typedef void (*setter_t)(int,T);
533 SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
534 : _index(index), _getter(getter), _setter(setter) {}
535 virtual ~SGRawValueFunctionsIndexed () {}
536 virtual T getValue () const {
537 if (_getter) return (*_getter)(_index);
538 else return SGRawValue<T>::DefaultValue;
540 virtual bool setValue (T value) {
541 if (_setter) { (*_setter)(_index, value); return true; }
544 virtual SGRaw* clone () const {
545 return new SGRawValueFunctionsIndexed(_index, _getter, _setter);
555 * A value managed through an object and access methods.
557 * A read-only value will not have a setter; a write-only value will
560 template <class C, class T>
561 class SGRawValueMethods : public SGRawValue<T>
564 typedef T (C::*getter_t)() const;
565 typedef void (C::*setter_t)(T);
566 SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
567 : _obj(obj), _getter(getter), _setter(setter) {}
568 virtual ~SGRawValueMethods () {}
569 virtual T getValue () const {
570 if (_getter) { return (_obj.*_getter)(); }
571 else { return SGRawValue<T>::DefaultValue; }
573 virtual bool setValue (T value) {
574 if (_setter) { (_obj.*_setter)(value); return true; }
577 virtual SGRaw* clone () const {
578 return new SGRawValueMethods(_obj, _getter, _setter);
588 * An indexed value managed through an object and access methods.
590 * A read-only value will not have a setter; a write-only value will
593 template <class C, class T>
594 class SGRawValueMethodsIndexed : public SGRawValue<T>
597 typedef T (C::*getter_t)(int) const;
598 typedef void (C::*setter_t)(int, T);
599 SGRawValueMethodsIndexed (C &obj, int index,
600 getter_t getter = 0, setter_t setter = 0)
601 : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
602 virtual ~SGRawValueMethodsIndexed () {}
603 virtual T getValue () const {
604 if (_getter) { return (_obj.*_getter)(_index); }
605 else { return SGRawValue<T>::DefaultValue; }
607 virtual bool setValue (T value) {
608 if (_setter) { (_obj.*_setter)(_index, value); return true; }
611 virtual SGRaw* clone () const {
612 return new SGRawValueMethodsIndexed(_obj, _index, _getter, _setter);
622 * A raw value that contains its value. This provides a way for
623 * property nodes to contain values that shouldn't be stored in the
624 * property node itself.
627 class SGRawValueContainer : public SGRawValue<T>
632 * Explicit constructor.
634 SGRawValueContainer(const T& obj) : _obj(obj) {}
639 virtual ~SGRawValueContainer() {}
642 * Get the underlying value.
644 virtual T getValue() const { return _obj; }
647 * Set the underlying value.
649 * This method will dereference the pointer and change the
652 virtual bool setValue (T value) { _obj = value; return true; }
655 * Create a copy of this raw value.
657 virtual SGRaw* clone () const {
658 return new SGRawValueContainer(_obj);
666 SGRawExtended* SGRawBase<T, 0>::makeContainer() const
668 return new SGRawValueContainer<T>(static_cast<const SGRawValue<T>*>(this)
673 std::ostream& SGRawBase<T, 0>::printOn(std::ostream& stream) const
675 return stream << static_cast<SGRawValue<T>*>(this)->getValue();
679 std::istream& SGRawBase<T, 0>::readFrom(std::istream& stream)
682 simgear::readFrom(stream, value);
683 static_cast<SGRawValue<T>*>(this)->setValue(value);
688 std::ostream& SGRawBase<SGVec3d>::printOn(std::ostream& stream) const;
690 std::ostream& SGRawBase<SGVec4d>::printOn(std::ostream& stream) const;
694 * The smart pointer that manage reference counting
696 class SGPropertyNode;
697 typedef SGSharedPtr<SGPropertyNode> SGPropertyNode_ptr;
698 typedef SGSharedPtr<const SGPropertyNode> SGConstPropertyNode_ptr;
702 typedef std::vector<SGPropertyNode_ptr> PropertyList;
707 * The property change listener interface.
709 * <p>Any class that needs to listen for property changes must implement
710 * this interface.</p>
712 class SGPropertyChangeListener
715 virtual ~SGPropertyChangeListener ();
716 virtual void valueChanged (SGPropertyNode * node);
717 virtual void childAdded (SGPropertyNode * parent, SGPropertyNode * child);
718 virtual void childRemoved (SGPropertyNode * parent, SGPropertyNode * child);
721 friend class SGPropertyNode;
722 virtual void register_property (SGPropertyNode * node);
723 virtual void unregister_property (SGPropertyNode * node);
726 std::vector<SGPropertyNode *> _properties;
732 * A node in a property tree.
734 class SGPropertyNode : public SGReferenced
742 MAX_STRING_LEN = 1024
746 * Access mode attributes.
748 * <p>The ARCHIVE attribute is strictly advisory, and controls
749 * whether the property should normally be saved and restored.</p>
763 * Last used attribute
764 * Update as needed when enum Attribute is changed
766 static const int LAST_USED_ATTRIBUTE;
770 * Default constructor.
778 SGPropertyNode (const SGPropertyNode &node);
784 virtual ~SGPropertyNode ();
793 * Test whether this node contains a primitive leaf value.
795 bool hasValue () const { return (_type != simgear::props::NONE); }
799 * Get the node's simple (XML) name.
801 const char * getName () const { return _name.c_str(); }
804 * Get the node's pretty display name, with subscript when needed.
806 std::string getDisplayName (bool simplify = false) const;
810 * Get the node's integer index.
812 int getIndex () const { return _index; }
816 * Get a non-const pointer to the node's parent.
818 SGPropertyNode * getParent () { return _parent; }
822 * Get a const pointer to the node's parent.
824 const SGPropertyNode * getParent () const { return _parent; }
833 * Get the number of child nodes.
835 int nChildren () const { return _children.size(); }
839 * Get a child node by position (*NOT* index).
841 SGPropertyNode * getChild (int position);
845 * Get a const child node by position (*NOT* index).
847 const SGPropertyNode * getChild (int position) const;
851 * Test whether a named child exists.
853 bool hasChild (const char * name, int index = 0) const
855 return (getChild(name, index) != 0);
859 * Test whether a named child exists.
861 bool hasChild (const std::string& name, int index = 0) const
863 return (getChild(name, index) != 0);
867 * Create a child node after the last node with the same name.
869 SGPropertyNode * addChild (const char * name);
872 * Get a child node by name and index.
874 SGPropertyNode * getChild (const char * name, int index = 0,
875 bool create = false);
878 * Get a child node by name and index.
880 SGPropertyNode * getChild (const std::string& name, int index = 0,
882 { return getChild(name.c_str(), index, create); }
886 * Get a const child node by name and index.
888 const SGPropertyNode * getChild (const char * name, int index = 0) const;
891 * Get a const child node by name and index.
893 const SGPropertyNode * getChild (const std::string& name, int index = 0) const
894 { return getChild(name.c_str(), index); }
898 * Get a vector of all children with the specified name.
900 simgear::PropertyList getChildren (const char * name) const;
903 * Get a vector of all children with the specified name.
905 simgear::PropertyList getChildren (const std::string& name) const
906 { return getChildren(name.c_str()); }
909 * Remove child by position.
911 SGPropertyNode_ptr removeChild (int pos, bool keep = true);
915 * Remove a child node
917 SGPropertyNode_ptr removeChild (const char * name, int index = 0,
921 * Remove a child node
923 SGPropertyNode_ptr removeChild (const std::string& name, int index = 0,
925 { return removeChild(name.c_str(), index, keep); }
928 * Remove all children with the specified name.
930 simgear::PropertyList removeChildren (const char * name, bool keep = true);
933 * Remove all children with the specified name.
935 simgear::PropertyList removeChildren (const std::string& name,
937 { return removeChildren(name.c_str(), keep); }
945 * Alias this node's leaf value to another's.
947 bool alias (SGPropertyNode * target);
951 * Alias this node's leaf value to another's by relative path.
953 bool alias (const char * path);
956 * Alias this node's leaf value to another's by relative path.
958 bool alias (const std::string& path)
959 { return alias(path.c_str()); }
963 * Remove any alias for this node.
969 * Test whether the node's leaf value is aliased to another's.
971 bool isAlias () const { return (_type == simgear::props::ALIAS); }
975 * Get a non-const pointer to the current alias target, if any.
977 SGPropertyNode * getAliasTarget ();
981 * Get a const pointer to the current alias target, if any.
983 const SGPropertyNode * getAliasTarget () const;
992 * Get the path to this node from the root.
994 const char * getPath (bool simplify = false) const;
998 * Get a pointer to the root node.
1000 SGPropertyNode * getRootNode ();
1004 * Get a const pointer to the root node.
1006 const SGPropertyNode * getRootNode () const;
1010 * Get a pointer to another node by relative path.
1012 SGPropertyNode * getNode (const char * relative_path, bool create = false);
1015 * Get a pointer to another node by relative path.
1017 SGPropertyNode * getNode (const std::string& relative_path, bool create = false)
1018 { return getNode(relative_path.c_str(), create); }
1021 * Get a pointer to another node by relative path.
1023 * This method leaves the index off the last member of the path,
1024 * so that the user can specify it separately (and save some
1025 * string building). For example, getNode("/bar[1]/foo", 3) is
1026 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
1027 * provided overrides any given in the path itself for the last
1030 SGPropertyNode * getNode (const char * relative_path, int index,
1031 bool create = false);
1034 * Get a pointer to another node by relative path.
1036 * This method leaves the index off the last member of the path,
1037 * so that the user can specify it separately (and save some
1038 * string building). For example, getNode("/bar[1]/foo", 3) is
1039 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
1040 * provided overrides any given in the path itself for the last
1043 SGPropertyNode * getNode (const std::string& relative_path, int index,
1044 bool create = false)
1045 { return getNode(relative_path.c_str(), index, create); }
1048 * Get a const pointer to another node by relative path.
1050 const SGPropertyNode * getNode (const char * relative_path) const;
1053 * Get a const pointer to another node by relative path.
1055 const SGPropertyNode * getNode (const std::string& relative_path) const
1056 { return getNode(relative_path.c_str()); }
1060 * Get a const pointer to another node by relative path.
1062 * This method leaves the index off the last member of the path,
1063 * so that the user can specify it separate.
1065 const SGPropertyNode * getNode (const char * relative_path,
1069 * Get a const pointer to another node by relative path.
1071 * This method leaves the index off the last member of the path,
1072 * so that the user can specify it separate.
1074 const SGPropertyNode * getNode (const std::string& relative_path,
1076 { return getNode(relative_path.c_str(), index); }
1083 * Check a single mode attribute for the property node.
1085 bool getAttribute (Attribute attr) const { return ((_attr & attr) != 0); }
1089 * Set a single mode attribute for the property node.
1091 void setAttribute (Attribute attr, bool state) {
1092 (state ? _attr |= attr : _attr &= ~attr);
1097 * Get all of the mode attributes for the property node.
1099 int getAttributes () const { return _attr; }
1103 * Set all of the mode attributes for the property node.
1105 void setAttributes (int attr) { _attr = attr; }
1109 // Leaf Value (primitive).
1114 * Get the type of leaf value, if any, for this node.
1116 simgear::props::Type getType () const;
1120 * Get a bool value for this node.
1122 bool getBoolValue () const;
1126 * Get an int value for this node.
1128 int getIntValue () const;
1132 * Get a long int value for this node.
1134 long getLongValue () const;
1138 * Get a float value for this node.
1140 float getFloatValue () const;
1144 * Get a double value for this node.
1146 double getDoubleValue () const;
1150 * Get a string value for this node.
1152 const char * getStringValue () const;
1155 * Get a value from a node. If the actual type of the node doesn't
1156 * match the desired type, a conversion isn't guaranteed.
1158 template<typename T>
1159 T getValue(typename boost::enable_if_c<simgear::props::PropertyTraits<T>::Internal>
1160 ::type* dummy = 0) const;
1161 // Getter for extended property
1162 template<typename T>
1163 T getValue(typename boost::disable_if_c<simgear::props::PropertyTraits<T>::Internal>
1164 ::type* dummy = 0) const;
1167 * Set a bool value for this node.
1169 bool setBoolValue (bool value);
1173 * Set an int value for this node.
1175 bool setIntValue (int value);
1179 * Set a long int value for this node.
1181 bool setLongValue (long value);
1185 * Set a float value for this node.
1187 bool setFloatValue (float value);
1191 * Set a double value for this node.
1193 bool setDoubleValue (double value);
1197 * Set a string value for this node.
1199 bool setStringValue (const char * value);
1202 * Set a string value for this node.
1204 bool setStringValue (const std::string& value)
1205 { return setStringValue(value.c_str()); }
1209 * Set a value of unspecified type for this node.
1211 bool setUnspecifiedValue (const char * value);
1213 template<typename T>
1214 bool setValue(const T& val,
1215 typename boost::enable_if_c<simgear::props::PropertyTraits<T>::Internal>
1218 template<typename T>
1219 bool setValue(const T& val,
1220 typename boost::disable_if_c<simgear::props::PropertyTraits<T>::Internal>
1224 * Print the value of the property to a stream.
1226 std::ostream& printOn(std::ostream& stream) const;
1234 * Test whether this node is bound to an external data source.
1236 bool isTied () const { return _tied; }
1239 * Bind this node to an external source.
1241 template<typename T>
1242 bool tie(const SGRawValue<T> &rawValue, bool useDefault = true);
1245 * Unbind this node from any external data source.
1251 // Convenience methods using paths.
1252 // TODO: add attribute methods
1257 * Get another node's type.
1259 simgear::props::Type getType (const char * relative_path) const;
1262 * Get another node's type.
1264 simgear::props::Type getType (const std::string& relative_path) const
1265 { return getType(relative_path.c_str()); }
1268 * Test whether another node has a leaf value.
1270 bool hasValue (const char * relative_path) const;
1273 * Test whether another node has a leaf value.
1275 bool hasValue (const std::string& relative_path) const
1276 { return hasValue(relative_path.c_str()); }
1279 * Get another node's value as a bool.
1281 bool getBoolValue (const char * relative_path,
1282 bool defaultValue = false) const;
1285 * Get another node's value as a bool.
1287 bool getBoolValue (const std::string& relative_path,
1288 bool defaultValue = false) const
1289 { return getBoolValue(relative_path.c_str(), defaultValue); }
1292 * Get another node's value as an int.
1294 int getIntValue (const char * relative_path,
1295 int defaultValue = 0) const;
1298 * Get another node's value as an int.
1300 int getIntValue (const std::string& relative_path,
1301 int defaultValue = 0) const
1302 { return getIntValue(relative_path.c_str(), defaultValue); }
1306 * Get another node's value as a long int.
1308 long getLongValue (const char * relative_path,
1309 long defaultValue = 0L) const;
1312 * Get another node's value as a long int.
1314 long getLongValue (const std::string& relative_path,
1315 long defaultValue = 0L) const
1316 { return getLongValue(relative_path.c_str(), defaultValue); }
1319 * Get another node's value as a float.
1321 float getFloatValue (const char * relative_path,
1322 float defaultValue = 0.0f) const;
1325 * Get another node's value as a float.
1327 float getFloatValue (const std::string& relative_path,
1328 float defaultValue = 0.0f) const
1329 { return getFloatValue(relative_path.c_str(), defaultValue); }
1333 * Get another node's value as a double.
1335 double getDoubleValue (const char * relative_path,
1336 double defaultValue = 0.0) const;
1339 * Get another node's value as a double.
1341 double getDoubleValue (const std::string& relative_path,
1342 double defaultValue = 0.0) const
1343 { return getDoubleValue(relative_path.c_str(), defaultValue); }
1346 * Get another node's value as a string.
1348 const char * getStringValue (const char * relative_path,
1349 const char * defaultValue = "") const;
1353 * Get another node's value as a string.
1355 const char * getStringValue (const std::string& relative_path,
1356 const char * defaultValue = "") const
1357 { return getStringValue(relative_path.c_str(), defaultValue); }
1361 * Set another node's value as a bool.
1363 bool setBoolValue (const char * relative_path, bool value);
1366 * Set another node's value as a bool.
1368 bool setBoolValue (const std::string& relative_path, bool value)
1369 { return setBoolValue(relative_path.c_str(), value); }
1373 * Set another node's value as an int.
1375 bool setIntValue (const char * relative_path, int value);
1378 * Set another node's value as an int.
1380 bool setIntValue (const std::string& relative_path, int value)
1381 { return setIntValue(relative_path.c_str(), value); }
1385 * Set another node's value as a long int.
1387 bool setLongValue (const char * relative_path, long value);
1390 * Set another node's value as a long int.
1392 bool setLongValue (const std::string& relative_path, long value)
1393 { return setLongValue(relative_path.c_str(), value); }
1397 * Set another node's value as a float.
1399 bool setFloatValue (const char * relative_path, float value);
1402 * Set another node's value as a float.
1404 bool setFloatValue (const std::string& relative_path, float value)
1405 { return setFloatValue(relative_path.c_str(), value); }
1409 * Set another node's value as a double.
1411 bool setDoubleValue (const char * relative_path, double value);
1414 * Set another node's value as a double.
1416 bool setDoubleValue (const std::string& relative_path, double value)
1417 { return setDoubleValue(relative_path.c_str(), value); }
1421 * Set another node's value as a string.
1423 bool setStringValue (const char * relative_path, const char * value);
1425 bool setStringValue(const char * relative_path, const std::string& value)
1426 { return setStringValue(relative_path, value.c_str()); }
1428 * Set another node's value as a string.
1430 bool setStringValue (const std::string& relative_path, const char * value)
1431 { return setStringValue(relative_path.c_str(), value); }
1433 bool setStringValue (const std::string& relative_path,
1434 const std::string& value)
1435 { return setStringValue(relative_path.c_str(), value.c_str()); }
1438 * Set another node's value with no specified type.
1440 bool setUnspecifiedValue (const char * relative_path, const char * value);
1444 * Test whether another node is bound to an external data source.
1446 bool isTied (const char * relative_path) const;
1449 * Test whether another node is bound to an external data source.
1451 bool isTied (const std::string& relative_path) const
1452 { return isTied(relative_path.c_str()); }
1455 * Bind another node to an external bool source.
1457 bool tie (const char * relative_path, const SGRawValue<bool> &rawValue,
1458 bool useDefault = true);
1461 * Bind another node to an external bool source.
1463 bool tie (const std::string& relative_path, const SGRawValue<bool> &rawValue,
1464 bool useDefault = true)
1465 { return tie(relative_path.c_str(), rawValue, useDefault); }
1469 * Bind another node to an external int source.
1471 bool tie (const char * relative_path, const SGRawValue<int> &rawValue,
1472 bool useDefault = true);
1475 * Bind another node to an external int source.
1477 bool tie (const std::string& relative_path, const SGRawValue<int> &rawValue,
1478 bool useDefault = true)
1479 { return tie(relative_path.c_str(), rawValue, useDefault); }
1483 * Bind another node to an external long int source.
1485 bool tie (const char * relative_path, const SGRawValue<long> &rawValue,
1486 bool useDefault = true);
1489 * Bind another node to an external long int source.
1491 bool tie (const std::string& relative_path, const SGRawValue<long> &rawValue,
1492 bool useDefault = true)
1493 { return tie(relative_path.c_str(), rawValue, useDefault); }
1497 * Bind another node to an external float source.
1499 bool tie (const char * relative_path, const SGRawValue<float> &rawValue,
1500 bool useDefault = true);
1503 * Bind another node to an external float source.
1505 bool tie (const std::string& relative_path, const SGRawValue<float> &rawValue,
1506 bool useDefault = true)
1507 { return tie(relative_path.c_str(), rawValue, useDefault); }
1511 * Bind another node to an external double source.
1513 bool tie (const char * relative_path, const SGRawValue<double> &rawValue,
1514 bool useDefault = true);
1517 * Bind another node to an external double source.
1519 bool tie (const std::string& relative_path, const SGRawValue<double> &rawValue,
1520 bool useDefault = true)
1521 { return tie(relative_path.c_str(), rawValue, useDefault); }
1525 * Bind another node to an external string source.
1527 bool tie (const char * relative_path, const SGRawValue<const char *> &rawValue,
1528 bool useDefault = true);
1531 * Bind another node to an external string source.
1533 bool tie (const std::string& relative_path, const SGRawValue<const char*> &rawValue,
1534 bool useDefault = true)
1535 { return tie(relative_path.c_str(), rawValue, useDefault); }
1539 * Unbind another node from any external data source.
1541 bool untie (const char * relative_path);
1544 * Unbind another node from any external data source.
1546 bool untie (const std::string& relative_path)
1547 { return untie(relative_path.c_str()); }
1551 * Add a change listener to the property. If "initial" is set call the
1552 * listener initially.
1554 void addChangeListener (SGPropertyChangeListener * listener,
1555 bool initial = false);
1559 * Remove a change listener from the property.
1561 void removeChangeListener (SGPropertyChangeListener * listener);
1565 * Get the number of listeners.
1567 int nListeners () const { return _listeners ? _listeners->size() : 0; }
1571 * Fire a value change event to all listeners.
1573 void fireValueChanged ();
1577 * Fire a child-added event to all listeners.
1579 void fireChildAdded (SGPropertyNode * child);
1583 * Fire a child-removed event to all listeners.
1585 void fireChildRemoved (SGPropertyNode * child);
1589 * Clear any existing value and set the type to NONE.
1596 void fireValueChanged (SGPropertyNode * node);
1597 void fireChildAdded (SGPropertyNode * parent, SGPropertyNode * child);
1598 void fireChildRemoved (SGPropertyNode * parent, SGPropertyNode * child);
1601 * Protected constructor for making new nodes on demand.
1603 SGPropertyNode (const char * name, int index, SGPropertyNode * parent);
1608 // Get the raw value
1609 bool get_bool () const;
1610 int get_int () const;
1611 long get_long () const;
1612 float get_float () const;
1613 double get_double () const;
1614 const char * get_string () const;
1616 // Set the raw value
1617 bool set_bool (bool value);
1618 bool set_int (int value);
1619 bool set_long (long value);
1620 bool set_float (float value);
1621 bool set_double (double value);
1622 bool set_string (const char * value);
1626 * Get the value as a string.
1628 const char * make_string () const;
1631 * Trace a read access.
1633 void trace_read () const;
1637 * Trace a write access.
1639 void trace_write () const;
1643 * Remove this node from all nodes that link to it in their path cache.
1645 void remove_from_path_caches();
1652 /// To avoid cyclic reference counting loops this shall not be a reference
1654 SGPropertyNode * _parent;
1655 simgear::PropertyList _children;
1656 simgear::PropertyList _removedChildren;
1657 std::vector<hash_table *> _linkedNodes;
1658 mutable std::string _path;
1659 mutable std::string _buffer;
1660 hash_table * _path_cache;
1661 simgear::props::Type _type;
1665 // The right kind of pointer...
1667 SGPropertyNode * alias;
1680 std::vector<SGPropertyChangeListener *> * _listeners;
1684 * Register/unregister node that links to this node in its path cache.
1686 void add_linked_node (hash_table * node) { _linkedNodes.push_back(node); }
1687 bool remove_linked_node (hash_table * node);
1692 * A very simple hash table.
1698 * An entry in a bucket in a hash table.
1704 const char * get_key () { return _key.c_str(); }
1705 void set_key (const char * key);
1706 SGPropertyNode * get_value () { return _value; }
1707 void set_value (SGPropertyNode * value);
1710 SGSharedPtr<SGPropertyNode> _value;
1715 * A bucket in a hash table.
1721 entry * get_entry (const char * key, bool create = false);
1722 bool erase (SGPropertyNode * node);
1723 void clear (hash_table * owner);
1729 friend class bucket;
1733 SGPropertyNode * get (const char * key);
1734 void put (const char * key, SGPropertyNode * value);
1735 bool erase (SGPropertyNode * node);
1738 unsigned int hashcode (const char * key);
1739 unsigned int _data_length;
1745 // Convenience functions for use in templates
1746 template<typename T>
1747 T getValue(const SGPropertyNode*);
1750 inline bool getValue<bool>(const SGPropertyNode* node) { return node->getBoolValue(); }
1753 inline int getValue<int>(const SGPropertyNode* node) { return node->getIntValue(); }
1756 inline long getValue<long>(const SGPropertyNode* node) { return node->getLongValue(); }
1759 inline float getValue<float>(const SGPropertyNode* node)
1761 return node->getFloatValue();
1765 inline double getValue<double>(const SGPropertyNode* node)
1767 return node->getDoubleValue();
1771 inline const char * getValue<const char*>(const SGPropertyNode* node)
1773 return node->getStringValue ();
1776 inline bool setValue(SGPropertyNode* node, bool value)
1778 return node->setBoolValue(value);
1781 inline bool setValue(SGPropertyNode* node, int value)
1783 return node->setIntValue(value);
1786 inline bool setValue(SGPropertyNode* node, long value)
1788 return node->setLongValue(value);
1791 inline bool setValue(SGPropertyNode* node, float value)
1793 return node->setFloatValue(value);
1796 inline bool setValue(SGPropertyNode* node, double value)
1798 return node->setDoubleValue(value);
1801 inline bool setValue(SGPropertyNode* node, const char* value)
1803 return node->setStringValue(value);
1806 inline bool setValue (SGPropertyNode* node, const std::string& value)
1808 return node->setStringValue(value.c_str());
1811 template<typename T>
1812 bool SGPropertyNode::tie(const SGRawValue<T> &rawValue, bool useDefault)
1814 using namespace simgear::props;
1815 if (_type == ALIAS || _tied)
1818 useDefault = useDefault && hasValue();
1819 T old_val = SGRawValue<T>::DefaultValue;
1821 old_val = getValue<T>(this);
1823 if (PropertyTraits<T>::Internal)
1824 _type = PropertyTraits<T>::type_tag;
1828 _value.val = rawValue.clone();
1835 bool SGPropertyNode::tie (const SGRawValue<const char *> &rawValue,
1838 template<typename T>
1839 T SGPropertyNode::getValue(typename boost::disable_if_c<simgear::props
1840 ::PropertyTraits<T>::Internal>::type* dummy) const
1842 using namespace simgear::props;
1843 if (_attr == (READ|WRITE) && _type == EXTENDED
1844 && _value.val->getType() == PropertyTraits<T>::type_tag) {
1845 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
1847 if (getAttribute(TRACE_READ))
1849 if (!getAttribute(READ))
1850 return SGRawValue<T>::DefaultValue;
1853 if (_value.val->getType() == PropertyTraits<T>::type_tag)
1854 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
1858 return simgear::parseString<T>(make_string());
1861 return SGRawValue<T>::DefaultValue;
1864 template<typename T>
1865 inline T SGPropertyNode::getValue(typename boost::enable_if_c<simgear::props
1866 ::PropertyTraits<T>::Internal>::type* dummy) const
1868 return ::getValue<T>(this);
1871 template<typename T>
1872 bool SGPropertyNode::setValue(const T& val,
1873 typename boost::disable_if_c<simgear::props
1874 ::PropertyTraits<T>::Internal>::type* dummy)
1876 using namespace simgear::props;
1877 if (_attr == (READ|WRITE) && _type == EXTENDED
1878 && _value.val->getType() == PropertyTraits<T>::type_tag) {
1879 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
1882 if (getAttribute(WRITE)
1883 && ((_type == EXTENDED
1884 && _value.val->getType() == PropertyTraits<T>::type_tag)
1885 || _type == NONE || _type == UNSPECIFIED)) {
1886 if (_type == NONE || _type == UNSPECIFIED) {
1889 _value.val = new SGRawValueContainer<T>(val);
1891 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
1893 if (getAttribute(TRACE_WRITE))
1900 template<typename T>
1901 inline bool SGPropertyNode::setValue(const T& val,
1902 typename boost::enable_if_c<simgear::props
1903 ::PropertyTraits<T>::Internal>::type* dummy)
1905 return ::setValue(this, val);
1909 * Utility function for creation of a child property node
1911 inline SGPropertyNode* makeChild(SGPropertyNode* parent, const char* name,
1914 return parent->getChild(name, index, true);
1916 #endif // __PROPS_HXX