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 fully qualified name of a node
120 * This function is very slow, so is probably useful for debugging only.
122 string GetFullyQualifiedName(void);
125 * Get a bool value for a property.
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.
133 * @param name The property name.
134 * @param defaultValue The default value to return if the property
136 * @return The property's value as a bool, or the default value provided.
138 bool GetBool (const string &name, bool defaultValue = false);
142 * Get an int value for a property.
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.
150 * @param name The property name.
151 * @param defaultValue The default value to return if the property
153 * @return The property's value as an int, or the default value provided.
155 int GetInt (const string &name, int defaultValue = 0);
159 * Get a long value for a property.
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.
167 * @param name The property name.
168 * @param defaultValue The default value to return if the property
170 * @return The property's value as a long, or the default value provided.
172 int GetLong (const string &name, long defaultValue = 0L);
176 * Get a float value for a property.
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.
184 * @param name The property name.
185 * @param defaultValue The default value to return if the property
187 * @return The property's value as a float, or the default value provided.
189 float GetFloat (const string &name, float defaultValue = 0.0);
193 * Get a double value for a property.
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.
201 * @param name The property name.
202 * @param defaultValue The default value to return if the property
204 * @return The property's value as a double, or the default value provided.
206 double GetDouble (const string &name, double defaultValue = 0.0);
210 * Get a string value for a property.
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.
218 * @param name The property name.
219 * @param defaultValue The default value to return if the property
221 * @return The property's value as a string, or the default value provided.
223 string GetString (const string &name, string defaultValue = "");
227 * Set a bool value for a property.
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
235 * @param name The property name.
236 * @param val The new value for the property.
237 * @return true if the assignment succeeded, false otherwise.
239 bool SetBool (const string &name, bool val);
243 * Set an int value for a property.
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
251 * @param name The property name.
252 * @param val The new value for the property.
253 * @return true if the assignment succeeded, false otherwise.
255 bool SetInt (const string &name, int val);
259 * Set a long value for a property.
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
267 * @param name The property name.
268 * @param val The new value for the property.
269 * @return true if the assignment succeeded, false otherwise.
271 bool SetLong (const string &name, long val);
275 * Set a float value for a property.
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
283 * @param name The property name.
284 * @param val The new value for the property.
285 * @return true if the assignment succeeded, false otherwise.
287 bool SetFloat (const string &name, float val);
291 * Set a double value for a property.
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
299 * @param name The property name.
300 * @param val The new value for the property.
301 * @return true if the assignment succeeded, false otherwise.
303 bool SetDouble (const string &name, double val);
307 * Set a string value for a property.
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
315 * @param name The property name.
316 * @param val The new value for the property.
317 * @return true if the assignment succeeded, false otherwise.
319 bool SetString (const string &name, const string &val);
322 ////////////////////////////////////////////////////////////////////////
323 // Convenience functions for setting property attributes.
324 ////////////////////////////////////////////////////////////////////////
328 * Set the state of the archive attribute for a property.
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
334 * A warning message will be printed if the property does not exist.
336 * @param name The property name.
337 * @param state The state of the archive attribute (defaults to true).
339 void SetArchivable (const string &name, bool state = true);
343 * Set the state of the read attribute for a property.
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
349 * A warning message will be printed if the property does not exist.
351 * @param name The property name.
352 * @param state The state of the read attribute (defaults to true).
354 void SetReadable (const string &name, bool state = true);
358 * Set the state of the write attribute for a property.
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.
364 * A warning message will be printed if the property does not exist.
366 * @param name The property name.
367 * @param state The state of the write attribute (defaults to true).
369 void SetWritable (const string &name, bool state = true);
372 ////////////////////////////////////////////////////////////////////////
373 // Convenience functions for tying properties, with logging.
374 ////////////////////////////////////////////////////////////////////////
378 * Untie a property from an external data source.
380 * Classes should use this function to release control of any
381 * properties they are managing.
383 void Untie (const string &name);
386 // Templates cause ambiguity here
389 * Tie a property to an external bool variable.
391 * The property's value will automatically mirror the variable's
392 * value, and vice-versa, until the property is untied.
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.
401 Tie (const string &name, bool *pointer, bool useDefault = true);
405 * Tie a property to an external int variable.
407 * The property's value will automatically mirror the variable's
408 * value, and vice-versa, until the property is untied.
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.
417 Tie (const string &name, int *pointer, bool useDefault = true);
421 * Tie a property to an external long variable.
423 * The property's value will automatically mirror the variable's
424 * value, and vice-versa, until the property is untied.
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.
433 Tie (const string &name, long *pointer, bool useDefault = true);
437 * Tie a property to an external float variable.
439 * The property's value will automatically mirror the variable's
440 * value, and vice-versa, until the property is untied.
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.
449 Tie (const string &name, float *pointer, bool useDefault = true);
452 * Tie a property to an external double variable.
454 * The property's value will automatically mirror the variable's
455 * value, and vice-versa, until the property is untied.
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.
464 Tie (const string &name, double *pointer, bool useDefault = true);
466 //============================================================================
468 // All of the following functions *must* be inlined, otherwise linker
469 // errors will result
471 //============================================================================
473 /* template <class V> void
474 Tie (const string &name, V (*getter)(), void (*setter)(V) = 0,
475 bool useDefault = true);
477 template <class V> void
478 Tie (const string &name, int index, V (*getter)(int),
479 void (*setter)(int, V) = 0, bool useDefault = true);
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);
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); */
491 * Tie a property to a pair of simple functions.
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
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.
507 template <class V> inline void
508 Tie (const string &name, V (*getter)(), void (*setter)(V) = 0, bool useDefault = true)
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;
518 * Tie a property to a pair of indexed functions.
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.
526 * @param name The property name to tie (full path).
527 * @param index The integer argument to pass to the getter and
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.
535 template <class V> inline void Tie (const string &name, int index, V (*getter)(int),
536 void (*setter)(int, V) = 0, bool useDefault = true)
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;
546 * Tie a property to a pair of object methods.
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
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
558 * @param setter The object's setter method, or 0 if the value is
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.
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)
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;
575 * Tie a property to a pair of indexed object methods.
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.
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
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.
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)
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;
604 #endif // FGPROPERTYMANAGER_H