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 #include <simgear/misc/props.hxx>
  40
  41 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  42 DEFINITIONS
  43 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  44
  45 #define ID_PROPERTYMANAGER "$Id$"
  46
  47 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  48 FORWARD DECLARATIONS
  49 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  50
  51 using namespace std;
  52
  53 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  54 COMMENTS, REFERENCES, and NOTES [use "class documentation" below for API docs]
  55 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  56
  57 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  58 CLASS DOCUMENTATION
  59 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  60
  61 /** Class wrapper for property handling.
  62     @author David Megginson, Tony Peden
  63     @see <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/jsbsim/JSBSim/FGPropertyManager.h?rev=HEAD&content-type=text/vnd.viewcvs-markup">
  64          Header File </a>
  65     @see <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/jsbsim/JSBSim/FGPropertyManager.cpp?rev=HEAD&content-type=text/vnd.viewcvs-markup">
  66          Source File </a>
  67   */
  68
  69 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  70 CLASS DECLARATION
  71 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  72
  73 class FGPropertyManager : public SGPropertyNode {
  74   public:
  75     /// Constructor
  76     FGPropertyManager(void) {}
  77     /// Destructor
  78     ~FGPropertyManager(void) {}
  79
  80     /** Property-ify a name
  81      *  replaces spaces with '-' and, optionally, makes name all lower case
  82      *  @param name string to change
  83      *  @param lowercase true to change all upper case chars to lower
  84      *  NOTE: this function changes its argument and thus relies
  85      *  on pass by value
  86      */
  87     string mkPropertyName(string name, bool lowercase);
  88
  89     /**
  90      * Get a property node.
  91      *
  92      * @param path The path of the node, relative to root.
  93      * @param create true to create the node if it doesn't exist.
  94      * @return The node, or 0 if none exists and none was created.
  95      */
  96     FGPropertyManager*
  97     GetNode (const string &path, bool create = false);
  98
  99     FGPropertyManager*
 100     GetNode (const string &relpath, int index, bool create = false);
 101
 102     /**
 103      * Test whether a given node exists.
 104      *
 105      * @param path The path of the node, relative to root.
 106      * @return true if the node exists, false otherwise.
 107      */
 108     bool HasNode (const string &path);
 109
 110     /**
 111      * Get the name of a node
 112      */
 113     string GetName( void );
 114
 115     /**
 116      * Get the fully qualified name of a node
 117      * This function is very slow, so is probably useful for debugging only.
 118      */
 119     string GetFullyQualifiedName(void);
 120
 121     /**
 122      * Get a bool 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 getBoolValue() 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 bool, or the default value provided.
 134      */
 135     bool GetBool (const string &name, bool defaultValue = false);
 136
 137
 138     /**
 139      * Get an int value for a property.
 140      *
 141      * This method is convenient but inefficient.  It should be used
 142      * infrequently (i.e. for initializing, loading, saving, etc.),
 143      * not in the main loop.  If you need to get a value frequently,
 144      * it is better to look up the node itself using GetNode and then
 145      * use the node's getIntValue() method, to avoid the lookup overhead.
 146      *
 147      * @param name The property name.
 148      * @param defaultValue The default value to return if the property
 149      *        does not exist.
 150      * @return The property's value as an int, or the default value provided.
 151      */
 152     int GetInt (const string &name, int defaultValue = 0);
 153
 154
 155     /**
 156      * Get a long value for a property.
 157      *
 158      * This method is convenient but inefficient.  It should be used
 159      * infrequently (i.e. for initializing, loading, saving, etc.),
 160      * not in the main loop.  If you need to get a value frequently,
 161      * it is better to look up the node itself using GetNode and then
 162      * use the node's getLongValue() method, to avoid the lookup overhead.
 163      *
 164      * @param name The property name.
 165      * @param defaultValue The default value to return if the property
 166      *        does not exist.
 167      * @return The property's value as a long, or the default value provided.
 168      */
 169     int GetLong (const string &name, long defaultValue = 0L);
 170
 171
 172     /**
 173      * Get a float value for a property.
 174      *
 175      * This method is convenient but inefficient.  It should be used
 176      * infrequently (i.e. for initializing, loading, saving, etc.),
 177      * not in the main loop.  If you need to get a value frequently,
 178      * it is better to look up the node itself using GetNode and then
 179      * use the node's getFloatValue() method, to avoid the lookup overhead.
 180      *
 181      * @param name The property name.
 182      * @param defaultValue The default value to return if the property
 183      *        does not exist.
 184      * @return The property's value as a float, or the default value provided.
 185      */
 186     float GetFloat (const string &name, float defaultValue = 0.0);
 187
 188
 189     /**
 190      * Get a double value for a property.
 191      *
 192      * This method is convenient but inefficient.  It should be used
 193      * infrequently (i.e. for initializing, loading, saving, etc.),
 194      * not in the main loop.  If you need to get a value frequently,
 195      * it is better to look up the node itself using GetNode and then
 196      * use the node's getDoubleValue() method, to avoid the lookup overhead.
 197      *
 198      * @param name The property name.
 199      * @param defaultValue The default value to return if the property
 200      *        does not exist.
 201      * @return The property's value as a double, or the default value provided.
 202      */
 203     double GetDouble (const string &name, double defaultValue = 0.0);
 204
 205
 206     /**
 207      * Get a string value for a property.
 208      *
 209      * This method is convenient but inefficient.  It should be used
 210      * infrequently (i.e. for initializing, loading, saving, etc.),
 211      * not in the main loop.  If you need to get a value frequently,
 212      * it is better to look up the node itself using GetNode and then
 213      * use the node's getStringValue() method, to avoid the lookup overhead.
 214      *
 215      * @param name The property name.
 216      * @param defaultValue The default value to return if the property
 217      *        does not exist.
 218      * @return The property's value as a string, or the default value provided.
 219      */
 220     string GetString (const string &name, string defaultValue = "");
 221
 222
 223     /**
 224      * Set a bool value for a property.
 225      *
 226      * Assign a bool value to a property.  If the property does not
 227      * yet exist, it will be created and its type will be set to
 228      * BOOL; if it has a type of UNKNOWN, the type will also be set to
 229      * BOOL; otherwise, the bool value will be converted to the property's
 230      * type.
 231      *
 232      * @param name The property name.
 233      * @param val The new value for the property.
 234      * @return true if the assignment succeeded, false otherwise.
 235      */
 236     bool SetBool (const string &name, bool val);
 237
 238
 239     /**
 240      * Set an int value for a property.
 241      *
 242      * Assign an int value to a property.  If the property does not
 243      * yet exist, it will be created and its type will be set to
 244      * INT; if it has a type of UNKNOWN, the type will also be set to
 245      * INT; otherwise, the bool value will be converted to the property's
 246      * type.
 247      *
 248      * @param name The property name.
 249      * @param val The new value for the property.
 250      * @return true if the assignment succeeded, false otherwise.
 251      */
 252     bool SetInt (const string &name, int val);
 253
 254
 255     /**
 256      * Set a long value for a property.
 257      *
 258      * Assign a long value to a property.  If the property does not
 259      * yet exist, it will be created and its type will be set to
 260      * LONG; if it has a type of UNKNOWN, the type will also be set to
 261      * LONG; otherwise, the bool value will be converted to the property's
 262      * type.
 263      *
 264      * @param name The property name.
 265      * @param val The new value for the property.
 266      * @return true if the assignment succeeded, false otherwise.
 267      */
 268     bool SetLong (const string &name, long val);
 269
 270
 271     /**
 272      * Set a float value for a property.
 273      *
 274      * Assign a float value to a property.  If the property does not
 275      * yet exist, it will be created and its type will be set to
 276      * FLOAT; if it has a type of UNKNOWN, the type will also be set to
 277      * FLOAT; otherwise, the bool value will be converted to the property's
 278      * type.
 279      *
 280      * @param name The property name.
 281      * @param val The new value for the property.
 282      * @return true if the assignment succeeded, false otherwise.
 283      */
 284     bool SetFloat (const string &name, float val);
 285
 286
 287     /**
 288      * Set a double value for a property.
 289      *
 290      * Assign a double value to a property.  If the property does not
 291      * yet exist, it will be created and its type will be set to
 292      * DOUBLE; if it has a type of UNKNOWN, the type will also be set to
 293      * DOUBLE; otherwise, the double value will be converted to the property's
 294      * type.
 295      *
 296      * @param name The property name.
 297      * @param val The new value for the property.
 298      * @return true if the assignment succeeded, false otherwise.
 299      */
 300     bool SetDouble (const string &name, double val);
 301
 302
 303     /**
 304      * Set a string value for a property.
 305      *
 306      * Assign a string value to a property.  If the property does not
 307      * yet exist, it will be created and its type will be set to
 308      * STRING; if it has a type of UNKNOWN, the type will also be set to
 309      * STRING; otherwise, the string value will be converted to the property's
 310      * type.
 311      *
 312      * @param name The property name.
 313      * @param val The new value for the property.
 314      * @return true if the assignment succeeded, false otherwise.
 315      */
 316     bool SetString (const string &name, const string &val);
 317
 318
 319     ////////////////////////////////////////////////////////////////////////
 320     // Convenience functions for setting property attributes.
 321     ////////////////////////////////////////////////////////////////////////
 322
 323
 324     /**
 325      * Set the state of the archive attribute for a property.
 326      *
 327      * If the archive attribute is true, the property will be written
 328      * when a flight is saved; if it is false, the property will be
 329      * skipped.
 330      *
 331      * A warning message will be printed if the property does not exist.
 332      *
 333      * @param name The property name.
 334      * @param state The state of the archive attribute (defaults to true).
 335      */
 336     void SetArchivable (const string &name, bool state = true);
 337
 338
 339     /**
 340      * Set the state of the read attribute for a property.
 341      *
 342      * If the read attribute is true, the property value will be readable;
 343      * if it is false, the property value will always be the default value
 344      * for its type.
 345      *
 346      * A warning message will be printed if the property does not exist.
 347      *
 348      * @param name The property name.
 349      * @param state The state of the read attribute (defaults to true).
 350      */
 351     void SetReadable (const string &name, bool state = true);
 352
 353
 354     /**
 355      * Set the state of the write attribute for a property.
 356      *
 357      * If the write attribute is true, the property value may be modified
 358      * (depending on how it is tied); if the write attribute is false, the
 359      * property value may not be modified.
 360      *
 361      * A warning message will be printed if the property does not exist.
 362      *
 363      * @param name The property name.
 364      * @param state The state of the write attribute (defaults to true).
 365      */
 366     void SetWritable (const string &name, bool state = true);
 367
 368
 369     ////////////////////////////////////////////////////////////////////////
 370     // Convenience functions for tying properties, with logging.
 371     ////////////////////////////////////////////////////////////////////////
 372
 373
 374     /**
 375      * Untie a property from an external data source.
 376      *
 377      * Classes should use this function to release control of any
 378      * properties they are managing.
 379      */
 380     void Untie (const string &name);
 381
 382
 383                                     // Templates cause ambiguity here
 384
 385     /**
 386      * Tie a property to an external bool variable.
 387      *
 388      * The property's value will automatically mirror the variable's
 389      * value, and vice-versa, until the property is untied.
 390      *
 391      * @param name The property name to tie (full path).
 392      * @param pointer A pointer to the variable.
 393      * @param useDefault true if any existing property value should be
 394      *        copied to the variable; false if the variable should not
 395      *        be modified; defaults to true.
 396      */
 397     void
 398     Tie (const string &name, bool *pointer, bool useDefault = true);
 399
 400
 401     /**
 402      * Tie a property to an external int variable.
 403      *
 404      * The property's value will automatically mirror the variable's
 405      * value, and vice-versa, until the property is untied.
 406      *
 407      * @param name The property name to tie (full path).
 408      * @param pointer A pointer to the variable.
 409      * @param useDefault true if any existing property value should be
 410      *        copied to the variable; false if the variable should not
 411      *        be modified; defaults to true.
 412      */
 413     void
 414     Tie (const string &name, int *pointer, bool useDefault = true);
 415
 416
 417     /**
 418      * Tie a property to an external long variable.
 419      *
 420      * The property's value will automatically mirror the variable's
 421      * value, and vice-versa, until the property is untied.
 422      *
 423      * @param name The property name to tie (full path).
 424      * @param pointer A pointer to the variable.
 425      * @param useDefault true if any existing property value should be
 426      *        copied to the variable; false if the variable should not
 427      *        be modified; defaults to true.
 428      */
 429     void
 430     Tie (const string &name, long *pointer, bool useDefault = true);
 431
 432
 433     /**
 434      * Tie a property to an external float variable.
 435      *
 436      * The property's value will automatically mirror the variable's
 437      * value, and vice-versa, until the property is untied.
 438      *
 439      * @param name The property name to tie (full path).
 440      * @param pointer A pointer to the variable.
 441      * @param useDefault true if any existing property value should be
 442      *        copied to the variable; false if the variable should not
 443      *        be modified; defaults to true.
 444      */
 445     void
 446     Tie (const string &name, float *pointer, bool useDefault = true);
 447
 448     /**
 449      * Tie a property to an external double variable.
 450      *
 451      * The property's value will automatically mirror the variable's
 452      * value, and vice-versa, until the property is untied.
 453      *
 454      * @param name The property name to tie (full path).
 455      * @param pointer A pointer to the variable.
 456      * @param useDefault true if any existing property value should be
 457      *        copied to the variable; false if the variable should not
 458      *        be modified; defaults to true.
 459      */
 460     void
 461     Tie (const string &name, double *pointer, bool useDefault = true);
 462
 463 //============================================================================
 464 //
 465 //  All of the following functions *must* be inlined, otherwise linker
 466 //  errors will result
 467 //
 468 //============================================================================
 469
 470     /* template <class V> void
 471     Tie (const string &name, V (*getter)(), void (*setter)(V) = 0,
 472            bool useDefault = true);
 473
 474     template <class V> void
 475     Tie (const string &name, int index, V (*getter)(int),
 476            void (*setter)(int, V) = 0, bool useDefault = true);
 477
 478     template <class T, class V> void
 479     Tie (const string &name, T * obj, V (T::*getter)() const,
 480            void (T::*setter)(V) = 0, bool useDefault = true);
 481
 482     template <class T, class V> void
 483     Tie (const string &name, T * obj, int index,
 484            V (T::*getter)(int) const, void (T::*setter)(int, V) = 0,
 485            bool useDefault = true); */
 486
 487      /**
 488      * Tie a property to a pair of simple functions.
 489      *
 490      * Every time the property value is queried, the getter (if any) will
 491      * be invoked; every time the property value is modified, the setter
 492      * (if any) will be invoked.  The getter can be 0 to make the property
 493      * unreadable, and the setter can be 0 to make the property
 494      * unmodifiable.
 495      *
 496      * @param name The property name to tie (full path).
 497      * @param getter The getter function, or 0 if the value is unreadable.
 498      * @param setter The setter function, or 0 if the value is unmodifiable.
 499      * @param useDefault true if the setter should be invoked with any existing
 500      *        property value should be; false if the old value should be
 501      *        discarded; defaults to true.
 502      */
 503
 504     template <class V> inline void
 505     Tie (const string &name, V (*getter)(), void (*setter)(V) = 0,
 506                                               bool useDefault = true)
 507     {
 508       if (!tie(name.c_str(), SGRawValueFunctions<V>(getter, setter),
 509                                      useDefault))
 510         cout <<
 511                "Failed to tie property " << name << " to functions" << endl;
 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,
 539                                                                    getter,
 540                                                                    setter),
 541                                      useDefault))
 542         cout <<
 543                "Failed to tie property " << name << " to indexed functions" << endl;
 544     }
 545
 546
 547     /**
 548      * Tie a property to a pair of object methods.
 549      *
 550      * Every time the property value is queried, the getter (if any) will
 551      * be invoked; every time the property value is modified, the setter
 552      * (if any) will be invoked.  The getter can be 0 to make the property
 553      * unreadable, and the setter can be 0 to make the property
 554      * unmodifiable.
 555      *
 556      * @param name The property name to tie (full path).
 557      * @param obj The object whose methods should be invoked.
 558      * @param getter The object's getter method, or 0 if the value is
 559      *        unreadable.
 560      * @param setter The object's setter method, or 0 if the value is
 561      *        unmodifiable.
 562      * @param useDefault true if the setter should be invoked with any existing
 563      *        property value should be; false if the old value should be
 564      *        discarded; defaults to true.
 565      */
 566     template <class T, class V> inline void
 567     Tie (const string &name, T * obj, V (T::*getter)() const,
 568            void (T::*setter)(V) = 0, bool useDefault = true)
 569     {
 570       if (!tie(name.c_str(),
 571                                  SGRawValueMethods<T,V>(*obj, getter, setter),
 572                                  useDefault))
 573         cout <<
 574            "Failed to tie property " << name << " to object methods" << endl;
 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,
 603                                                                index,
 604                                                                getter,
 605                                                                setter),
 606                                  useDefault))
 607         cout <<
 608            "Failed to tie property " << name << " to indexed object methods" << endl;
 609    }
 610 };
 611
 612 #endif // FGPROPERTYMANAGER_H
 613