src/Main/fg_props.hxx

   1 // fg_props.hxx - Declarations and inline methods for property handling.
   2 // Written by David Megginson, started 2000.
   3 //
   4 // This file is in the Public Domain, and comes with no warranty.
   5
   6 #ifndef __FG_PROPS_HXX
   7 #define __FG_PROPS_HXX 1
   8
   9 #include <iosfwd>
  10
  11 #include <simgear/structure/subsystem_mgr.hxx>
  12 #include <simgear/math/SGMath.hxx>
  13 \f
  14 ////////////////////////////////////////////////////////////////////////
  15 // Property management.
  16 ////////////////////////////////////////////////////////////////////////
  17
  18 class FGProperties : public SGSubsystem
  19 {
  20 public:
  21     FGProperties ();
  22     virtual ~FGProperties ();
  23
  24     void init ();
  25     void bind ();
  26     void unbind ();
  27     void update (double dt);
  28 };
  29
  30
  31 /**
  32  * Save a flight to disk.
  33  *
  34  * This function saves all of the archivable properties to a stream
  35  * so that the current flight can be restored later.
  36  *
  37  * @param output The output stream to write the XML save file to.
  38  * @param write_all If true, write all properties rather than
  39  *        just the ones flagged as archivable.
  40  * @return true if the flight was saved successfully.
  41  */
  42 extern bool fgSaveFlight (std::ostream &output, bool write_all = false);
  43
  44
  45 /**
  46  * Load a flight from disk.
  47  *
  48  * This function loads an XML save file from a stream to restore
  49  * a flight.
  50  *
  51  * @param input The input stream to read the XML from.
  52  * @return true if the flight was restored successfully.
  53  */
  54 extern bool fgLoadFlight (std::istream &input);
  55
  56
  57 /**
  58  * Load properties from a file.
  59  *
  60  * @param file The relative or absolute filename.
  61  * @param props The property node to load the properties into.
  62  * @param in_fg_root If true, look for the file relative to
  63  *        $FG_ROOT; otherwise, look for the file relative to the
  64  *        current working directory.
  65  * @return true if the properties loaded successfully, false
  66  *         otherwise.
  67  */
  68 extern bool fgLoadProps (const char * path, SGPropertyNode * props,
  69                          bool in_fg_root = true, int default_mode = 0);
  70
  71
  72 \f
  73 ////////////////////////////////////////////////////////////////////////
  74 // Convenience functions for getting property values.
  75 ////////////////////////////////////////////////////////////////////////
  76
  77 /**
  78  * Get a property node.
  79  *
  80  * @param path The path of the node, relative to root.
  81  * @param create true to create the node if it doesn't exist.
  82  * @return The node, or 0 if none exists and none was created.
  83  */
  84 extern SGPropertyNode * fgGetNode (const char * path, bool create = false);
  85
  86
  87 /**
  88  * Get a property node with separate index.
  89  *
  90  * This method separates the index from the path string, to make it
  91  * easier to iterate through multiple components without using sprintf
  92  * to add indices.  For example, fgGetNode("foo[1]/bar", 3) will
  93  * return the same result as fgGetNode("foo[1]/bar[3]").
  94  *
  95  * @param path The path of the node, relative to root.
  96  * @param index The index for the last member of the path (overrides
  97  * any given in the string).
  98  * @param create true to create the node if it doesn't exist.
  99  * @return The node, or 0 if none exists and none was created.
 100  */
 101 extern SGPropertyNode * fgGetNode (const char * path,
 102                                    int index, bool create = false);
 103
 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 extern bool fgHasNode (const char * path);
 112
 113
 114 /**
 115  * Add a listener to a node.
 116  *
 117  * @param listener The listener to add to the node.
 118  * @param path The path of the node, relative to root.
 119  * @param index The index for the last member of the path (overrides
 120  * any given in the string).
 121  */
 122 extern void fgAddChangeListener (SGPropertyChangeListener * listener,
 123                                  const char * path);
 124
 125
 126 /**
 127  * Add a listener to a node.
 128  *
 129  * @param listener The listener to add to the node.
 130  * @param path The path of the node, relative to root.
 131  * @param index The index for the last member of the path (overrides
 132  * any given in the string).
 133  */
 134 extern void fgAddChangeListener (SGPropertyChangeListener * listener,
 135                                  const char * path, int index);
 136
 137
 138 /**
 139  * Get a bool value for a property.
 140  *
 141  * This method is convenient but inefficient.  It should be used
 142  * infrequently (i.e. for initializing, loading, saving, etc.),
 143  * not in the main loop.  If you need to get a value frequently,
 144  * it is better to look up the node itself using fgGetNode and then
 145  * use the node's getBoolValue() method, to avoid the lookup overhead.
 146  *
 147  * @param name The property name.
 148  * @param defaultValue The default value to return if the property
 149  *        does not exist.
 150  * @return The property's value as a bool, or the default value provided.
 151  */
 152 extern bool fgGetBool (const char * name, bool defaultValue = false);
 153
 154
 155 /**
 156  * Get an int value for a property.
 157  *
 158  * This method is convenient but inefficient.  It should be used
 159  * infrequently (i.e. for initializing, loading, saving, etc.),
 160  * not in the main loop.  If you need to get a value frequently,
 161  * it is better to look up the node itself using fgGetNode and then
 162  * use the node's getIntValue() method, to avoid the lookup overhead.
 163  *
 164  * @param name The property name.
 165  * @param defaultValue The default value to return if the property
 166  *        does not exist.
 167  * @return The property's value as an int, or the default value provided.
 168  */
 169 extern int fgGetInt (const char * name, int defaultValue = 0);
 170
 171
 172 /**
 173  * Get a long value for a property.
 174  *
 175  * This method is convenient but inefficient.  It should be used
 176  * infrequently (i.e. for initializing, loading, saving, etc.),
 177  * not in the main loop.  If you need to get a value frequently,
 178  * it is better to look up the node itself using fgGetNode and then
 179  * use the node's getLongValue() method, to avoid the lookup overhead.
 180  *
 181  * @param name The property name.
 182  * @param defaultValue The default value to return if the property
 183  *        does not exist.
 184  * @return The property's value as a long, or the default value provided.
 185  */
 186 extern int fgGetLong (const char * name, long defaultValue = 0L);
 187
 188
 189 /**
 190  * Get a float value for a property.
 191  *
 192  * This method is convenient but inefficient.  It should be used
 193  * infrequently (i.e. for initializing, loading, saving, etc.),
 194  * not in the main loop.  If you need to get a value frequently,
 195  * it is better to look up the node itself using fgGetNode and then
 196  * use the node's getFloatValue() method, to avoid the lookup overhead.
 197  *
 198  * @param name The property name.
 199  * @param defaultValue The default value to return if the property
 200  *        does not exist.
 201  * @return The property's value as a float, or the default value provided.
 202  */
 203 extern float fgGetFloat (const char * name, float defaultValue = 0.0);
 204
 205
 206 /**
 207  * Get a double value for a property.
 208  *
 209  * This method is convenient but inefficient.  It should be used
 210  * infrequently (i.e. for initializing, loading, saving, etc.),
 211  * not in the main loop.  If you need to get a value frequently,
 212  * it is better to look up the node itself using fgGetNode and then
 213  * use the node's getDoubleValue() method, to avoid the lookup overhead.
 214  *
 215  * @param name The property name.
 216  * @param defaultValue The default value to return if the property
 217  *        does not exist.
 218  * @return The property's value as a double, or the default value provided.
 219  */
 220 extern double fgGetDouble (const char * name, double defaultValue = 0.0);
 221
 222
 223 /**
 224  * Get a string value for a property.
 225  *
 226  * This method is convenient but inefficient.  It should be used
 227  * infrequently (i.e. for initializing, loading, saving, etc.),
 228  * not in the main loop.  If you need to get a value frequently,
 229  * it is better to look up the node itself using fgGetNode and then
 230  * use the node's getStringValue() method, to avoid the lookup overhead.
 231  *
 232  * @param name The property name.
 233  * @param defaultValue The default value to return if the property
 234  *        does not exist.
 235  * @return The property's value as a string, or the default value provided.
 236  */
 237 extern const char * fgGetString (const char * name,
 238                                  const char * defaultValue = "");
 239
 240
 241 /**
 242  * Set a bool value for a property.
 243  *
 244  * Assign a bool value to a property.  If the property does not
 245  * yet exist, it will be created and its type will be set to
 246  * BOOL; if it has a type of UNKNOWN, the type will also be set to
 247  * BOOL; otherwise, the bool value will be converted to the property's
 248  * type.
 249  *
 250  * @param name The property name.
 251  * @param val The new value for the property.
 252  * @return true if the assignment succeeded, false otherwise.
 253  */
 254 extern bool fgSetBool (const char * name, bool val);
 255
 256
 257 /**
 258  * Set an int value for a property.
 259  *
 260  * Assign an int value to a property.  If the property does not
 261  * yet exist, it will be created and its type will be set to
 262  * INT; if it has a type of UNKNOWN, the type will also be set to
 263  * INT; otherwise, the bool value will be converted to the property's
 264  * type.
 265  *
 266  * @param name The property name.
 267  * @param val The new value for the property.
 268  * @return true if the assignment succeeded, false otherwise.
 269  */
 270 extern bool fgSetInt (const char * name, int val);
 271
 272
 273 /**
 274  * Set a long value for a property.
 275  *
 276  * Assign a long value to a property.  If the property does not
 277  * yet exist, it will be created and its type will be set to
 278  * LONG; if it has a type of UNKNOWN, the type will also be set to
 279  * LONG; otherwise, the bool value will be converted to the property's
 280  * type.
 281  *
 282  * @param name The property name.
 283  * @param val The new value for the property.
 284  * @return true if the assignment succeeded, false otherwise.
 285  */
 286 extern bool fgSetLong (const char * name, long val);
 287
 288
 289 /**
 290  * Set a float value for a property.
 291  *
 292  * Assign a float value to a property.  If the property does not
 293  * yet exist, it will be created and its type will be set to
 294  * FLOAT; if it has a type of UNKNOWN, the type will also be set to
 295  * FLOAT; otherwise, the bool value will be converted to the property's
 296  * type.
 297  *
 298  * @param name The property name.
 299  * @param val The new value for the property.
 300  * @return true if the assignment succeeded, false otherwise.
 301  */
 302 extern bool fgSetFloat (const char * name, float val);
 303
 304
 305 /**
 306  * Set a double value for a property.
 307  *
 308  * Assign a double value to a property.  If the property does not
 309  * yet exist, it will be created and its type will be set to
 310  * DOUBLE; if it has a type of UNKNOWN, the type will also be set to
 311  * DOUBLE; otherwise, the double value will be converted to the property's
 312  * type.
 313  *
 314  * @param name The property name.
 315  * @param val The new value for the property.
 316  * @return true if the assignment succeeded, false otherwise.
 317  */
 318 extern bool fgSetDouble (const char * name, double val);
 319
 320
 321 /**
 322  * Set a string value for a property.
 323  *
 324  * Assign a string value to a property.  If the property does not
 325  * yet exist, it will be created and its type will be set to
 326  * STRING; if it has a type of UNKNOWN, the type will also be set to
 327  * STRING; otherwise, the string value will be converted to the property's
 328  * type.
 329  *
 330  * @param name The property name.
 331  * @param val The new value for the property.
 332  * @return true if the assignment succeeded, false otherwise.
 333  */
 334 extern bool fgSetString (const char * name, const char * val);
 335
 336
 337 \f
 338 ////////////////////////////////////////////////////////////////////////
 339 // Convenience functions for setting property attributes.
 340 ////////////////////////////////////////////////////////////////////////
 341
 342
 343 /**
 344  * Set the state of the archive attribute for a property.
 345  *
 346  * If the archive attribute is true, the property will be written
 347  * when a flight is saved; if it is false, the property will be
 348  * skipped.
 349  *
 350  * A warning message will be printed if the property does not exist.
 351  *
 352  * @param name The property name.
 353  * @param state The state of the archive attribute (defaults to true).
 354  */
 355 extern void fgSetArchivable (const char * name, bool state = true);
 356
 357
 358 /**
 359  * Set the state of the read attribute for a property.
 360  *
 361  * If the read attribute is true, the property value will be readable;
 362  * if it is false, the property value will always be the default value
 363  * for its type.
 364  *
 365  * A warning message will be printed if the property does not exist.
 366  *
 367  * @param name The property name.
 368  * @param state The state of the read attribute (defaults to true).
 369  */
 370 extern void fgSetReadable (const char * name, bool state = true);
 371
 372
 373 /**
 374  * Set the state of the write attribute for a property.
 375  *
 376  * If the write attribute is true, the property value may be modified
 377  * (depending on how it is tied); if the write attribute is false, the
 378  * property value may not be modified.
 379  *
 380  * A warning message will be printed if the property does not exist.
 381  *
 382  * @param name The property name.
 383  * @param state The state of the write attribute (defaults to true).
 384  */
 385 extern void fgSetWritable (const char * name, bool state = true);
 386
 387
 388 \f
 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 extern void fgUntie (const char * name);
 401
 402
 403 /**
 404  * Tie a property to a pair of simple functions.
 405  *
 406  * Every time the property value is queried, the getter (if any) will
 407  * be invoked; every time the property value is modified, the setter
 408  * (if any) will be invoked.  The getter can be 0 to make the property
 409  * unreadable, and the setter can be 0 to make the property
 410  * unmodifiable.
 411  *
 412  * @param name The property name to tie (full path).
 413  * @param getter The getter function, or 0 if the value is unreadable.
 414  * @param setter The setter function, or 0 if the value is unmodifiable.
 415  * @param useDefault true if the setter should be invoked with any existing
 416  *        property value should be; false if the old value should be
 417  *        discarded; defaults to true.
 418  */
 419 template <class V>
 420 inline void
 421 fgTie (const char * name, V (*getter)(), void (*setter)(V) = 0,
 422        bool useDefault = true)
 423 {
 424   if (!globals->get_props()->tie(name, SGRawValueFunctions<V>(getter, setter),
 425                                  useDefault))
 426     SG_LOG(SG_GENERAL, SG_WARN,
 427            "Failed to tie property " << name << " to functions");
 428 }
 429
 430
 431 /**
 432  * Tie a property to a pair of indexed functions.
 433  *
 434  * Every time the property value is queried, the getter (if any) will
 435  * be invoked with the index provided; every time the property value
 436  * is modified, the setter (if any) will be invoked with the index
 437  * provided.  The getter can be 0 to make the property unreadable, and
 438  * the setter can be 0 to make the property unmodifiable.
 439  *
 440  * @param name The property name to tie (full path).
 441  * @param index The integer argument to pass to the getter and
 442  *        setter functions.
 443  * @param getter The getter function, or 0 if the value is unreadable.
 444  * @param setter The setter function, or 0 if the value is unmodifiable.
 445  * @param useDefault true if the setter should be invoked with any existing
 446  *        property value should be; false if the old value should be
 447  *        discarded; defaults to true.
 448  */
 449 template <class V>
 450 inline void
 451 fgTie (const char * name, int index, V (*getter)(int),
 452        void (*setter)(int, V) = 0, bool useDefault = true)
 453 {
 454   if (!globals->get_props()->tie(name,
 455                                  SGRawValueFunctionsIndexed<V>(index,
 456                                                                getter,
 457                                                                setter),
 458                                  useDefault))
 459     SG_LOG(SG_GENERAL, SG_WARN,
 460            "Failed to tie property " << name << " to indexed functions");
 461 }
 462
 463
 464 /**
 465  * Tie a property to a pair of object methods.
 466  *
 467  * Every time the property value is queried, the getter (if any) will
 468  * be invoked; every time the property value is modified, the setter
 469  * (if any) will be invoked.  The getter can be 0 to make the property
 470  * unreadable, and the setter can be 0 to make the property
 471  * unmodifiable.
 472  *
 473  * @param name The property name to tie (full path).
 474  * @param obj The object whose methods should be invoked.
 475  * @param getter The object's getter method, or 0 if the value is
 476  *        unreadable.
 477  * @param setter The object's setter method, or 0 if the value is
 478  *        unmodifiable.
 479  * @param useDefault true if the setter should be invoked with any existing
 480  *        property value should be; false if the old value should be
 481  *        discarded; defaults to true.
 482  */
 483 template <class T, class V>
 484 inline void
 485 fgTie (const char * name, T * obj, V (T::*getter)() const,
 486        void (T::*setter)(V) = 0, bool useDefault = true)
 487 {
 488   if (!globals->get_props()->tie(name,
 489                                  SGRawValueMethods<T,V>(*obj, getter, setter),
 490                                  useDefault))
 491     SG_LOG(SG_GENERAL, SG_WARN,
 492            "Failed to tie property " << name << " to object methods");
 493 }
 494
 495
 496 /**
 497  * Tie a property to a pair of indexed object methods.
 498  *
 499  * Every time the property value is queried, the getter (if any) will
 500  * be invoked with the index provided; every time the property value
 501  * is modified, the setter (if any) will be invoked with the index
 502  * provided.  The getter can be 0 to make the property unreadable, and
 503  * the setter can be 0 to make the property unmodifiable.
 504  *
 505  * @param name The property name to tie (full path).
 506  * @param obj The object whose methods should be invoked.
 507  * @param index The integer argument to pass to the getter and
 508  *        setter methods.
 509  * @param getter The getter method, or 0 if the value is unreadable.
 510  * @param setter The setter method, or 0 if the value is unmodifiable.
 511  * @param useDefault true if the setter should be invoked with any existing
 512  *        property value should be; false if the old value should be
 513  *        discarded; defaults to true.
 514  */
 515 template <class T, class V>
 516 inline void
 517 fgTie (const char * name, T * obj, int index,
 518        V (T::*getter)(int) const, void (T::*setter)(int, V) = 0,
 519        bool useDefault = true)
 520 {
 521   if (!globals->get_props()->tie(name,
 522                                  SGRawValueMethodsIndexed<T,V>(*obj,
 523                                                                index,
 524                                                                getter,
 525                                                                setter),
 526                                  useDefault))
 527     SG_LOG(SG_GENERAL, SG_WARN,
 528            "Failed to tie property " << name << " to indexed object methods");
 529 }
 530
 531
 532 class FGMakeUpperCase : public SGPropertyChangeListener {
 533 public:
 534     void valueChanged(SGPropertyNode *node) {
 535         if (node->getType() != simgear::props::STRING)
 536             return;
 537
 538         char *s = const_cast<char *>(node->getStringValue());
 539         for (; *s; s++)
 540             *s = toupper(*s);
 541     }
 542 };
 543
 544
 545 #endif // __FG_PROPS_HXX
 546