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
33 #include <simgear/compiler.h>
34 #include <simgear/debug/logstream.hxx>
39 #if !defined(SG_HAVE_NATIVE_SGI_COMPILERS)
40 SG_USING_STD(istream);
41 SG_USING_STD(ostream);
48 #pragma warn A sloppy coder has defined NONE as a macro!
53 #pragma warn A sloppy coder has defined ALIAS as a macro!
58 #pragma warn A sloppy coder has defined UNSPECIFIED as a macro!
63 #pragma warn A sloppy coder has defined BOOL as a macro!
68 #pragma warn A sloppy coder has defined INT as a macro!
73 #pragma warn A sloppy coder has defined LONG as a macro!
78 #pragma warn A sloppy coder has defined FLOAT as a macro!
83 #pragma warn A sloppy coder has defined DOUBLE as a macro!
88 #pragma warn A sloppy coder has defined STRING as a macro!
94 ////////////////////////////////////////////////////////////////////////
97 // This is the mechanism that information-providing routines can
98 // use to link their own values to the property manager. Any
99 // SGValue can be tied to a raw value and then untied again.
101 // Note: we are forced to use inlined methods here to ensure
102 // that the templates will be instantiated. We're probably taking
103 // a small performance hit for that.
104 ////////////////////////////////////////////////////////////////////////
108 * Abstract base class for a raw value.
110 * <p>The property manager is implemented in two layers. The {@link
111 * SGPropertyNode} is the highest and most abstract layer,
112 * representing an LValue/RValue pair: it records the position of the
113 * property in the property tree and contains facilities for
114 * navigation to other nodes. It is guaranteed to be persistent: the
115 * {@link SGPropertyNode} will not change during a session, even if
116 * the property is bound and unbound multiple times.</p>
118 * <p>When the property value is not managed internally in the
119 * SGPropertyNode, the SGPropertyNode will contain a reference to an
120 * SGRawValue (this class), which provides an abstract way to get,
121 * set, and clone the underlying value. The SGRawValue may change
122 * frequently during a session as a value is retyped or bound and
123 * unbound to various data source, but the abstract SGPropertyNode
124 * layer insulates the application from those changes. The raw value
125 * contains no facilities for data binding or for type conversion: it
126 * is simply the abstraction of a primitive data type (or a compound
127 * data type, in the case of a string).</p>
129 * <p>The SGPropertyNode class always keeps a *copy* of a raw value,
130 * not the original one passed to it; if you override a derived class
131 * but do not replace the {@link #clone} method, strange things will
134 * <p>All derived SGRawValue classes must implement {@link #getValue},
135 * {@link #setValue}, and {@link #clone} for the appropriate type.</p>
137 * @see SGPropertyNode
138 * @see SGRawValuePointer
139 * @see SGRawValueFunctions
140 * @see SGRawValueFunctionsIndexed
141 * @see SGRawValueMethods
142 * @see SGRawValueMethodsIndexed
150 * The default underlying value for this type.
152 * Every raw value has a default; the default is false for a
153 * boolean, 0 for the various numeric values, and "" for a string.
154 * If additional types of raw values are added in the future, they
155 * may need different kinds of default values (such as epoch for a
156 * date type). The default value is used when creating new values.
158 static const T DefaultValue; // Default for this kind of raw value.
164 * Use the default value for this type.
172 virtual ~SGRawValue () {}
176 * Return the underlying value.
178 * @return The actual value for the property.
181 virtual T getValue () const = 0;
185 * Assign a new underlying value.
187 * If the new value cannot be set (because this is a read-only
188 * raw value, or because the new value is not acceptable for
189 * some reason) this method returns false and leaves the original
192 * @param value The actual value for the property.
193 * @return true if the value was set successfully, false otherwise.
196 virtual bool setValue (T value) = 0;
200 * Create a new deep copy of this raw value.
202 * The copy will contain its own version of the underlying value
205 * @return A deep copy of the current object.
207 virtual SGRawValue * clone () const = 0;
212 * A raw value bound to a pointer.
214 * This is the most efficient way to tie an external value, but also
215 * the most dangerous, because there is no way for the supplier to
216 * perform bounds checking and derived calculations except by polling
217 * the variable to see if it has changed. There is no default
218 * constructor, because this class would be meaningless without a
222 class SGRawValuePointer : public SGRawValue<T>
227 * Explicit pointer constructor.
229 * Create a new raw value bound to the value of the variable
230 * referenced by the pointer.
232 * @param ptr The pointer to the variable to which this raw value
235 SGRawValuePointer (T * ptr) : _ptr(ptr) {}
240 virtual ~SGRawValuePointer () {}
243 * Get the underlying value.
245 * This method will dereference the pointer and return the
248 virtual T getValue () const { return *_ptr; }
251 * Set the underlying value.
253 * This method will dereference the pointer and change the
256 virtual bool setValue (T value) { *_ptr = value; return true; }
259 * Create a copy of this raw value.
261 * The copy will use the same external pointer as the original.
263 virtual SGRawValue<T> * clone () const {
264 return new SGRawValuePointer<T>(_ptr);
273 * A value managed through static functions.
275 * A read-only value will not have a setter; a write-only value will
279 class SGRawValueFunctions : public SGRawValue<T>
284 * The template type of a static getter function.
286 typedef T (*getter_t)();
289 * The template type of a static setter function.
291 typedef void (*setter_t)(T);
294 * Explicit constructor.
296 * Create a new raw value bound to the getter and setter supplied.
298 * @param getter A static function for getting a value, or 0
299 * to read-disable the value.
300 * @param setter A static function for setting a value, or 0
301 * to write-disable the value.
303 SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
304 : _getter(getter), _setter(setter) {}
309 virtual ~SGRawValueFunctions () {}
312 * Get the underlying value.
314 * This method will invoke the getter function to get a value.
315 * If no getter function was supplied, this method will always
316 * return the default value for the type.
318 virtual T getValue () const {
319 if (_getter) return (*_getter)();
320 else return SGRawValue<T>::DefaultValue;
324 * Set the underlying value.
326 * This method will invoke the setter function to change the
327 * underlying value. If no setter function was supplied, this
328 * method will return false.
330 virtual bool setValue (T value) {
331 if (_setter) { (*_setter)(value); return true; }
336 * Create a copy of this raw value, bound to the same functions.
338 virtual SGRawValue<T> * clone () const {
339 return new SGRawValueFunctions<T>(_getter,_setter);
349 * An indexed value bound to static functions.
351 * A read-only value will not have a setter; a write-only value will
352 * not have a getter. An indexed value is useful for binding one
353 * of a list of possible values (such as multiple engines for a
354 * plane). The index is hard-coded at creation time.
359 class SGRawValueFunctionsIndexed : public SGRawValue<T>
362 typedef T (*getter_t)(int);
363 typedef void (*setter_t)(int,T);
364 SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
365 : _index(index), _getter(getter), _setter(setter) {}
366 virtual ~SGRawValueFunctionsIndexed () {}
367 virtual T getValue () const {
368 if (_getter) return (*_getter)(_index);
369 else return SGRawValue<T>::DefaultValue;
371 virtual bool setValue (T value) {
372 if (_setter) { (*_setter)(_index, value); return true; }
375 virtual SGRawValue<T> * clone () const {
376 return new SGRawValueFunctionsIndexed<T>(_index, _getter, _setter);
386 * A value managed through an object and access methods.
388 * A read-only value will not have a setter; a write-only value will
391 template <class C, class T>
392 class SGRawValueMethods : public SGRawValue<T>
395 typedef T (C::*getter_t)() const;
396 typedef void (C::*setter_t)(T);
397 SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
398 : _obj(obj), _getter(getter), _setter(setter) {}
399 virtual ~SGRawValueMethods () {}
400 virtual T getValue () const {
401 if (_getter) { return (_obj.*_getter)(); }
402 else { return SGRawValue<T>::DefaultValue; }
404 virtual bool setValue (T value) {
405 if (_setter) { (_obj.*_setter)(value); return true; }
408 virtual SGRawValue<T> * clone () const {
409 return new SGRawValueMethods<C,T>(_obj, _getter, _setter);
419 * An indexed value managed through an object and access methods.
421 * A read-only value will not have a setter; a write-only value will
424 template <class C, class T>
425 class SGRawValueMethodsIndexed : public SGRawValue<T>
428 typedef T (C::*getter_t)(int) const;
429 typedef void (C::*setter_t)(int, T);
430 SGRawValueMethodsIndexed (C &obj, int index,
431 getter_t getter = 0, setter_t setter = 0)
432 : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
433 virtual ~SGRawValueMethodsIndexed () {}
434 virtual T getValue () const {
435 if (_getter) { return (_obj.*_getter)(_index); }
436 else { return SGRawValue<T>::DefaultValue; }
438 virtual bool setValue (T value) {
439 if (_setter) { (_obj.*_setter)(_index, value); return true; }
442 virtual SGRawValue<T> * clone () const {
443 return new SGRawValueMethodsIndexed<C,T>(_obj, _index, _getter, _setter);
454 * The smart pointer that manage reference counting
456 class SGPropertyNode;
457 class SGPropertyNode_ptr
462 * Default constructor
464 SGPropertyNode_ptr();
469 SGPropertyNode_ptr( const SGPropertyNode_ptr &r );
472 * Constructor from a pointer to a node
474 SGPropertyNode_ptr( SGPropertyNode *p );
479 ~SGPropertyNode_ptr();
482 * Assignement operator
484 SGPropertyNode_ptr &operator=( const SGPropertyNode_ptr &r );
487 * Pointer access operator
489 SGPropertyNode *operator->();
492 * Pointer access operator (const)
494 const SGPropertyNode *operator->() const;
497 * Conversion to SGPropertyNode * operator
499 operator SGPropertyNode *();
502 * Conversion to const SGPropertyNode * operator
504 operator const SGPropertyNode *() const;
507 * Return the pointer.
509 SGPropertyNode * ptr () { return _ptr; }
518 SGPropertyNode *_ptr;
524 * The property change listener interface.
526 * <p>Any class that needs to listen for property changes must implement
527 * this interface.</p>
529 class SGPropertyChangeListener
532 virtual ~SGPropertyChangeListener ();
533 virtual void valueChanged (SGPropertyNode * node);
534 virtual void childAdded (SGPropertyNode * parent, SGPropertyNode * child);
535 virtual void childRemoved (SGPropertyNode * parent, SGPropertyNode * child);
538 friend class SGPropertyNode;
539 virtual void register_property (SGPropertyNode * node);
540 virtual void unregister_property (SGPropertyNode * node);
543 vector<SGPropertyNode *> _properties;
549 * A node in a property tree.
559 MAX_STRING_LEN = 1024
563 * Property value types.
579 * Access mode attributes.
581 * <p>The ARCHIVE attribute is strictly advisory, and controls
582 * whether the property should normally be saved and restored.</p>
595 * Last used attribute
596 * Update as needed when enum Attribute is changed
598 static const int LAST_USED_ATTRIBUTE;
602 * Default constructor.
610 SGPropertyNode (const SGPropertyNode &node);
616 virtual ~SGPropertyNode ();
625 * Test whether this node contains a primitive leaf value.
627 bool hasValue () const { return (_type != NONE); }
631 * Get the node's simple (XML) name.
633 const char * getName () const { return _name; }
637 * Get the node's pretty display name, with subscript when needed.
639 const char * getDisplayName (bool simplify = false) const;
643 * Get the node's integer index.
645 int getIndex () const { return _index; }
649 * Get a non-const pointer to the node's parent.
651 SGPropertyNode * getParent () { return _parent; }
655 * Get a const pointer to the node's parent.
657 const SGPropertyNode * getParent () const { return _parent; }
666 * Get the number of child nodes.
668 int nChildren () const { return _children.size(); }
672 * Get a child node by position (*NOT* index).
674 SGPropertyNode * getChild (int position);
678 * Get a const child node by position (*NOT* index).
680 const SGPropertyNode * getChild (int position) const;
684 * Test whether a named child exists.
686 bool hasChild (const char * name, int index = 0) const
688 return (getChild(name, index) != 0);
693 * Get a child node by name and index.
695 SGPropertyNode * getChild (const char * name, int index = 0,
696 bool create = false);
700 * Get a const child node by name and index.
702 const SGPropertyNode * getChild (const char * name, int index = 0) const;
706 * Get a vector of all children with the specified name.
708 vector<SGPropertyNode_ptr> getChildren (const char * name) const;
712 * Remove a child node
714 SGPropertyNode_ptr removeChild (const char * name, int index = 0,
724 * Alias this node's leaf value to another's.
726 bool alias (SGPropertyNode * target);
730 * Alias this node's leaf value to another's by relative path.
732 bool alias (const char * path);
736 * Remove any alias for this node.
742 * Test whether the node's leaf value is aliased to another's.
744 bool isAlias () const { return (_type == ALIAS); }
748 * Get a non-const pointer to the current alias target, if any.
750 SGPropertyNode * getAliasTarget ();
754 * Get a const pointer to the current alias target, if any.
756 const SGPropertyNode * getAliasTarget () const;
765 * Get the path to this node from the root.
767 const char * getPath (bool simplify = false) const;
771 * Get a pointer to the root node.
773 SGPropertyNode * getRootNode ();
777 * Get a const pointer to the root node.
779 const SGPropertyNode * getRootNode () const;
783 * Get a pointer to another node by relative path.
785 SGPropertyNode * getNode (const char * relative_path, bool create = false);
789 * Get a pointer to another node by relative path.
791 * This method leaves the index off the last member of the path,
792 * so that the user can specify it separately (and save some
793 * string building). For example, getNode("/bar[1]/foo", 3) is
794 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
795 * provided overrides any given in the path itself for the last
798 SGPropertyNode * getNode (const char * relative_path, int index,
799 bool create = false);
803 * Get a const pointer to another node by relative path.
805 const SGPropertyNode * getNode (const char * relative_path) const;
809 * Get a const pointer to another node by relative path.
811 * This method leaves the index off the last member of the path,
812 * so that the user can specify it separate.
814 const SGPropertyNode * getNode (const char * relative_path,
823 * Check a single mode attribute for the property node.
825 bool getAttribute (Attribute attr) const { return ((_attr & attr) != 0); }
829 * Set a single mode attribute for the property node.
831 void setAttribute (Attribute attr, bool state) {
832 (state ? _attr |= attr : _attr &= ~attr);
837 * Get all of the mode attributes for the property node.
839 int getAttributes () const { return _attr; }
843 * Set all of the mode attributes for the property node.
845 void setAttributes (int attr) { _attr = attr; }
849 // Leaf Value (primitive).
854 * Get the type of leaf value, if any, for this node.
856 Type getType () const;
860 * Get a bool value for this node.
862 bool getBoolValue () const;
866 * Get an int value for this node.
868 int getIntValue () const;
872 * Get a long int value for this node.
874 long getLongValue () const;
878 * Get a float value for this node.
880 float getFloatValue () const;
884 * Get a double value for this node.
886 double getDoubleValue () const;
890 * Get a string value for this node.
892 const char * getStringValue () const;
897 * Set a bool value for this node.
899 bool setBoolValue (bool value);
903 * Set an int value for this node.
905 bool setIntValue (int value);
909 * Set a long int value for this node.
911 bool setLongValue (long value);
915 * Set a float value for this node.
917 bool setFloatValue (float value);
921 * Set a double value for this node.
923 bool setDoubleValue (double value);
927 * Set a string value for this node.
929 bool setStringValue (const char * value);
933 * Set a value of unspecified type for this node.
935 bool setUnspecifiedValue (const char * value);
944 * Test whether this node is bound to an external data source.
946 bool isTied () const { return _tied; }
950 * Bind this node to an external bool source.
952 bool tie (const SGRawValue<bool> &rawValue, bool useDefault = true);
956 * Bind this node to an external int source.
958 bool tie (const SGRawValue<int> &rawValue, bool useDefault = true);
962 * Bind this node to an external long int source.
964 bool tie (const SGRawValue<long> &rawValue, bool useDefault = true);
968 * Bind this node to an external float source.
970 bool tie (const SGRawValue<float> &rawValue, bool useDefault = true);
974 * Bind this node to an external double source.
976 bool tie (const SGRawValue<double> &rawValue, bool useDefault = true);
980 * Bind this node to an external string source.
982 bool tie (const SGRawValue<const char *> &rawValue, bool useDefault = true);
986 * Unbind this node from any external data source.
992 // Convenience methods using paths.
993 // TODO: add attribute methods
998 * Get another node's type.
1000 Type getType (const char * relative_path) const;
1004 * Test whether another node has a leaf value.
1006 bool hasValue (const char * relative_path) const;
1010 * Get another node's value as a bool.
1012 bool getBoolValue (const char * relative_path,
1013 bool defaultValue = false) const;
1017 * Get another node's value as an int.
1019 int getIntValue (const char * relative_path,
1020 int defaultValue = 0) const;
1024 * Get another node's value as a long int.
1026 long getLongValue (const char * relative_path,
1027 long defaultValue = 0L) const;
1031 * Get another node's value as a float.
1033 float getFloatValue (const char * relative_path,
1034 float defaultValue = 0.0) const;
1038 * Get another node's value as a double.
1040 double getDoubleValue (const char * relative_path,
1041 double defaultValue = 0.0L) const;
1045 * Get another node's value as a string.
1047 const char * getStringValue (const char * relative_path,
1048 const char * defaultValue = "") const;
1052 * Set another node's value as a bool.
1054 bool setBoolValue (const char * relative_path, bool value);
1058 * Set another node's value as an int.
1060 bool setIntValue (const char * relative_path, int value);
1064 * Set another node's value as a long int.
1066 bool setLongValue (const char * relative_path, long value);
1070 * Set another node's value as a float.
1072 bool setFloatValue (const char * relative_path, float value);
1076 * Set another node's value as a double.
1078 bool setDoubleValue (const char * relative_path, double value);
1082 * Set another node's value as a string.
1084 bool setStringValue (const char * relative_path, const char * value);
1088 * Set another node's value with no specified type.
1090 bool setUnspecifiedValue (const char * relative_path, const char * value);
1094 * Test whether another node is bound to an external data source.
1096 bool isTied (const char * relative_path) const;
1100 * Bind another node to an external bool source.
1102 bool tie (const char * relative_path, const SGRawValue<bool> &rawValue,
1103 bool useDefault = true);
1107 * Bind another node to an external int source.
1109 bool tie (const char * relative_path, const SGRawValue<int> &rawValue,
1110 bool useDefault = true);
1114 * Bind another node to an external long int source.
1116 bool tie (const char * relative_path, const SGRawValue<long> &rawValue,
1117 bool useDefault = true);
1121 * Bind another node to an external float source.
1123 bool tie (const char * relative_path, const SGRawValue<float> &rawValue,
1124 bool useDefault = true);
1128 * Bind another node to an external double source.
1130 bool tie (const char * relative_path, const SGRawValue<double> &rawValue,
1131 bool useDefault = true);
1135 * Bind another node to an external string source.
1137 bool tie (const char * relative_path, const SGRawValue<const char *> &rawValue,
1138 bool useDefault = true);
1142 * Unbind another node from any external data source.
1144 bool untie (const char * relative_path);
1148 * Add a change listener to the property.
1150 void addChangeListener (SGPropertyChangeListener * listener);
1154 * Remove a change listener from the property.
1156 void removeChangeListener (SGPropertyChangeListener * listener);
1160 * Fire a value change event to all listeners.
1162 void fireValueChanged ();
1166 * Fire a child-added event to all listeners.
1168 void fireChildAdded (SGPropertyNode * child);
1172 * Fire a child-removed event to all listeners.
1174 void fireChildRemoved (SGPropertyNode * child);
1179 void fireValueChanged (SGPropertyNode * node);
1180 void fireChildAdded (SGPropertyNode * parent, SGPropertyNode * child);
1181 void fireChildRemoved (SGPropertyNode * parent, SGPropertyNode * child);
1184 * Protected constructor for making new nodes on demand.
1186 SGPropertyNode (const char * name, int index, SGPropertyNode * parent);
1191 // Get the raw value
1192 bool get_bool () const;
1193 int get_int () const;
1194 long get_long () const;
1195 float get_float () const;
1196 double get_double () const;
1197 const char * get_string () const;
1199 // Set the raw value
1200 bool set_bool (bool value);
1201 bool set_int (int value);
1202 bool set_long (long value);
1203 bool set_float (float value);
1204 bool set_double (double value);
1205 bool set_string (const char * value);
1209 * Clear any existing value and set the type to NONE.
1211 void clear_value ();
1215 * Get the value as a string.
1217 const char * make_string () const;
1221 * Trace a read access.
1223 void trace_read () const;
1227 * Trace a write access.
1229 void trace_write () const;
1233 * Increment reference counter
1235 void incrementRef();
1238 * Decrement reference counter
1242 friend class SGPropertyNode_ptr;
1245 mutable char _buffer[MAX_STRING_LEN+1];
1250 mutable char * _display_name;
1252 SGPropertyNode * _parent;
1253 vector<SGPropertyNode_ptr> _children;
1254 vector<SGPropertyNode_ptr> _removedChildren;
1255 mutable char * _path;
1256 hash_table * _path_cache;
1262 // The right kind of pointer...
1264 SGPropertyNode * alias;
1265 SGRawValue<bool> * bool_val;
1266 SGRawValue<int> * int_val;
1267 SGRawValue<long> * long_val;
1268 SGRawValue<float> * float_val;
1269 SGRawValue<double> * double_val;
1270 SGRawValue<const char *> * string_val;
1282 vector <SGPropertyChangeListener *> * _listeners;
1287 * A very simple hash table with no remove functionality.
1293 * An entry in a bucket in a hash table.
1299 virtual const char * get_key () { return _key; }
1300 virtual void set_key (const char * key);
1301 virtual SGPropertyNode * get_value () { return _value; }
1302 virtual void set_value (SGPropertyNode * value);
1305 SGPropertyNode * _value;
1310 * A bucket in a hash table.
1316 virtual entry * get_entry (const char * key, bool create = false);
1322 friend class bucket;
1325 virtual ~hash_table ();
1326 virtual SGPropertyNode * get (const char * key);
1327 virtual void put (const char * key, SGPropertyNode * value);
1330 unsigned int hashcode (const char * key);
1331 unsigned int _data_length;
1337 #endif // __PROPS_HXX