Add documentation of Fl_Scroll::resize(...), fix some more Fl_Scroll docs.

As noticed in fltk.general, documentation of Fl_Scroll::resize() did not
exist, hence the documentation shown was that of the parent class Fl_Group,
which was definitely wrong.

Some more minor documentation fixes have also been applied. No code changes.


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

2 files changed, 81 insertions, 39 deletions

diff --git a/FL/Fl_Scroll.H b/FL/Fl_Scroll.H
index eb81d4af2..92f23fe27 100644
--- a/FL/Fl_Scroll.H
+++ b/FL/Fl_Scroll.H
@@ -3,7 +3,7 @@
 //
 // Scroll header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2015 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
@@ -38,37 +38,37 @@
   one of the _FRAME types. This will result in the best output.
   However, if the child widgets are a sparse arrangement you must
   set box() to a real _BOX type. This can result in some
-  blinking during redrawing, but that can be solved by using a 
+  blinking during redrawing, but that can be solved by using a
   Fl_Double_Window.
 
   By default you can scroll in both directions, and the scrollbars
-  disappear if the data will fit in the area of the scroll. 
+  disappear if the data will fit in the area of the scroll.
 
   Use Fl_Scroll::type() to change this as follows :
-  <UL>
-  <LI>0                            - No scrollbars </LI>
-  <LI>Fl_Scroll::HORIZONTAL        - Only a horizontal scrollbar. </LI>
-  <LI>Fl_Scroll::VERTICAL          - Only a vertical scrollbar. </LI>
-  <LI>Fl_Scroll::BOTH              - The default is both scrollbars. </LI>
-  <LI>Fl_Scroll::HORIZONTAL_ALWAYS - Horizontal scrollbar always on, vertical always off. </LI>
-  <LI>Fl_Scroll::VERTICAL_ALWAYS   - Vertical scrollbar always on, horizontal always off. </LI>
-  <LI>Fl_Scroll::BOTH_ALWAYS       - Both always on. </LI>
-  </UL>
+
+  - 0                            - No scrollbars
+  - Fl_Scroll::HORIZONTAL        - Only a horizontal scrollbar.
+  - Fl_Scroll::VERTICAL          - Only a vertical scrollbar.
+  - Fl_Scroll::BOTH              - The default is both scrollbars.
+  - Fl_Scroll::HORIZONTAL_ALWAYS - Horizontal scrollbar always on, vertical always off.
+  - Fl_Scroll::VERTICAL_ALWAYS   - Vertical scrollbar always on, horizontal always off.
+  - Fl_Scroll::BOTH_ALWAYS       - Both always on.
 
   Use <B> scrollbar.align(int) ( see void Fl_Widget::align(Fl_Align) ) :</B>
   to change what side the scrollbars are drawn on.
 
   If the FL_ALIGN_LEFT bit is on, the vertical scrollbar is on the left.
   If the FL_ALIGN_TOP bit is on, the horizontal scrollbar is on
-  the top. Note that only the alignment flags in scrollbar are 
+  the top. Note that only the alignment flags in scrollbar are
   considered. The flags in hscrollbar however are ignored.
 
   This widget can also be used to pan around a single child widget
-  "canvas".  This child widget should be of your own class, with a 
+  "canvas".  This child widget should be of your own class, with a
   draw() method that draws the contents.  The scrolling is done by
   changing the x() and y() of the widget, so this child
   must use the x() and y() to position its drawing.
-  To speed up drawing it should test fl_push_clip().
+  To speed up drawing it should test fl_not_clipped(int x,int y,int w,int h)
+  to find out if a particular area of the widget must be drawn.
 
   Another very useful child is a single Fl_Pack, which is itself a group
   that packs its children together and changes size to surround them.
@@ -144,7 +144,7 @@ public:
   Fl_Scrollbar scrollbar;
   Fl_Scrollbar hscrollbar;
 
-  void resize(int,int,int,int);
+  void resize(int X, int Y, int W, int H);
   int handle(int);
 
   Fl_Scroll(int X,int Y,int W,int H,const char*l=0);
@@ -168,9 +168,9 @@ public:
   /**
     Gets the current size of the scrollbars' troughs, in pixels.
 
-    If this value is zero (default), this widget will use the 
+    If this value is zero (default), this widget will use the
     Fl::scrollbar_size() value as the scrollbar's width.
-  
+
     \returns Scrollbar size in pixels, or 0 if the global Fl::scrollsize() is being used.
     \see Fl::scrollbar_size(int)
   */
@@ -181,17 +181,17 @@ public:
     Sets the pixel size of the scrollbars' troughs to \p newSize, in pixels.
 
     Normally you should not need this method, and should use
-    Fl::scrollbar_size(int) instead to manage the size of ALL 
-    your widgets' scrollbars. This ensures your application 
+    Fl::scrollbar_size(int) instead to manage the size of ALL
+    your widgets' scrollbars. This ensures your application
     has a consistent UI, is the default behavior, and is normally
     what you want.
 
     Only use THIS method if you really need to override the global
     scrollbar size. The need for this should be rare.
-    
+
     Setting \p newSize to the special value of 0 causes the widget to
     track the global Fl::scrollbar_size(), which is the default.
-    
+
     \param[in] newSize Sets the scrollbar size in pixels.\n
                     If 0 (default), scrollbar size tracks the global Fl::scrollbar_size()
     \see Fl::scrollbar_size()
@@ -199,7 +199,7 @@ public:
   void scrollbar_size(int newSize) {
       if ( newSize != scrollbar_size_ ) redraw();
       scrollbar_size_ = newSize;
-  }   
+  }
 };
 
 #endif
diff --git a/src/Fl_Scroll.cxx b/src/Fl_Scroll.cxx
index f385bd932..3ad146fb7 100644
--- a/src/Fl_Scroll.cxx
+++ b/src/Fl_Scroll.cxx
@@ -3,7 +3,7 @@
 //
 // Scroll widget for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2011 by Bill Spitzak and others.
+// Copyright 1998-2015 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
@@ -35,7 +35,7 @@ void Fl_Scroll::clear() {
   add(scrollbar);
 }
 
-/** Insure the scrollbars are the last children */
+/** Insure the scrollbars are the last children. */
 void Fl_Scroll::fix_scrollbar_order() {
   Fl_Widget** a = (Fl_Widget**)array();
   if (a[children()-1] != &scrollbar) {
@@ -90,12 +90,14 @@ void Fl_Scroll::draw_clip(void* v,int X, int Y, int W, int H) {
 }
 
 /**
-   Calculate visibility/size/position of scrollbars, find children's bounding box.
-   The \p si paramater will be filled with data from the calculations.
-   Derived classes can make use of this call to figure out the scrolling area
-   eg. during resize() handling.
-   \param[in] si -- ScrollInfo structure
-   \returns Structure containing the calculated info.
+  Calculate visibility/size/position of scrollbars, find children's bounding box.
+
+  The \p si parameter will be filled with data from the calculations.
+  Derived classes can make use of this call to figure out the scrolling area
+  eg. during resize() handling.
+
+  \param[in] si -- ScrollInfo structure
+  \returns Structure containing the calculated info.
 */
 void Fl_Scroll::recalc_scrollbars(ScrollInfo &si) {
 
@@ -170,7 +172,7 @@ void Fl_Scroll::recalc_scrollbars(ScrollInfo &si) {
 
   // calculate hor scrollbar position
   si.hscroll.x = si.innerchild.x;
-  si.hscroll.y = (scrollbar.align() & FL_ALIGN_TOP) 
+  si.hscroll.y = (scrollbar.align() & FL_ALIGN_TOP)
 		     ? si.innerbox.y
 		     : si.innerbox.y + si.innerbox.h - si.scrollsize;
   si.hscroll.w = si.innerchild.w;
@@ -213,10 +215,10 @@ void Fl_Scroll::recalc_scrollbars(ScrollInfo &si) {
 /**
   Returns the bounding box for the interior of the scrolling area, inside
   the scrollbars.
-  
+
   Currently this is only reliable after draw(), and before any resizing of
   the Fl_Scroll or any child widgets occur.
-  
+
   \todo The visibility of the scrollbars ought to be checked/calculated
   outside of the draw() method (STR #1895).
 */
@@ -328,6 +330,30 @@ void Fl_Scroll::draw() {
   }
 }
 
+/**
+  Resizes the Fl_Scroll widget and moves its children if necessary.
+
+  The Fl_Scroll widget first resizes itself, and then it moves all its
+  children if (and only if) the Fl_Scroll widget has been moved. The
+  children are moved by the same amount as the Fl_Scroll widget has been
+  moved, hence all children keep their relative positions.
+
+  \note Fl_Scroll::resize() does \b not call Fl_Group::resize(), and
+  child widgets are \b not resized.
+
+  Since children of an Fl_Scroll are not resized, the resizable() widget
+  is ignored (if it is set).
+
+  The scrollbars are moved to their proper positions, as given by
+  Fl_Scroll::scrollbar.align(), and switched on or off as necessary.
+
+  \note Due to current (FLTK 1.3.x) implementation constraints some of this
+  may effectively be postponed until the Fl_Scroll is drawn the next time.
+  This may change in a future release.
+
+  \sa Fl_Group::resizable()
+  \sa Fl_Widget::resize(int,int,int,int)
+*/
 void Fl_Scroll::resize(int X, int Y, int W, int H) {
   int dx = X-x(), dy = Y-y();
   int dw = W-w(), dh = H-h();
@@ -346,12 +372,27 @@ void Fl_Scroll::resize(int X, int Y, int W, int H) {
     scrollbar.position(al?X:X+W-scrollbar.w(), (at&&pad)?Y+hscrollbar.h():Y);
     hscrollbar.position((al&&pad)?X+scrollbar.w():X, at?Y:Y+H-hscrollbar.h());
   } else {
-    // FIXME recalculation of scrollbars needs to be moved out fo "draw()" (STR #1895)
+    // FIXME recalculation of scrollbars needs to be moved out of "draw()" (STR #1895)
     redraw(); // need full recalculation of scrollbars
   }
 }
 
-/**  Moves the contents of the scroll group to a new position.*/
+/**  Moves the contents of the scroll group to a new position.
+
+  This is like moving the scrollbars of the Fl_Scroll around. For instance:
+  \code
+    Fl_Scroll scroll (10,10,200,200);
+    Fl_Box b1 ( 10, 10,50,50,"b1"); // relative (x,y) = (0,0)
+    Fl_Box b2 ( 60, 60,50,50,"b2"); // relative (x,y) = (50,50)
+    Fl_Box b3 ( 60,110,50,50,"b3"); // relative (x,y) = (50,100)
+    // populate scroll with more children ...
+    scroll.end();
+    scroll.scroll_to(50,100);
+  \endcode
+  will move the logical origin of the internal scroll area to (-50,-100)
+  relative to the origin of the Fl_Scroll (10,10), i.e. Fl_Box b3 will
+  be visible in the top left corner of the scroll area.
+*/
 void Fl_Scroll::scroll_to(int X, int Y) {
   int dx = xposition_-X;
   int dy = yposition_-Y;
@@ -380,15 +421,16 @@ void Fl_Scroll::scrollbar_cb(Fl_Widget* o, void*) {
 /**
   Creates a new Fl_Scroll 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
+
+  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. A kludge has been done so the
   Fl_Scroll and all of its children can be automatic (local)
   variables, but you must declare the Fl_Scroll <I>first</I>, so
   that it is destroyed last.
 */
 Fl_Scroll::Fl_Scroll(int X,int Y,int W,int H,const char* L)
-  : Fl_Group(X,Y,W,H,L), 
+  : Fl_Group(X,Y,W,H,L),
     scrollbar(X+W-Fl::scrollbar_size(),Y,
               Fl::scrollbar_size(),H-Fl::scrollbar_size()),
     hscrollbar(X,Y+H-Fl::scrollbar_size(),