]> git.mxchange.org Git - flightgear.git/blob - src/Main/fg_props.hxx
Fix a misuse of a return value that lead to an error message being displayed
[flightgear.git] / src / Main / fg_props.hxx
1 // fg_props.hxx - Declarations and inline methods for property handling.
2 // Written by David Megginson, started 2000.
3 //
4 // This file is in the Public Domain, and comes with no warranty.
5
6 #ifndef __FG_PROPS_HXX
7 #define __FG_PROPS_HXX 1
8
9 #include <simgear/debug/logstream.hxx>
10 #include <simgear/props/props.hxx>
11 #include <simgear/props/props_io.hxx>
12 #include <simgear/structure/subsystem_mgr.hxx>
13
14 #include "globals.hxx"
15
16 \f
17 ////////////////////////////////////////////////////////////////////////
18 // Property management.
19 ////////////////////////////////////////////////////////////////////////
20
21 class FGProperties : public SGSubsystem
22 {
23 public:
24     FGProperties ();
25     virtual ~FGProperties ();
26
27     void init ();
28     void bind ();
29     void unbind ();
30     void update (double dt);
31 };
32
33
34 /**
35  * Save a flight to disk.
36  *
37  * This function saves all of the archivable properties to a stream
38  * so that the current flight can be restored later.
39  *
40  * @param output The output stream to write the XML save file to.
41  * @param write_all If true, write all properties rather than
42  *        just the ones flagged as archivable.
43  * @return true if the flight was saved successfully.
44  */
45 extern bool fgSaveFlight (ostream &output, bool write_all = false);
46
47
48 /**
49  * Load a flight from disk.
50  *
51  * This function loads an XML save file from a stream to restore
52  * a flight.
53  *
54  * @param input The input stream to read the XML from.
55  * @return true if the flight was restored successfully.
56  */
57 extern bool fgLoadFlight (istream &input);
58
59
60 /**
61  * Load properties from a file.
62  *
63  * @param file The relative or absolute filename.
64  * @param props The property node to load the properties into.
65  * @param in_fg_root If true, look for the file relative to
66  *        $FG_ROOT; otherwise, look for the file relative to the
67  *        current working directory.
68  * @return true if the properties loaded successfully, false
69  *         otherwise.
70  */
71 extern bool fgLoadProps (const char * path, SGPropertyNode * props,
72                          bool in_fg_root = true);
73
74
75 \f
76 ////////////////////////////////////////////////////////////////////////
77 // Convenience functions for getting property values.
78 ////////////////////////////////////////////////////////////////////////
79
80 /**
81  * Get a property node.
82  *
83  * @param path The path of the node, relative to root.
84  * @param create true to create the node if it doesn't exist.
85  * @return The node, or 0 if none exists and none was created.
86  */
87 extern SGPropertyNode * fgGetNode (const char * path, bool create = false);
88
89
90 /**
91  * Get a property node with separate index.
92  *
93  * This method separates the index from the path string, to make it
94  * easier to iterate through multiple components without using sprintf
95  * to add indices.  For example, fgGetNode("foo[1]/bar", 3) will
96  * return the same result as fgGetNode("foo[1]/bar[3]").
97  *
98  * @param path The path of the node, relative to root.
99  * @param index The index for the last member of the path (overrides
100  * any given in the string).
101  * @param create true to create the node if it doesn't exist.
102  * @return The node, or 0 if none exists and none was created.
103  */
104 extern SGPropertyNode * fgGetNode (const char * path,
105                                    int index, bool create = false);
106
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 extern bool fgHasNode (const char * path);
115
116
117 /**
118  * Add a listener to a node.
119  *
120  * @param listener The listener to add to the node.
121  * @param path The path of the node, relative to root.
122  * @param index The index for the last member of the path (overrides
123  * any given in the string).
124  */
125 extern void fgAddChangeListener (SGPropertyChangeListener * listener,
126                                  const char * path);
127
128
129 /**
130  * Add a listener to a node.
131  *
132  * @param listener The listener to add to the node.
133  * @param path The path of the node, relative to root.
134  * @param index The index for the last member of the path (overrides
135  * any given in the string).
136  */
137 extern void fgAddChangeListener (SGPropertyChangeListener * listener,
138                                  const char * path, int index);
139
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 fgGetNode 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 extern bool fgGetBool (const char * 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 fgGetNode 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 extern int fgGetInt (const char * 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 fgGetNode 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 extern int fgGetLong (const char * 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 fgGetNode 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 extern float fgGetFloat (const char * 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 fgGetNode 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 extern double fgGetDouble (const char * 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 fgGetNode 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 extern const char * fgGetString (const char * name,
241                                  const char * defaultValue = "");
242
243
244 /**
245  * Set a bool value for a property.
246  *
247  * Assign a bool value to a property.  If the property does not
248  * yet exist, it will be created and its type will be set to
249  * BOOL; if it has a type of UNKNOWN, the type will also be set to
250  * BOOL; otherwise, the bool value will be converted to the property's
251  * type.
252  *
253  * @param name The property name.
254  * @param val The new value for the property.
255  * @return true if the assignment succeeded, false otherwise.
256  */
257 extern bool fgSetBool (const char * name, bool val);
258
259
260 /**
261  * Set an int value for a property.
262  *
263  * Assign an int value to a property.  If the property does not
264  * yet exist, it will be created and its type will be set to
265  * INT; if it has a type of UNKNOWN, the type will also be set to
266  * INT; otherwise, the bool value will be converted to the property's
267  * type.
268  *
269  * @param name The property name.
270  * @param val The new value for the property.
271  * @return true if the assignment succeeded, false otherwise.
272  */
273 extern bool fgSetInt (const char * name, int val);
274
275
276 /**
277  * Set a long value for a property.
278  *
279  * Assign a long value to a property.  If the property does not
280  * yet exist, it will be created and its type will be set to
281  * LONG; if it has a type of UNKNOWN, the type will also be set to
282  * LONG; otherwise, the bool value will be converted to the property's
283  * type.
284  *
285  * @param name The property name.
286  * @param val The new value for the property.
287  * @return true if the assignment succeeded, false otherwise.
288  */
289 extern bool fgSetLong (const char * name, long val);
290
291
292 /**
293  * Set a float value for a property.
294  *
295  * Assign a float value to a property.  If the property does not
296  * yet exist, it will be created and its type will be set to
297  * FLOAT; if it has a type of UNKNOWN, the type will also be set to
298  * FLOAT; otherwise, the bool value will be converted to the property's
299  * type.
300  *
301  * @param name The property name.
302  * @param val The new value for the property.
303  * @return true if the assignment succeeded, false otherwise.
304  */
305 extern bool fgSetFloat (const char * name, float val);
306
307
308 /**
309  * Set a double value for a property.
310  *
311  * Assign a double value to a property.  If the property does not
312  * yet exist, it will be created and its type will be set to
313  * DOUBLE; if it has a type of UNKNOWN, the type will also be set to
314  * DOUBLE; otherwise, the double value will be converted to the property's
315  * type.
316  *
317  * @param name The property name.
318  * @param val The new value for the property.
319  * @return true if the assignment succeeded, false otherwise.
320  */
321 extern bool fgSetDouble (const char * name, double val);
322
323
324 /**
325  * Set a string value for a property.
326  *
327  * Assign a string value to a property.  If the property does not
328  * yet exist, it will be created and its type will be set to
329  * STRING; if it has a type of UNKNOWN, the type will also be set to
330  * STRING; otherwise, the string value will be converted to the property's
331  * type.
332  *
333  * @param name The property name.
334  * @param val The new value for the property.
335  * @return true if the assignment succeeded, false otherwise.
336  */
337 extern bool fgSetString (const char * name, const char * val);
338
339
340 \f
341 ////////////////////////////////////////////////////////////////////////
342 // Convenience functions for setting property attributes.
343 ////////////////////////////////////////////////////////////////////////
344
345
346 /**
347  * Set the state of the archive attribute for a property.
348  *
349  * If the archive attribute is true, the property will be written
350  * when a flight is saved; if it is false, the property will be
351  * skipped.
352  *
353  * A warning message will be printed if the property does not exist.
354  *
355  * @param name The property name.
356  * @param state The state of the archive attribute (defaults to true).
357  */
358 extern void fgSetArchivable (const char * name, bool state = true);
359
360
361 /**
362  * Set the state of the read attribute for a property.
363  *
364  * If the read attribute is true, the property value will be readable;
365  * if it is false, the property value will always be the default value
366  * for its type.
367  *
368  * A warning message will be printed if the property does not exist.
369  *
370  * @param name The property name.
371  * @param state The state of the read attribute (defaults to true).
372  */
373 extern void fgSetReadable (const char * name, bool state = true);
374
375
376 /**
377  * Set the state of the write attribute for a property.
378  *
379  * If the write attribute is true, the property value may be modified
380  * (depending on how it is tied); if the write attribute is false, the
381  * property value may not be modified.
382  *
383  * A warning message will be printed if the property does not exist.
384  *
385  * @param name The property name.
386  * @param state The state of the write attribute (defaults to true).
387  */
388 extern void fgSetWritable (const char * name, bool state = true);
389
390
391 \f
392 ////////////////////////////////////////////////////////////////////////
393 // Convenience functions for tying properties, with logging.
394 ////////////////////////////////////////////////////////////////////////
395
396
397 /**
398  * Untie a property from an external data source.
399  *
400  * Classes should use this function to release control of any
401  * properties they are managing.
402  */
403 extern void fgUntie (const char * name);
404
405
406 /**
407  * Tie a property to a pair of simple functions.
408  *
409  * Every time the property value is queried, the getter (if any) will
410  * be invoked; every time the property value is modified, the setter
411  * (if any) will be invoked.  The getter can be 0 to make the property
412  * unreadable, and the setter can be 0 to make the property
413  * unmodifiable.
414  *
415  * @param name The property name to tie (full path).
416  * @param getter The getter function, or 0 if the value is unreadable.
417  * @param setter The setter function, or 0 if the value is unmodifiable.
418  * @param useDefault true if the setter should be invoked with any existing 
419  *        property value should be; false if the old value should be
420  *        discarded; defaults to true.
421  */
422 template <class V>
423 inline void
424 fgTie (const char * name, V (*getter)(), void (*setter)(V) = 0,
425        bool useDefault = true)
426 {
427   if (!globals->get_props()->tie(name, SGRawValueFunctions<V>(getter, setter),
428                                  useDefault))
429     SG_LOG(SG_GENERAL, SG_WARN,
430            "Failed to tie property " << name << " to functions");
431 }
432
433
434 /**
435  * Tie a property to a pair of indexed functions.
436  *
437  * Every time the property value is queried, the getter (if any) will
438  * be invoked with the index provided; every time the property value
439  * is modified, the setter (if any) will be invoked with the index
440  * provided.  The getter can be 0 to make the property unreadable, and
441  * the setter can be 0 to make the property unmodifiable.
442  *
443  * @param name The property name to tie (full path).
444  * @param index The integer argument to pass to the getter and
445  *        setter functions.
446  * @param getter The getter function, or 0 if the value is unreadable.
447  * @param setter The setter function, or 0 if the value is unmodifiable.
448  * @param useDefault true if the setter should be invoked with any existing 
449  *        property value should be; false if the old value should be
450  *        discarded; defaults to true.
451  */
452 template <class V>
453 inline void
454 fgTie (const char * name, int index, V (*getter)(int),
455        void (*setter)(int, V) = 0, bool useDefault = true)
456 {
457   if (!globals->get_props()->tie(name,
458                                  SGRawValueFunctionsIndexed<V>(index,
459                                                                getter,
460                                                                setter),
461                                  useDefault))
462     SG_LOG(SG_GENERAL, SG_WARN,
463            "Failed to tie property " << name << " to indexed functions");
464 }
465
466
467 /**
468  * Tie a property to a pair of object methods.
469  *
470  * Every time the property value is queried, the getter (if any) will
471  * be invoked; every time the property value is modified, the setter
472  * (if any) will be invoked.  The getter can be 0 to make the property
473  * unreadable, and the setter can be 0 to make the property
474  * unmodifiable.
475  *
476  * @param name The property name to tie (full path).
477  * @param obj The object whose methods should be invoked.
478  * @param getter The object's getter method, or 0 if the value is
479  *        unreadable.
480  * @param setter The object's setter method, or 0 if the value is
481  *        unmodifiable.
482  * @param useDefault true if the setter should be invoked with any existing 
483  *        property value should be; false if the old value should be
484  *        discarded; defaults to true.
485  */
486 template <class T, class V>
487 inline void
488 fgTie (const char * name, T * obj, V (T::*getter)() const,
489        void (T::*setter)(V) = 0, bool useDefault = true)
490 {
491   if (!globals->get_props()->tie(name,
492                                  SGRawValueMethods<T,V>(*obj, getter, setter),
493                                  useDefault))
494     SG_LOG(SG_GENERAL, SG_WARN,
495            "Failed to tie property " << name << " to object methods");
496 }
497
498
499 /**
500  * Tie a property to a pair of indexed object methods.
501  *
502  * Every time the property value is queried, the getter (if any) will
503  * be invoked with the index provided; every time the property value
504  * is modified, the setter (if any) will be invoked with the index
505  * provided.  The getter can be 0 to make the property unreadable, and
506  * the setter can be 0 to make the property unmodifiable.
507  *
508  * @param name The property name to tie (full path).
509  * @param obj The object whose methods should be invoked.
510  * @param index The integer argument to pass to the getter and
511  *        setter methods.
512  * @param getter The getter method, or 0 if the value is unreadable.
513  * @param setter The setter method, or 0 if the value is unmodifiable.
514  * @param useDefault true if the setter should be invoked with any existing 
515  *        property value should be; false if the old value should be
516  *        discarded; defaults to true.
517  */
518 template <class T, class V>
519 inline void 
520 fgTie (const char * name, T * obj, int index,
521        V (T::*getter)(int) const, void (T::*setter)(int, V) = 0,
522        bool useDefault = true)
523 {
524   if (!globals->get_props()->tie(name,
525                                  SGRawValueMethodsIndexed<T,V>(*obj,
526                                                                index,
527                                                                getter,
528                                                                setter),
529                                  useDefault))
530     SG_LOG(SG_GENERAL, SG_WARN,
531            "Failed to tie property " << name << " to indexed object methods");
532 }
533
534
535 #endif // __FG_PROPS_HXX
536