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