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