plotkit_v091/doc/PlotKit.Renderer.txt

   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 %}