plotkit_v091/doc/PlotKit.Layout.txt

   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