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