client-freqwatch/Chart.js/docs/05-Pie-Doughnut-Chart.md

   1 ---
   2 title: Pie & Doughnut Charts
   3 anchor: doughnut-pie-chart
   4 ---
   5 ###Introduction
   6 Pie and doughnut charts are probably the most commonly used chart there are. They are divided into segments, the arc of each segment shows the proportional value of each piece of data.
   7
   8 They are excellent at showing the relational proportions between data.
   9
  10 Pie and doughnut charts are effectively the same class in Chart.js, but have one different default value - their `percentageInnerCutout`. This equates what percentage of the inner should be cut out. This defaults to `0` for pie charts, and `50` for doughnuts.
  11
  12 They are also registered under two aliases in the `Chart` core. Other than their different default value, and different alias, they are exactly the same.
  13
  14 <div class="canvas-holder half">
  15         <canvas width="250" height="125"></canvas>
  16 </div>
  17
  18 <div class="canvas-holder half">
  19         <canvas width="250" height="125"></canvas>
  20 </div>
  21
  22
  23 ### Example usage
  24
  25 ```javascript
  26 // For a pie chart
  27 var myPieChart = new Chart(ctx[0]).Pie(data,options);
  28
  29 // And for a doughnut chart
  30 var myDoughnutChart = new Chart(ctx[1]).Doughnut(data,options);
  31 ```
  32
  33 ### Data structure
  34
  35 ```javascript
  36 var data = [
  37         {
  38                 value: 300,
  39                 color:"#F7464A",
  40                 highlight: "#FF5A5E",
  41                 label: "Red"
  42         },
  43         {
  44                 value: 50,
  45                 color: "#46BFBD",
  46                 highlight: "#5AD3D1",
  47                 label: "Green"
  48         },
  49         {
  50                 value: 100,
  51                 color: "#FDB45C",
  52                 highlight: "#FFC870",
  53                 label: "Yellow"
  54         }
  55 ]
  56 ```
  57
  58 For a pie chart, you must pass in an array of objects with a value and an optional color property. The value attribute should be a number, Chart.js will total all of the numbers and calculate the relative proportion of each. The color attribute should be a string. Similar to CSS, for this string you can use HEX notation, RGB, RGBA or HSL.
  59
  60 ### Chart options
  61
  62 These are the customisation options specific to Pie & Doughnut charts. These options are merged with the [global chart configuration options](#getting-started-global-chart-configuration), and form the options of the chart.
  63
  64 ```javascript
  65 {
  66         //Boolean - Whether we should show a stroke on each segment
  67         segmentShowStroke : true,
  68
  69         //String - The colour of each segment stroke
  70         segmentStrokeColor : "#fff",
  71
  72         //Number - The width of each segment stroke
  73         segmentStrokeWidth : 2,
  74
  75         //Number - The percentage of the chart that we cut out of the middle
  76         percentageInnerCutout : 50, // This is 0 for Pie charts
  77
  78         //Number - Amount of animation steps
  79         animationSteps : 100,
  80
  81         //String - Animation easing effect
  82         animationEasing : "easeOutBounce",
  83
  84         //Boolean - Whether we animate the rotation of the Doughnut
  85         animateRotate : true,
  86
  87         //Boolean - Whether we animate scaling the Doughnut from the centre
  88         animateScale : false,
  89         {% raw %}
  90         //String - A legend template
  91         legendTemplate : "<ul class=\"<%=name.toLowerCase()%>-legend\"><% for (var i=0; i<segments.length; i++){%><li><span style=\"background-color:<%=segments[i].fillColor%>\"></span><%if(segments[i].label){%><%=segments[i].label%><%}%></li><%}%></ul>"
  92         {% endraw %}
  93 }
  94 ```
  95 You can override these for your `Chart` instance by passing a second argument into the `Doughnut` method as an object with the keys you want to override.
  96
  97 For example, we could have a doughnut chart that animates by scaling out from the centre like so:
  98
  99 ```javascript
 100 new Chart(ctx).Doughnut(data, {
 101         animateScale: true
 102 });
 103 // This will create a chart with all of the default options, merged from the global config,
 104 // and the Doughnut chart defaults but this particular instance will have `animateScale` set to `true`.
 105 ```
 106
 107 We can also change these default values for each Doughnut type that is created, this object is available at `Chart.defaults.Doughnut`. Pie charts also have a clone of these defaults available to change at `Chart.defaults.Pie`, with the only difference being `percentageInnerCutout` being set to 0.
 108
 109 ### Prototype methods
 110
 111 #### .getSegmentsAtEvent( event )
 112
 113 Calling `getSegmentsAtEvent(event)` on your Chart instance passing an argument of an event, or jQuery event, will return the segment elements that are at the same position of that event.
 114
 115 ```javascript
 116 canvas.onclick = function(evt){
 117         var activePoints = myDoughnutChart.getSegmentsAtEvent(evt);
 118         // => activePoints is an array of segments on the canvas that are at the same position as the click event.
 119 };
 120 ```
 121
 122 This functionality may be useful for implementing DOM based tooltips, or triggering custom behaviour in your application.
 123
 124 #### .update( )
 125
 126 Calling `update()` on your Chart instance will re-render the chart with any updated values, allowing you to edit the value of multiple existing points, then render those in one animated render loop.
 127
 128 ```javascript
 129 myDoughnutChart.segments[1].value = 10;
 130 // Would update the first dataset's value of 'Green' to be 10
 131 myDoughnutChart.update();
 132 // Calling update now animates the circumference of the segment 'Green' from 50 to 10.
 133 // and transitions other segment widths
 134 ```
 135
 136 #### .addData( segmentData, index )
 137
 138 Calling `addData(segmentData, index)` on your Chart instance passing an object in the same format as in the constructor. There is an optional second argument of 'index', this determines at what index the new segment should be inserted into the chart.
 139
 140 ```javascript
 141 // An object in the same format as the original data source
 142 myDoughnutChart.addData({
 143         value: 130,
 144         color: "#B48EAD",
 145         highlight: "#C69CBE",
 146         label: "Purple"
 147 });
 148 // The new segment will now animate in.
 149 ```
 150
 151 #### .removeData( index )
 152
 153 Calling `removeData(index)` on your Chart instance will remove segment at that particular index. If none is provided, it will default to the last segment.
 154
 155 ```javascript
 156 myDoughnutChart.removeData();
 157 // Other segments will update to fill the empty space left.
 158 ```