RGraph/docs/api.html

   1 <?php ob_start('ob_gzhandler') ?>
   2 <!DOCTYPE html>
   3 <html>
   4 <head>
   5     <meta http-equiv="X-UA-Compatible" content="chrome=1">
   6     <!--
   7         /**
   8         * o------------------------------------------------------------------------------o
   9         * | This file is part of the RGraph package - you can learn more at:             |
  10         * |                                                                              |
  11         * |                          http://www.rgraph.net                               |
  12         * |                                                                              |
  13         * | This package is licensed under the RGraph license. For all kinds of business |
  14         * | purposes there is a small one-time licensing fee to pay and for non          |
  15         * | commercial  purposes it is free to use. You can read the full license here:  |
  16         * |                                                                              |
  17         * |                      http://www.rgraph.net/LICENSE.txt                       |
  18         * o------------------------------------------------------------------------------o
  19         */
  20     -->
  21     <title>RGraph: HTML5 canvas graph library - API documentation</title>
  22
  23     <meta name="keywords" content="rgraph html5 canvas graph docs api" />
  24     <meta name="description" content="RGraph: HTML5 canvas graph software - Documentation about the RGraph API" />
  25
  26     <link rel="stylesheet" href="../css/website.css" type="text/css" media="screen" />
  27     <link rel="icon" type="image/png" href="../images/favicon.png">
  28 </head>
  29 <body>
  30
  31     <!-- Social networking buttons -->
  32     <script src="../libraries/RGraph.common.core.js" ></script>
  33
  34     <script>
  35         function HideTwitterDIV ()
  36         {
  37             document.getElementById("twitter_div").style.opacity = 0;
  38             document.getElementById("twitter_div").style.display = 'none';
  39         }
  40
  41
  42         function ShowTwitterDIV (e)
  43         {
  44             var e   = RGraph.FixEventObject(document.all ? event : e);
  45             var div = document.getElementById("twitter_div");
  46             var img = document.getElementById("twitter_icon");
  47
  48             div.style.display = 'block';
  49             div.style.left    = (RGraph.getCanvasXY(img)[0] + img.offsetWidth - div.offsetWidth + 110) + 'px';
  50             div.style.top     = (RGraph.getCanvasXY(img)[1] - 1) + 'px';
  51
  52             /**
  53             * Fade it in
  54             */
  55             setTimeout('document.getElementById("twitter_div").style.opacity = 0.2;', 25);
  56             setTimeout('document.getElementById("twitter_div").style.opacity = 0.4;', 50);
  57             setTimeout('document.getElementById("twitter_div").style.opacity = 0.6;', 100);
  58             setTimeout('document.getElementById("twitter_div").style.opacity = 0.8;', 125);
  59             setTimeout('document.getElementById("twitter_div").style.opacity = 1.0;', 150);
  60
  61             e.stopPropagation();
  62
  63             return false;
  64         }
  65
  66         /**
  67         * This code installs the event handler that hides the Twitter DIV
  68         */
  69         if (RGraph.isIE8()) {
  70              window.attachEvent('onload', function () {document.body.attachEvent('onclick', HideTwitterDIV);});
  71         } else {
  72             window.addEventListener('click', HideTwitterDIV, false);
  73         }
  74     </script>
  75
  76     <!-- The twitter DIV -->
  77     <div id="twitter_div" style="position: absolute;top: 0;left: 0;background-color: #eee;border: 2px dashed black;box-shadow: 0 0 15px #aaa;-moz-box-shadow: 0 0 15px #aaa;-webkit-box-shadow: 0 0 15px #aaa;padding: 3px;display: none;opacity: 0;z-index: 99;">
  78         <a href="http://twitter.com/home/?status=RGraph%3A+HTML5+canvas+graph+library+based+on+the+HTML5+canvas+tag+http%3A%2F%2Fwww.rgraph.net+%23rgraph+%23html5+%23canvas" target="_blank" title="Share on Twitter" rel="nofollow" style="text-decoration: none">Tweet&nbsp;about&nbsp;RGraph</a><br>
  79         <a href="http://twitter.com/_rgraph" style="text-decoration: none" rel="nofollow" target="_blank">Follow for HTML5 news</a>
  80     </div>
  81
  82     <div id="social_icons" class="warning" style="top: 0; left: 5px; position: absolute">
  83         <script>
  84             // Opera fix
  85             if (navigator.userAgent.indexOf('Opera') == -1) {
  86               document.getElementById("social_icons").style.position = 'fixed';
  87               document.getElementById("twitter_div").style.position = 'fixed';
  88
  89             }
  90         </script>
  91
  92         <b style="display: inline-block; position: relative; top: 1px">Bookmark and share:</b>
  93
  94
  95             <div id="social">
  96                 <a title="Bookmark with delicious" href="http://delicious.com/save?jump=close&v=4&noui&jump=close&url=http://www.rgraph.net&notes=RGraph%20is%20a%20HTML5%20based%20graph%20library%20supporting%20a%20wide%20range%20of%20different%20graph%20types:Bar,%20Bipolar,%20Donut,%20Funnel,%20Gantt,%20Horizontal%20Bar,%20LED,%20Line,%20Meter,%20Odometer,%20Pie,%20Progress%20Bar,%20Rose,%20RScatter,%20Scatter%20and%20Traditional%20Radar&title=RGraph:%20HTML5%20canvas%20graph%20library%20based%20on%20the%20HTML5%20canvas%20tag" target="_blank">
  97                     <img src="../images/delicious.png" alt="Bookmark with delicious" width="22" height="22" border="0" align="absmiddle" />
  98                 </a>
  99
 100                 <a href="" target="_blank" onmouseover="if (document.getElementById('twitter_div').style.display == 'none') ShowTwitterDIV(event);" onclick="event.stopPropagation(); event.cancelBubble = true; return false">
 101                     <img src="../images/twitter.png" id="twitter_icon" alt="tweet this site" width="22" height="22" border="0" align="absmiddle" />
 102                 </a>
 103
 104
 105 <!--
 106                 <a title="Post to Google Buzz!" href="" onclick="window.open('http://www.google.com/buzz/post?url=http://www.rgraph.net&imageurl=http://www.rgraph.net/images/logo.png', 'google_buzz_window', 'width=800,height=400,top=100,left=100'); return false">
 107                     <img src="../images/buzz.png" width="22" height="22" alt="Post to Google Buzz!" align="absmiddle" style="position: relative; top: -2px; border: 0" border="0"/>
 108                 </a>
 109
 110
 111                 <a title="Share RGraph on Facebook" href="" onclick="window.open('http://www.facebook.com/sharer.php?u=http://www.rgraph.net&t=RGraph:%20HTML5%20canvas%20graph%20library', 'facebook_window', 'width=500,height=300,top=100,left=100'); return false">
 112                     <img src="../images/facebook.png" width="22" height="22" alt="Post to Facebook" align="absmiddle" style="position: relative; top: -2px; border: 0" border="0"/>
 113                 </a>
 114
 115                 <a href="mailto:share@friendfeed.com" title="Share on FriendFeed">
 116                     <img src="../images/friendfeed.png" width="22" height="22" alt="Share on FriendFeed" border="0" align="absmiddle" />
 117                 </a>
 118
 119                 <a href="http://www.stumbleupon.com/submit?url=http://www.rgraph.net" target="_blank" title="Share on StumbleUpon" >
 120                     <img src="../images/stumble.png" alt="Stumble! this site" width="22" height="22" border="0" align="absmiddle" />
 121                 </a>
 122 -->
 123             </div>
 124     </div>
 125     <!-- /Social networking buttons -->
 126
 127     <div id="breadcrumb">
 128         <a href="../index.html">RGraph: HTML5 canvas graph library</a>
 129         >
 130         <a href="index.html">Documentation</a>
 131         >
 132         API Documentation
 133     </div>
 134
 135     <h1>RGraph: HTML5 canvas graph library - API documentation</h1>
 136
 137     <script>
 138         if (RGraph.isIE8()) {
 139             document.write('<div style="background-color: #fee; border: 2px dashed red; padding: 5px"><b>Important</b><br /><br /> Internet Explorer 8 does not natively support the HTML5 canvas tag, so if you want to see the graphs, you can either:<ul><li>Install <a href="http://code.google.com/chrome/chromeframe/">Google Chrome Frame</a></li><li>Use ExCanvas. This is provided in the RGraph Archive.</li><li>Use another browser entirely. Your choices are Firefox 3.5+, Chrome 2+, Safari 4+ or Opera 10.5+. </li></ul> <b>Note:</b> Internet Explorer 9 fully supports the canvas tag. Click <a href="http://groups.google.com/group/rgraph/browse_thread/thread/c5651ff8c56b8f3c#" target="_blank">here</a> to see some screenshots.</div>');
 140         }
 141     </script>
 142
 143     <br />
 144
 145     <ul>
 146         <li><a href="#overview">Overview</a></li>
 147         <li><a href="#references">Canvas and context references</a></li>
 148         <li><a href="#events">Working with events</a></li>
 149         <li><a href="#coords">Working with graph coordinates</a></li>
 150         <li><a href="#data">Working with graph data</a></li>
 151         <li><a href="#updating">Updating your graphs dynamically</a></li>
 152         <li><a href="#accessors">Setting properties</a></li>
 153         <li><a href="#references.other">References available on RGraph objects</a></li>
 154         <li><a href="#scale">Scale information</a></li>
 155         <li><a href="#text">Adding text to your graphs</a></li>
 156         <li>
 157             <a href="#functions">RGraph functions</a>
 158             <ul>
 159                 <li><a href="#functions.arrays">Arrays</a></li>
 160                 <li><a href="#functions.strings">Strings</a></li>
 161                 <li><a href="#functions.numbers">Numbers</a></li>
 162                 <li><a href="#functions.misc">Miscellaneous</a></li>
 163                 <li><a href="#functions.events">Custom RGraph event related functions</a></li>
 164                 <li><a href="#functions.other">Other</a></li>
 165             </ul>
 166         </li>
 167         <li><a href="#skeleton">The skeleton file</a></li>
 168         <li><a href="#questions">Questions</a></li>
 169     </ul>
 170
 171     <a name="overview"></a>
 172     <h4>Overview</h4>
 173
 174     <p>
 175         Working with RGraph objects is purposefully easy, to make them straight forward to integrate into your own scripts if you want to. For any
 176         particular graph type there are a few files required - the common libraries and the graph specific library. Eg:
 177     </p>
 178
 179     <pre class="code">
 180 &lt;script src="RGraph.common.core.js"&gt;&lt;/script&gt;
 181 &lt;script src="RGraph.bar.js"&gt;&lt;/script&gt;
 182 </pre>
 183
 184     <p>
 185         <i>RGraph.common.core.js</i> is a function library that contains a large set of functions that support the graph classes.
 186         Some functions, and sets of functions, have their own files. For example, the zoom functions reside in <i>RGraph.common.zoom.js</i>,
 187         so if you don't need zoom, you don't need this file.
 188         Each of the graph libraries (<i>RGraph.*.js</i>) contains that particular graphs class. If you'd like to see a "bare bones"
 189         implementation, you can look at the <a href="../examples/basic.html">basic example</a>. There's also a
 190         <a href="#skeleton">skeleton example</a> to make it easier to create new graph types.
 191     </p>
 192
 193     <a name="references"></a>
 194     <h4>Canvas and context references</h4>
 195
 196     <p>
 197         Each graph object maintains references to the <i>context</i> and <i>canvas</i> as properties. So to get hold of them all you
 198         need to do is this:
 199     </p>
 200
 201     <pre class="code">
 202 &lt;script&gt;
 203     window.onload = function ()
 204     {
 205         // 1/2 First draw the chart
 206         var myBar = new RGraph.Bar('myCanvas', [1,5,8,4,6,3,1,5,7,8,4,6]);
 207         myBar.Set('chart.labels', ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']);
 208         myBar.Draw();
 209
 210         // 2/2 Now get hold of the references
 211         var context = myBar.context; // Get hold of a reference to the context
 212         var canvas  = myBar.canvas;  // Get hold of a reference to the canvas
 213     }
 214 &lt;/script&gt;
 215 </pre>
 216
 217     <a name="events"></a>
 218     <h4>Working with events</h4>
 219
 220     <p>
 221         When working with events, you may come across the situation where you have a reference to the <i>canvas</i>, but
 222         also need to access the graph object. For this reason the constructor of each object adds a reference to the object to the
 223         canvas and you can access it like this:
 224     </p>
 225
 226     <pre class="code">
 227 &lt;script&gt;
 228     document.getElementById("myCanvas").onclick = function (e)
 229     {
 230         var src = (RGraph.isIE8() ? event.srcElement) : e.target;
 231
 232         // The RGraph object constructors add __object__ to the canvas.
 233         var myBar = src.__object__;
 234     }
 235 &lt;/script&gt;
 236 </pre>
 237
 238     <a name="coords"></a>
 239     <h4>Working with graph coordinates</h4>
 240
 241     <p>
 242         For most graph types, the coordinates of elements (eg bars, lines etc) are to be found in the class variable <i>obj.coords</i>.
 243         This is usually a multi-dimensional array consisting of the coordinates of those shapes, or of points. As an example the bar
 244         chart maintains the X, Y, width and height of each bar (or sections of bars in a stacked bar chart). The coords array is
 245         usually a flat array, even when you have multiple sets of data.
 246     </p>
 247
 248     <p>
 249         By using the RGraph.getMouseXY() function and this array you can determine if a bar was clicked on, or if the mouse is near a
 250         line point etc.
 251     </p>
 252
 253     <pre class="code">
 254 var myCoords = myBar.coords;
 255 </pre>
 256
 257     <p>
 258         <b>Note:</b> Previously the coords array values sometimes included the margin values, and sometimes didn't. As of 17th
 259         April 2010 the values have all been unified to not include the margin values, so the values are as reported.
 260     </p>
 261
 262     <a name="data"></a>
 263     <h4>Working with graph data</h4>
 264
 265     <p>
 266         Another variable you may need is the <i>data</i> variable. For most graph types, this is where the data is stored. It is usually
 267         untouched, so it is as you supplied to the graph objects constructor. A notable exception to this is filled line charts.
 268         Here the original data is stored in the class variable <i>original_data</i>. The data supplied is modified to produce the stacking
 269         effect. If you need to modify a filled line charts data you will need to change this variable instead.
 270     </p>
 271
 272     <p>
 273         Not all graph types use the <i>data</i> variable. For some the name is different so that it makes a little more sense. The
 274         graph types and their associate data variables are listed below<sup>1</sup>.
 275     </p>
 276
 277     <style>
 278         table#data_properties td,
 279         th {
 280             text-align: center;
 281         }
 282     </style>
 283
 284     <table border="0" align="center" id="data_properties">
 285         <tr>
 286             <th>Graph type</th>
 287             <th>Data variable(s)</th>
 288         </tr>
 289
 290         <tr>
 291             <td>Bar</td>
 292             <td>obj.data</td>
 293         </tr>
 294
 295         <tr>
 296             <td>Bi-polar</td>
 297             <td>obj.left, obj.right</td>
 298         </tr>
 299
 300         <tr>
 301             <td>Donut</td>
 302             <td>This is now a variant of the Pie chart</td>
 303         </tr>
 304
 305         <tr>
 306             <td>Funnel</td>
 307             <td>obj.data</td>
 308         </tr>
 309
 310         <tr>
 311             <td>Gantt</td>
 312             <td>See the <a href="gantt.html#events">docs</a></td>
 313         </tr>
 314
 315         <tr>
 316             <td>Horizontal Bar</td>
 317             <td>obj.data</td>
 318         </tr>
 319
 320         <tr>
 321             <td>Horizontal Progress bar</td>
 322             <td>obj.max, obj.value</td>
 323         </tr>
 324
 325         <tr>
 326             <td>LED</td>
 327             <td>obj.text</td>
 328         </tr>
 329
 330         <tr>
 331             <td>Line</td>
 332             <td>obj.original_data<sup>3</sup></td>
 333         </tr>
 334
 335         <tr>
 336             <td>Meter</td>
 337             <td>obj.min, obj.max, obj.value</td>
 338         </tr>
 339
 340         <tr>
 341             <td>Odometer</td>
 342             <td>obj.start, obj.end, obj.value</td>
 343         </tr>
 344
 345         <tr>
 346             <td>Pie</td>
 347             <td>obj.angles, obj.data</td>
 348         </tr>
 349
 350         <tr>
 351             <td>Radial Scatter chart</td>
 352             <td>obj.data</td>
 353         </tr>
 354
 355         <tr>
 356             <td>Rose</td>
 357             <td>obj.max, obj.data</td>
 358         </tr>
 359
 360         <tr>
 361             <td>Scatter</td>
 362             <td>obj.max, obj.data<sup>2</sup></td>
 363         </tr>
 364
 365         <tr>
 366             <td>Traditional Radar</td>
 367             <td>obj.data, obj.max</td>
 368         </tr>
 369
 370         <tr>
 371             <td>Vertical Progress bar</td>
 372             <td>obj.max, obj.value</td>
 373         </tr>
 374     </table>
 375
 376     <ol>
 377         <li style="margin-top: 0">In the table, <i>obj</i> refers to your graph object.</li>
 378         <li style="margin-top: 0">For the Scatter chart, each data point is an array of X/Y coordinates, the color and the tooltip for that point.</li>
 379         <li  style="margin-top: 0">
 380             The Line chart <i>obj.original_data</i> is an aggregation of all the datasets given to the Line chart, so the first
 381             dataset is held in <i>obj.original_data[0]</i>, the second in <i>obj.original_data[1]</i> etc.
 382         </li>
 383     </ol>
 384
 385     <a name="updating"></a>
 386     <h4>Updating your graphs dynamically</h4>
 387
 388         <p style="background-color: #ffa; padding: 3px; border: 1px dashed black">
 389             <b>Note:</b>
 390             It is important that you're careful with types when making AJAX requests. Since the response is initially a string,
 391             and your AJAX function/library may not do conversions for you, you may need to convert these strings to numbers. To
 392             do this you can use the <i>Number()</i> or <i>parseInt()</i> functions. For example:
 393         </p>
 394
 395         <pre class="code">
 396 &lt;script&gt;
 397     num = Number('23');
 398     num = parseInt('43');
 399 &lt;/script&gt;
 400 </pre>
 401
 402         <p>
 403             A common request is to be able to update graphs dynamically. This is quite simple and consists of three steps:
 404         </p>
 405
 406         <ol>
 407             <li style="margin-top: 0">Get the new data from the server (with an AJAX request for example).</li>
 408             <li style="margin-top: 0">Set the data in your graph object. See the above table for the appropriate property to use.</li>
 409             <li style="margin-top: 0">Call the .Draw() method again.</li>
 410         </ol>
 411
 412         <p>
 413             If you don't need to get data from your server (ie it's all client-side) then you can omit the first step. Also, it may be
 414             sufficient to simply recreate the entire object from scratch. This means that you won't have to alter and
 415             RGraph internal properties - just recreate the graph object and configuration. There's a simple function
 416             you can use for AJAX purposes <a href="index.html#ajax">here</a>.
 417         </p>
 418
 419
 420     <a name="accessors"></a>
 421     <h4>Setting properties</h4>
 422
 423         <p>
 424             To set RGraph properties, ideally you should use each objects setter  (there's also a corresponding getter). These functions
 425             accomodate some backwards compatibility changes, so by not using them you run the risk of your graphs not working entirely as
 426             expected.
 427         </p>
 428
 429     <pre class="code">
 430 myObj.Set('chart.gutter', 25);
 431 myObj.Get('chart.gutter');
 432 </pre>
 433
 434     <a name="references.other"></a>
 435     <p>&nbsp;</p>
 436     <h4>References available on RGraph objects</h4>
 437         <p>
 438             RGraph stores various references to objects on the canvas (typically) to make getting hold of them easier. There's also a
 439             Registry object in
 440             which references are stored. Typically the objects are named with the format <i>__xxx__</i>, and you can inspect the
 441             objects by using a console(eg the inspector that's part of Google Chrome - <i>CTRL+SHIFT+J</i>). Some examples are:
 442         </p>
 443
 444         <ul>
 445             <li>__object__ on the canvas - a reference to the graph object</li>
 446             <li>
 447                 RGraph.Registry.Get('chart.tooltip') - a reference to the currently visible tooltip. This in turn has the following
 448                 available:
 449                     <ul>
 450                         <li>__text__ - Since setting .innerHTML can cause changes in HTML, this is the original tooltip text.</li>
 451                         <li>__index__ - This is the numerical index corresponding to the tooltips array that you set.</li>
 452                         <li>__dataset__ - Used in the Scatter chart and corresponding to the dataset.</li>
 453                         <li>__canvas__ - A reference to the original canvas that triggered the tooltip.</li>
 454                     </ul>
 455             </li>
 456             <li>
 457                 RGraph.Registry.Get('chart.mousedown') - Used in annotating, and stipulates whether the mouse button is currently
 458                 pressed.
 459             </li>
 460             <li>
 461                 RGraph.Registry.Get('chart.contextmenu') - The currently shown context menu, if any. This in turn has the following
 462                 properties:
 463                 <ul>
 464                     <li>__canvas__ - The original canvas object.</li>
 465                 </ul>
 466             </li>
 467         </ul>
 468
 469         These are just a sample of what's available, to find more you should use an introspection tool, look at the source, or ask
 470         on the <a href="http://groups.google.com/group/rgraph/topics?gvc=2" target="_blank">support mailing list</a>.
 471
 472
 473
 474     <a name="scale"></a>
 475     <h4>Scale information</h4>
 476         <p>
 477             For the Bar, Bipolar, HBar, Line and Scatter charts the scale that is used is stored in the <i>scale</i> class variable. Eg:
 478         </p>
 479
 480         <pre class="code">
 481 &lt;script&gt;
 482     var myBar = new RGraph.Bar('cvs', [56,43,52,54,51,38,46,42,52]);
 483     myBar.Draw();
 484
 485     var myScale = myBar.scale
 486 &lt;/script&gt;
 487 </pre>
 488
 489     <a name="text"></a>
 490     <h4>Adding text to your graphs</h4>
 491         <p>
 492             If you want to add arbitrary text to your graph(s) you can use the API function <a href="#functions.other">RGraph.Text().</a>
 493         </p>
 494
 495         <pre class="code">
 496 &lt;script&gt;
 497     // Draw a basic graph
 498     var myObj = new RGraph.Bar('myCanvas', [4,5,5,8,7,6,4,8,5,9]);
 499     myObj.Draw();
 500
 501     // Draw some text
 502     myObj.context.beginPath();
 503         size = 12;
 504         font = 'Verdana';
 505         text = 'Some text!;
 506         x    = 10;
 507         y    = 10;
 508
 509         RGraph.Text(myObj.context, font, size, x, y, text);
 510     myObj.context.fill();
 511 &lt;/script&gt;
 512 </pre>
 513
 514     <a name="functions"></a>
 515     <h4>RGraph functions</h4>
 516
 517         <p>
 518             This is a list of some of the functions available to you in the RGraph common libraries.
 519             It's not every single one that's available, but is a list of the common ones that you're likely to want to use. Arguments
 520             in square brackets are optional.
 521         </p>
 522
 523     <pre class="code">
 524 &lt;script src="RGraph.common.core.js"&gt;&lt;/script&gt;
 525
 526 &lt;script&gt;
 527     // Returns 9
 528     myArray = [3,2,5,4,9,7,8];
 529     max = RGraph.array_max(myArray);
 530 &lt;/script&gt;
 531 </pre>
 532
 533     <a name="functions.arrays"></a>
 534     <h4>Arrays</h4>
 535
 536     <ul>
 537         <li><b>(number) RGraph.array_max(array)</b><br />Returns the maximum value in the array.<br /><i>File: RGraph.common.core.js</i><p /></li>
 538         <li><b>(number) RGraph.array_sum(array)</b><br />Returns the sum of all values in the array. You can also pass a single integer, in which case it is simply returned as-is.<br /><i>File: RGraph.common.core.js</i><p /></li>
 539         <li><b>(array) RGraph.array_clone(array)</b><br />Creates a copy/clone of the given array. Only numerically indexed arrays are supported.<br /><i>File: RGraph.common.core.js</i><p /></li>
 540         <li><b>(array) RGraph.array_reverse(array)</b><br />Returns a reversal of the given array.<br /><i>File: RGraph.common.core.js</i><p /></li>
 541         <li><b>(boolean) RGraph.is_array(obj)</b><br />Returns true or false as to whether the given object is an array or not.<br /><i>File: RGraph.common.core.js</i><p /></li>
 542         <li><b>(array) RGraph.array_pad(array, length[, value])</b><br />Pads the given array to the specified length (if the length is less, if not the array is returned as is). The third, optional, argument is the value which is used as the pad value. If not specified, <i>null</i> is used.<br /><i>File: RGraph.common.core.js</i><p /></li>
 543         <li><b>(array) RGraph.array_shift(array)</b><br />Shifts an element off of the start of the given array and returns the new array.<br /><i>File: RGraph.common.core.js</i><p /></li>
 544     </ul>
 545
 546     <a name="functions.strings"></a>
 547     <h4>Strings</h4>
 548
 549     <ul>
 550         <li><b>(string) RGraph.rtrim(string)</b><br />Strips the right hand white space from the string that you pass it.<br /><i>File: RGraph.common.core.js</i><p /></li>
 551         <li>
 552             <b>(string) RGraph.number_format(obj, number[, prepend[, append]])</b><br />
 553             This formats the given number (which can be either an integer or a float. The prepend and append variables are
 554             strings which are added to the string (eg 5%).<br /><br />
 555             <b>Note:</b>As of 5th September 2010 this functions argument list has been changed to include the graph object, as shown above.<br /><br />
 556             <i>File: RGraph.common.core.js</i><p />
 557         </li>
 558     </ul>
 559
 560     <a name="functions.numbers"></a>
 561     <h4>Numbers</h4>
 562
 563     <ul>
 564         <li><b>(number) RGraph.random(min, max)</b><br />Returns a random number between the minimum and maximum that you give.<br /><i>File: RGraph.common.core.js</i><br /><br /></li>
 565         <li><b>(string) RGraph.number_format(number[, prepend[, append]])</b><br />See <a href="#functions.strings">above</a>.<br /><i>File: RGraph.common.core.js</i></li>
 566     </ul>
 567
 568     <a name="functions.misc"></a>
 569     <h4>Miscellaneous</h4>
 570
 571     <ul>
 572         <li>
 573             <b>(object) RGraph.FixEventObject(event)</b><br />Pass this function an event object and it will attempt to "fill in" the missing properties (depending on the browser).
 574             It tries to add:<br /><br />
 575
 576             <ul>
 577                 <li>pageX (MSIE)</li>
 578                 <li>pageY (MSIE)</li>
 579                 <li>target (MSIE)</li>
 580                 <li>stopPropagation() (MSIE)</li>
 581                 <li>offsetX (FF)</li>
 582                 <li>offsetY (FF)</li>
 583             </ul>
 584             <br /><i>File: RGraph.common.core.js</i>
 585             <p />
 586         </li>
 587         <li><b>(null) RGraph.OldBrowserCompat(context)</b><br />This function "fills in" any required functions that some browsers don't have. At the moment this consists of adding the measureText() and fillText() functions to the context when they're missing (usually this means older versions of Opera).<br /><i>File: RGraph.common.core.js</i><p /></li>
 588         <li><b>(number) RGraph.GetDays(date)</b><br />This returns the number of days in the given month. The argument should be a Date object.<br /><i>File: RGraph.common.core.js</i><p /></li>
 589         <li><b>(null) RGraph.pr(mixed)</b><br />Emulates the PHP function print_r() by recursively printing the structure of whatever you pass to it. It handles numbers, strings, arrays, booleans, functions and objects.<br /><i>File: RGraph.common.core.js</i><p /></li>
 590         <li><b>(null) p(mixed)</b><br />An alias of the above albeit far shorter to type.<br /><i>File: RGraph.common.core.js</i><p /></li>
 591         <li><b>(null) cl(mixed)</b><br />A shortcut for the Firebug and Google Chrome debug function console.log().<br /><i>File: RGraph.common.core.js</i><p /></li>
 592         <li><b>(null) RGraph.Clear(canvas[, color])</b><br />Clears the canvas by drawing a white (or the optional color you give) rectangle over it.<br /><i>File: RGraph.common.core.js</i><p /></li>
 593         <li>
 594             <b>(null) RGraph.ClearAnnotations(id)</b><br />This function clears the annotation data associated with the given canvas ID (but DOES NOT redraw the graph). If you want to clear the visible annotations too, you will need to redraw the canvas. You could do this using the following code:
 595             <br />
 596             <pre class="code">
 597 function ClearAndRedraw (obj)
 598 {
 599     RGraph.Clear(obj.canvas); // This function also calls the RGraph.ClearAnnotations() function
 600     obj.Draw();
 601 }</pre>
 602         <br /><i>File: RGraph.common.annotatate.js</i><p />
 603         </li>
 604         <li><b>(null) RGraph.ReplayAnnotations(object)</b><br />This function redraws any annotations which have previously been drawn on the canvas. You would use this function when annotations are turned off and you want previous annotations to be displayed.<br /><i>File: RGraph.common.annotate.js</i><p /></li>
 605         <li><b>(array) RGraph.getMouseXY(event)</b><br />When passed your event object, it returns the X and Y coordinates (in relation to the canvas) of the mouse pointer. (0,0) is in the top left corner, with the X value increasing going right and the Y value increasing going down.<br /><i>File: RGraph.common.core.js</i><p /></li>
 606         <li><b>(array) RGraph.getCanvasXY(event)</b><br />Similar to the above function but returns the X/Y coordinates of the canvas in relation to the page.<br /><i>File: RGraph.common.core.js</i><p /></li>
 607         <li><b>(number) RGraph.degrees2Radians(number)</b><br />Converts and returns the given number of degrees to radians. 1 radian = 57.3 degrees.<br /><i>File: RGraph.common.core.js</i><p /></li>
 608         <li><b>(array) RGraph.getScale(max, obj)</b><br />Given the maximum value this will return an appropriate scale. The second argument is the graph object.<br /><i>File: RGraph.common.core.js</i><p /></li>
 609         <li><b>(mixed) RGraph.Registry.Get(name)</b><br />In conjunction with the next function, this is an implementation of the Registry pattern which can be used for storing settings.<br /><i>File: RGraph.common.core.js</i><br /><br /></li>
 610         <li><b>(mixed) RGraph.Registry.Set(name, value)</b><br />In conjunction with the previous function, this is an implementation of the Registry pattern which can be used for storing settings.<br /><i>File: RGraph.common.core.js</i><br /><br /></li>
 611         <li><b>(null) RGraph.Register(object)</b><br />This function is used in conjunction with the next to register a canvas for redrawing. Canvases are redrawn (for example) when tooltips or crosshairs are being used.<br /><i>File: RGraph.common.core.js</i><br /><br /></li>
 612
 613         <li>
 614             <b>(null) RGraph.Redraw([id, [color]])</b><br />This function is used in conjunction with the previous to redraw a canvas. Canvases are redrawn (for example) when tooltips or crosshairs are being used.<br /><br /> <b>Note:</b> All canvases that are registered are redrawn. However the optional first argument can be an ID (a string) of the canvas that is NOT to be redrawn. The optional second argument is the color to use when clearing canvases.<br /><i>File: RGraph.common.core.js</i><br /><br />
 615         </li>
 616
 617         <li><b>(null) RGraph.SetShadow(object, color, offetX, offsetY, blur)</b><br />This function is a shortcut function used to set the four shadow properties. The arguments are: your graph object, the shadow color, the X offset, the Y offset, the shadow blur.<br /><i>File: RGraph.common.core.js</i><br /><br /></li>
 618         <li><b>(null) RGraph.NoShadow(object)</b><br />This function is a shortcut function used to "turn off" the shadow. The argument is your graph object.<br /><i>File: RGraph.common.core.js</i><br /><br /></li>
 619         <li><b>(array) RGraph.getSegment(event)</b><br />This function can be used with the Pie (including the donut variant) and Rose charts to get segment information when the canvas is clicked on (or the mouse is moved). It returns an array consisting of: <p /><ul><li>The center X coordinate</li><li>The center Y coordinate</li> <li>The radius</li><li>The start angle (in degrees)</li><li>The end angle (in degrees)</li></ul><br />Angles are measured starting from the "east" axis.<br /><i>File: RGraph.common.core.js</i><br /><br /></li>
 620         <li>
 621             <b>(number) RGraph.Async(mixed[, delay])</b><br />This is a simple function but has significant implications on your pages performance. You
 622             can pass this either a function pointer, or a string containing the code to run and it will run the code asynchronously (ie in
 623             parallel to the page loading). In doing so it can mean that your page is displayed faster, as the graph is created
 624             seperate to the page loading. As such, the placement of your canvas tag becomes more important. What you can do is
 625             define the canvas tag and then the code to produce the graph immediately after it. This is how the front page is coded,
 626             (but not using the RGraph.Async() function).
 627             There's an example of it <a href="async.html">here</a>. The optional delay argument is measured in milliseconds
 628             (1 second = 1000 milliseconds) and defaults to 1. What you can do is specify something like 1000 to make the effect
 629             more pronounced to ensure it's working as expected.
 630
 631             <p>
 632                 <b>Note:</b> Since a dev release of version 4,  Google Chrome versions 4 and 5 have an issue with rendering text when using
 633                 the RGraph.Async() function. The solution here is to simply not use the RGraph.Async() function.
 634             </p>
 635             <i>File: RGraph.common.core.js</i><br /><br />
 636         </li>
 637
 638         <li>
 639             <b>(null) RGraph.filledCurvyRect(context, x, y, width, height[, radius[, curvy top left[, curvy top right[, curvy bottom right[, curvy bottom left]]]]])</b><br />
 640             This draws a rectangle with curvy corners. Similar to the built in rectangle functions, and you can control
 641             individual corners. The radius controls the severity of the corner curvature and defaults to 3. By default all
 642             the corners are curvy.<br /><i>File: RGraph.common.core.js</i><br /><br />
 643         </li>
 644
 645         <li>
 646             <b>(null) RGraph.strokedCurvyRect(context, x, y, width, height[, radius[, curvy top left[, curvy top right[, curvy bottom right[, curvy bottom left]]]]])</b><br />
 647             This draws a rectangle with curvy corners. Similar to the built in rectangle functions, and you can control
 648             individual corners. The radius controls the severity of the corner curvature and defaults to 3. By default all
 649             the corners are curvy.<br /><i>File: RGraph.common.core.js</i><br /><br />
 650         </li>
 651     </ul>
 652
 653     <a name="functions.events"></a>
 654     <h4>Custom RGraph event related functions</h4>
 655
 656     <ul>
 657         <li><b>(null) RGraph.AddCustomEventHandler(object, event, callback)</b><br />This attaches a function to the spacified event. The object argument is your graph object, the event argument should be the name of the event, eg <i>ontooltip</i>, and the function argument is your function which handles the event.<br /><i>File: RGraph.common.core.js</i><br /><br /></li>
 658         <li><b>(null) RGraph.FireCustomEvent(object, event)</b><br />This fires a custom event. The object is your graph object, and the name is a string specifying the name of the event.<br /><i>File: RGraph.common.core.js</i></li>
 659     </ul>
 660
 661     <a name="functions.other"></a>
 662     <h4>Other</h4>
 663
 664     <p>
 665         These are functions which are less generic, and used to build the graphs. You may still wish to use them however.
 666     </p>
 667
 668     <ul>
 669         <li><b>(null) RGraph.lineByAngle(context, x, y, angle, length)</b><br />This function draws a line from the given X and Y coordinates at the specified angle.<br /><i>File: RGraph.common.core.js</i><br /><br /></li>
 670
 671         <li>
 672             <b>(null) RGraph.Text(context, font, size, x, y, text[, valign[, halign[, border[, angle[, background[, bold[, indicator]]]]]]])</b><br />
 673             This function acts as a wrapper around the canvas text functionality. The arguments are:
 674
 675             <ul>
 676                 <li>The context is the canvases 2D context.</li>
 677                 <li>The font is the name of the font you want to use (eg Arial).</li>
 678                 <li>The size is an integer specifying the size of the text, (measured in points).</li>
 679                 <li>The x and y arguments are the X/Y coordinates at which to draw the text.</li>
 680                 <li>The text argument is the text to draw.</li>
 681                 <li>The optional valign argument is the vertical alignment and can be either <i>top</i>, <i>center</i> or <i>bottom</i>.</li>
 682                 <li>The optional halign argument is the horizontal alignment and can be <i>left</i>, <i>center</i> or <i>right</i>.</li>
 683                 <li>The optional border argument is a boolean (<i>true</i> or <i>false</i>) controlling whether the text has a border.</li>
 684                 <li>The optional angle argument specifies the angle at which the text is drawn (rotated around the X/Y coordinates and measured in degrees).</li>
 685                 <li>The optional background argument is the color of the background, (eg #fff).</li>
 686                 <li>The optional bold argument is boolean which controls whether the text is bold or not.</li>
 687                 <li>And the optional indicator argument is a boolean which controls whether a placement indicator is shown.</li>
 688             </ul>
 689
 690             <br /><i>File: RGraph.common.core.js</i>
 691             <br /><br />
 692         </li>
 693
 694         <li><b>(null) RGraph.DrawTitle(canvas, text, gutter[, centerx[, size]])</b><br />This function draws the title. The centerx argument is the center point to use. If not given the center of the canvas is used.<br /><i>File: RGraph.common.core.js</i><br /><br /></li>
 695         <li><b>(null) RGraph.Tooltip(canvas, text, x, y, idx)</b><br />This function shows a tooltip. The idx value corresponds to the tooltip array that you give.<br /><i>File: RGraph.common.tooltips.js</i><br /><br /></li>
 696         <li><b>(null) RGraph.DrawKey(object, key, colors)</b><br />This function draws the key. The first argument is the graph object, the second is an array of key information and the last is an array of the colors to use.<br /><i>File: RGraph.common.core.js</i><br /><br /></li>
 697         <li><b>(null) RGraph.DrawBars(object)</b><br />This draws the horizontal background bars. The argument is the graph object.<br /><i>File: RGraph.common.core.js</i><br /><br /></li>
 698         <li><b>(null) RGraph.DrawInGraphLabels(object)</b><br />This draws the in-graph labels. The argument is the graph object.<br /><i>File: RGraph.common.core.js</i><br /><br /></li>
 699         <li><b>(null) RGraph.DrawCrosshairs(object)</b><br />This function draws the crosshairs. The argument is the graph object.<br /><i>File: RGraph.common.core.js</i><br /><br /></li>
 700         <li><b>(null) RGraph.HideContext()</b><br />This function clears the context menu. RGraph uses it to hide the context menu, but only AFTER your function/callback is run. You may wish to hide the context menu before your own function, in which case you can call this function.<br /><i>File: RGraph.common.context.js</i><br /><br /></li>
 701         <li>
 702             <b>(null) RGraph.showPNG([canvas[, event]])</b><br />
 703             This function allows you to easily facilitate getting a PNG image representation of your graph.
 704             You can use it like this:<br />
 705
 706             <pre class="code">myBar.Set('chart.contextmenu', [
 707                                 <span style="color: green">['Get PNG', RGraph.showPNG]</span>,
 708                                 null,
 709                                 ['Cancel', function () {}]
 710                                ]);</pre>
 711             Optionally, you can pass in the canvas as an argument which will be used, meaning now you do not have to use a
 712             context menu (there's an example <a href="png.html"><b>here</b></a>). It WAS originally designed to be used with a context menu, hence it's part of the <i>RGraph.core.context.js</i>
 713             file.<br />
 714             <i>File: RGraph.common.context.js</i>
 715             <br /><br />
 716         </li>
 717
 718         <li>
 719             <b>(number) RGraph.getGutterSuggest(obj, data)</b><br />
 720             This function returns a suggested gutter setting based on the vertical labels. If the bottom labels are larger, this
 721             setting may be inappropriate. The <i>data</i> variable is a simple single dimension array, <i>eg [1,2,3,4,5]</i>.
 722             <br />
 723             <pre class="code">
 724 var size = RGraph.getGutterSuggest(obj, data);
 725 obj.Set('chart.gutter', size);
 726 </pre>
 727             <i>File: RGraph.common.core.js</i>
 728             <br /><br />
 729         </li>
 730
 731         <li>
 732             <b>(boolean) RGraph.isIE8()</b><br />
 733             This function tests the useragent for MSIE8.<br />
 734             <i>File: RGraph.common.core.js</i>
 735             <br /><br />
 736         </li>
 737
 738         <li>
 739             <b>(boolean) RGraph.isIE8up()</b><br />
 740             This function tests the useragent for MSIE8 or higher.<br />
 741             <i>File: RGraph.common.core.js</i>
 742             <br /><br />
 743         </li>
 744
 745         <li>
 746             <b>(boolean) RGraph.isIE9()</b><br />
 747             This function tests the useragent for MSIE9.<br />
 748             <i>File: RGraph.common.core.js</i>
 749             <br /><br />
 750         </li>
 751
 752         <li>
 753             <b>(boolean) RGraph.isIE9up()</b><br />
 754             This function tests the useragent for MSIE9 or higher.<br />
 755             <i>File: RGraph.common.core.js</i>
 756             <br /><br />
 757         </li>
 758
 759         <li>
 760             <b>(null) RGraph.background.Draw(obj)</b><br />
 761             This function is used by the Bar, Gantt, Line and Scatter chart to draw the chart background (but not the axes).
 762             It is passed the graph object which it uses to get the properties it uses:<br /><br />
 763
 764             <div>
 765                 <div style="float: left">
 766                     <ul>
 767                         <li>chart.gutter</li>
 768                         <li>chart.variant</li>
 769                         <li>chart.text.size</li>
 770                         <li>chart.text.font</li>
 771                         <li>chart.title</li>
 772                         <li>chart.title.yaxis</li>
 773                         <li>chart.background.barcolor1</li>
 774                         <li>chart.background.barcolor2</li>
 775                         <li>chart.background.grid</li>
 776                         <li>chart.background.grid.autofit</li>
 777                     </ul>
 778                 </div>
 779                 <div style="float: left">
 780                     <ul>
 781                         <li>chart.background.grid.autofit.numhlines</li>
 782                         <li>chart.background.grid.autofit.numvlines</li>
 783                         <li>chart.background.grid.hlines</li>
 784                         <li>chart.background.grid.vlines</li>
 785                         <li>chart.background.grid.hsize</li>
 786                         <li>chart.background.grid.vsize</li>
 787                         <li>chart.background.grid.width</li>
 788                         <li>chart.background.grid.color</li>
 789                         <li>chart.background.grid.color</li>
 790                     </ul>
 791
 792                 </div>
 793             </div>
 794
 795             <br clear="all" />
 796
 797
 798
 799             <p>
 800                  Note that this function also calls RGraph.DrawTitle() in order to draw the title.<br />
 801                  <i>File: RGraph.common.core.js</i>
 802             </p>
 803
 804             <br /><br />
 805         </li>
 806     </ul>
 807
 808
 809     <a name="skeleton"></a>
 810     <h4>The skeleton file</h4>
 811     <p>
 812         The skeleton object
 813         (<a href="../libraries/RGraph.skeleton.js" target="_blank"><i>RGraph.skeleton.js</i></a>) gives you a base for creating new graph types that
 814         match the RGraph object system (eg getters, setters, RGraph names etc). Example usage of the skeleton object would be:
 815     </p>
 816
 817     <pre class="code">
 818 &lt;script&gt;
 819     var myObj = new RGraph.Skeleton('cvs', [3,3,4,5,3,8,3,2,1,9]);
 820     myObj.Set('chart.colors', ['red']);
 821     myObj.Draw();
 822
 823     var colors = myObj.Get('chart.colors');
 824 &lt;/script&gt;
 825 </pre>
 826
 827     <a name="questions"></a>
 828     <h4>Questions</h4>
 829
 830     <p>
 831         If you have a question regarding the API, you can ask it on the
 832         <a href="http://groups.google.com/group/rgraph/topics?gvc=2" target="_blank">mailing list</a>
 833     </p>
 834 </body>
 835 </html>