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 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 General Public License for more
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.
24 Further information about the GNU 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 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
39 #include <simgear/props/props.hxx>
41 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
43 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
45 #define ID_PROPERTYMANAGER "$Id$"
47 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
49 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
55 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
57 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
59 /** Class wrapper for property handling.
60 @author David Megginson, Tony Peden
63 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
65 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
67 class FGPropertyManager : public SGPropertyNode {
70 FGPropertyManager(void) {}
72 ~FGPropertyManager(void) {}
74 /** Property-ify a name
75 * replaces spaces with '-' and, optionally, makes name all lower case
76 * @param name string to change
77 * @param lowercase true to change all upper case chars to lower
78 * NOTE: this function changes its argument and thus relies
81 string mkPropertyName(string name, bool lowercase);
84 * Get a property node.
86 * @param path The path of the node, relative to root.
87 * @param create true to create the node if it doesn't exist.
88 * @return The node, or 0 if none exists and none was created.
91 GetNode (const string &path, bool create = false);
94 GetNode (const string &relpath, int index, bool create = false);
97 * Test whether a given node exists.
99 * @param path The path of the node, relative to root.
100 * @return true if the node exists, false otherwise.
102 bool HasNode (const string &path);
105 * Get the name of a node
107 string GetName( void );
110 * Get the fully qualified name of a node
111 * This function is very slow, so is probably useful for debugging only.
113 string GetFullyQualifiedName(void);
116 * Get a bool value for a property.
118 * This method is convenient but inefficient. It should be used
119 * infrequently (i.e. for initializing, loading, saving, etc.),
120 * not in the main loop. If you need to get a value frequently,
121 * it is better to look up the node itself using GetNode and then
122 * use the node's getBoolValue() method, to avoid the lookup overhead.
124 * @param name The property name.
125 * @param defaultValue The default value to return if the property
127 * @return The property's value as a bool, or the default value provided.
129 bool GetBool (const string &name, bool defaultValue = false);
133 * Get an int value for a property.
135 * This method is convenient but inefficient. It should be used
136 * infrequently (i.e. for initializing, loading, saving, etc.),
137 * not in the main loop. If you need to get a value frequently,
138 * it is better to look up the node itself using GetNode and then
139 * use the node's getIntValue() method, to avoid the lookup overhead.
141 * @param name The property name.
142 * @param defaultValue The default value to return if the property
144 * @return The property's value as an int, or the default value provided.
146 int GetInt (const string &name, int defaultValue = 0);
150 * Get a long value for a property.
152 * This method is convenient but inefficient. It should be used
153 * infrequently (i.e. for initializing, loading, saving, etc.),
154 * not in the main loop. If you need to get a value frequently,
155 * it is better to look up the node itself using GetNode and then
156 * use the node's getLongValue() method, to avoid the lookup overhead.
158 * @param name The property name.
159 * @param defaultValue The default value to return if the property
161 * @return The property's value as a long, or the default value provided.
163 int GetLong (const string &name, long defaultValue = 0L);
167 * Get a float value for a property.
169 * This method is convenient but inefficient. It should be used
170 * infrequently (i.e. for initializing, loading, saving, etc.),
171 * not in the main loop. If you need to get a value frequently,
172 * it is better to look up the node itself using GetNode and then
173 * use the node's getFloatValue() method, to avoid the lookup overhead.
175 * @param name The property name.
176 * @param defaultValue The default value to return if the property
178 * @return The property's value as a float, or the default value provided.
180 float GetFloat (const string &name, float defaultValue = 0.0);
184 * Get a double value for a property.
186 * This method is convenient but inefficient. It should be used
187 * infrequently (i.e. for initializing, loading, saving, etc.),
188 * not in the main loop. If you need to get a value frequently,
189 * it is better to look up the node itself using GetNode and then
190 * use the node's getDoubleValue() method, to avoid the lookup overhead.
192 * @param name The property name.
193 * @param defaultValue The default value to return if the property
195 * @return The property's value as a double, or the default value provided.
197 double GetDouble (const string &name, double defaultValue = 0.0);
201 * Get a string value for a property.
203 * This method is convenient but inefficient. It should be used
204 * infrequently (i.e. for initializing, loading, saving, etc.),
205 * not in the main loop. If you need to get a value frequently,
206 * it is better to look up the node itself using GetNode and then
207 * use the node's getStringValue() method, to avoid the lookup overhead.
209 * @param name The property name.
210 * @param defaultValue The default value to return if the property
212 * @return The property's value as a string, or the default value provided.
214 string GetString (const string &name, string defaultValue = "");
218 * Set a bool value for a property.
220 * Assign a bool value to a property. If the property does not
221 * yet exist, it will be created and its type will be set to
222 * BOOL; if it has a type of UNKNOWN, the type will also be set to
223 * BOOL; otherwise, the bool value will be converted to the property's
226 * @param name The property name.
227 * @param val The new value for the property.
228 * @return true if the assignment succeeded, false otherwise.
230 bool SetBool (const string &name, bool val);
234 * Set an int value for a property.
236 * Assign an int value to a property. If the property does not
237 * yet exist, it will be created and its type will be set to
238 * INT; if it has a type of UNKNOWN, the type will also be set to
239 * INT; otherwise, the bool value will be converted to the property's
242 * @param name The property name.
243 * @param val The new value for the property.
244 * @return true if the assignment succeeded, false otherwise.
246 bool SetInt (const string &name, int val);
250 * Set a long value for a property.
252 * Assign a long value to a property. If the property does not
253 * yet exist, it will be created and its type will be set to
254 * LONG; if it has a type of UNKNOWN, the type will also be set to
255 * LONG; otherwise, the bool value will be converted to the property's
258 * @param name The property name.
259 * @param val The new value for the property.
260 * @return true if the assignment succeeded, false otherwise.
262 bool SetLong (const string &name, long val);
266 * Set a float value for a property.
268 * Assign a float value to a property. If the property does not
269 * yet exist, it will be created and its type will be set to
270 * FLOAT; if it has a type of UNKNOWN, the type will also be set to
271 * FLOAT; otherwise, the bool value will be converted to the property's
274 * @param name The property name.
275 * @param val The new value for the property.
276 * @return true if the assignment succeeded, false otherwise.
278 bool SetFloat (const string &name, float val);
282 * Set a double value for a property.
284 * Assign a double value to a property. If the property does not
285 * yet exist, it will be created and its type will be set to
286 * DOUBLE; if it has a type of UNKNOWN, the type will also be set to
287 * DOUBLE; otherwise, the double value will be converted to the property's
290 * @param name The property name.
291 * @param val The new value for the property.
292 * @return true if the assignment succeeded, false otherwise.
294 bool SetDouble (const string &name, double val);
298 * Set a string value for a property.
300 * Assign a string value to a property. If the property does not
301 * yet exist, it will be created and its type will be set to
302 * STRING; if it has a type of UNKNOWN, the type will also be set to
303 * STRING; otherwise, the string value will be converted to the property's
306 * @param name The property name.
307 * @param val The new value for the property.
308 * @return true if the assignment succeeded, false otherwise.
310 bool SetString (const string &name, const string &val);
313 ////////////////////////////////////////////////////////////////////////
314 // Convenience functions for setting property attributes.
315 ////////////////////////////////////////////////////////////////////////
319 * Set the state of the archive attribute for a property.
321 * If the archive attribute is true, the property will be written
322 * when a flight is saved; if it is false, the property will be
325 * A warning message will be printed if the property does not exist.
327 * @param name The property name.
328 * @param state The state of the archive attribute (defaults to true).
330 void SetArchivable (const string &name, bool state = true);
334 * Set the state of the read attribute for a property.
336 * If the read attribute is true, the property value will be readable;
337 * if it is false, the property value will always be the default value
340 * A warning message will be printed if the property does not exist.
342 * @param name The property name.
343 * @param state The state of the read attribute (defaults to true).
345 void SetReadable (const string &name, bool state = true);
349 * Set the state of the write attribute for a property.
351 * If the write attribute is true, the property value may be modified
352 * (depending on how it is tied); if the write attribute is false, the
353 * property value may not be modified.
355 * A warning message will be printed if the property does not exist.
357 * @param name The property name.
358 * @param state The state of the write attribute (defaults to true).
360 void SetWritable (const string &name, bool state = true);
363 ////////////////////////////////////////////////////////////////////////
364 // Convenience functions for tying properties, with logging.
365 ////////////////////////////////////////////////////////////////////////
369 * Untie a property from an external data source.
371 * Classes should use this function to release control of any
372 * properties they are managing.
374 void Untie (const string &name);
377 // Templates cause ambiguity here
380 * Tie a property to an external bool variable.
382 * The property's value will automatically mirror the variable's
383 * value, and vice-versa, until the property is untied.
385 * @param name The property name to tie (full path).
386 * @param pointer A pointer to the variable.
387 * @param useDefault true if any existing property value should be
388 * copied to the variable; false if the variable should not
389 * be modified; defaults to true.
392 Tie (const string &name, bool *pointer, bool useDefault = true);
396 * Tie a property to an external int variable.
398 * The property's value will automatically mirror the variable's
399 * value, and vice-versa, until the property is untied.
401 * @param name The property name to tie (full path).
402 * @param pointer A pointer to the variable.
403 * @param useDefault true if any existing property value should be
404 * copied to the variable; false if the variable should not
405 * be modified; defaults to true.
408 Tie (const string &name, int *pointer, bool useDefault = true);
412 * Tie a property to an external long variable.
414 * The property's value will automatically mirror the variable's
415 * value, and vice-versa, until the property is untied.
417 * @param name The property name to tie (full path).
418 * @param pointer A pointer to the variable.
419 * @param useDefault true if any existing property value should be
420 * copied to the variable; false if the variable should not
421 * be modified; defaults to true.
424 Tie (const string &name, long *pointer, bool useDefault = true);
428 * Tie a property to an external float variable.
430 * The property's value will automatically mirror the variable's
431 * value, and vice-versa, until the property is untied.
433 * @param name The property name to tie (full path).
434 * @param pointer A pointer to the variable.
435 * @param useDefault true if any existing property value should be
436 * copied to the variable; false if the variable should not
437 * be modified; defaults to true.
440 Tie (const string &name, float *pointer, bool useDefault = true);
443 * Tie a property to an external double variable.
445 * The property's value will automatically mirror the variable's
446 * value, and vice-versa, until the property is untied.
448 * @param name The property name to tie (full path).
449 * @param pointer A pointer to the variable.
450 * @param useDefault true if any existing property value should be
451 * copied to the variable; false if the variable should not
452 * be modified; defaults to true.
455 Tie (const string &name, double *pointer, bool useDefault = true);
457 //============================================================================
459 // All of the following functions *must* be inlined, otherwise linker
460 // errors will result
462 //============================================================================
464 /* template <class V> void
465 Tie (const string &name, V (*getter)(), void (*setter)(V) = 0,
466 bool useDefault = true);
468 template <class V> void
469 Tie (const string &name, int index, V (*getter)(int),
470 void (*setter)(int, V) = 0, bool useDefault = true);
472 template <class T, class V> void
473 Tie (const string &name, T * obj, V (T::*getter)() const,
474 void (T::*setter)(V) = 0, bool useDefault = true);
476 template <class T, class V> void
477 Tie (const string &name, T * obj, int index,
478 V (T::*getter)(int) const, void (T::*setter)(int, V) = 0,
479 bool useDefault = true); */
482 * Tie a property to a pair of simple functions.
484 * Every time the property value is queried, the getter (if any) will
485 * be invoked; every time the property value is modified, the setter
486 * (if any) will be invoked. The getter can be 0 to make the property
487 * unreadable, and the setter can be 0 to make the property
490 * @param name The property name to tie (full path).
491 * @param getter The getter function, or 0 if the value is unreadable.
492 * @param setter The setter function, or 0 if the value is unmodifiable.
493 * @param useDefault true if the setter should be invoked with any existing
494 * property value should be; false if the old value should be
495 * discarded; defaults to true.
498 template <class V> inline void
499 Tie (const string &name, V (*getter)(), void (*setter)(V) = 0,
500 bool useDefault = true)
502 if (!tie(name.c_str(), SGRawValueFunctions<V>(getter, setter),
506 "Failed to tie property " << name << " to functions" << endl;
512 * Tie a property to a pair of indexed functions.
514 * Every time the property value is queried, the getter (if any) will
515 * be invoked with the index provided; every time the property value
516 * is modified, the setter (if any) will be invoked with the index
517 * provided. The getter can be 0 to make the property unreadable, and
518 * the setter can be 0 to make the property unmodifiable.
520 * @param name The property name to tie (full path).
521 * @param index The integer argument to pass to the getter and
523 * @param getter The getter function, or 0 if the value is unreadable.
524 * @param setter The setter function, or 0 if the value is unmodifiable.
525 * @param useDefault true if the setter should be invoked with any existing
526 * property value should be; false if the old value should be
527 * discarded; defaults to true.
529 template <class V> inline void Tie (const string &name,
530 int index, V (*getter)(int),
531 void (*setter)(int, V) = 0, bool useDefault = true)
533 if (!tie(name.c_str(),
534 SGRawValueFunctionsIndexed<V>(index, getter, setter), useDefault))
537 "Failed to tie property " << name << " to indexed functions" << endl;
543 * Tie a property to a pair of object methods.
545 * Every time the property value is queried, the getter (if any) will
546 * be invoked; every time the property value is modified, the setter
547 * (if any) will be invoked. The getter can be 0 to make the property
548 * unreadable, and the setter can be 0 to make the property
551 * @param name The property name to tie (full path).
552 * @param obj The object whose methods should be invoked.
553 * @param getter The object's getter method, or 0 if the value is
555 * @param setter The object's setter method, or 0 if the value is
557 * @param useDefault true if the setter should be invoked with any existing
558 * property value should be; false if the old value should be
559 * discarded; defaults to true.
561 template <class T, class V> inline void
562 Tie (const string &name, T * obj, V (T::*getter)() const,
563 void (T::*setter)(V) = 0, bool useDefault = true)
565 if (!tie(name.c_str(),
566 SGRawValueMethods<T,V>(*obj, getter, setter), useDefault))
569 "Failed to tie property " << name << " to object methods" << endl;
574 * Tie a property to a pair of indexed object methods.
576 * Every time the property value is queried, the getter (if any) will
577 * be invoked with the index provided; every time the property value
578 * is modified, the setter (if any) will be invoked with the index
579 * provided. The getter can be 0 to make the property unreadable, and
580 * the setter can be 0 to make the property unmodifiable.
582 * @param name The property name to tie (full path).
583 * @param obj The object whose methods should be invoked.
584 * @param index The integer argument to pass to the getter and
586 * @param getter The getter method, or 0 if the value is unreadable.
587 * @param setter The setter method, or 0 if the value is unmodifiable.
588 * @param useDefault true if the setter should be invoked with any existing
589 * property value should be; false if the old value should be
590 * discarded; defaults to true.
592 template <class T, class V> inline void
593 Tie (const string &name, T * obj, int index,
594 V (T::*getter)(int) const, void (T::*setter)(int, V) = 0,
595 bool useDefault = true)
597 if (!tie(name.c_str(),
598 SGRawValueMethodsIndexed<T,V>(*obj, index, getter, setter), useDefault))
601 "Failed to tie property " << name << " to indexed object methods" << endl;
606 #endif // FGPROPERTYMANAGER_H