Documentation updates, in parts concerning changes done for STR #1894.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6652 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

FL/Fl_Group.H

@@ -39,9 +39,8 @@
   The Fl_Group class is the FLTK container widget. It maintains
   an array of child widgets. These children can themselves be any widget
   including Fl_Group. The most important subclass of Fl_Group
-  is Fl_Window, however
+  is Fl_Window, however groups can also be used to control radio buttons 
-  groups can also be used to control radio buttons or to enforce resize
+  or to enforce resize behavior.
-  behavior.
 */
 class FL_EXPORT Fl_Group : public Fl_Widget {
 
@@ -105,8 +104,8 @@ public:
   void add(Fl_Widget* o) {add(*o);}
   void insert(Fl_Widget&, int i);
   /**
-    This does insert(w, find(beforethis)).  This will append the
+    This does insert(w, find(before)).  This will append the
-    widget if beforethis is not in the group.
+    widget if \a before is not in the group.
   */
   void insert(Fl_Widget& o, Fl_Widget* before) {insert(o,find(before));}
   void remove(Fl_Widget&);
@@ -127,19 +126,22 @@ public:
     children. Widgets that are horizontally or vertically inside the
     dimensions of the box are scaled to the new size. Widgets outside the
     box are moved.
-    <P>In these examples the gray area is the resizable:
+
-    <BR></P>
+    In these examples the gray area is the resizable:
-    <P align=center>\image html resizebox1.gif&nbsp;&nbsp;
+
-    \image html resizebox2.gif</P>
+    \image html resizebox1.gif
-    \image latex resizebox1.eps  "before resize"  width=4cm
+    \image html resizebox2.gif
-    \image latex resizebox2.eps "after resize"  width=4cm
+    \image latex resizebox1.eps "before resize"  width=4cm
-    <P>The resizable may be set to the group itself (this is the default
+    \image latex resizebox2.eps "after resize"   width=4cm
-    value for an Fl_Group, although NULL is the default
+
-    for Fl_Window and Fl_Pack), in which case all the 
+    The resizable may be set to the group itself, in which case all the
-    contents are resized.
+    contents are resized. This is the default value for Fl_Group,
+    although NULL is the default for Fl_Window and Fl_Pack.
+
     If the resizable is NULL then all widgets remain a fixed size
-    and distance from the top-left corner. </P>
+    and distance from the top-left corner.
-    <P>It is possible to achieve any type of resize behavior by using an
+
+    It is possible to achieve any type of resize behavior by using an
     invisible Fl_Box as the resizable and/or by using a hierarchy
     of child Fl_Group's.
   */
@@ -181,8 +183,10 @@ public:
     \sa Fl_Widget::take_focus();
   */
   void focus(Fl_Widget* W) {W->take_focus();}
+
   /** This is for forms compatibility only */
   Fl_Widget* & _ddfdesign_kludge() {return resizable_;}
+
   /** This is for forms compatibility only */
   void forms_end();
 };

FL/Fl_Widget.H

@@ -164,11 +164,12 @@ protected:
 public:
 
   /** Destroys the widget.
-      Destroying single widgets is not very common, and it is your responsibility 
+      Destroying single widgets is not very common. You almost always want to 
-      to either remove() them from any enclosing group or destroy that group 
+      destroy the parent group instead, which will destroy all of the child widgets 
-      \em immediately after destroying the children. You almost always want to 
-      destroy the parent group instead which will destroy all of the child widgets 
       and groups in that group.
+      
+      \since FLTK 1.3, the widget's destructor removes the widget from its parent
+      group, if it is member of a group.
    */
   virtual ~Fl_Widget();
 
@@ -185,7 +186,7 @@ public:
       You normally don't call this method directly, but instead let FLTK do 
       it when the user interacts with the widget.
      
-      When implemented in a new widget, this function must return 0 if the 
+      When implemented in a widget, this function must return 0 if the 
       widget does not use the event or 1 otherwise.
 
       Most of the time, you want to call the inherited handle() method in 
@@ -208,7 +209,7 @@ public:
 
   /** Internal use only - "for hacks only".
   
-      It is \em STRONGLY recommended not to use this method, because it
+      It is \em \b STRONGLY recommended not to use this method, because it
       short-circuits Fl_Group's normal widget adding and removing methods,
       if the widget is already a child widget of another Fl_Group.
 
@@ -371,7 +372,7 @@ public:
    */
   void color(unsigned bg, unsigned sel) {color_=bg; color2_=sel;}
 
-  /** Get the current label text.
+  /** Gets the current label text.
       \return a pointer to the current label text
       \see label(Fl_CString), copy_label(Fl_CString)
    */
@@ -600,7 +601,7 @@ public:
      \li FL_WHEN_ENTER_KEY: If the user types the Enter key, the entire 
          text is selected, and the callback is done if the text has changed. 
 	 Normally the Enter key will navigate to the next field (or insert 
-	 a newline for a Fl_Mulitline_Input) - this changes the behavior.
+	 a newline for a Fl_Multiline_Input) - this changes the behavior.
      \li FL_WHEN_ENTER_KEY|FL_WHEN_NOT_CHANGED: The Enter key will do the
          callback even if the text has not changed. Useful for command fields.
       Fl_Widget::when() is a set of bitflags used by subclasses of 
@@ -898,7 +899,7 @@ public:
 
 /**
     Reserved type numbers (necessary for my cheapo RTTI) start here.
-    grep the header files for "RESERVED_TYPE" to find the next available
+    Grep the header files for "RESERVED_TYPE" to find the next available
     number.
 */
 #define FL_RESERVED_TYPE 100

src/Fl_Group.cxx

@@ -405,10 +405,16 @@ void Fl_Group::clear() {
 /**
   The destructor <I>also deletes all the children</I>. This allows a
   whole tree to be deleted at once, without having to keep a pointer to
-  all the children in the user code. A kludge has been done so the 
+  all the children in the user code.
-  Fl_Group and all of it's children can be automatic (local)
+  
-  variables, but you must declare the Fl_Group <I>first</I>, so
+  It is allowed that the Fl_Group and all of its children are automatic
-  that it is destroyed last.
+  (local) variables, but you must declare the Fl_Group \e first, so that
+  it is destroyed last.
+  
+  If you add static or automatic (local) variables to an Fl_Group, then it
+  is your responsibility to remove (or delete) all such static or automatic
+  child widgets \e \b before destroying the group - otherwise the child
+  widgets' destructors would be called twice!
 */
 Fl_Group::~Fl_Group() {
   clear();
@@ -416,7 +422,7 @@ Fl_Group::~Fl_Group() {
 
 /**
   The widget is removed from its current group (if any) and then
-  inserted into this group. It is put at index n (or at the end
+  inserted into this group. It is put at index n - or at the end,
   if n >= children(). This can also be used to rearrange
   the widgets inside a group.
 */