highcharts 6.1.1 → 6.2.0

package/es-modules/parts/Interaction.js

@@ -1,9 +1,11 @@
 /**
- * (c) 2010-2017 Torstein Honsi
+ * (c) 2010-2018 Torstein Honsi
  *
  * License: www.highcharts.com/license
  */
+
 'use strict';
+
 import H from './Globals.js';
 import './Utilities.js';
 import './Chart.js';
@@ -11,6 +13,7 @@ import './Options.js';
 import './Legend.js';
 import './Point.js';
 import './Series.js';
+
 var addEvent = H.addEvent,
     Chart = H.Chart,
     createElement = H.createElement,
@@ -34,11 +37,19 @@ var addEvent = H.addEvent,
 
 /**
  * TrackerMixin for points and graphs.
+ *
+ * @private
+ * @mixin Highcharts.TrackerMixin
  */
 TrackerMixin = H.TrackerMixin = {
 
     /**
      * Draw the tracker for a point.
+     *
+     * @private
+     * @function Highcharts.TrackerMixin.drawTrackerPoint
+     *
+     * @fires Highcharts.Series#event:afterDrawTracker
      */
     drawTrackerPoint: function () {
         var series = this,
@@ -101,6 +112,11 @@ TrackerMixin = H.TrackerMixin = {
      * track mouse events on the graph or points. For the line type charts
      * the tracker uses the same graphPath, but with a greater stroke width
      * for better control.
+     *
+     * @private
+     * @function Highcharts.TrackerMixin.drawTrackerGraph
+     *
+     * @fires Highcharts.Series#event:afterDrawTracker
      */
     drawTrackerGraph: function () {
         var series = this,
@@ -171,14 +187,21 @@ TrackerMixin = H.TrackerMixin = {
 
             series.tracker = renderer.path(trackerPath)
             .attr({
+                
                 'stroke-linejoin': 'round', // #1225
-                visibility: series.visible ? 'visible' : 'hidden',
                 stroke: TRACKER_FILL,
                 fill: trackByArea ? TRACKER_FILL : 'none',
                 'stroke-width': series.graph.strokeWidth() +
                     (trackByArea ? 0 : 2 * snap),
+                
+                visibility: series.visible ? 'visible' : 'hidden',
                 zIndex: 2
             })
+            .addClass(
+                trackByArea ?
+                    'highcharts-tracker-area' :
+                    'highcharts-tracker-line'
+            )
             .add(series.group);
 
             // The tracker is added to the series group, which is clipped, but
@@ -208,28 +231,62 @@ TrackerMixin = H.TrackerMixin = {
 /* End TrackerMixin */
 
 
-/**
+/*
  * Add tracking event listener to the series group, so the point graphics
  * themselves act as trackers
  */
 
 if (seriesTypes.column) {
+    /**
+     * @private
+     * @borrows Highcharts.TrackerMixin.drawTrackerPoint as Highcharts.seriesTypes.column#drawTracker
+     */
     seriesTypes.column.prototype.drawTracker = TrackerMixin.drawTrackerPoint;
 }
 
 if (seriesTypes.pie) {
+    /**
+     * @private
+     * @borrows Highcharts.TrackerMixin.drawTrackerPoint as Highcharts.seriesTypes.pie#drawTracker
+     */
     seriesTypes.pie.prototype.drawTracker = TrackerMixin.drawTrackerPoint;
 }
 
 if (seriesTypes.scatter) {
+    /**
+     * @private
+     * @borrows Highcharts.TrackerMixin.drawTrackerPoint as Highcharts.seriesTypes.scatter#drawTracker
+     */
     seriesTypes.scatter.prototype.drawTracker = TrackerMixin.drawTrackerPoint;
 }
 
-/*
- * Extend Legend for item events
+
+
+// Add pointer cursor to legend itemstyle in defaultOptions
+/**
+ * @default   'pointer'
+ * @apioption legend.itemStyle.cursor
  */
+defaultOptions.legend.itemStyle.cursor = 'pointer';
+
+
+
+// Extend Legend for item events.
 extend(Legend.prototype, {
 
+    /**
+     * @private
+     * @function Highcharts.Legend#setItemEvents
+     *
+     * @param {Highcharts.Point|Highcharts.Series} item
+     *
+     * @param {Highcharts.SVGElement} legendItem
+     *
+     * @param {boolean} [useHTML=false]
+     *
+     * @fires Highcharts.Point#event:legendItemClick
+     * @fires Highcharts.Series#event:legendItemClick
+     */
     setItemEvents: function (item, legendItem, useHTML) {
         var legend = this,
             boxWrapper = legend.chart.renderer.boxWrapper,
@@ -291,11 +348,20 @@ extend(Legend.prototype, {
         });
     },
 
+    /**
+     * @private
+     * @function Highcharts.Legend#createCheckboxForItem
+     *
+     * @param {Highcharts.Point|Highcharts.Series} item
+     *
+     * @fires Highcharts.Series#event:checkboxClick
+     */
     createCheckboxForItem: function (item) {
         var legend = this;
 
         item.checkbox = createElement('input', {
             type: 'checkbox',
+            className: 'highcharts-legend-checkbox',
             checked: item.selected,
             defaultChecked: item.selected // required by IE7
         }, legend.options.itemCheckboxStyle, legend.chart.container);
@@ -317,22 +383,16 @@ extend(Legend.prototype, {
     }
 });
 
-
-
-// Add pointer cursor to legend itemstyle in defaultOptions
-defaultOptions.legend.itemStyle.cursor = 'pointer';
-
-
-
-/*
- * Extend the Chart object with interaction
- */
-
+// Extend the Chart object with interaction.
 extend(Chart.prototype, /** @lends Chart.prototype */ {
+
     /**
      * Display the zoom button.
      *
      * @private
+     * @function Highcharts.Chart#showResetZoom
+     *
+     * @fires Highcharts.Chart#event:beforeShowResetZoom
      */
     showResetZoom: function () {
         var chart = this,
@@ -367,9 +427,12 @@ extend(Chart.prototype, /** @lends Chart.prototype */ {
     },
 
     /**
-     * Zoom out to 1:1.
+     * Zoom the chart out after a user has zoomed in. See also
+     * [Axis.setExtremes](/class-reference/Highcharts.Axis#setExtremes).
      *
-     * @private
+     * @function Highcharts.Chart#zoomOut
+     *
+     * @fires Highcharts.Chart#event:selection
      */
     zoomOut: function () {
         fireEvent(this, 'selection', { resetSelection: true }, this.zoom);
@@ -377,9 +440,11 @@ extend(Chart.prototype, /** @lends Chart.prototype */ {
 
     /**
      * Zoom into a given portion of the chart given by axis coordinates.
-     * @param {Object} event
      *
      * @private
+     * @function Highcharts.Chart#zoom
+     *
+     * @param {Highcharts.SelectEventObject} event
      */
     zoom: function (event) {
         var chart = this,
@@ -437,6 +502,11 @@ extend(Chart.prototype, /** @lends Chart.prototype */ {
      * compared to the first chartX position in the dragging operation.
      *
      * @private
+     * @function Highcharts.Chart#pan
+     *
+     * @param {Highcharts.PointerEventObject} e
+     *
+     * @param {string} panning
      */
     pan: function (e, panning) {
 
@@ -529,24 +599,13 @@ extend(Chart.prototype, /** @lends Chart.prototype */ {
     }
 });
 
-/*
- * Extend the Point object with interaction
- */
+// Extend the Point object with interaction
 extend(Point.prototype, /** @lends Highcharts.Point.prototype */ {
+
     /**
      * Toggle the selection status of a point.
-     * @param  {Boolean} [selected]
-     *         When `true`, the point is selected. When `false`, the point is
-     *         unselected. When `null` or `undefined`, the selection state is
-     *         toggled.
-     * @param  {Boolean} [accumulate=false]
-     *         When `true`, the selection is added to other selected points.
-     *         When `false`, other selected points are deselected. Internally in
-     *         Highcharts, when {@link http://api.highcharts.com/highcharts/plotOptions.series.allowPointSelect|allowPointSelect}
-     *         is `true`, selected points are accumulated on Control, Shift or
-     *         Cmd clicking the point.
      *
-     * @see    Highcharts.Chart#getSelectedPoints
+     * @see Highcharts.Chart#getSelectedPoints
      *
      * @sample highcharts/members/point-select/
      *         Select a point from a button
@@ -554,6 +613,24 @@ extend(Point.prototype, /** @lends Highcharts.Point.prototype */ {
      *         Select a range of points through a drag selection
      * @sample maps/series/data-id/
      *         Select a point in Highmaps
+     *
+     * @function Highcharts.Point#select
+     *
+     * @param {boolean} [selected]
+     *        When `true`, the point is selected. When `false`, the point is
+     *        unselected. When `null` or `undefined`, the selection state is
+     *        toggled.
+     *
+     * @param {boolean} [accumulate=false]
+     *        When `true`, the selection is added to other selected points.
+     *        When `false`, other selected points are deselected. Internally in
+     *        Highcharts, when
+     *        {@link http://api.highcharts.com/highcharts/plotOptions.series.allowPointSelect|allowPointSelect}
+     *        is `true`, selected points are accumulated on Control, Shift or
+     *        Cmd clicking the point.
+     *
+     * @fires Highcharts.Point#event:select
+     * @fires Highcharts.Point#event:unselect
      */
     select: function (selected, accumulate) {
         var point = this,
@@ -570,11 +647,12 @@ extend(Point.prototype, /** @lends Highcharts.Point.prototype */ {
 
                 /**
                  * Whether the point is selected or not.
+                 *
                  * @see Point#select
                  * @see Chart#getSelectedPoints
-                 * @memberof Point
-                 * @name selected
-                 * @type {Boolean}
+                 *
+                 * @name Highcharts.Point#selected
+                 * @type {boolean}
                  */
                 point.selected = point.options.selected = selected;
                 series.options.data[inArray(point, series.data)] =
@@ -604,7 +682,10 @@ extend(Point.prototype, /** @lends Highcharts.Point.prototype */ {
      * Runs on mouse over the point. Called internally from mouse and touch
      * events.
      *
-     * @param {Object} e The event arguments
+     * @function Highcharts.Point#onMouseOver
+     *
+     * @param {Highcharts.PointerEventObject} e
+     *        The event arguments.
      */
     onMouseOver: function (e) {
         var point = this,
@@ -621,6 +702,10 @@ extend(Point.prototype, /** @lends Highcharts.Point.prototype */ {
     /**
      * Runs on mouse out from the point. Called internally from mouse and touch
      * events.
+     *
+     * @function Highcharts.Point#onMouseOut
+     *
+     * @fires Highcharts.Point#event:mouseOut
      */
     onMouseOut: function () {
         var point = this,
@@ -637,6 +722,7 @@ extend(Point.prototype, /** @lends Highcharts.Point.prototype */ {
      * demand, to save processing time on hovering.
      *
      * @private
+     * @function Highcharts.Point#importEvents
      */
     importEvents: function () {
         if (!this.hasImportedEvents) {
@@ -656,9 +742,17 @@ extend(Point.prototype, /** @lends Highcharts.Point.prototype */ {
 
     /**
      * Set the point's state.
-     * @param  {String} [state]
-     *         The new state, can be one of `''` (an empty string), `hover` or
-     *         `select`.
+     *
+     * @function Highcharts.Point#setState
+     *
+     * @param {string} [state]
+     *        The new state, can be one of `''` (an empty string), `hover` or
+     *        `select`.
+     *
+     * @param {boolean} [move]
+     *        State for animation.
+     *
+     * @fires Highcharts.Point#event:afterSetState
      */
     setState: function (state, move) {
         var point = this,
@@ -852,9 +946,14 @@ extend(Point.prototype, /** @lends Highcharts.Point.prototype */ {
     /**
      * Get the path definition for the halo, which is usually a shadow-like
      * circle around the currently hovered point.
-     * @param  {Number} size
-     *         The radius of the circular halo.
-     * @return {Array} The path definition
+     *
+     * @function Highcharts.Point#haloPath
+     *
+     * @param {number} size
+     *        The radius of the circular halo.
+     *
+     * @return {Highcharts.SVGPathArray}
+     *         The path definition.
      */
     haloPath: function (size) {
         var series = this.series,
@@ -869,13 +968,15 @@ extend(Point.prototype, /** @lends Highcharts.Point.prototype */ {
     }
 });
 
-/*
- * Extend the Series object with interaction
- */
-
+// Extend the Series object with interaction
 extend(Series.prototype, /** @lends Highcharts.Series.prototype */ {
+
     /**
      * Runs on mouse over the series graphical items.
+     *
+     * @function Highcharts.Series#onMouseOver
+     *
+     * @fires Highcharts.Series#event:mouseOver
      */
     onMouseOver: function () {
         var series = this,
@@ -900,6 +1001,10 @@ extend(Series.prototype, /** @lends Highcharts.Series.prototype */ {
 
     /**
      * Runs on mouse out of the series graphical items.
+     *
+     * @function Highcharts.Series#onMouseOut
+     *
+     * @fires Highcharts.Series#event:mouseOut
      */
     onMouseOut: function () {
         // trigger the event only if listeners exist
@@ -941,9 +1046,10 @@ extend(Series.prototype, /** @lends Highcharts.Series.prototype */ {
      * operations, but it can also be called directly to visually
      * highlight a series.
      *
-     * @param  {String} [state]
-     *         Can be either `hover` or undefined to set to normal
-     *         state.
+     * @function Highcharts.Series#setState
+     *
+     * @param {string} [state]
+     *        Can be either `hover` or undefined to set to normal state.
      */
     setState: function (state) {
         var series = this,
@@ -1013,20 +1119,28 @@ extend(Series.prototype, /** @lends Highcharts.Series.prototype */ {
                     i = i + 1;
                 }
             }
+
             
+
         }
     },
 
     /**
      * Show or hide the series.
      *
-     * @param  {Boolean} [visible]
-     *         True to show the series, false to hide. If undefined, the
-     *         visibility is toggled.
-     * @param  {Boolean} [redraw=true]
-     *         Whether to redraw the chart after the series is altered. If doing
-     *         more operations on the chart, it is a good idea to set redraw to
-     *         false and call {@link Chart#redraw|chart.redraw()} after.
+     * @function Highcharts.Series#setVisible
+     *
+     * @param {boolean} [visible]
+     *        True to show the series, false to hide. If undefined, the
+     *        visibility is toggled.
+     *
+     * @param {boolean} [redraw=true]
+     *        Whether to redraw the chart after the series is altered. If doing
+     *        more operations on the chart, it is a good idea to set redraw to
+     *        false and call {@link Chart#redraw|chart.redraw()} after.
+     *
+     * @fires Highcharts.Series#event:hide
+     * @fires Highcharts.Series#event:show
      */
     setVisible: function (vis, redraw) {
         var series = this,
@@ -1104,6 +1218,10 @@ extend(Series.prototype, /** @lends Highcharts.Series.prototype */ {
      *
      * @sample highcharts/members/series-hide/
      *         Toggle visibility from a button
+     *
+     * @function Highcharts.Series#show
+     *
+     * @fires Highcharts.Series#event:show
      */
     show: function () {
         this.setVisible(true);
@@ -1117,6 +1235,10 @@ extend(Series.prototype, /** @lends Highcharts.Series.prototype */ {
      *
      * @sample highcharts/members/series-hide/
      *         Toggle visibility from a button
+     *
+     * @function Highcharts.Series#hide
+     *
+     * @fires Highcharts.Series#event:hide
      */
     hide: function () {
         this.setVisible(false);
@@ -1124,17 +1246,24 @@ extend(Series.prototype, /** @lends Highcharts.Series.prototype */ {
 
 
     /**
-     * Select or unselect the series. This means its {@link
-     * Highcharts.Series.selected|selected} property is set, the checkbox in the
-     * legend is toggled and when selected, the series is returned by the
-     * {@link Highcharts.Chart#getSelectedSeries} function.
-     *
-     * @param  {Boolean} [selected]
-     *         True to select the series, false to unselect. If undefined, the
-     *         selection state is toggled.
+     * Select or unselect the series. This means its
+     * {@link Highcharts.Series.selected|selected}
+     * property is set, the checkbox in the legend is toggled and when selected,
+     * the series is returned by the
+     * {@link Highcharts.Chart#getSelectedSeries}
+     * function.
      *
      * @sample highcharts/members/series-select/
      *         Select a series from a button
+     *
+     * @function Highcharts.Series#select
+     *
+     * @param {boolean} [selected]
+     *        True to select the series, false to unselect. If undefined, the
+     *        selection state is toggled.
+     *
+     * @fires Highcharts.Series#event:select
+     * @fires Highcharts.Series#event:unselect
      */
     select: function (selected) {
         var series = this;
@@ -1150,5 +1279,9 @@ extend(Series.prototype, /** @lends Highcharts.Series.prototype */ {
         fireEvent(series, selected ? 'select' : 'unselect');
     },
 
+    /**
+     * @private
+     * @borrows Highcharts.TrackerMixin.drawTrackerGraph as Highcharts.Series#drawTracker
+     */
     drawTracker: TrackerMixin.drawTrackerGraph
 });