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