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

@@ -760,11 +760,14 @@ gimp_display_shell_size_changed_detailed_handler (GimpImage        *image,
       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_x;
-      gint       scaled_previous_origin_y = SCALEY (shell, previous_origin_y);
+      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
+       * gimp_display_shell_scroll_clamp_and_update() and
-       * need it to be called, so simply call it explicitly here at
+       * gimp_display_shell_expose_full() in all cases because when
-       * the end
+       * 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);
 

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);
 }