From 4dc28f11f4dfa53480a44d693b59fcfd35852f43 Mon Sep 17 00:00:00 2001
From: david <david>
Date: Mon, 20 Jan 2003 16:01:54 +0000
Subject: [PATCH] Add more documentation comments.

Fix memory leaks (PUI doesn't make copies of lists, so we have to make
our own copies and keep pointers to them).

Adjust for new method names in NewGUI.

Move the GUIInfo struct into the cxx file so that it's not part of the
public interface.
---
 src/GUI/dialog.hxx | 66 ++++++++++++++++++++++++++++++----------------
 1 file changed, 44 insertions(+), 22 deletions(-)

diff --git a/src/GUI/dialog.hxx b/src/GUI/dialog.hxx
index de2e900a9..4b4752d16 100644
--- a/src/GUI/dialog.hxx
+++ b/src/GUI/dialog.hxx
@@ -1,4 +1,4 @@
-// dialog.hxx - XML-configurable dialog box.
+// dialog.hxx - XML-configured dialog box.
 
 #ifndef __DIALOG_HXX
 #define __DIALOG_HXX 1
@@ -20,28 +20,25 @@ class FGBinding;
 
 
 /**
- * PUI userdata describing a GUI object.
- */
-struct GUIInfo
-{
-    GUIInfo (FGDialog * w);
-    virtual ~GUIInfo ();
-    
-    FGDialog * widget;
-    vector <FGBinding *> bindings;
-};
-
-
-/**
- * Top-level GUI widget.
+ * An XML-configured dialog box.
+ *
+ * The GUI manager stores only the property tree for the dialog
+ * boxes.  This class creates a PUI dialog box on demand from
+ * the properties in that tree.  The manager recreates the dialog
+ * every time it needs to show it.
  */
 class FGDialog
 {
 public:
 
-
     /**
      * Construct a new GUI widget configured by a property tree.
+     *
+     * The configuration properties are not part of the main
+     * FlightGear property tree; the GUI manager reads them
+     * from individual configuration files.
+     *
+     * @param props A property tree describing the dialog.
      */
     FGDialog (SGPropertyNode_ptr props);
 
@@ -55,7 +52,8 @@ public:
     /**
      * Update the values of all GUI objects with a specific name.
      *
-     * This method copies from the property to the GUI object.
+     * This method copies values from the FlightGear property tree to
+     * the GUI object(s).
      *
      * @param objectName The name of the GUI object(s) to update.
      *        Use the empty name for all unnamed objects.
@@ -66,7 +64,8 @@ public:
     /**
      * Apply the values of all GUI objects with a specific name.
      *
-     * This method copies from the GUI object to the property.
+     * This method copies values from the GUI object(s) to the
+     * FlightGear property tree.
      *
      * @param objectName The name of the GUI object(s) to update.
      *        Use the empty name for all unnamed objects.
@@ -77,7 +76,8 @@ public:
     /**
      * Update the values of all GUI objects.
      *
-     * This method copies from the properties to the GUI objects.
+     * This method copies values from the FlightGear property tree to
+     * the GUI objects.
      */
     virtual void updateValues ();
 
@@ -85,23 +85,39 @@ public:
     /**
      * Apply the values of all GUI objects.
      *
-     * This method copies from the GUI objects to the properties.
+     * This method copies from the GUI objects to the FlightGear
+     * property tree properties.
      */
     virtual void applyValues ();
 
 
 private:
-    FGDialog (const FGDialog &); // just for safety
 
+    // Private copy constructor to avoid unpleasant surprises.
+    FGDialog (const FGDialog &);
+
+    // Show the dialog.
     void display (SGPropertyNode_ptr props);
+
+    // Build the dialog or a subobject of it.
     puObject * makeObject (SGPropertyNode * props,
                            int parentWidth, int parentHeight);
+
+    // Common configuration for all GUI objects.
     void setupObject (puObject * object, SGPropertyNode * props);
+
+    // Common configuration for all GUI group objects.
     void setupGroup (puGroup * group, SGPropertyNode * props,
                      int width, int height, bool makeFrame = false);
 
+    // The top-level PUI object.
     puObject * _object;
-    vector<GUIInfo *> _info;
+
+    // PUI provides no way for userdata to be deleted automatically
+    // with a GUI object, so we have to keep track of all the special
+    // data we allocated and then free it manually when the dialog
+    // closes.
+    vector<void *> _info;
     struct PropertyObject {
         PropertyObject (const char * name,
                         puObject * object,
@@ -111,6 +127,12 @@ private:
         SGPropertyNode_ptr node;
     };
     vector<PropertyObject *> _propertyObjects;
+
+    // PUI doesn't copy arrays, so we have to allocate string arrays
+    // and then keep pointers so that we can delete them when the
+    // dialog closes.
+    char ** make_char_array (int size);
+    vector<char **> _char_arrays;
 };
 
 #endif // __DIALOG_HXX