Commit | Line | Data |
---|---|---|
6a1aa64f DV |
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> |