1 // fg_props.hxx - Declarations and inline methods for property handling.
2 // Written by David Megginson, started 2000.
4 // This file is in the Public Domain, and comes with no warranty.
7 #define __FG_PROPS_HXX 1
11 #include <simgear/structure/subsystem_mgr.hxx>
12 #include <simgear/math/SGMath.hxx>
14 ////////////////////////////////////////////////////////////////////////
15 // Property management.
16 ////////////////////////////////////////////////////////////////////////
18 class FGProperties : public SGSubsystem
22 virtual ~FGProperties ();
27 void update (double dt);
32 * Save a flight to disk.
34 * This function saves all of the archivable properties to a stream
35 * so that the current flight can be restored later.
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.
42 extern bool fgSaveFlight (std::ostream &output, bool write_all = false);
46 * Load a flight from disk.
48 * This function loads an XML save file from a stream to restore
51 * @param input The input stream to read the XML from.
52 * @return true if the flight was restored successfully.
54 extern bool fgLoadFlight (std::istream &input);
58 * Load properties from a file.
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
68 extern bool fgLoadProps (const char * path, SGPropertyNode * props,
69 bool in_fg_root = true, int default_mode = 0);
73 ////////////////////////////////////////////////////////////////////////
74 // Convenience functions for getting property values.
75 ////////////////////////////////////////////////////////////////////////
78 * Get a property node.
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.
84 extern SGPropertyNode * fgGetNode (const char * path, bool create = false);
88 * Get a property node with separate index.
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]").
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.
101 extern SGPropertyNode * fgGetNode (const char * path,
102 int index, bool create = false);
106 * Test whether a given node exists.
108 * @param path The path of the node, relative to root.
109 * @return true if the node exists, false otherwise.
111 extern bool fgHasNode (const char * path);
115 * Add a listener to a node.
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).
122 extern void fgAddChangeListener (SGPropertyChangeListener * listener,
127 * Add a listener to a node.
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).
134 extern void fgAddChangeListener (SGPropertyChangeListener * listener,
135 const char * path, int index);
139 * Get a bool value for a property.
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.
147 * @param name The property name.
148 * @param defaultValue The default value to return if the property
150 * @return The property's value as a bool, or the default value provided.
152 extern bool fgGetBool (const char * name, bool defaultValue = false);
156 * Get an int value for a property.
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.
164 * @param name The property name.
165 * @param defaultValue The default value to return if the property
167 * @return The property's value as an int, or the default value provided.
169 extern int fgGetInt (const char * name, int defaultValue = 0);
173 * Get a long value for a property.
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.
181 * @param name The property name.
182 * @param defaultValue The default value to return if the property
184 * @return The property's value as a long, or the default value provided.
186 extern int fgGetLong (const char * name, long defaultValue = 0L);
190 * Get a float value for a property.
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.
198 * @param name The property name.
199 * @param defaultValue The default value to return if the property
201 * @return The property's value as a float, or the default value provided.
203 extern float fgGetFloat (const char * name, float defaultValue = 0.0);
207 * Get a double value for a property.
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.
215 * @param name The property name.
216 * @param defaultValue The default value to return if the property
218 * @return The property's value as a double, or the default value provided.
220 extern double fgGetDouble (const char * name, double defaultValue = 0.0);
224 * Get a string value for a property.
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.
232 * @param name The property name.
233 * @param defaultValue The default value to return if the property
235 * @return The property's value as a string, or the default value provided.
237 extern const char * fgGetString (const char * name,
238 const char * defaultValue = "");
242 * Set a bool value for a property.
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
250 * @param name The property name.
251 * @param val The new value for the property.
252 * @return true if the assignment succeeded, false otherwise.
254 extern bool fgSetBool (const char * name, bool val);
258 * Set an int value for a property.
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
266 * @param name The property name.
267 * @param val The new value for the property.
268 * @return true if the assignment succeeded, false otherwise.
270 extern bool fgSetInt (const char * name, int val);
274 * Set a long value for a property.
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
282 * @param name The property name.
283 * @param val The new value for the property.
284 * @return true if the assignment succeeded, false otherwise.
286 extern bool fgSetLong (const char * name, long val);
290 * Set a float value for a property.
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
298 * @param name The property name.
299 * @param val The new value for the property.
300 * @return true if the assignment succeeded, false otherwise.
302 extern bool fgSetFloat (const char * name, float val);
306 * Set a double value for a property.
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
314 * @param name The property name.
315 * @param val The new value for the property.
316 * @return true if the assignment succeeded, false otherwise.
318 extern bool fgSetDouble (const char * name, double val);
322 * Set a string value for a property.
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
330 * @param name The property name.
331 * @param val The new value for the property.
332 * @return true if the assignment succeeded, false otherwise.
334 extern bool fgSetString (const char * name, const char * val);
338 ////////////////////////////////////////////////////////////////////////
339 // Convenience functions for setting property attributes.
340 ////////////////////////////////////////////////////////////////////////
344 * Set the state of the archive attribute for a property.
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
350 * A warning message will be printed if the property does not exist.
352 * @param name The property name.
353 * @param state The state of the archive attribute (defaults to true).
355 extern void fgSetArchivable (const char * name, bool state = true);
359 * Set the state of the read attribute for a property.
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
365 * A warning message will be printed if the property does not exist.
367 * @param name The property name.
368 * @param state The state of the read attribute (defaults to true).
370 extern void fgSetReadable (const char * name, bool state = true);
374 * Set the state of the write attribute for a property.
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.
380 * A warning message will be printed if the property does not exist.
382 * @param name The property name.
383 * @param state The state of the write attribute (defaults to true).
385 extern void fgSetWritable (const char * name, bool state = true);
389 ////////////////////////////////////////////////////////////////////////
390 // Convenience functions for tying properties, with logging.
391 ////////////////////////////////////////////////////////////////////////
395 * Untie a property from an external data source.
397 * Classes should use this function to release control of any
398 * properties they are managing.
400 extern void fgUntie (const char * name);
404 * Tie a property to a pair of simple functions.
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
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.
421 fgTie (const char * name, V (*getter)(), void (*setter)(V) = 0,
422 bool useDefault = true)
424 if (!globals->get_props()->tie(name, SGRawValueFunctions<V>(getter, setter),
426 SG_LOG(SG_GENERAL, SG_WARN,
427 "Failed to tie property " << name << " to functions");
432 * Tie a property to a pair of indexed functions.
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.
440 * @param name The property name to tie (full path).
441 * @param index The integer argument to pass to the getter and
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.
451 fgTie (const char * name, int index, V (*getter)(int),
452 void (*setter)(int, V) = 0, bool useDefault = true)
454 if (!globals->get_props()->tie(name,
455 SGRawValueFunctionsIndexed<V>(index,
459 SG_LOG(SG_GENERAL, SG_WARN,
460 "Failed to tie property " << name << " to indexed functions");
465 * Tie a property to a pair of object methods.
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
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
477 * @param setter The object's setter method, or 0 if the value is
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.
483 template <class T, class V>
485 fgTie (const char * name, T * obj, V (T::*getter)() const,
486 void (T::*setter)(V) = 0, bool useDefault = true)
488 if (!globals->get_props()->tie(name,
489 SGRawValueMethods<T,V>(*obj, getter, setter),
491 SG_LOG(SG_GENERAL, SG_WARN,
492 "Failed to tie property " << name << " to object methods");
497 * Tie a property to a pair of indexed object methods.
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.
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
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.
515 template <class T, class V>
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)
521 if (!globals->get_props()->tie(name,
522 SGRawValueMethodsIndexed<T,V>(*obj,
527 SG_LOG(SG_GENERAL, SG_WARN,
528 "Failed to tie property " << name << " to indexed object methods");
532 class FGMakeUpperCase : public SGPropertyChangeListener {
534 void valueChanged(SGPropertyNode *node) {
535 if (node->getType() != simgear::props::STRING)
538 char *s = const_cast<char *>(node->getStringValue());
545 #endif // __FG_PROPS_HXX