| 1 | |
| 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
| 3 | <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en" > |
| 4 | <head> |
| 5 | <title>PlotKit.Renderer | liquidx</title> |
| 6 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| 7 | <link href="http://media.liquidx.net/css/x_general.css" media="screen" rel="Stylesheet" type="text/css" /> |
| 8 | <link href="http://media.liquidx.net/css/x_header.css" media="screen" rel="Stylesheet" type="text/css" /> |
| 9 | <link href="http://media.liquidx.net/css/x_layout.css" media="screen" rel="Stylesheet" type="text/css" /> |
| 10 | <link href="http://media.liquidx.net/css/x_blocks.css" media="screen" rel="Stylesheet" type="text/css" /> |
| 11 | <link rel="icon" href="/favicon.png" type="image/x-png"> |
| 12 | <link rel="shortcut icon" href="/favicon.png" type="image/x-png"> |
| 13 | <!--[if lt IE 7.]> |
| 14 | <script defer type="text/javascript" src="http://media.liquidx.net/js/pngfix.js"></script> |
| 15 | <![endif]--> |
| 16 | |
| 17 | <link href="doc.css" media="screen" rel="stylesheet" type="text/css" /> |
| 18 | |
| 19 | </head> |
| 20 | |
| 21 | <body> |
| 22 | <div id="header"> |
| 23 | <div id="logo"><a href="http://www.liquidx.net/"><img src="http://media.liquidx.net/imgx/logo.png" width="256" height="128" alt="liquidx.net" /></a></div> |
| 24 | <div id="menu-hack"> |
| 25 | <div id="menu-l"><img src="http://media.liquidx.net/imgx/menu_l.png" width="17" height="28" alt="menu cap" /></div><div id="menu-r"><img src="http://media.liquidx.net/imgx/menu_r.png" width="17" height="28" alt="menu cap" /></div> |
| 26 | <div id="menu-main"> |
| 27 | <ul id="menu" class="code"> |
| 28 | <li class="tab" id="blog"><a href="http://www.liquidx.net/" title="blog/home">blog</a></li> |
| 29 | <li class="tab" id="code"><a href="http://www.liquidx.net/code/" title="software i have written">software</a></li> |
| 30 | <li class="tab" id="dev"><a href="http://projects.liquidx.net/" title="source code for my open source projects">dev</a></li> |
| 31 | <li class="tab" id="photos"><a href="http://al.tse.id.au/gallery/" title="photos and videos">photos</a></li> |
| 32 | <li class="tab" id="research"><a href="http://al.tse.id.au/research/" title="research profile">research</a></li> |
| 33 | <li class="tab" id="links"><a href="http://www.liquidx.net/links/" title="my bookmarks">linkblog</a></li> |
| 34 | <li class="tab" id="stats"><a href="http://stats.liquidx.net/" title="stats for various parts of my website">stats</a></li> |
| 35 | <li class="tab" id="status"><a href="http://www.liquidx.net/status/" title="weather report for alastair">status</a></li> |
| 36 | <li class="tab" id="about"><a href="http://al.tse.id.au/" title="about alastair tse">aboutme</a></li> |
| 37 | </ul> |
| 38 | </div> |
| 39 | </div> |
| 40 | <div id="quickbuttons"> |
| 41 | <span class="quickbutton"><a href="http://www.liquidx.net/albumartwidget/"><img src="http://media.liquidx.net/imgx/quick_widget.png" alt="album art widget" /></a></span> |
| 42 | <span class="quickbutton"><a href="http://www.liquidx.net/plotkit/"><img src="http://media.liquidx.net/imgx/quick_plotkit.png" alt="plotkit" /></a></span> |
| 43 | <span class="quickbutton"><a href="http://www.liquidx.net/fruity/"><img src="http://media.liquidx.net/imgx/quick_fruity.png" alt="fruity" /></a></span> |
| 44 | </div> |
| 45 | |
| 46 | </div> |
| 47 | |
| 48 | <div id="body"> |
| 49 | <div class="page doc api"> |
| 50 | |
| 51 | <p> <a href="PlotKit.html">PlotKit Home</a> | <a href="PlotKit.Layout.html"><<</a> | <a href="PlotKit.Canvas.html">>></a> |
| 52 | </p> |
| 53 | |
| 54 | <h1> PlotKit Renderer</h1> |
| 55 | <p>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. |
| 56 | </p> |
| 57 | <p>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. |
| 58 | </p> |
| 59 | <p>PlotKit Renderers should follow an informal protocol to allow users to plug and play different renderers. Below is the informal protocol: |
| 60 | </p> |
| 61 | |
| 62 | <h2> PlotKit Renderer Protocol</h2> |
| 63 | <ul> |
| 64 | <li> |
| 65 | Constructor: <code>new Renderer(element, layout, options = {})</code> |
| 66 | </li> |
| 67 | </ul> |
| 68 | <p> <code>element</code> is the element which this renderer will perform on, <code>layout</code> is the PlotKit.Layout object and <code>options</code> is an associative dictionary described below. |
| 69 | </p> |
| 70 | <ul> |
| 71 | <li> |
| 72 | class function: <code>isSupported()</code> |
| 73 | </li> |
| 74 | </ul> |
| 75 | <p> Optional check that returns <code>true</code> if the renderer is supported in the current browser. |
| 76 | </p> |
| 77 | <ul> |
| 78 | <li> |
| 79 | object method: <code>render()</code> |
| 80 | </li> |
| 81 | </ul> |
| 82 | <p> Renders to canvas, can be called multiple times, but <code>clear()</code> must be called between invokations. |
| 83 | </p> |
| 84 | <ul> |
| 85 | <li> |
| 86 | object method: <code>clear()</code> |
| 87 | </li> |
| 88 | </ul> |
| 89 | <p> Clear the canvas. |
| 90 | </p> |
| 91 | |
| 92 | <h2> PlotKit Renderer Options</h2> |
| 93 | <p>To allow some basic flexibility of the output, a renderer should |
| 94 | accept and act on the following options passed in the constructor. |
| 95 | </p> |
| 96 | <table cellpadding="0" cellspacing="0"> |
| 97 | <thead> |
| 98 | <tr><td>Option name</td><td>Description</td><td>Type</td><td>Default</td></tr> |
| 99 | </thead> |
| 100 | <tbody> |
| 101 | <tr> |
| 102 | <th>backgroundColor</th> |
| 103 | <td>color to use for background</td> |
| 104 | <td>MochiKit.Color.Color</td> |
| 105 | <td>Color.whiteColor()</td> |
| 106 | </tr> |
| 107 | <tr> |
| 108 | <th>colorScheme</th> |
| 109 | <td>Color scheme used</td> |
| 110 | <td>Array of MochiKit.Color.Color</td> |
| 111 | <td>output of PlotKit.Base.colorScheme()</td> |
| 112 | </tr> |
| 113 | <tr> |
| 114 | <th>strokeColor</th> |
| 115 | <td>Color used stroking. If set to null, the renderer will |
| 116 | attempt to use strokeColorTransform</td> |
| 117 | <td>MochiKit.Color.Color or null</td> |
| 118 | <td>null</td> |
| 119 | </tr> |
| 120 | <tr> |
| 121 | <th>strokeColorTransform</th> |
| 122 | <td>Name of the method to call to transform Color into stroke color.</td> |
| 123 | <td>string (name of a function that accepts no arguments)</td> |
| 124 | <td>"asStrokeColor"</td> |
| 125 | </tr> |
| 126 | <tr> |
| 127 | <th>drawBackground</th> |
| 128 | <td>Whether the background should be drawn</td> |
| 129 | <td>boolean</td> |
| 130 | <td>true</td> |
| 131 | </tr> |
| 132 | <tr> |
| 133 | <th>shouldFill</th> |
| 134 | <td>Should fill in area under chart</td> |
| 135 | <td>boolean</td> |
| 136 | <td>true</td> |
| 137 | </tr> |
| 138 | <tr> |
| 139 | <th>shouldStroke</th> |
| 140 | <td>Should stroke the borders of shapes in chart</td> |
| 141 | <td>boolean</td> |
| 142 | <td>true</td> |
| 143 | </tr> |
| 144 | <tr> |
| 145 | <th>strokeWidth</th> |
| 146 | <td>Width of stroke used (if shouldStroke is set)</td> |
| 147 | <td>float</td> |
| 148 | <td>0.1</td> |
| 149 | </tr> |
| 150 | <tr> |
| 151 | <th>padding</th> |
| 152 | <td>Padding of the graph drawn (excluding labels)</td> |
| 153 | <td>Object with properties: top, bottom, left, right.</td> |
| 154 | <td>{left: 30, right:20, top: 10, bottom: 10}</td> |
| 155 | </tr> |
| 156 | <tr> |
| 157 | <th>drawYAxis</th> |
| 158 | <td>draw Y Axis</td> |
| 159 | <td>boolean</td> |
| 160 | <td>true</td> |
| 161 | </tr> |
| 162 | <tr> |
| 163 | <th>drawXAxis</th> |
| 164 | <td>draw X Axis</td> |
| 165 | <td>boolean</td> |
| 166 | <td>true</td> |
| 167 | </tr> |
| 168 | <tr> |
| 169 | <th>axisLineColor</th> |
| 170 | <td>Color of axes line.</td> |
| 171 | <td>MochiKit.Color.Color</td> |
| 172 | <td>Color.blackColor()</td> |
| 173 | </tr> |
| 174 | <tr> |
| 175 | <th>axisLineWidth</th> |
| 176 | <td>axis line width</td> |
| 177 | <td>float</td> |
| 178 | <td>0.5</td> |
| 179 | </tr> |
| 180 | <tr> |
| 181 | <th>axisTickSize</th> |
| 182 | <td>length or height of a tick on the y and x axis respectively, in pixels</td> |
| 183 | <td>float</td> |
| 184 | <td>3.0</td> |
| 185 | </tr> |
| 186 | <tr> |
| 187 | <th>axisLabelColor</th> |
| 188 | <td>color of text label on axis.</td> |
| 189 | <td>MochiKit.Color.Color</td> |
| 190 | <td>Color.blackColor()</td> |
| 191 | </tr> |
| 192 | <tr> |
| 193 | <th>axisLabelFontSize</th> |
| 194 | <td>Font size of labels in pixels </td> |
| 195 | <td>integer</td> |
| 196 | <td>9</td> |
| 197 | </tr> |
| 198 | <tr> |
| 199 | <th>axisLabelWidth</th> |
| 200 | <td>Width of labels on ticks, in pixels</td> |
| 201 | <td>integer</td> |
| 202 | <td>50</td> |
| 203 | </tr> |
| 204 | <tr> |
| 205 | <th>enableEvents</th> |
| 206 | <td>Enable events (if supported)</td> |
| 207 | <td>boolean</td> |
| 208 | <td>true</td> |
| 209 | </tr> |
| 210 | </tbody> |
| 211 | </table> |
| 212 | |
| 213 | |
| 214 | <h1> Internal Renderer Methods and Style</h1> |
| 215 | <p>The default renderers that are available follow a rough structure. If |
| 216 | you plan to write a new renderer, you should think about using a |
| 217 | similar structure. |
| 218 | </p> |
| 219 | <p>Also, it is important that you follow an Object Orientated style and |
| 220 | split up the rendering methods as much as logically possible to allow |
| 221 | other developers to extend the work by using a "psuedo subclassing" |
| 222 | method described below. |
| 223 | </p> |
| 224 | |
| 225 | <h2> Subclassing</h2> |
| 226 | <p>PlotKit Renderers should adopt a Javascript subclassing structure to |
| 227 | allow developers/themers to customise certain aspects of the |
| 228 | rendering. Here is an example of what is expected: |
| 229 | </p> |
| 230 | <pre><code>MyRenderer = function(element, layout, options) { |
| 231 | if (arguments.length > 0) |
| 232 | this.__init__(element, layout, options); |
| 233 | }; |
| 234 | |
| 235 | MyRenderer.prototype.__init__ = function(element, layout, options) { |
| 236 | .... |
| 237 | }; |
| 238 | </code></pre><p>In this case, the default javascript constructor acts only when passed |
| 239 | arguments. <code>MyRenderer.prototype.__init__</code> is the real |
| 240 | constructor. It is named in similar vein to Python's constructor. |
| 241 | </p> |
| 242 | <p>For users who would like to subclass, they will need to use the |
| 243 | following snippet of code: |
| 244 | </p> |
| 245 | <pre><code> MyAlternateRenderer = function(element, layout. options) { |
| 246 | if (arguments.length > 0) |
| 247 | this.__init__(element, layout, options); |
| 248 | }; |
| 249 | MyAlternateRenderer.prototype = new MyRenderer(); |
| 250 | MyAlternateRenderer.prototype.constructor = MyAlternateRenderer; |
| 251 | MyAlternateRenderer.__super__ = MyRenderer.prototype; |
| 252 | |
| 253 | MyAlternateRenderer.prototype.__init__ = function(element, layout, options) { |
| 254 | MyAlternateRenderer.__super__.__init__.call(this, element, layout, options); |
| 255 | }; |
| 256 | </code></pre><p>For subclasses, they will need the following magic in order to |
| 257 | initialise their subclass. But after that, you can either override |
| 258 | <code>MyAlternateRenderer.prototype.__init__</code> with your own |
| 259 | implementation or just leave the superclass to deal with the |
| 260 | constructor. |
| 261 | </p> |
| 262 | <p>A more thorough example can be found in the PlotKit source for |
| 263 | <code>Canvas.js</code> and <code>SweetCanvas.js</code> respectively. |
| 264 | </p> |
| 265 | |
| 266 | <h2> Internal Renderer Properties</h2> |
| 267 | <p>The bundled renderers are have the following common properties to |
| 268 | allow standard access by all subclasses: |
| 269 | </p> |
| 270 | <ul> |
| 271 | <li> |
| 272 | <code>this.layout</code> |
| 273 | </li> |
| 274 | </ul> |
| 275 | <p>The PlotKit.Layout object passed by the user. |
| 276 | </p> |
| 277 | <ul> |
| 278 | <li> |
| 279 | <code>this.element</code> |
| 280 | </li> |
| 281 | </ul> |
| 282 | <p>The HTML element to use, either a Canvas Element or SVG Element depending |
| 283 | on whether a Canvas Renderer or SVG Renderer is in use. |
| 284 | </p> |
| 285 | <ul> |
| 286 | <li> |
| 287 | <code>this.options</code> |
| 288 | </li> |
| 289 | </ul> |
| 290 | <p>A dictionary of options that are applicable to the rendering style. |
| 291 | </p> |
| 292 | <ul> |
| 293 | <li> |
| 294 | <code>this.xlabels</code> |
| 295 | </li> |
| 296 | </ul> |
| 297 | <p>A list of elements that represent the axis. Should be cleared whenever |
| 298 | <code>clear()</code> is executed. |
| 299 | </p> |
| 300 | <ul> |
| 301 | <li> |
| 302 | <code>this.ylabels</code> |
| 303 | </li> |
| 304 | </ul> |
| 305 | <p>A list of elements that represent the axis. Should be cleared whenever |
| 306 | <code>clear()</code> is executed. |
| 307 | </p> |
| 308 | |
| 309 | <h2> Internal Renderer Methods</h2> |
| 310 | <ul> |
| 311 | <li> |
| 312 | <code>_renderBarChart()</code> |
| 313 | </li> |
| 314 | </ul> |
| 315 | <p>Renders only the bars of a bar chart on the element by looking at |
| 316 | <code>this.layout.bars</code> for the bars to render. Will only be called if |
| 317 | <code>this.layout.style == "bars"</code> |
| 318 | </p> |
| 319 | <ul> |
| 320 | <li> |
| 321 | <code>_renderLineChart()</code> |
| 322 | </li> |
| 323 | </ul> |
| 324 | <p>Renders only the lines of a line chart on the element by looking at |
| 325 | <code>this.layout.points</code> for the points to render. Will only be called if |
| 326 | <code>this.layout.style == "line"</code> |
| 327 | </p> |
| 328 | <ul> |
| 329 | <li> |
| 330 | <code>_renderPieChart()</code> |
| 331 | </li> |
| 332 | </ul> |
| 333 | <p>Renders only the slices of the pie in <code>this.layout.slices</code>. |
| 334 | Will only be called if <code>this.layout.style == "pie"</code> |
| 335 | </p> |
| 336 | <ul> |
| 337 | <li> |
| 338 | <code>_renderBarAxis()</code> |
| 339 | </li> |
| 340 | </ul> |
| 341 | <p>Renders the axis for a bar chart by looking at the |
| 342 | <code>this.layout.xticks</code> and <code>this.layout.yticks</code>. |
| 343 | </p> |
| 344 | <ul> |
| 345 | <li> |
| 346 | <code>_renderLineAxis()</code> |
| 347 | </li> |
| 348 | </ul> |
| 349 | <p>Renders the axis for a line chart by looking at the |
| 350 | <code>this.layout.xticks</code> and <code>this.layout.yticks</code>. |
| 351 | </p> |
| 352 | <ul> |
| 353 | <li> |
| 354 | <code>_renderPieAxis()</code> |
| 355 | </li> |
| 356 | </ul> |
| 357 | <p>Renders the labels for a pie chart by looking at |
| 358 | <code>this.layout.xticks</code> only. |
| 359 | </p> |
| 360 | <ul> |
| 361 | <li> |
| 362 | <code>_renderBackground()</code> |
| 363 | </li> |
| 364 | </ul> |
| 365 | <p>Called to render the background of the chart. Should check whether |
| 366 | <code>this.options.drawsBackground</code> is set before proceeding. |
| 367 | </p> |
| 368 | |
| 369 | <h1> Events from the Chart</h1> |
| 370 | <p>There is preliminary support for events from the chart for the Canvas |
| 371 | Renderer but the API is not stablised and subject to change. <strong>(TODO)</strong>. |
| 372 | </p> |
| 373 | |
| 374 | |
| 375 | </div> |
| 376 | </div> |
| 377 | |
| 378 | |
| 379 | |
| 380 | |
| 381 | <div id="footer"> |
| 382 | <div class="block"> |
| 383 | <h3>Syndication Feeds:</h3> |
| 384 | <p> |
| 385 | <ul class="tiny"> |
| 386 | <li><a href="http://www.liquidx.net/blog/feed/atom/" class="feed" title="feed for all posts on liquidx.net"><img src="http://media.liquidx.net/imgx/feed.gif" class="feed" alt="feed" />Atom Feed for the Blog Entries</a></li> |
| 387 | <li><a href="http://www.liquidx.net/blog/feed/rss/" class="feed" title="feed for all posts on liquidx.net"><img src="http://media.liquidx.net/imgx/feed.gif" class="feed" alt="feed" />RSS Feed for the Blog Entries</a></li> |
| 388 | <li><a href="http://www.liquidx.net/comments/feed/atom/" class="feed" title="feed for all posts on liquidx.net"><img src="http://media.liquidx.net/imgx/feed.gif" class="feed" alt="feed" />Feed for All Comments</a></li> |
| 389 | <li><a href="http://www.liquidx.net/links/feed/atom/" class="feed" title="feed for all bookmarked links"><img src="http://media.liquidx.net/imgx/feed.gif" class="feed" alt="feed" />Feed for Links</a></li> |
| 390 | </ul> |
| 391 | </p> |
| 392 | </div> |
| 393 | <div class="block"> |
| 394 | <h3>About this site:</h3> |
| 395 | <p>Content on this site is licensed under <a href="http://creativecommons.org/licenses/by/2.5/">CC By Attribution</a> unless otherwise specified. |
| 396 | Copyright (c) 2002-2006, <a href="http://al.tse.id.au/">Alastair Tse</a>.</p> |
| 397 | <p>For more information, see <a href="http://al.tse.id.au/">al.tse.id.au</a>.</p> |
| 398 | <p><script type="text/javascript" src="http://technorati.com/embed/itwctkzez.js"></script></p> |
| 399 | </div> |
| 400 | <div class="block"> |
| 401 | <h3>Is Made Possible By:</h3> |
| 402 | <p> |
| 403 | <dl> |
| 404 | <dt><a href="http://ecto.kung-foo.tv/" class="clean">ecto</a>. </dt> |
| 405 | <dd>Blogging client for Mac</dd> |
| 406 | <dt><a href="http://djangoproject.com/" class="clean">Django</a>. </dt> |
| 407 | <dd>Python Web Framework</dd> |
| 408 | <dt><a href="http://www.lighttpd.net/" class="clean">lighttpd</a>. </dt> |
| 409 | <dd>Really Fast Web Server</dd> |
| 410 | <dt><a href="http://www.saddi.com/software/flup/" class="clean">flup</a>. </dt> |
| 411 | <dd>FastCGI for Python</dd> |
| 412 | </dl> |
| 413 | </p> |
| 414 | </div> |
| 415 | <div class="block"> |
| 416 | <h3>Search My Sites:</h3> |
| 417 | <p> |
| 418 | <div style='margin: 10px; text-align: center; width: 160px;'><form action='http://www.rollyo.com/search.html' ><fieldset style='margin: 0; padding: 4px 0 0 0; height: 60px; border: none; background: url(http://rollyo.com/remote/togo-bg4.png) no-repeat top left;'><div style="position: absolute; float:left; z-index:99; width: 46px; height: 50px;"><a href="http://rollyo.com"><img style="border: none;" height="50" width="46" src="http://rollyo.com/remote/x.gif"></a></div> <input type='text' size='30' style='float: left; width: 90px; margin: 2px 0 0 48px; padding: 0; font-size: 12px;' name='q' value='Search...' onclick='this.value="";' /><br /> <select name='sid' style='float: left; width: 78px; height: 15px; margin: 12px 0 0 46px; font-size: 7pt; padding: 0;'><option value='106081' selected='selected'>liquidx</option><option value='web'>Search The Web</option></select><input type='image' src='http://rollyo.com/remote/btn-togo.png' alt='Go' style='margin: 12px 0 0 3px; float: left;' /><input type='hidden' name='togo-v' value='1' /></fieldset></form></div> |
| 419 | </p> |
| 420 | </div> |
| 421 | |
| 422 | |
| 423 | <div class="clear"> </div> |
| 424 | |
| 425 | </div> |
| 426 | |
| 427 | |
| 428 | |
| 429 | <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script> |
| 430 | <script type="text/javascript"> |
| 431 | _uacct = "UA-58117-1"; |
| 432 | urchinTracker(); |
| 433 | </script> |
| 434 | |
| 435 | </body> |
| 436 | </html> |