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 a bool value for a property.
 117      *
 118      * This method is convenient but inefficient.  It should be used
 119      * infrequently (i.e. for initializing, loading, saving, etc.),
 120      * not in the main loop.  If you need to get a value frequently,
 121      * it is better to look up the node itself using GetNode and then
 122      * use the node's getBoolValue() method, to avoid the lookup overhead.
 123      *
 124      * @param name The property name.
 125      * @param defaultValue The default value to return if the property
 126      *        does not exist.
 127      * @return The property's value as a bool, or the default value provided.
 128      */
 129     bool GetBool (const string &name, bool defaultValue = false);
 130
 131
 132     /**
 133      * Get an int value for a property.
 134      *
 135      * This method is convenient but inefficient.  It should be used
 136      * infrequently (i.e. for initializing, loading, saving, etc.),
 137      * not in the main loop.  If you need to get a value frequently,
 138      * it is better to look up the node itself using GetNode and then
 139      * use the node's getIntValue() method, to avoid the lookup overhead.
 140      *
 141      * @param name The property name.
 142      * @param defaultValue The default value to return if the property
 143      *        does not exist.
 144      * @return The property's value as an int, or the default value provided.
 145      */
 146     int GetInt (const string &name, int defaultValue = 0);
 147
 148
 149     /**
 150      * Get a long value for a property.
 151      *
 152      * This method is convenient but inefficient.  It should be used
 153      * infrequently (i.e. for initializing, loading, saving, etc.),
 154      * not in the main loop.  If you need to get a value frequently,
 155      * it is better to look up the node itself using GetNode and then
 156      * use the node's getLongValue() method, to avoid the lookup overhead.
 157      *
 158      * @param name The property name.
 159      * @param defaultValue The default value to return if the property
 160      *        does not exist.
 161      * @return The property's value as a long, or the default value provided.
 162      */
 163     int GetLong (const string &name, long defaultValue = 0L);
 164
 165
 166     /**
 167      * Get a float value for a property.
 168      *
 169      * This method is convenient but inefficient.  It should be used
 170      * infrequently (i.e. for initializing, loading, saving, etc.),
 171      * not in the main loop.  If you need to get a value frequently,
 172      * it is better to look up the node itself using GetNode and then
 173      * use the node's getFloatValue() method, to avoid the lookup overhead.
 174      *
 175      * @param name The property name.
 176      * @param defaultValue The default value to return if the property
 177      *        does not exist.
 178      * @return The property's value as a float, or the default value provided.
 179      */
 180     float GetFloat (const string &name, float defaultValue = 0.0);
 181
 182
 183     /**
 184      * Get a double value for a property.
 185      *
 186      * This method is convenient but inefficient.  It should be used
 187      * infrequently (i.e. for initializing, loading, saving, etc.),
 188      * not in the main loop.  If you need to get a value frequently,
 189      * it is better to look up the node itself using GetNode and then
 190      * use the node's getDoubleValue() method, to avoid the lookup overhead.
 191      *
 192      * @param name The property name.
 193      * @param defaultValue The default value to return if the property
 194      *        does not exist.
 195      * @return The property's value as a double, or the default value provided.
 196      */
 197     double GetDouble (const string &name, double defaultValue = 0.0);
 198
 199
 200     /**
 201      * Get a string value for a property.
 202      *
 203      * This method is convenient but inefficient.  It should be used
 204      * infrequently (i.e. for initializing, loading, saving, etc.),
 205      * not in the main loop.  If you need to get a value frequently,
 206      * it is better to look up the node itself using GetNode and then
 207      * use the node's getStringValue() method, to avoid the lookup overhead.
 208      *
 209      * @param name The property name.
 210      * @param defaultValue The default value to return if the property
 211      *        does not exist.
 212      * @return The property's value as a string, or the default value provided.
 213      */
 214     string GetString (const string &name, string defaultValue = "");
 215
 216
 217     /**
 218      * Set a bool value for a property.
 219      *
 220      * Assign a bool value to a property.  If the property does not
 221      * yet exist, it will be created and its type will be set to
 222      * BOOL; if it has a type of UNKNOWN, the type will also be set to
 223      * BOOL; otherwise, the bool value will be converted to the property's
 224      * type.
 225      *
 226      * @param name The property name.
 227      * @param val The new value for the property.
 228      * @return true if the assignment succeeded, false otherwise.
 229      */
 230     bool SetBool (const string &name, bool val);
 231
 232
 233     /**
 234      * Set an int value for a property.
 235      *
 236      * Assign an int value to a property.  If the property does not
 237      * yet exist, it will be created and its type will be set to
 238      * INT; if it has a type of UNKNOWN, the type will also be set to
 239      * INT; otherwise, the bool value will be converted to the property's
 240      * type.
 241      *
 242      * @param name The property name.
 243      * @param val The new value for the property.
 244      * @return true if the assignment succeeded, false otherwise.
 245      */
 246     bool SetInt (const string &name, int val);
 247
 248
 249     /**
 250      * Set a long value for a property.
 251      *
 252      * Assign a long value to a property.  If the property does not
 253      * yet exist, it will be created and its type will be set to
 254      * LONG; if it has a type of UNKNOWN, the type will also be set to
 255      * LONG; otherwise, the bool value will be converted to the property's
 256      * type.
 257      *
 258      * @param name The property name.
 259      * @param val The new value for the property.
 260      * @return true if the assignment succeeded, false otherwise.
 261      */
 262     bool SetLong (const string &name, long val);
 263
 264
 265     /**
 266      * Set a float value for a property.
 267      *
 268      * Assign a float value to a property.  If the property does not
 269      * yet exist, it will be created and its type will be set to
 270      * FLOAT; if it has a type of UNKNOWN, the type will also be set to
 271      * FLOAT; otherwise, the bool value will be converted to the property's
 272      * type.
 273      *
 274      * @param name The property name.
 275      * @param val The new value for the property.
 276      * @return true if the assignment succeeded, false otherwise.
 277      */
 278     bool SetFloat (const string &name, float val);
 279
 280
 281     /**
 282      * Set a double value for a property.
 283      *
 284      * Assign a double value to a property.  If the property does not
 285      * yet exist, it will be created and its type will be set to
 286      * DOUBLE; if it has a type of UNKNOWN, the type will also be set to
 287      * DOUBLE; otherwise, the double value will be converted to the property's
 288      * type.
 289      *
 290      * @param name The property name.
 291      * @param val The new value for the property.
 292      * @return true if the assignment succeeded, false otherwise.
 293      */
 294     bool SetDouble (const string &name, double val);
 295
 296
 297     /**
 298      * Set a string value for a property.
 299      *
 300      * Assign a string value to a property.  If the property does not
 301      * yet exist, it will be created and its type will be set to
 302      * STRING; if it has a type of UNKNOWN, the type will also be set to
 303      * STRING; otherwise, the string value will be converted to the property's
 304      * type.
 305      *
 306      * @param name The property name.
 307      * @param val The new value for the property.
 308      * @return true if the assignment succeeded, false otherwise.
 309      */
 310     bool SetString (const string &name, const string &val);
 311
 312
 313     ////////////////////////////////////////////////////////////////////////
 314     // Convenience functions for setting property attributes.
 315     ////////////////////////////////////////////////////////////////////////
 316
 317
 318     /**
 319      * Set the state of the archive attribute for a property.
 320      *
 321      * If the archive attribute is true, the property will be written
 322      * when a flight is saved; if it is false, the property will be
 323      * skipped.
 324      *
 325      * A warning message will be printed if the property does not exist.
 326      *
 327      * @param name The property name.
 328      * @param state The state of the archive attribute (defaults to true).
 329      */
 330     void SetArchivable (const string &name, bool state = true);
 331
 332
 333     /**
 334      * Set the state of the read attribute for a property.
 335      *
 336      * If the read attribute is true, the property value will be readable;
 337      * if it is false, the property value will always be the default value
 338      * for its type.
 339      *
 340      * A warning message will be printed if the property does not exist.
 341      *
 342      * @param name The property name.
 343      * @param state The state of the read attribute (defaults to true).
 344      */
 345     void SetReadable (const string &name, bool state = true);
 346
 347
 348     /**
 349      * Set the state of the write attribute for a property.
 350      *
 351      * If the write attribute is true, the property value may be modified
 352      * (depending on how it is tied); if the write attribute is false, the
 353      * property value may not be modified.
 354      *
 355      * A warning message will be printed if the property does not exist.
 356      *
 357      * @param name The property name.
 358      * @param state The state of the write attribute (defaults to true).
 359      */
 360     void SetWritable (const string &name, bool state = true);
 361
 362
 363     ////////////////////////////////////////////////////////////////////////
 364     // Convenience functions for tying properties, with logging.
 365     ////////////////////////////////////////////////////////////////////////
 366
 367
 368     /**
 369      * Untie a property from an external data source.
 370      *
 371      * Classes should use this function to release control of any
 372      * properties they are managing.
 373      */
 374     void Untie (const string &name);
 375
 376
 377                                     // Templates cause ambiguity here
 378
 379     /**
 380      * Tie a property to an external bool variable.
 381      *
 382      * The property's value will automatically mirror the variable's
 383      * value, and vice-versa, until the property is untied.
 384      *
 385      * @param name The property name to tie (full path).
 386      * @param pointer A pointer to the variable.
 387      * @param useDefault true if any existing property value should be
 388      *        copied to the variable; false if the variable should not
 389      *        be modified; defaults to true.
 390      */
 391     void
 392     Tie (const string &name, bool *pointer, bool useDefault = true);
 393
 394
 395     /**
 396      * Tie a property to an external int variable.
 397      *
 398      * The property's value will automatically mirror the variable's
 399      * value, and vice-versa, until the property is untied.
 400      *
 401      * @param name The property name to tie (full path).
 402      * @param pointer A pointer to the variable.
 403      * @param useDefault true if any existing property value should be
 404      *        copied to the variable; false if the variable should not
 405      *        be modified; defaults to true.
 406      */
 407     void
 408     Tie (const string &name, int *pointer, bool useDefault = true);
 409
 410
 411     /**
 412      * Tie a property to an external long variable.
 413      *
 414      * The property's value will automatically mirror the variable's
 415      * value, and vice-versa, until the property is untied.
 416      *
 417      * @param name The property name to tie (full path).
 418      * @param pointer A pointer to the variable.
 419      * @param useDefault true if any existing property value should be
 420      *        copied to the variable; false if the variable should not
 421      *        be modified; defaults to true.
 422      */
 423     void
 424     Tie (const string &name, long *pointer, bool useDefault = true);
 425
 426
 427     /**
 428      * Tie a property to an external float variable.
 429      *
 430      * The property's value will automatically mirror the variable's
 431      * value, and vice-versa, until the property is untied.
 432      *
 433      * @param name The property name to tie (full path).
 434      * @param pointer A pointer to the variable.
 435      * @param useDefault true if any existing property value should be
 436      *        copied to the variable; false if the variable should not
 437      *        be modified; defaults to true.
 438      */
 439     void
 440     Tie (const string &name, float *pointer, bool useDefault = true);
 441
 442     /**
 443      * Tie a property to an external double 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     void
 455     Tie (const string &name, double *pointer, bool useDefault = true);
 456
 457 //============================================================================
 458 //
 459 //  All of the following functions *must* be inlined, otherwise linker
 460 //  errors will result
 461 //
 462 //============================================================================
 463
 464     /* template <class V> void
 465     Tie (const string &name, V (*getter)(), void (*setter)(V) = 0,
 466            bool useDefault = true);
 467
 468     template <class V> void
 469     Tie (const string &name, int index, V (*getter)(int),
 470            void (*setter)(int, V) = 0, bool useDefault = true);
 471
 472     template <class T, class V> void
 473     Tie (const string &name, T * obj, V (T::*getter)() const,
 474            void (T::*setter)(V) = 0, bool useDefault = true);
 475
 476     template <class T, class V> void
 477     Tie (const string &name, T * obj, int index,
 478            V (T::*getter)(int) const, void (T::*setter)(int, V) = 0,
 479            bool useDefault = true); */
 480
 481      /**
 482      * Tie a property to a pair of simple functions.
 483      *
 484      * Every time the property value is queried, the getter (if any) will
 485      * be invoked; every time the property value is modified, the setter
 486      * (if any) will be invoked.  The getter can be 0 to make the property
 487      * unreadable, and the setter can be 0 to make the property
 488      * unmodifiable.
 489      *
 490      * @param name The property name to tie (full path).
 491      * @param getter The getter function, or 0 if the value is unreadable.
 492      * @param setter The setter function, or 0 if the value is unmodifiable.
 493      * @param useDefault true if the setter should be invoked with any existing
 494      *        property value should be; false if the old value should be
 495      *        discarded; defaults to true.
 496      */
 497
 498     template <class V> inline void
 499     Tie (const string &name, V (*getter)(), void (*setter)(V) = 0,
 500                                               bool useDefault = true)
 501     {
 502       if (!tie(name.c_str(), SGRawValueFunctions<V>(getter, setter),
 503                                      useDefault))
 504         cout <<
 505                "Failed to tie property " << name << " to functions" << endl;
 506     }
 507
 508
 509     /**
 510      * Tie a property to a pair of indexed functions.
 511      *
 512      * Every time the property value is queried, the getter (if any) will
 513      * be invoked with the index provided; every time the property value
 514      * is modified, the setter (if any) will be invoked with the index
 515      * provided.  The getter can be 0 to make the property unreadable, and
 516      * the setter can be 0 to make the property unmodifiable.
 517      *
 518      * @param name The property name to tie (full path).
 519      * @param index The integer argument to pass to the getter and
 520      *        setter functions.
 521      * @param getter The getter function, or 0 if the value is unreadable.
 522      * @param setter The setter function, or 0 if the value is unmodifiable.
 523      * @param useDefault true if the setter should be invoked with any existing
 524      *        property value should be; false if the old value should be
 525      *        discarded; defaults to true.
 526      */
 527     template <class V> inline void Tie (const string &name,
 528                                         int index, V (*getter)(int),
 529            void (*setter)(int, V) = 0, bool useDefault = true)
 530     {
 531       if (!tie(name.c_str(),
 532                                      SGRawValueFunctionsIndexed<V>(index,
 533                                                                    getter,
 534                                                                    setter),
 535                                      useDefault))
 536         cout <<
 537                "Failed to tie property " << name << " to indexed functions" << endl;
 538     }
 539
 540
 541     /**
 542      * Tie a property to a pair of object methods.
 543      *
 544      * Every time the property value is queried, the getter (if any) will
 545      * be invoked; every time the property value is modified, the setter
 546      * (if any) will be invoked.  The getter can be 0 to make the property
 547      * unreadable, and the setter can be 0 to make the property
 548      * unmodifiable.
 549      *
 550      * @param name The property name to tie (full path).
 551      * @param obj The object whose methods should be invoked.
 552      * @param getter The object's getter method, or 0 if the value is
 553      *        unreadable.
 554      * @param setter The object's setter method, or 0 if the value is
 555      *        unmodifiable.
 556      * @param useDefault true if the setter should be invoked with any existing
 557      *        property value should be; false if the old value should be
 558      *        discarded; defaults to true.
 559      */
 560     template <class T, class V> inline void
 561     Tie (const string &name, T * obj, V (T::*getter)() const,
 562            void (T::*setter)(V) = 0, bool useDefault = true)
 563     {
 564       if (!tie(name.c_str(),
 565                                  SGRawValueMethods<T,V>(*obj, getter, setter),
 566                                  useDefault))
 567         cout <<
 568            "Failed to tie property " << name << " to object methods" << endl;
 569     }
 570
 571     /**
 572      * Tie a property to a pair of indexed object methods.
 573      *
 574      * Every time the property value is queried, the getter (if any) will
 575      * be invoked with the index provided; every time the property value
 576      * is modified, the setter (if any) will be invoked with the index
 577      * provided.  The getter can be 0 to make the property unreadable, and
 578      * the setter can be 0 to make the property unmodifiable.
 579      *
 580      * @param name The property name to tie (full path).
 581      * @param obj The object whose methods should be invoked.
 582      * @param index The integer argument to pass to the getter and
 583      *        setter methods.
 584      * @param getter The getter method, or 0 if the value is unreadable.
 585      * @param setter The setter method, or 0 if the value is unmodifiable.
 586      * @param useDefault true if the setter should be invoked with any existing
 587      *        property value should be; false if the old value should be
 588      *        discarded; defaults to true.
 589      */
 590     template <class T, class V> inline void
 591     Tie (const string &name, T * obj, int index,
 592            V (T::*getter)(int) const, void (T::*setter)(int, V) = 0,
 593                                               bool useDefault = true)
 594     {
 595       if (!tie(name.c_str(),
 596                                  SGRawValueMethodsIndexed<T,V>(*obj,
 597                                                                index,
 598                                                                getter,
 599                                                                setter),
 600                                  useDefault))
 601         cout <<
 602            "Failed to tie property " << name << " to indexed object methods" << endl;
 603    }
 604 };
 605
 606 #endif // FGPROPERTYMANAGER_H
 607