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