src/FDM/JSBSim/FGPropertyManager.h

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