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