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 <simgear/compiler.h>
25 #include <simgear/debug/logstream.hxx>
30 #include <simgear/structure/SGReferenced.hxx>
31 #include <simgear/structure/SGSharedPtr.hxx>
33 // XXX This whole file should be in the simgear namespace, but I don't
34 // have the guts yet...
39 * Property value types.
43 #pragma warn A sloppy coder has defined NONE as a macro!
48 #pragma warn A sloppy coder has defined ALIAS as a macro!
53 #pragma warn A sloppy coder has defined UNSPECIFIED as a macro!
58 #pragma warn A sloppy coder has defined BOOL as a macro!
63 #pragma warn A sloppy coder has defined INT as a macro!
68 #pragma warn A sloppy coder has defined LONG as a macro!
73 #pragma warn A sloppy coder has defined FLOAT as a macro!
78 #pragma warn A sloppy coder has defined DOUBLE as a macro!
83 #pragma warn A sloppy coder has defined STRING as a macro!
103 struct PropertyTraits
105 static const Type type_tag = NONE;
109 struct PropertyTraits<bool>
111 static const Type type_tag = BOOL;
115 struct PropertyTraits<int>
117 static const Type type_tag = INT;
121 struct PropertyTraits<long>
123 static const Type type_tag = LONG;
127 struct PropertyTraits<float>
129 static const Type type_tag = FLOAT;
133 struct PropertyTraits<double>
135 static const Type type_tag = DOUBLE;
139 struct PropertyTraits<const char *>
141 static const Type type_tag = STRING;
149 ////////////////////////////////////////////////////////////////////////
152 // This is the mechanism that information-providing routines can
153 // use to link their own values to the property manager. Any
154 // SGValue can be tied to a raw value and then untied again.
156 // Note: we are forced to use inlined methods here to ensure
157 // that the templates will be instantiated. We're probably taking
158 // a small performance hit for that.
159 ////////////////////////////////////////////////////////////////////////
161 /** Base for virtual destructor
166 virtual ~SGRawBase() {}
170 * Abstract base class for a raw value.
172 * <p>The property manager is implemented in two layers. The {@link
173 * SGPropertyNode} is the highest and most abstract layer,
174 * representing an LValue/RValue pair: it records the position of the
175 * property in the property tree and contains facilities for
176 * navigation to other nodes. It is guaranteed to be persistent: the
177 * {@link SGPropertyNode} will not change during a session, even if
178 * the property is bound and unbound multiple times.</p>
180 * <p>When the property value is not managed internally in the
181 * SGPropertyNode, the SGPropertyNode will contain a reference to an
182 * SGRawValue (this class), which provides an abstract way to get,
183 * set, and clone the underlying value. The SGRawValue may change
184 * frequently during a session as a value is retyped or bound and
185 * unbound to various data source, but the abstract SGPropertyNode
186 * layer insulates the application from those changes. The raw value
187 * contains no facilities for data binding or for type conversion: it
188 * is simply the abstraction of a primitive data type (or a compound
189 * data type, in the case of a string).</p>
191 * <p>The SGPropertyNode class always keeps a *copy* of a raw value,
192 * not the original one passed to it; if you override a derived class
193 * but do not replace the {@link #clone} method, strange things will
196 * <p>All derived SGRawValue classes must implement {@link #getValue},
197 * {@link #setValue}, and {@link #clone} for the appropriate type.</p>
199 * @see SGPropertyNode
200 * @see SGRawValuePointer
201 * @see SGRawValueFunctions
202 * @see SGRawValueFunctionsIndexed
203 * @see SGRawValueMethods
204 * @see SGRawValueMethodsIndexed
207 class SGRawValue : public SGRawBase
212 * The default underlying value for this type.
214 * Every raw value has a default; the default is false for a
215 * boolean, 0 for the various numeric values, and "" for a string.
216 * If additional types of raw values are added in the future, they
217 * may need different kinds of default values (such as epoch for a
218 * date type). The default value is used when creating new values.
220 static const T DefaultValue; // Default for this kind of raw value.
226 * Use the default value for this type.
234 virtual ~SGRawValue () {}
238 * Return the underlying value.
240 * @return The actual value for the property.
243 virtual T getValue () const = 0;
247 * Assign a new underlying value.
249 * If the new value cannot be set (because this is a read-only
250 * raw value, or because the new value is not acceptable for
251 * some reason) this method returns false and leaves the original
254 * @param value The actual value for the property.
255 * @return true if the value was set successfully, false otherwise.
258 virtual bool setValue (T value) = 0;
262 * Create a new deep copy of this raw value.
264 * The copy will contain its own version of the underlying value
267 * @return A deep copy of the current object.
269 virtual SGRawValue * clone () const = 0;
272 ////////////////////////////////////////////////////////////////////////
273 // Default values for every type.
274 ////////////////////////////////////////////////////////////////////////
276 template<> const bool SGRawValue<bool>::DefaultValue;
277 template<> const int SGRawValue<int>::DefaultValue;
278 template<> const long SGRawValue<long>::DefaultValue;
279 template<> const float SGRawValue<float>::DefaultValue;
280 template<> const double SGRawValue<double>::DefaultValue;
281 template<> const char * const SGRawValue<const char *>::DefaultValue;
284 * A raw value bound to a pointer.
286 * This is the most efficient way to tie an external value, but also
287 * the most dangerous, because there is no way for the supplier to
288 * perform bounds checking and derived calculations except by polling
289 * the variable to see if it has changed. There is no default
290 * constructor, because this class would be meaningless without a
294 class SGRawValuePointer : public SGRawValue<T>
299 * Explicit pointer constructor.
301 * Create a new raw value bound to the value of the variable
302 * referenced by the pointer.
304 * @param ptr The pointer to the variable to which this raw value
307 SGRawValuePointer (T * ptr) : _ptr(ptr) {}
312 virtual ~SGRawValuePointer () {}
315 * Get the underlying value.
317 * This method will dereference the pointer and return the
320 virtual T getValue () const { return *_ptr; }
323 * Set the underlying value.
325 * This method will dereference the pointer and change the
328 virtual bool setValue (T value) { *_ptr = value; return true; }
331 * Create a copy of this raw value.
333 * The copy will use the same external pointer as the original.
335 virtual SGRawValue<T> * clone () const {
336 return new SGRawValuePointer<T>(_ptr);
345 * A value managed through static functions.
347 * A read-only value will not have a setter; a write-only value will
351 class SGRawValueFunctions : public SGRawValue<T>
356 * The template type of a static getter function.
358 typedef T (*getter_t)();
361 * The template type of a static setter function.
363 typedef void (*setter_t)(T);
366 * Explicit constructor.
368 * Create a new raw value bound to the getter and setter supplied.
370 * @param getter A static function for getting a value, or 0
371 * to read-disable the value.
372 * @param setter A static function for setting a value, or 0
373 * to write-disable the value.
375 SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
376 : _getter(getter), _setter(setter) {}
381 virtual ~SGRawValueFunctions () {}
384 * Get the underlying value.
386 * This method will invoke the getter function to get a value.
387 * If no getter function was supplied, this method will always
388 * return the default value for the type.
390 virtual T getValue () const {
391 if (_getter) return (*_getter)();
392 else return SGRawValue<T>::DefaultValue;
396 * Set the underlying value.
398 * This method will invoke the setter function to change the
399 * underlying value. If no setter function was supplied, this
400 * method will return false.
402 virtual bool setValue (T value) {
403 if (_setter) { (*_setter)(value); return true; }
408 * Create a copy of this raw value, bound to the same functions.
410 virtual SGRawValue<T> * clone () const {
411 return new SGRawValueFunctions<T>(_getter,_setter);
421 * An indexed value bound to static functions.
423 * A read-only value will not have a setter; a write-only value will
424 * not have a getter. An indexed value is useful for binding one
425 * of a list of possible values (such as multiple engines for a
426 * plane). The index is hard-coded at creation time.
431 class SGRawValueFunctionsIndexed : public SGRawValue<T>
434 typedef T (*getter_t)(int);
435 typedef void (*setter_t)(int,T);
436 SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
437 : _index(index), _getter(getter), _setter(setter) {}
438 virtual ~SGRawValueFunctionsIndexed () {}
439 virtual T getValue () const {
440 if (_getter) return (*_getter)(_index);
441 else return SGRawValue<T>::DefaultValue;
443 virtual bool setValue (T value) {
444 if (_setter) { (*_setter)(_index, value); return true; }
447 virtual SGRawValue<T> * clone () const {
448 return new SGRawValueFunctionsIndexed<T>(_index, _getter, _setter);
458 * A value managed through an object and access methods.
460 * A read-only value will not have a setter; a write-only value will
463 template <class C, class T>
464 class SGRawValueMethods : public SGRawValue<T>
467 typedef T (C::*getter_t)() const;
468 typedef void (C::*setter_t)(T);
469 SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
470 : _obj(obj), _getter(getter), _setter(setter) {}
471 virtual ~SGRawValueMethods () {}
472 virtual T getValue () const {
473 if (_getter) { return (_obj.*_getter)(); }
474 else { return SGRawValue<T>::DefaultValue; }
476 virtual bool setValue (T value) {
477 if (_setter) { (_obj.*_setter)(value); return true; }
480 virtual SGRawValue<T> * clone () const {
481 return new SGRawValueMethods<C,T>(_obj, _getter, _setter);
491 * An indexed value managed through an object and access methods.
493 * A read-only value will not have a setter; a write-only value will
496 template <class C, class T>
497 class SGRawValueMethodsIndexed : public SGRawValue<T>
500 typedef T (C::*getter_t)(int) const;
501 typedef void (C::*setter_t)(int, T);
502 SGRawValueMethodsIndexed (C &obj, int index,
503 getter_t getter = 0, setter_t setter = 0)
504 : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
505 virtual ~SGRawValueMethodsIndexed () {}
506 virtual T getValue () const {
507 if (_getter) { return (_obj.*_getter)(_index); }
508 else { return SGRawValue<T>::DefaultValue; }
510 virtual bool setValue (T value) {
511 if (_setter) { (_obj.*_setter)(_index, value); return true; }
514 virtual SGRawValue<T> * clone () const {
515 return new SGRawValueMethodsIndexed<C,T>(_obj, _index, _getter, _setter);
526 * The smart pointer that manage reference counting
528 class SGPropertyNode;
529 typedef SGSharedPtr<SGPropertyNode> SGPropertyNode_ptr;
530 typedef SGSharedPtr<const SGPropertyNode> SGConstPropertyNode_ptr;
534 * The property change listener interface.
536 * <p>Any class that needs to listen for property changes must implement
537 * this interface.</p>
539 class SGPropertyChangeListener
542 virtual ~SGPropertyChangeListener ();
543 virtual void valueChanged (SGPropertyNode * node);
544 virtual void childAdded (SGPropertyNode * parent, SGPropertyNode * child);
545 virtual void childRemoved (SGPropertyNode * parent, SGPropertyNode * child);
548 friend class SGPropertyNode;
549 virtual void register_property (SGPropertyNode * node);
550 virtual void unregister_property (SGPropertyNode * node);
553 std::vector<SGPropertyNode *> _properties;
559 * A node in a property tree.
561 class SGPropertyNode : public SGReferenced
569 MAX_STRING_LEN = 1024
573 * Access mode attributes.
575 * <p>The ARCHIVE attribute is strictly advisory, and controls
576 * whether the property should normally be saved and restored.</p>
590 * Last used attribute
591 * Update as needed when enum Attribute is changed
593 static const int LAST_USED_ATTRIBUTE;
597 * Default constructor.
605 SGPropertyNode (const SGPropertyNode &node);
611 virtual ~SGPropertyNode ();
620 * Test whether this node contains a primitive leaf value.
622 bool hasValue () const { return (_type != simgear::props::NONE); }
626 * Get the node's simple (XML) name.
628 const char * getName () const { return _name.c_str(); }
632 * Get the node's pretty display name, with subscript when needed.
634 const char * getDisplayName (bool simplify = false) const;
638 * Get the node's integer index.
640 int getIndex () const { return _index; }
644 * Get a non-const pointer to the node's parent.
646 SGPropertyNode * getParent () { return _parent; }
650 * Get a const pointer to the node's parent.
652 const SGPropertyNode * getParent () const { return _parent; }
661 * Get the number of child nodes.
663 int nChildren () const { return _children.size(); }
667 * Get a child node by position (*NOT* index).
669 SGPropertyNode * getChild (int position);
673 * Get a const child node by position (*NOT* index).
675 const SGPropertyNode * getChild (int position) const;
679 * Test whether a named child exists.
681 bool hasChild (const char * name, int index = 0) const
683 return (getChild(name, index) != 0);
687 * Test whether a named child exists.
689 bool hasChild (const std::string& name, int index = 0) const
691 return (getChild(name, index) != 0);
695 * Create a child node after the last node with the same name.
697 SGPropertyNode * addChild (const char * name);
700 * Get a child node by name and index.
702 SGPropertyNode * getChild (const char * name, int index = 0,
703 bool create = false);
706 * Get a child node by name and index.
708 SGPropertyNode * getChild (const std::string& name, int index = 0,
710 { return getChild(name.c_str(), index, create); }
714 * Get a const child node by name and index.
716 const SGPropertyNode * getChild (const char * name, int index = 0) const;
719 * Get a const child node by name and index.
721 const SGPropertyNode * getChild (const std::string& name, int index = 0) const
722 { return getChild(name.c_str(), index); }
726 * Get a vector of all children with the specified name.
728 std::vector<SGPropertyNode_ptr> getChildren (const char * name) const;
731 * Get a vector of all children with the specified name.
733 std::vector<SGPropertyNode_ptr> getChildren (const std::string& name) const
734 { return getChildren(name.c_str()); }
737 * Remove child by position.
739 SGPropertyNode_ptr removeChild (int pos, bool keep = true);
743 * Remove a child node
745 SGPropertyNode_ptr removeChild (const char * name, int index = 0,
749 * Remove a child node
751 SGPropertyNode_ptr removeChild (const std::string& name, int index = 0,
753 { return removeChild(name.c_str(), index, keep); }
756 * Remove all children with the specified name.
758 std::vector<SGPropertyNode_ptr> removeChildren (const char * name,
763 * Remove all children with the specified name.
765 std::vector<SGPropertyNode_ptr> removeChildren (const std::string& name,
767 { return removeChildren(name.c_str(), keep); }
775 * Alias this node's leaf value to another's.
777 bool alias (SGPropertyNode * target);
781 * Alias this node's leaf value to another's by relative path.
783 bool alias (const char * path);
786 * Alias this node's leaf value to another's by relative path.
788 bool alias (const std::string& path)
789 { return alias(path.c_str()); }
793 * Remove any alias for this node.
799 * Test whether the node's leaf value is aliased to another's.
801 bool isAlias () const { return (_type == simgear::props::ALIAS); }
805 * Get a non-const pointer to the current alias target, if any.
807 SGPropertyNode * getAliasTarget ();
811 * Get a const pointer to the current alias target, if any.
813 const SGPropertyNode * getAliasTarget () const;
822 * Get the path to this node from the root.
824 const char * getPath (bool simplify = false) const;
828 * Get a pointer to the root node.
830 SGPropertyNode * getRootNode ();
834 * Get a const pointer to the root node.
836 const SGPropertyNode * getRootNode () const;
840 * Get a pointer to another node by relative path.
842 SGPropertyNode * getNode (const char * relative_path, bool create = false);
845 * Get a pointer to another node by relative path.
847 SGPropertyNode * getNode (const std::string& relative_path, bool create = false)
848 { return getNode(relative_path.c_str(), create); }
851 * Get a pointer to another node by relative path.
853 * This method leaves the index off the last member of the path,
854 * so that the user can specify it separately (and save some
855 * string building). For example, getNode("/bar[1]/foo", 3) is
856 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
857 * provided overrides any given in the path itself for the last
860 SGPropertyNode * getNode (const char * relative_path, int index,
861 bool create = false);
864 * Get a pointer to another node by relative path.
866 * This method leaves the index off the last member of the path,
867 * so that the user can specify it separately (and save some
868 * string building). For example, getNode("/bar[1]/foo", 3) is
869 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
870 * provided overrides any given in the path itself for the last
873 SGPropertyNode * getNode (const std::string& relative_path, int index,
875 { return getNode(relative_path.c_str(), index, create); }
878 * Get a const pointer to another node by relative path.
880 const SGPropertyNode * getNode (const char * relative_path) const;
883 * Get a const pointer to another node by relative path.
885 const SGPropertyNode * getNode (const std::string& relative_path) const
886 { return getNode(relative_path.c_str()); }
890 * Get a const pointer to another node by relative path.
892 * This method leaves the index off the last member of the path,
893 * so that the user can specify it separate.
895 const SGPropertyNode * getNode (const char * relative_path,
899 * Get a const pointer to another node by relative path.
901 * This method leaves the index off the last member of the path,
902 * so that the user can specify it separate.
904 const SGPropertyNode * getNode (const std::string& relative_path,
906 { return getNode(relative_path.c_str(), index); }
913 * Check a single mode attribute for the property node.
915 bool getAttribute (Attribute attr) const { return ((_attr & attr) != 0); }
919 * Set a single mode attribute for the property node.
921 void setAttribute (Attribute attr, bool state) {
922 (state ? _attr |= attr : _attr &= ~attr);
927 * Get all of the mode attributes for the property node.
929 int getAttributes () const { return _attr; }
933 * Set all of the mode attributes for the property node.
935 void setAttributes (int attr) { _attr = attr; }
939 // Leaf Value (primitive).
944 * Get the type of leaf value, if any, for this node.
946 simgear::props::Type getType () const;
950 * Get a bool value for this node.
952 bool getBoolValue () const;
956 * Get an int value for this node.
958 int getIntValue () const;
962 * Get a long int value for this node.
964 long getLongValue () const;
968 * Get a float value for this node.
970 float getFloatValue () const;
974 * Get a double value for this node.
976 double getDoubleValue () const;
980 * Get a string value for this node.
982 const char * getStringValue () const;
987 * Set a bool value for this node.
989 bool setBoolValue (bool value);
993 * Set an int value for this node.
995 bool setIntValue (int value);
999 * Set a long int value for this node.
1001 bool setLongValue (long value);
1005 * Set a float value for this node.
1007 bool setFloatValue (float value);
1011 * Set a double value for this node.
1013 bool setDoubleValue (double value);
1017 * Set a string value for this node.
1019 bool setStringValue (const char * value);
1022 * Set a string value for this node.
1024 bool setStringValue (const std::string& value)
1025 { return setStringValue(value.c_str()); }
1029 * Set a value of unspecified type for this node.
1031 bool setUnspecifiedValue (const char * value);
1040 * Test whether this node is bound to an external data source.
1042 bool isTied () const { return _tied; }
1045 * Bind this node to an external source.
1047 template<typename T>
1048 bool tie(const SGRawValue<T> &rawValue, bool useDefault = true);
1051 * Unbind this node from any external data source.
1057 // Convenience methods using paths.
1058 // TODO: add attribute methods
1063 * Get another node's type.
1065 simgear::props::Type getType (const char * relative_path) const;
1068 * Get another node's type.
1070 simgear::props::Type getType (const std::string& relative_path) const
1071 { return getType(relative_path.c_str()); }
1074 * Test whether another node has a leaf value.
1076 bool hasValue (const char * relative_path) const;
1079 * Test whether another node has a leaf value.
1081 bool hasValue (const std::string& relative_path) const
1082 { return hasValue(relative_path.c_str()); }
1085 * Get another node's value as a bool.
1087 bool getBoolValue (const char * relative_path,
1088 bool defaultValue = false) const;
1091 * Get another node's value as a bool.
1093 bool getBoolValue (const std::string& relative_path,
1094 bool defaultValue = false) const
1095 { return getBoolValue(relative_path.c_str(), defaultValue); }
1098 * Get another node's value as an int.
1100 int getIntValue (const char * relative_path,
1101 int defaultValue = 0) const;
1104 * Get another node's value as an int.
1106 int getIntValue (const std::string& relative_path,
1107 int defaultValue = 0) const
1108 { return getIntValue(relative_path.c_str(), defaultValue); }
1112 * Get another node's value as a long int.
1114 long getLongValue (const char * relative_path,
1115 long defaultValue = 0L) const;
1118 * Get another node's value as a long int.
1120 long getLongValue (const std::string& relative_path,
1121 long defaultValue = 0L) const
1122 { return getLongValue(relative_path.c_str(), defaultValue); }
1125 * Get another node's value as a float.
1127 float getFloatValue (const char * relative_path,
1128 float defaultValue = 0.0f) const;
1131 * Get another node's value as a float.
1133 float getFloatValue (const std::string& relative_path,
1134 float defaultValue = 0.0f) const
1135 { return getFloatValue(relative_path.c_str(), defaultValue); }
1139 * Get another node's value as a double.
1141 double getDoubleValue (const char * relative_path,
1142 double defaultValue = 0.0) const;
1145 * Get another node's value as a double.
1147 double getDoubleValue (const std::string& relative_path,
1148 double defaultValue = 0.0) const
1149 { return getDoubleValue(relative_path.c_str(), defaultValue); }
1152 * Get another node's value as a string.
1154 const char * getStringValue (const char * relative_path,
1155 const char * defaultValue = "") const;
1159 * Get another node's value as a string.
1161 const char * getStringValue (const std::string& relative_path,
1162 const char * defaultValue = "") const
1163 { return getStringValue(relative_path.c_str(), defaultValue); }
1167 * Set another node's value as a bool.
1169 bool setBoolValue (const char * relative_path, bool value);
1172 * Set another node's value as a bool.
1174 bool setBoolValue (const std::string& relative_path, bool value)
1175 { return setBoolValue(relative_path.c_str(), value); }
1179 * Set another node's value as an int.
1181 bool setIntValue (const char * relative_path, int value);
1184 * Set another node's value as an int.
1186 bool setIntValue (const std::string& relative_path, int value)
1187 { return setIntValue(relative_path.c_str(), value); }
1191 * Set another node's value as a long int.
1193 bool setLongValue (const char * relative_path, long value);
1196 * Set another node's value as a long int.
1198 bool setLongValue (const std::string& relative_path, long value)
1199 { return setLongValue(relative_path.c_str(), value); }
1203 * Set another node's value as a float.
1205 bool setFloatValue (const char * relative_path, float value);
1208 * Set another node's value as a float.
1210 bool setFloatValue (const std::string& relative_path, float value)
1211 { return setFloatValue(relative_path.c_str(), value); }
1215 * Set another node's value as a double.
1217 bool setDoubleValue (const char * relative_path, double value);
1220 * Set another node's value as a double.
1222 bool setDoubleValue (const std::string& relative_path, double value)
1223 { return setDoubleValue(relative_path.c_str(), value); }
1227 * Set another node's value as a string.
1229 bool setStringValue (const char * relative_path, const char * value);
1232 * Set another node's value as a string.
1234 bool setStringValue (const std::string& relative_path, const char * value)
1235 { return setStringValue(relative_path.c_str(), value); }
1239 * Set another node's value with no specified type.
1241 bool setUnspecifiedValue (const char * relative_path, const char * value);
1245 * Test whether another node is bound to an external data source.
1247 bool isTied (const char * relative_path) const;
1250 * Test whether another node is bound to an external data source.
1252 bool isTied (const std::string& relative_path) const
1253 { return isTied(relative_path.c_str()); }
1256 * Bind another node to an external bool source.
1258 bool tie (const char * relative_path, const SGRawValue<bool> &rawValue,
1259 bool useDefault = true);
1262 * Bind another node to an external bool source.
1264 bool tie (const std::string& relative_path, const SGRawValue<bool> &rawValue,
1265 bool useDefault = true)
1266 { return tie(relative_path.c_str(), rawValue, useDefault); }
1270 * Bind another node to an external int source.
1272 bool tie (const char * relative_path, const SGRawValue<int> &rawValue,
1273 bool useDefault = true);
1276 * Bind another node to an external int source.
1278 bool tie (const std::string& relative_path, const SGRawValue<int> &rawValue,
1279 bool useDefault = true)
1280 { return tie(relative_path.c_str(), rawValue, useDefault); }
1284 * Bind another node to an external long int source.
1286 bool tie (const char * relative_path, const SGRawValue<long> &rawValue,
1287 bool useDefault = true);
1290 * Bind another node to an external long int source.
1292 bool tie (const std::string& relative_path, const SGRawValue<long> &rawValue,
1293 bool useDefault = true)
1294 { return tie(relative_path.c_str(), rawValue, useDefault); }
1298 * Bind another node to an external float source.
1300 bool tie (const char * relative_path, const SGRawValue<float> &rawValue,
1301 bool useDefault = true);
1304 * Bind another node to an external float source.
1306 bool tie (const std::string& relative_path, const SGRawValue<float> &rawValue,
1307 bool useDefault = true)
1308 { return tie(relative_path.c_str(), rawValue, useDefault); }
1312 * Bind another node to an external double source.
1314 bool tie (const char * relative_path, const SGRawValue<double> &rawValue,
1315 bool useDefault = true);
1318 * Bind another node to an external double source.
1320 bool tie (const std::string& relative_path, const SGRawValue<double> &rawValue,
1321 bool useDefault = true)
1322 { return tie(relative_path.c_str(), rawValue, useDefault); }
1326 * Bind another node to an external string source.
1328 bool tie (const char * relative_path, const SGRawValue<const char *> &rawValue,
1329 bool useDefault = true);
1332 * Bind another node to an external string source.
1334 bool tie (const std::string& relative_path, const SGRawValue<const char*> &rawValue,
1335 bool useDefault = true)
1336 { return tie(relative_path.c_str(), rawValue, useDefault); }
1340 * Unbind another node from any external data source.
1342 bool untie (const char * relative_path);
1345 * Unbind another node from any external data source.
1347 bool untie (const std::string& relative_path)
1348 { return untie(relative_path.c_str()); }
1352 * Add a change listener to the property. If "initial" is set call the
1353 * listener initially.
1355 void addChangeListener (SGPropertyChangeListener * listener,
1356 bool initial = false);
1360 * Remove a change listener from the property.
1362 void removeChangeListener (SGPropertyChangeListener * listener);
1366 * Get the number of listeners.
1368 int nListeners () const { return _listeners ? _listeners->size() : 0; }
1372 * Fire a value change event to all listeners.
1374 void fireValueChanged ();
1378 * Fire a child-added event to all listeners.
1380 void fireChildAdded (SGPropertyNode * child);
1384 * Fire a child-removed event to all listeners.
1386 void fireChildRemoved (SGPropertyNode * child);
1390 * Clear any existing value and set the type to NONE.
1397 void fireValueChanged (SGPropertyNode * node);
1398 void fireChildAdded (SGPropertyNode * parent, SGPropertyNode * child);
1399 void fireChildRemoved (SGPropertyNode * parent, SGPropertyNode * child);
1402 * Protected constructor for making new nodes on demand.
1404 SGPropertyNode (const char * name, int index, SGPropertyNode * parent);
1409 // Get the raw value
1410 bool get_bool () const;
1411 int get_int () const;
1412 long get_long () const;
1413 float get_float () const;
1414 double get_double () const;
1415 const char * get_string () const;
1417 // Set the raw value
1418 bool set_bool (bool value);
1419 bool set_int (int value);
1420 bool set_long (long value);
1421 bool set_float (float value);
1422 bool set_double (double value);
1423 bool set_string (const char * value);
1427 * Get the value as a string.
1429 const char * make_string () const;
1433 * Trace a read access.
1435 void trace_read () const;
1439 * Trace a write access.
1441 void trace_write () const;
1445 * Remove this node from all nodes that link to it in their path cache.
1447 void remove_from_path_caches();
1454 mutable std::string _display_name;
1455 /// To avoid cyclic reference counting loops this shall not be a reference
1457 SGPropertyNode * _parent;
1458 std::vector<SGPropertyNode_ptr> _children;
1459 std::vector<SGPropertyNode_ptr> _removedChildren;
1460 std::vector<hash_table *> _linkedNodes;
1461 mutable std::string _path;
1462 mutable std::string _buffer;
1463 hash_table * _path_cache;
1464 simgear::props::Type _type;
1468 // The right kind of pointer...
1470 SGPropertyNode * alias;
1483 std::vector<SGPropertyChangeListener *> * _listeners;
1487 * Register/unregister node that links to this node in its path cache.
1489 void add_linked_node (hash_table * node) { _linkedNodes.push_back(node); }
1490 bool remove_linked_node (hash_table * node);
1495 * A very simple hash table.
1501 * An entry in a bucket in a hash table.
1507 const char * get_key () { return _key.c_str(); }
1508 void set_key (const char * key);
1509 SGPropertyNode * get_value () { return _value; }
1510 void set_value (SGPropertyNode * value);
1513 SGSharedPtr<SGPropertyNode> _value;
1518 * A bucket in a hash table.
1524 entry * get_entry (const char * key, bool create = false);
1525 bool erase (SGPropertyNode * node);
1526 void clear (hash_table * owner);
1532 friend class bucket;
1536 SGPropertyNode * get (const char * key);
1537 void put (const char * key, SGPropertyNode * value);
1538 bool erase (SGPropertyNode * node);
1541 unsigned int hashcode (const char * key);
1542 unsigned int _data_length;
1548 // Convenience functions for use in templates
1549 template<typename T>
1550 T getValue(const SGPropertyNode*);
1553 inline bool getValue<bool>(const SGPropertyNode* node) { return node->getBoolValue(); }
1556 inline int getValue<int>(const SGPropertyNode* node) { return node->getIntValue(); }
1559 inline long getValue<long>(const SGPropertyNode* node) { return node->getLongValue(); }
1562 inline float getValue<float>(const SGPropertyNode* node)
1564 return node->getFloatValue();
1568 inline double getValue<double>(const SGPropertyNode* node)
1570 return node->getDoubleValue();
1574 inline const char * getValue<const char*>(const SGPropertyNode* node)
1576 return node->getStringValue ();
1579 inline bool setValue(SGPropertyNode* node, bool value)
1581 return node->setBoolValue(value);
1584 inline bool setValue(SGPropertyNode* node, int value)
1586 return node->setIntValue(value);
1589 inline bool setValue(SGPropertyNode* node, long value)
1591 return node->setLongValue(value);
1594 inline bool setValue(SGPropertyNode* node, float value)
1596 return node->setFloatValue(value);
1599 inline bool setValue(SGPropertyNode* node, double value)
1601 return node->setDoubleValue(value);
1604 inline bool setValue(SGPropertyNode* node, const char* value)
1606 return node->setStringValue(value);
1609 inline bool setValue (SGPropertyNode* node, const std::string& value)
1611 return node->setStringValue(value.c_str());
1614 template<typename T>
1615 bool SGPropertyNode::tie(const SGRawValue<T> &rawValue, bool useDefault)
1617 if (_type == simgear::props::ALIAS || _tied)
1620 useDefault = useDefault && hasValue();
1621 T old_val = SGRawValue<T>::DefaultValue;
1623 old_val = getValue<T>(this);
1625 _type = simgear::props::PropertyTraits<T>::type_tag;
1627 _value.val = rawValue.clone();
1630 setValue(this, old_val);
1636 bool SGPropertyNode::tie (const SGRawValue<const char *> &rawValue,
1639 #endif // __PROPS_HXX