]> git.mxchange.org Git - flightgear.git/blob - src/FDM/JSBSim/input_output/FGPropertyManager.h
Merge branch 'ehofman/jsbsim'
[flightgear.git] / src / FDM / JSBSim / input_output / FGPropertyManager.h
1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2
3  Header:       FGPropertyManager.h
4  Author:       Tony Peden
5                Based on work originally by David Megginson
6  Date:         2/2002
7
8  ------------- Copyright (C) 2002 -------------
9
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
13  version.
14
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
18  details.
19
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.
23
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.
26
27 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
28 SENTRY
29 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
30
31 #ifndef FGPROPERTYMANAGER_H
32 #define FGPROPERTYMANAGER_H
33
34 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
35 INCLUDES
36 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
37
38 // This is needed by MSVC9 when included in FlightGear because of
39 // the new Vec4d class in props.hxx
40 #if defined( HAVE_CONFIG_H )
41 # include <config.h>
42 #endif
43
44 #include <string>
45 #include "simgear/props/props.hxx"
46 #if !PROPS_STANDALONE
47 # include "simgear/math/SGMath.hxx"
48 #endif
49
50 #include "FGJSBBase.h"
51
52 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
53 DEFINITIONS
54 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
55
56 #define ID_PROPERTYMANAGER "$Id$"
57
58 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
59 FORWARD DECLARATIONS
60 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
61
62 namespace JSBSim {
63
64 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
65 CLASS DOCUMENTATION
66 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
67
68 /** Class wrapper for property handling.
69     @author David Megginson, Tony Peden
70   */
71
72 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
73 CLASS DECLARATION
74 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
75
76 class FGPropertyManager : public SGPropertyNode, public FGJSBBase
77 {
78   private:
79     static bool suppress_warning;
80   public:
81     /// Constructor
82     FGPropertyManager(void) {suppress_warning = false;}
83     /// Destructor
84     virtual ~FGPropertyManager(void) {}
85
86     /** Property-ify a name
87      *  replaces spaces with '-' and, optionally, makes name all lower case
88      *  @param name string to change
89      *  @param lowercase true to change all upper case chars to lower
90      *  NOTE: this function changes its argument and thus relies
91      *  on pass by value
92      */
93     std::string mkPropertyName(std::string name, bool lowercase);
94
95     /**
96      * Get a property node.
97      *
98      * @param path The path of the node, relative to root.
99      * @param create true to create the node if it doesn't exist.
100      * @return The node, or 0 if none exists and none was created.
101      */
102     FGPropertyManager*
103     GetNode (const std::string &path, bool create = false);
104
105     FGPropertyManager*
106     GetNode (const std::string &relpath, int index, bool create = false);
107
108     /**
109      * Test whether a given node exists.
110      *
111      * @param path The path of the node, relative to root.
112      * @return true if the node exists, false otherwise.
113      */
114     bool HasNode (const std::string &path);
115
116     /**
117      * Get the name of a node
118      */
119     std::string GetName( void );
120
121     /**
122      * Get the name of a node without underscores, etc.
123      */
124     std::string GetPrintableName( void );
125
126     /**
127      * Get the fully qualified name of a node
128      * This function is very slow, so is probably useful for debugging only.
129      */
130     std::string GetFullyQualifiedName(void);
131
132     /**
133      * Get a bool value for a property.
134      *
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 getBoolValue() method, to avoid the lookup overhead.
140      *
141      * @param name The property name.
142      * @param defaultValue The default value to return if the property
143      *        does not exist.
144      * @return The property's value as a bool, or the default value provided.
145      */
146     bool GetBool (const std::string &name, bool defaultValue = false);
147
148
149     /**
150      * Get an int value for a property.
151      *
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 getIntValue() method, to avoid the lookup overhead.
157      *
158      * @param name The property name.
159      * @param defaultValue The default value to return if the property
160      *        does not exist.
161      * @return The property's value as an int, or the default value provided.
162      */
163     int GetInt (const std::string &name, int defaultValue = 0);
164
165
166     /**
167      * Get a long value for a property.
168      *
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 getLongValue() method, to avoid the lookup overhead.
174      *
175      * @param name The property name.
176      * @param defaultValue The default value to return if the property
177      *        does not exist.
178      * @return The property's value as a long, or the default value provided.
179      */
180     int GetLong (const std::string &name, long defaultValue = 0L);
181
182
183     /**
184      * Get a float value for a property.
185      *
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 getFloatValue() method, to avoid the lookup overhead.
191      *
192      * @param name The property name.
193      * @param defaultValue The default value to return if the property
194      *        does not exist.
195      * @return The property's value as a float, or the default value provided.
196      */
197     float GetFloat (const std::string &name, float defaultValue = 0.0);
198
199
200     /**
201      * Get a double value for a property.
202      *
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 getDoubleValue() method, to avoid the lookup overhead.
208      *
209      * @param name The property name.
210      * @param defaultValue The default value to return if the property
211      *        does not exist.
212      * @return The property's value as a double, or the default value provided.
213      */
214     double GetDouble (const std::string &name, double defaultValue = 0.0);
215
216
217     /**
218      * Get a string value for a property.
219      *
220      * This method is convenient but inefficient.  It should be used
221      * infrequently (i.e. for initializing, loading, saving, etc.),
222      * not in the main loop.  If you need to get a value frequently,
223      * it is better to look up the node itself using GetNode and then
224      * use the node's getStringValue() method, to avoid the lookup overhead.
225      *
226      * @param name The property name.
227      * @param defaultValue The default value to return if the property
228      *        does not exist.
229      * @return The property's value as a string, or the default value provided.
230      */
231     std::string GetString (const std::string &name, std::string defaultValue = "");
232
233
234     /**
235      * Set a bool value for a property.
236      *
237      * Assign a bool value to a property.  If the property does not
238      * yet exist, it will be created and its type will be set to
239      * BOOL; if it has a type of UNKNOWN, the type will also be set to
240      * BOOL; otherwise, the bool value will be converted to the property's
241      * type.
242      *
243      * @param name The property name.
244      * @param val The new value for the property.
245      * @return true if the assignment succeeded, false otherwise.
246      */
247     bool SetBool (const std::string &name, bool val);
248
249
250     /**
251      * Set an int value for a property.
252      *
253      * Assign an int value to a property.  If the property does not
254      * yet exist, it will be created and its type will be set to
255      * INT; if it has a type of UNKNOWN, the type will also be set to
256      * INT; otherwise, the bool value will be converted to the property's
257      * type.
258      *
259      * @param name The property name.
260      * @param val The new value for the property.
261      * @return true if the assignment succeeded, false otherwise.
262      */
263     bool SetInt (const std::string &name, int val);
264
265
266     /**
267      * Set a long value for a property.
268      *
269      * Assign a long value to a property.  If the property does not
270      * yet exist, it will be created and its type will be set to
271      * LONG; if it has a type of UNKNOWN, the type will also be set to
272      * LONG; otherwise, the bool value will be converted to the property's
273      * type.
274      *
275      * @param name The property name.
276      * @param val The new value for the property.
277      * @return true if the assignment succeeded, false otherwise.
278      */
279     bool SetLong (const std::string &name, long val);
280
281
282     /**
283      * Set a float value for a property.
284      *
285      * Assign a float value to a property.  If the property does not
286      * yet exist, it will be created and its type will be set to
287      * FLOAT; if it has a type of UNKNOWN, the type will also be set to
288      * FLOAT; otherwise, the bool value will be converted to the property's
289      * type.
290      *
291      * @param name The property name.
292      * @param val The new value for the property.
293      * @return true if the assignment succeeded, false otherwise.
294      */
295     bool SetFloat (const std::string &name, float val);
296
297
298     /**
299      * Set a double value for a property.
300      *
301      * Assign a double value to a property.  If the property does not
302      * yet exist, it will be created and its type will be set to
303      * DOUBLE; if it has a type of UNKNOWN, the type will also be set to
304      * DOUBLE; otherwise, the double value will be converted to the property's
305      * type.
306      *
307      * @param name The property name.
308      * @param val The new value for the property.
309      * @return true if the assignment succeeded, false otherwise.
310      */
311     bool SetDouble (const std::string &name, double val);
312
313
314     /**
315      * Set a string value for a property.
316      *
317      * Assign a string value to a property.  If the property does not
318      * yet exist, it will be created and its type will be set to
319      * STRING; if it has a type of UNKNOWN, the type will also be set to
320      * STRING; otherwise, the string value will be converted to the property's
321      * type.
322      *
323      * @param name The property name.
324      * @param val The new value for the property.
325      * @return true if the assignment succeeded, false otherwise.
326      */
327     bool SetString (const std::string &name, const std::string &val);
328
329
330     ////////////////////////////////////////////////////////////////////////
331     // Convenience functions for setting property attributes.
332     ////////////////////////////////////////////////////////////////////////
333
334
335     /**
336      * Set the state of the archive attribute for a property.
337      *
338      * If the archive attribute is true, the property will be written
339      * when a flight is saved; if it is false, the property will be
340      * skipped.
341      *
342      * A warning message will be printed if the property does not exist.
343      *
344      * @param name The property name.
345      * @param state The state of the archive attribute (defaults to true).
346      */
347     void SetArchivable (const std::string &name, bool state = true);
348
349
350     /**
351      * Set the state of the read attribute for a property.
352      *
353      * If the read attribute is true, the property value will be readable;
354      * if it is false, the property value will always be the default value
355      * for its type.
356      *
357      * A warning message will be printed if the property does not exist.
358      *
359      * @param name The property name.
360      * @param state The state of the read attribute (defaults to true).
361      */
362     void SetReadable (const std::string &name, bool state = true);
363
364
365     /**
366      * Set the state of the write attribute for a property.
367      *
368      * If the write attribute is true, the property value may be modified
369      * (depending on how it is tied); if the write attribute is false, the
370      * property value may not be modified.
371      *
372      * A warning message will be printed if the property does not exist.
373      *
374      * @param name The property name.
375      * @param state The state of the write attribute (defaults to true).
376      */
377     void SetWritable (const std::string &name, bool state = true);
378
379
380     ////////////////////////////////////////////////////////////////////////
381     // Convenience functions for tying properties, with logging.
382     ////////////////////////////////////////////////////////////////////////
383
384
385     /**
386      * Untie a property from an external data source.
387      *
388      * Classes should use this function to release control of any
389      * properties they are managing.
390      */
391     void Untie (const std::string &name);
392
393
394         // Templates cause ambiguity here
395
396     /**
397      * Tie a property to an external bool variable.
398      *
399      * The property's value will automatically mirror the variable's
400      * value, and vice-versa, until the property is untied.
401      *
402      * @param name The property name to tie (full path).
403      * @param pointer A pointer to the variable.
404      * @param useDefault true if any existing property value should be
405      *        copied to the variable; false if the variable should not
406      *        be modified; defaults to true.
407      */
408     void
409     Tie (const std::string &name, bool *pointer, bool useDefault = true);
410
411
412     /**
413      * Tie a property to an external int variable.
414      *
415      * The property's value will automatically mirror the variable's
416      * value, and vice-versa, until the property is untied.
417      *
418      * @param name The property name to tie (full path).
419      * @param pointer A pointer to the variable.
420      * @param useDefault true if any existing property value should be
421      *        copied to the variable; false if the variable should not
422      *        be modified; defaults to true.
423      */
424     void
425     Tie (const std::string &name, int *pointer, bool useDefault = true);
426
427
428     /**
429      * Tie a property to an external long variable.
430      *
431      * The property's value will automatically mirror the variable's
432      * value, and vice-versa, until the property is untied.
433      *
434      * @param name The property name to tie (full path).
435      * @param pointer A pointer to the variable.
436      * @param useDefault true if any existing property value should be
437      *        copied to the variable; false if the variable should not
438      *        be modified; defaults to true.
439      */
440     void
441     Tie (const std::string &name, long *pointer, bool useDefault = true);
442
443
444     /**
445      * Tie a property to an external float variable.
446      *
447      * The property's value will automatically mirror the variable's
448      * value, and vice-versa, until the property is untied.
449      *
450      * @param name The property name to tie (full path).
451      * @param pointer A pointer to the variable.
452      * @param useDefault true if any existing property value should be
453      *        copied to the variable; false if the variable should not
454      *        be modified; defaults to true.
455      */
456     void
457     Tie (const std::string &name, float *pointer, bool useDefault = true);
458
459     /**
460      * Tie a property to an external double variable.
461      *
462      * The property's value will automatically mirror the variable's
463      * value, and vice-versa, until the property is untied.
464      *
465      * @param name The property name to tie (full path).
466      * @param pointer A pointer to the variable.
467      * @param useDefault true if any existing property value should be
468      *        copied to the variable; false if the variable should not
469      *        be modified; defaults to true.
470      */
471     void
472     Tie (const std::string &name, double *pointer, bool useDefault = true);
473
474 //============================================================================
475 //
476 //  All of the following functions *must* be inlined, otherwise linker
477 //  errors will result
478 //
479 //============================================================================
480
481     /* template <class V> void
482     Tie (const std::string &name, V (*getter)(), void (*setter)(V) = 0,
483            bool useDefault = true);
484
485     template <class V> void
486     Tie (const std::string &name, int index, V (*getter)(int),
487            void (*setter)(int, V) = 0, bool useDefault = true);
488
489     template <class T, class V> void
490     Tie (const std::string &name, T * obj, V (T::*getter)() const,
491            void (T::*setter)(V) = 0, bool useDefault = true);
492
493     template <class T, class V> void
494     Tie (const std::string &name, T * obj, int index,
495            V (T::*getter)(int) const, void (T::*setter)(int, V) = 0,
496            bool useDefault = true); */
497
498      /**
499      * Tie a property to a pair of simple functions.
500      *
501      * Every time the property value is queried, the getter (if any) will
502      * be invoked; every time the property value is modified, the setter
503      * (if any) will be invoked.  The getter can be 0 to make the property
504      * unreadable, and the setter can be 0 to make the property
505      * unmodifiable.
506      *
507      * @param name The property name to tie (full path).
508      * @param getter The getter function, or 0 if the value is unreadable.
509      * @param setter The setter function, or 0 if the value is unmodifiable.
510      * @param useDefault true if the setter should be invoked with any existing
511      *        property value should be; false if the old value should be
512      *        discarded; defaults to true.
513      */
514
515     template <class V> inline void
516     Tie (const std::string &name, V (*getter)(), void (*setter)(V) = 0, bool useDefault = true)
517     {
518       if (!tie(name.c_str(), SGRawValueFunctions<V>(getter, setter), useDefault))
519         std::cout << "Failed to tie property " << name << " to functions" << std::endl;
520       else if (debug_lvl & 0x20)
521         std::cout << name << std::endl;
522     }
523
524
525     /**
526      * Tie a property to a pair of indexed functions.
527      *
528      * Every time the property value is queried, the getter (if any) will
529      * be invoked with the index provided; every time the property value
530      * is modified, the setter (if any) will be invoked with the index
531      * provided.  The getter can be 0 to make the property unreadable, and
532      * the setter can be 0 to make the property unmodifiable.
533      *
534      * @param name The property name to tie (full path).
535      * @param index The integer argument to pass to the getter and
536      *        setter functions.
537      * @param getter The getter function, or 0 if the value is unreadable.
538      * @param setter The setter function, or 0 if the value is unmodifiable.
539      * @param useDefault true if the setter should be invoked with any existing
540      *        property value should there be one; false if the old value should be
541      *        discarded; defaults to true.
542      */
543     template <class V> inline void Tie (const std::string &name, int index, V (*getter)(int),
544                                 void (*setter)(int, V) = 0, bool useDefault = true)
545     {
546       if (!tie(name.c_str(), SGRawValueFunctionsIndexed<V>(index, getter, setter), useDefault))
547         std::cout << "Failed to tie property " << name << " to indexed functions" << std::endl;
548       else if (debug_lvl & 0x20)
549         std::cout << name << std::endl;
550     }
551
552
553     /**
554      * Tie a property to a pair of object methods.
555      *
556      * Every time the property value is queried, the getter (if any) will
557      * be invoked; every time the property value is modified, the setter
558      * (if any) will be invoked.  The getter can be 0 to make the property
559      * unreadable, and the setter can be 0 to make the property
560      * unmodifiable.
561      *
562      * @param name The property name to tie (full path).
563      * @param obj The object whose methods should be invoked.
564      * @param getter The object's getter method, or 0 if the value is
565      *        unreadable.
566      * @param setter The object's setter method, or 0 if the value is
567      *        unmodifiable.
568      * @param useDefault true if the setter should be invoked with any existing
569      *        property value should there be one; false if the old value should be
570      *        discarded; defaults to true.
571      */
572     template <class T, class V> inline void
573     Tie (const std::string &name, T * obj, V (T::*getter)() const,
574            void (T::*setter)(V) = 0, bool useDefault = true)
575     {
576       if (!tie(name.c_str(), SGRawValueMethods<T,V>(*obj, getter, setter), useDefault))
577         std::cout << "Failed to tie property " << name << " to object methods" << std::endl;
578       else if (debug_lvl & 0x20)
579         std::cout << name << std::endl;
580     }
581
582     /**
583      * Tie a property to a pair of indexed object methods.
584      *
585      * Every time the property value is queried, the getter (if any) will
586      * be invoked with the index provided; every time the property value
587      * is modified, the setter (if any) will be invoked with the index
588      * provided.  The getter can be 0 to make the property unreadable, and
589      * the setter can be 0 to make the property unmodifiable.
590      *
591      * @param name The property name to tie (full path).
592      * @param obj The object whose methods should be invoked.
593      * @param index The integer argument to pass to the getter and
594      *        setter methods.
595      * @param getter The getter method, or 0 if the value is unreadable.
596      * @param setter The setter method, or 0 if the value is unmodifiable.
597      * @param useDefault true if the setter should be invoked with any existing
598      *        property value should be; false if the old value should be
599      *        discarded; defaults to true.
600      */
601     template <class T, class V> inline void
602     Tie (const std::string &name, T * obj, int index, V (T::*getter)(int) const,
603                          void (T::*setter)(int, V) = 0, bool useDefault = true)
604     {
605       if (!tie(name.c_str(), SGRawValueMethodsIndexed<T,V>(*obj, index, getter, setter), useDefault))
606         std::cout << "Failed to tie property " << name << " to indexed object methods" << std::endl;
607       else if (debug_lvl & 0x20)
608         std::cout << name << std::endl;
609    }
610 };
611 }
612 #endif // FGPROPERTYMANAGER_H
613