PlotKit.Layout.html
18.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en" >
<head>
<title>PlotKit.Layout | liquidx</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<link href="http://media.liquidx.net/css/x_general.css" media="screen" rel="Stylesheet" type="text/css" />
<link href="http://media.liquidx.net/css/x_header.css" media="screen" rel="Stylesheet" type="text/css" />
<link href="http://media.liquidx.net/css/x_layout.css" media="screen" rel="Stylesheet" type="text/css" />
<link href="http://media.liquidx.net/css/x_blocks.css" media="screen" rel="Stylesheet" type="text/css" />
<link rel="icon" href="/favicon.png" type="image/x-png">
<link rel="shortcut icon" href="/favicon.png" type="image/x-png">
<!--[if lt IE 7.]>
<script defer type="text/javascript" src="http://media.liquidx.net/js/pngfix.js"></script>
<![endif]-->
<link href="doc.css" media="screen" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="header">
<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>
<div id="menu-hack">
<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>
<div id="menu-main">
<ul id="menu" class="code">
<li class="tab" id="blog"><a href="http://www.liquidx.net/" title="blog/home">blog</a></li>
<li class="tab" id="code"><a href="http://www.liquidx.net/code/" title="software i have written">software</a></li>
<li class="tab" id="dev"><a href="http://projects.liquidx.net/" title="source code for my open source projects">dev</a></li>
<li class="tab" id="photos"><a href="http://al.tse.id.au/gallery/" title="photos and videos">photos</a></li>
<li class="tab" id="research"><a href="http://al.tse.id.au/research/" title="research profile">research</a></li>
<li class="tab" id="links"><a href="http://www.liquidx.net/links/" title="my bookmarks">linkblog</a></li>
<li class="tab" id="stats"><a href="http://stats.liquidx.net/" title="stats for various parts of my website">stats</a></li>
<li class="tab" id="status"><a href="http://www.liquidx.net/status/" title="weather report for alastair">status</a></li>
<li class="tab" id="about"><a href="http://al.tse.id.au/" title="about alastair tse">aboutme</a></li>
</ul>
</div>
</div>
<div id="quickbuttons">
<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>
<span class="quickbutton"><a href="http://www.liquidx.net/plotkit/"><img src="http://media.liquidx.net/imgx/quick_plotkit.png" alt="plotkit" /></a></span>
<span class="quickbutton"><a href="http://www.liquidx.net/fruity/"><img src="http://media.liquidx.net/imgx/quick_fruity.png" alt="fruity" /></a></span>
</div>
</div>
<div id="body">
<div class="page doc api">
<p> <a href="PlotKit.html">PlotKit Home</a> | <a href="PlotKit.Base.html"><<</a> | <a href="PlotKit.Renderer.html">>></a>
</p>
<h1> PlotKit Layout</h1>
<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.
</p>
<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.
</p>
<p>PlotKit Layout also is responsible for simple chart state querying so renderers can implement basic event support for objects on the canvas.
</p>
<h1> Constructor</h1>
<p> <code>new Layout(style, options);</code>
</p>
<p>Layout takes the following arguments:
</p>
<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.
</p>
<p> <strong>options</strong> is a dictionary/associative array of layout options. Unrecognised keys are ignored. The following options are supported:
</p>
<h1> Layout Options</h1>
<h2> Bar and Line Chart layout options</h2>
<table cellpadding="0" cellspacing="0">
<thead>
<tr><td>Option name</td><td>Description</td><td>Type</td><td>Default</td></tr>
</thead>
<tbody>
<tr>
<th>barWidthFillFraction</th>
<td>Amount of space the total amount of bars should consume per X value.</td>
<td>Real number</td>
<td>0.75</td>
</tr>
<tr>
<th>barOrientation</th>
<td>Orientation of a bar chart. <b>(PlotKit 0.9+ only)</b></td>
<td>String ("vertical", "horizontal")</td>
<td>vertical</td>
</tr>
<tr>
<th>xAxis</th>
<td>Minimum and Maximum values on the X axis.</td>
<td>Array of 2 Real numbers. (eg. [0.0, 10.0])</td>
<td>null</td>
</tr>
<tr>
<th>xNumberOfTicks</th>
<td>Used when automatically calculating axis ticks. This denotes the number of ticks there should be in the graph.</td>
<td>integer</td>
<td>10</td>
</tr>
<tr>
<th>xOriginIsZero</th>
<td>Should graph have X axis origin at 0</td>
<td>boolean</td>
<td>true</td>
</tr>
<tr>
<th>xTickPrecision</th>
<td>The number of decimal places we should round to for tick values.</td>
<td>integer</td>
<td>1</td>
</tr>
<tr>
<th>xTicks</th>
<td>X values at which ticks should be drawn. Automatically calculated if not defined using the parameters `xNumberOfTicks` and ``xTickPrecision``.</td>
<td>Array of {label: "somelabel", v:value}.</td>
<td>null</td>
</tr>
<tr>
<th>yAxis</th>
<td>Minimum and Maximum values on the Y axis.</td>
<td>Array of 2 Real numbers. (eg. [0.0, 10.0])</td>
<td>null</td>
</tr>
<tr>
<th>yNumberOfTicks</th>
<td>Used when automatically calculating axis ticks. This denotes the number of ticks there should be in the graph.</td>
<td>integer</td>
<td>5</td>
</tr>
<tr>
<th>yOriginIsZero</th>
<td>Should graph have Y axis origin at 0</td>
<td>true</td>
</tr>
<tr>
<th>yTickPrecision</th>
<td>The number of decimal places we should round to for tick values.</td>
<td>integer</td>
<td>1</td>
</tr>
<tr>
<th>yTicks</th>
<td>Y values at which ticks should be drawn. Automatically calculated if not defined using the parameters ``yNumberOfTicks`` and ``yTickPrecision``.</td>
<td>Array of {label: "somelabel", v:value}.</td>
<td>null</td>
</tr>
</tbody>
</table>
<h2> Pie Chart Layout Options</h2>
<table>
<thead>
<tr><td>Option name</td><td>Description</td><td>Type</td><td>Default</td></tr>
</thead>
<tbody>
<tr>
<th>pieRadius</th>
<td>Radius of the circle to be drawn.</td>
<td>Real number</td>
<td>0.4</td>
</tr>
</tbody>
</table>
<h1> Layout Properties</h1>
<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.
</p>
<table cellpadding="0" cellspacing="0">
<thead>
<tr><td>Property</td><td>Type</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<th>style</th>
<td>String</td>
<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>
</tr>
<tr>
<th>bars</th>
<td>Array of Bar.</td>
<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>
</tr>
<tr>
<th>points</th>
<td>Array of Point.</td>
<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>
</tr>
<tr>
<th>slices</th>
<td>Array of Slice.</td>
<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>
</tr>
<tr>
<th>xticks</th>
<td>Array of Tick.</td>
<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>
</tr>
<tr>
<th>yticks</th>
<td>Array of Tick.</td>
<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>
</tr>
<tr>
<th>datasets</th>
<td>Associative Array of datasets</td>
<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>
</tr>
</tbody>
</table>
<h1> Layout Types</h1>
<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.
</p>
<h2> Bar Type</h2>
<p>Represents a bar that the renderer will draw. It contains the following properties.
</p>
<table cellpadding="0" cellspacing="0">
<thead>
<tr><td>Property</td><td>Type</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<th>x, y</th>
<td>float</td>
<td>top left position of the bar between 0.0 and 1.0.</td>
</tr>
<tr>
<th>w, h</th>
<td>float</td>
<td>width and height of the bar from (``x``, ``y``) between 0.0 and 1.0.</td>
</tr>
<tr>
<th>xval, yval</th>
<td>float</td>
<td>The actual x value and y value this bar represents.</td>
</tr>
<tr>
<th>name</th>
<td>string</td>
<td>Name of the dataset which this bar belongs to.</td>
</tr>
</tbody>
</table>
<h2> Point Type</h2>
<p>This represents a point on a line chart.
</p>
<table cellpadding="0" cellspacing="0">
<thead>
<tr><td>Property</td><td>Type</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<th>x, y</th>
<td>float</td>
<td>top left position of the point between 0.0 and 1.0.</td>
</tr>
<tr>
<th>xval, yval</th>
<td>float</td>
<td>The actual x value and y value this bar represents.</td>
</tr>
<tr>
<th>name</th>
<td>string</td>
<td>Name of the dataset which this bar belongs to.</td>
</tr>
</tbody>
</table>
<h2> Slice Type</h2>
<p>This represents a pie slice in a pie chart.
</p>
<table>
<thead>
<tr><td>Property</td><td>Type</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<th>fraction</th>
<td>float</td>
<td>The fractional value this slice represents. This number is between 0.0 and 1.0</td>
</tr>
<tr>
<th>xval, yval</th>
<td>float</td>
<td>The x and y values of this slice.</td>
</tr>
<tr>
<th>startAngle</th>
<td>float</td>
<td>This is the angle of the start of the slice, in radians.</td>
</tr>
<tr>
<th>endAngle</th>
<td>float</td>
<td>This is the angle of the end of the slice, in radians.</td>
</tr>
</tbody>
</table>
<h1> Layout Methods</h1>
<ul>
<li>
<code>addDataset(name, values)</code>
</li>
</ul>
<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.
</p>
<ul>
<li>
<code>removeDataset(name)</code>
</li>
</ul>
<p> Removes a dataset from the layout engine. In order for the new data to take effect, you must run <code>evaluate()</code>.
</p>
<ul>
<li>
<code>addDatasetFromTable(name, tableElement, xcol = 0, ycol = 1, labelCol = -1)</code>
</li>
</ul>
<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>.
</p>
<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.
</p>
<ul>
<li>
<code>evaluate()</code>
</li>
</ul>
<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.
</p>
<ul>
<li>
hitTest(x, y)
</li>
</ul>
<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.
</p>
<p> <strong>Note that the specification of this function is subject to change</strong>.
</p>
<h1> Layout Notes</h1>
<h2> Pie Chart Data and Ticks Restrictions</h2>
<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.
</p>
<p>Labels for pie charts will only use xTicks.
</p>
<h1> Layout Examples</h1>
</div>
</div>
<div id="footer">
<div class="block">
<h3>Syndication Feeds:</h3>
<p>
<ul class="tiny">
<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>
<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>
<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>
<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>
</ul>
</p>
</div>
<div class="block">
<h3>About this site:</h3>
<p>Content on this site is licensed under <a href="http://creativecommons.org/licenses/by/2.5/">CC By Attribution</a> unless otherwise specified.
Copyright (c) 2002-2006, <a href="http://al.tse.id.au/">Alastair Tse</a>.</p>
<p>For more information, see <a href="http://al.tse.id.au/">al.tse.id.au</a>.</p>
<p><script type="text/javascript" src="http://technorati.com/embed/itwctkzez.js"></script></p>
</div>
<div class="block">
<h3>Is Made Possible By:</h3>
<p>
<dl>
<dt><a href="http://ecto.kung-foo.tv/" class="clean">ecto</a>. </dt>
<dd>Blogging client for Mac</dd>
<dt><a href="http://djangoproject.com/" class="clean">Django</a>. </dt>
<dd>Python Web Framework</dd>
<dt><a href="http://www.lighttpd.net/" class="clean">lighttpd</a>. </dt>
<dd>Really Fast Web Server</dd>
<dt><a href="http://www.saddi.com/software/flup/" class="clean">flup</a>. </dt>
<dd>FastCGI for Python</dd>
</dl>
</p>
</div>
<div class="block">
<h3>Search My Sites:</h3>
<p>
<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>
</p>
</div>
<div class="clear"> </div>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
<script type="text/javascript">
_uacct = "UA-58117-1";
urchinTracker();
</script>
</body>
</html>