Upgrade to ExtJS 3.1.0 - Released 12/16/2009
[extjs.git] / docs / source / Chart.html
index ec59f43..e3881a5 100644 (file)
@@ -1,5 +1,6 @@
 <html>\r
 <head>\r
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
   <title>The source code</title>\r
     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
  * @extends Ext.FlashComponent\r
  * The Ext.chart package provides the capability to visualize data with flash based charting.\r
  * Each chart binds directly to an Ext.data.Store enabling automatic updates of the chart.\r
+ * To change the look and feel of a chart, see the {@link #chartStyle} and {@link #extraStyle} config options.\r
  * @constructor\r
  * @xtype chart\r
  */\r
  \r
  Ext.chart.Chart = Ext.extend(Ext.FlashComponent, {\r
     refreshBuffer: 100,\r
+    \r
+    <div id="cfg-Ext.chart.Chart-backgroundColor"></div>/**\r
+     * @cfg {String} backgroundColor\r
+     * @hide\r
+     */\r
 \r
     <div id="cfg-Ext.chart.Chart-chartStyle"></div>/**\r
      * @cfg {Object} chartStyle\r
-     * Sets styles for this chart. Contains a number of default values. Modifying this property will override\r
-     * the base styles on the chart.\r
+     * Sets styles for this chart. This contains default styling, so modifying this property will <b>override</b>\r
+     * the built in styles of the chart. Use {@link #extraStyle} to add customizations to the default styling. \r
      */\r
     chartStyle: {\r
         padding: 10,\r
     <div id="cfg-Ext.chart.Chart-extraStyle"></div>/**\r
      * @cfg {Object} extraStyle\r
      * Contains extra styles that will be added or overwritten to the default chartStyle. Defaults to <tt>null</tt>.\r
+     * For a detailed list of the options available, visit the YUI Charts site \r
+     * at <a href="http://developer.yahoo.com/yui/charts/#basicstyles">http://developer.yahoo.com/yui/charts/#basicstyles</a><br/>\r
+     * Some of the options availabe:<br />\r
+     * <ul style="padding:5px;padding-left:16px;list-style-type:inherit;">\r
+     * <li><b>padding</b> - The space around the edge of the chart's contents. Padding does not increase the size of the chart.</li>\r
+     * <li><b>animationEnabled</b> - A Boolean value that specifies whether marker animations are enabled or not. Enabled by default.</li>\r
+     * <li><b>font</b> - An Object defining the font style to be used in the chart. Defaults to <tt>{ name: 'Tahoma', color: 0x444444, size: 11 }</tt><br/>\r
+     *  <ul style="padding:5px;padding-left:26px;list-style-type:circle;">\r
+     *      <li><b>name</b> - font name</li>\r
+     *      <li><b>color</b> - font color (hex code, ie: "#ff0000", "ff0000" or 0xff0000)</li>\r
+     *      <li><b>size</b> - font size in points (numeric portion only, ie: 11)</li>\r
+     *      <li><b>bold</b> - boolean</li>\r
+     *      <li><b>italic</b> - boolean</li>\r
+     *      <li><b>underline</b> - boolean</li>\r
+     *  </ul>\r
+     * </li>\r
+     * <li><b>border</b> - An object defining the border style around the chart. The chart itself will decrease in dimensions to accomodate the border.<br/>\r
+     *  <ul style="padding:5px;padding-left:26px;list-style-type:circle;">\r
+     *      <li><b>color</b> - border color (hex code, ie: "#ff0000", "ff0000" or 0xff0000)</li>\r
+     *      <li><b>size</b> - border size in pixels (numeric portion only, ie: 1)</li>\r
+     *  </ul>\r
+     * </li>\r
+     * <li><b>background</b> - An object defining the background style of the chart.<br/>\r
+     *  <ul style="padding:5px;padding-left:26px;list-style-type:circle;">\r
+     *      <li><b>color</b> - border color (hex code, ie: "#ff0000", "ff0000" or 0xff0000)</li>\r
+     *      <li><b>image</b> - an image URL. May be relative to the current document or absolute.</li>\r
+     *  </ul>\r
+     * </li>\r
+     * <li><b>legend</b> - An object defining the legend style<br/>\r
+     *  <ul style="padding:5px;padding-left:26px;list-style-type:circle;">\r
+     *      <li><b>display</b> - location of the legend. Possible values are "none", "left", "right", "top", and "bottom".</li>\r
+     *      <li><b>spacing</b> - an image URL. May be relative to the current document or absolute.</li>\r
+     *      <li><b>padding, border, background, font</b> - same options as described above.</li>\r
+     *  </ul></li>\r
+     * <li><b>dataTip</b> - An object defining the style of the data tip (tooltip).<br/>\r
+     *  <ul style="padding:5px;padding-left:26px;list-style-type:circle;">\r
+     *      <li><b>padding, border, background, font</b> - same options as described above.</li>\r
+     *  </ul></li>\r
+     * <li><b>xAxis and yAxis</b> - An object defining the style of the style of either axis.<br/>\r
+     *  <ul style="padding:5px;padding-left:26px;list-style-type:circle;">\r
+     *      <li><b>color</b> - same option as described above.</li>\r
+     *      <li><b>size</b> - same option as described above.</li>\r
+     *      <li><b>showLabels</b> - boolean</li>\r
+     *      <li><b>labelRotation</b> - a value in degrees from -90 through 90. Default is zero.</li>\r
+     *  </ul></li>\r
+     * <li><b>majorGridLines and minorGridLines</b> - An object defining the style of the style of the grid lines.<br/>\r
+     *  <ul style="padding:5px;padding-left:26px;list-style-type:circle;">\r
+     *      <li><b>color, size</b> - same options as described above.</li>\r
+     *  </ul></li></li>\r
+     * <li><b>zeroGridLine</b> - An object defining the style of the style of the zero grid line.<br/>\r
+     *  <ul style="padding:5px;padding-left:26px;list-style-type:circle;">\r
+     *      <li><b>color, size</b> - same options as described above.</li>\r
+     *  </ul></li></li>\r
+     * <li><b>majorTicks and minorTicks</b> - An object defining the style of the style of ticks in the chart.<br/>\r
+     *  <ul style="padding:5px;padding-left:26px;list-style-type:circle;">\r
+     *      <li><b>color, size</b> - same options as described above.</li>\r
+     *      <li><b>length</b> - the length of each tick in pixels extending from the axis.</li>\r
+     *      <li><b>display</b> - how the ticks are drawn. Possible values are "none", "inside", "outside", and "cross".</li>\r
+     *  </ul></li></li>\r
+     * </ul>\r
      */\r
     extraStyle: null,\r
     \r
+    <div id="cfg-Ext.chart.Chart-seriesStyles"></div>/**\r
+     * @cfg {Object} seriesStyles\r
+     * Contains styles to apply to the series after a refresh. Defaults to <tt>null</tt>.\r
+     */\r
+    seriesStyles: null,\r
+    \r
     <div id="cfg-Ext.chart.Chart-disableCaching"></div>/**\r
      * @cfg {Boolean} disableCaching\r
      * True to add a "cache buster" to the end of the chart url. Defaults to true for Opera and IE.\r
             'itemdoubleclick',\r
             'itemdragstart',\r
             'itemdrag',\r
-            'itemdragend'\r
+            'itemdragend',\r
+            <div id="event-Ext.chart.Chart-beforerefresh"></div>/**\r
+             * @event beforerefresh\r
+             * Fires before a refresh to the chart data is called.  If the beforerefresh handler returns\r
+             * <tt>false</tt> the {@link #refresh} action will be cancelled.\r
+             * @param {Chart} this\r
+             */\r
+            'beforerefresh',\r
+            <div id="event-Ext.chart.Chart-refresh"></div>/**\r
+             * @event refresh\r
+             * Fires after the chart data has been refreshed.\r
+             * @param {Chart} this\r
+             */\r
+            'refresh'\r
         );\r
         this.store = Ext.StoreMgr.lookup(this.store);\r
     },\r
      * @param styles {Array} Initializer for all Chart series styles.\r
      */\r
     setSeriesStyles: function(styles){\r
+        this.seriesStyles = styles;\r
         var s = [];\r
         Ext.each(styles, function(style){\r
             s.push(Ext.encode(style));\r
      */\r
     bindStore : function(store, initial){\r
         if(!initial && this.store){\r
-            this.store.un("datachanged", this.refresh, this);\r
-            this.store.un("add", this.delayRefresh, this);\r
-            this.store.un("remove", this.delayRefresh, this);\r
-            this.store.un("update", this.delayRefresh, this);\r
-            this.store.un("clear", this.refresh, this);\r
             if(store !== this.store && this.store.autoDestroy){\r
                 this.store.destroy();\r
+            }else{\r
+                this.store.un("datachanged", this.refresh, this);\r
+                this.store.un("add", this.delayRefresh, this);\r
+                this.store.un("remove", this.delayRefresh, this);\r
+                this.store.un("update", this.delayRefresh, this);\r
+                this.store.un("clear", this.refresh, this);\r
             }\r
         }\r
         if(store){\r
         this.swf.setType(this.type);\r
 \r
         if(this.chartStyle){\r
-            this.setStyles(Ext.apply(this.extraStyle || {}, this.chartStyle));\r
+            this.setStyles(Ext.apply({}, this.extraStyle, this.chartStyle));\r
         }\r
 \r
         if(this.categoryNames){\r
     },\r
 \r
     refresh : function(){\r
-        var styleChanged = false;\r
-        // convert the store data into something YUI charts can understand\r
-        var data = [], rs = this.store.data.items;\r
-        for(var j = 0, len = rs.length; j < len; j++){\r
-            data[j] = rs[j].data;\r
-        }\r
-        //make a copy of the series definitions so that we aren't\r
-        //editing them directly.\r
-        var dataProvider = [];\r
-        var seriesCount = 0;\r
-        var currentSeries = null;\r
-        var i = 0;\r
-        if(this.series){\r
-            seriesCount = this.series.length;\r
-            for(i = 0; i < seriesCount; i++){\r
-                currentSeries = this.series[i];\r
-                var clonedSeries = {};\r
-                for(var prop in currentSeries){\r
-                    if(prop == "style" && currentSeries.style !== null){\r
-                        clonedSeries.style = Ext.encode(currentSeries.style);\r
-                        styleChanged = true;\r
-                        //we don't want to modify the styles again next time\r
-                        //so null out the style property.\r
-                        // this causes issues\r
-                        // currentSeries.style = null;\r
-                    } else{\r
-                        clonedSeries[prop] = currentSeries[prop];\r
-                    }\r
-                }\r
-                dataProvider.push(clonedSeries);\r
-            }\r
+        if(this.fireEvent('beforerefresh', this) !== false){\r
+               var styleChanged = false;\r
+               // convert the store data into something YUI charts can understand\r
+               var data = [], rs = this.store.data.items;\r
+               for(var j = 0, len = rs.length; j < len; j++){\r
+                   data[j] = rs[j].data;\r
+               }\r
+               //make a copy of the series definitions so that we aren't\r
+               //editing them directly.\r
+               var dataProvider = [];\r
+               var seriesCount = 0;\r
+               var currentSeries = null;\r
+               var i = 0;\r
+               if(this.series){\r
+                   seriesCount = this.series.length;\r
+                   for(i = 0; i < seriesCount; i++){\r
+                       currentSeries = this.series[i];\r
+                       var clonedSeries = {};\r
+                       for(var prop in currentSeries){\r
+                           if(prop == "style" && currentSeries.style !== null){\r
+                               clonedSeries.style = Ext.encode(currentSeries.style);\r
+                               styleChanged = true;\r
+                               //we don't want to modify the styles again next time\r
+                               //so null out the style property.\r
+                               // this causes issues\r
+                               // currentSeries.style = null;\r
+                           } else{\r
+                               clonedSeries[prop] = currentSeries[prop];\r
+                           }\r
+                       }\r
+                       dataProvider.push(clonedSeries);\r
+                   }\r
+               }\r
+       \r
+               if(seriesCount > 0){\r
+                   for(i = 0; i < seriesCount; i++){\r
+                       currentSeries = dataProvider[i];\r
+                       if(!currentSeries.type){\r
+                           currentSeries.type = this.type;\r
+                       }\r
+                       currentSeries.dataProvider = data;\r
+                   }\r
+               } else{\r
+                   dataProvider.push({type: this.type, dataProvider: data});\r
+               }\r
+               this.swf.setDataProvider(dataProvider);\r
+               if(this.seriesStyles){\r
+                   this.setSeriesStyles(this.seriesStyles);\r
+               }\r
+            this.fireEvent('refresh', this);\r
         }\r
-\r
-        if(seriesCount > 0){\r
-            for(i = 0; i < seriesCount; i++){\r
-                currentSeries = dataProvider[i];\r
-                if(!currentSeries.type){\r
-                    currentSeries.type = this.type;\r
-                }\r
-                currentSeries.dataProvider = data;\r
-            }\r
-        } else{\r
-            dataProvider.push({type: this.type, dataProvider: data});\r
-        }\r
-        this.swf.setDataProvider(dataProvider);\r
     },\r
 \r
     createFnProxy : function(fn, old){\r
     \r
     onDestroy: function(){\r
         Ext.chart.Chart.superclass.onDestroy.call(this);\r
-        delete window[this.tipFnName];\r
+        this.bindStore(null);\r
+        var tip = this.tipFnName;\r
+        if(!Ext.isEmpty(tip)){\r
+            delete window[tip];\r
+        }\r
     }\r
 });\r
 Ext.reg('chart', Ext.chart.Chart);\r