1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 Header: FGPropertyManager.h
5 Based on work originally by David Megginson
8 ------------- Copyright (C) 2002 -------------
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
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
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.
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.
27 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
29 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
31 #ifndef FGPROPERTYMANAGER_H
32 #define FGPROPERTYMANAGER_H
34 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
36 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
40 # include <simgear/props/props.hxx>
42 # include "simgear/props/props.hxx"
45 #include "FGJSBBase.h"
47 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
49 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
51 #define ID_PROPERTYMANAGER "$Id$"
53 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
55 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
61 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
63 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
65 /** Class wrapper for property handling.
66 @author David Megginson, Tony Peden
69 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
71 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
73 class FGPropertyManager : public SGPropertyNode, public FGJSBBase
76 static bool suppress_warning;
79 FGPropertyManager(void) {suppress_warning = false;}
81 virtual ~FGPropertyManager(void) {}
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
90 string mkPropertyName(string name, bool lowercase);
93 * Get a property node.
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.
100 GetNode (const string &path, bool create = false);
103 GetNode (const string &relpath, 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 bool HasNode (const string &path);
114 * Get the name of a node
116 string GetName( void );
119 * Get the name of a node without underscores, etc.
121 string GetPrintableName( void );
124 * Get the fully qualified name of a node
125 * This function is very slow, so is probably useful for debugging only.
127 string GetFullyQualifiedName(void);
130 * Get a bool value for a property.
132 * This method is convenient but inefficient. It should be used
133 * infrequently (i.e. for initializing, loading, saving, etc.),
134 * not in the main loop. If you need to get a value frequently,
135 * it is better to look up the node itself using GetNode and then
136 * use the node's getBoolValue() method, to avoid the lookup overhead.
138 * @param name The property name.
139 * @param defaultValue The default value to return if the property
141 * @return The property's value as a bool, or the default value provided.
143 bool GetBool (const string &name, bool defaultValue = false);
147 * Get an int value for a property.
149 * This method is convenient but inefficient. It should be used
150 * infrequently (i.e. for initializing, loading, saving, etc.),
151 * not in the main loop. If you need to get a value frequently,
152 * it is better to look up the node itself using GetNode and then
153 * use the node's getIntValue() method, to avoid the lookup overhead.
155 * @param name The property name.
156 * @param defaultValue The default value to return if the property
158 * @return The property's value as an int, or the default value provided.
160 int GetInt (const string &name, int defaultValue = 0);
164 * Get a long value for a property.
166 * This method is convenient but inefficient. It should be used
167 * infrequently (i.e. for initializing, loading, saving, etc.),
168 * not in the main loop. If you need to get a value frequently,
169 * it is better to look up the node itself using GetNode and then
170 * use the node's getLongValue() method, to avoid the lookup overhead.
172 * @param name The property name.
173 * @param defaultValue The default value to return if the property
175 * @return The property's value as a long, or the default value provided.
177 int GetLong (const string &name, long defaultValue = 0L);
181 * Get a float value for a property.
183 * This method is convenient but inefficient. It should be used
184 * infrequently (i.e. for initializing, loading, saving, etc.),
185 * not in the main loop. If you need to get a value frequently,
186 * it is better to look up the node itself using GetNode and then
187 * use the node's getFloatValue() method, to avoid the lookup overhead.
189 * @param name The property name.
190 * @param defaultValue The default value to return if the property
192 * @return The property's value as a float, or the default value provided.
194 float GetFloat (const string &name, float defaultValue = 0.0);
198 * Get a double value for a property.
200 * This method is convenient but inefficient. It should be used
201 * infrequently (i.e. for initializing, loading, saving, etc.),
202 * not in the main loop. If you need to get a value frequently,
203 * it is better to look up the node itself using GetNode and then
204 * use the node's getDoubleValue() method, to avoid the lookup overhead.
206 * @param name The property name.
207 * @param defaultValue The default value to return if the property
209 * @return The property's value as a double, or the default value provided.
211 double GetDouble (const string &name, double defaultValue = 0.0);
215 * Get a string value for a property.
217 * This method is convenient but inefficient. It should be used
218 * infrequently (i.e. for initializing, loading, saving, etc.),
219 * not in the main loop. If you need to get a value frequently,
220 * it is better to look up the node itself using GetNode and then
221 * use the node's getStringValue() method, to avoid the lookup overhead.
223 * @param name The property name.
224 * @param defaultValue The default value to return if the property
226 * @return The property's value as a string, or the default value provided.
228 string GetString (const string &name, string defaultValue = "");
232 * Set a bool value for a property.
234 * Assign a bool value to a property. If the property does not
235 * yet exist, it will be created and its type will be set to
236 * BOOL; if it has a type of UNKNOWN, the type will also be set to
237 * BOOL; otherwise, the bool value will be converted to the property's
240 * @param name The property name.
241 * @param val The new value for the property.
242 * @return true if the assignment succeeded, false otherwise.
244 bool SetBool (const string &name, bool val);
248 * Set an int value for a property.
250 * Assign an int value to a property. If the property does not
251 * yet exist, it will be created and its type will be set to
252 * INT; if it has a type of UNKNOWN, the type will also be set to
253 * INT; otherwise, the bool value will be converted to the property's
256 * @param name The property name.
257 * @param val The new value for the property.
258 * @return true if the assignment succeeded, false otherwise.
260 bool SetInt (const string &name, int val);
264 * Set a long value for a property.
266 * Assign a long value to a property. If the property does not
267 * yet exist, it will be created and its type will be set to
268 * LONG; if it has a type of UNKNOWN, the type will also be set to
269 * LONG; otherwise, the bool value will be converted to the property's
272 * @param name The property name.
273 * @param val The new value for the property.
274 * @return true if the assignment succeeded, false otherwise.
276 bool SetLong (const string &name, long val);
280 * Set a float value for a property.
282 * Assign a float value to a property. If the property does not
283 * yet exist, it will be created and its type will be set to
284 * FLOAT; if it has a type of UNKNOWN, the type will also be set to
285 * FLOAT; otherwise, the bool value will be converted to the property's
288 * @param name The property name.
289 * @param val The new value for the property.
290 * @return true if the assignment succeeded, false otherwise.
292 bool SetFloat (const string &name, float val);
296 * Set a double value for a property.
298 * Assign a double value to a property. If the property does not
299 * yet exist, it will be created and its type will be set to
300 * DOUBLE; if it has a type of UNKNOWN, the type will also be set to
301 * DOUBLE; otherwise, the double value will be converted to the property's
304 * @param name The property name.
305 * @param val The new value for the property.
306 * @return true if the assignment succeeded, false otherwise.
308 bool SetDouble (const string &name, double val);
312 * Set a string value for a property.
314 * Assign a string value to a property. If the property does not
315 * yet exist, it will be created and its type will be set to
316 * STRING; if it has a type of UNKNOWN, the type will also be set to
317 * STRING; otherwise, the string value will be converted to the property's
320 * @param name The property name.
321 * @param val The new value for the property.
322 * @return true if the assignment succeeded, false otherwise.
324 bool SetString (const string &name, const string &val);
327 ////////////////////////////////////////////////////////////////////////
328 // Convenience functions for setting property attributes.
329 ////////////////////////////////////////////////////////////////////////
333 * Set the state of the archive attribute for a property.
335 * If the archive attribute is true, the property will be written
336 * when a flight is saved; if it is false, the property will be
339 * A warning message will be printed if the property does not exist.
341 * @param name The property name.
342 * @param state The state of the archive attribute (defaults to true).
344 void SetArchivable (const string &name, bool state = true);
348 * Set the state of the read attribute for a property.
350 * If the read attribute is true, the property value will be readable;
351 * if it is false, the property value will always be the default value
354 * A warning message will be printed if the property does not exist.
356 * @param name The property name.
357 * @param state The state of the read attribute (defaults to true).
359 void SetReadable (const string &name, bool state = true);
363 * Set the state of the write attribute for a property.
365 * If the write attribute is true, the property value may be modified
366 * (depending on how it is tied); if the write attribute is false, the
367 * property value may not be modified.
369 * A warning message will be printed if the property does not exist.
371 * @param name The property name.
372 * @param state The state of the write attribute (defaults to true).
374 void SetWritable (const string &name, bool state = true);
377 ////////////////////////////////////////////////////////////////////////
378 // Convenience functions for tying properties, with logging.
379 ////////////////////////////////////////////////////////////////////////
383 * Untie a property from an external data source.
385 * Classes should use this function to release control of any
386 * properties they are managing.
388 void Untie (const string &name);
391 // Templates cause ambiguity here
394 * Tie a property to an external bool variable.
396 * The property's value will automatically mirror the variable's
397 * value, and vice-versa, until the property is untied.
399 * @param name The property name to tie (full path).
400 * @param pointer A pointer to the variable.
401 * @param useDefault true if any existing property value should be
402 * copied to the variable; false if the variable should not
403 * be modified; defaults to true.
406 Tie (const string &name, bool *pointer, bool useDefault = true);
410 * Tie a property to an external int variable.
412 * The property's value will automatically mirror the variable's
413 * value, and vice-versa, until the property is untied.
415 * @param name The property name to tie (full path).
416 * @param pointer A pointer to the variable.
417 * @param useDefault true if any existing property value should be
418 * copied to the variable; false if the variable should not
419 * be modified; defaults to true.
422 Tie (const string &name, int *pointer, bool useDefault = true);
426 * Tie a property to an external long variable.
428 * The property's value will automatically mirror the variable's
429 * value, and vice-versa, until the property is untied.
431 * @param name The property name to tie (full path).
432 * @param pointer A pointer to the variable.
433 * @param useDefault true if any existing property value should be
434 * copied to the variable; false if the variable should not
435 * be modified; defaults to true.
438 Tie (const string &name, long *pointer, bool useDefault = true);
442 * Tie a property to an external float variable.
444 * The property's value will automatically mirror the variable's
445 * value, and vice-versa, until the property is untied.
447 * @param name The property name to tie (full path).
448 * @param pointer A pointer to the variable.
449 * @param useDefault true if any existing property value should be
450 * copied to the variable; false if the variable should not
451 * be modified; defaults to true.
454 Tie (const string &name, float *pointer, bool useDefault = true);
457 * Tie a property to an external double variable.
459 * The property's value will automatically mirror the variable's
460 * value, and vice-versa, until the property is untied.
462 * @param name The property name to tie (full path).
463 * @param pointer A pointer to the variable.
464 * @param useDefault true if any existing property value should be
465 * copied to the variable; false if the variable should not
466 * be modified; defaults to true.
469 Tie (const string &name, double *pointer, bool useDefault = true);
471 //============================================================================
473 // All of the following functions *must* be inlined, otherwise linker
474 // errors will result
476 //============================================================================
478 /* template <class V> void
479 Tie (const string &name, V (*getter)(), void (*setter)(V) = 0,
480 bool useDefault = true);
482 template <class V> void
483 Tie (const string &name, int index, V (*getter)(int),
484 void (*setter)(int, V) = 0, bool useDefault = true);
486 template <class T, class V> void
487 Tie (const string &name, T * obj, V (T::*getter)() const,
488 void (T::*setter)(V) = 0, bool useDefault = true);
490 template <class T, class V> void
491 Tie (const string &name, T * obj, int index,
492 V (T::*getter)(int) const, void (T::*setter)(int, V) = 0,
493 bool useDefault = true); */
496 * Tie a property to a pair of simple functions.
498 * Every time the property value is queried, the getter (if any) will
499 * be invoked; every time the property value is modified, the setter
500 * (if any) will be invoked. The getter can be 0 to make the property
501 * unreadable, and the setter can be 0 to make the property
504 * @param name The property name to tie (full path).
505 * @param getter The getter function, or 0 if the value is unreadable.
506 * @param setter The setter function, or 0 if the value is unmodifiable.
507 * @param useDefault true if the setter should be invoked with any existing
508 * property value should be; false if the old value should be
509 * discarded; defaults to true.
512 template <class V> inline void
513 Tie (const string &name, V (*getter)(), void (*setter)(V) = 0, bool useDefault = true)
515 if (!tie(name.c_str(), SGRawValueFunctions<V>(getter, setter), useDefault))
516 cout << "Failed to tie property " << name << " to functions" << endl;
517 else if (debug_lvl & 0x20)
518 cout << name << endl;
523 * Tie a property to a pair of indexed functions.
525 * Every time the property value is queried, the getter (if any) will
526 * be invoked with the index provided; every time the property value
527 * is modified, the setter (if any) will be invoked with the index
528 * provided. The getter can be 0 to make the property unreadable, and
529 * the setter can be 0 to make the property unmodifiable.
531 * @param name The property name to tie (full path).
532 * @param index The integer argument to pass to the getter and
534 * @param getter The getter function, or 0 if the value is unreadable.
535 * @param setter The setter function, or 0 if the value is unmodifiable.
536 * @param useDefault true if the setter should be invoked with any existing
537 * property value should there be one; false if the old value should be
538 * discarded; defaults to true.
540 template <class V> inline void Tie (const string &name, int index, V (*getter)(int),
541 void (*setter)(int, V) = 0, bool useDefault = true)
543 if (!tie(name.c_str(), SGRawValueFunctionsIndexed<V>(index, getter, setter), useDefault))
544 cout << "Failed to tie property " << name << " to indexed functions" << endl;
545 else if (debug_lvl & 0x20)
546 cout << name << endl;
551 * Tie a property to a pair of object methods.
553 * Every time the property value is queried, the getter (if any) will
554 * be invoked; every time the property value is modified, the setter
555 * (if any) will be invoked. The getter can be 0 to make the property
556 * unreadable, and the setter can be 0 to make the property
559 * @param name The property name to tie (full path).
560 * @param obj The object whose methods should be invoked.
561 * @param getter The object's getter method, or 0 if the value is
563 * @param setter The object's setter method, or 0 if the value is
565 * @param useDefault true if the setter should be invoked with any existing
566 * property value should be; false if the old value should be
567 * discarded; defaults to true.
569 template <class T, class V> inline void
570 Tie (const string &name, T * obj, V (T::*getter)() const,
571 void (T::*setter)(V) = 0, bool useDefault = true)
573 if (!tie(name.c_str(), SGRawValueMethods<T,V>(*obj, getter, setter), useDefault))
574 cout << "Failed to tie property " << name << " to object methods" << endl;
575 else if (debug_lvl & 0x20)
576 cout << name << endl;
580 * Tie a property to a pair of indexed object methods.
582 * Every time the property value is queried, the getter (if any) will
583 * be invoked with the index provided; every time the property value
584 * is modified, the setter (if any) will be invoked with the index
585 * provided. The getter can be 0 to make the property unreadable, and
586 * the setter can be 0 to make the property unmodifiable.
588 * @param name The property name to tie (full path).
589 * @param obj The object whose methods should be invoked.
590 * @param index The integer argument to pass to the getter and
592 * @param getter The getter method, or 0 if the value is unreadable.
593 * @param setter The setter method, or 0 if the value is unmodifiable.
594 * @param useDefault true if the setter should be invoked with any existing
595 * property value should be; false if the old value should be
596 * discarded; defaults to true.
598 template <class T, class V> inline void
599 Tie (const string &name, T * obj, int index, V (T::*getter)(int) const,
600 void (T::*setter)(int, V) = 0, bool useDefault = true)
602 if (!tie(name.c_str(), SGRawValueMethodsIndexed<T,V>(*obj, index, getter, setter), useDefault))
603 cout << "Failed to tie property " << name << " to indexed object methods" << endl;
604 else if (debug_lvl & 0x20)
605 cout << name << endl;
609 #endif // FGPROPERTYMANAGER_H