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