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