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.Layout | 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.Base.html"><<</a> | <a href="PlotKit.Renderer.html">>></a> | |
52 | </p> | |
53 | ||
54 | <h1> PlotKit Layout</h1> | |
55 | <p>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. | |
56 | </p> | |
57 | <p>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. | |
58 | </p> | |
59 | <p>PlotKit Layout also is responsible for simple chart state querying so renderers can implement basic event support for objects on the canvas. | |
60 | </p> | |
61 | ||
62 | <h1> Constructor</h1> | |
63 | <p> <code>new Layout(style, options);</code> | |
64 | </p> | |
65 | <p>Layout takes the following arguments: | |
66 | </p> | |
67 | <p> <strong>style</strong> which can be <code>bar</code>, <code>line</code> or <code>pie</code> which represnts the style of the graph that is desired. | |
68 | </p> | |
69 | <p> <strong>options</strong> is a dictionary/associative array of layout options. Unrecognised keys are ignored. The following options are supported: | |
70 | </p> | |
71 | ||
72 | <h1> Layout Options</h1> | |
73 | ||
74 | <h2> Bar and Line Chart layout options</h2> | |
75 | <table cellpadding="0" cellspacing="0"> | |
76 | <thead> | |
77 | <tr><td>Option name</td><td>Description</td><td>Type</td><td>Default</td></tr> | |
78 | </thead> | |
79 | <tbody> | |
80 | <tr> | |
81 | <th>barWidthFillFraction</th> | |
82 | <td>Amount of space the total amount of bars should consume per X value.</td> | |
83 | <td>Real number</td> | |
84 | <td>0.75</td> | |
85 | </tr> | |
86 | <tr> | |
87 | <th>barOrientation</th> | |
88 | <td>Orientation of a bar chart. <b>(PlotKit 0.9+ only)</b></td> | |
89 | <td>String ("vertical", "horizontal")</td> | |
90 | <td>vertical</td> | |
91 | </tr> | |
92 | ||
93 | <tr> | |
94 | <th>xAxis</th> | |
95 | <td>Minimum and Maximum values on the X axis.</td> | |
96 | <td>Array of 2 Real numbers. (eg. [0.0, 10.0])</td> | |
97 | <td>null</td> | |
98 | </tr> | |
99 | <tr> | |
100 | <th>xNumberOfTicks</th> | |
101 | <td>Used when automatically calculating axis ticks. This denotes the number of ticks there should be in the graph.</td> | |
102 | <td>integer</td> | |
103 | <td>10</td> | |
104 | </tr> | |
105 | <tr> | |
106 | <th>xOriginIsZero</th> | |
107 | <td>Should graph have X axis origin at 0</td> | |
108 | <td>boolean</td> | |
109 | <td>true</td> | |
110 | </tr> | |
111 | <tr> | |
112 | <th>xTickPrecision</th> | |
113 | <td>The number of decimal places we should round to for tick values.</td> | |
114 | <td>integer</td> | |
115 | <td>1</td> | |
116 | </tr> | |
117 | <tr> | |
118 | <th>xTicks</th> | |
119 | <td>X values at which ticks should be drawn. Automatically calculated if not defined using the parameters `xNumberOfTicks` and ``xTickPrecision``.</td> | |
120 | <td>Array of {label: "somelabel", v:value}.</td> | |
121 | <td>null</td> | |
122 | </tr> | |
123 | ||
124 | <tr> | |
125 | <th>yAxis</th> | |
126 | <td>Minimum and Maximum values on the Y axis.</td> | |
127 | <td>Array of 2 Real numbers. (eg. [0.0, 10.0])</td> | |
128 | <td>null</td> | |
129 | </tr> | |
130 | <tr> | |
131 | <th>yNumberOfTicks</th> | |
132 | <td>Used when automatically calculating axis ticks. This denotes the number of ticks there should be in the graph.</td> | |
133 | <td>integer</td> | |
134 | <td>5</td> | |
135 | </tr> | |
136 | <tr> | |
137 | <th>yOriginIsZero</th> | |
138 | <td>Should graph have Y axis origin at 0</td> | |
139 | <td>true</td> | |
140 | </tr> | |
141 | <tr> | |
142 | <th>yTickPrecision</th> | |
143 | <td>The number of decimal places we should round to for tick values.</td> | |
144 | <td>integer</td> | |
145 | <td>1</td> | |
146 | </tr> | |
147 | <tr> | |
148 | <th>yTicks</th> | |
149 | <td>Y values at which ticks should be drawn. Automatically calculated if not defined using the parameters ``yNumberOfTicks`` and ``yTickPrecision``.</td> | |
150 | <td>Array of {label: "somelabel", v:value}.</td> | |
151 | <td>null</td> | |
152 | </tr> | |
153 | </tbody> | |
154 | </table> | |
155 | ||
156 | ||
157 | <h2> Pie Chart Layout Options</h2> | |
158 | <table> | |
159 | <thead> | |
160 | <tr><td>Option name</td><td>Description</td><td>Type</td><td>Default</td></tr> | |
161 | </thead> | |
162 | <tbody> | |
163 | <tr> | |
164 | <th>pieRadius</th> | |
165 | <td>Radius of the circle to be drawn.</td> | |
166 | <td>Real number</td> | |
167 | <td>0.4</td> | |
168 | </tr> | |
169 | </tbody> | |
170 | </table> | |
171 | ||
172 | ||
173 | <h1> Layout Properties</h1> | |
174 | <p>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. | |
175 | </p> | |
176 | <table cellpadding="0" cellspacing="0"> | |
177 | <thead> | |
178 | <tr><td>Property</td><td>Type</td><td>Description</td></tr> | |
179 | </thead> | |
180 | <tbody> | |
181 | <tr> | |
182 | <th>style</th> | |
183 | <td>String</td> | |
184 | <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> | |
185 | </tr> | |
186 | <tr> | |
187 | <th>bars</th> | |
188 | <td>Array of Bar.</td> | |
189 | <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> | |
190 | </tr> | |
191 | <tr> | |
192 | <th>points</th> | |
193 | <td>Array of Point.</td> | |
194 | <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> | |
195 | </tr> | |
196 | <tr> | |
197 | <th>slices</th> | |
198 | <td>Array of Slice.</td> | |
199 | <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> | |
200 | </tr> | |
201 | <tr> | |
202 | <th>xticks</th> | |
203 | <td>Array of Tick.</td> | |
204 | <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> | |
205 | </tr> | |
206 | <tr> | |
207 | <th>yticks</th> | |
208 | <td>Array of Tick.</td> | |
209 | <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> | |
210 | </tr> | |
211 | <tr> | |
212 | <th>datasets</th> | |
213 | <td>Associative Array of datasets</td> | |
214 | <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> | |
215 | </tr> | |
216 | </tbody> | |
217 | </table> | |
218 | ||
219 | ||
220 | <h1> Layout Types</h1> | |
221 | <p>Here are the definition of the types that you will encounter if you access the properties of the Layout object, specifically <code>bars</code>, <code>points</code> and <code>slices</code>. If you are not writing a renderer, you do not need to know this. | |
222 | </p> | |
223 | ||
224 | <h2> Bar Type</h2> | |
225 | <p>Represents a bar that the renderer will draw. It contains the following properties. | |
226 | </p> | |
227 | <table cellpadding="0" cellspacing="0"> | |
228 | <thead> | |
229 | <tr><td>Property</td><td>Type</td><td>Description</td></tr> | |
230 | </thead> | |
231 | <tbody> | |
232 | <tr> | |
233 | <th>x, y</th> | |
234 | <td>float</td> | |
235 | <td>top left position of the bar between 0.0 and 1.0.</td> | |
236 | </tr> | |
237 | <tr> | |
238 | <th>w, h</th> | |
239 | <td>float</td> | |
240 | <td>width and height of the bar from (``x``, ``y``) between 0.0 and 1.0.</td> | |
241 | </tr> | |
242 | <tr> | |
243 | <th>xval, yval</th> | |
244 | <td>float</td> | |
245 | <td>The actual x value and y value this bar represents.</td> | |
246 | </tr> | |
247 | <tr> | |
248 | <th>name</th> | |
249 | <td>string</td> | |
250 | <td>Name of the dataset which this bar belongs to.</td> | |
251 | </tr> | |
252 | </tbody> | |
253 | </table> | |
254 | ||
255 | ||
256 | <h2> Point Type</h2> | |
257 | <p>This represents a point on a line chart. | |
258 | </p> | |
259 | <table cellpadding="0" cellspacing="0"> | |
260 | <thead> | |
261 | <tr><td>Property</td><td>Type</td><td>Description</td></tr> | |
262 | </thead> | |
263 | <tbody> | |
264 | <tr> | |
265 | <th>x, y</th> | |
266 | <td>float</td> | |
267 | <td>top left position of the point between 0.0 and 1.0.</td> | |
268 | </tr> | |
269 | <tr> | |
270 | <th>xval, yval</th> | |
271 | <td>float</td> | |
272 | <td>The actual x value and y value this bar represents.</td> | |
273 | </tr> | |
274 | <tr> | |
275 | <th>name</th> | |
276 | <td>string</td> | |
277 | <td>Name of the dataset which this bar belongs to.</td> | |
278 | </tr> | |
279 | </tbody> | |
280 | </table> | |
281 | ||
282 | ||
283 | <h2> Slice Type</h2> | |
284 | <p>This represents a pie slice in a pie chart. | |
285 | </p> | |
286 | <table> | |
287 | <thead> | |
288 | <tr><td>Property</td><td>Type</td><td>Description</td></tr> | |
289 | </thead> | |
290 | <tbody> | |
291 | <tr> | |
292 | <th>fraction</th> | |
293 | <td>float</td> | |
294 | <td>The fractional value this slice represents. This number is between 0.0 and 1.0</td> | |
295 | </tr> | |
296 | <tr> | |
297 | <th>xval, yval</th> | |
298 | <td>float</td> | |
299 | <td>The x and y values of this slice.</td> | |
300 | </tr> | |
301 | <tr> | |
302 | <th>startAngle</th> | |
303 | <td>float</td> | |
304 | <td>This is the angle of the start of the slice, in radians.</td> | |
305 | </tr> | |
306 | <tr> | |
307 | <th>endAngle</th> | |
308 | <td>float</td> | |
309 | <td>This is the angle of the end of the slice, in radians.</td> | |
310 | </tr> | |
311 | </tbody> | |
312 | </table> | |
313 | ||
314 | ||
315 | <h1> Layout Methods</h1> | |
316 | <ul> | |
317 | <li> | |
318 | <code>addDataset(name, values)</code> | |
319 | </li> | |
320 | </ul> | |
321 | <p> Adds a dataset to the layout engine and assigns it with <code>name</code>. <code>values</code> is an array of <code>\[x, y\]</code> values. | |
322 | </p> | |
323 | <ul> | |
324 | <li> | |
325 | <code>removeDataset(name)</code> | |
326 | </li> | |
327 | </ul> | |
328 | <p> Removes a dataset from the layout engine. In order for the new data to take effect, you must run <code>evaluate()</code>. | |
329 | </p> | |
330 | <ul> | |
331 | <li> | |
332 | <code>addDatasetFromTable(name, tableElement, xcol = 0, ycol = 1, labelCol = -1)</code> | |
333 | </li> | |
334 | </ul> | |
335 | <p> Handy function to read values off a table. <code>name</code> is the name to give to the dataset just like in <code>addDataset()</code>, <code>tableElement</code> is the table which contains the values. Optionally, the user may specify to extract alternative columns using <code>xcol</code> and <code>ycol</code>. | |
336 | </p> | |
337 | <p> <strong>New in 0.9.1:</strong> If <code>labelCol</code> is specified to a value greater than -1, it will take the contents of that column as the xTick labels. | |
338 | </p> | |
339 | <ul> | |
340 | <li> | |
341 | <code>evaluate()</code> | |
342 | </li> | |
343 | </ul> | |
344 | <p> Performs the evaluation of the layout. It is not done automatically, and you <strong>must</strong> execute this before passing the layout to a renderer. | |
345 | </p> | |
346 | <ul> | |
347 | <li> | |
348 | hitTest(x, y) | |
349 | </li> | |
350 | </ul> | |
351 | <p> Used by renderers to see if a virtual canvas position corresponds to any data. The return value varies per style. For <code>bar</code> charts, it will return the Bar type if it is a hit, or null if not. For <code>line</code> charts, it will return a value if the point is underneath the highest curve, otherwise null <strong>(TODO: expand this or change implementation)</strong>. For <code>pie</code> charts, it will return the Slice object that is at the point, otherwise null. | |
352 | </p> | |
353 | <p> <strong>Note that the specification of this function is subject to change</strong>. | |
354 | </p> | |
355 | ||
356 | <h1> Layout Notes</h1> | |
357 | ||
358 | <h2> Pie Chart Data and Ticks Restrictions</h2> | |
359 | <p>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. | |
360 | </p> | |
361 | <p>Labels for pie charts will only use xTicks. | |
362 | </p> | |
363 | ||
364 | <h1> Layout Examples</h1> | |
365 | ||
366 | ||
367 | </div> | |
368 | </div> | |
369 | ||
370 | ||
371 | ||
372 | ||
373 | <div id="footer"> | |
374 | <div class="block"> | |
375 | <h3>Syndication Feeds:</h3> | |
376 | <p> | |
377 | <ul class="tiny"> | |
378 | <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> | |
379 | <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> | |
380 | <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> | |
381 | <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> | |
382 | </ul> | |
383 | </p> | |
384 | </div> | |
385 | <div class="block"> | |
386 | <h3>About this site:</h3> | |
387 | <p>Content on this site is licensed under <a href="http://creativecommons.org/licenses/by/2.5/">CC By Attribution</a> unless otherwise specified. | |
388 | Copyright (c) 2002-2006, <a href="http://al.tse.id.au/">Alastair Tse</a>.</p> | |
389 | <p>For more information, see <a href="http://al.tse.id.au/">al.tse.id.au</a>.</p> | |
390 | <p><script type="text/javascript" src="http://technorati.com/embed/itwctkzez.js"></script></p> | |
391 | </div> | |
392 | <div class="block"> | |
393 | <h3>Is Made Possible By:</h3> | |
394 | <p> | |
395 | <dl> | |
396 | <dt><a href="http://ecto.kung-foo.tv/" class="clean">ecto</a>. </dt> | |
397 | <dd>Blogging client for Mac</dd> | |
398 | <dt><a href="http://djangoproject.com/" class="clean">Django</a>. </dt> | |
399 | <dd>Python Web Framework</dd> | |
400 | <dt><a href="http://www.lighttpd.net/" class="clean">lighttpd</a>. </dt> | |
401 | <dd>Really Fast Web Server</dd> | |
402 | <dt><a href="http://www.saddi.com/software/flup/" class="clean">flup</a>. </dt> | |
403 | <dd>FastCGI for Python</dd> | |
404 | </dl> | |
405 | </p> | |
406 | </div> | |
407 | <div class="block"> | |
408 | <h3>Search My Sites:</h3> | |
409 | <p> | |
410 | <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> | |
411 | </p> | |
412 | </div> | |
413 | ||
414 | ||
415 | <div class="clear"> </div> | |
416 | ||
417 | </div> | |
418 | ||
419 | ||
420 | ||
421 | <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script> | |
422 | <script type="text/javascript"> | |
423 | _uacct = "UA-58117-1"; | |
424 | urchinTracker(); | |
425 | </script> | |
426 | ||
427 | </body> | |
428 | </html> |