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>
34 #include <simgear/structure/SGReferenced.hxx>
35 #include <simgear/structure/SGSharedPtr.hxx>
37 // XXX This whole file should be in the simgear namespace, but I don't
38 // have the guts yet...
43 std::istream& readFrom(std::istream& stream, T& result)
50 * Parse a string as an object of a given type.
51 * XXX no error behavior yet.
53 * @tparam T the return type
54 * @param str the string
58 inline T parseString(const std::string& str)
60 std::istringstream stream(str);
62 readFrom(stream, result);
67 * Property value types.
71 #pragma warn A sloppy coder has defined NONE as a macro!
76 #pragma warn A sloppy coder has defined ALIAS as a macro!
81 #pragma warn A sloppy coder has defined UNSPECIFIED as a macro!
86 #pragma warn A sloppy coder has defined BOOL as a macro!
91 #pragma warn A sloppy coder has defined INT as a macro!
96 #pragma warn A sloppy coder has defined LONG as a macro!
101 #pragma warn A sloppy coder has defined FLOAT as a macro!
106 #pragma warn A sloppy coder has defined DOUBLE as a macro!
111 #pragma warn A sloppy coder has defined STRING as a macro!
118 * The possible types of an SGPropertyNode. Types that appear after
119 * EXTENDED are not stored in the SGPropertyNode itself.
122 NONE = 0, /**< The node hasn't been assigned a value yet. */
123 ALIAS, /**< The node "points" to another node. */
131 EXTENDED /**< The node's value is not stored in the property;
132 * the actual value and type is retrieved from an
133 * SGRawValue node. This type is never returned by @see
134 * SGPropertyNode::getType.
138 template<typename T> struct PropertyTraits;
140 #define DEFINTERNALPROP(TYPE, PROP) \
142 struct PropertyTraits<TYPE> \
144 static const Type type_tag = PROP; \
145 enum { Internal = 1 }; \
148 DEFINTERNALPROP(bool, BOOL);
149 DEFINTERNALPROP(int, INT);
150 DEFINTERNALPROP(long, LONG);
151 DEFINTERNALPROP(float, FLOAT);
152 DEFINTERNALPROP(double, DOUBLE);
153 DEFINTERNALPROP(const char *, STRING);
154 #undef DEFINTERNALPROP
162 ////////////////////////////////////////////////////////////////////////
165 // This is the mechanism that information-providing routines can
166 // use to link their own values to the property manager. Any
167 // SGValue can be tied to a raw value and then untied again.
169 // Note: we are forced to use inlined methods here to ensure
170 // that the templates will be instantiated. We're probably taking
171 // a small performance hit for that.
172 ////////////////////////////////////////////////////////////////////////
175 * Base class for SGRawValue classes that holds no type
176 * information. This allows some generic manipulation of the
183 * Get the type enumeration for the raw value.
187 virtual simgear::props::Type getType() const = 0;
191 * Create a new deep copy of this raw value.
193 * The copy will contain its own version of the underlying value
194 * as well, and will be the same type.
196 * @return A deep copy of the current object.
198 virtual SGRaw* clone() const = 0;
202 class SGRawExtended : public SGRaw
206 * Make an SGRawValueContainer from the SGRawValue.
208 * This is a virtual function of SGRawExtended so that
209 * SGPropertyNode::untie doesn't need to know the type of an
212 virtual SGRawExtended* makeContainer() const = 0;
214 * Write value out to a stream
216 virtual std::ostream& printOn(std::ostream& stream) const = 0;
218 * Read value from a stream and store it.
220 virtual std::istream& readFrom(std::istream& stream) = 0;
223 // Choose between different base classes based on whether the value is
224 // stored internal to the property node. This frees us from defining
225 // the virtual functions in the SGRawExtended interface where they
226 // don't make sense, e.g. readFrom for the const char* type.
227 template<typename T, int internal = simgear::props::PropertyTraits<T>::Internal>
231 class SGRawBase<T, 1> : public SGRaw
236 class SGRawBase<T, 0> : public SGRawExtended
238 virtual SGRawExtended* makeContainer() const;
239 virtual std::ostream& printOn(std::ostream& stream) const;
240 virtual std::istream& readFrom(std::istream& stream);
244 * Abstract base class for a raw value.
246 * <p>The property manager is implemented in two layers. The {@link
247 * SGPropertyNode} is the highest and most abstract layer,
248 * representing an LValue/RValue pair: it records the position of the
249 * property in the property tree and contains facilities for
250 * navigation to other nodes. It is guaranteed to be persistent: the
251 * {@link SGPropertyNode} will not change during a session, even if
252 * the property is bound and unbound multiple times.</p>
254 * <p>When the property value is not managed internally in the
255 * SGPropertyNode, the SGPropertyNode will contain a reference to an
256 * SGRawValue (this class), which provides an abstract way to get,
257 * set, and clone the underlying value. The SGRawValue may change
258 * frequently during a session as a value is retyped or bound and
259 * unbound to various data source, but the abstract SGPropertyNode
260 * layer insulates the application from those changes.
262 * <p>The SGPropertyNode class always keeps a *copy* of a raw value,
263 * not the original one passed to it; if you override a derived class
264 * but do not replace the {@link #clone} method, strange things will
267 * <p>All derived SGRawValue classes must implement {@link #getValue},
268 * {@link #setValue}, and {@link #clone} for the appropriate type.</p>
270 * @see SGPropertyNode
271 * @see SGRawValuePointer
272 * @see SGRawValueFunctions
273 * @see SGRawValueFunctionsIndexed
274 * @see SGRawValueMethods
275 * @see SGRawValueMethodsIndexed
276 * @see SGRawValueContainer
279 class SGRawValue : public SGRawBase<T>
284 * The default underlying value for this type.
286 * Every raw value has a default; the default is false for a
287 * boolean, 0 for the various numeric values, and "" for a string.
288 * If additional types of raw values are added in the future, they
289 * may need different kinds of default values (such as epoch for a
290 * date type). The default value is used when creating new values.
292 static const T DefaultValue; // Default for this kind of raw value.
298 * Use the default value for this type.
306 virtual ~SGRawValue () {}
310 * Return the underlying value.
312 * @return The actual value for the property.
315 virtual T getValue () const = 0;
319 * Assign a new underlying value.
321 * If the new value cannot be set (because this is a read-only
322 * raw value, or because the new value is not acceptable for
323 * some reason) this method returns false and leaves the original
326 * @param value The actual value for the property.
327 * @return true if the value was set successfully, false otherwise.
330 virtual bool setValue (T value) = 0;
334 * Return the type tag for this raw value type.
336 virtual simgear::props::Type getType() const
338 return simgear::props::PropertyTraits<T>::type_tag;
344 ////////////////////////////////////////////////////////////////////////
345 // Default values for every type.
346 ////////////////////////////////////////////////////////////////////////
348 template<> const bool SGRawValue<bool>::DefaultValue;
349 template<> const int SGRawValue<int>::DefaultValue;
350 template<> const long SGRawValue<long>::DefaultValue;
351 template<> const float SGRawValue<float>::DefaultValue;
352 template<> const double SGRawValue<double>::DefaultValue;
353 template<> const char * const SGRawValue<const char *>::DefaultValue;
356 * A raw value bound to a pointer.
358 * This is the most efficient way to tie an external value, but also
359 * the most dangerous, because there is no way for the supplier to
360 * perform bounds checking and derived calculations except by polling
361 * the variable to see if it has changed. There is no default
362 * constructor, because this class would be meaningless without a
366 class SGRawValuePointer : public SGRawValue<T>
371 * Explicit pointer constructor.
373 * Create a new raw value bound to the value of the variable
374 * referenced by the pointer.
376 * @param ptr The pointer to the variable to which this raw value
379 SGRawValuePointer (T * ptr) : _ptr(ptr) {}
384 virtual ~SGRawValuePointer () {}
387 * Get the underlying value.
389 * This method will dereference the pointer and return the
392 virtual T getValue () const { return *_ptr; }
395 * Set the underlying value.
397 * This method will dereference the pointer and change the
400 virtual bool setValue (T value) { *_ptr = value; return true; }
403 * Create a copy of this raw value.
405 * The copy will use the same external pointer as the original.
407 virtual SGRaw* clone () const {
408 return new SGRawValuePointer(_ptr);
417 * A value managed through static functions.
419 * A read-only value will not have a setter; a write-only value will
423 class SGRawValueFunctions : public SGRawValue<T>
428 * The template type of a static getter function.
430 typedef T (*getter_t)();
433 * The template type of a static setter function.
435 typedef void (*setter_t)(T);
438 * Explicit constructor.
440 * Create a new raw value bound to the getter and setter supplied.
442 * @param getter A static function for getting a value, or 0
443 * to read-disable the value.
444 * @param setter A static function for setting a value, or 0
445 * to write-disable the value.
447 SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
448 : _getter(getter), _setter(setter) {}
453 virtual ~SGRawValueFunctions () {}
456 * Get the underlying value.
458 * This method will invoke the getter function to get a value.
459 * If no getter function was supplied, this method will always
460 * return the default value for the type.
462 virtual T getValue () const {
463 if (_getter) return (*_getter)();
464 else return SGRawValue<T>::DefaultValue;
468 * Set the underlying value.
470 * This method will invoke the setter function to change the
471 * underlying value. If no setter function was supplied, this
472 * method will return false.
474 virtual bool setValue (T value) {
475 if (_setter) { (*_setter)(value); return true; }
480 * Create a copy of this raw value, bound to the same functions.
482 virtual SGRaw* clone () const {
483 return new SGRawValueFunctions(_getter,_setter);
493 * An indexed value bound to static functions.
495 * A read-only value will not have a setter; a write-only value will
496 * not have a getter. An indexed value is useful for binding one
497 * of a list of possible values (such as multiple engines for a
498 * plane). The index is hard-coded at creation time.
503 class SGRawValueFunctionsIndexed : public SGRawValue<T>
506 typedef T (*getter_t)(int);
507 typedef void (*setter_t)(int,T);
508 SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
509 : _index(index), _getter(getter), _setter(setter) {}
510 virtual ~SGRawValueFunctionsIndexed () {}
511 virtual T getValue () const {
512 if (_getter) return (*_getter)(_index);
513 else return SGRawValue<T>::DefaultValue;
515 virtual bool setValue (T value) {
516 if (_setter) { (*_setter)(_index, value); return true; }
519 virtual SGRaw* clone () const {
520 return new SGRawValueFunctionsIndexed(_index, _getter, _setter);
530 * A value managed through an object and access methods.
532 * A read-only value will not have a setter; a write-only value will
535 template <class C, class T>
536 class SGRawValueMethods : public SGRawValue<T>
539 typedef T (C::*getter_t)() const;
540 typedef void (C::*setter_t)(T);
541 SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
542 : _obj(obj), _getter(getter), _setter(setter) {}
543 virtual ~SGRawValueMethods () {}
544 virtual T getValue () const {
545 if (_getter) { return (_obj.*_getter)(); }
546 else { return SGRawValue<T>::DefaultValue; }
548 virtual bool setValue (T value) {
549 if (_setter) { (_obj.*_setter)(value); return true; }
552 virtual SGRaw* clone () const {
553 return new SGRawValueMethods(_obj, _getter, _setter);
563 * An indexed value managed through an object and access methods.
565 * A read-only value will not have a setter; a write-only value will
568 template <class C, class T>
569 class SGRawValueMethodsIndexed : public SGRawValue<T>
572 typedef T (C::*getter_t)(int) const;
573 typedef void (C::*setter_t)(int, T);
574 SGRawValueMethodsIndexed (C &obj, int index,
575 getter_t getter = 0, setter_t setter = 0)
576 : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
577 virtual ~SGRawValueMethodsIndexed () {}
578 virtual T getValue () const {
579 if (_getter) { return (_obj.*_getter)(_index); }
580 else { return SGRawValue<T>::DefaultValue; }
582 virtual bool setValue (T value) {
583 if (_setter) { (_obj.*_setter)(_index, value); return true; }
586 virtual SGRaw* clone () const {
587 return new SGRawValueMethodsIndexed(_obj, _index, _getter, _setter);
597 * A raw value that contains its value. This provides a way for
598 * property nodes to contain values that shouldn't be stored in the
599 * property node itself.
602 class SGRawValueContainer : public SGRawValue<T>
607 * Explicit constructor.
609 SGRawValueContainer(const T& obj) : _obj(obj) {}
614 virtual ~SGRawValueContainer() {}
617 * Get the underlying value.
619 virtual T getValue() const { return _obj; }
622 * Set the underlying value.
624 * This method will dereference the pointer and change the
627 virtual bool setValue (T value) { _obj = value; return true; }
630 * Create a copy of this raw value.
632 virtual SGRaw* clone () const {
633 return new SGRawValueContainer(_obj);
641 SGRawExtended* SGRawBase<T, 0>::makeContainer() const
643 return new SGRawValueContainer<T>(static_cast<const SGRawValue<T>*>(this)
648 std::ostream& SGRawBase<T, 0>::printOn(std::ostream& stream) const
650 return stream << static_cast<SGRawValue<T>*>(this)->getValue();
654 std::istream& SGRawBase<T, 0>::readFrom(std::istream& stream)
657 simgear::readFrom(stream, value);
658 static_cast<SGRawValue<T>*>(this)->setValue(value);
663 * The smart pointer that manage reference counting
665 class SGPropertyNode;
666 typedef SGSharedPtr<SGPropertyNode> SGPropertyNode_ptr;
667 typedef SGSharedPtr<const SGPropertyNode> SGConstPropertyNode_ptr;
671 * The property change listener interface.
673 * <p>Any class that needs to listen for property changes must implement
674 * this interface.</p>
676 class SGPropertyChangeListener
679 virtual ~SGPropertyChangeListener ();
680 virtual void valueChanged (SGPropertyNode * node);
681 virtual void childAdded (SGPropertyNode * parent, SGPropertyNode * child);
682 virtual void childRemoved (SGPropertyNode * parent, SGPropertyNode * child);
685 friend class SGPropertyNode;
686 virtual void register_property (SGPropertyNode * node);
687 virtual void unregister_property (SGPropertyNode * node);
690 std::vector<SGPropertyNode *> _properties;
696 * A node in a property tree.
698 class SGPropertyNode : public SGReferenced
706 MAX_STRING_LEN = 1024
710 * Access mode attributes.
712 * <p>The ARCHIVE attribute is strictly advisory, and controls
713 * whether the property should normally be saved and restored.</p>
727 * Last used attribute
728 * Update as needed when enum Attribute is changed
730 static const int LAST_USED_ATTRIBUTE;
734 * Default constructor.
742 SGPropertyNode (const SGPropertyNode &node);
748 virtual ~SGPropertyNode ();
757 * Test whether this node contains a primitive leaf value.
759 bool hasValue () const { return (_type != simgear::props::NONE); }
763 * Get the node's simple (XML) name.
765 const char * getName () const { return _name.c_str(); }
769 * Get the node's pretty display name, with subscript when needed.
771 const char * getDisplayName (bool simplify = false) const;
775 * Get the node's integer index.
777 int getIndex () const { return _index; }
781 * Get a non-const pointer to the node's parent.
783 SGPropertyNode * getParent () { return _parent; }
787 * Get a const pointer to the node's parent.
789 const SGPropertyNode * getParent () const { return _parent; }
798 * Get the number of child nodes.
800 int nChildren () const { return _children.size(); }
804 * Get a child node by position (*NOT* index).
806 SGPropertyNode * getChild (int position);
810 * Get a const child node by position (*NOT* index).
812 const SGPropertyNode * getChild (int position) const;
816 * Test whether a named child exists.
818 bool hasChild (const char * name, int index = 0) const
820 return (getChild(name, index) != 0);
824 * Test whether a named child exists.
826 bool hasChild (const std::string& name, int index = 0) const
828 return (getChild(name, index) != 0);
832 * Create a child node after the last node with the same name.
834 SGPropertyNode * addChild (const char * name);
837 * Get a child node by name and index.
839 SGPropertyNode * getChild (const char * name, int index = 0,
840 bool create = false);
843 * Get a child node by name and index.
845 SGPropertyNode * getChild (const std::string& name, int index = 0,
847 { return getChild(name.c_str(), index, create); }
851 * Get a const child node by name and index.
853 const SGPropertyNode * getChild (const char * name, int index = 0) const;
856 * Get a const child node by name and index.
858 const SGPropertyNode * getChild (const std::string& name, int index = 0) const
859 { return getChild(name.c_str(), index); }
863 * Get a vector of all children with the specified name.
865 std::vector<SGPropertyNode_ptr> getChildren (const char * name) const;
868 * Get a vector of all children with the specified name.
870 std::vector<SGPropertyNode_ptr> getChildren (const std::string& name) const
871 { return getChildren(name.c_str()); }
874 * Remove child by position.
876 SGPropertyNode_ptr removeChild (int pos, bool keep = true);
880 * Remove a child node
882 SGPropertyNode_ptr removeChild (const char * name, int index = 0,
886 * Remove a child node
888 SGPropertyNode_ptr removeChild (const std::string& name, int index = 0,
890 { return removeChild(name.c_str(), index, keep); }
893 * Remove all children with the specified name.
895 std::vector<SGPropertyNode_ptr> removeChildren (const char * name,
900 * Remove all children with the specified name.
902 std::vector<SGPropertyNode_ptr> removeChildren (const std::string& name,
904 { return removeChildren(name.c_str(), keep); }
912 * Alias this node's leaf value to another's.
914 bool alias (SGPropertyNode * target);
918 * Alias this node's leaf value to another's by relative path.
920 bool alias (const char * path);
923 * Alias this node's leaf value to another's by relative path.
925 bool alias (const std::string& path)
926 { return alias(path.c_str()); }
930 * Remove any alias for this node.
936 * Test whether the node's leaf value is aliased to another's.
938 bool isAlias () const { return (_type == simgear::props::ALIAS); }
942 * Get a non-const pointer to the current alias target, if any.
944 SGPropertyNode * getAliasTarget ();
948 * Get a const pointer to the current alias target, if any.
950 const SGPropertyNode * getAliasTarget () const;
959 * Get the path to this node from the root.
961 const char * getPath (bool simplify = false) const;
965 * Get a pointer to the root node.
967 SGPropertyNode * getRootNode ();
971 * Get a const pointer to the root node.
973 const SGPropertyNode * getRootNode () const;
977 * Get a pointer to another node by relative path.
979 SGPropertyNode * getNode (const char * relative_path, bool create = false);
982 * Get a pointer to another node by relative path.
984 SGPropertyNode * getNode (const std::string& relative_path, bool create = false)
985 { return getNode(relative_path.c_str(), create); }
988 * Get a pointer to another node by relative path.
990 * This method leaves the index off the last member of the path,
991 * so that the user can specify it separately (and save some
992 * string building). For example, getNode("/bar[1]/foo", 3) is
993 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
994 * provided overrides any given in the path itself for the last
997 SGPropertyNode * getNode (const char * relative_path, int index,
998 bool create = false);
1001 * Get a pointer to another node by relative path.
1003 * This method leaves the index off the last member of the path,
1004 * so that the user can specify it separately (and save some
1005 * string building). For example, getNode("/bar[1]/foo", 3) is
1006 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
1007 * provided overrides any given in the path itself for the last
1010 SGPropertyNode * getNode (const std::string& relative_path, int index,
1011 bool create = false)
1012 { return getNode(relative_path.c_str(), index, create); }
1015 * Get a const pointer to another node by relative path.
1017 const SGPropertyNode * getNode (const char * relative_path) const;
1020 * Get a const pointer to another node by relative path.
1022 const SGPropertyNode * getNode (const std::string& relative_path) const
1023 { return getNode(relative_path.c_str()); }
1027 * Get a const pointer to another node by relative path.
1029 * This method leaves the index off the last member of the path,
1030 * so that the user can specify it separate.
1032 const SGPropertyNode * getNode (const char * relative_path,
1036 * Get a const pointer to another node by relative path.
1038 * This method leaves the index off the last member of the path,
1039 * so that the user can specify it separate.
1041 const SGPropertyNode * getNode (const std::string& relative_path,
1043 { return getNode(relative_path.c_str(), index); }
1050 * Check a single mode attribute for the property node.
1052 bool getAttribute (Attribute attr) const { return ((_attr & attr) != 0); }
1056 * Set a single mode attribute for the property node.
1058 void setAttribute (Attribute attr, bool state) {
1059 (state ? _attr |= attr : _attr &= ~attr);
1064 * Get all of the mode attributes for the property node.
1066 int getAttributes () const { return _attr; }
1070 * Set all of the mode attributes for the property node.
1072 void setAttributes (int attr) { _attr = attr; }
1076 // Leaf Value (primitive).
1081 * Get the type of leaf value, if any, for this node.
1083 simgear::props::Type getType () const;
1087 * Get a bool value for this node.
1089 bool getBoolValue () const;
1093 * Get an int value for this node.
1095 int getIntValue () const;
1099 * Get a long int value for this node.
1101 long getLongValue () const;
1105 * Get a float value for this node.
1107 float getFloatValue () const;
1111 * Get a double value for this node.
1113 double getDoubleValue () const;
1117 * Get a string value for this node.
1119 const char * getStringValue () const;
1122 * Get a value from a node. If the actual type of the node doesn't
1123 * match the desired type, a conversion isn't guaranteed.
1125 template<typename T>
1126 T getValue(typename boost::enable_if_c<simgear::props::PropertyTraits<T>::Internal>
1127 ::type* dummy = 0) const;
1128 // Getter for extended property
1129 template<typename T>
1130 T getValue(typename boost::disable_if_c<simgear::props::PropertyTraits<T>::Internal>
1131 ::type* dummy = 0) const;
1134 * Set a bool value for this node.
1136 bool setBoolValue (bool value);
1140 * Set an int value for this node.
1142 bool setIntValue (int value);
1146 * Set a long int value for this node.
1148 bool setLongValue (long value);
1152 * Set a float value for this node.
1154 bool setFloatValue (float value);
1158 * Set a double value for this node.
1160 bool setDoubleValue (double value);
1164 * Set a string value for this node.
1166 bool setStringValue (const char * value);
1169 * Set a string value for this node.
1171 bool setStringValue (const std::string& value)
1172 { return setStringValue(value.c_str()); }
1176 * Set a value of unspecified type for this node.
1178 bool setUnspecifiedValue (const char * value);
1180 template<typename T>
1181 bool setValue(const T& val,
1182 typename boost::enable_if_c<simgear::props::PropertyTraits<T>::Internal>
1185 template<typename T>
1186 bool setValue(const T& val,
1187 typename boost::disable_if_c<simgear::props::PropertyTraits<T>::Internal>
1191 * Print the value of the property to a stream.
1193 std::ostream& printOn(std::ostream& stream) const;
1201 * Test whether this node is bound to an external data source.
1203 bool isTied () const { return _tied; }
1206 * Bind this node to an external source.
1208 template<typename T>
1209 bool tie(const SGRawValue<T> &rawValue, bool useDefault = true);
1212 * Unbind this node from any external data source.
1218 // Convenience methods using paths.
1219 // TODO: add attribute methods
1224 * Get another node's type.
1226 simgear::props::Type getType (const char * relative_path) const;
1229 * Get another node's type.
1231 simgear::props::Type getType (const std::string& relative_path) const
1232 { return getType(relative_path.c_str()); }
1235 * Test whether another node has a leaf value.
1237 bool hasValue (const char * relative_path) const;
1240 * Test whether another node has a leaf value.
1242 bool hasValue (const std::string& relative_path) const
1243 { return hasValue(relative_path.c_str()); }
1246 * Get another node's value as a bool.
1248 bool getBoolValue (const char * relative_path,
1249 bool defaultValue = false) const;
1252 * Get another node's value as a bool.
1254 bool getBoolValue (const std::string& relative_path,
1255 bool defaultValue = false) const
1256 { return getBoolValue(relative_path.c_str(), defaultValue); }
1259 * Get another node's value as an int.
1261 int getIntValue (const char * relative_path,
1262 int defaultValue = 0) const;
1265 * Get another node's value as an int.
1267 int getIntValue (const std::string& relative_path,
1268 int defaultValue = 0) const
1269 { return getIntValue(relative_path.c_str(), defaultValue); }
1273 * Get another node's value as a long int.
1275 long getLongValue (const char * relative_path,
1276 long defaultValue = 0L) const;
1279 * Get another node's value as a long int.
1281 long getLongValue (const std::string& relative_path,
1282 long defaultValue = 0L) const
1283 { return getLongValue(relative_path.c_str(), defaultValue); }
1286 * Get another node's value as a float.
1288 float getFloatValue (const char * relative_path,
1289 float defaultValue = 0.0f) const;
1292 * Get another node's value as a float.
1294 float getFloatValue (const std::string& relative_path,
1295 float defaultValue = 0.0f) const
1296 { return getFloatValue(relative_path.c_str(), defaultValue); }
1300 * Get another node's value as a double.
1302 double getDoubleValue (const char * relative_path,
1303 double defaultValue = 0.0) const;
1306 * Get another node's value as a double.
1308 double getDoubleValue (const std::string& relative_path,
1309 double defaultValue = 0.0) const
1310 { return getDoubleValue(relative_path.c_str(), defaultValue); }
1313 * Get another node's value as a string.
1315 const char * getStringValue (const char * relative_path,
1316 const char * defaultValue = "") const;
1320 * Get another node's value as a string.
1322 const char * getStringValue (const std::string& relative_path,
1323 const char * defaultValue = "") const
1324 { return getStringValue(relative_path.c_str(), defaultValue); }
1328 * Set another node's value as a bool.
1330 bool setBoolValue (const char * relative_path, bool value);
1333 * Set another node's value as a bool.
1335 bool setBoolValue (const std::string& relative_path, bool value)
1336 { return setBoolValue(relative_path.c_str(), value); }
1340 * Set another node's value as an int.
1342 bool setIntValue (const char * relative_path, int value);
1345 * Set another node's value as an int.
1347 bool setIntValue (const std::string& relative_path, int value)
1348 { return setIntValue(relative_path.c_str(), value); }
1352 * Set another node's value as a long int.
1354 bool setLongValue (const char * relative_path, long value);
1357 * Set another node's value as a long int.
1359 bool setLongValue (const std::string& relative_path, long value)
1360 { return setLongValue(relative_path.c_str(), value); }
1364 * Set another node's value as a float.
1366 bool setFloatValue (const char * relative_path, float value);
1369 * Set another node's value as a float.
1371 bool setFloatValue (const std::string& relative_path, float value)
1372 { return setFloatValue(relative_path.c_str(), value); }
1376 * Set another node's value as a double.
1378 bool setDoubleValue (const char * relative_path, double value);
1381 * Set another node's value as a double.
1383 bool setDoubleValue (const std::string& relative_path, double value)
1384 { return setDoubleValue(relative_path.c_str(), value); }
1388 * Set another node's value as a string.
1390 bool setStringValue (const char * relative_path, const char * value);
1393 * Set another node's value as a string.
1395 bool setStringValue (const std::string& relative_path, const char * value)
1396 { return setStringValue(relative_path.c_str(), value); }
1400 * Set another node's value with no specified type.
1402 bool setUnspecifiedValue (const char * relative_path, const char * value);
1406 * Test whether another node is bound to an external data source.
1408 bool isTied (const char * relative_path) const;
1411 * Test whether another node is bound to an external data source.
1413 bool isTied (const std::string& relative_path) const
1414 { return isTied(relative_path.c_str()); }
1417 * Bind another node to an external bool source.
1419 bool tie (const char * relative_path, const SGRawValue<bool> &rawValue,
1420 bool useDefault = true);
1423 * Bind another node to an external bool source.
1425 bool tie (const std::string& relative_path, const SGRawValue<bool> &rawValue,
1426 bool useDefault = true)
1427 { return tie(relative_path.c_str(), rawValue, useDefault); }
1431 * Bind another node to an external int source.
1433 bool tie (const char * relative_path, const SGRawValue<int> &rawValue,
1434 bool useDefault = true);
1437 * Bind another node to an external int source.
1439 bool tie (const std::string& relative_path, const SGRawValue<int> &rawValue,
1440 bool useDefault = true)
1441 { return tie(relative_path.c_str(), rawValue, useDefault); }
1445 * Bind another node to an external long int source.
1447 bool tie (const char * relative_path, const SGRawValue<long> &rawValue,
1448 bool useDefault = true);
1451 * Bind another node to an external long int source.
1453 bool tie (const std::string& relative_path, const SGRawValue<long> &rawValue,
1454 bool useDefault = true)
1455 { return tie(relative_path.c_str(), rawValue, useDefault); }
1459 * Bind another node to an external float source.
1461 bool tie (const char * relative_path, const SGRawValue<float> &rawValue,
1462 bool useDefault = true);
1465 * Bind another node to an external float source.
1467 bool tie (const std::string& relative_path, const SGRawValue<float> &rawValue,
1468 bool useDefault = true)
1469 { return tie(relative_path.c_str(), rawValue, useDefault); }
1473 * Bind another node to an external double source.
1475 bool tie (const char * relative_path, const SGRawValue<double> &rawValue,
1476 bool useDefault = true);
1479 * Bind another node to an external double source.
1481 bool tie (const std::string& relative_path, const SGRawValue<double> &rawValue,
1482 bool useDefault = true)
1483 { return tie(relative_path.c_str(), rawValue, useDefault); }
1487 * Bind another node to an external string source.
1489 bool tie (const char * relative_path, const SGRawValue<const char *> &rawValue,
1490 bool useDefault = true);
1493 * Bind another node to an external string source.
1495 bool tie (const std::string& relative_path, const SGRawValue<const char*> &rawValue,
1496 bool useDefault = true)
1497 { return tie(relative_path.c_str(), rawValue, useDefault); }
1501 * Unbind another node from any external data source.
1503 bool untie (const char * relative_path);
1506 * Unbind another node from any external data source.
1508 bool untie (const std::string& relative_path)
1509 { return untie(relative_path.c_str()); }
1513 * Add a change listener to the property. If "initial" is set call the
1514 * listener initially.
1516 void addChangeListener (SGPropertyChangeListener * listener,
1517 bool initial = false);
1521 * Remove a change listener from the property.
1523 void removeChangeListener (SGPropertyChangeListener * listener);
1527 * Get the number of listeners.
1529 int nListeners () const { return _listeners ? _listeners->size() : 0; }
1533 * Fire a value change event to all listeners.
1535 void fireValueChanged ();
1539 * Fire a child-added event to all listeners.
1541 void fireChildAdded (SGPropertyNode * child);
1545 * Fire a child-removed event to all listeners.
1547 void fireChildRemoved (SGPropertyNode * child);
1551 * Clear any existing value and set the type to NONE.
1558 void fireValueChanged (SGPropertyNode * node);
1559 void fireChildAdded (SGPropertyNode * parent, SGPropertyNode * child);
1560 void fireChildRemoved (SGPropertyNode * parent, SGPropertyNode * child);
1563 * Protected constructor for making new nodes on demand.
1565 SGPropertyNode (const char * name, int index, SGPropertyNode * parent);
1570 // Get the raw value
1571 bool get_bool () const;
1572 int get_int () const;
1573 long get_long () const;
1574 float get_float () const;
1575 double get_double () const;
1576 const char * get_string () const;
1578 // Set the raw value
1579 bool set_bool (bool value);
1580 bool set_int (int value);
1581 bool set_long (long value);
1582 bool set_float (float value);
1583 bool set_double (double value);
1584 bool set_string (const char * value);
1588 * Get the value as a string.
1590 const char * make_string () const;
1593 * Trace a read access.
1595 void trace_read () const;
1599 * Trace a write access.
1601 void trace_write () const;
1605 * Remove this node from all nodes that link to it in their path cache.
1607 void remove_from_path_caches();
1614 mutable std::string _display_name;
1615 /// To avoid cyclic reference counting loops this shall not be a reference
1617 SGPropertyNode * _parent;
1618 std::vector<SGPropertyNode_ptr> _children;
1619 std::vector<SGPropertyNode_ptr> _removedChildren;
1620 std::vector<hash_table *> _linkedNodes;
1621 mutable std::string _path;
1622 mutable std::string _buffer;
1623 hash_table * _path_cache;
1624 simgear::props::Type _type;
1628 // The right kind of pointer...
1630 SGPropertyNode * alias;
1643 std::vector<SGPropertyChangeListener *> * _listeners;
1647 * Register/unregister node that links to this node in its path cache.
1649 void add_linked_node (hash_table * node) { _linkedNodes.push_back(node); }
1650 bool remove_linked_node (hash_table * node);
1655 * A very simple hash table.
1661 * An entry in a bucket in a hash table.
1667 const char * get_key () { return _key.c_str(); }
1668 void set_key (const char * key);
1669 SGPropertyNode * get_value () { return _value; }
1670 void set_value (SGPropertyNode * value);
1673 SGSharedPtr<SGPropertyNode> _value;
1678 * A bucket in a hash table.
1684 entry * get_entry (const char * key, bool create = false);
1685 bool erase (SGPropertyNode * node);
1686 void clear (hash_table * owner);
1692 friend class bucket;
1696 SGPropertyNode * get (const char * key);
1697 void put (const char * key, SGPropertyNode * value);
1698 bool erase (SGPropertyNode * node);
1701 unsigned int hashcode (const char * key);
1702 unsigned int _data_length;
1708 // Convenience functions for use in templates
1709 template<typename T>
1710 T getValue(const SGPropertyNode*);
1713 inline bool getValue<bool>(const SGPropertyNode* node) { return node->getBoolValue(); }
1716 inline int getValue<int>(const SGPropertyNode* node) { return node->getIntValue(); }
1719 inline long getValue<long>(const SGPropertyNode* node) { return node->getLongValue(); }
1722 inline float getValue<float>(const SGPropertyNode* node)
1724 return node->getFloatValue();
1728 inline double getValue<double>(const SGPropertyNode* node)
1730 return node->getDoubleValue();
1734 inline const char * getValue<const char*>(const SGPropertyNode* node)
1736 return node->getStringValue ();
1739 inline bool setValue(SGPropertyNode* node, bool value)
1741 return node->setBoolValue(value);
1744 inline bool setValue(SGPropertyNode* node, int value)
1746 return node->setIntValue(value);
1749 inline bool setValue(SGPropertyNode* node, long value)
1751 return node->setLongValue(value);
1754 inline bool setValue(SGPropertyNode* node, float value)
1756 return node->setFloatValue(value);
1759 inline bool setValue(SGPropertyNode* node, double value)
1761 return node->setDoubleValue(value);
1764 inline bool setValue(SGPropertyNode* node, const char* value)
1766 return node->setStringValue(value);
1769 inline bool setValue (SGPropertyNode* node, const std::string& value)
1771 return node->setStringValue(value.c_str());
1774 template<typename T>
1775 bool SGPropertyNode::tie(const SGRawValue<T> &rawValue, bool useDefault)
1777 using namespace simgear::props;
1778 if (_type == ALIAS || _tied)
1781 useDefault = useDefault && hasValue();
1782 T old_val = SGRawValue<T>::DefaultValue;
1784 old_val = getValue<T>(this);
1786 if (PropertyTraits<T>::Internal)
1787 _type = PropertyTraits<T>::type_tag;
1791 _value.val = rawValue.clone();
1798 bool SGPropertyNode::tie (const SGRawValue<const char *> &rawValue,
1801 template<typename T>
1802 T SGPropertyNode::getValue(typename boost::disable_if_c<simgear::props
1803 ::PropertyTraits<T>::Internal>::type* dummy) const
1805 using namespace simgear::props;
1806 if (_attr == (READ|WRITE) && _type == EXTENDED
1807 && _value.val->getType() == PropertyTraits<T>::type_tag) {
1808 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
1810 if (getAttribute(TRACE_READ))
1812 if (!getAttribute(READ))
1813 return SGRawValue<T>::DefaultValue;
1816 if (_value.val->getType() == PropertyTraits<T>::type_tag)
1817 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
1821 return simgear::parseString<T>(make_string());
1824 return SGRawValue<T>::DefaultValue;
1827 template<typename T>
1828 inline T SGPropertyNode::getValue(typename boost::enable_if_c<simgear::props
1829 ::PropertyTraits<T>::Internal>::type* dummy) const
1831 return ::getValue<T>(this);
1834 template<typename T>
1835 bool SGPropertyNode::setValue(const T& val,
1836 typename boost::disable_if_c<simgear::props
1837 ::PropertyTraits<T>::Internal>::type* dummy)
1839 using namespace simgear::props;
1840 if (_attr == (READ|WRITE) && _type == EXTENDED
1841 && _value.val->getType() == PropertyTraits<T>::type_tag) {
1842 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
1845 if (getAttribute(WRITE)
1846 && ((_type == EXTENDED
1847 && _value.val->getType() == PropertyTraits<T>::type_tag)
1848 || _type == NONE || _type == UNSPECIFIED)) {
1849 if (_type == NONE || _type == UNSPECIFIED) {
1852 _value.val = new SGRawValueContainer<T>(val);
1854 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
1856 if (getAttribute(TRACE_WRITE))
1863 template<typename T>
1864 inline bool SGPropertyNode::setValue(const T& val,
1865 typename boost::enable_if_c<simgear::props
1866 ::PropertyTraits<T>::Internal>::type* dummy)
1868 return ::setValue(this, val);
1870 #endif // __PROPS_HXX