- Fixed a bug in the scrollable_region widget that caused it to scroll in an

    unpleasant way when the horizontal and vertical scroll increments weren't set
    to the same value.
  - Generally made the specs more clear and added some missing requires clauses.

--HG--
extra : convert_revision : svn%3Afdd8eb12-d10e-0410-9acb-85c331704f74/trunk%402519

dlib/geometry/rectangle_abstract.h

@@ -70,6 +70,8 @@ namespace dlib
             unsigned long height_
         );
         /*!
+            requires
+                - (width_ > 0 && height_ > 0) || (width_ == 0 && height_ == 0)
             ensures
                 - #left() == 0  
                 - #top() == 0

dlib/gui_widgets/base_widgets.h

@@ -2950,6 +2950,14 @@ namespace dlib
             unsigned long height
         )
         {
+            DLIB_ASSERT(width > 0 && height > 0 || width == 0 && height == 0,
+                "\tvoid scrollable_region::set_total_rect_size(width,height)"
+                << "\n\twidth and height must be > 0 or both == 0"
+                << "\n\twidth:  " << width 
+                << "\n\theight: " << height 
+                << "\n\tthis: " << this
+                );
+
             total_rect_ = move_rect(rectangle(width,height), 
                                     display_rect_.left()-static_cast<long>(hsb.slider_pos()),
                                     display_rect_.top()-static_cast<long>(vsb.slider_pos()));
@@ -2965,9 +2973,10 @@ namespace dlib
         }
 
         void scroll_to_rect (
-            const rectangle& r
+            const rectangle& r_
         )
         {
+            const rectangle r(total_rect_.intersect(r_));
             const rectangle old(total_rect_);
             // adjust the horizontal scroll bar so that r fits as best as possible
             if (r.left() < display_rect_.left())
@@ -2984,12 +2993,12 @@ namespace dlib
             // adjust the vertical scroll bar so that r fits as best as possible
             if (r.top() < display_rect_.top())
             {
-                long distance = (r.top()-total_rect_.top())/hscroll_bar_inc;
+                long distance = (r.top()-total_rect_.top())/vscroll_bar_inc;
                 vsb.set_slider_pos(distance);
             }
             else if (r.bottom() > display_rect_.bottom())
             {
-                long distance = (r.bottom()-total_rect_.top()-display_rect_.height()+hscroll_bar_inc)/hscroll_bar_inc;
+                long distance = (r.bottom()-total_rect_.top()-display_rect_.height()+vscroll_bar_inc)/vscroll_bar_inc;
                 vsb.set_slider_pos(distance);
             }
       

dlib/gui_widgets/base_widgets_abstract.h

@@ -1580,7 +1580,9 @@ namespace dlib
                 protected member functions.  It provides a function, total_rect(), that
                 tells you where the 2D region is on the screen.  You draw your stuff 
                 inside total_rect() as you would normally except that you only modify 
-                pixels that are also inside display_rect(). 
+                pixels that are also inside display_rect().  When the user moves the
+                scroll bars the position of total_rect() is updated accordingly, causing
+                the widget's content to scroll across the screen. 
         !*/
 
     public:
@@ -1715,9 +1717,13 @@ namespace dlib
         /*!
             requires
                 - mutex drawable::m is locked
+                - (width > 0 && height > 0) || (width == 0 && height == 0)
             ensures
-                - #total_rect().width() == width
+                - #total_rect().width()  == width
                 - #total_rect().height() == height 
+                - The scroll bars as well as the position of #total_rect() 
+                  is updated so that the total rect is still in the correct
+                  position with respect to the scroll bars.
         !*/
 
         const rectangle& total_rect (
@@ -1728,7 +1734,7 @@ namespace dlib
             ensures
                 - returns a rectangle that represents the entire scrollable
                   region inside this widget, even the parts that are outside
-                  this->rect.  
+                  display_rect().  
         !*/
 
         void scroll_to_rect (
@@ -1738,9 +1744,9 @@ namespace dlib
             requires
                 - mutex drawable::m is locked
             ensures
-                - adjusts the scroll bars of this object so that the rectangle
-                  r is displayed in the display_rect() (or as close to being 
-                  displayed as possible if r is outside of total_rect())
+                - Adjusts the scroll bars of this object so that the part of 
+                  the total_rect() rectangle that overlaps with r is displayed in 
+                  the display_rect() rectangle on the screen.
         !*/
 
     // ---------------------------- event handlers ----------------------------