3 * Interface definition for a property list.
4 * Started Fall 2000 by David Megginson, david@megginson.com
5 * This code is released into the Public Domain.
7 * See props.html for documentation [replace with URL when available].
15 #ifndef PROPS_STANDALONE
16 #define PROPS_STANDALONE 0
24 #include <boost/utility.hpp>
28 #include <simgear/compiler.h>
29 #include <simgear/debug/logstream.hxx>
33 #include <simgear/math/SGMathFwd.hxx>
34 #include <simgear/structure/SGReferenced.hxx>
35 #include <simgear/structure/SGSharedPtr.hxx>
37 // XXX This whole file should be in the simgear namespace, but I don't
38 // have the guts yet...
43 std::istream& readFrom(std::istream& stream, T& result)
50 * Parse a string as an object of a given type.
51 * XXX no error behavior yet.
53 * @tparam T the return type
54 * @param str the string
58 inline T parseString(const std::string& str)
60 std::istringstream stream(str);
62 readFrom(stream, result);
67 * Property value types.
71 #pragma warn A sloppy coder has defined NONE as a macro!
76 #pragma warn A sloppy coder has defined ALIAS as a macro!
81 #pragma warn A sloppy coder has defined UNSPECIFIED as a macro!
86 #pragma warn A sloppy coder has defined BOOL as a macro!
91 #pragma warn A sloppy coder has defined INT as a macro!
96 #pragma warn A sloppy coder has defined LONG as a macro!
101 #pragma warn A sloppy coder has defined FLOAT as a macro!
106 #pragma warn A sloppy coder has defined DOUBLE as a macro!
111 #pragma warn A sloppy coder has defined STRING as a macro!
118 * The possible types of an SGPropertyNode. Types that appear after
119 * EXTENDED are not stored in the SGPropertyNode itself.
122 NONE = 0, /**< The node hasn't been assigned a value yet. */
123 ALIAS, /**< The node "points" to another node. */
131 EXTENDED, /**< The node's value is not stored in the property;
132 * the actual value and type is retrieved from an
133 * SGRawValue node. This type is never returned by @see
134 * SGPropertyNode::getType.
136 // Extended properties
141 template<typename T> struct PropertyTraits;
143 #define DEFINTERNALPROP(TYPE, PROP) \
145 struct PropertyTraits<TYPE> \
147 static const Type type_tag = PROP; \
148 enum { Internal = 1 }; \
151 DEFINTERNALPROP(bool, BOOL);
152 DEFINTERNALPROP(int, INT);
153 DEFINTERNALPROP(long, LONG);
154 DEFINTERNALPROP(float, FLOAT);
155 DEFINTERNALPROP(double, DOUBLE);
156 DEFINTERNALPROP(const char *, STRING);
157 DEFINTERNALPROP(const char[], STRING);
158 #undef DEFINTERNALPROP
165 ////////////////////////////////////////////////////////////////////////
168 // This is the mechanism that information-providing routines can
169 // use to link their own values to the property manager. Any
170 // SGValue can be tied to a raw value and then untied again.
172 // Note: we are forced to use inlined methods here to ensure
173 // that the templates will be instantiated. We're probably taking
174 // a small performance hit for that.
175 ////////////////////////////////////////////////////////////////////////
178 * Base class for SGRawValue classes that holds no type
179 * information. This allows some generic manipulation of the
186 * Get the type enumeration for the raw value.
190 virtual simgear::props::Type getType() const = 0;
194 * Create a new deep copy of this raw value.
196 * The copy will contain its own version of the underlying value
197 * as well, and will be the same type.
199 * @return A deep copy of the current object.
201 virtual SGRaw* clone() const = 0;
205 class SGRawExtended : public SGRaw
209 * Make an SGRawValueContainer from the SGRawValue.
211 * This is a virtual function of SGRawExtended so that
212 * SGPropertyNode::untie doesn't need to know the type of an
215 virtual SGRawExtended* makeContainer() const = 0;
217 * Write value out to a stream
219 virtual std::ostream& printOn(std::ostream& stream) const = 0;
221 * Read value from a stream and store it.
223 virtual std::istream& readFrom(std::istream& stream) = 0;
226 // Choose between different base classes based on whether the value is
227 // stored internal to the property node. This frees us from defining
228 // the virtual functions in the SGRawExtended interface where they
229 // don't make sense, e.g. readFrom for the const char* type.
230 template<typename T, int internal = simgear::props::PropertyTraits<T>::Internal>
234 class SGRawBase<T, 1> : public SGRaw
239 class SGRawBase<T, 0> : public SGRawExtended
241 virtual SGRawExtended* makeContainer() const;
242 virtual std::ostream& printOn(std::ostream& stream) const;
243 virtual std::istream& readFrom(std::istream& stream);
247 * Abstract base class for a raw value.
249 * <p>The property manager is implemented in two layers. The {@link
250 * SGPropertyNode} is the highest and most abstract layer,
251 * representing an LValue/RValue pair: it records the position of the
252 * property in the property tree and contains facilities for
253 * navigation to other nodes. It is guaranteed to be persistent: the
254 * {@link SGPropertyNode} will not change during a session, even if
255 * the property is bound and unbound multiple times.</p>
257 * <p>When the property value is not managed internally in the
258 * SGPropertyNode, the SGPropertyNode will contain a reference to an
259 * SGRawValue (this class), which provides an abstract way to get,
260 * set, and clone the underlying value. The SGRawValue may change
261 * frequently during a session as a value is retyped or bound and
262 * unbound to various data source, but the abstract SGPropertyNode
263 * layer insulates the application from those changes.
265 * <p>The SGPropertyNode class always keeps a *copy* of a raw value,
266 * not the original one passed to it; if you override a derived class
267 * but do not replace the {@link #clone} method, strange things will
270 * <p>All derived SGRawValue classes must implement {@link #getValue},
271 * {@link #setValue}, and {@link #clone} for the appropriate type.</p>
273 * @see SGPropertyNode
274 * @see SGRawValuePointer
275 * @see SGRawValueFunctions
276 * @see SGRawValueFunctionsIndexed
277 * @see SGRawValueMethods
278 * @see SGRawValueMethodsIndexed
279 * @see SGRawValueContainer
282 class SGRawValue : public SGRawBase<T>
287 * The default underlying value for this type.
289 * Every raw value has a default; the default is false for a
290 * boolean, 0 for the various numeric values, and "" for a string.
291 * If additional types of raw values are added in the future, they
292 * may need different kinds of default values (such as epoch for a
293 * date type). The default value is used when creating new values.
295 static T DefaultValue()
304 * Use the default value for this type.
312 virtual ~SGRawValue () {}
316 * Return the underlying value.
318 * @return The actual value for the property.
321 virtual T getValue () const = 0;
325 * Assign a new underlying value.
327 * If the new value cannot be set (because this is a read-only
328 * raw value, or because the new value is not acceptable for
329 * some reason) this method returns false and leaves the original
332 * @param value The actual value for the property.
333 * @return true if the value was set successfully, false otherwise.
336 virtual bool setValue (T value) = 0;
340 * Return the type tag for this raw value type.
342 virtual simgear::props::Type getType() const
344 return simgear::props::PropertyTraits<T>::type_tag;
350 ////////////////////////////////////////////////////////////////////////
351 // Default values for every type.
352 ////////////////////////////////////////////////////////////////////////
354 template<> inline bool SGRawValue<bool>::DefaultValue()
359 template<> inline const char * SGRawValue<const char *>::DefaultValue()
365 * A raw value bound to a pointer.
367 * This is the most efficient way to tie an external value, but also
368 * the most dangerous, because there is no way for the supplier to
369 * perform bounds checking and derived calculations except by polling
370 * the variable to see if it has changed. There is no default
371 * constructor, because this class would be meaningless without a
375 class SGRawValuePointer : public SGRawValue<T>
380 * Explicit pointer constructor.
382 * Create a new raw value bound to the value of the variable
383 * referenced by the pointer.
385 * @param ptr The pointer to the variable to which this raw value
388 SGRawValuePointer (T * ptr) : _ptr(ptr) {}
393 virtual ~SGRawValuePointer () {}
396 * Get the underlying value.
398 * This method will dereference the pointer and return the
401 virtual T getValue () const { return *_ptr; }
404 * Set the underlying value.
406 * This method will dereference the pointer and change the
409 virtual bool setValue (T value) { *_ptr = value; return true; }
412 * Create a copy of this raw value.
414 * The copy will use the same external pointer as the original.
416 virtual SGRaw* clone () const {
417 return new SGRawValuePointer(_ptr);
426 * A value managed through static functions.
428 * A read-only value will not have a setter; a write-only value will
432 class SGRawValueFunctions : public SGRawValue<T>
437 * The template type of a static getter function.
439 typedef T (*getter_t)();
442 * The template type of a static setter function.
444 typedef void (*setter_t)(T);
447 * Explicit constructor.
449 * Create a new raw value bound to the getter and setter supplied.
451 * @param getter A static function for getting a value, or 0
452 * to read-disable the value.
453 * @param setter A static function for setting a value, or 0
454 * to write-disable the value.
456 SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
457 : _getter(getter), _setter(setter) {}
462 virtual ~SGRawValueFunctions () {}
465 * Get the underlying value.
467 * This method will invoke the getter function to get a value.
468 * If no getter function was supplied, this method will always
469 * return the default value for the type.
471 virtual T getValue () const {
472 if (_getter) return (*_getter)();
473 else return SGRawValue<T>::DefaultValue();
477 * Set the underlying value.
479 * This method will invoke the setter function to change the
480 * underlying value. If no setter function was supplied, this
481 * method will return false.
483 virtual bool setValue (T value) {
484 if (_setter) { (*_setter)(value); return true; }
489 * Create a copy of this raw value, bound to the same functions.
491 virtual SGRaw* clone () const {
492 return new SGRawValueFunctions(_getter,_setter);
502 * An indexed value bound to static functions.
504 * A read-only value will not have a setter; a write-only value will
505 * not have a getter. An indexed value is useful for binding one
506 * of a list of possible values (such as multiple engines for a
507 * plane). The index is hard-coded at creation time.
512 class SGRawValueFunctionsIndexed : public SGRawValue<T>
515 typedef T (*getter_t)(int);
516 typedef void (*setter_t)(int,T);
517 SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
518 : _index(index), _getter(getter), _setter(setter) {}
519 virtual ~SGRawValueFunctionsIndexed () {}
520 virtual T getValue () const {
521 if (_getter) return (*_getter)(_index);
522 else return SGRawValue<T>::DefaultValue();
524 virtual bool setValue (T value) {
525 if (_setter) { (*_setter)(_index, value); return true; }
528 virtual SGRaw* clone () const {
529 return new SGRawValueFunctionsIndexed(_index, _getter, _setter);
539 * A value managed through an object and access methods.
541 * A read-only value will not have a setter; a write-only value will
544 template <class C, class T>
545 class SGRawValueMethods : public SGRawValue<T>
548 typedef T (C::*getter_t)() const;
549 typedef void (C::*setter_t)(T);
550 SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
551 : _obj(obj), _getter(getter), _setter(setter) {}
552 virtual ~SGRawValueMethods () {}
553 virtual T getValue () const {
554 if (_getter) { return (_obj.*_getter)(); }
555 else { return SGRawValue<T>::DefaultValue(); }
557 virtual bool setValue (T value) {
558 if (_setter) { (_obj.*_setter)(value); return true; }
561 virtual SGRaw* clone () const {
562 return new SGRawValueMethods(_obj, _getter, _setter);
572 * An indexed value managed through an object and access methods.
574 * A read-only value will not have a setter; a write-only value will
577 template <class C, class T>
578 class SGRawValueMethodsIndexed : public SGRawValue<T>
581 typedef T (C::*getter_t)(int) const;
582 typedef void (C::*setter_t)(int, T);
583 SGRawValueMethodsIndexed (C &obj, int index,
584 getter_t getter = 0, setter_t setter = 0)
585 : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
586 virtual ~SGRawValueMethodsIndexed () {}
587 virtual T getValue () const {
588 if (_getter) { return (_obj.*_getter)(_index); }
589 else { return SGRawValue<T>::DefaultValue(); }
591 virtual bool setValue (T value) {
592 if (_setter) { (_obj.*_setter)(_index, value); return true; }
595 virtual SGRaw* clone () const {
596 return new SGRawValueMethodsIndexed(_obj, _index, _getter, _setter);
606 * A raw value that contains its value. This provides a way for
607 * property nodes to contain values that shouldn't be stored in the
608 * property node itself.
611 class SGRawValueContainer : public SGRawValue<T>
616 * Explicit constructor.
618 SGRawValueContainer(const T& obj) : _obj(obj) {}
623 virtual ~SGRawValueContainer() {}
626 * Get the underlying value.
628 virtual T getValue() const { return _obj; }
631 * Set the underlying value.
633 * This method will dereference the pointer and change the
636 virtual bool setValue (T value) { _obj = value; return true; }
639 * Create a copy of this raw value.
641 virtual SGRaw* clone () const {
642 return new SGRawValueContainer(_obj);
650 SGRawExtended* SGRawBase<T, 0>::makeContainer() const
652 return new SGRawValueContainer<T>(static_cast<const SGRawValue<T>*>(this)
657 std::ostream& SGRawBase<T, 0>::printOn(std::ostream& stream) const
659 return stream << static_cast<SGRawValue<T>*>(this)->getValue();
663 std::istream& SGRawBase<T, 0>::readFrom(std::istream& stream)
666 simgear::readFrom(stream, value);
667 static_cast<SGRawValue<T>*>(this)->setValue(value);
672 * The smart pointer that manage reference counting
674 class SGPropertyNode;
675 typedef SGSharedPtr<SGPropertyNode> SGPropertyNode_ptr;
676 typedef SGSharedPtr<const SGPropertyNode> SGConstPropertyNode_ptr;
680 typedef std::vector<SGPropertyNode_ptr> PropertyList;
684 * The property change listener interface.
686 * <p>Any class that needs to listen for property changes must implement
687 * this interface.</p>
689 class SGPropertyChangeListener
692 virtual ~SGPropertyChangeListener ();
693 virtual void valueChanged (SGPropertyNode * node);
694 virtual void childAdded (SGPropertyNode * parent, SGPropertyNode * child);
695 virtual void childRemoved (SGPropertyNode * parent, SGPropertyNode * child);
698 friend class SGPropertyNode;
699 virtual void register_property (SGPropertyNode * node);
700 virtual void unregister_property (SGPropertyNode * node);
703 std::vector<SGPropertyNode *> _properties;
708 * A node in a property tree.
710 class SGPropertyNode : public SGReferenced
718 MAX_STRING_LEN = 1024
722 * Access mode attributes.
724 * <p>The ARCHIVE attribute is strictly advisory, and controls
725 * whether the property should normally be saved and restored.</p>
736 // beware: if you add another attribute here,
737 // also update value of "LAST_USED_ATTRIBUTE".
742 * Last used attribute
743 * Update as needed when enum Attribute is changed
745 static const int LAST_USED_ATTRIBUTE;
748 * Default constructor.
756 SGPropertyNode (const SGPropertyNode &node);
762 virtual ~SGPropertyNode ();
771 * Test whether this node contains a primitive leaf value.
773 bool hasValue () const { return (_type != simgear::props::NONE); }
777 * Get the node's simple (XML) name.
779 const char * getName () const { return _name.c_str(); }
782 * Get the node's simple name as a string.
784 const std::string& getNameString () const { return _name; }
787 * Get the node's pretty display name, with subscript when needed.
789 std::string getDisplayName (bool simplify = false) const;
793 * Get the node's integer index.
795 int getIndex () const { return _index; }
799 * Get a non-const pointer to the node's parent.
801 SGPropertyNode * getParent () { return _parent; }
805 * Get a const pointer to the node's parent.
807 const SGPropertyNode * getParent () const { return _parent; }
816 * Get the number of child nodes.
818 int nChildren () const { return (int)_children.size(); }
822 * Get a child node by position (*NOT* index).
824 SGPropertyNode * getChild (int position);
828 * Get a const child node by position (*NOT* index).
830 const SGPropertyNode * getChild (int position) const;
834 * Test whether a named child exists.
836 bool hasChild (const char * name, int index = 0) const
838 return (getChild(name, index) != 0);
842 * Test whether a named child exists.
844 bool hasChild (const std::string& name, int index = 0) const
846 return (getChild(name, index) != 0);
850 * Create a new child node with the given name and an unused index
852 * @param min_index Minimal index for new node (skips lower indices)
853 * @param append Whether to simply use the index after the last used index
854 * or use a lower, unused index if it exists
856 SGPropertyNode * addChild ( const char* name,
858 bool append = true );
859 SGPropertyNode * addChild ( const std::string& name,
862 { return addChild(name.c_str(), min_index, append); }
865 * Create multiple child nodes with the given name an unused indices
867 * @param count The number of nodes create
868 * @param min_index Minimal index for new nodes (skips lower indices)
869 * @param append Whether to simply use the index after the last used index
870 * or use a lower, unused index if it exists
872 simgear::PropertyList addChildren ( const std::string& name,
875 bool append = true );
878 * Get a child node by name and index.
880 SGPropertyNode * getChild (const char* name, int index = 0,
881 bool create = false);
882 SGPropertyNode * getChild (const std::string& name, int index = 0,
883 bool create = false);
885 * Get a const child node by name and index.
887 const SGPropertyNode * getChild (const char * name, int index = 0) const;
890 * Get a const child node by name and index.
892 const SGPropertyNode * getChild (const std::string& name, int index = 0) const
893 { return getChild(name.c_str(), index); }
897 * Get a vector of all children with the specified name.
899 simgear::PropertyList getChildren (const char * name) const;
902 * Get a vector of all children with the specified name.
904 simgear::PropertyList getChildren (const std::string& name) const
905 { return getChildren(name.c_str()); }
908 * Remove child by position.
910 SGPropertyNode_ptr removeChild (int pos, bool keep = true);
914 * Remove a child node
916 SGPropertyNode_ptr removeChild (const char * name, int index = 0,
920 * Remove a child node
922 SGPropertyNode_ptr removeChild (const std::string& name, int index = 0,
924 { return removeChild(name.c_str(), index, keep); }
927 * Remove all children with the specified name.
929 simgear::PropertyList removeChildren (const char * name, bool keep = true);
932 * Remove all children with the specified name.
934 simgear::PropertyList removeChildren (const std::string& name,
936 { return removeChildren(name.c_str(), keep); }
944 * Alias this node's leaf value to another's.
946 bool alias (SGPropertyNode * target);
950 * Alias this node's leaf value to another's by relative path.
952 bool alias (const char * path);
955 * Alias this node's leaf value to another's by relative path.
957 bool alias (const std::string& path)
958 { return alias(path.c_str()); }
962 * Remove any alias for this node.
968 * Test whether the node's leaf value is aliased to another's.
970 bool isAlias () const { return (_type == simgear::props::ALIAS); }
974 * Get a non-const pointer to the current alias target, if any.
976 SGPropertyNode * getAliasTarget ();
980 * Get a const pointer to the current alias target, if any.
982 const SGPropertyNode * getAliasTarget () const;
991 * Get the path to this node from the root.
993 std::string getPath (bool simplify = false) const;
997 * Get a pointer to the root node.
999 SGPropertyNode * getRootNode ();
1003 * Get a const pointer to the root node.
1005 const SGPropertyNode * getRootNode () const;
1009 * Get a pointer to another node by relative path.
1011 SGPropertyNode * getNode (const char * relative_path, bool create = false);
1014 * Get a pointer to another node by relative path.
1016 SGPropertyNode * getNode (const std::string& relative_path, bool create = false)
1017 { return getNode(relative_path.c_str(), create); }
1020 * Get a pointer to another node by relative path.
1022 * This method leaves the index off the last member of the path,
1023 * so that the user can specify it separately (and save some
1024 * string building). For example, getNode("/bar[1]/foo", 3) is
1025 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
1026 * provided overrides any given in the path itself for the last
1029 SGPropertyNode * getNode (const char * relative_path, int index,
1030 bool create = false);
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 std::string& relative_path, int index,
1043 bool create = false)
1044 { return getNode(relative_path.c_str(), index, create); }
1047 * Get a const pointer to another node by relative path.
1049 const SGPropertyNode * getNode (const char * relative_path) const;
1052 * Get a const pointer to another node by relative path.
1054 const SGPropertyNode * getNode (const std::string& relative_path) const
1055 { return getNode(relative_path.c_str()); }
1059 * Get a const pointer to another node by relative path.
1061 * This method leaves the index off the last member of the path,
1062 * so that the user can specify it separate.
1064 const SGPropertyNode * getNode (const char * relative_path,
1068 * Get a const pointer to another node by relative path.
1070 * This method leaves the index off the last member of the path,
1071 * so that the user can specify it separate.
1073 const SGPropertyNode * getNode (const std::string& relative_path,
1075 { return getNode(relative_path.c_str(), index); }
1082 * Check a single mode attribute for the property node.
1084 bool getAttribute (Attribute attr) const { return ((_attr & attr) != 0); }
1088 * Set a single mode attribute for the property node.
1090 void setAttribute (Attribute attr, bool state) {
1091 (state ? _attr |= attr : _attr &= ~attr);
1096 * Get all of the mode attributes for the property node.
1098 int getAttributes () const { return _attr; }
1102 * Set all of the mode attributes for the property node.
1104 void setAttributes (int attr) { _attr = attr; }
1108 // Leaf Value (primitive).
1113 * Get the type of leaf value, if any, for this node.
1115 simgear::props::Type getType () const;
1119 * Get a bool value for this node.
1121 bool getBoolValue () const;
1125 * Get an int value for this node.
1127 int getIntValue () const;
1131 * Get a long int value for this node.
1133 long getLongValue () const;
1137 * Get a float value for this node.
1139 float getFloatValue () const;
1143 * Get a double value for this node.
1145 double getDoubleValue () const;
1149 * Get a string value for this node.
1151 const char * getStringValue () const;
1154 * Get a value from a node. If the actual type of the node doesn't
1155 * match the desired type, a conversion isn't guaranteed.
1157 template<typename T>
1158 T getValue(typename boost::enable_if_c<simgear::props::PropertyTraits<T>::Internal>
1159 ::type* dummy = 0) const;
1160 // Getter for extended property
1161 template<typename T>
1162 T getValue(typename boost::disable_if_c<simgear::props::PropertyTraits<T>::Internal>
1163 ::type* dummy = 0) const;
1166 * Get a list of values from all children with the given name
1168 template<typename T, typename T_get /* = T */> // TODO use C++11 or traits
1169 std::vector<T> getChildValues(const std::string& name) const;
1172 * Get a list of values from all children with the given name
1174 template<typename T>
1175 std::vector<T> getChildValues(const std::string& name) const;
1178 * Set a bool value for this node.
1180 bool setBoolValue (bool value);
1184 * Set an int value for this node.
1186 bool setIntValue (int value);
1190 * Set a long int value for this node.
1192 bool setLongValue (long value);
1196 * Set a float value for this node.
1198 bool setFloatValue (float value);
1202 * Set a double value for this node.
1204 bool setDoubleValue (double value);
1208 * Set a string value for this node.
1210 bool setStringValue (const char * value);
1213 * Set a string value for this node.
1215 bool setStringValue (const std::string& value)
1216 { return setStringValue(value.c_str()); }
1220 * Set a value of unspecified type for this node.
1222 bool setUnspecifiedValue (const char * value);
1224 template<typename T>
1225 bool setValue(const T& val,
1226 typename boost::enable_if_c<simgear::props::PropertyTraits<T>::Internal>
1229 template<typename T>
1230 bool setValue(const T& val,
1231 typename boost::disable_if_c<simgear::props::PropertyTraits<T>::Internal>
1235 bool setValue(const char (&val)[N])
1237 return setValue(&val[0]);
1241 * Print the value of the property to a stream.
1243 std::ostream& printOn(std::ostream& stream) const;
1251 * Test whether this node is bound to an external data source.
1253 bool isTied () const { return _tied; }
1256 * Bind this node to an external source.
1258 template<typename T>
1259 bool tie(const SGRawValue<T> &rawValue, bool useDefault = true);
1262 * Unbind this node from any external data source.
1268 // Convenience methods using paths.
1269 // TODO: add attribute methods
1274 * Get another node's type.
1276 simgear::props::Type getType (const char * relative_path) const;
1279 * Get another node's type.
1281 simgear::props::Type getType (const std::string& relative_path) const
1282 { return getType(relative_path.c_str()); }
1285 * Test whether another node has a leaf value.
1287 bool hasValue (const char * relative_path) const;
1290 * Test whether another node has a leaf value.
1292 bool hasValue (const std::string& relative_path) const
1293 { return hasValue(relative_path.c_str()); }
1296 * Get another node's value as a bool.
1298 bool getBoolValue (const char * relative_path,
1299 bool defaultValue = false) const;
1302 * Get another node's value as a bool.
1304 bool getBoolValue (const std::string& relative_path,
1305 bool defaultValue = false) const
1306 { return getBoolValue(relative_path.c_str(), defaultValue); }
1309 * Get another node's value as an int.
1311 int getIntValue (const char * relative_path,
1312 int defaultValue = 0) const;
1315 * Get another node's value as an int.
1317 int getIntValue (const std::string& relative_path,
1318 int defaultValue = 0) const
1319 { return getIntValue(relative_path.c_str(), defaultValue); }
1323 * Get another node's value as a long int.
1325 long getLongValue (const char * relative_path,
1326 long defaultValue = 0L) const;
1329 * Get another node's value as a long int.
1331 long getLongValue (const std::string& relative_path,
1332 long defaultValue = 0L) const
1333 { return getLongValue(relative_path.c_str(), defaultValue); }
1336 * Get another node's value as a float.
1338 float getFloatValue (const char * relative_path,
1339 float defaultValue = 0.0f) const;
1342 * Get another node's value as a float.
1344 float getFloatValue (const std::string& relative_path,
1345 float defaultValue = 0.0f) const
1346 { return getFloatValue(relative_path.c_str(), defaultValue); }
1350 * Get another node's value as a double.
1352 double getDoubleValue (const char * relative_path,
1353 double defaultValue = 0.0) const;
1356 * Get another node's value as a double.
1358 double getDoubleValue (const std::string& relative_path,
1359 double defaultValue = 0.0) const
1360 { return getDoubleValue(relative_path.c_str(), defaultValue); }
1363 * Get another node's value as a string.
1365 const char * getStringValue (const char * relative_path,
1366 const char * defaultValue = "") const;
1370 * Get another node's value as a string.
1372 const char * getStringValue (const std::string& relative_path,
1373 const char * defaultValue = "") const
1374 { return getStringValue(relative_path.c_str(), defaultValue); }
1378 * Set another node's value as a bool.
1380 bool setBoolValue (const char * relative_path, bool value);
1383 * Set another node's value as a bool.
1385 bool setBoolValue (const std::string& relative_path, bool value)
1386 { return setBoolValue(relative_path.c_str(), value); }
1390 * Set another node's value as an int.
1392 bool setIntValue (const char * relative_path, int value);
1395 * Set another node's value as an int.
1397 bool setIntValue (const std::string& relative_path, int value)
1398 { return setIntValue(relative_path.c_str(), value); }
1402 * Set another node's value as a long int.
1404 bool setLongValue (const char * relative_path, long value);
1407 * Set another node's value as a long int.
1409 bool setLongValue (const std::string& relative_path, long value)
1410 { return setLongValue(relative_path.c_str(), value); }
1414 * Set another node's value as a float.
1416 bool setFloatValue (const char * relative_path, float value);
1419 * Set another node's value as a float.
1421 bool setFloatValue (const std::string& relative_path, float value)
1422 { return setFloatValue(relative_path.c_str(), value); }
1426 * Set another node's value as a double.
1428 bool setDoubleValue (const char * relative_path, double value);
1431 * Set another node's value as a double.
1433 bool setDoubleValue (const std::string& relative_path, double value)
1434 { return setDoubleValue(relative_path.c_str(), value); }
1438 * Set another node's value as a string.
1440 bool setStringValue (const char * relative_path, const char * value);
1442 bool setStringValue(const char * relative_path, const std::string& value)
1443 { return setStringValue(relative_path, value.c_str()); }
1445 * Set another node's value as a string.
1447 bool setStringValue (const std::string& relative_path, const char * value)
1448 { return setStringValue(relative_path.c_str(), value); }
1450 bool setStringValue (const std::string& relative_path,
1451 const std::string& value)
1452 { return setStringValue(relative_path.c_str(), value.c_str()); }
1455 * Set another node's value with no specified type.
1457 bool setUnspecifiedValue (const char * relative_path, const char * value);
1461 * Test whether another node is bound to an external data source.
1463 bool isTied (const char * relative_path) const;
1466 * Test whether another node is bound to an external data source.
1468 bool isTied (const std::string& relative_path) const
1469 { return isTied(relative_path.c_str()); }
1472 * Bind another node to an external bool source.
1474 bool tie (const char * relative_path, const SGRawValue<bool> &rawValue,
1475 bool useDefault = true);
1478 * Bind another node to an external bool source.
1480 bool tie (const std::string& relative_path, const SGRawValue<bool> &rawValue,
1481 bool useDefault = true)
1482 { return tie(relative_path.c_str(), rawValue, useDefault); }
1486 * Bind another node to an external int source.
1488 bool tie (const char * relative_path, const SGRawValue<int> &rawValue,
1489 bool useDefault = true);
1492 * Bind another node to an external int source.
1494 bool tie (const std::string& relative_path, const SGRawValue<int> &rawValue,
1495 bool useDefault = true)
1496 { return tie(relative_path.c_str(), rawValue, useDefault); }
1500 * Bind another node to an external long int source.
1502 bool tie (const char * relative_path, const SGRawValue<long> &rawValue,
1503 bool useDefault = true);
1506 * Bind another node to an external long int source.
1508 bool tie (const std::string& relative_path, const SGRawValue<long> &rawValue,
1509 bool useDefault = true)
1510 { return tie(relative_path.c_str(), rawValue, useDefault); }
1514 * Bind another node to an external float source.
1516 bool tie (const char * relative_path, const SGRawValue<float> &rawValue,
1517 bool useDefault = true);
1520 * Bind another node to an external float source.
1522 bool tie (const std::string& relative_path, const SGRawValue<float> &rawValue,
1523 bool useDefault = true)
1524 { return tie(relative_path.c_str(), rawValue, useDefault); }
1528 * Bind another node to an external double source.
1530 bool tie (const char * relative_path, const SGRawValue<double> &rawValue,
1531 bool useDefault = true);
1534 * Bind another node to an external double source.
1536 bool tie (const std::string& relative_path, const SGRawValue<double> &rawValue,
1537 bool useDefault = true)
1538 { return tie(relative_path.c_str(), rawValue, useDefault); }
1542 * Bind another node to an external string source.
1544 bool tie (const char * relative_path, const SGRawValue<const char *> &rawValue,
1545 bool useDefault = true);
1548 * Bind another node to an external string source.
1550 bool tie (const std::string& relative_path, const SGRawValue<const char*> &rawValue,
1551 bool useDefault = true)
1552 { return tie(relative_path.c_str(), rawValue, useDefault); }
1556 * Unbind another node from any external data source.
1558 bool untie (const char * relative_path);
1561 * Unbind another node from any external data source.
1563 bool untie (const std::string& relative_path)
1564 { return untie(relative_path.c_str()); }
1568 * Add a change listener to the property. If "initial" is set call the
1569 * listener initially.
1571 void addChangeListener (SGPropertyChangeListener * listener,
1572 bool initial = false);
1576 * Remove a change listener from the property.
1578 void removeChangeListener (SGPropertyChangeListener * listener);
1582 * Get the number of listeners.
1584 int nListeners () const { return _listeners ? (int)_listeners->size() : 0; }
1588 * Fire a value change event to all listeners.
1590 void fireValueChanged ();
1594 * Fire a child-added event to all listeners.
1596 void fireChildAdded (SGPropertyNode * child);
1599 * Trigger a child-added and value-changed event for every child (Unlimited
1600 * depth) and the node itself.
1602 * It can be used to simulating the creation of a property tree, eg. for
1603 * (re)initializing a subsystem which is controlled through the property tree.
1605 void fireCreatedRecursive();
1608 * Fire a child-removed event to all listeners.
1610 void fireChildRemoved (SGPropertyNode * child);
1613 * Fire a child-removed event for every child of this node (Unlimited depth)
1615 * Upon removal of a child node only for this single node a child-removed
1616 * event is triggered. If eg. resource cleanup relies on receiving a
1617 * child-removed event for every child this method can be used.
1619 void fireChildrenRemovedRecursive();
1623 * Clear any existing value and set the type to NONE.
1628 * Compare two property trees. The property trees are equal if: 1)
1629 * They have no children, and have the same type and the values are
1630 * equal, or 2) have the same number of children, and the
1631 * corresponding children in each tree are equal. "corresponding"
1632 * means have the same name and index.
1634 * Attributes, removed children, and aliases aren't considered.
1636 static bool compare (const SGPropertyNode& lhs, const SGPropertyNode& rhs);
1640 void fireValueChanged (SGPropertyNode * node);
1641 void fireChildAdded (SGPropertyNode * parent, SGPropertyNode * child);
1642 void fireChildRemoved (SGPropertyNode * parent, SGPropertyNode * child);
1645 * Protected constructor for making new nodes on demand.
1647 SGPropertyNode (const std::string& name, int index, SGPropertyNode * parent);
1648 template<typename Itr>
1649 SGPropertyNode (Itr begin, Itr end, int index, SGPropertyNode * parent);
1653 // Get the raw value
1654 bool get_bool () const;
1655 int get_int () const;
1656 long get_long () const;
1657 float get_float () const;
1658 double get_double () const;
1659 const char * get_string () const;
1661 // Set the raw value
1662 bool set_bool (bool value);
1663 bool set_int (int value);
1664 bool set_long (long value);
1665 bool set_float (float value);
1666 bool set_double (double value);
1667 bool set_string (const char * value);
1671 * Get the value as a string.
1673 const char * make_string () const;
1676 * Trace a read access.
1678 void trace_read () const;
1682 * Trace a write access.
1684 void trace_write () const;
1688 /// To avoid cyclic reference counting loops this shall not be a reference
1690 SGPropertyNode * _parent;
1691 simgear::PropertyList _children;
1692 simgear::PropertyList _removedChildren;
1693 mutable std::string _buffer;
1694 simgear::props::Type _type;
1698 // The right kind of pointer...
1700 SGPropertyNode * alias;
1713 std::vector<SGPropertyChangeListener *> * _listeners;
1715 // Pass name as a pair of iterators
1716 template<typename Itr>
1717 SGPropertyNode * getChildImpl (Itr begin, Itr end, int index = 0, bool create = false);
1718 // very internal method
1719 template<typename Itr>
1720 SGPropertyNode* getExistingChild (Itr begin, Itr end, int index, bool create);
1721 // very internal path parsing function
1722 template<typename SplitItr>
1723 friend SGPropertyNode* find_node_aux(SGPropertyNode * current, SplitItr& itr,
1724 bool create, int last_index);
1726 friend size_t hash_value(const SGPropertyNode& node);
1729 // Convenience functions for use in templates
1730 template<typename T>
1731 T getValue(const SGPropertyNode*);
1734 inline bool getValue<bool>(const SGPropertyNode* node) { return node->getBoolValue(); }
1737 inline int getValue<int>(const SGPropertyNode* node) { return node->getIntValue(); }
1740 inline long getValue<long>(const SGPropertyNode* node) { return node->getLongValue(); }
1743 inline float getValue<float>(const SGPropertyNode* node)
1745 return node->getFloatValue();
1749 inline double getValue<double>(const SGPropertyNode* node)
1751 return node->getDoubleValue();
1755 inline const char * getValue<const char*>(const SGPropertyNode* node)
1757 return node->getStringValue ();
1760 inline bool setValue(SGPropertyNode* node, bool value)
1762 return node->setBoolValue(value);
1765 inline bool setValue(SGPropertyNode* node, int value)
1767 return node->setIntValue(value);
1770 inline bool setValue(SGPropertyNode* node, long value)
1772 return node->setLongValue(value);
1775 inline bool setValue(SGPropertyNode* node, float value)
1777 return node->setFloatValue(value);
1780 inline bool setValue(SGPropertyNode* node, double value)
1782 return node->setDoubleValue(value);
1785 inline bool setValue(SGPropertyNode* node, const char* value)
1787 return node->setStringValue(value);
1790 inline bool setValue (SGPropertyNode* node, const std::string& value)
1792 return node->setStringValue(value.c_str());
1795 template<typename T>
1796 bool SGPropertyNode::tie(const SGRawValue<T> &rawValue, bool useDefault)
1798 using namespace simgear::props;
1799 if (_type == ALIAS || _tied)
1802 useDefault = useDefault && hasValue();
1803 T old_val = SGRawValue<T>::DefaultValue();
1805 old_val = getValue<T>(this);
1807 if (PropertyTraits<T>::Internal)
1808 _type = PropertyTraits<T>::type_tag;
1812 _value.val = rawValue.clone();
1814 int save_attributes = getAttributes();
1815 setAttribute( WRITE, true );
1817 setAttributes( save_attributes );
1823 bool SGPropertyNode::tie (const SGRawValue<const char *> &rawValue,
1826 template<typename T>
1827 T SGPropertyNode::getValue(typename boost::disable_if_c<simgear::props
1828 ::PropertyTraits<T>::Internal>::type* dummy) const
1830 using namespace simgear::props;
1831 if (_attr == (READ|WRITE) && _type == EXTENDED
1832 && _value.val->getType() == PropertyTraits<T>::type_tag) {
1833 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
1835 if (getAttribute(TRACE_READ))
1837 if (!getAttribute(READ))
1838 return SGRawValue<T>::DefaultValue();
1841 if (_value.val->getType() == PropertyTraits<T>::type_tag)
1842 return static_cast<SGRawValue<T>*>(_value.val)->getValue();
1846 return simgear::parseString<T>(make_string());
1848 default: // avoid compiler warning
1851 return SGRawValue<T>::DefaultValue();
1854 template<typename T>
1855 inline T SGPropertyNode::getValue(typename boost::enable_if_c<simgear::props
1856 ::PropertyTraits<T>::Internal>::type* dummy) const
1858 return ::getValue<T>(this);
1861 template<typename T, typename T_get /* = T */> // TODO use C++11 or traits
1862 std::vector<T> SGPropertyNode::getChildValues(const std::string& name) const
1864 const simgear::PropertyList& props = getChildren(name);
1865 std::vector<T> values( props.size() );
1867 for( size_t i = 0; i < props.size(); ++i )
1868 values[i] = props[i]->getValue<T_get>();
1873 template<typename T>
1875 std::vector<T> SGPropertyNode::getChildValues(const std::string& name) const
1877 return getChildValues<T, T>(name);
1880 template<typename T>
1881 bool SGPropertyNode::setValue(const T& val,
1882 typename boost::disable_if_c<simgear::props
1883 ::PropertyTraits<T>::Internal>::type* dummy)
1885 using namespace simgear::props;
1886 if (_attr == (READ|WRITE) && _type == EXTENDED
1887 && _value.val->getType() == PropertyTraits<T>::type_tag) {
1888 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
1891 if (getAttribute(WRITE)
1892 && ((_type == EXTENDED
1893 && _value.val->getType() == PropertyTraits<T>::type_tag)
1894 || _type == NONE || _type == UNSPECIFIED)) {
1895 if (_type == NONE || _type == UNSPECIFIED) {
1898 _value.val = new SGRawValueContainer<T>(val);
1900 static_cast<SGRawValue<T>*>(_value.val)->setValue(val);
1902 if (getAttribute(TRACE_WRITE))
1909 template<typename T>
1910 inline bool SGPropertyNode::setValue(const T& val,
1911 typename boost::enable_if_c<simgear::props
1912 ::PropertyTraits<T>::Internal>::type* dummy)
1914 return ::setValue(this, val);
1918 * Utility function for creation of a child property node.
1920 inline SGPropertyNode* makeChild(SGPropertyNode* parent, const char* name,
1923 return parent->getChild(name, index, true);
1927 * Utility function for creation of a child property node using a
1932 template<typename StringType>
1933 inline SGPropertyNode* makeNode(SGPropertyNode* parent, const StringType& name)
1935 return parent->getNode(name, true);
1940 size_t hash_value(const SGPropertyNode& node);
1942 // Helper comparison and hash functions for common cases
1950 bool operator()(const SGPropertyNode* lhs, const SGPropertyNode* rhs) const
1952 return SGPropertyNode::compare(*lhs, *rhs);
1954 bool operator()(SGPropertyNode_ptr lhs, const SGPropertyNode* rhs) const
1956 return SGPropertyNode::compare(*lhs, *rhs);
1958 bool operator()(const SGPropertyNode* lhs, SGPropertyNode_ptr rhs) const
1960 return SGPropertyNode::compare(*lhs, *rhs);
1962 bool operator()(SGPropertyNode_ptr lhs, SGPropertyNode_ptr rhs) const
1964 return SGPropertyNode::compare(*lhs, *rhs);
1970 size_t operator()(const SGPropertyNode* node) const
1972 return hash_value(*node);
1974 size_t operator()(SGPropertyNode_ptr node) const
1976 return hash_value(*node);
1982 /** Convenience class for change listener callbacks without
1983 * creating a derived class implementing a "valueChanged" method.
1984 * Also removes listener on destruction automatically.
1987 class SGPropertyChangeCallback
1988 : public SGPropertyChangeListener
1991 SGPropertyChangeCallback(T* obj, void (T::*method)(SGPropertyNode*),
1992 SGPropertyNode_ptr property,bool initial=false)
1993 : _obj(obj), _callback(method), _property(property)
1995 _property->addChangeListener(this,initial);
1997 virtual ~SGPropertyChangeCallback()
1999 _property->removeChangeListener(this);
2001 void valueChanged (SGPropertyNode * node)
2003 (_obj->*_callback)(node);
2007 void (T::*_callback)(SGPropertyNode*);
2008 SGPropertyNode_ptr _property;
2011 #endif // __PROPS_HXX