| 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> |