simgear/props/props.hxx

   1 /**
   2  * \file props.hxx
   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.
   6  *
   7  * See props.html for documentation [replace with URL when available].
   8  *
   9  * $Id$
  10  */
  11
  12 #ifndef __PROPS_HXX
  13 #define __PROPS_HXX
  14
  15 #ifndef PROPS_STANDALONE
  16 #define PROPS_STANDALONE 0
  17 #endif
  18
  19 #include <vector>
  20
  21 #if PROPS_STANDALONE
  22
  23 #include <string>
  24 #include <iostream>
  25
  26 using std::string;
  27 using std::vector;
  28 using std::istream;
  29 using std::ostream;
  30
  31 #else
  32
  33 #include <simgear/compiler.h>
  34 #include <simgear/debug/logstream.hxx>
  35 #include STL_STRING
  36 #include STL_IOSTREAM
  37 SG_USING_STD(string);
  38 SG_USING_STD(vector);
  39 SG_USING_STD(istream);
  40 SG_USING_STD(ostream);
  41
  42 #endif
  43
  44
  45 #ifdef NONE
  46 #pragma warn A sloppy coder has defined NONE as a macro!
  47 #undef NONE
  48 #endif
  49
  50 #ifdef ALIAS
  51 #pragma warn A sloppy coder has defined ALIAS as a macro!
  52 #undef ALIAS
  53 #endif
  54
  55 #ifdef UNSPECIFIED
  56 #pragma warn A sloppy coder has defined UNSPECIFIED as a macro!
  57 #undef UNSPECIFIED
  58 #endif
  59
  60 #ifdef BOOL
  61 #pragma warn A sloppy coder has defined BOOL as a macro!
  62 #undef BOOL
  63 #endif
  64
  65 #ifdef INT
  66 #pragma warn A sloppy coder has defined INT as a macro!
  67 #undef INT
  68 #endif
  69
  70 #ifdef LONG
  71 #pragma warn A sloppy coder has defined LONG as a macro!
  72 #undef LONG
  73 #endif
  74
  75 #ifdef FLOAT
  76 #pragma warn A sloppy coder has defined FLOAT as a macro!
  77 #undef FLOAT
  78 #endif
  79
  80 #ifdef DOUBLE
  81 #pragma warn A sloppy coder has defined DOUBLE as a macro!
  82 #undef DOUBLE
  83 #endif
  84
  85 #ifdef STRING
  86 #pragma warn A sloppy coder has defined STRING as a macro!
  87 #undef STRING
  88 #endif
  89
  90
  91 \f
  92 ////////////////////////////////////////////////////////////////////////
  93 // A raw value.
  94 //
  95 // This is the mechanism that information-providing routines can
  96 // use to link their own values to the property manager.  Any
  97 // SGValue can be tied to a raw value and then untied again.
  98 //
  99 // Note: we are forced to use inlined methods here to ensure
 100 // that the templates will be instantiated.  We're probably taking
 101 // a small performance hit for that.
 102 ////////////////////////////////////////////////////////////////////////
 103
 104
 105 /**
 106  * Abstract base class for a raw value.
 107  *
 108  * <p>The property manager is implemented in two layers.  The {@link
 109  * SGPropertyNode} is the highest and most abstract layer,
 110  * representing an LValue/RValue pair: it records the position of the
 111  * property in the property tree and contains facilities for
 112  * navigation to other nodes.  It is guaranteed to be persistent: the
 113  * {@link SGPropertyNode} will not change during a session, even if
 114  * the property is bound and unbound multiple times.</p>
 115  *
 116  * <p>When the property value is not managed internally in the
 117  * SGPropertyNode, the SGPropertyNode will contain a reference to an
 118  * SGRawValue (this class), which provides an abstract way to get,
 119  * set, and clone the underlying value.  The SGRawValue may change
 120  * frequently during a session as a value is retyped or bound and
 121  * unbound to various data source, but the abstract SGPropertyNode
 122  * layer insulates the application from those changes.  The raw value
 123  * contains no facilities for data binding or for type conversion: it
 124  * is simply the abstraction of a primitive data type (or a compound
 125  * data type, in the case of a string).</p>
 126  *
 127  * <p>The SGPropertyNode class always keeps a *copy* of a raw value,
 128  * not the original one passed to it; if you override a derived class
 129  * but do not replace the {@link #clone} method, strange things will
 130  * happen.</p>
 131  *
 132  * <p>All derived SGRawValue classes must implement {@link #getValue},
 133  * {@link #setValue}, and {@link #clone} for the appropriate type.</p>
 134  *
 135  * @see SGPropertyNode
 136  * @see SGRawValuePointer
 137  * @see SGRawValueFunctions
 138  * @see SGRawValueFunctionsIndexed
 139  * @see SGRawValueMethods
 140  * @see SGRawValueMethodsIndexed
 141  */
 142 template <class T>
 143 class SGRawValue
 144 {
 145 public:
 146
 147   /**
 148    * The default underlying value for this type.
 149    *
 150    * Every raw value has a default; the default is false for a
 151    * boolean, 0 for the various numeric values, and "" for a string.
 152    * If additional types of raw values are added in the future, they
 153    * may need different kinds of default values (such as epoch for a
 154    * date type).  The default value is used when creating new values.
 155    */
 156   static const T DefaultValue;  // Default for this kind of raw value.
 157
 158
 159   /**
 160    * Constructor.
 161    *
 162    * Use the default value for this type.
 163    */
 164   SGRawValue () {}
 165
 166
 167   /**
 168    * Destructor.
 169    */
 170   virtual ~SGRawValue () {}
 171
 172
 173   /**
 174    * Return the underlying value.
 175    *
 176    * @return The actual value for the property.
 177    * @see #setValue
 178    */
 179   virtual T getValue () const = 0;
 180
 181
 182   /**
 183    * Assign a new underlying value.
 184    *
 185    * If the new value cannot be set (because this is a read-only
 186    * raw value, or because the new value is not acceptable for
 187    * some reason) this method returns false and leaves the original
 188    * value unchanged.
 189    *
 190    * @param value The actual value for the property.
 191    * @return true if the value was set successfully, false otherwise.
 192    * @see #getValue
 193    */
 194   virtual bool setValue (T value) = 0;
 195
 196
 197   /**
 198    * Create a new deep copy of this raw value.
 199    *
 200    * The copy will contain its own version of the underlying value
 201    * as well.
 202    *
 203    * @return A deep copy of the current object.
 204    */
 205   virtual SGRawValue * clone () const = 0;
 206 };
 207
 208
 209 /**
 210  * A raw value bound to a pointer.
 211  *
 212  * This is the most efficient way to tie an external value, but also
 213  * the most dangerous, because there is no way for the supplier to
 214  * perform bounds checking and derived calculations except by polling
 215  * the variable to see if it has changed.  There is no default
 216  * constructor, because this class would be meaningless without a
 217  * pointer.
 218  */
 219 template <class T>
 220 class SGRawValuePointer : public SGRawValue<T>
 221 {
 222 public:
 223
 224   /**
 225    * Explicit pointer constructor.
 226    *
 227    * Create a new raw value bound to the value of the variable
 228    * referenced by the pointer.
 229    *
 230    * @param ptr The pointer to the variable to which this raw value
 231    * will be bound.
 232    */
 233   SGRawValuePointer (T * ptr) : _ptr(ptr) {}
 234
 235   /**
 236    * Destructor.
 237    */
 238   virtual ~SGRawValuePointer () {}
 239
 240   /**
 241    * Get the underlying value.
 242    *
 243    * This method will dereference the pointer and return the
 244    * variable's value.
 245    */
 246   virtual T getValue () const { return *_ptr; }
 247
 248   /**
 249    * Set the underlying value.
 250    *
 251    * This method will dereference the pointer and change the
 252    * variable's value.
 253    */
 254   virtual bool setValue (T value) { *_ptr = value; return true; }
 255
 256   /**
 257    * Create a copy of this raw value.
 258    *
 259    * The copy will use the same external pointer as the original.
 260    */
 261   virtual SGRawValue<T> * clone () const {
 262     return new SGRawValuePointer<T>(_ptr);
 263   }
 264
 265 private:
 266   T * _ptr;
 267 };
 268
 269
 270 /**
 271  * A value managed through static functions.
 272  *
 273  * A read-only value will not have a setter; a write-only value will
 274  * not have a getter.
 275  */
 276 template <class T>
 277 class SGRawValueFunctions : public SGRawValue<T>
 278 {
 279 public:
 280
 281   /**
 282    * The template type of a static getter function.
 283    */
 284   typedef T (*getter_t)();
 285
 286   /**
 287    * The template type of a static setter function.
 288    */
 289   typedef void (*setter_t)(T);
 290
 291   /**
 292    * Explicit constructor.
 293    *
 294    * Create a new raw value bound to the getter and setter supplied.
 295    *
 296    * @param getter A static function for getting a value, or 0
 297    * to read-disable the value.
 298    * @param setter A static function for setting a value, or 0
 299    * to write-disable the value.
 300    */
 301   SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
 302     : _getter(getter), _setter(setter) {}
 303
 304   /**
 305    * Destructor.
 306    */
 307   virtual ~SGRawValueFunctions () {}
 308
 309   /**
 310    * Get the underlying value.
 311    *
 312    * This method will invoke the getter function to get a value.
 313    * If no getter function was supplied, this method will always
 314    * return the default value for the type.
 315    */
 316   virtual T getValue () const {
 317     if (_getter) return (*_getter)();
 318     else return SGRawValue<T>::DefaultValue;
 319   }
 320
 321   /**
 322    * Set the underlying value.
 323    *
 324    * This method will invoke the setter function to change the
 325    * underlying value.  If no setter function was supplied, this
 326    * method will return false.
 327    */
 328   virtual bool setValue (T value) {
 329     if (_setter) { (*_setter)(value); return true; }
 330     else return false;
 331   }
 332
 333   /**
 334    * Create a copy of this raw value, bound to the same functions.
 335    */
 336   virtual SGRawValue<T> * clone () const {
 337     return new SGRawValueFunctions<T>(_getter,_setter);
 338   }
 339
 340 private:
 341   getter_t _getter;
 342   setter_t _setter;
 343 };
 344
 345
 346 /**
 347  * An indexed value bound to static functions.
 348  *
 349  * A read-only value will not have a setter; a write-only value will
 350  * not have a getter.  An indexed value is useful for binding one
 351  * of a list of possible values (such as multiple engines for a
 352  * plane).  The index is hard-coded at creation time.
 353  *
 354  * @see SGRawValue
 355  */
 356 template <class T>
 357 class SGRawValueFunctionsIndexed : public SGRawValue<T>
 358 {
 359 public:
 360   typedef T (*getter_t)(int);
 361   typedef void (*setter_t)(int,T);
 362   SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
 363     : _index(index), _getter(getter), _setter(setter) {}
 364   virtual ~SGRawValueFunctionsIndexed () {}
 365   virtual T getValue () const {
 366     if (_getter) return (*_getter)(_index);
 367     else return SGRawValue<T>::DefaultValue;
 368   }
 369   virtual bool setValue (T value) {
 370     if (_setter) { (*_setter)(_index, value); return true; }
 371     else return false;
 372   }
 373   virtual SGRawValue<T> * clone () const {
 374     return new SGRawValueFunctionsIndexed<T>(_index, _getter, _setter);
 375   }
 376 private:
 377   int _index;
 378   getter_t _getter;
 379   setter_t _setter;
 380 };
 381
 382
 383 /**
 384  * A value managed through an object and access methods.
 385  *
 386  * A read-only value will not have a setter; a write-only value will
 387  * not have a getter.
 388  */
 389 template <class C, class T>
 390 class SGRawValueMethods : public SGRawValue<T>
 391 {
 392 public:
 393   typedef T (C::*getter_t)() const;
 394   typedef void (C::*setter_t)(T);
 395   SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
 396     : _obj(obj), _getter(getter), _setter(setter) {}
 397   virtual ~SGRawValueMethods () {}
 398   virtual T getValue () const {
 399     if (_getter) { return (_obj.*_getter)(); }
 400     else { return SGRawValue<T>::DefaultValue; }
 401   }
 402   virtual bool setValue (T value) {
 403     if (_setter) { (_obj.*_setter)(value); return true; }
 404     else return false;
 405   }
 406   virtual SGRawValue<T> * clone () const {
 407     return new SGRawValueMethods<C,T>(_obj, _getter, _setter);
 408   }
 409 private:
 410   C &_obj;
 411   getter_t _getter;
 412   setter_t _setter;
 413 };
 414
 415
 416 /**
 417  * An indexed value managed through an object and access methods.
 418  *
 419  * A read-only value will not have a setter; a write-only value will
 420  * not have a getter.
 421  */
 422 template <class C, class T>
 423 class SGRawValueMethodsIndexed : public SGRawValue<T>
 424 {
 425 public:
 426   typedef T (C::*getter_t)(int) const;
 427   typedef void (C::*setter_t)(int, T);
 428   SGRawValueMethodsIndexed (C &obj, int index,
 429                      getter_t getter = 0, setter_t setter = 0)
 430     : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
 431   virtual ~SGRawValueMethodsIndexed () {}
 432   virtual T getValue () const {
 433     if (_getter) { return (_obj.*_getter)(_index); }
 434     else { return SGRawValue<T>::DefaultValue; }
 435   }
 436   virtual bool setValue (T value) {
 437     if (_setter) { (_obj.*_setter)(_index, value); return true; }
 438     else return false;
 439   }
 440   virtual SGRawValue<T> * clone () const {
 441     return new SGRawValueMethodsIndexed<C,T>(_obj, _index, _getter, _setter);
 442   }
 443 private:
 444   C &_obj;
 445   int _index;
 446   getter_t _getter;
 447   setter_t _setter;
 448 };
 449
 450 \f
 451 /**
 452  * The smart pointer that manage reference counting
 453  */
 454 class SGPropertyNode;
 455 class SGPropertyNode_ptr
 456 {
 457 public:
 458
 459   /**
 460    * Default constructor
 461    */
 462   SGPropertyNode_ptr();
 463
 464   /**
 465    * Copy constructor
 466    */
 467   SGPropertyNode_ptr( const SGPropertyNode_ptr &r );
 468
 469   /**
 470    * Constructor from a pointer to a node
 471    */
 472   SGPropertyNode_ptr( SGPropertyNode *p );
 473
 474   /**
 475    * Destructor
 476    */
 477   ~SGPropertyNode_ptr();
 478
 479   /**
 480    * Assignement operator
 481    */
 482   SGPropertyNode_ptr &operator=( const SGPropertyNode_ptr &r );
 483
 484   /**
 485    * Pointer access operator
 486    */
 487   SGPropertyNode *operator->();
 488
 489   /**
 490    * Pointer access operator (const)
 491    */
 492   const SGPropertyNode *operator->() const;
 493
 494   /**
 495    * Conversion to SGPropertyNode * operator
 496    */
 497   operator SGPropertyNode *();
 498
 499   /**
 500    * Conversion to const SGPropertyNode * operator
 501    */
 502   operator const SGPropertyNode *() const;
 503
 504   /**
 505    * Return the pointer.
 506    */
 507   SGPropertyNode * ptr () { return _ptr; }
 508
 509   /**
 510    * Validity test
 511    */
 512   bool valid() const;
 513
 514 private:
 515
 516   SGPropertyNode *_ptr;
 517 };
 518
 519
 520 \f
 521 /**
 522  * The property change listener interface.
 523  *
 524  * <p>Any class that needs to listen for property changes must implement
 525  * this interface.</p>
 526  */
 527 class SGPropertyChangeListener
 528 {
 529 public:
 530   virtual ~SGPropertyChangeListener ();
 531   virtual void valueChanged (SGPropertyNode * node);
 532   virtual void childAdded (SGPropertyNode * parent, SGPropertyNode * child);
 533   virtual void childRemoved (SGPropertyNode * parent, SGPropertyNode * child);
 534
 535 protected:
 536   friend class SGPropertyNode;
 537   virtual void register_property (SGPropertyNode * node);
 538   virtual void unregister_property (SGPropertyNode * node);
 539
 540 private:
 541   vector<SGPropertyNode *> _properties;
 542 };
 543
 544
 545 \f
 546 /**
 547  * A node in a property tree.
 548  */
 549 class SGPropertyNode
 550 {
 551 public:
 552
 553   /**
 554    * Public constants.
 555    */
 556   enum {
 557     MAX_STRING_LEN = 1024
 558   };
 559
 560   /**
 561    * Property value types.
 562    */
 563   enum Type {
 564     NONE = 0,
 565     ALIAS,
 566     BOOL,
 567     INT,
 568     LONG,
 569     FLOAT,
 570     DOUBLE,
 571     STRING,
 572     UNSPECIFIED
 573   };
 574
 575
 576   /**
 577    * Access mode attributes.
 578    *
 579    * <p>The ARCHIVE attribute is strictly advisory, and controls
 580    * whether the property should normally be saved and restored.</p>
 581    */
 582   enum Attribute {
 583     READ = 1,
 584     WRITE = 2,
 585     ARCHIVE = 4,
 586     REMOVED = 8,
 587     TRACE_READ = 16,
 588     TRACE_WRITE = 32
 589   };
 590
 591
 592   /**
 593    * Last used attribute
 594    * Update as needed when enum Attribute is changed
 595    */
 596   static const int LAST_USED_ATTRIBUTE;
 597
 598
 599   /**
 600    * Default constructor.
 601    */
 602   SGPropertyNode ();
 603
 604
 605   /**
 606    * Copy constructor.
 607    */
 608   SGPropertyNode (const SGPropertyNode &node);
 609
 610
 611   /**
 612    * Destructor.
 613    */
 614   virtual ~SGPropertyNode ();
 615
 616
 617
 618   //
 619   // Basic properties.
 620   //
 621
 622   /**
 623    * Test whether this node contains a primitive leaf value.
 624    */
 625   bool hasValue () const { return (_type != NONE); }
 626
 627
 628   /**
 629    * Get the node's simple (XML) name.
 630    */
 631   const char * getName () const { return _name; }
 632
 633
 634   /**
 635    * Get the node's pretty display name, with subscript when needed.
 636    */
 637   const char * getDisplayName (bool simplify = false) const;
 638
 639
 640   /**
 641    * Get the node's integer index.
 642    */
 643   int getIndex () const { return _index; }
 644
 645
 646   /**
 647    * Get a non-const pointer to the node's parent.
 648    */
 649   SGPropertyNode * getParent () { return _parent; }
 650
 651
 652   /**
 653    * Get a const pointer to the node's parent.
 654    */
 655   const SGPropertyNode * getParent () const { return _parent; }
 656
 657
 658   //
 659   // Children.
 660   //
 661
 662
 663   /**
 664    * Get the number of child nodes.
 665    */
 666   int nChildren () const { return _children.size(); }
 667
 668
 669   /**
 670    * Get a child node by position (*NOT* index).
 671    */
 672   SGPropertyNode * getChild (int position);
 673
 674
 675   /**
 676    * Get a const child node by position (*NOT* index).
 677    */
 678   const SGPropertyNode * getChild (int position) const;
 679
 680
 681   /**
 682    * Test whether a named child exists.
 683    */
 684   bool hasChild (const char * name, int index = 0) const
 685   {
 686     return (getChild(name, index) != 0);
 687   }
 688
 689
 690   /**
 691    * Get a child node by name and index.
 692    */
 693   SGPropertyNode * getChild (const char * name, int index = 0,
 694                              bool create = false);
 695
 696
 697   /**
 698    * Get a const child node by name and index.
 699    */
 700   const SGPropertyNode * getChild (const char * name, int index = 0) const;
 701
 702
 703   /**
 704    * Get a vector of all children with the specified name.
 705    */
 706   vector<SGPropertyNode_ptr> getChildren (const char * name) const;
 707
 708
 709   /**
 710    * Remove a child node
 711    */
 712   SGPropertyNode_ptr removeChild (const char * name, int index = 0,
 713                                   bool keep = true);
 714
 715
 716   //
 717   // Alias support.
 718   //
 719
 720
 721   /**
 722    * Alias this node's leaf value to another's.
 723    */
 724   bool alias (SGPropertyNode * target);
 725
 726
 727   /**
 728    * Alias this node's leaf value to another's by relative path.
 729    */
 730   bool alias (const char * path);
 731
 732
 733   /**
 734    * Remove any alias for this node.
 735    */
 736   bool unalias ();
 737
 738
 739   /**
 740    * Test whether the node's leaf value is aliased to another's.
 741    */
 742   bool isAlias () const { return (_type == ALIAS); }
 743
 744
 745   /**
 746    * Get a non-const pointer to the current alias target, if any.
 747    */
 748   SGPropertyNode * getAliasTarget ();
 749
 750
 751   /**
 752    * Get a const pointer to the current alias target, if any.
 753    */
 754   const SGPropertyNode * getAliasTarget () const;
 755
 756
 757   //
 758   // Path information.
 759   //
 760
 761
 762   /**
 763    * Get the path to this node from the root.
 764    */
 765   const char * getPath (bool simplify = false) const;
 766
 767
 768   /**
 769    * Get a pointer to the root node.
 770    */
 771   SGPropertyNode * getRootNode ();
 772
 773
 774   /**
 775    * Get a const pointer to the root node.
 776    */
 777   const SGPropertyNode * getRootNode () const;
 778
 779
 780   /**
 781    * Get a pointer to another node by relative path.
 782    */
 783   SGPropertyNode * getNode (const char * relative_path, bool create = false);
 784
 785
 786   /**
 787    * Get a pointer to another node by relative path.
 788    *
 789    * This method leaves the index off the last member of the path,
 790    * so that the user can specify it separately (and save some
 791    * string building).  For example, getNode("/bar[1]/foo", 3) is
 792    * exactly equivalent to getNode("bar[1]/foo[3]").  The index
 793    * provided overrides any given in the path itself for the last
 794    * component.
 795    */
 796   SGPropertyNode * getNode (const char * relative_path, int index,
 797                             bool create = false);
 798
 799
 800   /**
 801    * Get a const pointer to another node by relative path.
 802    */
 803   const SGPropertyNode * getNode (const char * relative_path) const;
 804
 805
 806   /**
 807    * Get a const pointer to another node by relative path.
 808    *
 809    * This method leaves the index off the last member of the path,
 810    * so that the user can specify it separate.
 811    */
 812   const SGPropertyNode * getNode (const char * relative_path,
 813                                   int index) const;
 814
 815
 816   //
 817   // Access Mode.
 818   //
 819
 820   /**
 821    * Check a single mode attribute for the property node.
 822    */
 823   bool getAttribute (Attribute attr) const { return ((_attr & attr) != 0); }
 824
 825
 826   /**
 827    * Set a single mode attribute for the property node.
 828    */
 829   void setAttribute (Attribute attr, bool state) {
 830     (state ? _attr |= attr : _attr &= ~attr);
 831   }
 832
 833
 834   /**
 835    * Get all of the mode attributes for the property node.
 836    */
 837   int getAttributes () const { return _attr; }
 838
 839
 840   /**
 841    * Set all of the mode attributes for the property node.
 842    */
 843   void setAttributes (int attr) { _attr = attr; }
 844
 845
 846   //
 847   // Leaf Value (primitive).
 848   //
 849
 850
 851   /**
 852    * Get the type of leaf value, if any, for this node.
 853    */
 854   Type getType () const;
 855
 856
 857   /**
 858    * Get a bool value for this node.
 859    */
 860   bool getBoolValue () const;
 861
 862
 863   /**
 864    * Get an int value for this node.
 865    */
 866   int getIntValue () const;
 867
 868
 869   /**
 870    * Get a long int value for this node.
 871    */
 872   long getLongValue () const;
 873
 874
 875   /**
 876    * Get a float value for this node.
 877    */
 878   float getFloatValue () const;
 879
 880
 881   /**
 882    * Get a double value for this node.
 883    */
 884   double getDoubleValue () const;
 885
 886
 887   /**
 888    * Get a string value for this node.
 889    */
 890   const char * getStringValue () const;
 891
 892
 893
 894   /**
 895    * Set a bool value for this node.
 896    */
 897   bool setBoolValue (bool value);
 898
 899
 900   /**
 901    * Set an int value for this node.
 902    */
 903   bool setIntValue (int value);
 904
 905
 906   /**
 907    * Set a long int value for this node.
 908    */
 909   bool setLongValue (long value);
 910
 911
 912   /**
 913    * Set a float value for this node.
 914    */
 915   bool setFloatValue (float value);
 916
 917
 918   /**
 919    * Set a double value for this node.
 920    */
 921   bool setDoubleValue (double value);
 922
 923
 924   /**
 925    * Set a string value for this node.
 926    */
 927   bool setStringValue (const char * value);
 928
 929
 930   /**
 931    * Set a value of unspecified type for this node.
 932    */
 933   bool setUnspecifiedValue (const char * value);
 934
 935
 936   //
 937   // Data binding.
 938   //
 939
 940
 941   /**
 942    * Test whether this node is bound to an external data source.
 943    */
 944   bool isTied () const { return _tied; }
 945
 946
 947   /**
 948    * Bind this node to an external bool source.
 949    */
 950   bool tie (const SGRawValue<bool> &rawValue, bool useDefault = true);
 951
 952
 953   /**
 954    * Bind this node to an external int source.
 955    */
 956   bool tie (const SGRawValue<int> &rawValue, bool useDefault = true);
 957
 958
 959   /**
 960    * Bind this node to an external long int source.
 961    */
 962   bool tie (const SGRawValue<long> &rawValue, bool useDefault = true);
 963
 964
 965   /**
 966    * Bind this node to an external float source.
 967    */
 968   bool tie (const SGRawValue<float> &rawValue, bool useDefault = true);
 969
 970
 971   /**
 972    * Bind this node to an external double source.
 973    */
 974   bool tie (const SGRawValue<double> &rawValue, bool useDefault = true);
 975
 976
 977   /**
 978    * Bind this node to an external string source.
 979    */
 980   bool tie (const SGRawValue<const char *> &rawValue, bool useDefault = true);
 981
 982
 983   /**
 984    * Unbind this node from any external data source.
 985    */
 986   bool untie ();
 987
 988
 989   //
 990   // Convenience methods using paths.
 991   // TODO: add attribute methods
 992   //
 993
 994
 995   /**
 996    * Get another node's type.
 997    */
 998   Type getType (const char * relative_path) const;
 999
1000
1001   /**
1002    * Test whether another node has a leaf value.
1003    */
1004   bool hasValue (const char * relative_path) const;
1005
1006
1007   /**
1008    * Get another node's value as a bool.
1009    */
1010   bool getBoolValue (const char * relative_path,
1011                      bool defaultValue = false) const;
1012
1013
1014   /**
1015    * Get another node's value as an int.
1016    */
1017   int getIntValue (const char * relative_path,
1018                    int defaultValue = 0) const;
1019
1020
1021   /**
1022    * Get another node's value as a long int.
1023    */
1024   long getLongValue (const char * relative_path,
1025                      long defaultValue = 0L) const;
1026
1027
1028   /**
1029    * Get another node's value as a float.
1030    */
1031   float getFloatValue (const char * relative_path,
1032                        float defaultValue = 0.0) const;
1033
1034
1035   /**
1036    * Get another node's value as a double.
1037    */
1038   double getDoubleValue (const char * relative_path,
1039                          double defaultValue = 0.0L) const;
1040
1041
1042   /**
1043    * Get another node's value as a string.
1044    */
1045   const char * getStringValue (const char * relative_path,
1046                                const char * defaultValue = "") const;
1047
1048
1049   /**
1050    * Set another node's value as a bool.
1051    */
1052   bool setBoolValue (const char * relative_path, bool value);
1053
1054
1055   /**
1056    * Set another node's value as an int.
1057    */
1058   bool setIntValue (const char * relative_path, int value);
1059
1060
1061   /**
1062    * Set another node's value as a long int.
1063    */
1064   bool setLongValue (const char * relative_path, long value);
1065
1066
1067   /**
1068    * Set another node's value as a float.
1069    */
1070   bool setFloatValue (const char * relative_path, float value);
1071
1072
1073   /**
1074    * Set another node's value as a double.
1075    */
1076   bool setDoubleValue (const char * relative_path, double value);
1077
1078
1079   /**
1080    * Set another node's value as a string.
1081    */
1082   bool setStringValue (const char * relative_path, const char * value);
1083
1084
1085   /**
1086    * Set another node's value with no specified type.
1087    */
1088   bool setUnspecifiedValue (const char * relative_path, const char * value);
1089
1090
1091   /**
1092    * Test whether another node is bound to an external data source.
1093    */
1094   bool isTied (const char * relative_path) const;
1095
1096
1097   /**
1098    * Bind another node to an external bool source.
1099    */
1100   bool tie (const char * relative_path, const SGRawValue<bool> &rawValue,
1101             bool useDefault = true);
1102
1103
1104   /**
1105    * Bind another node to an external int source.
1106    */
1107   bool tie (const char * relative_path, const SGRawValue<int> &rawValue,
1108             bool useDefault = true);
1109
1110
1111   /**
1112    * Bind another node to an external long int source.
1113    */
1114   bool tie (const char * relative_path, const SGRawValue<long> &rawValue,
1115             bool useDefault = true);
1116
1117
1118   /**
1119    * Bind another node to an external float source.
1120    */
1121   bool tie (const char * relative_path, const SGRawValue<float> &rawValue,
1122             bool useDefault = true);
1123
1124
1125   /**
1126    * Bind another node to an external double source.
1127    */
1128   bool tie (const char * relative_path, const SGRawValue<double> &rawValue,
1129             bool useDefault = true);
1130
1131
1132   /**
1133    * Bind another node to an external string source.
1134    */
1135   bool tie (const char * relative_path, const SGRawValue<const char *> &rawValue,
1136             bool useDefault = true);
1137
1138
1139   /**
1140    * Unbind another node from any external data source.
1141    */
1142   bool untie (const char * relative_path);
1143
1144
1145   /**
1146    * Add a change listener to the property.
1147    */
1148   void addChangeListener (SGPropertyChangeListener * listener);
1149
1150
1151   /**
1152    * Remove a change listener from the property.
1153    */
1154   void removeChangeListener (SGPropertyChangeListener * listener);
1155
1156
1157   /**
1158    * Fire a value change event to all listeners.
1159    */
1160   void fireValueChanged ();
1161
1162
1163   /**
1164    * Fire a child-added event to all listeners.
1165    */
1166   void fireChildAdded (SGPropertyNode * child);
1167
1168
1169   /**
1170    * Fire a child-removed event to all listeners.
1171    */
1172   void fireChildRemoved (SGPropertyNode * child);
1173
1174
1175   /**
1176    * Clear any existing value and set the type to NONE.
1177    */
1178   void clearValue ();
1179
1180
1181 protected:
1182
1183   void fireValueChanged (SGPropertyNode * node);
1184   void fireChildAdded (SGPropertyNode * parent, SGPropertyNode * child);
1185   void fireChildRemoved (SGPropertyNode * parent, SGPropertyNode * child);
1186
1187   /**
1188    * Protected constructor for making new nodes on demand.
1189    */
1190   SGPropertyNode (const char * name, int index, SGPropertyNode * parent);
1191
1192
1193 private:
1194
1195                                 // Get the raw value
1196   bool get_bool () const;
1197   int get_int () const;
1198   long get_long () const;
1199   float get_float () const;
1200   double get_double () const;
1201   const char * get_string () const;
1202
1203                                 // Set the raw value
1204   bool set_bool (bool value);
1205   bool set_int (int value);
1206   bool set_long (long value);
1207   bool set_float (float value);
1208   bool set_double (double value);
1209   bool set_string (const char * value);
1210
1211
1212   /**
1213    * Get the value as a string.
1214    */
1215   const char * make_string () const;
1216
1217
1218   /**
1219    * Trace a read access.
1220    */
1221   void trace_read () const;
1222
1223
1224   /**
1225    * Trace a write access.
1226    */
1227   void trace_write () const;
1228
1229
1230   /**
1231    * Increment reference counter
1232    */
1233   void incrementRef();
1234
1235   /**
1236    * Decrement reference counter
1237    */
1238   int decrementRef();
1239
1240   friend class SGPropertyNode_ptr;
1241
1242
1243   mutable char _buffer[MAX_STRING_LEN+1];
1244
1245   class hash_table;
1246
1247   char * _name;
1248   mutable char * _display_name;
1249   int _index;
1250   SGPropertyNode * _parent;
1251   vector<SGPropertyNode_ptr> _children;
1252   vector<SGPropertyNode_ptr> _removedChildren;
1253   mutable char * _path;
1254   hash_table * _path_cache;
1255   Type _type;
1256   bool _tied;
1257   int _attr;
1258   int _count;
1259
1260                                 // The right kind of pointer...
1261   union {
1262     SGPropertyNode * alias;
1263     SGRawValue<bool> * bool_val;
1264     SGRawValue<int> * int_val;
1265     SGRawValue<long> * long_val;
1266     SGRawValue<float> * float_val;
1267     SGRawValue<double> * double_val;
1268     SGRawValue<const char *> * string_val;
1269   } _value;
1270
1271   union {
1272     bool bool_val;
1273     int int_val;
1274     long long_val;
1275     float float_val;
1276     double double_val;
1277     char * string_val;
1278   } _local_val;
1279
1280   vector <SGPropertyChangeListener *> * _listeners;
1281
1282
1283 \f
1284   /**
1285    * A very simple hash table with no remove functionality.
1286    */
1287   class hash_table {
1288   public:
1289
1290     /**
1291      * An entry in a bucket in a hash table.
1292      */
1293     class entry {
1294     public:
1295       entry ();
1296       virtual ~entry ();
1297       virtual const char * get_key () { return _key; }
1298       virtual void set_key (const char * key);
1299       virtual SGPropertyNode * get_value () { return _value; }
1300       virtual void set_value (SGPropertyNode * value);
1301     private:
1302       char * _key;
1303       SGPropertyNode * _value;
1304     };
1305
1306
1307     /**
1308      * A bucket in a hash table.
1309      */
1310     class bucket {
1311     public:
1312       bucket ();
1313       virtual ~bucket ();
1314       virtual entry * get_entry (const char * key, bool create = false);
1315       virtual void erase(const char * key);
1316     private:
1317       int _length;
1318       entry ** _entries;
1319     };
1320
1321     friend class bucket;
1322
1323     hash_table ();
1324     virtual ~hash_table ();
1325     virtual SGPropertyNode * get (const char * key);
1326     virtual void put (const char * key, SGPropertyNode * value);
1327     virtual void erase(const char * key);
1328
1329   private:
1330     unsigned int hashcode (const char * key);
1331     unsigned int _data_length;
1332     bucket ** _data;
1333   };
1334
1335 };
1336
1337 #endif // __PROPS_HXX
1338
1339 // end of props.hxx