Merge pull request #3369 from Carreau/auto-scroll

Use different treshold for (auto)scroll in output

Use different treshold for (auto)scroll in output
Allow, in particular to switch to scolling for longer input (or disable
it) by still keeping the possibility to manually toggle the output to
scroll.

cf jsdoc, 
OutputArea.auto_scroll_threshold
and
OutputArea.minimum_scroll_threshold

OutputArea.auto_scroll_threshold < 0 will prevent auto_scroll from ever happening.

IPython/frontend/html/notebook/static/notebook/js/notebook.js

@@ -1257,7 +1257,7 @@ var IPython = (function (IPython) {
         for (var i=0; i<ncells; i++) {
             if (cells[i] instanceof IPython.CodeCell) {
                 cells[i].output_area.expand();
-                cells[i].output_area.scroll_if_long(20);
+                cells[i].output_area.scroll_if_long();
             }
         };
         // this should not be set if the `collapse` key is removed from nbformat

IPython/frontend/html/notebook/static/notebook/js/outputarea.js

@@ -1,5 +1,5 @@
 //----------------------------------------------------------------------------
-//  Copyright (C) 2008-2011  The IPython Development Team
+//  Copyright (C) 2008 The IPython Development Team
 //
 //  Distributed under the terms of the BSD License.  The full license is in
 //  the file COPYING, distributed as part of this software.
@@ -9,11 +9,22 @@
 // OutputArea
 //============================================================================
 
+/**
+ * @module IPython
+ * @namespace IPython
+ * @submodule OutputArea
+ */
 var IPython = (function (IPython) {
     "use strict";
 
     var utils = IPython.utils;
 
+    /**
+     * @class OutputArea
+     *
+     * @constructor
+     */
+
     var OutputArea = function (selector, prompt_area) {
         this.selector = selector;
         this.wrapper = $(selector);
@@ -59,8 +70,18 @@ var IPython = (function (IPython) {
         this.collapse();
     };
 
-
+    /**
+     * Should the OutputArea scroll?
+     * Returns whether the height (in lines) exceeds a threshold.
+     *
+     * @private
+     * @method _should_scroll
+     * @param [lines=100]{Integer}
+     * @return {Bool}
+     *
+     */
     OutputArea.prototype._should_scroll = function (lines) {
+        if (lines <=0 ){ return }
         if (!lines) {
             lines = 100;
         }
@@ -84,7 +105,7 @@ var IPython = (function (IPython) {
             }
             // maybe scroll output,
             // if it's grown large enough and hasn't already been scrolled.
-            if ( !that.scrolled && that._should_scroll()) {
+            if ( !that.scrolled && that._should_scroll(OutputArea.auto_scroll_threshold)) {
                 that.scroll_area();
             }
         });
@@ -143,9 +164,55 @@ var IPython = (function (IPython) {
         this.scrolled = false;
     };
 
-
+    /**
+     * Threshold to trigger autoscroll when the OutputArea is resized,
+     * typically when new outputs are added.
+     *
+     * Behavior is undefined if autoscroll is lower than minimum_scroll_threshold,
+     * unless it is < 0, in which case autoscroll will never be triggered
+     *
+     * @property auto_scroll_threshold
+     * @type Number
+     * @default 100
+     *
+     **/
+    OutputArea.auto_scroll_threshold = 100;
+
+
+    /**
+     * Lower limit (in lines) for OutputArea to be made scrollable. OutputAreas
+     * shorter than this are never scrolled.
+     *
+     * @property minimum_scroll_threshold
+     * @type Number
+     * @default 20
+     *
+     **/
+    OutputArea.minimum_scroll_threshold = 20;
+
+
+    /**
+     *
+     * Scroll OutputArea if height supperior than a threshold (in lines).
+     *
+     * Threshold is a maximum number of lines. If unspecified, defaults to
+     * OutputArea.minimum_scroll_threshold.
+     *
+     * Negative threshold will prevent the OutputArea from ever scrolling.
+     *
+     * @method scroll_if_long
+     *
+     * @param [lines=20]{Number} Default to 20 if not set,
+     * behavior undefined for value of `0`.
+     *
+     **/
     OutputArea.prototype.scroll_if_long = function (lines) {
-        if (this._should_scroll(lines)) {
+        var n = lines | OutputArea.minimum_scroll_threshold;
+        if(n <= 0){
+            return
+        }
+
+        if (this._should_scroll(n)) {
             // only allow scrolling long-enough output
             this.scroll_area();
         }
@@ -157,7 +224,7 @@ var IPython = (function (IPython) {
             this.unscroll_area();
         } else {
             // only allow scrolling long-enough output
-            this.scroll_if_long(20);
+            this.scroll_if_long();
         }
     };
 
@@ -466,7 +533,7 @@ var IPython = (function (IPython) {
         toinsert.append(latex);
         element.append(toinsert);
     };
-    
+
     OutputArea.prototype.append_raw_input = function (content) {
         var that = this;
         this.expand();