highcharts 6.1.1 → 6.2.0

package/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,172 +50,263 @@ 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,
+
     
 
     /**
      * The background color of the scrollbar itself.
      *
-     * @type {Color}
-     * @sample {highstock} stock/scrollbar/style/ Scrollbar styling
-     * @default #cccccc
-     * @product highstock
+     * @sample {highstock} stock/scrollbar/style/
+     *         Scrollbar styling
+     *
+     * @type       {Highcharts.ColorString}
+     * @default    #cccccc
+     * @product    highstock
+     * @apioption  scrollbar.barBackgroundColor
      */
     barBackgroundColor: '#cccccc',
 
     /**
      * The width of the bar's border.
      *
-     * @type {Number}
-     * @sample {highstock} stock/scrollbar/style/ Scrollbar styling
-     * @default 1
-     * @product highstock
+     * @sample {highstock} stock/scrollbar/style/
+     *         Scrollbar styling
+     *
+     * @type       {number}
+     * @default    1
+     * @product    highstock
+     * @apioption  scrollbar.barBorderWidth
      */
     barBorderWidth: 1,
 
     /**
      * The color of the scrollbar's border.
      *
-     * @type {Color}
-     * @default #cccccc
-     * @product highstock
+     * @type       {Highcharts.ColorString}
+     * @default    #cccccc
+     * @product    highstock
+     * @apioption  scrollbar.barBorderColor
      */
     barBorderColor: '#cccccc',
 
     /**
      * The color of the small arrow inside the scrollbar buttons.
      *
-     * @type {Color}
-     * @sample {highstock} stock/scrollbar/style/ Scrollbar styling
-     * @default #333333
-     * @product highstock
+     * @sample {highstock} stock/scrollbar/style/
+     *         Scrollbar styling
+     *
+     * @type       {Highcharts.ColorString}
+     * @default    #333333
+     * @product    highstock
+     * @apioption  scrollbar.buttonArrowColor
      */
     buttonArrowColor: '#333333',
 
     /**
      * The color of scrollbar buttons.
      *
-     * @type {Color}
-     * @sample {highstock} stock/scrollbar/style/ Scrollbar styling
-     * @default #e6e6e6
-     * @product highstock
+     * @sample {highstock} stock/scrollbar/style/
+     *         Scrollbar styling
+     *
+     * @type       {Highcharts.ColorString}
+     * @default    #e6e6e6
+     * @product    highstock
+     * @apioption  scrollbar.buttonBackgroundColor
      */
     buttonBackgroundColor: '#e6e6e6',
 
     /**
      * The color of the border of the scrollbar buttons.
      *
-     * @type {Color}
-     * @sample {highstock} stock/scrollbar/style/ Scrollbar styling
-     * @default #cccccc
-     * @product highstock
+     * @sample {highstock} stock/scrollbar/style/
+     *         Scrollbar styling
+     *
+     * @type       {Highcharts.ColorString}
+     * @default    #cccccc
+     * @product    highstock
+     * @apioption  scrollbar.buttonBorderColor
      */
     buttonBorderColor: '#cccccc',
 
     /**
      * The border width of the scrollbar buttons.
      *
-     * @type {Number}
-     * @sample {highstock} stock/scrollbar/style/ Scrollbar styling
-     * @default 1
-     * @product highstock
+     * @sample {highstock} stock/scrollbar/style/
+     *         Scrollbar styling
+     *
+     * @type       {number}
+     * @default    1
+     * @product    highstock
+     * @apioption  scrollbar.buttonBorderWidth
      */
     buttonBorderWidth: 1,
 
     /**
      * The color of the small rifles in the middle of the scrollbar.
      *
-     * @type {Color}
-     * @default #333333
-     * @product highstock
+     * @type       {Highcharts.ColorString}
+     * @default    #333333
+     * @product    highstock
+     * @apioption  scrollbar.rifleColor
      */
     rifleColor: '#333333',
 
     /**
      * The color of the track background.
      *
-     * @type {Color}
-     * @sample {highstock} stock/scrollbar/style/ Scrollbar styling
-     * @default #f2f2f2
-     * @product highstock
+     * @sample {highstock} stock/scrollbar/style/
+     *         Scrollbar styling
+     *
+     * @type       {Highcharts.ColorString}
+     * @default    #f2f2f2
+     * @product    highstock
+     * @apioption  scrollbar.trackBackgroundColor
      */
     trackBackgroundColor: '#f2f2f2',
 
     /**
      * The color of the border of the scrollbar track.
      *
-     * @type {Color}
-     * @sample {highstock} stock/scrollbar/style/ Scrollbar styling
-     * @default #f2f2f2
-     * @product highstock
+     * @sample {highstock} stock/scrollbar/style/
+     *         Scrollbar styling
+     *
+     * @type       {Highcharts.ColorString}
+     * @default    #f2f2f2
+     * @product    highstock
+     * @apioption  scrollbar.trackBorderColor
      */
     trackBorderColor: '#f2f2f2',
 
+    /**
+     * The corner radius of the border of the scrollbar track.
+     *
+     * @sample {highstock} stock/scrollbar/style/
+     *         Scrollbar styling
+     *
+     * @type       {number}
+     * @default    0
+     * @product    highstock
+     * @apioption  scrollbar.trackBorderRadius
+     */
+
     /**
      * The width of the border of the scrollbar track.
      *
-     * @type {Number}
-     * @sample {highstock} stock/scrollbar/style/ Scrollbar styling
-     * @default 1
-     * @product highstock
+     * @sample {highstock} stock/scrollbar/style/
+     *         Scrollbar styling
+     *
+     * @type       {number}
+     * @default    1
+     * @product    highstock
+     * @apioption  scrollbar.trackBorderWidth
      */
     trackBorderWidth: 1
     
@@ -230,11 +319,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,
@@ -255,10 +352,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);
@@ -266,6 +366,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 = [];
@@ -290,6 +401,10 @@ Scrollbar.prototype = {
 
     /**
     * Render scrollbar with all required items.
+    *
+    * @function Highcharts.Scrollbar#render
+    *
+    * @return {void}
     */
     render: function () {
         var scroller = this,
@@ -381,10 +496,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,
@@ -435,7 +562,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,
@@ -497,8 +630,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,
@@ -511,7 +652,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;
@@ -580,6 +725,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;
@@ -720,9 +872,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,
@@ -741,6 +898,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) {
@@ -759,6 +924,12 @@ Scrollbar.prototype = {
 
     /**
      * Update the scrollbar with new options
+     *
+     * @function Highcharts.Scrollbar#update
+     *
+     * @param  {Highcharts.ScrollbarOptions} options
+     *
+     * @return {void}
      */
     update: function (options) {
         this.destroy();
@@ -771,6 +942,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],
@@ -810,6 +985,10 @@ Scrollbar.prototype = {
 
     /**
      * Removes the event handlers attached previously with addEvents.
+     *
+     * @function Highcharts.Scrollbar#removeEvents
+     *
+     * @return {void}
      */
     removeEvents: function () {
         each(this._events, function (args) {
@@ -820,6 +999,10 @@ Scrollbar.prototype = {
 
     /**
      * Destroys allocated elements.
+     *
+     * @function Highcharts.Scrollbar#destroy
+     *
+     * @return {void}
      */
     destroy: function () {
 
@@ -855,14 +1038,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;
@@ -906,10 +1092,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),
@@ -927,8 +1113,6 @@ wrap(Axis.prototype, 'render', function (proceed) {
         from,
         to;
 
-    proceed.apply(axis, Array.prototype.slice.call(arguments, 1));
-
     if (scrollbar) {
 
         if (axis.horiz) {
@@ -987,16 +1171,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] +=
@@ -1004,15 +1186,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;