GChart API Reference
Contents
GChart_DIR: Before you use GChart, you should set GChart_DIR to the directory of GChart library. For example:
define ('GChart_DIR',dirname(__FILE__).'/gchart/');
GChart_DECIMALS: Set the number of digits after the digital point.
Most of chart classes have the following common functions:
- set_title($title): sets the chart's title.
- set_encoding($encoding): (This is not included in GChart_QR class) sets the data encoding. The argument $encoding can be one of the following definitions:
- TEXT_ENCODING (default)
- TEXT_ENCODING_SCALING
- SIMPLE_ENCODING
- EXTENDED_ENCODING
GChart_Pie is used for drawing pie charts. It is an abstract class so you can not create an instant of it. There are two types of pie charts: 2D-pie chart and 3D-pie chart. You should use GChart_Pie2D or GChart_Pie3D to create a chart object instead of GChart_Pie. The two classes derive from GChart_Pie class.
Add a data array to the pie chart.
Parameters:
$arr: $arr is an integer-indexed array or an associative array. If it is an associative array, the keys are treated as labels.
Examples:
<?php
$p=new GChart_Pie2D(240,160);
$p->add(array(30,87,24));
?>
<img src="<?php echo $p->get_image_string(); ?>" />
produces
<?php
$p=new GChart_Pie2D(240,160);
$p->add(array('First'=>30,'Second'=>87,'Third'=>24));
?>
<img src="<?php echo $p->get_image_string(); ?>" />
produces
Add a data element to the chart.
Parameters:
$value: the element's value. It must be a number (float number or integer).
$label: then element's label. If it is set, there will be a text label points to the corresponding part.
$color: indicates the color of the part. The format is 'RRGGBB'.
Examples:
<?php
$p=new GChart_Pie2D(240,140);
$p->add(30,'First','FF0000');
$p->add(87,'Second','00FF00');
$p->add(24,'Third','0000FF');
?>
<img src="<?php echo $p->get_image_string(); ?>" />
The result is:
function add_color(string $color)
If you didn't set the part color while adding data elements, you can use this function to add color later. The n-th color is assigned to the n-th element part.
Parameters:
$color: a color string.
Set the chart's backgound color.
Parameters:
$color: a string indicating the background color. The format is 'RRGGBB'.
function set_scaling(number $low, number $high)
If you set the data encoding to TEXT_ENCODING_SCALING, you can use this function to set the data boundry. It means all number is between $low and $high.
GChart_Pie2D extends GChart_Pie. It is used for creating 2D-pie chart.
GChart_Pie3D extends GChart_Pie. It is used for creating 3D-pie chart.
GChart_Bar is the bar chart class. It is an abstract class because there are two types of bar charts: vertical bar chart and horizontal bar chart. You should use GChart_Bar_V or GChart_Bar_H to create a bar chart.
add a GChart_DataSeries object to the chart. A GChart_DataSeries object stands for a group of data elements. Normally, they have the same color.
Parameters:
$s: an instance of GChart_DataSeries class.
Add a series of data elements to the bar chart.
Parameters:
$data: an array which contains some numbers.
$label: (optional) the label for this series. It is used for genereting legends.
$color: (optional) sets the color of the seires of elements. The format is 'RRGGBB'.
Add a GChart_Axis object to the bar chart so that the chart will show the axis.
Parameters:
$axis: an instance of the GChart_Axis class.
Add an axis directly. It doesn't need to create a GChart_Axis object.
Parameters:
$type: The type of the axis. It can be one of the following four values:
- GChart_BOTTOM_X_AXIS (or 'x')
- GChart_TOP_X_AXIS (or 't')
- GChart_LEFT_Y_AXIS (or 'y')
- GChart_RIGHT_Y_AXIS (or 'r')
$name: (optional). The name of the axis. It must be a unique string.It is used by "get_axis_by_name()" function.
$labels: an string array. It contains the labels on the axis. For example, if the x-axis stands for months, the $label should be array('Jan','Feb','Mar',...).
$start, $end: The start and end value of the axis. For example, you may want to let the axis start from 100 and end at 1000'. So you need to set $start to 100 and $end to 1000.
If you set a label for a series of data, you can retrieve the series by the label. If there is not a series whose label is $label, the function returns false.
Parameters:
$label: a string that stands for the label.
Get the n-th data series.
Parameters:
$index: an integer n that stands for n-th data series.
Since you can set a name for an axis object, you can also use the name to retrieve it with this function. If there is not an axis whose name is $name, the function return false.
Set the background color of the bar chart. See GChart_Pie::set_background.
function set_bar_width(int $width, int $space=null, int $group_space=null)
Set the width of each bar, the distance between two bars in a group and the distance of two groups.
Parameters:
$width: The width of each bar.
$space: (optional) The distance between two bars in a group.
$group_space: (optional) The distance between two groups.
This function sets the color of the data region. While set_background() sets the whole background color.
GChart_Bar_H extends the GChart_Bar class. It is used for creating horizontal charts.
The constructor of GChart_Bar_H class.
Parameters:
$width, $height: the size of the bar chart.
$grouped: indicates whether the multiple data sets are grouped.
Example:
Multiple data sets are not grouped
<?php
$bar_h=new GChart_Bar_H(300,130);
$bar_h->set_bar_width(10);
$bar_h->add_array(array(24,58,29,132,59,98,21),'First','FF0000');
$s=new GChart_DataSeries();
$s->set_items(array(9,49,17,94,29,38,69),'Second','00FF00');
$bar_h->add_series($s);
?>
<img src="<?php echo $bar_h->get_image_string(); ?>" />
Multiple data sets are grouped
<?php
$bar_h=new GChart_Bar_H(300,130,true);
$bar_h->set_bar_width(4,2,6);
$bar_h->add_array(array(24,58,29,132,59,98,21),'First','FF0000');
$s=new GChart_DataSeries();
$s->set_items(array(9,49,17,94,29,38,69),'Second','00FF00');
$bar_h->add_series($s);
?>
<img src="<?php echo $bar_h->get_image_string(); ?>" />
GChart_Bar_V extends the GChart_Bar class. It is used for creating vertical charts.
constructor __construct(int $width, int $height, $grouped=false)
The constructor the GChart_Bar_V. See GChart_Bar_H::__construct.
GChart_Line class is used for creating line charts. Most of its functions are similar to those of GChart_Bar.
function add(DataSeries $s)
Add a series of data to the line chart. It is expressed as a line. See GChart_Bar::add().
function add(array $data, string $label='', string $color='')
Add a series of data to the line chart. It uses an array as the first parameter instead of an GChart_DataSeries object. See GChart_Bar::add().
function add_axis(GChart_Axis $axis)
Add an axis to the line chart. See GChart_Bar::add_axis().
function add_axis(string $type, string $name='', array $labels=array(), int $start=null, int $end=null)
Add an axis to the line chart. It uses a type string and other arguments to construct an axis. See GChart_Bar::add_axis().
function get_axis_by_name(string $name)
returns the axis instance whose name is $name. See GChart_Bar::get_axis_by_name().
function get_series_by_label(string $label)
return the series (a line) whose label is $label. If it doesn't exist, return false. See GChart_Bar::get_series_by_label().
function get_series_by_index(int $index)
returns the $index-th data series. See GChart_Bar::get_series_by_index().
function set_background(string $color)
See GChart_Bar::set_background().
function set_chart_background(string $color)
See GChart_Bar::set_chart_background().
GChart_Scatter_Plot is the class for creating scatter plot charts.
function add_plot(GChart_Plot $plot)
add a plot to the chart.
Parameters:
$plot: an instance of GChart_Plot class.
function add_axis(GChart_Axis $axis)
Add an axis to the chart. See GChart_Bar::add_axis().
function add_axis(string $type, string $name='', array $labels=array(), int $start=null, int $end=null)
Add an axis through a type string and other arguments. See GChart_Bar::add_axis().
function get_axis_by_name(string $name)
return a reference to the axis whose name is $name. See GChart_Bar::get_axis_by_name().
function set_background(string $color)
Set the backgound color. See GChart_Bar::set_background().
function set_chart_background(string $color)
Set the chart background color of the chart. See GChart_Bar::set_chart_background().
GChart_Radar class is used for creating radar charts.
constructor __construct(int $width, int $height, int $curve=false)
The constructor of GChart_Radar class.
Parameters:
$width, $height: the size of the chart.
$curve: If it is set to true, all points are connected with a curve line. By default, the points are connected with a straight line.
function add(DataSeries $s)
Add a series of data where $s is an instance of GChart_DataSeries.
function add(array $data, string $label='', string $color='')
Add a series of data. It uses an array as the first parameter instead of a GChart_DataSeries object. See GChart_Bar::add().
function add_axis(GChart_Axis $axis)
See GChart_Bar::add_axis().
function add_axis(string $type, string $name='', array $labels=array(), int $start=null, int $end=null)
See GChart_Bar::add_axis().
function get_series_by_index(int $index)
See GChart_Bar::get_series_by_index().
function get_series_by_label(string $label)
See GChart_Bar::get_series_by_label().
function get_axis_by_name(string $name)
See GChart_Bar::get_axis_by_name().
function set_background(string $color)
See GChart_Pie::set_background().
GChart_GOM class is used for creating Google-O-Meter charts.
function add(array $arr)
See GChart_Pie::add().
function add(number $value, string $label='', $color='')
See GChart_Pie::add().
GChart_QR is used for creating QR-Code charts. QR Codes are a popular type of two-dimensional barcode, which are also known as hardlinks or physical world hyperlinks. QR Codes store text which can be a hyperlink, contact information, telephone number, even whole verses of poems!
function set_text(string $text)
Set the text to be encoded.
function set_char_encoding(string $encoding)
set the output character encoding.
Parameters:
$encoding: The output encoding. It can be one of the three values:
- GChart_QR_SHIFT_JIS (or 'Shift_JIS')
- GChart_QR_UTF-8 (or 'UTF-8')
- GChart_QR_ISO-8859-1 (or 'ISO-8859-1')
GChart_DataItem class is used for expressing an single data element.
:
constructor __construct(number $value, string $name='')
The constructor function. The second argument is a unique name for the data element and it is optional.
function set_marker(GChart_Marker $marker)
Set a special marker for the data element. See GChart_Marker.
The GChart_DataSeries class is used for expressing a series of data elements. For example, Line charts and radar charts use a series of number to draw a line.
constructor __construct($items=null, $label=null, $color=null)
The constructor. $item is an array, $label and $color are strings. If all the arguments are omitted, you should use "set_items()" to set the data.
Parameters
$items: an array which contains several numbers.
$label: an string. It can be used to generate the legends.
$color: an color string. It is used for indicating the color of a line (line charts, radar charts) or a bar (bar charts).
add_item(GChart_DataItem $item)
add an data elements to the GChart_DataSeries object.
function set_items(array $items, string $label=null, string $color=null)
set the object's data elements. $items is an array which contains numbers.
function get_item_by_index(int $index)
return the $index-th data elements. The return type is GChart_DataItem.
GChart_Axis class describes an axis. It is used by GChart_Line, GChart_Bar, GChart_Radar, GChart_Scatter_Plot.
constructor __construct($type, $labels=array())
The constructor. The second parameter $labels is optioanll.
Parameters:
$type: $type indicates the type of the axis. It can be one of the following for values:
- GChart_BOTTOM_X_AXIS (or 'x')
- GChart_TOP_X_AXIS (or 't')
- GChart_LEFT_Y_AXIS (or 'y')
- GChart_RIGHT_Y_AXIS (or 'r')
$labels: (optional). It is an array. It's element's is used for generating the axis' labels.
function set_boundry(number $low, number $high)
This function sets the start point ($low) and the end point ($high) of the axis.
function set_labels(array $labels)
This function sets the labels of the axis. $labels is normally an array of strings.
GChart_Marker class is used for describing the special markers. The markers can be added to a GChart_DataItem object.
constructor __construct(string $type, string $color, int $size, int $priority=null)
This is the only function of GChart_Marker class.
Parameters:
$type: indicates the type of the marker. It can be one of the following values or definitions:
- GChart_M_ARROW (or 'a')
- GChart_M_CROSS (or 'c')
- GChart_M_DIAMOND (or 'd')
- GChart_M_CIRCLE (or 'o')
- GChart_M_SQUARE (or 's')
- GChart_M_TEXT (or 't')
- GChart_M_VLINE_T (or 'V')
- GChart_M_VLINE_X (or 'v')
- GChart_M_HLINE (or 'h')
- GChart_M_X (or 'x')
If you set the type to GChart_M_TEXT, you should add a string after GChart_M_TEXT or 't'. For example, $m=new GChart_Marker('tThe Text'), or $m=new GChart_Marker(GChart_M_TEXT.'The Text')
$color: A string that indicates the marker's color.
$size: An integer that sets the size of the marker.
$priority: determines the order in which bars, lines, markers, and fills are drawn: -1 specifies the marker is drawn before all other parts of the chart. This means the marker will be hidden if another chart element is drawn in the same place. 0 is the default and specifies the marker is drawn on top of bars or lines and beneath other markers. 1 specifies the marker is drawn on top of all other parts of the chart. This means it will hide another chart element if it is drawn in the same place.
GChart_Plot is used by GChart_Scatter_Plot. It stands for a plot or a point.
constructor __construct(number $x, number $y, int $size=null)
constructs a plot for a scatter plot chart. $x and $y indicates the position of the plot, and the optional argument $size indicates the size of the plot.