move custom_rhino out of plotkit
[dygraphs.git] / 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 %}