| 1 | {% extends "basex.html" %} |
| 2 | {% load markup %} |
| 3 | {% block pageid %}code{% endblock %} |
| 4 | {% block headers %} |
| 5 | <link href="doc.css" media="screen" rel="stylesheet" type="text/css" /> |
| 6 | {% endblock %} |
| 7 | {% block title %}PlotKit.Renderer{% endblock %} |
| 8 | |
| 9 | {% block content %} |
| 10 | <div class="page doc api"> |
| 11 | {% filter markdown %} |
| 12 | [PlotKit Home](PlotKit.html) | [<<](PlotKit.Layout.html) | [>>](PlotKit.Canvas.html) |
| 13 | |
| 14 | PlotKit Renderer |
| 15 | ================ |
| 16 | |
| 17 | A Renderer is responsible for translating the layout calculated by PlotKit.Layout and draw it on to a HTML Canvas, SVG object or any other way. One way to use the renderer is to allow theming of graphs by tweaking the layout. |
| 18 | |
| 19 | PlotKit includes some common basic renderers, so you do not need to customise anything if you just plan to change the spacing, colors, fonts, or layout. |
| 20 | |
| 21 | PlotKit Renderers should follow an informal protocol to allow users to plug and play different renderers. Below is the informal protocol: |
| 22 | |
| 23 | PlotKit Renderer Protocol |
| 24 | ------------------------- |
| 25 | * Constructor: ``new Renderer(element, layout, options = {})`` |
| 26 | |
| 27 | ``element`` is the element which this renderer will perform on, ``layout`` is the PlotKit.Layout object and ``options`` is an associative dictionary described below. |
| 28 | |
| 29 | * class function: ``isSupported()`` |
| 30 | |
| 31 | Optional check that returns ``true`` if the renderer is supported in the current browser. |
| 32 | |
| 33 | * object method: ``render()`` |
| 34 | |
| 35 | Renders to canvas, can be called multiple times, but ``clear()`` must be called between invokations. |
| 36 | |
| 37 | * object method: ``clear()`` |
| 38 | |
| 39 | Clear the canvas. |
| 40 | |
| 41 | PlotKit Renderer Options |
| 42 | ------------------------ |
| 43 | To allow some basic flexibility of the output, a renderer should |
| 44 | accept and act on the following options passed in the constructor. |
| 45 | |
| 46 | |
| 47 | <table cellpadding="0" cellspacing="0"> |
| 48 | <thead> |
| 49 | <tr><td>Option name</td><td>Description</td><td>Type</td><td>Default</td></tr> |
| 50 | </thead> |
| 51 | <tbody> |
| 52 | <tr> |
| 53 | <th>backgroundColor</th> |
| 54 | <td>color to use for background</td> |
| 55 | <td>MochiKit.Color.Color</td> |
| 56 | <td>Color.whiteColor()</td> |
| 57 | </tr> |
| 58 | <tr> |
| 59 | <th>colorScheme</th> |
| 60 | <td>Color scheme used</td> |
| 61 | <td>Array of MochiKit.Color.Color</td> |
| 62 | <td>output of PlotKit.Base.colorScheme()</td> |
| 63 | </tr> |
| 64 | <tr> |
| 65 | <th>strokeColor</th> |
| 66 | <td>Color used stroking. If set to null, the renderer will |
| 67 | attempt to use strokeColorTransform</td> |
| 68 | <td>MochiKit.Color.Color or null</td> |
| 69 | <td>null</td> |
| 70 | </tr> |
| 71 | <tr> |
| 72 | <th>strokeColorTransform</th> |
| 73 | <td>Name of the method to call to transform Color into stroke color.</td> |
| 74 | <td>string (name of a function that accepts no arguments)</td> |
| 75 | <td>"asStrokeColor"</td> |
| 76 | </tr> |
| 77 | <tr> |
| 78 | <th>drawBackground</th> |
| 79 | <td>Whether the background should be drawn</td> |
| 80 | <td>boolean</td> |
| 81 | <td>true</td> |
| 82 | </tr> |
| 83 | <tr> |
| 84 | <th>shouldFill</th> |
| 85 | <td>Should fill in area under chart</td> |
| 86 | <td>boolean</td> |
| 87 | <td>true</td> |
| 88 | </tr> |
| 89 | <tr> |
| 90 | <th>shouldStroke</th> |
| 91 | <td>Should stroke the borders of shapes in chart</td> |
| 92 | <td>boolean</td> |
| 93 | <td>true</td> |
| 94 | </tr> |
| 95 | <tr> |
| 96 | <th>strokeWidth</th> |
| 97 | <td>Width of stroke used (if shouldStroke is set)</td> |
| 98 | <td>float</td> |
| 99 | <td>0.1</td> |
| 100 | </tr> |
| 101 | <tr> |
| 102 | <th>padding</th> |
| 103 | <td>Padding of the graph drawn (excluding labels)</td> |
| 104 | <td>Object with properties: top, bottom, left, right.</td> |
| 105 | <td>{left: 30, right:20, top: 10, bottom: 10}</td> |
| 106 | </tr> |
| 107 | <tr> |
| 108 | <th>drawYAxis</th> |
| 109 | <td>draw Y Axis</td> |
| 110 | <td>boolean</td> |
| 111 | <td>true</td> |
| 112 | </tr> |
| 113 | <tr> |
| 114 | <th>drawXAxis</th> |
| 115 | <td>draw X Axis</td> |
| 116 | <td>boolean</td> |
| 117 | <td>true</td> |
| 118 | </tr> |
| 119 | <tr> |
| 120 | <th>axisLineColor</th> |
| 121 | <td>Color of axes line.</td> |
| 122 | <td>MochiKit.Color.Color</td> |
| 123 | <td>Color.blackColor()</td> |
| 124 | </tr> |
| 125 | <tr> |
| 126 | <th>axisLineWidth</th> |
| 127 | <td>axis line width</td> |
| 128 | <td>float</td> |
| 129 | <td>0.5</td> |
| 130 | </tr> |
| 131 | <tr> |
| 132 | <th>axisTickSize</th> |
| 133 | <td>length or height of a tick on the y and x axis respectively, in pixels</td> |
| 134 | <td>float</td> |
| 135 | <td>3.0</td> |
| 136 | </tr> |
| 137 | <tr> |
| 138 | <th>axisLabelColor</th> |
| 139 | <td>color of text label on axis.</td> |
| 140 | <td>MochiKit.Color.Color</td> |
| 141 | <td>Color.blackColor()</td> |
| 142 | </tr> |
| 143 | <tr> |
| 144 | <th>axisLabelFontSize</th> |
| 145 | <td>Font size of labels in pixels </td> |
| 146 | <td>integer</td> |
| 147 | <td>9</td> |
| 148 | </tr> |
| 149 | <tr> |
| 150 | <th>axisLabelWidth</th> |
| 151 | <td>Width of labels on ticks, in pixels</td> |
| 152 | <td>integer</td> |
| 153 | <td>50</td> |
| 154 | </tr> |
| 155 | <tr> |
| 156 | <th>enableEvents</th> |
| 157 | <td>Enable events (if supported)</td> |
| 158 | <td>boolean</td> |
| 159 | <td>true</td> |
| 160 | </tr> |
| 161 | </tbody> |
| 162 | </table> |
| 163 | |
| 164 | Internal Renderer Methods and Style |
| 165 | =================================== |
| 166 | |
| 167 | The default renderers that are available follow a rough structure. If |
| 168 | you plan to write a new renderer, you should think about using a |
| 169 | similar structure. |
| 170 | |
| 171 | Also, it is important that you follow an Object Orientated style and |
| 172 | split up the rendering methods as much as logically possible to allow |
| 173 | other developers to extend the work by using a "psuedo subclassing" |
| 174 | method described below. |
| 175 | |
| 176 | Subclassing |
| 177 | ----------- |
| 178 | |
| 179 | PlotKit Renderers should adopt a Javascript subclassing structure to |
| 180 | allow developers/themers to customise certain aspects of the |
| 181 | rendering. Here is an example of what is expected: |
| 182 | |
| 183 | MyRenderer = function(element, layout, options) { |
| 184 | if (arguments.length > 0) |
| 185 | this.__init__(element, layout, options); |
| 186 | }; |
| 187 | |
| 188 | MyRenderer.prototype.__init__ = function(element, layout, options) { |
| 189 | .... |
| 190 | }; |
| 191 | |
| 192 | In this case, the default javascript constructor acts only when passed |
| 193 | arguments. ``MyRenderer.prototype.__init__`` is the real |
| 194 | constructor. It is named in similar vein to Python's constructor. |
| 195 | |
| 196 | For users who would like to subclass, they will need to use the |
| 197 | following snippet of code: |
| 198 | |
| 199 | MyAlternateRenderer = function(element, layout. options) { |
| 200 | if (arguments.length > 0) |
| 201 | this.__init__(element, layout, options); |
| 202 | }; |
| 203 | MyAlternateRenderer.prototype = new MyRenderer(); |
| 204 | MyAlternateRenderer.prototype.constructor = MyAlternateRenderer; |
| 205 | MyAlternateRenderer.__super__ = MyRenderer.prototype; |
| 206 | |
| 207 | MyAlternateRenderer.prototype.__init__ = function(element, layout, options) { |
| 208 | MyAlternateRenderer.__super__.__init__.call(this, element, layout, options); |
| 209 | }; |
| 210 | |
| 211 | |
| 212 | For subclasses, they will need the following magic in order to |
| 213 | initialise their subclass. But after that, you can either override |
| 214 | ``MyAlternateRenderer.prototype.__init__`` with your own |
| 215 | implementation or just leave the superclass to deal with the |
| 216 | constructor. |
| 217 | |
| 218 | A more thorough example can be found in the PlotKit source for |
| 219 | ``Canvas.js`` and ``SweetCanvas.js`` respectively. |
| 220 | |
| 221 | Internal Renderer Properties |
| 222 | ---------------------------- |
| 223 | |
| 224 | The bundled renderers are have the following common properties to |
| 225 | allow standard access by all subclasses: |
| 226 | |
| 227 | * ``this.layout`` |
| 228 | |
| 229 | The PlotKit.Layout object passed by the user. |
| 230 | |
| 231 | * ``this.element`` |
| 232 | |
| 233 | The HTML element to use, either a Canvas Element or SVG Element depending |
| 234 | on whether a Canvas Renderer or SVG Renderer is in use. |
| 235 | |
| 236 | * ``this.options`` |
| 237 | |
| 238 | A dictionary of options that are applicable to the rendering style. |
| 239 | |
| 240 | * ``this.xlabels`` |
| 241 | |
| 242 | A list of elements that represent the axis. Should be cleared whenever |
| 243 | ``clear()`` is executed. |
| 244 | |
| 245 | * ``this.ylabels`` |
| 246 | |
| 247 | A list of elements that represent the axis. Should be cleared whenever |
| 248 | ``clear()`` is executed. |
| 249 | |
| 250 | Internal Renderer Methods |
| 251 | ------------------------- |
| 252 | |
| 253 | * ``_renderBarChart()`` |
| 254 | |
| 255 | Renders only the bars of a bar chart on the element by looking at |
| 256 | ``this.layout.bars`` for the bars to render. Will only be called if |
| 257 | ``this.layout.style == "bars"`` |
| 258 | |
| 259 | * ``_renderLineChart()`` |
| 260 | |
| 261 | Renders only the lines of a line chart on the element by looking at |
| 262 | ``this.layout.points`` for the points to render. Will only be called if |
| 263 | ``this.layout.style == "line"`` |
| 264 | |
| 265 | * ``_renderPieChart()`` |
| 266 | |
| 267 | Renders only the slices of the pie in ``this.layout.slices``. |
| 268 | Will only be called if ``this.layout.style == "pie"`` |
| 269 | |
| 270 | * ``_renderBarAxis()`` |
| 271 | |
| 272 | Renders the axis for a bar chart by looking at the |
| 273 | ``this.layout.xticks`` and ``this.layout.yticks``. |
| 274 | |
| 275 | * ``_renderLineAxis()`` |
| 276 | |
| 277 | Renders the axis for a line chart by looking at the |
| 278 | ``this.layout.xticks`` and ``this.layout.yticks``. |
| 279 | |
| 280 | * ``_renderPieAxis()`` |
| 281 | |
| 282 | Renders the labels for a pie chart by looking at |
| 283 | ``this.layout.xticks`` only. |
| 284 | |
| 285 | * ``_renderBackground()`` |
| 286 | |
| 287 | Called to render the background of the chart. Should check whether |
| 288 | ``this.options.drawsBackground`` is set before proceeding. |
| 289 | |
| 290 | |
| 291 | Events from the Chart |
| 292 | ===================== |
| 293 | |
| 294 | There is preliminary support for events from the chart for the Canvas |
| 295 | Renderer but the API is not stablised and subject to change. __(TODO)__. |
| 296 | |
| 297 | {% endfilter %} |
| 298 | </div> |
| 299 | {% endblock %} |