src/FDM/JSBSim/FGPropertyManager.h

   1 // FGPropertyManager.h
   2 // Class wrapper for property handling.
   3 // based on FlightGear source src/Main/fg_props.hxx
   4 // Originally written by David Megginson, started 2000.
   5 //
   6 // This file is in the Public Domain, and comes with no warranty.
   7
   8 #ifndef FGPROPERTYMANAGER_H
   9 #define FGPROPERTYMANAGER_H
  10
  11 #include <simgear/misc/props.hxx>
  12
  13 using namespace std;
  14
  15 class FGPropertyManager:public SGPropertyNode {
  16   public:
  17     FGPropertyManager::FGPropertyManager(void) {
  18
  19     }
  20
  21     FGPropertyManager::~FGPropertyManager(void) {
  22
  23     }
  24     /**
  25      * Get a property node.
  26      *
  27      * @param path The path of the node, relative to root.
  28      * @param create true to create the node if it doesn't exist.
  29      * @return The node, or 0 if none exists and none was created.
  30      */
  31     inline FGPropertyManager*
  32     GetNode (const string &path, bool create = false)
  33     {
  34       SGPropertyNode* node=this->getNode(path.c_str(), create);
  35       if(node == 0)
  36         cout << "FGPropertyManager::GetNode() No node found for "
  37              << path << endl;
  38       return (FGPropertyManager*)node;
  39     }
  40
  41     inline FGPropertyManager*
  42     GetNode (const string &relpath, int index, bool create = false)
  43     {
  44         return (FGPropertyManager*)getNode(relpath.c_str(),index,create);
  45     }
  46
  47
  48     /**
  49      * Test whether a given node exists.
  50      *
  51      * @param path The path of the node, relative to root.
  52      * @return true if the node exists, false otherwise.
  53      */
  54     inline bool
  55     HasNode (const string &path)
  56     {
  57       return (GetNode(path, false) != 0);
  58     }
  59
  60
  61     /**
  62      * Get a bool value for a property.
  63      *
  64      * This method is convenient but inefficient.  It should be used
  65      * infrequently (i.e. for initializing, loading, saving, etc.),
  66      * not in the main loop.  If you need to get a value frequently,
  67      * it is better to look up the node itself using GetNode and then
  68      * use the node's getBoolValue() method, to avoid the lookup overhead.
  69      *
  70      * @param name The property name.
  71      * @param defaultValue The default value to return if the property
  72      *        does not exist.
  73      * @return The property's value as a bool, or the default value provided.
  74      */
  75     inline bool GetBool (const string &name, bool defaultValue = false)
  76     {
  77       return getBoolValue(name.c_str(), defaultValue);
  78     }
  79
  80
  81     /**
  82      * Get an int value for a property.
  83      *
  84      * This method is convenient but inefficient.  It should be used
  85      * infrequently (i.e. for initializing, loading, saving, etc.),
  86      * not in the main loop.  If you need to get a value frequently,
  87      * it is better to look up the node itself using GetNode and then
  88      * use the node's getIntValue() method, to avoid the lookup overhead.
  89      *
  90      * @param name The property name.
  91      * @param defaultValue The default value to return if the property
  92      *        does not exist.
  93      * @return The property's value as an int, or the default value provided.
  94      */
  95     inline int GetInt (const string &name, int defaultValue = 0)
  96     {
  97       return getIntValue(name.c_str(), defaultValue);
  98     }
  99
 100
 101     /**
 102      * Get a long value for a property.
 103      *
 104      * This method is convenient but inefficient.  It should be used
 105      * infrequently (i.e. for initializing, loading, saving, etc.),
 106      * not in the main loop.  If you need to get a value frequently,
 107      * it is better to look up the node itself using GetNode and then
 108      * use the node's getLongValue() method, to avoid the lookup overhead.
 109      *
 110      * @param name The property name.
 111      * @param defaultValue The default value to return if the property
 112      *        does not exist.
 113      * @return The property's value as a long, or the default value provided.
 114      */
 115     inline int GetLong (const string &name, long defaultValue = 0L)
 116     {
 117       return getLongValue(name.c_str(), defaultValue);
 118     }
 119
 120
 121     /**
 122      * Get a float value for a property.
 123      *
 124      * This method is convenient but inefficient.  It should be used
 125      * infrequently (i.e. for initializing, loading, saving, etc.),
 126      * not in the main loop.  If you need to get a value frequently,
 127      * it is better to look up the node itself using GetNode and then
 128      * use the node's getFloatValue() method, to avoid the lookup overhead.
 129      *
 130      * @param name The property name.
 131      * @param defaultValue The default value to return if the property
 132      *        does not exist.
 133      * @return The property's value as a float, or the default value provided.
 134      */
 135     inline float GetFloat (const string &name, float defaultValue = 0.0)
 136     {
 137       return getFloatValue(name.c_str(), defaultValue);
 138     }
 139
 140
 141     /**
 142      * Get a double value for a property.
 143      *
 144      * This method is convenient but inefficient.  It should be used
 145      * infrequently (i.e. for initializing, loading, saving, etc.),
 146      * not in the main loop.  If you need to get a value frequently,
 147      * it is better to look up the node itself using GetNode and then
 148      * use the node's getDoubleValue() method, to avoid the lookup overhead.
 149      *
 150      * @param name The property name.
 151      * @param defaultValue The default value to return if the property
 152      *        does not exist.
 153      * @return The property's value as a double, or the default value provided.
 154      */
 155     inline double GetDouble (const string &name, double defaultValue = 0.0)
 156     {
 157       return getDoubleValue(name.c_str(), defaultValue);
 158     }
 159
 160
 161     /**
 162      * Get a string value for a property.
 163      *
 164      * This method is convenient but inefficient.  It should be used
 165      * infrequently (i.e. for initializing, loading, saving, etc.),
 166      * not in the main loop.  If you need to get a value frequently,
 167      * it is better to look up the node itself using GetNode and then
 168      * use the node's getStringValue() method, to avoid the lookup overhead.
 169      *
 170      * @param name The property name.
 171      * @param defaultValue The default value to return if the property
 172      *        does not exist.
 173      * @return The property's value as a string, or the default value provided.
 174      */
 175     inline string GetString (const string &name, string defaultValue = "")
 176     {
 177       return string(getStringValue(name.c_str(), defaultValue.c_str()));
 178     }
 179
 180
 181     /**
 182      * Set a bool value for a property.
 183      *
 184      * Assign a bool value to a property.  If the property does not
 185      * yet exist, it will be created and its type will be set to
 186      * BOOL; if it has a type of UNKNOWN, the type will also be set to
 187      * BOOL; otherwise, the bool value will be converted to the property's
 188      * type.
 189      *
 190      * @param name The property name.
 191      * @param val The new value for the property.
 192      * @return true if the assignment succeeded, false otherwise.
 193      */
 194     inline bool SetBool (const string &name, bool val)
 195     {
 196       return setBoolValue(name.c_str(), val);
 197     }
 198
 199
 200     /**
 201      * Set an int value for a property.
 202      *
 203      * Assign an int value to a property.  If the property does not
 204      * yet exist, it will be created and its type will be set to
 205      * INT; if it has a type of UNKNOWN, the type will also be set to
 206      * INT; otherwise, the bool value will be converted to the property's
 207      * type.
 208      *
 209      * @param name The property name.
 210      * @param val The new value for the property.
 211      * @return true if the assignment succeeded, false otherwise.
 212      */
 213     inline bool SetInt (const string &name, int val)
 214     {
 215       return setIntValue(name.c_str(), val);
 216     }
 217
 218
 219     /**
 220      * Set a long value for a property.
 221      *
 222      * Assign a long value to a property.  If the property does not
 223      * yet exist, it will be created and its type will be set to
 224      * LONG; if it has a type of UNKNOWN, the type will also be set to
 225      * LONG; otherwise, the bool value will be converted to the property's
 226      * type.
 227      *
 228      * @param name The property name.
 229      * @param val The new value for the property.
 230      * @return true if the assignment succeeded, false otherwise.
 231      */
 232     inline bool SetLong (const string &name, long val)
 233     {
 234       return setLongValue(name.c_str(), val);
 235     }
 236
 237
 238     /**
 239      * Set a float value for a property.
 240      *
 241      * Assign a float value to a property.  If the property does not
 242      * yet exist, it will be created and its type will be set to
 243      * FLOAT; if it has a type of UNKNOWN, the type will also be set to
 244      * FLOAT; otherwise, the bool value will be converted to the property's
 245      * type.
 246      *
 247      * @param name The property name.
 248      * @param val The new value for the property.
 249      * @return true if the assignment succeeded, false otherwise.
 250      */
 251     inline bool SetFloat (const string &name, float val)
 252     {
 253       return setFloatValue(name.c_str(), val);
 254     }
 255
 256
 257     /**
 258      * Set a double value for a property.
 259      *
 260      * Assign a double value to a property.  If the property does not
 261      * yet exist, it will be created and its type will be set to
 262      * DOUBLE; if it has a type of UNKNOWN, the type will also be set to
 263      * DOUBLE; otherwise, the double value will be converted to the property's
 264      * type.
 265      *
 266      * @param name The property name.
 267      * @param val The new value for the property.
 268      * @return true if the assignment succeeded, false otherwise.
 269      */
 270     inline bool SetDouble (const string &name, double val)
 271     {
 272       return setDoubleValue(name.c_str(), val);
 273     }
 274
 275
 276     /**
 277      * Set a string value for a property.
 278      *
 279      * Assign a string value to a property.  If the property does not
 280      * yet exist, it will be created and its type will be set to
 281      * STRING; if it has a type of UNKNOWN, the type will also be set to
 282      * STRING; otherwise, the string value will be converted to the property's
 283      * type.
 284      *
 285      * @param name The property name.
 286      * @param val The new value for the property.
 287      * @return true if the assignment succeeded, false otherwise.
 288      */
 289     inline bool SetString (const string &name, const string &val)
 290     {
 291       return setStringValue(name.c_str(), val.c_str());
 292     }
 293
 294
 295     \f
 296     ////////////////////////////////////////////////////////////////////////
 297     // Convenience functions for setting property attributes.
 298     ////////////////////////////////////////////////////////////////////////
 299
 300
 301     /**
 302      * Set the state of the archive attribute for a property.
 303      *
 304      * If the archive attribute is true, the property will be written
 305      * when a flight is saved; if it is false, the property will be
 306      * skipped.
 307      *
 308      * A warning message will be printed if the property does not exist.
 309      *
 310      * @param name The property name.
 311      * @param state The state of the archive attribute (defaults to true).
 312      */
 313     inline void
 314     SetArchivable (const string &name, bool state = true)
 315     {
 316       SGPropertyNode * node = getNode(name.c_str());
 317       if (node == 0)
 318         cout <<
 319                "Attempt to set archive flag for non-existant property "
 320                << name;
 321       else
 322         node->setAttribute(SGPropertyNode::ARCHIVE, state);
 323     }
 324
 325
 326     /**
 327      * Set the state of the read attribute for a property.
 328      *
 329      * If the read attribute is true, the property value will be readable;
 330      * if it is false, the property value will always be the default value
 331      * for its type.
 332      *
 333      * A warning message will be printed if the property does not exist.
 334      *
 335      * @param name The property name.
 336      * @param state The state of the read attribute (defaults to true).
 337      */
 338     inline void
 339     SetReadable (const string &name, bool state = true)
 340     {
 341       SGPropertyNode * node = getNode(name.c_str());
 342       if (node == 0)
 343         cout <<
 344                "Attempt to set read flag for non-existant property "
 345                << name;
 346       else
 347         node->setAttribute(SGPropertyNode::READ, state);
 348     }
 349
 350
 351     /**
 352      * Set the state of the write attribute for a property.
 353      *
 354      * If the write attribute is true, the property value may be modified
 355      * (depending on how it is tied); if the write attribute is false, the
 356      * property value may not be modified.
 357      *
 358      * A warning message will be printed if the property does not exist.
 359      *
 360      * @param name The property name.
 361      * @param state The state of the write attribute (defaults to true).
 362      */
 363     inline void
 364     SetWritable (const string &name, bool state = true)
 365     {
 366       SGPropertyNode * node = getNode(name.c_str());
 367       if (node == 0)
 368         cout <<
 369                "Attempt to set write flag for non-existant property "
 370                << name;
 371       else
 372         node->setAttribute(SGPropertyNode::WRITE, state);
 373     }
 374
 375
 376     \f
 377     ////////////////////////////////////////////////////////////////////////
 378     // Convenience functions for tying properties, with logging.
 379     ////////////////////////////////////////////////////////////////////////
 380
 381
 382     /**
 383      * Untie a property from an external data source.
 384      *
 385      * Classes should use this function to release control of any
 386      * properties they are managing.
 387      */
 388     inline void
 389     Untie (const string &name)
 390     {
 391       if (!untie(name.c_str()))
 392         cout << "Failed to untie property " << name;
 393     }
 394
 395
 396                                     // Templates cause ambiguity here
 397
 398     /**
 399      * Tie a property to an external bool variable.
 400      *
 401      * The property's value will automatically mirror the variable's
 402      * value, and vice-versa, until the property is untied.
 403      *
 404      * @param name The property name to tie (full path).
 405      * @param pointer A pointer to the variable.
 406      * @param useDefault true if any existing property value should be
 407      *        copied to the variable; false if the variable should not
 408      *        be modified; defaults to true.
 409      */
 410     inline void
 411     Tie (const string &name, bool *pointer, bool useDefault = true)
 412     {
 413       if (!tie(name.c_str(), SGRawValuePointer<bool>(pointer),
 414                                      useDefault))
 415         cout <<
 416                "Failed to tie property " << name << " to a pointer";
 417     }
 418
 419
 420     /**
 421      * Tie a property to an external int variable.
 422      *
 423      * The property's value will automatically mirror the variable's
 424      * value, and vice-versa, until the property is untied.
 425      *
 426      * @param name The property name to tie (full path).
 427      * @param pointer A pointer to the variable.
 428      * @param useDefault true if any existing property value should be
 429      *        copied to the variable; false if the variable should not
 430      *        be modified; defaults to true.
 431      */
 432     inline void
 433     Tie (const string &name, int *pointer, bool useDefault = true)
 434     {
 435       if (!tie(name.c_str(), SGRawValuePointer<int>(pointer),
 436                                      useDefault))
 437         cout <<
 438                "Failed to tie property " << name << " to a pointer";
 439     }
 440
 441
 442     /**
 443      * Tie a property to an external long variable.
 444      *
 445      * The property's value will automatically mirror the variable's
 446      * value, and vice-versa, until the property is untied.
 447      *
 448      * @param name The property name to tie (full path).
 449      * @param pointer A pointer to the variable.
 450      * @param useDefault true if any existing property value should be
 451      *        copied to the variable; false if the variable should not
 452      *        be modified; defaults to true.
 453      */
 454     inline void
 455     Tie (const string &name, long *pointer, bool useDefault = true)
 456     {
 457       if (!tie(name.c_str(), SGRawValuePointer<long>(pointer),
 458                                      useDefault))
 459         cout <<
 460                "Failed to tie property " << name << " to a pointer";
 461     }
 462
 463
 464     /**
 465      * Tie a property to an external float variable.
 466      *
 467      * The property's value will automatically mirror the variable's
 468      * value, and vice-versa, until the property is untied.
 469      *
 470      * @param name The property name to tie (full path).
 471      * @param pointer A pointer to the variable.
 472      * @param useDefault true if any existing property value should be
 473      *        copied to the variable; false if the variable should not
 474      *        be modified; defaults to true.
 475      */
 476     inline void
 477     Tie (const string &name, float *pointer, bool useDefault = true)
 478     {
 479       if (!tie(name.c_str(), SGRawValuePointer<float>(pointer),
 480                                      useDefault))
 481         cout <<
 482                "Failed to tie property " << name << " to a pointer";
 483     }
 484
 485
 486     /**
 487      * Tie a property to an external double variable.
 488      *
 489      * The property's value will automatically mirror the variable's
 490      * value, and vice-versa, until the property is untied.
 491      *
 492      * @param name The property name to tie (full path).
 493      * @param pointer A pointer to the variable.
 494      * @param useDefault true if any existing property value should be
 495      *        copied to the variable; false if the variable should not
 496      *        be modified; defaults to true.
 497      */
 498     inline void
 499     Tie (const string &name, double *pointer, bool useDefault = true)
 500     {
 501       if (!tie(name.c_str(), SGRawValuePointer<double>(pointer),
 502                                      useDefault))
 503         cout <<
 504                "Failed to tie property " << name << " to a pointer";
 505     }
 506
 507     /* template <class V> void
 508     FGPropertyManager::Tie (const string &name, V (*getter)(), void (*setter)(V) = 0,
 509            bool useDefault = true);
 510
 511     template <class V> void
 512     FGPropertyManager::Tie (const string &name, int index, V (*getter)(int),
 513            void (*setter)(int, V) = 0, bool useDefault = true);
 514
 515     template <class T, class V> void
 516     FGPropertyManager::Tie (const string &name, T * obj, V (T::*getter)() const,
 517            void (T::*setter)(V) = 0, bool useDefault = true);
 518
 519     template <class T, class V> void
 520     FGPropertyManager::Tie (const string &name, T * obj, int index,
 521            V (T::*getter)(int) const, void (T::*setter)(int, V) = 0,
 522            bool useDefault = true); */
 523
 524 /**
 525      * Tie a property to a pair of simple functions.
 526      *
 527      * Every time the property value is queried, the getter (if any) will
 528      * be invoked; every time the property value is modified, the setter
 529      * (if any) will be invoked.  The getter can be 0 to make the property
 530      * unreadable, and the setter can be 0 to make the property
 531      * unmodifiable.
 532      *
 533      * @param name The property name to tie (full path).
 534      * @param getter The getter function, or 0 if the value is unreadable.
 535      * @param setter The setter function, or 0 if the value is unmodifiable.
 536      * @param useDefault true if the setter should be invoked with any existing
 537      *        property value should be; false if the old value should be
 538      *        discarded; defaults to true.
 539      */
 540     template <class V>
 541     inline void
 542     FGPropertyManager::Tie (const string &name, V (*getter)(), void (*setter)(V) = 0,
 543            bool useDefault = true)
 544     {
 545       if (!tie(name.c_str(), SGRawValueFunctions<V>(getter, setter),
 546                                      useDefault))
 547         cout <<
 548                "Failed to tie property " << name << " to functions";
 549     }
 550
 551
 552     /**
 553      * Tie a property to a pair of indexed functions.
 554      *
 555      * Every time the property value is queried, the getter (if any) will
 556      * be invoked with the index provided; every time the property value
 557      * is modified, the setter (if any) will be invoked with the index
 558      * provided.  The getter can be 0 to make the property unreadable, and
 559      * the setter can be 0 to make the property unmodifiable.
 560      *
 561      * @param name The property name to tie (full path).
 562      * @param index The integer argument to pass to the getter and
 563      *        setter functions.
 564      * @param getter The getter function, or 0 if the value is unreadable.
 565      * @param setter The setter function, or 0 if the value is unmodifiable.
 566      * @param useDefault true if the setter should be invoked with any existing
 567      *        property value should be; false if the old value should be
 568      *        discarded; defaults to true.
 569      */
 570     template <class V>
 571     inline void
 572     FGPropertyManager::Tie (const string &name, int index, V (*getter)(int),
 573            void (*setter)(int, V) = 0, bool useDefault = true)
 574     {
 575       if (!tie(name.c_str(),
 576                                      SGRawValueFunctionsIndexed<V>(index,
 577                                                                    getter,
 578                                                                    setter),
 579                                      useDefault))
 580         cout <<
 581                "Failed to tie property " << name << " to indexed functions";
 582     }
 583
 584
 585     /**
 586      * Tie a property to a pair of object methods.
 587      *
 588      * Every time the property value is queried, the getter (if any) will
 589      * be invoked; every time the property value is modified, the setter
 590      * (if any) will be invoked.  The getter can be 0 to make the property
 591      * unreadable, and the setter can be 0 to make the property
 592      * unmodifiable.
 593      *
 594      * @param name The property name to tie (full path).
 595      * @param obj The object whose methods should be invoked.
 596      * @param getter The object's getter method, or 0 if the value is
 597      *        unreadable.
 598      * @param setter The object's setter method, or 0 if the value is
 599      *        unmodifiable.
 600      * @param useDefault true if the setter should be invoked with any existing
 601      *        property value should be; false if the old value should be
 602      *        discarded; defaults to true.
 603      */
 604     template <class T, class V>
 605     inline void
 606     FGPropertyManager::Tie (const string &name, T * obj, V (T::*getter)() const,
 607            void (T::*setter)(V) = 0, bool useDefault = true)
 608     {
 609       if (!tie(name.c_str(),
 610                                      SGRawValueMethods<T,V>(*obj, getter, setter),
 611                                      useDefault))
 612         cout <<
 613                "Failed to tie property " << name << " to object methods";
 614     }
 615
 616
 617     /**
 618      * Tie a property to a pair of indexed object methods.
 619      *
 620      * Every time the property value is queried, the getter (if any) will
 621      * be invoked with the index provided; every time the property value
 622      * is modified, the setter (if any) will be invoked with the index
 623      * provided.  The getter can be 0 to make the property unreadable, and
 624      * the setter can be 0 to make the property unmodifiable.
 625      *
 626      * @param name The property name to tie (full path).
 627      * @param obj The object whose methods should be invoked.
 628      * @param index The integer argument to pass to the getter and
 629      *        setter methods.
 630      * @param getter The getter method, or 0 if the value is unreadable.
 631      * @param setter The setter method, or 0 if the value is unmodifiable.
 632      * @param useDefault true if the setter should be invoked with any existing
 633      *        property value should be; false if the old value should be
 634      *        discarded; defaults to true.
 635      */
 636     template <class T, class V>
 637     inline void
 638     FGPropertyManager::Tie (const string &name, T * obj, int index,
 639            V (T::*getter)(int) const, void (T::*setter)(int, V) = 0,
 640            bool useDefault = true)
 641     {
 642       if (!tie(name.c_str(),
 643                                      SGRawValueMethodsIndexed<T,V>(*obj,
 644                                                                    index,
 645                                                                    getter,
 646                                                                    setter),
 647                                      useDefault))
 648         cout <<
 649                "Failed to tie property " << name << " to indexed object methods";
 650     }
 651
 652 };
 653
 654
 655 #endif // FGPROPERTYMANAGER_H
 656