]> git.mxchange.org Git - flightgear.git/blob - src/FDM/JSBSim/input_output/FGPropertyManager.h
Merge branch 'work4' into next
[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: FGPropertyManager.h,v 1.17 2010/07/08 11:36:28 jberndt Exp $"
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 the qualified name of a node relative to given base path,
134      * otherwise the fully qualified name.
135      * This function is very slow, so is probably useful for debugging only.
136      *
137      * @param path The path to strip off, if found.
138      */
139     std::string GetRelativeName( const std::string &path = "/fdm/jsbsim/" );
140
141     /**
142      * Get a bool value for a property.
143      *
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 getBoolValue() method, to avoid the lookup overhead.
149      *
150      * @param name The property name.
151      * @param defaultValue The default value to return if the property
152      *        does not exist.
153      * @return The property's value as a bool, or the default value provided.
154      */
155     bool GetBool (const std::string &name, bool defaultValue = false);
156
157
158     /**
159      * Get an int value for a property.
160      *
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 getIntValue() method, to avoid the lookup overhead.
166      *
167      * @param name The property name.
168      * @param defaultValue The default value to return if the property
169      *        does not exist.
170      * @return The property's value as an int, or the default value provided.
171      */
172     int GetInt (const std::string &name, int defaultValue = 0);
173
174
175     /**
176      * Get a long value for a property.
177      *
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 getLongValue() method, to avoid the lookup overhead.
183      *
184      * @param name The property name.
185      * @param defaultValue The default value to return if the property
186      *        does not exist.
187      * @return The property's value as a long, or the default value provided.
188      */
189     int GetLong (const std::string &name, long defaultValue = 0L);
190
191
192     /**
193      * Get a float value for a property.
194      *
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 getFloatValue() method, to avoid the lookup overhead.
200      *
201      * @param name The property name.
202      * @param defaultValue The default value to return if the property
203      *        does not exist.
204      * @return The property's value as a float, or the default value provided.
205      */
206     float GetFloat (const std::string &name, float defaultValue = 0.0);
207
208
209     /**
210      * Get a double value for a property.
211      *
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 getDoubleValue() method, to avoid the lookup overhead.
217      *
218      * @param name The property name.
219      * @param defaultValue The default value to return if the property
220      *        does not exist.
221      * @return The property's value as a double, or the default value provided.
222      */
223     double GetDouble (const std::string &name, double defaultValue = 0.0);
224
225
226     /**
227      * Get a string value for a property.
228      *
229      * This method is convenient but inefficient.  It should be used
230      * infrequently (i.e. for initializing, loading, saving, etc.),
231      * not in the main loop.  If you need to get a value frequently,
232      * it is better to look up the node itself using GetNode and then
233      * use the node's getStringValue() method, to avoid the lookup overhead.
234      *
235      * @param name The property name.
236      * @param defaultValue The default value to return if the property
237      *        does not exist.
238      * @return The property's value as a string, or the default value provided.
239      */
240     std::string GetString (const std::string &name, std::string defaultValue = "");
241
242
243     /**
244      * Set a bool value for a property.
245      *
246      * Assign a bool value to a property.  If the property does not
247      * yet exist, it will be created and its type will be set to
248      * BOOL; if it has a type of UNKNOWN, the type will also be set to
249      * BOOL; otherwise, the bool value will be converted to the property's
250      * type.
251      *
252      * @param name The property name.
253      * @param val The new value for the property.
254      * @return true if the assignment succeeded, false otherwise.
255      */
256     bool SetBool (const std::string &name, bool val);
257
258
259     /**
260      * Set an int value for a property.
261      *
262      * Assign an int value to a property.  If the property does not
263      * yet exist, it will be created and its type will be set to
264      * INT; if it has a type of UNKNOWN, the type will also be set to
265      * INT; otherwise, the bool value will be converted to the property's
266      * type.
267      *
268      * @param name The property name.
269      * @param val The new value for the property.
270      * @return true if the assignment succeeded, false otherwise.
271      */
272     bool SetInt (const std::string &name, int val);
273
274
275     /**
276      * Set a long value for a property.
277      *
278      * Assign a long value to a property.  If the property does not
279      * yet exist, it will be created and its type will be set to
280      * LONG; if it has a type of UNKNOWN, the type will also be set to
281      * LONG; otherwise, the bool value will be converted to the property's
282      * type.
283      *
284      * @param name The property name.
285      * @param val The new value for the property.
286      * @return true if the assignment succeeded, false otherwise.
287      */
288     bool SetLong (const std::string &name, long val);
289
290
291     /**
292      * Set a float value for a property.
293      *
294      * Assign a float value to a property.  If the property does not
295      * yet exist, it will be created and its type will be set to
296      * FLOAT; if it has a type of UNKNOWN, the type will also be set to
297      * FLOAT; otherwise, the bool value will be converted to the property's
298      * type.
299      *
300      * @param name The property name.
301      * @param val The new value for the property.
302      * @return true if the assignment succeeded, false otherwise.
303      */
304     bool SetFloat (const std::string &name, float val);
305
306
307     /**
308      * Set a double value for a property.
309      *
310      * Assign a double value to a property.  If the property does not
311      * yet exist, it will be created and its type will be set to
312      * DOUBLE; if it has a type of UNKNOWN, the type will also be set to
313      * DOUBLE; otherwise, the double value will be converted to the property's
314      * type.
315      *
316      * @param name The property name.
317      * @param val The new value for the property.
318      * @return true if the assignment succeeded, false otherwise.
319      */
320     bool SetDouble (const std::string &name, double val);
321
322
323     /**
324      * Set a string value for a property.
325      *
326      * Assign a string value to a property.  If the property does not
327      * yet exist, it will be created and its type will be set to
328      * STRING; if it has a type of UNKNOWN, the type will also be set to
329      * STRING; otherwise, the string value will be converted to the property's
330      * type.
331      *
332      * @param name The property name.
333      * @param val The new value for the property.
334      * @return true if the assignment succeeded, false otherwise.
335      */
336     bool SetString (const std::string &name, const std::string &val);
337
338
339     ////////////////////////////////////////////////////////////////////////
340     // Convenience functions for setting property attributes.
341     ////////////////////////////////////////////////////////////////////////
342
343
344     /**
345      * Set the state of the archive attribute for a property.
346      *
347      * If the archive attribute is true, the property will be written
348      * when a flight is saved; if it is false, the property will be
349      * skipped.
350      *
351      * A warning message will be printed if the property does not exist.
352      *
353      * @param name The property name.
354      * @param state The state of the archive attribute (defaults to true).
355      */
356     void SetArchivable (const std::string &name, bool state = true);
357
358
359     /**
360      * Set the state of the read attribute for a property.
361      *
362      * If the read attribute is true, the property value will be readable;
363      * if it is false, the property value will always be the default value
364      * for its type.
365      *
366      * A warning message will be printed if the property does not exist.
367      *
368      * @param name The property name.
369      * @param state The state of the read attribute (defaults to true).
370      */
371     void SetReadable (const std::string &name, bool state = true);
372
373
374     /**
375      * Set the state of the write attribute for a property.
376      *
377      * If the write attribute is true, the property value may be modified
378      * (depending on how it is tied); if the write attribute is false, the
379      * property value may not be modified.
380      *
381      * A warning message will be printed if the property does not exist.
382      *
383      * @param name The property name.
384      * @param state The state of the write attribute (defaults to true).
385      */
386     void SetWritable (const std::string &name, bool state = true);
387
388
389     ////////////////////////////////////////////////////////////////////////
390     // Convenience functions for tying properties, with logging.
391     ////////////////////////////////////////////////////////////////////////
392
393
394     /**
395      * Untie a property from an external data source.
396      *
397      * Classes should use this function to release control of any
398      * properties they are managing.
399      */
400     void Untie (const std::string &name);
401
402
403         // Templates cause ambiguity here
404
405     /**
406      * Tie a property to an external bool variable.
407      *
408      * The property's value will automatically mirror the variable's
409      * value, and vice-versa, until the property is untied.
410      *
411      * @param name The property name to tie (full path).
412      * @param pointer A pointer to the variable.
413      * @param useDefault true if any existing property value should be
414      *        copied to the variable; false if the variable should not
415      *        be modified; defaults to true.
416      */
417     void
418     Tie (const std::string &name, bool *pointer, bool useDefault = true);
419
420
421     /**
422      * Tie a property to an external int variable.
423      *
424      * The property's value will automatically mirror the variable's
425      * value, and vice-versa, until the property is untied.
426      *
427      * @param name The property name to tie (full path).
428      * @param pointer A pointer to the variable.
429      * @param useDefault true if any existing property value should be
430      *        copied to the variable; false if the variable should not
431      *        be modified; defaults to true.
432      */
433     void
434     Tie (const std::string &name, int *pointer, bool useDefault = true);
435
436
437     /**
438      * Tie a property to an external long variable.
439      *
440      * The property's value will automatically mirror the variable's
441      * value, and vice-versa, until the property is untied.
442      *
443      * @param name The property name to tie (full path).
444      * @param pointer A pointer to the variable.
445      * @param useDefault true if any existing property value should be
446      *        copied to the variable; false if the variable should not
447      *        be modified; defaults to true.
448      */
449     void
450     Tie (const std::string &name, long *pointer, bool useDefault = true);
451
452
453     /**
454      * Tie a property to an external float variable.
455      *
456      * The property's value will automatically mirror the variable's
457      * value, and vice-versa, until the property is untied.
458      *
459      * @param name The property name to tie (full path).
460      * @param pointer A pointer to the variable.
461      * @param useDefault true if any existing property value should be
462      *        copied to the variable; false if the variable should not
463      *        be modified; defaults to true.
464      */
465     void
466     Tie (const std::string &name, float *pointer, bool useDefault = true);
467
468     /**
469      * Tie a property to an external double variable.
470      *
471      * The property's value will automatically mirror the variable's
472      * value, and vice-versa, until the property is untied.
473      *
474      * @param name The property name to tie (full path).
475      * @param pointer A pointer to the variable.
476      * @param useDefault true if any existing property value should be
477      *        copied to the variable; false if the variable should not
478      *        be modified; defaults to true.
479      */
480     void
481     Tie (const std::string &name, double *pointer, bool useDefault = true);
482
483 //============================================================================
484 //
485 //  All of the following functions *must* be inlined, otherwise linker
486 //  errors will result
487 //
488 //============================================================================
489
490     /* template <class V> void
491     Tie (const std::string &name, V (*getter)(), void (*setter)(V) = 0,
492            bool useDefault = true);
493
494     template <class V> void
495     Tie (const std::string &name, int index, V (*getter)(int),
496            void (*setter)(int, V) = 0, bool useDefault = true);
497
498     template <class T, class V> void
499     Tie (const std::string &name, T * obj, V (T::*getter)() const,
500            void (T::*setter)(V) = 0, bool useDefault = true);
501
502     template <class T, class V> void
503     Tie (const std::string &name, T * obj, int index,
504            V (T::*getter)(int) const, void (T::*setter)(int, V) = 0,
505            bool useDefault = true); */
506
507      /**
508      * Tie a property to a pair of simple functions.
509      *
510      * Every time the property value is queried, the getter (if any) will
511      * be invoked; every time the property value is modified, the setter
512      * (if any) will be invoked.  The getter can be 0 to make the property
513      * unreadable, and the setter can be 0 to make the property
514      * unmodifiable.
515      *
516      * @param name The property name to tie (full path).
517      * @param getter The getter function, or 0 if the value is unreadable.
518      * @param setter The setter function, or 0 if the value is unmodifiable.
519      * @param useDefault true if the setter should be invoked with any existing
520      *        property value should be; false if the old value should be
521      *        discarded; defaults to true.
522      */
523
524     template <class V> inline void
525     Tie (const std::string &name, V (*getter)(), void (*setter)(V) = 0, bool useDefault = true)
526     {
527       if (!tie(name.c_str(), SGRawValueFunctions<V>(getter, setter), useDefault))
528         std::cout << "Failed to tie property " << name << " to functions" << std::endl;
529       else if (debug_lvl & 0x20)
530         std::cout << name << std::endl;
531     }
532
533
534     /**
535      * Tie a property to a pair of indexed functions.
536      *
537      * Every time the property value is queried, the getter (if any) will
538      * be invoked with the index provided; every time the property value
539      * is modified, the setter (if any) will be invoked with the index
540      * provided.  The getter can be 0 to make the property unreadable, and
541      * the setter can be 0 to make the property unmodifiable.
542      *
543      * @param name The property name to tie (full path).
544      * @param index The integer argument to pass to the getter and
545      *        setter functions.
546      * @param getter The getter function, or 0 if the value is unreadable.
547      * @param setter The setter function, or 0 if the value is unmodifiable.
548      * @param useDefault true if the setter should be invoked with any existing
549      *        property value should there be one; false if the old value should be
550      *        discarded; defaults to true.
551      */
552     template <class V> inline void Tie (const std::string &name, int index, V (*getter)(int),
553                                 void (*setter)(int, V) = 0, bool useDefault = true)
554     {
555       if (!tie(name.c_str(), SGRawValueFunctionsIndexed<V>(index, getter, setter), useDefault))
556         std::cout << "Failed to tie property " << name << " to indexed functions" << std::endl;
557       else if (debug_lvl & 0x20)
558         std::cout << name << std::endl;
559     }
560
561
562     /**
563      * Tie a property to a pair of object methods.
564      *
565      * Every time the property value is queried, the getter (if any) will
566      * be invoked; every time the property value is modified, the setter
567      * (if any) will be invoked.  The getter can be 0 to make the property
568      * unreadable, and the setter can be 0 to make the property
569      * unmodifiable.
570      *
571      * @param name The property name to tie (full path).
572      * @param obj The object whose methods should be invoked.
573      * @param getter The object's getter method, or 0 if the value is
574      *        unreadable.
575      * @param setter The object's setter method, or 0 if the value is
576      *        unmodifiable.
577      * @param useDefault true if the setter should be invoked with any existing
578      *        property value should there be one; false if the old value should be
579      *        discarded; defaults to true.
580      */
581     template <class T, class V> inline void
582     Tie (const std::string &name, T * obj, V (T::*getter)() const,
583            void (T::*setter)(V) = 0, bool useDefault = true)
584     {
585       if (!tie(name.c_str(), SGRawValueMethods<T,V>(*obj, getter, setter), useDefault))
586         std::cout << "Failed to tie property " << name << " to object methods" << std::endl;
587       else if (debug_lvl & 0x20)
588         std::cout << name << std::endl;
589     }
590
591     /**
592      * Tie a property to a pair of indexed object methods.
593      *
594      * Every time the property value is queried, the getter (if any) will
595      * be invoked with the index provided; every time the property value
596      * is modified, the setter (if any) will be invoked with the index
597      * provided.  The getter can be 0 to make the property unreadable, and
598      * the setter can be 0 to make the property unmodifiable.
599      *
600      * @param name The property name to tie (full path).
601      * @param obj The object whose methods should be invoked.
602      * @param index The integer argument to pass to the getter and
603      *        setter methods.
604      * @param getter The getter method, or 0 if the value is unreadable.
605      * @param setter The setter method, or 0 if the value is unmodifiable.
606      * @param useDefault true if the setter should be invoked with any existing
607      *        property value should be; false if the old value should be
608      *        discarded; defaults to true.
609      */
610     template <class T, class V> inline void
611     Tie (const std::string &name, T * obj, int index, V (T::*getter)(int) const,
612                          void (T::*setter)(int, V) = 0, bool useDefault = true)
613     {
614       if (!tie(name.c_str(), SGRawValueMethodsIndexed<T,V>(*obj, index, getter, setter), useDefault))
615         std::cout << "Failed to tie property " << name << " to indexed object methods" << std::endl;
616       else if (debug_lvl & 0x20)
617         std::cout << name << std::endl;
618    }
619 };
620 }
621 #endif // FGPROPERTYMANAGER_H
622