In addition to minor code cleanup I also changed the following:

   - The zoomable_region widget now uses exponential rather than linear
     zoom scaling since this is much more pleasing to use.  There is now
     a new requirement on the zoom increment that it must be between 0
     and 1.
   - I added a few missing requires clauses.
   - I changed the set_zoom_scale() function so that it actually changes
     the zoom scale even if the user requests a zoom value outside the
     allowed range.  It just uses the max or min allowed value rather than
     doing nothing.

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

dlib/gui_widgets/base_widgets.cpp

@@ -1963,7 +1963,7 @@ namespace dlib
         drawable(w,MOUSE_CLICK | MOUSE_WHEEL | MOUSE_MOVE | events),
         min_scale(0.15),
         max_scale(1.0),
-        zoom_increment_(0.02),
+        zoom_increment_(0.90),
         vsb(w, scroll_bar::VERTICAL),
         hsb(w, scroll_bar::HORIZONTAL)
     {
@@ -2010,6 +2010,13 @@ namespace dlib
         double zi
     )
     {
+        DLIB_ASSERT(0.0 < zi && zi < 1.0,
+                    "\tvoid zoomable_region::set_zoom_increment(zi)"
+                    << "\n\t the zoom increment must be between 0 and 1"
+                    << "\n\t zi:   " << zi
+                    << "\n\t this: " << this
+        );
+
         auto_mutex M(m);
         zoom_increment_ = zi;
     }
@@ -2031,6 +2038,13 @@ namespace dlib
         double ms 
     )
     {
+        DLIB_ASSERT(ms > 0,
+                    "\tvoid zoomable_region::set_max_zoom_scale(ms)"
+                    << "\n\t the max zoom scale must be greater than 0"
+                    << "\n\t ms:   " << ms 
+                    << "\n\t this: " << this
+        );
+
         auto_mutex M(m);
         max_scale = ms;
         if (scale > ms)
@@ -2048,6 +2062,13 @@ namespace dlib
         double ms 
     )
     {
+        DLIB_ASSERT(ms > 0,
+                    "\tvoid zoomable_region::set_min_zoom_scale(ms)"
+                    << "\n\t the min zoom scale must be greater than 0"
+                    << "\n\t ms:   " << ms 
+                    << "\n\t this: " << this
+        );
+
         auto_mutex M(m);
         min_scale = ms;
 
@@ -2084,8 +2105,8 @@ namespace dlib
 
     void zoomable_region::
     set_size (
-        long width,
-        long height
+        unsigned long width,
+        unsigned long height
     )
     {
         auto_mutex M(m);
@@ -2233,15 +2254,22 @@ namespace dlib
         double new_scale
     )
     {
-        if (min_scale <= new_scale && new_scale <= max_scale)
+        // if new_scale isn't in the right range then put it back in range before we do the 
+        // rest of this function
+        if (!(min_scale <= new_scale && new_scale <= max_scale))
         {
-            // find the point in the center of the graph area
-            point center((display_rect_.left()+display_rect_.right())/2,  (display_rect_.top()+display_rect_.bottom())/2);
-            point graph_p(gui_to_graph_space(center));
-            scale = new_scale;
-            adjust_origin(center, graph_p);
-            redraw_graph();
+            if (new_scale > max_scale)
+                new_scale = max_scale;
+            else
+                new_scale = min_scale;
         }
+
+        // find the point in the center of the graph area
+        point center((display_rect_.left()+display_rect_.right())/2,  (display_rect_.top()+display_rect_.bottom())/2);
+        point graph_p(gui_to_graph_space(center));
+        scale = new_scale;
+        adjust_origin(center, graph_p);
+        redraw_graph();
     }
 
 // ----------------------------------------------------------------------------------------
@@ -2269,7 +2297,7 @@ namespace dlib
         {
             point gui_p(lastx,lasty);
             point graph_p(gui_to_graph_space(gui_p));
-            scale -= zoom_increment_;
+            scale *= zoom_increment_;
             if (scale < min_scale)
                 scale = min_scale;
             redraw_graph(); 
@@ -2289,7 +2317,7 @@ namespace dlib
         {
             point gui_p(lastx,lasty);
             point graph_p(gui_to_graph_space(gui_p));
-            scale += zoom_increment_;
+            scale /= zoom_increment_;
             if (scale > max_scale)
                 scale = max_scale;
             redraw_graph(); 
@@ -3127,8 +3155,8 @@ namespace dlib
 
     void popup_menu_region::
     set_size (
-        long width, 
-        long height
+        unsigned long width, 
+        unsigned long height
     )
     {
         auto_mutex M(m);

dlib/gui_widgets/base_widgets.h

@@ -463,8 +463,8 @@ namespace dlib
         ){ disable_events();}
 
         void set_size (
-            long width, 
-            long height 
+            unsigned long width, 
+            unsigned long height 
         )
         {
             auto_mutex M(m);
@@ -2143,8 +2143,8 @@ namespace dlib
         ) const;
 
         void set_size (
-            long width,
-            long height
+            unsigned long width,
+            unsigned long height
         );
 
         void show (
@@ -2510,8 +2510,8 @@ namespace dlib
         );
 
         void set_size (
-            long width, 
-            long height
+            unsigned long width, 
+            unsigned long height
         );
 
         void set_rect (

dlib/gui_widgets/base_widgets_abstract.h

@@ -1040,8 +1040,8 @@ namespace dlib
         !*/
 
         void set_size (
-            long width_, 
-            long height_ 
+            unsigned long width_, 
+            unsigned long height_ 
         );
         /*!
             ensures
@@ -1520,8 +1520,8 @@ namespace dlib
         !*/
 
         void set_size (
-            long width_, 
-            long height_ 
+            unsigned long width_, 
+            unsigned long height_ 
         );
         /*!
             ensures
@@ -1579,7 +1579,7 @@ namespace dlib
             INITIAL VALUE
                 - min_zoom_scale() == 0.15
                 - max_zoom_scale() == 1.0
-                - zoom_increment() == 0.02
+                - zoom_increment() == 0.90
                 - zoom_scale() == 1.0
 
             WHAT THIS OBJECT REPRESENTS
@@ -1651,6 +1651,8 @@ namespace dlib
             double zi
         );
         /*!
+            requires
+                - 0 < zi < 1
             ensures
                 - #zoom_increment() == zi
         !*/
@@ -1659,14 +1661,20 @@ namespace dlib
         ) const;
         /*!
             ensures
-                - returns the amount by which zoom_scale() is changed when the user
-                  zooms in or out by using the mouse wheel.
+                - When the user zooms in using the mouse wheel:
+                    - #zoom_scale() == zoom_scale() / zoom_increment()
+                - When the user zooms out using the mouse wheel:
+                    - #zoom_scale() == zoom_scale() * zoom_increment()
+                - So this function returns the number that determines how much the zoom
+                  changes when the mouse wheel is moved.
         !*/
 
         void set_max_zoom_scale (
             double ms 
         );
         /*!
+            requires
+                - ms > 0
             ensures
                 - #max_zoom_scale() == ms
         !*/
@@ -1675,6 +1683,8 @@ namespace dlib
             double ms 
         );
         /*!
+            requires
+                - ms > 0
             ensures
                 - #min_zoom_scale() == ms
         !*/
@@ -1684,6 +1694,7 @@ namespace dlib
         /*!
             ensures
                 - returns the minimum allowed value of zoom_scale()
+                  (i.e. this is the number that determines how far out the user is allowed to zoom)
         !*/
 
         double max_zoom_scale (
@@ -1691,11 +1702,12 @@ namespace dlib
         /*!
             ensures
                 - returns the maximum allowed value of zoom_scale() 
+                  (i.e. this is the number that determines how far in the user is allowed to zoom)
         !*/
 
         void set_size (
-            long width,
-            long height
+            unsigned long width,
+            unsigned long height
         );
         /*! 
             ensures
@@ -1775,12 +1787,13 @@ namespace dlib
             requires
                 - mutex drawable::m is locked
             ensures
+                - invalidates the display_rect() so that it will be redrawn
                 - if (min_zoom_scale() <= new_scale && new_scale <= max_zoom_scale()) then
                     - #zoom_scale() == new_scale
-                    - invalidates the display_rect() so that it will be redrawn
-                - else
-                   - #zoom_scale() == zoom_scale()
-                     I.e. this function has no effect
+                - else if (new_scale < min_zoom_scale()) then
+                    - #zoom_scale() == min_zoom_scale() 
+                - else if (new_scale > max_zoom_scale()) then
+                    - #zoom_scale() == max_zoom_scale() 
         !*/
 
         void center_display_at_graph_point (