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.Layout{% endblock %} | |
8 | ||
9 | {% block content %} | |
10 | <div class="page doc api"> | |
11 | {% filter markdown %} | |
12 | [PlotKit Home](PlotKit.html) | [<<](PlotKit.Base.html) | [>>](PlotKit.Renderer.html) | |
13 | ||
14 | PlotKit Layout | |
15 | ============== | |
16 | ||
17 | PlotKit Layout is the core of the plotting engine. It deals exclusively with laying objects out on a virtual canvas that has the dimension of 1.0 x 1.0. | |
18 | ||
19 | The layout engine abstracts away all the complex layout problems with plotting charts and presents a list of objects that need to rendered rather than mixing this with the rendering logic. | |
20 | ||
21 | PlotKit Layout also is responsible for simple chart state querying so renderers can implement basic event support for objects on the canvas. | |
22 | ||
23 | Constructor | |
24 | =========== | |
25 | ||
26 | `new Layout(style, options);` | |
27 | ||
28 | Layout takes the following arguments: | |
29 | ||
30 | __style__ which can be `bar`, `line` or `pie` which represnts the style of the graph that is desired. | |
31 | ||
32 | __options__ is a dictionary/associative array of layout options. Unrecognised keys are ignored. The following options are supported: | |
33 | ||
34 | Layout Options | |
35 | ============== | |
36 | ||
37 | Bar and Line Chart layout options | |
38 | --------------------------------- | |
39 | ||
40 | <table cellpadding="0" cellspacing="0"> | |
41 | <thead> | |
42 | <tr><td>Option name</td><td>Description</td><td>Type</td><td>Default</td></tr> | |
43 | </thead> | |
44 | <tbody> | |
45 | <tr> | |
46 | <th>barWidthFillFraction</th> | |
47 | <td>Amount of space the total amount of bars should consume per X value.</td> | |
48 | <td>Real number</td> | |
49 | <td>0.75</td> | |
50 | </tr> | |
51 | <tr> | |
52 | <th>barOrientation</th> | |
53 | <td>Orientation of a bar chart. <b>(PlotKit 0.9+ only)</b></td> | |
54 | <td>String ("vertical", "horizontal")</td> | |
55 | <td>vertical</td> | |
56 | </tr> | |
57 | ||
58 | <tr> | |
59 | <th>xAxis</th> | |
60 | <td>Minimum and Maximum values on the X axis.</td> | |
61 | <td>Array of 2 Real numbers. (eg. [0.0, 10.0])</td> | |
62 | <td>null</td> | |
63 | </tr> | |
64 | <tr> | |
65 | <th>xNumberOfTicks</th> | |
66 | <td>Used when automatically calculating axis ticks. This denotes the number of ticks there should be in the graph.</td> | |
67 | <td>integer</td> | |
68 | <td>10</td> | |
69 | </tr> | |
70 | <tr> | |
71 | <th>xOriginIsZero</th> | |
72 | <td>Should graph have X axis origin at 0</td> | |
73 | <td>boolean</td> | |
74 | <td>true</td> | |
75 | </tr> | |
76 | <tr> | |
77 | <th>xTickPrecision</th> | |
78 | <td>The number of decimal places we should round to for tick values.</td> | |
79 | <td>integer</td> | |
80 | <td>1</td> | |
81 | </tr> | |
82 | <tr> | |
83 | <th>xTicks</th> | |
84 | <td>X values at which ticks should be drawn. Automatically calculated if not defined using the parameters `xNumberOfTicks` and ``xTickPrecision``.</td> | |
85 | <td>Array of {label: "somelabel", v:value}.</td> | |
86 | <td>null</td> | |
87 | </tr> | |
88 | ||
89 | <tr> | |
90 | <th>yAxis</th> | |
91 | <td>Minimum and Maximum values on the Y axis.</td> | |
92 | <td>Array of 2 Real numbers. (eg. [0.0, 10.0])</td> | |
93 | <td>null</td> | |
94 | </tr> | |
95 | <tr> | |
96 | <th>yNumberOfTicks</th> | |
97 | <td>Used when automatically calculating axis ticks. This denotes the number of ticks there should be in the graph.</td> | |
98 | <td>integer</td> | |
99 | <td>5</td> | |
100 | </tr> | |
101 | <tr> | |
102 | <th>yOriginIsZero</th> | |
103 | <td>Should graph have Y axis origin at 0</td> | |
104 | <td>true</td> | |
105 | </tr> | |
106 | <tr> | |
107 | <th>yTickPrecision</th> | |
108 | <td>The number of decimal places we should round to for tick values.</td> | |
109 | <td>integer</td> | |
110 | <td>1</td> | |
111 | </tr> | |
112 | <tr> | |
113 | <th>yTicks</th> | |
114 | <td>Y values at which ticks should be drawn. Automatically calculated if not defined using the parameters ``yNumberOfTicks`` and ``yTickPrecision``.</td> | |
115 | <td>Array of {label: "somelabel", v:value}.</td> | |
116 | <td>null</td> | |
117 | </tr> | |
118 | </tbody> | |
119 | </table> | |
120 | ||
121 | Pie Chart Layout Options | |
122 | ------------------------ | |
123 | ||
124 | <table> | |
125 | <thead> | |
126 | <tr><td>Option name</td><td>Description</td><td>Type</td><td>Default</td></tr> | |
127 | </thead> | |
128 | <tbody> | |
129 | <tr> | |
130 | <th>pieRadius</th> | |
131 | <td>Radius of the circle to be drawn.</td> | |
132 | <td>Real number</td> | |
133 | <td>0.4</td> | |
134 | </tr> | |
135 | </tbody> | |
136 | </table> | |
137 | ||
138 | Layout Properties | |
139 | ================= | |
140 | ||
141 | There are some properties you can access, either because you are using a layout inside a renderer or if you would like additional information. Under normal operations, you will not need to, or should modify these parameters. | |
142 | ||
143 | <table cellpadding="0" cellspacing="0"> | |
144 | <thead> | |
145 | <tr><td>Property</td><td>Type</td><td>Description</td></tr> | |
146 | </thead> | |
147 | <tbody> | |
148 | <tr> | |
149 | <th>style</th> | |
150 | <td>String</td> | |
151 | <td>This denotes the type of chart this layout is using. Valid values are ``bar``, ``line`` or ``pie``. Renderers will use this to determine which parameter (``bars``, ``points`` or ``slices``) to access in order to get draw the chart.</td> | |
152 | </tr> | |
153 | <tr> | |
154 | <th>bars</th> | |
155 | <td>Array of Bar.</td> | |
156 | <td>This is a list of rectangles with values that the renderer should plot. This will only be valid after ``evaluate()`` has run. The properties of ``bar`` is described here. This is only valid if style is ``bar``. This array is sorted by dataset and then x-values.</td> | |
157 | </tr> | |
158 | <tr> | |
159 | <th>points</th> | |
160 | <td>Array of Point.</td> | |
161 | <td>This is a list of points with values that the renderer should plot. This will only be valid after ``evaluate()`` has run. The properties of ``bar`` is described here. This is only valid if style is ``line``. This array is sorted by dataset and then x-values.</td> | |
162 | </tr> | |
163 | <tr> | |
164 | <th>slices</th> | |
165 | <td>Array of Slice.</td> | |
166 | <td>This is a list of pie slices with values that the renderer should plot. This will only be valid after ``evaluate()`` has run. The properties of ``bar`` is described here. This is only valid if style is ``pie``.</td> | |
167 | </tr> | |
168 | <tr> | |
169 | <th>xticks</th> | |
170 | <td>Array of Tick.</td> | |
171 | <td>For style in ``bar`` or ``line``, these are the ticks on the X axis. A ``tick`` is represented as a two element array with the first element representing the x position of the tick and the second element representing the string value of the label at that position.</td> | |
172 | </tr> | |
173 | <tr> | |
174 | <th>yticks</th> | |
175 | <td>Array of Tick.</td> | |
176 | <td>For style in ``bar`` or ``line``, these are the ticks on the Y axis. A ``tick`` is represented as a two element array with the first element representing the y position of the tick and the second element representing the string value of the label at that position.</td> | |
177 | </tr> | |
178 | <tr> | |
179 | <th>datasets</th> | |
180 | <td>Associative Array of datasets</td> | |
181 | <td>This should normally only be used to find the number of datasets by performing ``keys(layout.datasets)``. If you are looking at this in a renderer, then the layout engine needs to be extended.</td> | |
182 | </tr> | |
183 | </tbody> | |
184 | </table> | |
185 | ||
186 | Layout Types | |
187 | ============ | |
188 | ||
189 | Here are the definition of the types that you will encounter if you access the properties of the Layout object, specifically ``bars``, ``points`` and ``slices``. If you are not writing a renderer, you do not need to know this. | |
190 | ||
191 | Bar Type | |
192 | -------- | |
193 | ||
194 | Represents a bar that the renderer will draw. It contains the following properties. | |
195 | ||
196 | <table cellpadding="0" cellspacing="0"> | |
197 | <thead> | |
198 | <tr><td>Property</td><td>Type</td><td>Description</td></tr> | |
199 | </thead> | |
200 | <tbody> | |
201 | <tr> | |
202 | <th>x, y</th> | |
203 | <td>float</td> | |
204 | <td>top left position of the bar between 0.0 and 1.0.</td> | |
205 | </tr> | |
206 | <tr> | |
207 | <th>w, h</th> | |
208 | <td>float</td> | |
209 | <td>width and height of the bar from (``x``, ``y``) between 0.0 and 1.0.</td> | |
210 | </tr> | |
211 | <tr> | |
212 | <th>xval, yval</th> | |
213 | <td>float</td> | |
214 | <td>The actual x value and y value this bar represents.</td> | |
215 | </tr> | |
216 | <tr> | |
217 | <th>name</th> | |
218 | <td>string</td> | |
219 | <td>Name of the dataset which this bar belongs to.</td> | |
220 | </tr> | |
221 | </tbody> | |
222 | </table> | |
223 | ||
224 | Point Type | |
225 | ---------- | |
226 | ||
227 | This represents a point on a line chart. | |
228 | ||
229 | <table cellpadding="0" cellspacing="0"> | |
230 | <thead> | |
231 | <tr><td>Property</td><td>Type</td><td>Description</td></tr> | |
232 | </thead> | |
233 | <tbody> | |
234 | <tr> | |
235 | <th>x, y</th> | |
236 | <td>float</td> | |
237 | <td>top left position of the point between 0.0 and 1.0.</td> | |
238 | </tr> | |
239 | <tr> | |
240 | <th>xval, yval</th> | |
241 | <td>float</td> | |
242 | <td>The actual x value and y value this bar represents.</td> | |
243 | </tr> | |
244 | <tr> | |
245 | <th>name</th> | |
246 | <td>string</td> | |
247 | <td>Name of the dataset which this bar belongs to.</td> | |
248 | </tr> | |
249 | </tbody> | |
250 | </table> | |
251 | ||
252 | Slice Type | |
253 | ---------- | |
254 | ||
255 | This represents a pie slice in a pie chart. | |
256 | ||
257 | <table> | |
258 | <thead> | |
259 | <tr><td>Property</td><td>Type</td><td>Description</td></tr> | |
260 | </thead> | |
261 | <tbody> | |
262 | <tr> | |
263 | <th>fraction</th> | |
264 | <td>float</td> | |
265 | <td>The fractional value this slice represents. This number is between 0.0 and 1.0</td> | |
266 | </tr> | |
267 | <tr> | |
268 | <th>xval, yval</th> | |
269 | <td>float</td> | |
270 | <td>The x and y values of this slice.</td> | |
271 | </tr> | |
272 | <tr> | |
273 | <th>startAngle</th> | |
274 | <td>float</td> | |
275 | <td>This is the angle of the start of the slice, in radians.</td> | |
276 | </tr> | |
277 | <tr> | |
278 | <th>endAngle</th> | |
279 | <td>float</td> | |
280 | <td>This is the angle of the end of the slice, in radians.</td> | |
281 | </tr> | |
282 | </tbody> | |
283 | </table> | |
284 | ||
285 | Layout Methods | |
286 | ============== | |
287 | ||
288 | * ``addDataset(name, values)`` | |
289 | ||
290 | Adds a dataset to the layout engine and assigns it with ``name``. ``values`` is an array of ``\[x, y\]`` values. | |
291 | ||
292 | * ``removeDataset(name)`` | |
293 | ||
294 | Removes a dataset from the layout engine. In order for the new data to take effect, you must run ``evaluate()``. | |
295 | ||
296 | * ``addDatasetFromTable(name, tableElement, xcol = 0, ycol = 1, labelCol = -1)`` | |
297 | ||
298 | Handy function to read values off a table. ``name`` is the name to give to the dataset just like in ``addDataset()``, ``tableElement`` is the table which contains the values. Optionally, the user may specify to extract alternative columns using ``xcol`` and ``ycol``. | |
299 | ||
300 | **New in 0.9.1:** If ``labelCol`` is specified to a value greater than -1, it will take the contents of that column as the xTick labels. | |
301 | ||
302 | * ``evaluate()`` | |
303 | ||
304 | Performs the evaluation of the layout. It is not done automatically, and you __must__ execute this before passing the layout to a renderer. | |
305 | ||
306 | * hitTest(x, y) | |
307 | ||
308 | Used by renderers to see if a virtual canvas position corresponds to any data. The return value varies per style. For ``bar`` charts, it will return the Bar type if it is a hit, or null if not. For ``line`` charts, it will return a value if the point is underneath the highest curve, otherwise null __(TODO: expand this or change implementation)__. For ``pie`` charts, it will return the Slice object that is at the point, otherwise null. | |
309 | ||
310 | __Note that the specification of this function is subject to change__. | |
311 | ||
312 | Layout Notes | |
313 | ============ | |
314 | ||
315 | Pie Chart Data and Ticks Restrictions | |
316 | ------------------------------------- | |
317 | ||
318 | Note that you can only use one dataset for pie charts. Only the y value of the dataset will be used, but the x value must be unique and set as it will correspond to the xTicks that are given. | |
319 | ||
320 | Labels for pie charts will only use xTicks. | |
321 | ||
322 | Layout Examples | |
323 | =============== | |
324 | ||
325 | {% endfilter %} | |
326 | </div> | |
327 | {% endblock %} | |
328 | ||
329 | ||
330 |