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