In order to create a canvas graph you need to include the file "jpgraph_canvas.php" in addition to the standard "jpgraph.php" file. You might also want to include the "jpgraph_canvtools.php" to get access to some supporting classes that may (or not) come in handy.

Creating a canvas gives you the opportunity draw arbitrary shapes on a "white" piece of paper. Let's first show a simple example were we just draw a text box. We first show you the code which we will walk through

(File: canvasex01.php)

 <?php


// $Id: canvasex01.php,v 1.3 2002/10/23 08:17:23 aditus Exp $

include 
"../jpgraph.php";

include "../jpgraph_canvas.php";



// Setup a basic canvas we can work 

$g = new CanvasGraph(
400,300,'auto'
);

$g->SetMargin(
5,11,6
,11);

$g->SetShadow();

$g->SetMarginColor(
"teal");




// We need to stroke the plotarea and margin before we add the

// text since we otherwise would overwrite the text.

$g->InitFrame();



// Draw a text box in the middle

$txt="This\nis\na TEXT!!!";

$t = new Text(
$txt,200,10
);

$t->SetFont(
FF_ARIAL,
FS_BOLD,40);




// How should the text box interpret the coordinates?

$t->Align(
'center','top');



// How should the paragraph be aligned?

$t->ParagraphAlign(
'center');




// Add a box around the text, white fill, black border and gray shadow

$t->SetBox(
"white",
"black","gray");



// Stroke the text

$t->Stroke(
$g->img);



// Stroke the graph

$g->Stroke();



?>

The example above starts by creating a (400x200) sized image. We set the margins to get a nice frame around the image. For canvases the margins has no effect in the way you enter coordinates. Top left is (0,0) and bottom right (including any potential margin and shadow) is the maximum. In this case the coordinates are X:0-399, and Y:0-199

We then call the InitFrame() method which actually strokes the margin and plotarea to the graph. Since everything is stroked in the order you issue the commands you must make sure that the graphical objects you want on top is stroked last. This is different from the way you normally work with JpGraph since it queues up all you addition and then makes sure they are stroked in the correct order.

We then create a Text object, setup it's properties, including the absolute screen position where we want the text, and then stroke it. Her it might be a need for a closer explanation of the, perhaps misnamed, method Text::Align() This method states how the text coordinates should be interpreted , i.e when we specify (200,10) as the coordinates for the text paragraph should that be interpreted as the top left corner, bottom-left corner or something else (of the bounding box)? In the code above we have chosen to interpret the X-coordinate as being the center of the bounding box and the Y-coordinate as the top. Hence the text will be aligned so that the (200,100) point in the graph is aligned with the middle of the top line of the paragraphs bounding box.

We also specify that the lines within the paragraph should be centered with a call to Text::ParagraphAlign() Since we also choose to have a box around the text we have to make use of the method Text::SetBox() which is used to specify the fill color, the border color and the shadow color (if you leave out shadow color or set it to '', no shadow will be used).

Now we are ready to stroke the text onto the canvas. In order to do so we must specify the basic Image drawing class we want to use. Without discussing this further we just state that a suitable image class can always be found as the img property of the Graph class.

Finally we are ready to stroke the entire graph, which in effect sends the canvas back to the browser. Below you can see the effect of all this code

10.2 Creating a simple canvas