[gimp] app: clean up gimp_display_shell_scroll() a bit

[Michael Natterer <mitch src gnome org>]

commit 18bd9c39c3dd7bca0de05d6ebc60a1052fe589c7
Author: Michael Natterer <mitch gimp org>
Date:   Tue Jan 5 17:33:22 2016 +0100

    app: clean up gimp_display_shell_scroll() a bit
    
    and document the difference to gimp_display_shell_scroll_set_offset()
    and why we need both.

 app/display/gimpdisplayshell-handlers.c |   22 ++++++++----
 app/display/gimpdisplayshell-scroll.c   |   55 +++++++++++++++++++------------
 2 files changed, 48 insertions(+), 29 deletions(-)
---
diff --git a/app/display/gimpdisplayshell-handlers.c b/app/display/gimpdisplayshell-handlers.c
index fd23e16..cd8c5d2 100644
--- a/app/display/gimpdisplayshell-handlers.c
+++ b/app/display/gimpdisplayshell-handlers.c
@@ -757,14 +757,17 @@ gimp_display_shell_size_changed_detailed_handler (GimpImage        *image,
     }
   else
     {
-      GimpImage *image                    = gimp_display_get_image (shell->display);
-      gint       new_width                = gimp_image_get_width  (image);
-      gint       new_height               = gimp_image_get_height (image);
-      gint       scaled_previous_origin_x = SCALEX (shell, previous_origin_x);
-      gint       scaled_previous_origin_y = SCALEY (shell, previous_origin_y);
+      GimpImage *image      = gimp_display_get_image (shell->display);
+      gint       new_width  = gimp_image_get_width  (image);
+      gint       new_height = gimp_image_get_height (image);
+      gint       scaled_previous_origin_x;
+      gint       scaled_previous_origin_y;
       gboolean   horizontally;
       gboolean   vertically;
 
+      scaled_previous_origin_x = SCALEX (shell, previous_origin_x);
+      scaled_previous_origin_y = SCALEY (shell, previous_origin_y);
+
       horizontally = (SCALEX (shell, previous_width)  >  shell->disp_width  &&
                       SCALEX (shell, new_width)       <= shell->disp_width);
       vertically   = (SCALEY (shell, previous_height) >  shell->disp_height &&
@@ -777,9 +780,12 @@ gimp_display_shell_size_changed_detailed_handler (GimpImage        *image,
       gimp_display_shell_scroll_center_image (shell, horizontally, vertically);
 
       /* The above calls might not lead to a call to
-       * gimp_display_shell_scroll_clamp_and_update() in all cases we
-       * need it to be called, so simply call it explicitly here at
-       * the end
+       * gimp_display_shell_scroll_clamp_and_update() and
+       * gimp_display_shell_expose_full() in all cases because when
+       * scaling the old and new scroll offset might be the same.
+       *
+       * We need them to be called in all cases, so simply call them
+       * explicitly here at the end
        */
       gimp_display_shell_scroll_clamp_and_update (shell);
 
diff --git a/app/display/gimpdisplayshell-scroll.c b/app/display/gimpdisplayshell-scroll.c
index c9a3ce3..dc214d8 100644
--- a/app/display/gimpdisplayshell-scroll.c
+++ b/app/display/gimpdisplayshell-scroll.c
@@ -48,6 +48,18 @@
 static void   gimp_display_shell_scroll_clamp_offsets (GimpDisplayShell *shell);
 
 
+/**
+ * gimp_display_shell_scroll:
+ * @shell:
+ * @x_offset:
+ * @y_offset:
+ *
+ * This function scrolls the image in the shell's viewport. It does
+ * actual scrolling of the pixels, so only the newly scrolled-in parts
+ * are freshly redrawn.
+ *
+ * Use it for incremental actual panning.
+ **/
 void
 gimp_display_shell_scroll (GimpDisplayShell *shell,
                            gint              x_offset,
@@ -64,10 +76,13 @@ gimp_display_shell_scroll (GimpDisplayShell *shell,
   old_x = shell->offset_x;
   old_y = shell->offset_y;
 
+  /* freeze the active tool */
+  gimp_display_shell_pause (shell);
+
   shell->offset_x += x_offset;
   shell->offset_y += y_offset;
 
-  gimp_display_shell_scroll_clamp_offsets (shell);
+  gimp_display_shell_scroll_clamp_and_update (shell);
 
   /*  the actual changes in offset  */
   x_offset = (shell->offset_x - old_x);
@@ -75,31 +90,29 @@ gimp_display_shell_scroll (GimpDisplayShell *shell,
 
   if (x_offset || y_offset)
     {
-      /*  reset the old values so that the tool can accurately redraw  */
-      shell->offset_x = old_x;
-      shell->offset_y = old_y;
-
-      gimp_display_shell_pause (shell);
-
-      /*  set the offsets back to the new values  */
-      shell->offset_x += x_offset;
-      shell->offset_y += y_offset;
-
-      gimp_display_shell_rotate_update_transform (shell);
-
       gimp_overlay_box_scroll (GIMP_OVERLAY_BOX (shell->canvas),
                                -x_offset, -y_offset);
 
-      /*  Update scrollbars and rulers  */
-      gimp_display_shell_scale_update_scrollbars (shell);
-      gimp_display_shell_scale_update_rulers (shell);
-
-      gimp_display_shell_resume (shell);
-
       gimp_display_shell_scrolled (shell);
     }
+
+  /* re-enable the active tool */
+  gimp_display_shell_resume (shell);
 }
 
+/**
+ * gimp_display_shell_scroll_set_offsets:
+ * @shell:
+ * @offset_x:
+ * @offset_y:
+ *
+ * This function scrolls the image in the shell's viewport. It redraws
+ * the entire canvas.
+ *
+ * Use it for setting the scroll offset on freshly scaled images or
+ * when the window is resized. For panning, use
+ * gimp_display_shell_scroll().
+ **/
 void
 gimp_display_shell_scroll_set_offset (GimpDisplayShell *shell,
                                       gint              offset_x,
@@ -121,10 +134,10 @@ gimp_display_shell_scroll_set_offset (GimpDisplayShell *shell,
 
   gimp_display_shell_scroll_clamp_and_update (shell);
 
-  gimp_display_shell_scrolled (shell);
-
   gimp_display_shell_expose_full (shell);
 
+  gimp_display_shell_scrolled (shell);
+
   /* re-enable the active tool */
   gimp_display_shell_resume (shell);
 }