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