plotkit_v091/doc/PlotKit.Layout.html

   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">&lt;&lt;</a> | <a href="PlotKit.Renderer.html">&gt;&gt;</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">&nbsp;</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>