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