highcharts 6.1.1 → 6.2.0

package/js/es-modules/parts/Scrollbar.js

@@ -1,5 +1,5 @@
 /**
- * (c) 2010-2017 Torstein Honsi
+ * (c) 2010-2018 Torstein Honsi
  *
  * License: www.highcharts.com/license
  */
@@ -21,8 +21,6 @@ var addEvent = H.addEvent,
     merge = H.merge,
     pick = H.pick,
     removeEvent = H.removeEvent,
-    svg = H.svg,
-    wrap = H.wrap,
     swapXY;
 
 /**
@@ -52,65 +50,115 @@ var defaultScrollbarOptions = {
      * of the scroll arrows so that they are always squares. Defaults to
      * 20 for touch devices and 14 for mouse devices.
      *
-     * @type {Number}
-     * @sample {highstock} stock/scrollbar/height/ A 30px scrollbar
-     * @product highstock
+     * @sample {highstock} stock/scrollbar/height/
+     *         A 30px scrollbar
+     *
+     * @type       {number}
+     * @default    20/14
+     * @product    highstock
+     * @apioption  scrollbar.height
      */
     height: isTouchDevice ? 20 : 14,
 
     /**
      * The border rounding radius of the bar.
      *
-     * @type {Number}
-     * @sample {highstock} stock/scrollbar/style/ Scrollbar styling
-     * @default 0
-     * @product highstock
+     * @sample {highstock} stock/scrollbar/style/
+     *         Scrollbar styling
+     *
+     * @type       {number}
+     * @default    0
+     * @product    highstock
+     * @apioption  scrollbar.barBorderRadius
      */
     barBorderRadius: 0,
 
     /**
      * The corner radius of the scrollbar buttons.
      *
-     * @type {Number}
-     * @sample {highstock} stock/scrollbar/style/ Scrollbar styling
-     * @default 0
-     * @product highstock
+     * @sample {highstock} stock/scrollbar/style/
+     *         Scrollbar styling
+     *
+     * @type       {number}
+     * @default    0
+     * @product    highstock
+     * @apioption  scrollbar.buttonBorderRadius
      */
     buttonBorderRadius: 0,
 
+    /**
+     * Enable or disable the scrollbar.
+     *
+     * @type       {boolean}
+     * @sample     {highstock} stock/scrollbar/enabled/
+     *             Disable the scrollbar, only use navigator
+     * @default    true
+     * @product    highstock
+     * @apioption  scrollbar.enabled
+     */
+
     /**
      * Whether to redraw the main chart as the scrollbar or the navigator
      * zoomed window is moved. Defaults to `true` for modern browsers and
      * `false` for legacy IE browsers as well as mobile devices.
      *
-     * @type {Boolean}
-     * @since 1.3
-     * @product highstock
+     * @type       {boolean}
+     * @since      1.3
+     * @product    highstock
+     *
+     * @sample     stock/scrollbar/liveredraw Setting live redraw to false
+     *
+     * @apioption  scrollbar.liveRedraw
      */
-    liveRedraw: svg && !isTouchDevice,
+    liveRedraw: undefined,
 
     /**
      * The margin between the scrollbar and its axis when the scrollbar is
      * applied directly to an axis.
+     *
+     * @type       {number}
+     * @default    10
+     * @apioption  scrollbar.margin
      */
     margin: 10,
 
     /**
      * The minimum width of the scrollbar.
      *
-     * @type {Number}
-     * @default 6
-     * @since 1.2.5
-     * @product highstock
+     * @type       {number}
+     * @default    6
+     * @since      1.2.5
+     * @product    highstock
+     * @apioption  scrollbar.minWidth
      */
     minWidth: 6,
 
+    /**
+     * Whether to show or hide the scrollbar when the scrolled content is
+     * zoomed out to it full extent.
+     *
+     * @type       {boolean}
+     * @default    true
+     * @product    highstock
+     * @apioption  scrollbar.showFull
+     */
+
+    /**
+     * @type       {number}
+     * @default    0.2
+     * @apioption  scrollbar.step
+     */
     step: 0.2,
 
     /**
      * The z index of the scrollbar group.
+     *
+     * @type       {number}
+     * @default    3
+     * @apioption  scrollbar.zIndex
      */
     zIndex: 3
+
     
 };
 
@@ -121,11 +169,19 @@ defaultOptions.scrollbar = merge(
 );
 
 /**
-* When we have vertical scrollbar, rifles and arrow in buttons should be
-* rotated. The same method is used in Navigator's handles, to rotate them.
-* @param {Array} path - path to be rotated
-* @param {Boolean} vertical - if vertical scrollbar, swap x-y values
-*/
+ * When we have vertical scrollbar, rifles and arrow in buttons should be
+ * rotated. The same method is used in Navigator's handles, to rotate them.
+ *
+ * @function Highcharts.swapXY
+ *
+ * @param  {Array<number|string>} path
+ *         Path to be rotated.
+ *
+ * @param  {boolean} vertical
+ *         If vertical scrollbar, swap x-y values.
+ *
+ * @return {Array<number|string>}
+ */
 H.swapXY = swapXY = function (path, vertical) {
     var i,
         len = path.length,
@@ -146,10 +202,13 @@ H.swapXY = swapXY = function (path, vertical) {
  * A reusable scrollbar, internally used in Highstock's navigator and optionally
  * on individual axes.
  *
- * @class
- * @param {Object} renderer
- * @param {Object} options
- * @param {Object} chart
+ * @class Highcharts.Scrollbar
+ *
+ * @param {Highcharts.SVGRenderer} renderer
+ *
+ * @param {Highcharts.ScrollbarOptions} options
+ *
+ * @param {Highcharts.Chart} chart
  */
 function Scrollbar(renderer, options, chart) { // docs
     this.init(renderer, options, chart);
@@ -157,6 +216,17 @@ function Scrollbar(renderer, options, chart) { // docs
 
 Scrollbar.prototype = {
 
+    /**
+     * @function Highcharts.Scrollbar#init
+     *
+     * @param  {Highcharts.SVGRenderer} renderer
+     *
+     * @param  {Highcharts.ScrollbarOptions} options
+     *
+     * @param  {Highcharts.Chart} chart
+     *
+     * @return {void}
+     */
     init: function (renderer, options, chart) {
 
         this.scrollbarButtons = [];
@@ -181,6 +251,10 @@ Scrollbar.prototype = {
 
     /**
     * Render scrollbar with all required items.
+    *
+    * @function Highcharts.Scrollbar#render
+    *
+    * @return {void}
     */
     render: function () {
         var scroller = this,
@@ -256,10 +330,22 @@ Scrollbar.prototype = {
     /**
      * Position the scrollbar, method called from a parent with defined
      * dimensions.
-     * @param {Number} x - x-position on the chart
-     * @param {Number} y - y-position on the chart
-     * @param {Number} width - width of the scrollbar
-     * @param {Number} height - height of the scorllbar
+     *
+     * @function Highcharts.Scrollbar#position
+     *
+     * @param  {number} x
+     *         x-position on the chart
+     *
+     * @param  {number} y
+     *         y-position on the chart
+     *
+     * @param  {number} width
+     *         width of the scrollbar
+     *
+     * @param  {number} height
+     *         height of the scorllbar
+     *
+     * @return {void}
      */
     position: function (x, y, width, height) {
         var scroller = this,
@@ -310,7 +396,13 @@ Scrollbar.prototype = {
 
     /**
      * Draw the scrollbar buttons with arrows
-     * @param {Number} index 0 is left, 1 is right
+     *
+     * @function Highcharts.Scrollbar#drawScrollbarButton
+     *
+     * @param  {number} index
+     *         0 is left, 1 is right
+     *
+     * @return {void}
      */
     drawScrollbarButton: function (index) {
         var scroller = this,
@@ -361,8 +453,16 @@ Scrollbar.prototype = {
 
     /**
     * Set scrollbar size, with a given scale.
-    * @param {Number} from - scale (0-1) where bar should start
-    * @param {Number} to - scale (0-1) where bar should end
+    *
+    * @function Highcharts.Scrollbar#setRange
+    *
+    * @param  {number} from
+    *         scale (0-1) where bar should start
+    *
+    * @param  {number} to
+    *         scale (0-1) where bar should end
+    *
+    * @return {void}
     */
     setRange: function (from, to) {
         var scroller = this,
@@ -375,7 +475,11 @@ Scrollbar.prototype = {
             newPos,
             newSize,
             newRiflesPos,
-            method = this.rendered && !this.hasDragged ? 'animate' : 'attr';
+            method = (
+                this.rendered &&
+                !this.hasDragged &&
+                !(this.chart.navigator && this.chart.navigator.hasDragged)
+            ) ? 'animate' : 'attr';
 
         if (!defined(fullWidth)) {
             return;
@@ -444,6 +548,13 @@ Scrollbar.prototype = {
 
     /**
     * Init events methods, so we have an access to the Scrollbar itself
+    *
+    * @function Highcharts.Scrollbar#initEvents
+    *
+    * @return {void}
+    *
+    * @todo
+    * Make events official: Fires the event `changed`.
     */
     initEvents: function () {
         var scroller = this;
@@ -584,9 +695,14 @@ Scrollbar.prototype = {
 
     /**
      * Get normalized (0-1) cursor position over the scrollbar
-     * @param {Event} normalizedEvent - normalized event, with chartX and chartY
-     *                                values
-     * @return {Object} Local position {chartX, chartY}
+     *
+     * @function Highcharts.Scrollbar#cursorToScrollbarPosition
+     *
+     * @param  {*} normalizedEvent
+     *         normalized event, with chartX and chartY values
+     *
+     * @return {*}
+     *         Local position {chartX, chartY}
      */
     cursorToScrollbarPosition: function (normalizedEvent) {
         var scroller = this,
@@ -605,6 +721,14 @@ Scrollbar.prototype = {
 
     /**
     * Update position option in the Scrollbar, with normalized 0-1 scale
+    *
+    * @function Highcharts.Scrollbar#updatePosition
+    *
+    * @param  {number} from
+    *
+    * @param  {number} to
+    *
+    * @return {void}
     */
     updatePosition: function (from, to) {
         if (to > 1) {
@@ -623,6 +747,12 @@ Scrollbar.prototype = {
 
     /**
      * Update the scrollbar with new options
+     *
+     * @function Highcharts.Scrollbar#update
+     *
+     * @param  {Highcharts.ScrollbarOptions} options
+     *
+     * @return {void}
      */
     update: function (options) {
         this.destroy();
@@ -635,6 +765,10 @@ Scrollbar.prototype = {
 
     /**
      * Set up the mouse and touch events for the Scrollbar
+     *
+     * @function Highcharts.Scrollbar#addEvents
+     *
+     * @return {void}
      */
     addEvents: function () {
         var buttonsOrder = this.options.inverted ? [1, 0] : [0, 1],
@@ -674,6 +808,10 @@ Scrollbar.prototype = {
 
     /**
      * Removes the event handlers attached previously with addEvents.
+     *
+     * @function Highcharts.Scrollbar#removeEvents
+     *
+     * @return {void}
      */
     removeEvents: function () {
         each(this._events, function (args) {
@@ -684,6 +822,10 @@ Scrollbar.prototype = {
 
     /**
      * Destroys allocated elements.
+     *
+     * @function Highcharts.Scrollbar#destroy
+     *
+     * @return {void}
      */
     destroy: function () {
 
@@ -719,14 +861,17 @@ Scrollbar.prototype = {
     }
 };
 
-/**
-* Wrap axis initialization and create scrollbar if enabled:
-*/
-wrap(Axis.prototype, 'init', function (proceed) {
+/*
+ * Wrap axis initialization and create scrollbar if enabled:
+ */
+addEvent(Axis, 'afterInit', function () {
     var axis = this;
-    proceed.apply(axis, Array.prototype.slice.call(arguments, 1));
 
-    if (axis.options.scrollbar && axis.options.scrollbar.enabled) {
+    if (
+        axis.options &&
+        axis.options.scrollbar &&
+        axis.options.scrollbar.enabled
+    ) {
         // Predefined options:
         axis.options.scrollbar.vertical = !axis.horiz;
         axis.options.startOnTick = axis.options.endOnTick = false;
@@ -770,10 +915,10 @@ wrap(Axis.prototype, 'init', function (proceed) {
     }
 });
 
-/**
-* Wrap rendering axis, and update scrollbar if one is created:
-*/
-wrap(Axis.prototype, 'render', function (proceed) {
+/*
+ * Wrap rendering axis, and update scrollbar if one is created:
+ */
+addEvent(Axis, 'afterRender', function () {
     var axis = this,
         scrollMin = Math.min(
             pick(axis.options.min, axis.min),
@@ -791,8 +936,6 @@ wrap(Axis.prototype, 'render', function (proceed) {
         from,
         to;
 
-    proceed.apply(axis, Array.prototype.slice.call(arguments, 1));
-
     if (scrollbar) {
 
         if (axis.horiz) {
@@ -851,16 +994,14 @@ wrap(Axis.prototype, 'render', function (proceed) {
     }
 });
 
-/**
-* Make space for a scrollbar
-*/
-wrap(Axis.prototype, 'getOffset', function (proceed) {
+/*
+ * Make space for a scrollbar
+ */
+addEvent(Axis, 'afterGetOffset', function () {
     var axis = this,
         index = axis.horiz ? 2 : 1,
         scrollbar = axis.scrollbar;
 
-    proceed.apply(axis, Array.prototype.slice.call(arguments, 1));
-
     if (scrollbar) {
         axis.chart.scrollbarsOffsets = [0, 0]; // reset scrollbars offsets
         axis.chart.axisOffset[index] +=
@@ -868,15 +1009,4 @@ wrap(Axis.prototype, 'getOffset', function (proceed) {
     }
 });
 
-/**
-* Destroy scrollbar when connected to the specific axis
-*/
-wrap(Axis.prototype, 'destroy', function (proceed) {
-    if (this.scrollbar) {
-        this.scrollbar = this.scrollbar.destroy();
-    }
-
-    proceed.apply(this, Array.prototype.slice.call(arguments, 1));
-});
-
 H.Scrollbar = Scrollbar;