plotkit_v091/doc/PlotKit.Renderer.html

   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">&lt;&lt;</a> | <a href="PlotKit.Canvas.html">&gt;&gt;</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 &quot;psuedo subclassing&quot;
 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  &gt; 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 &gt; 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 == &quot;bars&quot;</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 == &quot;line&quot;</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 == &quot;pie&quot;</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">&nbsp;</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>