Clarify documentation of Fl_Pack

3 files changed, 67 insertions, 33 deletions

diff --git a/FL/Fl_Pack.H b/FL/Fl_Pack.H
index 6a7e2be0d..26c5a33a7 100644
--- a/FL/Fl_Pack.H
+++ b/FL/Fl_Pack.H
@@ -3,17 +3,17 @@
 //
 // Pack header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2020 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
 // file is missing or damaged, see the license at:
 //
-//     http://www.fltk.org/COPYING.php
+//     https://www.fltk.org/COPYING.php
 //
 // Please report all bugs and problems on the following page:
 //
-//     http://www.fltk.org/str.php
+//     https://www.fltk.org/str.php
 //
 
 /* \file
@@ -27,18 +27,31 @@
 /**
   This widget was designed to add the functionality of compressing and
   aligning widgets.
-  <P>If type() is Fl_Pack::HORIZONTAL all the children are
+
+  If type() is Fl_Pack::HORIZONTAL all the children are
   resized to the height of the Fl_Pack, and are moved next to
   each other horizontally. If type() is not Fl_Pack::HORIZONTAL
   then the children are resized to the width and are stacked below each
-  other.  Then the Fl_Pack resizes itself to surround the child
-  widgets.
-  <P>This widget is needed for the Fl_Tabs.
-  In addition you may want to put the Fl_Pack inside an 
-  Fl_Scroll.
-
-  <P>The resizable for Fl_Pack is set to NULL by default.</p>
-  <P>See also: Fl_Group::resizable()
+  other.  Then the Fl_Pack resizes itself to surround the child widgets.
+
+  You may want to put the Fl_Pack inside an Fl_Scroll.
+
+  The \p 'resizable()' for Fl_Pack is set to NULL by default. Its behavior
+  is slightly different than in a normal Fl_Group widget: only if the
+  resizable() widget is the last widget in the group it is extended to take
+  the full available width or height, respectively, of the Fl_Pack group.
+
+  \note You can nest Fl_Pack widgets or put them inside Fl_Scroll widgets
+    or inside other group widgets but their behavior can sometimes be
+    <i>"surprising"</i>. This is partly due to the fact that Fl_Pack widgets
+    resize themselves during their draw() operation, trying to react on
+    their child widgets resizing themselves during \b their draw() operations
+    which can be confusing. If you want to achieve special resize behavior
+    of nested group widgets it can sometimes be easier to derive your own
+    specialized group widget than to try to make nested Fl_Pack widgets
+    behave as expected.
+
+  \see Fl_Group::resizable()
 */
 class FL_EXPORT Fl_Pack : public Fl_Group {
   int spacing_;
@@ -53,7 +66,7 @@ protected:
   void draw();
 
 public:
-  Fl_Pack(int x,int y,int w ,int h,const char *l = 0);
+  Fl_Pack(int X, int Y, int W, int H, const char *L = 0);
   /**
     Gets the number of extra pixels of blank space that are added
     between the children.
@@ -64,7 +77,18 @@ public:
     between the children.
   */
   void spacing(int i) {spacing_ = i;}
-  /** Same as Fl_Group::type() */
+  /** Returns non-zero if Fl_Pack alignment is horizontal.
+
+    \returns non-zero if Fl_Pack alignment is horizontal (Fl_Pack::HORIZONTAL)
+
+    \note Currently the return value is the same as Fl_Group::type(), but
+      this may change in the future. Do not set any other values than the
+      following with Fl_Pack::type():
+      - Fl_Pack::VERTICAL (Default)
+      - Fl_Pack::HORIZONTAL
+
+    See class Fl_Pack documentation for details.
+  */
   uchar horizontal() const {return type();}
 };
 
diff --git a/FL/Fl_Widget.H b/FL/Fl_Widget.H
index cefe4e632..200a086bb 100644
--- a/FL/Fl_Widget.H
+++ b/FL/Fl_Widget.H
@@ -3,17 +3,17 @@
 //
 // Widget header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2016 by Bill Spitzak and others.
+// Copyright 1998-2020 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
 // file is missing or damaged, see the license at:
 //
-//     http://www.fltk.org/COPYING.php
+//     https://www.fltk.org/COPYING.php
 //
 // Please report all bugs and problems on the following page:
 //
-//     http://www.fltk.org/str.php
+//     https://www.fltk.org/str.php
 //
 
 /** \file
@@ -201,8 +201,8 @@ public:
       (because draw() is virtual) like this:
 
       \code
-        Fl_Widget *s = &scroll;		// scroll is an embedded Fl_Scrollbar
-	s->draw();			// calls Fl_Scrollbar::draw()
+        Fl_Widget *s = &scrollbar; // scrollbar is an embedded Fl_Scrollbar
+        s->draw();                 // calls Fl_Scrollbar::draw()
       \endcode
    */
   virtual void draw() = 0;
diff --git a/src/Fl_Pack.cxx b/src/Fl_Pack.cxx
index 55ad2c385..2907effee 100644
--- a/src/Fl_Pack.cxx
+++ b/src/Fl_Pack.cxx
@@ -3,17 +3,17 @@
 //
 // Packing widget for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2020 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
 // file is missing or damaged, see the license at:
 //
-//     http://www.fltk.org/COPYING.php
+//     https://www.fltk.org/COPYING.php
 //
 // Please report all bugs and problems on the following page:
 //
-//     http://www.fltk.org/str.php
+//     https://www.fltk.org/str.php
 //
 
 // Based on code by Curtis Edwards
@@ -27,16 +27,26 @@
 
 /**
   Creates a new Fl_Pack widget using the given position, size,
-  and label string. The default boxtype is FL_NO_BOX.
-  <P>The destructor <I>also deletes all the children</I>. This allows a
+  and label string.
+
+  The default boxtype is FL_NO_BOX.
+
+  The default type() is Fl_Pack::VERTICAL.
+
+  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 
-  Fl_Pack and all of it's children can be automatic (local)
-  variables, but you must declare the Fl_Pack<I>first</I>, so
+  all the children in the user code. A kludge has been done so the
+  Fl_Pack and all of its children can be automatic (local)
+  variables, but you must declare the Fl_Pack <I>first</I>, so
   that it is destroyed last.
+
+  \param[in] X,Y	X and Y coordinates (position)
+  \param[in] W,H	width and height, respectively
+  \param[in] L		label (optional)
+
 */
-Fl_Pack::Fl_Pack(int X, int Y, int W, int H,const char *l)
-: Fl_Group(X, Y, W, H, l) {
+Fl_Pack::Fl_Pack(int X, int Y, int W, int H, const char *L)
+: Fl_Group(X, Y, W, H, L) {
   resizable(0);
   spacing_ = 0;
   // type(VERTICAL); // already set like this
@@ -55,7 +65,7 @@ void Fl_Pack::draw() {
   if (horizontal()) {
     rw = -spacing_;
     rh = th;
-    
+
     for (int i = children(); i--;)
       if (child(i)->visible()) {
         if (child(i) != this->resizable()) rw += child(i)->w();
@@ -64,7 +74,7 @@ void Fl_Pack::draw() {
   } else {
     rw = tw;
     rh = -spacing_;
-    
+
     for (int i = children(); i--;)
       if (child(i)->visible()) {
         if (child(i) != this->resizable()) rh += child(i)->h();
@@ -116,7 +126,7 @@ void Fl_Pack::draw() {
       current_position += spacing_;
     }
   }
-  
+
   if (horizontal()) {
     if (maximum_position < tx+tw && box()) {
       fl_color(color());
@@ -130,7 +140,7 @@ void Fl_Pack::draw() {
     }
     th = maximum_position-ty;
   }
-  
+
   tw += Fl::box_dw(box()); if (tw <= 0) tw = 1;
   th += Fl::box_dh(box()); if (th <= 0) th = 1;
   if (tw != w() || th != h()) {