CLASS Graph
(Defined in: jpgraph.php : 613)
 Graph 
 Add() 
 AddBand() 
 AddLine() 
 AddText() 
 AddY2() 
 AdjBackgroundImage() 
 AdjImage() 
 GetHTMLImageMap() 
 Graph() 
 SetAngle() 
 SetAxisStyle() 
 SetBackgroundImage() 
 SetBox() 
 SetColor() 
 SetFrame() 
 SetGridDepth() 
 SetMargin() 
 SetMarginColor() 
 SetScale() 
 SetShadow() 
 SetTickDensity() 
 SetY2Scale() 
 Stroke() 
 StrokeCSIM() 
 StrokeFrameBackground() 
 

Class usage and Overview
The Graph class is the main container class for all x,y-axis based plots which controls the creation of the entire graph. You must always instantiate one instance to create a graph. Through this class one controls many overall settings of the image displayed.

Please note that to create Pie, Gantt, Canvas and Spider charts you have to use their respective creation classes.

Public properties:
NameTypeDescription
xaxis Axis X-axis
yaxis Axis Y-axis
xgrid Grid Grid lines for X-axis
ygrid Grid Grid lines for Y-axis
legend Legend Properties for legend box
title Text Graph main title
subtitle Text Sub title
img RotImage The image canvas

 

See also related classes:
Axis, Grid, Text and Image

 


Class Methods

 

 

function Add(&$aPlot)
Add any plot object to the graph

ArgumentDefaultDescription
&$aPlot  Plot object

Description
Each plot that should be displayed within the graph has to be added to the graph. This is the main method to add object. You can use this method to add This method will add a plopt for use with the “Left” Y-scale, (the normal Y scale). To add a plot to the second Y scale you should use AddY2().

Note that since the plot is added as a reference any changes you make to the original plot will also happen to the plot you have added to the graph.

Add() will always add plots to the first Y-scale. If you are using two Y-axis then you must use AddY2() to add plots to the second Y-scale.  
 

See also
Graph::AddY2 and Graph::SetScale

Example

$graph = new Graph(300,200,"auto");    
$graph->img->SetMargin(40,30,20,40);
$graph->SetScale("textlin");
$graph->SetShadow();

// Create a bar pot
$bplot = new BarPlot($datay);
$bplot->SetFillColor("orange");
$graph->Add($bplot);

// Display the graph
$graph->Stroke();

 

 

function AddBand(&$aBand)
Add vertical or horizontal band

ArgumentDefaultDescription
&$aBand  Band object

Description
A plot may have one or several filled horizontal or vertical "bands" to emphasise certain scale areas.

Each band is an instance of the PlotBand class. For types of plot band see the documentation of class PlotBand

Note: You can alos use the standard method Add() to add bands. 
 

See also
PlotBand::PlotBand and Graph::Add

Example

$graph->AddBand(new PlotBand(HORIZONTAL,BAND_RDIAG,0"max""red"2));

 

 

function AddLine(&$aLine)
Add a line object (class PlotLine) to the graph

ArgumentDefaultDescription
&$aLine  Line object to add

Description
Add a vertical or horizontal line to the graph. The line will extend over the entire length of the plot. The plot object is an instance of the PlotLine class

Note: You can alos use the standard method Add() to add lines. 
 

See also
PlotLine::PlotLine and Graph::Add

Example

// Add mark graph with static lines
$graph->AddLine(new PlotLine(HORIZONTAL,0,"black",2));
$graph->AddLine(new PlotLine(VERTICAL,3,"black",2));

 

 

function AddText(&$aTxt)
Add text object to the graph

ArgumentDefaultDescription
&$aTxt  Text object to add

Description
Adds an instance of the Text class to the graph, allowing arbitrary text to be placed anywhere in the graph.

Note: You can alos use the standard method Add() to add bands.  
 

See also
Text::Text and Graph::Add

Example

// You can specify the position as fraction of the
// image width and height
$caption=new Text(“Figure 1. Temperature over time”,0.1,0.8);
$caption->SetFont(FONT1_BOLD);
$graph->AddText($caption);

 

 

function AddY2(&$aPlot)
Add plot to second Y-axis

ArgumentDefaultDescription
&$aPlot  Plot to add to the Y2 axis

Description
Works the same way as Add() but the plot is added for use with the Y2 scale (the right Y scale) instead. 
 
See also
Graph::Add and Graph::SetY2Scale

Example

$graph->new Graph(300,200);
$graph->SetScale(“linlin”);
$graph->SetY2Scale(“linlog”);
$lineplot = New LinePlot($datay);
$graph->AddY2($lineplot);

 

 

function AdjBackgroundImage($aBright,$aContr,$aSat)
Adjust brightness and constrast for background image

ArgumentDefaultDescription
$aBright  Brighness (-1,1)
$aContr 0 Constrast (-1,1)
$aSat 0 Saturation (-1,1)

Description
When using background images it is often desirable to make it a "shadow" image so it doesn't disturb the main messagfe of the plot. This can often be accomplished by, for example, increasing the brightness level of the image.

With method you can adjust both the brighness, contrast as well as color saturation in the loaded background image before it is displayed on the graph. This makes it unnecessary to first adjust the image in an image processing program.

All values are gives as fraction between 0 and 1 where lower values indicates a "lower" value. The special value 0 leaves the parameter as is.  
 

See also
Graph::LoadBkgImage

Example

$graph->AdjBackgroundImage(0.7,0.3);

 

 

function AdjImage($aBright,$aContr,$aSat)
Adjust brightness and constrast for image

ArgumentDefaultDescription
$aBright  Brightness (-1,1)
$aContr 0 Contrast (-1,1)
$aSat 0 Saturation (-1,1)

Description
With this method you can adjust both the brightness, contrast as well as color saturation in the image before it is sent to the browser or filedisplayed on the graph.

All values are gives as fraction between 0 and 1 where lower values indicates a "lower" value. The special value 0 leaves the parameter as is.  
 

See also
Graph::AdjBackgroundImage

Example

$graph->AdjImage(0.7,0.3);

 

 

function GetHTMLImageMap($aMapName)
Get a complete .. tag for the final image map

ArgumentDefaultDescription
$aMapName  Image map name

Description
When you are using image maps for a plot then this routine is called in your script to get the resulting image map as a string for the graph. The image map is given the name specified as the first argument to the method.

Please note that due to the way client side image maps work you need to have both the image map and the image available in the script that is sent back to the browser. Since you can't do this at the same time you will have to create an image to disk and read the image map. The you have to stream the HTML page with an tag to load the previously generated image as well as the image map.  

Example

// The image must be stroked to find out the image maps
$graph->Stroke($myfile);

// Then read the image map
$imagemap $graph->GetHTMLImageMap('MainMap');

echo 
$imagemap;
echo 
"<img src=$myfile>";

 

 

function Graph($aWidth,$aHeight,$aCachedName,$aTimeOut,$aInline)
Creates a new graph.

ArgumentDefaultDescription
$aWidth 300 Width
$aHeight 200 Height
$aCachedName "" Cache file name
$aTimeOut 0 Timeout value for cache
$aInline true True=Stream the image back to the browser

Description
Creates a new graph. This is often the first call made to set-up a new graph.
If the cache name is specified (via the $aCachedname) argument then this method will first try to locate the named file in the cache directory (as specified by the DEFINE in jpgraph.php) rather then generating the graph on the fly. If the file is not there or if it is older then the specified timeout value ($aTimeOut) the graph will be generated and saved as the specified file.

If the cache name is specifed as 'auto' then the cache name will be based on the basename of the script with an extension indicating the image format used, i.e. JPG, GIF or PNG.

If the specified file is found in the cache directory then it will be streamed back to the browser directly.

If no cache name is specified then the graph will always be generated and the cache bypassed. The same is true if the DEFINE 'USE_CACHE' or 'READ_CACHE' is set to false.

Before any other operation is performed on the graph a call to SetScale() should be made to finish the initialisation of the graph.  
 

See also
Graph::Stroke

Example

// Example 1. use cache and automtic create the cache name
$graph = new Graph(400,200,"auto");    
$graph->img->SetMargin(60,20,30,50);
$graph->SetScale("textlin");
$graph->SetMarginColor("silver");
$graph->SetShadow();

// Example 2 . Don't use the cache
$graph = new Graph(400,200);    
$graph->SetScale("textint");

 

 

function SetAngle($aAngle)
Specify graph angle 0-360 degrees.

ArgumentDefaultDescription
$aAngle  Rotation angle for graph

Description
The graph can be rotated an arbitrary number of degrees. This will allow you to easily create, for example, horizontal bar graphs by rotating a normal bar graph 90 degrees.

See horizbarex1.php for a real life example. 

Example

$graph = new Graph(300,200);
$graph->SetScale('textlin');
$graph->SetAngle(90);

 

 

function SetAxisStyle($aStyle)
Specify axis style (boxed or single)

ArgumentDefaultDescription
$aStyle  Style of axis

Description
The most common type of axis is two axis which crosses at a specified point. However for scientific plot it is often common to want to mirror the axis (and the scale) around the plot area. This method controls which type to use See funcex1.php, funcex2.php and funcex3.php for real life examples. 

Example

$graph->SetAxisStyle(AXSTYLE_BOXIN);

 

 

function SetBackgroundImage($aFileName,$aBgType,$aImgFormat)
Specify a background image fro the plot

ArgumentDefaultDescription
$aFileName  Filename for background image
$aBgType BGIMG_FILLPLOT Style of background image
$aImgFormat "auto" Image format ("jpeg", "gif", "png")

Description
A graph may have a background image. The image is loaded from a specified file and may be of type GIF, JPG or PNG.

The positioning and sizing of the background image can be controlled by the $aBgType parameter. Possible values are

 

Example

// PNG is the default image format
$graph->SetBackgroundImage("tiger_bkg.png",BGIMG_FILLFRAME);

 

 

function SetBox($aDrawPlotFrame,$aPlotFrameColor,$aPlotFrameWeight)
Set a frame around the plot area

ArgumentDefaultDescription
$aDrawPlotFrame true True=Draw the frame
$aPlotFrameColor array(0,0,0) Frame color
$aPlotFrameWeight 1 Width fo frame line

Description
This is used to specify whether the plot-area should have a rectangle around it and the specifics of that rectangle. 
 
See also
Graph::SetFrame

Example

$graph->new Graph(300,200);
$graph->SetScale(“linlin”);
$graph->Box();

 

 

function SetColor($aColor)
Specify color for the plotarea (not the margins)

ArgumentDefaultDescription
$aColor  Color

Description
Specify color for the plotarea (not the margins) 
 
See also
Graph::SetFrame and Graph::SetMarginColor

Example

$graph->SetColor(“wheat”);

 

 

function SetFrame($aDrawImgFrame,$aImgFrameColor,$aImgFrameWeight)
Set a frame around the entire image

ArgumentDefaultDescription
$aDrawImgFrame true True=Draw a frame around the entire image
$aImgFrameColor array(0,0,0) Frame color
$aImgFrameWeight 1 Width of frame

Description
Sets a frame (rectangle) of the chosen color around the edges of the image. 
 
See also
Graph::SetMarginColor

Example

$graph->SetFrame(true,'darkblue',2);

 

 

function SetGridDepth($aDepth)
Should the grid be in front or back of the plot?

ArgumentDefaultDescription
$aDepth  Grid depth

Description
Specify if the grid in the plot should be drawn under or on top of the actual plots.

Valid values for grid depth are

The default is to draw the grid lines under the plots. 

Example

$graph->SetGridDepth(DEPTH_FRONT);

 

 

function SetMargin($lm,$rm,$tm,$bm)
Shortcut to image margin

ArgumentDefaultDescription
$lm  Left margin (in pixels)
$rm  Right margin (in pixels)
$tm  Top margin (in pixels)
$bm  Bottom margin (in pixels)

Description
Specify the margin around the actual plot area. This is actually just a shortcut for the Image::SetMargin() 
 
See also
Image::SetMargin

Example

$graph->SetMargin(40,20,60,20);

 

 

function SetMarginColor($aColor)
Specify color for the margins (all areas outside the plotarea)

ArgumentDefaultDescription
$aColor  Color

Description
Specifies the color of the area between the plot area and the edge of the image. 
 
See also
Graph::SetColor and Graph::SetFrame

Example

$graph->SetMarginColor('silver');

 

 

function SetScale($aAxisType,$aYMin,$aYMax,$aXMin,$aXMax)
Specify scale to use for X and Y axis

ArgumentDefaultDescription
$aAxisType  Type of axis
$aYMin 1 Y-min
$aYMax 1 Y-max
$aXMin 1 X-min
$aXMax 1 X-max

Description
Specifies what kind of scales should be used in the graph. The following combinations are allowed Any combination of these may be used. Linear and logarithmic scales are pretty straightforward. The text scale might deserve some explanation. The easiest way to think of the text scale is as a linear scale consisting of only natural numbers, i.e. 0,1,2,3,4,… . This scale is used when you just have a number of Y-values you want to plot in a consecutive order and don’t care about the X-values. It is also used when you need to have text labesl you specify (via $graph->xaxis->SetTickLabels($labels) ).

To specify which combination of X and Y scales you want to use the $axtype parameter is specified. In this parameter you specify, by a text string, the type of scale you want to use for both X and Y scale.

Possible values for each axis are:
X: 'lin', 'text', 'log', 'int'
Y: 'lin', 'log', 'int'

Example of possible combination:

It is normally recommended to use the auto-scaling feature since for most practical purposes it is good enough. However on rare occasions you might want to specify the limits yourself. This is then done by the rest of the parameters to the method.

Note: If you want to use a logarithmic scale you must make sure that the “jpgraph_log.php” is included.

Note: Note that if you manually specify the scale you must also specify the tick distance with a call to Ticks::Set(). For example $graph->yaxis->scale->ticks->Set(10,5)  
 

See also
Ticks::Set

Example

//----------------------
// EXAMPLE1: Using autoscaling
$graph->SetScale('textlin');

//----------------------
// EXAMPLE2: Using manual scale for Y-scale and only major ticks
$graph->SetScale("linlin",5,75);
$graph->yaxis->scale->ticks->Set(10); // Set major and minor tick to 10

//----------------------
// EXAMPLE3: Using manual scale for Y-scale
$graph->SetScale("linlin",5,200);
// Set major tick dist to 40 and minor to 20
$graph->yaxis->scale->ticks->Set(40,20); 

//----------------------
// EXAMPLE4: Using manual scale for both X and Y-scale
$graph->SetScale("linlin",5,200,0,100);
// Set major tick dist to 40 and minor to 20
$graph->yaxis->scale->ticks->Set(40,20);
// Set major and minor tick dist to 20
$graph->xaxis->scale->ticks->Set(20); 


 

 

function SetShadow($aShowShadow,$aShadowWidth,$aShadowColor)
Add a drop shadow to the image

ArgumentDefaultDescription
$aShowShadow true True=add a drop shadow
$aShadowWidth 5 Width (in pixels of shadow)
$aShadowColor array(102,102,102) Shadow color

Description
Sets a frame with a drop down shadow around the entire image 
 
See also
Graph::SetFrame

Example

$graph->SetShadow();

 

 

function SetTickDensity($aYDensity,$aXDensity)
Specify how dense the ticks should be drawn

ArgumentDefaultDescription
$aYDensity TICKD_NORMAL Y-density
$aXDensity TICKD_NORMAL X-density

Description
This method is used to hint how many ticks the auto-scaling should try to fit on each of the axis.

The following DEFINES may be used to hint to the auto-scaling how many ticks should be allocated

 

Example

$graph->SetTickDensity(TICKD_DENSE); // Many Y-ticks

 

 

function SetY2Scale($aAxisType,$aY2Min,$aY2Max)
Specify secondary Y scale

ArgumentDefaultDescription
$aAxisType "lin" Type of scale
$aY2Min 1 Y2Min value
$aY2Max 1 Y2Max value

Description
The graph allows two different Y-scales to be used and you can choose which one you want to use for a specific plot by the way you are adding the plot to the graph, either by Add() or by AddY2() method.

This method works in the exact same way for the Y2 axis as the SetScale() method previously described.

Allowed values for the $axtype are

Note: If you want to use a logarithmic scale you must make sure that the “jpgraph_log.php” is included.  
 
See also
Graph::SetScale and Graph::AddY2

Example

// Left Y scale linear and right Y-scale logarithmic
$graph = new Graph(300,200);
$graph->SetScale(“textlin”);
$graph->SetY2Scale(“log”);

 

 

function Stroke($aStrokeFileName)
Stroke graph to browser or file

ArgumentDefaultDescription
$aStrokeFileName "" File name

Description
Should be the final method called in the script that generates a graph. This will generate the image and send it back to the browser.

If $aStrokeFileName != "" the image will be written to this file and NOT streamed back to the browser

If the file name is specified with the define _IMG_HANDLE then no image will be streamed to file or browser. Instead the Stroke() method will simply return the image handle used by the GD library. This can come in handy of you like to post manipulate the image or use the raw GD image in other context. Such as in creating dynamic PDF documents.

You may also specify the file name as "auto" in which case the filename will be created from the script name but with the extension changed to reflect the choosen image format.  

Example

// Example 1 : (Normal case) Stream back to browser
$graph->Stroke();

// Example 2 : Stream to the file with absolute file path
$graph->Stroke($fileName);

// Example 3
// Get the image handle. NOTE: No image will be
// streamed to the browser in this case.
$ih $graph->Stroke(_IMG_HANDLE);

 

 

function StrokeCSIM($aScriptName,$aCSIMName,$aBorder)
Stroke an image with a CSIM

ArgumentDefaultDescription
$aScriptName  Name of the image generating script
$aCSIMName 'myjpgimage' Image map name
$aBorder 0 Should the image be bordered?

Description
To generate an CSIM you must use this method at the end of your script instead of the normal Graph::Stroke() method. This method does not send back an image to the browser but rather a HTML page which contains an image map and a "recursive call" back to the image script. See the full JpGraph manual for a detailed explanation on how this works.

Please note that it is abolutely imperative that you specify the image generating scripts name as the first argument.

Why that? Because it is impossible for JpGraph to find out the name of the script it is executed from in the case where it is included as oart of a "standard" HTML/PHP page. Using the PHP_SELF will only return the master document and not the actual script name.

If you use several image map images on the same HTML page you must also specify unique names of each of the image maps as the second argument for this function.

To specify targets for the image maps you must call the individual plots Pot::SetCSIMTargets() 
 

See also
Plot::SetCSIMTargets

Example

...
$graph->StrokeCSIM('examplescript1.php');

 

 

function StrokeFrameBackground()
Stroke the frames background and border


Description
Semi Internal routine. Exclusively used together with canvas graphs where object are added directly to the canvas and we therefore must make sure that the background is stroked first.