src/chart/series/Series.js

   1 /**
   2  * @class Ext.chart.series.Series
   3  *
   4  * Series is the abstract class containing the common logic to all chart series. Series includes
   5  * methods from Labels, Highlights, Tips and Callouts mixins. This class implements the logic of handling
   6  * mouse events, animating, hiding, showing all elements and returning the color of the series to be used as a legend item.
   7  *
   8  * ## Listeners
   9  *
  10  * The series class supports listeners via the Observable syntax. Some of these listeners are:
  11  *
  12  *  - `itemmouseup` When the user interacts with a marker.
  13  *  - `itemmousedown` When the user interacts with a marker.
  14  *  - `itemmousemove` When the user iteracts with a marker.
  15  *  - `afterrender` Will be triggered when the animation ends or when the series has been rendered completely.
  16  *
  17  * For example:
  18  *
  19  *     series: [{
  20  *             type: 'column',
  21  *             axis: 'left',
  22  *             listeners: {
  23  *                     'afterrender': function() {
  24  *                             console('afterrender');
  25  *                     }
  26  *             },
  27  *             xField: 'category',
  28  *             yField: 'data1'
  29  *     }]
  30  *
  31  */
  32 Ext.define('Ext.chart.series.Series', {
  33
  34     /* Begin Definitions */
  35
  36     mixins: {
  37         observable: 'Ext.util.Observable',
  38         labels: 'Ext.chart.Label',
  39         highlights: 'Ext.chart.Highlight',
  40         tips: 'Ext.chart.Tip',
  41         callouts: 'Ext.chart.Callout'
  42     },
  43
  44     /* End Definitions */
  45
  46     /**
  47      * @cfg {Boolean|Object} highlight
  48      * If set to `true` it will highlight the markers or the series when hovering
  49      * with the mouse. This parameter can also be an object with the same style
  50      * properties you would apply to a {@link Ext.draw.Sprite} to apply custom
  51      * styles to markers and series.
  52      */
  53
  54     /**
  55      * @cfg {Object} tips
  56      * Add tooltips to the visualization's markers. The options for the tips are the
  57      * same configuration used with {@link Ext.tip.ToolTip}. For example:
  58      *
  59      *     tips: {
  60      *       trackMouse: true,
  61      *       width: 140,
  62      *       height: 28,
  63      *       renderer: function(storeItem, item) {
  64      *         this.setTitle(storeItem.get('name') + ': ' + storeItem.get('data1') + ' views');
  65      *       }
  66      *     },
  67      */
  68
  69     /**
  70      * @cfg {String} type
  71      * The type of series. Set in subclasses.
  72      */
  73     type: null,
  74
  75     /**
  76      * @cfg {String} title
  77      * The human-readable name of the series.
  78      */
  79     title: null,
  80
  81     /**
  82      * @cfg {Boolean} showInLegend
  83      * Whether to show this series in the legend.
  84      */
  85     showInLegend: true,
  86
  87     /**
  88      * @cfg {Function} renderer
  89      * A function that can be overridden to set custom styling properties to each rendered element.
  90      * Passes in (sprite, record, attributes, index, store) to the function.
  91      */
  92     renderer: function(sprite, record, attributes, index, store) {
  93         return attributes;
  94     },
  95
  96     /**
  97      * @cfg {Array} shadowAttributes
  98      * An array with shadow attributes
  99      */
 100     shadowAttributes: null,
 101
 102     //@private triggerdrawlistener flag
 103     triggerAfterDraw: false,
 104
 105     /**
 106      * @cfg {Object} listeners
 107      * An (optional) object with event callbacks. All event callbacks get the target *item* as first parameter. The callback functions are:
 108      *
 109      *  <ul>
 110      *      <li>itemmouseover</li>
 111      *      <li>itemmouseout</li>
 112      *      <li>itemmousedown</li>
 113      *      <li>itemmouseup</li>
 114      *  </ul>
 115      */
 116
 117     constructor: function(config) {
 118         var me = this;
 119         if (config) {
 120             Ext.apply(me, config);
 121         }
 122
 123         me.shadowGroups = [];
 124
 125         me.mixins.labels.constructor.call(me, config);
 126         me.mixins.highlights.constructor.call(me, config);
 127         me.mixins.tips.constructor.call(me, config);
 128         me.mixins.callouts.constructor.call(me, config);
 129
 130         me.addEvents({
 131             scope: me,
 132             itemmouseover: true,
 133             itemmouseout: true,
 134             itemmousedown: true,
 135             itemmouseup: true,
 136             mouseleave: true,
 137             afterdraw: true,
 138
 139             /**
 140              * @event titlechange
 141              * Fires when the series title is changed via {@link #setTitle}.
 142              * @param {String} title The new title value
 143              * @param {Number} index The index in the collection of titles
 144              */
 145             titlechange: true
 146         });
 147
 148         me.mixins.observable.constructor.call(me, config);
 149
 150         me.on({
 151             scope: me,
 152             itemmouseover: me.onItemMouseOver,
 153             itemmouseout: me.onItemMouseOut,
 154             mouseleave: me.onMouseLeave
 155         });
 156     },
 157
 158     // @private set the bbox and clipBox for the series
 159     setBBox: function(noGutter) {
 160         var me = this,
 161             chart = me.chart,
 162             chartBBox = chart.chartBBox,
 163             gutterX = noGutter ? 0 : chart.maxGutter[0],
 164             gutterY = noGutter ? 0 : chart.maxGutter[1],
 165             clipBox, bbox;
 166
 167         clipBox = {
 168             x: chartBBox.x,
 169             y: chartBBox.y,
 170             width: chartBBox.width,
 171             height: chartBBox.height
 172         };
 173         me.clipBox = clipBox;
 174
 175         bbox = {
 176             x: (clipBox.x + gutterX) - (chart.zoom.x * chart.zoom.width),
 177             y: (clipBox.y + gutterY) - (chart.zoom.y * chart.zoom.height),
 178             width: (clipBox.width - (gutterX * 2)) * chart.zoom.width,
 179             height: (clipBox.height - (gutterY * 2)) * chart.zoom.height
 180         };
 181         me.bbox = bbox;
 182     },
 183
 184     // @private set the animation for the sprite
 185     onAnimate: function(sprite, attr) {
 186         var me = this;
 187         sprite.stopAnimation();
 188         if (me.triggerAfterDraw) {
 189             return sprite.animate(Ext.applyIf(attr, me.chart.animate));
 190         } else {
 191             me.triggerAfterDraw = true;
 192             return sprite.animate(Ext.apply(Ext.applyIf(attr, me.chart.animate), {
 193                 listeners: {
 194                     'afteranimate': function() {
 195                         me.triggerAfterDraw = false;
 196                         me.fireEvent('afterrender');
 197                     }
 198                 }
 199             }));
 200         }
 201     },
 202
 203     // @private return the gutter.
 204     getGutters: function() {
 205         return [0, 0];
 206     },
 207
 208     // @private wrapper for the itemmouseover event.
 209     onItemMouseOver: function(item) {
 210         var me = this;
 211         if (item.series === me) {
 212             if (me.highlight) {
 213                 me.highlightItem(item);
 214             }
 215             if (me.tooltip) {
 216                 me.showTip(item);
 217             }
 218         }
 219     },
 220
 221     // @private wrapper for the itemmouseout event.
 222     onItemMouseOut: function(item) {
 223         var me = this;
 224         if (item.series === me) {
 225             me.unHighlightItem();
 226             if (me.tooltip) {
 227                 me.hideTip(item);
 228             }
 229         }
 230     },
 231
 232     // @private wrapper for the mouseleave event.
 233     onMouseLeave: function() {
 234         var me = this;
 235         me.unHighlightItem();
 236         if (me.tooltip) {
 237             me.hideTip();
 238         }
 239     },
 240
 241     /**
 242      * For a given x/y point relative to the Surface, find a corresponding item from this
 243      * series, if any.
 244      * @param {Number} x
 245      * @param {Number} y
 246      * @return {Object} An object describing the item, or null if there is no matching item. The exact contents of
 247      *                  this object will vary by series type, but should always contain at least the following:
 248      *                  <ul>
 249      *                    <li>{Ext.chart.series.Series} series - the Series object to which the item belongs</li>
 250      *                    <li>{Object} value - the value(s) of the item's data point</li>
 251      *                    <li>{Array} point - the x/y coordinates relative to the chart box of a single point
 252      *                        for this data item, which can be used as e.g. a tooltip anchor point.</li>
 253      *                    <li>{Ext.draw.Sprite} sprite - the item's rendering Sprite.
 254      *                  </ul>
 255      */
 256     getItemForPoint: function(x, y) {
 257         //if there are no items to query just return null.
 258         if (!this.items || !this.items.length || this.seriesIsHidden) {
 259             return null;
 260         }
 261         var me = this,
 262             items = me.items,
 263             bbox = me.bbox,
 264             item, i, ln;
 265         // Check bounds
 266         if (!Ext.draw.Draw.withinBox(x, y, bbox)) {
 267             return null;
 268         }
 269         for (i = 0, ln = items.length; i < ln; i++) {
 270             if (items[i] && this.isItemInPoint(x, y, items[i], i)) {
 271                 return items[i];
 272             }
 273         }
 274
 275         return null;
 276     },
 277
 278     isItemInPoint: function(x, y, item, i) {
 279         return false;
 280     },
 281
 282     /**
 283      * Hides all the elements in the series.
 284      */
 285     hideAll: function() {
 286         var me = this,
 287             items = me.items,
 288             item, len, i, sprite;
 289
 290         me.seriesIsHidden = true;
 291         me._prevShowMarkers = me.showMarkers;
 292
 293         me.showMarkers = false;
 294         //hide all labels
 295         me.hideLabels(0);
 296         //hide all sprites
 297         for (i = 0, len = items.length; i < len; i++) {
 298             item = items[i];
 299             sprite = item.sprite;
 300             if (sprite) {
 301                 sprite.setAttributes({
 302                     hidden: true
 303                 }, true);
 304             }
 305         }
 306     },
 307
 308     /**
 309      * Shows all the elements in the series.
 310      */
 311     showAll: function() {
 312         var me = this,
 313             prevAnimate = me.chart.animate;
 314         me.chart.animate = false;
 315         me.seriesIsHidden = false;
 316         me.showMarkers = me._prevShowMarkers;
 317         me.drawSeries();
 318         me.chart.animate = prevAnimate;
 319     },
 320
 321     /**
 322      * Returns a string with the color to be used for the series legend item.
 323      */
 324     getLegendColor: function(index) {
 325         var me = this, fill, stroke;
 326         if (me.seriesStyle) {
 327             fill = me.seriesStyle.fill;
 328             stroke = me.seriesStyle.stroke;
 329             if (fill && fill != 'none') {
 330                 return fill;
 331             }
 332             return stroke;
 333         }
 334         return '#000';
 335     },
 336
 337     /**
 338      * Checks whether the data field should be visible in the legend
 339      * @private
 340      * @param {Number} index The index of the current item
 341      */
 342     visibleInLegend: function(index){
 343         var excludes = this.__excludes;
 344         if (excludes) {
 345             return !excludes[index];
 346         }
 347         return !this.seriesIsHidden;
 348     },
 349
 350     /**
 351      * Changes the value of the {@link #title} for the series.
 352      * Arguments can take two forms:
 353      * <ul>
 354      * <li>A single String value: this will be used as the new single title for the series (applies
 355      * to series with only one yField)</li>
 356      * <li>A numeric index and a String value: this will set the title for a single indexed yField.</li>
 357      * </ul>
 358      * @param {Number} index
 359      * @param {String} title
 360      */
 361     setTitle: function(index, title) {
 362         var me = this,
 363             oldTitle = me.title;
 364
 365         if (Ext.isString(index)) {
 366             title = index;
 367             index = 0;
 368         }
 369
 370         if (Ext.isArray(oldTitle)) {
 371             oldTitle[index] = title;
 372         } else {
 373             me.title = title;
 374         }
 375
 376         me.fireEvent('titlechange', title, index);
 377     }
 378 });