Merge remote-tracking branch 'refs/remotes/origin/master'

2 files changed, 65 insertions, 38 deletions

diff --git a/src/Fl_File_Chooser2.cxx b/src/Fl_File_Chooser2.cxx
index 4b5292a8d..5ff8ac24e 100644
--- a/src/Fl_File_Chooser2.cxx
+++ b/src/Fl_File_Chooser2.cxx
@@ -3,20 +3,26 @@
 //
 // More Fl_File_Chooser routines.
 //
-// Copyright 1999-2018 by Michael Sweet.
+// Copyright 1999-2007 by Michael Sweet.
+// Copyright 2008-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
 //
 
-// fabien: ATTENTION: Only Out Of Source Gen. because cxx/H files are autogenerated by fluid.
+// The following documentation is placed here because the implementation and
+// header files FL/Fl_File_Chooser.H and src/Fl_File_Chooser.cxx are generated
+// by fluid from src/Fl_File_Chooser.fl.
+
+// *** BEGIN OUT OF SOURCE DOCUMENTATION ***
+
 /** \defgroup group_comdlg Common Dialogs classes and functions
     @{
 */
@@ -111,8 +117,7 @@
 
   The Fl_File_Chooser class also exports the Fl_File_Chooser::newButton
   and Fl_File_Chooser::previewButton widgets so that application developers
-  can control their appearance and use.  For more complex customization,
-  consider copying the FLTK file chooser code and changing it accordingly.
+  can control their appearance and use.
 */
 /** @} */
 
@@ -250,28 +255,45 @@
 /** \fn int Fl_File_Chooser::visible()
   Returns 1 if the Fl_File_Chooser window is visible.*/
 
-/** \fn Fl_Widget* Fl_File_Chooser::add_extra(Fl_Widget*)
-  Adds extra widget at the bottom of Fl_File_Chooser window.
-  Returns pointer for previous extra widget or NULL if not set previously.
-  If argument is NULL only remove previous extra widget.
+/** \fn Fl_Widget *Fl_File_Chooser::add_extra(Fl_Widget *extra)
+  Adds an extra widget at the bottom of the Fl_File_Chooser window.
+
+  You can use any Fl_Widget or Fl_Group. If you use an Fl_Group, set its (x, y)
+  coordinates to (0, 0) and position its children relative to (0, 0) inside
+  the Fl_Group container widget. Make sure that all child widgets of the
+  Fl_Group are entirely included inside the bounding box of their parents,
+  i.e. the Fl_Group widget, and the Fl_File_Chooser window, respectively.
+
+  \note The width of the Fl_File_Chooser window is an undocumented
+    implementation detail and may change in the future.
 
-  \note Fl_File_Chooser does \b not delete extra widget in destructor!
-     To prevent memory leakage, don't forget to delete unused extra widgets
+  If \p extra is NULL any previous extra widget is removed.
+
+  \param[in] extra Custom widget or group to be added to the Fl_File_Chooser window.
+
+  \returns Pointer to previous extra widget or NULL if not set previously.
+
+  \note Fl_File_Chooser does \b not delete the extra widget in its destructor!
+    The extra widget is removed from the Fl_File_Chooser window before the
+    Fl_File_Chooser widget gets destroyed. To prevent memory leakage, don't
+    forget to delete unused extra widgets.
 */
   /** \fn int Fl_File_Chooser::shown()
-    Returns non-zero if the file chooser main window show() has been called (but not hide()
-    see Fl_Window::shown()
+    Returns non-zero if the file chooser main window show() has been called,
+    but not hide().
+    \see Fl_Window::shown()
   */
 
   /** \fn void Fl_File_Chooser::callback(void (*cb)(Fl_File_Chooser *, void *), void *d = 0)
-    Sets the file chooser callback cb and associated data d */
+    Sets the file chooser callback cb and associated data \p d */
 
   /** \fn void Fl_File_Chooser::user_data(void *d)
-    Sets the file chooser user data d */
+    Sets the file chooser user data \p d */
 
   /** \fn void * Fl_File_Chooser::user_data() const
-    Gets the file chooser user data */
-// *** END OF OUT OF SOURCE DOC ***
+    Gets the file chooser user data. */
+
+// *** END OF OUT OF SOURCE DOCUMENTATION ***
 
 // Contents:
 //
@@ -290,12 +312,7 @@
 //   quote_pathname()                     - Quote a pathname for a menu.
 //   unquote_pathname()                   - Unquote a pathname from a menu.
 //
-//   Fl_File_Chooser::add_extra()         - add extra widget at the bottom, return pointer 
-//                                          to previous extra widget or NULL if none,
-//                                          If argument is NULL extra widget removed.
-//                                          NOTE! file chooser does't delete extra widget in 
-//                                          destructor! To prevent memory leakage don't forget
-//					    delete unused extra widgets by yourself.
+//   Fl_File_Chooser::add_extra()         - add custom extra widget or group
 //
 
 //
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()) {