Context Navigation

source: Dev/trunk/RGraph/docs/api.html @ 178

Last change on this file since 178 was 77, checked in by fpvanagthoven, 14 years ago
RGraph
File size: 41.3 KB

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

Note: See TracBrowser for help on using the repository browser.

Download in other formats: