Blame | Letzte Änderung | Log anzeigen | RSS feed
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"><HTML><HEAD><META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso-iso-8859-1"><LINK REL="Start" HREF="index.html"><LINK REL="Contents" HREF="toc.html"><STYLE TYPE="text/css"><!--BODY { font-family: serif }H1 { font-family: sans-serif }H2 { font-family: sans-serif }H3 { font-family: sans-serif }H4 { font-family: sans-serif }H5 { font-family: sans-serif }H6 { font-family: sans-serif }SUB { font-size: smaller }SUP { font-size: smaller }PRE { font-family: monospace }A { text-decoration: none }--></STYLE></HEAD><BODY><LINK HREF="jpgmanual.css" REL="STYLESHEET" TYPE="text/css"><DIV class="page"><H1><A NAME="1">1 About this manual</A></H1><P></P><H2><A NAME="1_1">1.1 Version history</A></H2><P></P><P></P><TABLE border="1" cellpadding="2"><TR><TH>Version</TH><TH>Date</TH><TH>Status</TH><TH>Who</TH><TH>Comment</TH></TR><TR><TD>R1.8</TD><TD>2005-12-28</TD><TD>Released</TD><TD>Johan Persson</TD><TD>Additional info for JpGraph 1.20.1</TD></TR></TABLE><H2><A NAME="1_2">1.2 How was this manual produced?</A></H2><P> The bulk of the text was written directly in Emacs on a GNU/Linuxsystem in a mixture of PHP and HTML. A number of PHP functions wereused to automate the handling of formatting example code and figures.</P><P> To generate the images automatically in the img directory a customawk-script is used to extract all the used image script from themanual. The script then uses the client version of PHP generate theimages from the scripts and stores them in the 'img' directory.</P><P> The final set of HTML files was then processes by HTMLDOC toconstruct table of contents and chapter links.</P><H1><A NAME="2">2 Introduction</A></H1><P></P><H2><A NAME="2_1">2.1 Version</A></H2><P> This manual covers versions up to 1.20 of JpGraph. A 2D graphplotting library for PHP.</P><P> Even though the library is known to work with version of PHP priorto 4.3 the library is not tested nor is it recommended to run with anyolder versions of PHP.</P><H2><A NAME="2_2">2.2 Software License</A></H2><P> JpGraph is released under a dual license QPL 1.0 (Qt-License) fornon-commercial (including educational) use of the library and theJpGraph Professional License for commercial use.</P><H2><A NAME="2_3">2.3 JpGraph Features</A></H2><P> JpGraph library is an OO graph library which makes it easy to bothdraw a "quick and dirty" graph with a minimum of code and quite complexgraphs which requires a very fine grain of control. The library triesto assign sensible default values for most parameters hence making thelearning curve quite flat since for most of the time very few commandsis required to draw graphs with a pleasing esthetic look.</P><P> Some highlights of available features are</P><UL><LI> Flexible scales, supports text-lin, text-log, lin-lin, lin-log,log-lin and log-log and integer scales.</LI><LI> Supports both PNG, GIF and JPG graphic formats. Note that theavailable formats are dependent on the specific PHP installation wherethe library is used.</LI><LI>Supports caching of generated graphs to lessen burden of a HTTPserver.</LI><LI> Supports batch mode to only generate images to a file</LI><LI>Supports client side image maps which makes it easy to produce drilldown images.</LI><LI>Intelligent auto-scaling which gravitates towards esthetic values,i.e. multiples of 2:s and 5:s</LI><LI>Fully supports manual scaling, with fine grain control of positionof ticks.</LI><LI>Supports background images with different formatting options</LI><LI>Supports color and brightness adjustments of images directly in PHP.</LI><LI>User specified grace for auto-scaling</LI><LI> Supports up to two different y-scale, it is possible to havedifferent left and right y-scale and add plots to both</LI><LI>Supports, line-plots, filled line-plots, accumulated line-plots, barplots, accumulated bar plots, grouped bar plots, error plots, lineerror plots, scatter plots, gantt-charts, radar plots, 2D and 3D piecharts.</LI><LI>Supports unlimited number of plots in each graph, makes it easy tocompose complex graph which consists of several plot types</LI><LI>User specified position of axis</LI><LI>Supports color gradient fill in seven styles</LI><LI>Designed as a flexible OO framework which makes it easy to add newtypes of plots</LI><LI>Supports automatic legend generation</LI><LI>Supports both vertical and horizontal grids</LI><LI>Supports anti-aliasing of lines</LI><LI>Supports background images as well as unlimited number of icons inthe graph</LI><LI>Supports rotation of linear graphs</LI><LI>More then 400 named colors</LI><LI>Designed modularly - you don't have to include code which isn't used</LI><LI> ...and many many more features</LI></UL><P> In addition to these high level features the library has beendesigned to be orthogonal and consistent in its' naming convention. Forexample, to specify color each object (i.e. axis, grids, texts, titlesetc) within the graph implements the method SetColor() with the samesignature.</P><H2><A NAME="2_4">2.4 Getting the latest version</A></H2><P> The latest version of jpgraph can always be found on <A href="http://www.aditus.nu/jpgraph/">http://www.aditus.nu/jpgraph/</A></P><P> Information on version numbering schema</P><UL><LI>1.x -> 1.x.y, Bug fix release 'y' for version 1.x does not introducenew features</LI><LI>1.x -> 1.(x+1), Added functionality. Mostly keeping backwardscompatibility unless a very good reason not to.</LI><LI>1.x -> 2.0, Support for PHP5</LI></UL><P></P><H2><A NAME="2_5">2.5 Planned future addition</A></H2><P> For the latest update on planned future version see the web-site forJpGraph at http://www.aditus.nu/jpgraph/</P><H2><A NAME="2_6">2.6 Known bugs and omissions</A></H2><P></P><UL><LI>Background images does not work as expected for rotated graphs</LI></UL><P></P><H2><A NAME="2_7">2.7 Acknowledgments</A></H2><P> The idea for writing this library grew out of our own need for ahigh quality graph drawing library for PHP. When evaluating potentialexisting libraries we found (at that time circa 2001) these three</P><OL><LI> "chart 0.3" http://quimby.gnus.org/circus/chart/chart-0.3.tar.gz,by Lars Magne Ingebrigtsen</LI><LI> "ykcee.php", http://ykcee.sourceforge.net</LI><LI> "phplot.php", http://www.phplot.com</LI></OL><P> All these libraries implements some fine graphic features butunfortunately none of those completely fulfilled our needs either foravailable functionality (for example none of these supported both twoY-scales, auto-scaling, and logarithmic scales), or generalflexibility. We especially needed the option of two Y-scales, whichnone of the above packages supported. Our own preferences for designwas closest to "chart 0.3" so we started by fixing some bugs in thatpackage and adding some new features. However It was soon realized thatto add all the features and flexibility we needed to "chart 0.3" itwould require a complete rewrite since the original design wasn'tflexible enough, especially adding a second Y-scale would require amore flexible OO architecture.</P><H2><A NAME="2_8">2.8 Reporting bugs and suggesting improvements</A></H2><P> Defects or suggestion for new features can be entered using the <A href="http://www.aditus.nu/bugtraq/">JpGraph BugTracker</A> available at <A href="http://www.aditus.nu/bugtraq/">http://www.aditus.nu/bugtraq/</A></P><P> Before reporting bugs or feature suggestions may we ask that thefollowing facts are considered.</P><UL><LI>The 1.x version of the library does<B> not</B> work with PHP 5.x</LI><LI>The 1.x version of the library is only guaranteed to work with PHPversions >= 4.3</LI><LI>The 2.x version of the library does<B> not</B> work with PHP 4.x</LI></UL><P></P><H2><A NAME="2_9">2.9 Getting support</A></H2><P> Customers who have acquired the pro-version of the library areentitled to prioritized e-mail support for a specific time after thepurchase. Support tickets may be created by first logging in to <A href="http://www.aditus.nu/jpgraph/pro_login.html">http://www.aditus.nu/jpgraph/pro_login.php</A> and then create a supportticket.</P><P> For other users a public community forum is available at <A href="http://jpgraph.intellit.nl/">http://jpgraph.intellit.nl/</A> where many common questions are answeredand discussed.</P><P> A collection of FAQ is available at <A href="http://www.aditus.nu/jpgraph/jpgraphfaq.html">http://www.aditus.nu/jpgraph/jpgraphfaq.php</A></P><P> In addition there is a growing list of "HowTo" documents availableat <A href="http://www.aditus.nu/jpgraph/jpgraphhowto.html">http://www.aditus.nu/jpgraph/jpgraphowto.php</A></P><P> Finally, we regret that we are unable to provide general supportregarding PHP/GD/TTF/Apache installation outside the specific scope ofthe JpGraph library. Please see the corresponding documentation andrelevant FAQ for those products.</P><P></P><H1><A NAME="3">3 Installation</A></H1><P></P><H2><A NAME="3_1">3.1 Preparation</A></H2><P> In order to make use of the library it is necessary to ensure thatthe script files can correctly access the library include files (asdescribed below) and that the PHP installation supports at least onegraphic format, i.e. it supports the "image" extension in PHP.</P><P> This is easiest verified by either checking the output of the<I>phpinfo()</I> standard PHP function or by making sure the PHPinstallation make the 'imagecreate()' function available.</P><P> This means that the installation<!--string-->must have a working GD-library together with PHP before the libraryJpGraph can be used. Please make sure you have version 4.3.x or aboveof PHP since JpGraph is<STRONG> not</STRONG> actively tested withversions prior to PHP 4.3.x Ideally you should use at least PHP 4.3.8</P><P> Please note that the 1.x version of the library do<B> not</B>support PHP 5.x</P><H3><A NAME="3_1_1">3.1.1 Verifying that you have the GD libraryinstalled</A></H3><P> In order to make sure that the GD installed the following examplewould be run. The example creates a very simple image using just pureGD calls and outputs an image in PNG format. This could be considered asmoke-test to see that the GD library is available from PHP. Pleasenote that this is an<B> absolute</B> pre-requisite in order for theJpGraph library to work at all.</P><P> Store the code snippet below somewhere in the document root and makesure it runs correctly.<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $im </FONT><FONT color="#007700">= @</FONT><FONT color="#0000BB">ImageCreate </FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">150</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">100</FONT><FONTcolor="#007700">)<BR> or die (</FONT><FONT color="#DD0000">"Cannot create a new GD image."</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$background_color </FONT><FONT color="#007700">= </FONT><FONT color="#0000BB">ImageColorAllocate </FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$im</FONT><FONT color="#007700">, </FONT><FONTcolor="#0000BB">255</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">255</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">255</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">$text_color </FONT><FONT color="#007700">= </FONT><FONT color="#0000BB">ImageColorAllocate </FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$im</FONT><FONT color="#007700">, </FONT><FONTcolor="#0000BB">233</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">14</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">91</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">ImageString </FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$im</FONT><FONT color="#007700">, </FONT><FONTcolor="#0000BB">1</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">5</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">5</FONT><FONTcolor="#007700">, </FONT><FONT color="#DD0000">"A Simple Text String"</FONT><FONTcolor="#007700">, </FONT><FONT color="#0000BB">$text_color</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">header </FONT><FONT color="#007700">(</FONT><FONTcolor="#DD0000">"Content-type: image/png"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">ImagePng </FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$im</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> If the above script does not work or some error or warnings areprinted on the screen then it is necessary to correct those problemsbefore proceeding with the installation.</P><H3><A NAME="3_1_2">3.1.2 Verifying that you have GD2 installed</A></H3><P> To access the more advanced features of JpGraph needs the GD 2.xlibrary. This will allow the use of features such as alpha-blending andtrucolor images.</P><P> The GD 2.x library is included in all standard PHP versions from4.2.x and above. To make sure that the GD 2.x library is installed thefollowing script must be working.<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $im </FONT><FONT color="#007700">= </FONT><FONT color="#0000BB">imagecreatetruecolor </FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">300</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">200</FONT><FONTcolor="#007700">); <BR></FONT><FONT color="#0000BB">$black </FONT><FONT color="#007700">= </FONT><FONTcolor="#0000BB">imagecolorallocate </FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$im</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">0</FONT><FONTcolor="#007700">, </FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">); <BR></FONT><FONT color="#0000BB">$white </FONT><FONT color="#007700">= </FONT><FONTcolor="#0000BB">imagecolorallocate </FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$im</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">255</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">255</FONT><FONTcolor="#007700">, </FONT><FONT color="#0000BB">255</FONT><FONT color="#007700">); <BR><BR></FONT><FONT color="#0000BB">imagefilledrectangle</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$im</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">399</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">99</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$white</FONT><FONT color="#007700">); <BR></FONT><FONT color="#0000BB">imagerectangle</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$im</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">20</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">20</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">250</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">190</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$black</FONT><FONT color="#007700">); <BR><BR></FONT><FONT color="#0000BB">header </FONT><FONT color="#007700">(</FONT><FONTcolor="#DD0000">"Content-type: image/png"</FONT><FONT color="#007700">); <BR></FONT><FONT color="#0000BB">imagepng </FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$im</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> After running this script you should now see a black rectangle inyour browser.</P><H3><A NAME="3_1_3">3.1.3 Preparing True Type Font Files</A></H3><P> JpGraph contains as default a standard set of bitmap fonts whichonly supports the standard ASCII 7-bit character set. In order to useaccented characters, UTF-8, Chinese, Japanese, etc You need to downloadTTF fonts. Due to various legal issues no TTF fonts are supplied in theJpGraph package. To enable TTF fonts there are three alternatives:</P><OL><LI>If you are on a Windows platform you can just point to the TTFdirectory in JpGraph to the standard fonts directory (e.gC:\windows\fonts\)</LI><LI>If you are on a Unix platform you can download and install the coreMS WEB-initiative fonts from <A href="http://corefonts.sourceforge.net/">http://corefonts.sourceforge.net/</A></LI><LI>It is also possible to use the Vera Bitstream TTF fonts availablefrom <A href="http://www.gnome.org/fonts/">http://www.gnome.org/fonts/</A></LI></OL><P> It is also necessary to make sure that the PHP installation supportsTTF fonts (either through FreeType 1 or FreeType 2 libraries). I naddition some suitable TTF font files must also be available. To makethe font files available for the library the directory path to thelocation of the font files must be specified in the configuration file,jpg-config.inc</P><P> JpGraph uses a standard naming convention for the TTF font files inorder to be able to find the correct font files. This naming conventionfollows the standard naming of the available font files.</P><P> If the installation of the library is made on a computer running MSWindows then it is recommended to use the already available font filesin Windows (usually located in C:\WINDOWS\FONTS).</P><P> If the installation is made on a UNIX derivate running X11 then thefont location can differ between versions and UNIX brands. One commonlyused path is "/usr/X11R6/lib/X11/fonts/truetype/".</P><P> Finally we note that it is possible to install additional fonts notnatively supported by the library. Since this requires augmenting thelibrary files this is considered advanced use and not further discussedin this introduction.</P><H3><A NAME="3_1_4">3.1.4 Using non-latin based fonts with JpGraph</A></H3><P> In addition to European font it is also possible to use non-latinbased fonts such as Cyrillic, Japanese and Chinese.</P><P> In all cases a suitable TTF font that supports the non-latin basedlanguage must be available.</P><P> For Cyrillic support the define LANGUAGE_CYRILLIC in jpg-config.phpmust be set to true. It is then possible to use a suitable Cyrillicfont as replacement for the ordinary fonts.</P><P> For Chinese character set JpGraph supports both BIG5 and GB2312encoding. For BIG5 encoding the PHP installation must have support forthe "iconv()" function. Furthermore the define CHINESE_TTF_FONT must beset to the name of the Chinese BIG5 font that is to be used. By defaultthis is set to "bkai00mp.ttf". To use the Chinese BIG5 font in thescripts one must then specify the font family as FF_CHINESE.</P><P> To use the alternative font files "simsun.ttc" and "simhei.ttf"(which uses the GB2312 encoding) the only step needed is to installthose fonts in the normal TTF font directory and then specify the fontfamily as FF_SIMSUN, the "simhei.ttf" is used when the font style isspecified as FS_BOLD.</P><H2><A NAME="3_2">3.2 Customizing the installation</A></H2><P> In order for JpGraph to work it is necessary to adjust the cache andTTF directory to suit the specific installation. By default the TTFdirectory is "/usr/X11R6/lib/X11/fonts/truetype/" and for the cache"/tmp/jpgraph_cache/". These are defined as PHP defines at the top of<I>jpg-config.inc</I></P><P> Please make sure that PHP has write permissions to the cachedirectory if the cache feature should be used. If this is not the casea "Can't write file xxx.yyy" error will occur when a graph that usesthe cache feature are generate. More information regarding the cachefeature of JpGraph is available in the section<I> Making sense ofcaching system in JpGraph</I></P><H2><A NAME="3_3">3.3 Required files</A></H2><P> This is the base library files, which you must have</P><UL><LI> jpgraph.php, base library, always needed</LI><LI> jpg-config.inc, Configuration file</LI></UL><P></P><H3><A NAME="3_3_1">3.3.1 Plot extension modules</A></H3><P> To add plots to the graph you will need one or more of the followingfiles plot extension files depending on what kind of graph you need tocreate.</P><UL><LI>jpgraph_log.php, Plot extension to support logarithmic X and Yscales</LI><LI>jpgraph_line.php, Plot extension. Needed to draw various line plots</LI><LI>jpgraph_date.php, Plot extension to handle date scales.</LI><LI>jpgraph_bar.php, Plot extension. Needed to draw various bar plots</LI><LI>jpgraph_error.php, Plot extension. Needed to draw various errorplots</LI><LI>jpgraph_scatter.php, Plot extension. Needed to draw scatter andimpulse plots.</LI><LI>jpgraph_spider.php, Plot extension. Needed to draw spider plots.</LI><LI>jpgraph_pie.php, Plot extension. Needed to draw Pie plots</LI><LI>jpgraph_pie3d.php, Plot extension. Needed to draw 3D Pie plots</LI><LI>jpgraph_gantt.php, Plot extension. Needed to create gantt plots</LI><LI>jpgraph_radar.php, Plot extension. Needed for radar plots</LI><LI>jpgraph_polar.php, Plot extension. Needed for Polar plots</LI><LI>jpgraph_gantt.php, Plot extension. Needed for Gantt charts</LI><LI>jpgraph_regstat.php, Statistic extension. Needed to plot spline andbezier curves</LI><LI> jpgraph_stock.php, Plot extension. Needed to plot stock charts</LI><LI> jpgraph_antispam.php, Special extension to generate anti-spamimages consisting of letters+images which are very hard to digitallyread with an OCR program</LI><LI> jpgraph_gradient.php, Internal module. Contains all color gradient</LI><LI> jpgraph_gb2312.php, Handling of gb2312 font encoding (used for someChinese fonts)</LI><LI> jpgraph_plotmark.inc, Handling of plotmarks in line and scatterplot.</LI><LI> jpgraph_iconplot.php, Handling icons (small images) that can beadded to the plots</LI><LI> jpgraph_plotband.php, Handling of plotbands added to the graphs</LI><LI> jpgraph_flags.php, Handling of country flags used as plot marks oras backgrounds.</LI><LI> jpgraph_utils.php, Various utility function</LI><LI> imgdata_*.inc, Encoded images for plotmarks</LI><LI> flags*.dat, Image data for flags. Pre-compiled data for countryflags.</LI><LI>jpgraph_canvas.php, Plot extension to make it possible to drawarbitrary graphic on a canvas.</LI><LI>jpgraph_canvtools.php, Add on to the canvas graph to provide aneasier way to draw arbitrary shapes.</LI></UL><P> In the pro-version the following additional files are available</P><UL><LI> jpgraph_windrose.php, Windrose plot extension</LI><LI> jpgraph_odo.php, Odometer plot extension</LI><LI> jpgraph_barcode.php, Linear barcode extension</LI><LI> jpgraph_pdf417.php, PDF417 2-Dimensional Barcode extension</LI></UL><P></P><H2><A NAME="3_4">3.4 Image formats and external image libraries</A></H2><P> Per default the standard GD image library supports PNG graphicformats. You will need to have that installed together with your PHPmodule for this library to work at all. Please refer to PHPdocumentation on specifics. Note that the newer versions of GD does notsupport the GIF format due to copyright problems. Hence by default onlyPNG is supported.</P><P> If you want JPEG support you will also need an additional libraryfor PHP, again please see PHP documentation for specifics. For mostpractical purposes PNG is a better format since it normally achievesbetter compression then GIF (typically by a factor of 2 for the typesof images generated by JpGraph). In comparison with JPEG format PNG isalso better for the type of images generated by this library. So, thebottom line is, you should have a very good reason to choose any otherformat then PNG.</P><P> By default the image format is set to "auto". This means thatJpGraph automatically chooses the best available graphic using thepreferred order "PNG", "GIF", "JPG".</P><P></P><H2><A NAME="3_5">3.5 Detailed steps to install JpGraph</A></H2><P></P><OL><LI>If You are insatlling the 1.x branch then make sure the PHP versionused is at least 4.3.x (preferable 4.3.10 or higher) and that the PHPversion have compiled support for GD library. It is absolutely criticalthat GD is fully working. Please see the earlier sections on how tomake sure. JpGraph supports both GD 1.x and GD 2.x However it isstrongly recommended to use GD 2.x since that will improve performanceand support true color images as well as alphablending.<P> If You are insatlling the 2.x branch then make sure the PHP versionused is at least 5.0.1 (preferable 5.0.5 or higher) and that the PHPversion have compiled support for GD 2.x library. Please note that the2.x branch will<B> not</B> work with PHP 4.x</P></LI><LI>Unzip and copy the files to a directory of your choice.</LI><LI>Set up the directory paths in<I> jpg-config.inc</I> where the cachedirectory should be and where your TTF directory is. Note thatApache/PHP must have write permission in your cache directory.</LI><LI> Check that all rest of the DEFINE in the top of JpGraph.php issetup to your preference. The default should be fine for most users.(See also Note 5. below) Specifically check that the settings ofUSE_GD2_LIBRARY reflects your installation, (should be true if you haveGD2 installed, false otherwise).</LI><LI>Make sure PHP have write privileges to your cache directory if youplan on using the cache feature.</LI><LI> Some windows installations seems to have a problem with a PHPscript ending in a newline (This newline seems to be sent to thebrowser and will cause a Header already sent error). If you have thisproblem try remove all trailing newlines in the jpgraph* files</LI><LI> Read (really!) <A href="http://www.aditus.nu/jpgraph/jpgraphfaq.html">the JpGraph FAQ</A>.</LI></OL><P></P><H2><A NAME="3_6">3.6 Troubleshooting your installation</A></H2><P> For 99% of the users this library will work directly with a recentinstallation of PHP without any problem.</P><P> Experience shows that most of the trouble are caused by either anold buggy version of the free-type TTF library or using an oldantiquated version of the GD library. In order to narrow it down theproblem the following steps is helpful.</P><OL><LI> If no background images are displayed (instead a solid black boxare displayed) chances are that GD 2.x is available but thejpg-config.inc has been changed so that true color images are disabled.Correct this by enabling the USE_TRUECOLOR define.</LI><LI> If background images does not work make sure the settings ofUSE_GD2_LIBRARY corresponds to the actual installation, i.e. If the GD2library is not available then this define must be false!</LI><LI> If you are running IIS and Win2k and get the error "Can't findfont" when trying to use TTF fonts then try to change the paths to UNIXstyle, i.e. "/usr/local/fonts/ttf/". Remember that the path is absoluteand not relative to the htdocs catalogue.</LI><LI> If no images and no error messages gets sent back to the browserthen there is a big chance that HTTP-Server PHP module (e.g.Apache-PHP) has crashed. This is often due to a broken PHP installationand more than often a problem with the True Type libraries. The bestway to track these types of problem down is to investigate theHTTP-Server logs or the general system logs for evidence of a PHPcrash. The other reasons is that in some rare cases the auto detectionof the GD library could fail. If only the GD1 library is available andthe JpGraph library mistakenly detects the GD2 this could in rare casescause PHP to crash. Please try re-run the example by setting the DEFINEUSE_GD2_LIBRARY to "false".</LI><LI> If the system is running IIS on Windows and some images which usesTTF fonts just return an empty page then try to set the TTF_DIR pathmanually (in jpg-config.php) to the directory where all the TTF fontsare stored (normally c:/WINDOWS/fonts)</LI><LI> If the cache is enabled please make sure that the permissions arecorrectly set for the cache directory so that the process runningApache/PHP has write access to the cache directory.</LI><LI> If the TTF fonts only shows up as yellow then you have a buggyinstallation of the freetype font library and the only thing to do isto re-install and setup PHP+GD again.</LI></OL><P></P><H2><A NAME="3_7">3.7 Compiling PHP 4</A></H2><P><I> This is not meant to be a complete discussion about configuringor compiling PHP. It is meant as an example of a configuration of PHPthat is known to work well with JpGraph.</I></P><P> Below is an example of a standard configuration that can be used toconfigure and compile PHP for use with the JpGraph Library</P><P> Please note that depending on the specific installation requirementsother options might have to be specified, specifically the paths toexternal libraries might need to be adjusted.</P><PRE>./configure --prefix=/usr/share \--datadir=/usr/share/php \--with-apxs=/usr/sbin/apxs \--libdir=/usr/share \--includedir=/usr/include \--bindir=/usr/bin \--with-config-file-path=/etc \--enable-mbstring --enable-mbregex \--with-pdflib=/usr \--with-mysql \--with-ttf-dir=/usr/lib \--with-freetype-dir=/usr/lib \--with-gd --enable-gd-imgstrttf --enable-gd-native-ttf \--with-zlib-dir=/usr/lib \--with-png-dir=/usr/lib --with-jpeg-dir=/usr/lib --with-xpm-dir=/usr/X11R6 \--with-tiff-dir=/usr/lib \--enable-ftp \--enable-memory-limit --enable-safe-mode \--bindir=/usr/bin \--enable-bcmath -enable-calendar \--enable-ctype --with-ftp \--enable-magic-quotes \--enable-inline-optimization \--with-bz2 \--with-iconv</PRE><H1><A NAME="4">4 Quick Start: Dynamic Image Generation</A></H1><P> The purpose of this chapter is to put dynamic image generation inperspective and illustrate how HTML tags is used to call imagegenerating scripts. Even if You are familiar with PHP it is stronglyrecommended to quickly browse through this chapter to make sure allconcepts are known.</P><P> If You fully understand and can explain the concept of MIME types,HTTP streams and why the "Headers already sent error" error is verycommon when generating dynamic images with PHP it is probably safe toskip this chapter. Otherwise it might be wise to read through thischapter once.</P><H2><A NAME="4_1">4.1 Scope of this chapter</A></H2><P></P><H3><A NAME="4_1_1">4.1.1 What you will learn in this chapter</A></H3><P></P><OL><LI> The principle of generating dynamic images in PHP</LI><LI> How to choose a specific image format (e.g. JPG, PNG, GIF)</LI><LI> Various ways of using the generated image, streaming it back to thebrowser, sending it to a file or getting hold of the image handle forfurther post processing</LI><LI> How to specify fonts (both bit-mapped and TTF) in JpGraph</LI><LI> How to extend JpGraph with your own fonts</LI><LI> How to work with Cyrillic fonts</LI><LI> How to specify colors in JpGraph</LI><LI> List all available named colors in JpGraph</LI><LI> How to effectively use the built in cache schema in JpGraph</LI></OL><P></P><H3><A NAME="4_1_2">4.1.2 What you will NOT learn in this chapter</A></H3><P></P><OL><LI> Any details on how to generate graphs with the JpGraph library</LI></OL><P></P><H2><A NAME="4_2">4.2 How to generate images with PHP</A></H2><P> As a general rule each PHP script which generates an image must bespecified in a separate file which is then called in an HTML <IMG> tag.For example, the following HTML excerpt includes the image generated bythe PHP script in "fig1.php".</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> </FONT><FONT color="#007700"><</FONT><FONT color="#0000BB">img src</FONT><FONTcolor="#007700">=</FONT><FONT color="#DD0000">"fig1.php" </FONT><FONT color="#0000BB">border</FONT><FONT color="#007700">=</FONT><FONT color="#0000BB">0 align</FONT><FONTcolor="#007700">=</FONT><FONT color="#0000BB">center width</FONT><FONT color="#007700">=</FONT><FONT color="#0000BB">300 height</FONT><FONT color="#007700">=</FONT><FONTcolor="#0000BB">200</FONT><FONT color="#007700">></FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> Strictly speaking the "align", "width" and "height" are notnecessary but helps the browser position the image correctly before theimage has been fully sent back to the browser.</P><P> The library will automatically generate the necessary headers to besent back to the browser so that it correctly recognize the data streamreceived as an image of either PNG/GIF/JPEG format. The browser canthen correctly decode the image</P><P> Observe that you<STRONG> can't</STRONG> return anything else than animage from the image script. By definition each HTML page (or morecorrectly each HTTP stream) can only consist of one mime type which isdetermined by the header for that particular stream.</P><P> A common mistake is to have a space in the beginning of the imagescript which the HTTP server will send back to the browser. The browsernow assumes that the data coming back from this script is text since ithasn't received an explicit header. When then the image headers getsent back to the browser to forewarn the browser of the forthcomingimage the browser will not like that as it has already assumed the datastream was a text stream. The browser will then give the infamous"Headers already sent error".</P><P> To include several images together with text on a page you need tohave a parent page with several <IMG> tags which each refers to animage script (or the same image script with GET/POST data).</P><H3><A NAME="4_2_1">4.2.1 Using the JpGraph library to send back images</A></H3><P> To get access to the JpGraph library you will need to include atleast two files, the base library and one or more of the plotextensions. So for example to create a basic line plot the top of yourPHP file must have the lines:<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> <BR></FONT><FONT color="#007700">include (</FONT><FONT color="#DD0000">'jpgraph.php'</FONT><FONT color="#007700">);<BR>include (</FONT><FONT color="#DD0000">'jpgraph_line.php'</FONT><FONT color="#007700">);<BR>...<BR> </FONT><FONT color="#FF8000">// Code that uses the jpgraph library<BR></FONT><FONT color="#007700">...</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P><DIV class="note"><B>Note:</B> You might also use the PHP directive<I>require</I>. The difference is subtle in that include will only includethe code if the include statement is actually executed. While require()will always be replaced by the file specified. See PHP documentationfor further explanation. For most practical purposes they areidentical.</DIV></P><H2><A NAME="4_3">4.3 Using PHP directly</A></H2><P> It is also possible to generate images directly using the commandline version of PHP. This works the same way as the normal "through thebrowser" generation with the exception that no HTTP headers will begenerated. Only the binary image data.</P><P> Please make sure that you run the command line version of PHP (cli).Using the CGI SAPI version will not work since then the HTTP headerswill be generated. Note: If the CGI version is used the generation ofheaders may be suppressed by the '-q' option.</P><P> You can easily check the version installed by running</P><PRE>php --version</PRE><P> you should then get a response with something like</P><PRE>PHP 4.3.8 (cli) (built: Aug 29 2004 22:48:10)Copyright (c) 1997-2004 The PHP GroupZend Engine v1.3.0, Copyright (c) 1998-2004 Zend Technologies</PRE><P> The important thing here is the</P><PRE>(cli)</PRE><P> marker. The JpGraph library check from what SAPI API it is invokedfrom and adjusts the header generation accordingly.</P><P> If all the above requirements are met then images can be generateddirectly on the command line and stored in a suitable file. For exampleby</P><PRE>$> php myimage.php > image.png</PRE><P> Please note that the file extension on the image file must match theformat in which the image is generated.</P><H2><A NAME="4_4">4.4 The basic principle of JpGraph and the creation ofimages</A></H2><P> The common pattern for creating graphs is</P><OL><LI> Create a script that constructs the image, type, colors size and soon.</LI><LI> A wrapper script which contains one or more <IMG> tags to positionthe graphs on the proper HTML page.</LI></OL><P> Of course it is of perfectly possible to call the image scriptdirectly in the browser to just display the generated image in thebrowser.</P><P> You should remember that it is also possible to pass arguments tothe image script via the normal HTTP GET/POST arguments. For example<DIVclass="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> </FONT><FONTcolor="#007700"><</FONT><FONT color="#0000BB">img src</FONT><FONT color="#007700">=</FONT><FONT color="#DD0000">"showgraph.php?a=1&b=2"</FONT><FONT color="#007700">></FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> This could for example be used to control the appearance of theimage or perhaps send data to the image which will be displayed. Notethat this is probably not the best way to send large amount of data toplot. Instead the only practical way, for large data sizes, is to getall the data in the image script, perhaps from a DB. Anotheralternative for large amount of data to be sent to the image script isby creating a POST request to the image script.<DIV class="note"><B>Note:</B><B> Forcing the browser to update your image</B> Some browsermay not send back a request to the web browser unless the user presses"Refresh" (F5 - in most browsers). This can lead to problems that theuser is seeing old data. A simple trick is to add a dummy time argumentwhich is not used in the script. For example<PRE>echo '<img src="myimagescript.php?dummy='.now().'">';</PRE>It is also important to be aware of any internal caching the browsermight do. The general problem with dynamically generated images is thatthe image generating script (file) remains the same. This makes thebrowser believe that the data hasn't changed and if the browser alreadyhas issues a previous GET request and has the data cached it will notsend a new GET if the timestamp on the file is the same since it thenbelieves it my use the old cached version.</DIV></P><P> When it comes to the structure of your imaging script they willgenerally have the structure<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> </FONT><FONT color="#FF8000">// ... Include necessary headers<BR><BR></FONT><FONT color="#0000BB">$graph </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">Graph</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$width</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$height</FONT><FONT color="#007700">, ...);<BR><BR></FONT><FONT color="#FF8000">// ... code to construct the graph details<BR><BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Stroke</FONT><FONT color="#007700">();<BR></FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> JpGraph is completely Object oriented so all calls will be action onspecific instances of classes. One of the fundamental classes is theGraph() class which represents the entire graph.</P><P> After the creation of the Graph() object all the code lines toconstruct the details of the graph are added.</P><P> The final method called in an image script will most likely be the<I>Graph::Stroke()</I> method. This will send the constructed image backto the browser. A variation of this is used if the graph are supposedto have image maps. In that case the final method will be<I>Graph::StrokeCSIM()</I></P><P> In addition to this standard usage pattern you can also choose to</P><UL><LI> ... send the graph directly to a file</LI><LI> ... access the GD image handler for further image processing (alsoneeded to include the image in an PDF file)</LI><LI> ... make use of the builtin cache system to send back a previouslygenerated image</LI></UL><P> The cache system, which lessens the burden of the PHP server, worksby avoiding o run all the code that follows the initial Graph() call bychecking if the image has already been created and in that casedirectly send back the previously created (and stored in a file) imageto the browser. When using the cache system a filename must bespecified in the initial Graph() call which is used to store the imagein the cache system and possibly also a timeout value to indicate howlong the image in the cache directory should be valid.</P><P> In many of the examples in this manual the following pattern will beused<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">Graph</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">300</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">200</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"auto"</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P> The two first parameters specify the width and height of the graphand the third parameter the name of the image file in the cachedirectory. The special name<I> 'auto'</I> indicates that the image filewill be given the same name as the image script but with the extensionchanged to indicate the graphic format used, i.e '.jpg', '.png' and soon.</P><P> Please note that the cache system by default is disabled and must beenabled by setting the proper define in the file "jpg-config.inc"</P><H2><A NAME="4_5">4.5 Choosing the image format for JpGraph</A></H2><P> By default JpGraph automatically chooses the image format to use inthe order PNG, JPEG and GIF. The exact format depends on what isavailable on your system. There are two ways you can influence the waythe graphic format is chosen.</P><OL><LI> Change the default graphic format by changing the DEFINE<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> DEFINE</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"DEFAULT_GFORMAT"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"auto"</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV><P></P></LI><LI> Set the graphic format in your script by calling the method <A href="../ref/Image.html#_IMAGE_SETIMGFORMAT">SetImgFormat()</A> For example, to force your script to use JPEG in onespecific image use<DIV class="phpscript"><CODE><FONT color="#000000"> <FONTcolor="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">img</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetImgFormat</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"jpeg"</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P></P></LI></OL><P></P><H2><A NAME="4_6">4.6 Alternatives to streaming back the image</A></H2><P> If you like to save the image directly to a file instead ofstreaming it back to the browser then you just have to specify anabsolute filename in the final call to Graph::Stroke(), i.e.</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Stroke</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"/usr/home/peter/images/result2002.png"</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> Please note that the user running as Apache/PHP must have writeaccess to the specified directory.</P><P> There are also two predefined filenames which have special meaning.</P><UL><LI>"auto", This will create a file in the same directory as the scriptwith the same name as the script but with the correct image extension.</LI><LI>_IMG_HANDLER, (This is defined in jpgraph.php). Specifying thisfilename will not create a an image to file or stram it back to thebrowser. Instead it will instruct the Stroke() method to just returnthe handle for the GD image. This is useful if you later want tomanipulate the image in ways that are not yet supported by Jpgraph. Forexample include the image in generated PDF files.<BR><I> Example:</I><DIV class="phpscript"><CODE><FONT color="#000000"> <FONTcolor="#0000BB"> $handle </FONT><FONT color="#007700">= </FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Stroke</FONT><FONTcolor="#007700">(</FONT><FONT color="#0000BB">_IMG_HANDLER</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P></P></LI></UL><P></P><H2><A NAME="4_7">4.7 Working with fonts in JpGraph</A></H2><P> JpGraph supports both a set of built in bit-mapped fonts as well asTrue Type Fonts. For scale values on axis it is strongly recommendedthat you just use the built in bitmap fonts for the simple reason thatthey are, for most people, easier to read (they are also quicker torender). Try to use TTF only for headlines and perhaps the title for agraph and it's axis. By default the TTF will be drawn withanti-aliasing turned on.</P><P> In many of the example you can see examples of both TrueType andBitmap fonts.</P><P> There are a number of subtle differences in the way builtin fontsand TrueType fonts are rendered to the screen. However, JpGraph,abstracts away 99.9% of the differences so it will be, for the user,completely transparent to switch between the different fonts.</P><H3><A NAME="4_7_1">4.7.1 Installing TrueType fonts</A></H3><P> Since Internally TrueType fonts are rendered by locating a fontspecification file you must install the accompanying TrueType fonts indirectory of your choice. You must then tell JpGraph where these fontsmay be found by specifying the font-path in the FONT_PATH define (injpg-config.inc). Please note that this must be the absolute file pathand not relative to the htdocs directory. By default the path is set to<DIVclass="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> DEFINE</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"TTF_DIR"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"/usr/local/fonts/ttf/"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> Since JpGraph must be able to tell the difference between the italicand bold versions of the same font family a standard naming conventionis used to name the files. The available fonts are also defined byDEFINES and hence you can't just copy your own TTF files to thedirectory and expect it to work. At the moment there is no "easy" wayto add new fonts but to make some (small) mods to the code. Howeverthis is expected to change in future version of JpGraph.</P><H3><A NAME="4_7_2">4.7.2 Verifying that the TTF fonts work</A></H3><P> In order to get TTF fonts working with JpGraph you should firstcheck that the following pure GD scripts work correctly. Please adjustthe font path according to your installation.<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> DEFINE</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"TTF_DIR"</FONT><FONT color="#007700">,</FONT><FONTcolor="#DD0000">"/usr/X11R6/lib/X11/fonts/truetype/"</FONT><FONT color="#007700">); <BR><BR></FONT><FONT color="#0000BB">$im </FONT><FONT color="#007700">= </FONT><FONTcolor="#0000BB">imagecreatetruecolor </FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">400</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">100</FONT><FONT color="#007700">); <BR></FONT><FONT color="#0000BB">$black </FONT><FONT color="#007700">= </FONT><FONTcolor="#0000BB">imagecolorallocate </FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$im</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">0</FONT><FONTcolor="#007700">, </FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">); <BR></FONT><FONT color="#0000BB">$white </FONT><FONT color="#007700">= </FONT><FONTcolor="#0000BB">imagecolorallocate </FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$im</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">255</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">255</FONT><FONTcolor="#007700">, </FONT><FONT color="#0000BB">255</FONT><FONT color="#007700">); <BR><BR></FONT><FONT color="#0000BB">imagerectangle</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$im</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">399</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">99</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$black</FONT><FONT color="#007700">); <BR></FONT><FONT color="#0000BB">imagefilledrectangle</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$im</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">399</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">99</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$white</FONT><FONT color="#007700">); <BR><BR></FONT><FONT color="#0000BB">imagettftext </FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$im</FONT><FONT color="#007700">, </FONT><FONTcolor="#0000BB">30</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">10</FONT><FONTcolor="#007700">, </FONT><FONT color="#0000BB">40</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">$black</FONT><FONT color="#007700">, </FONT><FONTcolor="#0000BB">TTF_DIR</FONT><FONT color="#007700">.</FONT><FONT color="#DD0000">"arial.ttf"</FONT><FONT color="#007700">, </FONT><FONT color="#DD0000">"Hello World!"</FONT><FONT color="#007700">); <BR><BR></FONT><FONT color="#0000BB">header </FONT><FONT color="#007700">(</FONT><FONTcolor="#DD0000">"Content-type: image/png"</FONT><FONT color="#007700">); <BR></FONT><FONT color="#0000BB">imagepng </FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$im</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The above script assumes you have the GD2 library and will create animage with the classical "Hello World!" text printed in black.</P><H3><A NAME="4_7_3">4.7.3 Specifying fonts</A></H3><P> All graph objects that uses text allows you to specify the font tobe used by calling the SetFont() method and specifying three parameters</P><OL><LI> Font family, Specified with a FF_ define</LI><LI> Font style, Specified with a FS_ define</LI><LI> Font size, Numeric value (only used for TTF fonts)</LI></OL><P> For the builtin fonts the third, size, parameter is ignored sincethe size is fixed for the three builtin fonts. The available fontfamilies and the corresponding name (in JpGraph 1.7) are listed in thetable below.</P><P></P><TABLE border="1"><TR><TD>Font family</TD><TD>Type</TD><TD>Note</TD></TR><TR><TD>FF_FONT0</TD><TD>Builtin font</TD><TD>A very small font, onlyone style</TD></TR><TR><TD>FF_FONT1</TD><TD>Builtin font</TD><TD>A medium sized font</TD></TR><TR><TD>FF_FONT2</TD><TD>Builtin font</TD><TD>The largest bit mappedfont</TD></TR><TR><TD>FF_ARIAL</TD><TD>TTF font</TD><TD>Arial font</TD></TR><TR><TD>FF_VERDANA</TD><TD>TTF font</TD><TD>Verdana font</TD></TR><TR><TD>FF_COURIER</TD><TD>TTF font</TD><TD>Fix pitched courier</TD></TR><TR><TD>FF_BOOK</TD><TD>TTF font</TD><TD>Bookman</TD></TR><TR><TD>FF_COMIC</TD><TD>TTF font</TD><TD>Comic sans</TD></TR><TR><TD>FF_TIMES</TD><TD>TTF font</TD><TD>Times New Roman</TD></TR><TR><TD>FF_GEORGIA</TD><TD>TTF font</TD><TD>Georgia</TD></TR><TR><TD>FF_TREBUCHE</TD><TD>TTF font</TD><TD>Trebuche</TD></TR><TR><TD>FF_VERA</TD><TD>TTF font</TD><TD>Gnome Vera font, Available fromhttp://www.gnome.org/fonts/</TD></TR><TR><TD>FF_VERAMONO</TD><TD>TTF font</TD><TD>Gnome Vera Mono font,Available from http://www.gnome.org/fonts/</TD></TR><TD>FF_VERASERIF</TD><TD>TTF font</TD><TD>Gnome Vera Serif font,Available from http://www.gnome.org/fonts/</TD><TR><TD>FF_CHINESE</TD><TD>TTF font</TD><TD>Installed chinese font</TD></TR><TR><TD>FF_SIMSUN</TD><TD>TTF font</TD><TD>Installed chinese font</TD></TR><TR><TD>FF_BIG5</TD><TD>TTF font</TD><TD>Installed Chinese BIG5 font(needs iconv())</TD></TR></TABLE><P> Please note that not all font families support all styles. Thefigure below illustrates each of the available font families and whatstyles you may use.<DIV class="example"><BR> <A href="exframes/frame_listfontsex1.html" target="blank"><IMG border="0"HEIGHT="450" src="img/img/img/img/img/img/img/img/listfontsex1.png" WIDTH="550"></A><BR><B>Figure 1:</B> Illustration of some of the available fonts inJpGraph <A href="exframes/frame_listfontsex1.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P> We finally show some example of valid font specifications<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">FF_FONT2</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">FF_FONT2</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FS_BOLD</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">FF_ARIAL</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">FF_ARIAL</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FS_BOLD</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">24</FONT><FONTcolor="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><H3><A NAME="4_7_4">4.7.4 Adding additional fonts to JpGraph</A></H3><P><STRONG> Note:</STRONG> This information is only given here for veryadvanced users. No free support will be given in the case you run intodifficulties trying to add new fonts. At the moment adding new fontsrequire code modifications as outlined below.</P><P> In order to add you favorite fonts there are three steps you need tofollow :</P><OL><LI> Define a new "FF_" constant naming your font family with a suitablehigh index number</LI><LI>Get the TTF file(s) and add it to your font directory. You needseparate files for each of the styles you want to support. You thenneed to add the file names of the font as definitions in the class TTF.Use the previous defined "FF_" name as index in the font specificationarray.</LI></OL><P></P><H3><A NAME="4_7_5">4.7.5 Understanding text alignment in JpGraph</A></H3><P> For everyday use of JpGraph understanding of the alignment of textstrings in not necessary. However, if you like to add arbitrary stringsto the graph (with Graph::AddText()) or when working directly on acanvas it will help understand this.</P><P> Text is added to a graph with the creation of a <A href="../ref/Text.html#_C_TEXT">Text()</A> object. And the alignment is specified with <A href="../ref/Text.html#_TEXT_ALIGN">Text::Align()</A> Text alignment might actually be a misguiding name.What you specify is rather the anchor point for the text, i.e. when youspecify that a text should be positioned at position<I> (x,y)</I> howis that coordinate to be interpretated.</P><P> The image below shows a text string aligned in the 9 possiblecombinations. In the image the red crosses indicate what coordinatethat text string was positioned at. The alignment used for each of thecases is shown below.<DIV class="example"><BR> <A href="exframes/frame_textalignex1.html" target="blank"><IMG border="0"HEIGHT="494" src="img/img/img/img/img/img/img/img/textalignex1.png" WIDTH="480"></A><BR><B>Figure 2:</B> Specifying alignment (anchor-point) for textstrings <A href="exframes/frame_textalignex1.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P></P><H2><A NAME="4_8">4.8 Specifying colors in JpGraph</A></H2><P> Colors can be specified in three different ways</P><OL><LI> By using one of the, roughly, 400 pre-defined color names, e.g<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"khaki"</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV><P> A named color can also be modified by adding a adjustment factor. Anadjustment factor, 0 < f < 1, a smaller value will give a darkerversion and a value of 0 or 1 will return the original color. A value >1 will make the color brighter. A few examples<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"khaki:0.5"</FONT><FONT color="#007700">); </FONT><FONT color="#FF8000">// A darker version of "khaki"<BR></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONTcolor="#DD0000">"yellow:1.2"</FONT><FONT color="#007700">); </FONT><FONT color="#FF8000">// A slightly lighter version of "yellow"</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P></LI><LI> By specifying a RGB triple, e.g.<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> SetColor</FONT><FONT color="#007700">(array(</FONT><FONTcolor="#0000BB">65</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">100</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">176</FONT><FONTcolor="#007700">));</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P></P></LI><LI> By specifying the color as a hex string value<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"#A16BFF"</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV><P></P></LI></OL><P></P><H3><A NAME="4_8_1">4.8.1 Adjusting the transparency</A></H3><P> From version 1.10 JpGraph also supports the use of Alpha Blendingtogether with GD2.x This lets you specify how much of the underlyingcolor should be visible. You specify the amount of transparency for acolor by adding an extra parameter to the color specification separatedby an '@' (at) character.</P><P> For example to specify a red color which is 40% transparent youwrite<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"red@0.4"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> or to specify 90% transparancy you write<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"red@0.9"</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P> Below is an example of how a bar graph with a background image canmake use of transparency<DIV class="example"><BR> <A href="exframes/frame_alphabarex1.html" target="blank"><IMG border="0"HEIGHT="250" src="img/img/img/img/img/img/img/img/alphabarex1.png" WIDTH="450"></A><BR><B>Figure 3:</B> Using alpha blending in a bar graph <A href="exframes/frame_alphabarex1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="4_8_2">4.8.2 Available named colors</A></H3><P> The chart below shows all available named colors. <IMG HEIGHT="1240" src="img/img/img/img/img/img/img/img/color_chart01.png"WIDTH="700"><BR> <IMG HEIGHT="1240" src="img/img/img/img/img/img/img/img/color_chart02.png" WIDTH="700"><BR> <IMG HEIGHT="1240" src="img/img/img/img/img/img/img/img/color_chart03.png" WIDTH="700"><BR> <IMG HEIGHT="1240" src="img/img/img/img/img/img/img/img/color_chart04.png" WIDTH="700"></P><H3><A NAME="4_8_3">4.8.3 Theme colors for pie's</A></H3><P> For more on how to use the different themes to set the colors of Pieplots please refer to "Working with 2D & 3D pie plots"</P><P> <IMG border="1" HEIGHT="355" src="img/img/img/img/img/img/img/img/theme01.png" WIDTH="700"><BR><STRONG> Theme 1:</STRONG> Earth</P><P> <IMG border="1" HEIGHT="290" src="img/img/img/img/img/img/img/img/theme02.png" WIDTH="700"><BR><STRONG> Theme 2:</STRONG> Pastel</P><P> <IMG border="1" HEIGHT="225" src="img/img/img/img/img/img/img/img/theme03.png" WIDTH="700"><BR><STRONG> Theme 3:</STRONG> Water</P><P> <IMG border="1" HEIGHT="225" src="img/img/img/img/img/img/img/img/theme04.png" WIDTH="700"><BR><STRONG> Theme 4:</STRONG> Sand</P><P></P><H1><A NAME="5">5 Understanding the JpGraph caching system</A></H1><P> To reduce load on the web server JpGraph implements an advancedcaching system which avoids the burden of always having to run the fullimage script.</P><P> Depending on the complexity of the image script (for example if itis doing several DB lookups) this could significantly improveperformance.</P><P> The rationale behind this is of course performance, and theobservation that very few graphs are really real-time, i.e. needs to beupdated absolutely every time the graphing script is called.</P><P></P><H2><A NAME="5_1">5.1 Enabling the cache system</A></H2><P> The enabling disabling of the cache system is controlled by twodefines (in jpg-config.php)</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> DEFINE</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"USE_CACHE"</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">true</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">DEFINE</FONT><FONT color="#007700">(</FONT><FONTcolor="#DD0000">"READ_CACHE"</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">true</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> The first of these, USE_CACHE, is the master-switch which must beset to true to enable the caching system. The second switch READ_CACHEvery seldom needs to be changed.</P><P> This second switch basically tells whether or not JpGraph shouldever look in the cache. Setting this to false and the master-switch totrue would then always generate an new updated image file in the cacheand this new image would be send back to the browser. The main use forthis (admittedly) strange setting is if you like to have the sideeffect of the script that a fresh image is always stored in the cachedirectory.</P><P> Once you have enabled the cache you must also make sure that a validcache directory is setup. The cache directory is specified with thedefine</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> DEFINE</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"CACHE_DIR"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"/tmp/jpgraph_cache/"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> You can of course change the default directory to whatever directoryyou fancy. But, you must remember one important thing.<STRONG> Thecache directory must be writable for the user running Apache/PHP</STRONG>.</P><H2><A NAME="5_2">5.2 Using the cache in your script</A></H2><P> To use caching in your script you must supply a suitable file namewhich will be used to store the image in the cache. You can also supplya timeout value indicating how many minutes the cached image should beconsidered valid.</P><P> These parameters are supplied in the initial Graph() method callwhich should be among the first in your script. Instead of manuallyspecifying a file name to be used you could often use the special name"auto". If the filename is specified as "auto" the cashed image willthen be named the same as the image script but with the correctextension depending on what image format have been chosen.</P><P> If you don't specify a file name no caching will be used no matterthe settings of USE_CACHE (without a file name it is impossible!)</P><P> The following call to Graph() shows a typical use of the cache.</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">Graph</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">300</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">200</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"auto"</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">60</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> The above code will use the automatic filename and a make the cachevalid for 60 minutes.</P><P> So, how does this all work now?</P><P> The first time you call your script (no cached image) everythingwill be as usual, the script will run and you will in the end send backthe image to the browser. However if you have the caching enabledJpGraph will automatically have stored a copy of the generated image inthe cache directory.</P><P> The next time you call the script the first thing that happens inthe initial Graph() is that it will go and check in the cache directoryif the named image exists there. If this is the case it will alsochecks that the image isn't too old (as compared to the specifiedtimeout value). If the image is valid then the image will be streamedstraight back from the image file to the browser and the script willend it's execution.</P><P> Hence, if the image is found in the cache<STRONG> no code linesafter the initial Graph() call will be executed</STRONG></P><P> The design decision behind this is that your image script code neverhas to include anything special to make full use of the cache. It willjust automatically work.</P><H2><A NAME="5_3">5.3 Using the cache with Client Side Image Maps</A></H2><P> You can also use the cache system for CSIM as well. The cache systeminterface is slightly different in this case since the cache needs tostore<STRONG> both</STRONG> the cached image and the cached image-map.It also needs to change due to the way CSIM HTML paradigm work. The twomajor differences from the "standard" cache is</P><OL><LI> The cached version will<STRONG> not</STRONG> be stored in theprevious defined cache directory. See more below.</LI><LI> You must call an extra method, CheckCSIMCache(), to check thecache, see more below.</LI></OL><P></P><P> The performance benefits even for simple CSIM images is around 50%if the cache can be used and can of course be several 1000% ifconstruction of the image requires DB calls and other complexoperations which can be avoided.</P><P> Before reading further you should have an understanding on how theCSIM works by reading the section "sing Client side image maps".</P><P> Please remember that when using CSIM you must end your script with acall to <A href="">Graph::StrokeCSIM()</A> method instead of the <A href="">Graph::Stroke()</A> used for non-csim.</P><P> To use the cache with CSIM you have to call the <A href="">Graph::CheckCSIMCache()</A>. As with the caching for non-CSIM you haveto supply a name to be used for the cached version as well as anoptional timeout value. The default timeout value if nothing else isspecified is 60 minutes.</P><P> The name argument requires some more explanations. You must specifya relative name here. For example "myimage" or perhaps"firstpage/image3". Depending on your installation of JpGraph this willnow end up in the directory specified in the CSIMCACHE_DIR define. Thismust also be a directory accessible by the normal web server. Bydefault a directory called "csimcache" will be created in the samedirectory as the image script itself.</P><P> This has the drawback that the directory from where the script isexecuted must be writable by the process running PHP. Best practice forthis is to keep the number of writable directory for PHP down to aminimum and re-use the same directory as is used for the standardcache. This however, require that your system administrator setup thatcache directory so that it also accessible by the HTTP server from thehtdocs root.</P><P> The CheckCSIMCache() method checks the cache for an existing cachedversion and if found it returns it and halts execution of the script.So, this call should be the first call after the creation of theGraph() and before any heavy work is done to create the image so thatyou can minimize the execution of the script in the case a match isfound.</P><P> So, the general structure of a script that uses CSIM and the cacheis<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">Graph</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">400</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">300</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Check cache, 10 min timeout<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">CheckCSIMCache</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"image1"</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">10</FONT><FONTcolor="#007700">);<BR><BR></FONT><FONT color="#FF8000">// !! If cached version exists, execution halts here !!<BR><BR>//<BR>// ... Construct the image with heavy DB calls etc, etc<BR>//<BR><BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">StrokeCSIM</FONT><FONT color="#007700">();</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> Please note that you<STRONG> do not</STRONG> need to pass anyargument to the final call to StrokeCSIM() as you do when not using thecache.<DIV class="note"><B>Note:</B> The CSIM caching works by storingtwo files in the cache directory. One file being the image and theother file being the corresponding image map as a pure HTML file.</DIV></P><H2><A NAME="5_4">5.4 Some final comments</A></H2><P></P><UL><LI>If you want the timeout value to be "forever" then you can specify a0 as the timeout value (or leave the parameter blank). To regeneratethe image you will have to remove the image files from the cache. Thisremoval could for example be handled by a nightly cron-job</LI><LI> If you use images where you have enabled the anti-aliasing youshould strongly consider using caching since anti-aliasing is quitetime consuming compared to standard line drawings.</LI></UL><P></P><H2><A NAME="5_5">5.5 Common feature for all graphs</A></H2><P> This is a summary of the available feature for all Graph basedcharts, i.e. line plots, error plots, scatter plots, etc.</P><H3><A NAME="5_5_1">5.5.1 Clipping</A></H3><P> By default all plots are clipped outside the plot area. This meansthat if you manually specify a scale and then try to plot which hasvalues smaller/larger than the scale those values will not show.</P><P> The clipping algorithm is "perfect" in the sense that for exampleline plots where the plot area cuts the line between two data pointsthe line will be drawn up to the edge of the plot area. The algorithmused is O(1) in number of data points.</P><P> The disabling/enabling of clipping manually is controlled by <A href="../ref/Graph.html#_GRAPH_SETCLIPPING">Graph::SetClipping()</A></P><H3><A NAME="5_5_2">5.5.2 Commonly used properties</A></H3><P></P><OL><LI> Each graph can have three titles accessed through the properties'Graph::title', ''Graph::subtitle' and ''Graph::subsubtitle'</LI><LI> Each graph have a legend accessed through the 'Graph::legend'property</LI><LI> Each graph can have a left, center and right footer accessedthrough 'Graph::footer::left','Graph::footer::center' and'Graph::footer::right'</LI><LI> You access the axis through 'Graph::xaxis', 'Graph::yaxis' and'Graph::y2axis'</LI><LI> You access the grids through 'Graph::xgrid', 'Graph::ygrid' and'Graph::y2grid'</LI></OL><P></P><H3><A NAME="5_5_3">5.5.3 Commonly used methods</A></H3><P></P><OL><LI> You add plot objects (bar plots, pie plots, texts, bands, linesetc) with the 'Graph::Add() method.</LI><LI> Each graph can have a specified margin set by 'Graph::SetMargin()'</LI><LI> Each graph can have a fill color in the plot area'Graph::SetColor()'</LI><LI> The plot areas may have a box around it 'Graph::SetBox()'</LI><LI> Each graph can have a specified margin color'Graph::SetMarginColor()'</LI><LI> Each graph can have a frame or not 'Graph::SetFrame()'</LI><LI> Each graph can have a specified drop shadow 'Graph::SetShadow()'</LI><LI> The grid lines can be either behind or in front of the plots'Graph::SetGridDepth()'</LI><LI> The plot can be rotated an arbitrary angle with 'Graph::SetAngle()'</LI><LI> You can add a background image with 'Graph::SetBackgroundImage'</LI><LI> You can change the overall appearance of the axis with'Graph::SetAxisStyle'</LI></OL><P></P><H1><A NAME="6">6 Using image maps with JpGraph</A></H1><P> Image maps, or client side image (CSIM) as they are known is fullysupported in JpGraph. It gives you the opportunity to create hot-spotsin the graphs which allows you to build a set of "drill-down" graphs.</P><P> In the following section is based on the assumption that the readeris familiar with the basic concepts of client side image map in HTML.</P><P> To shortly recapitulate. Client side image maps consists of twoparts. The first part is the actual image and the second part is amapping that gives the coordinates for areas in the image which shouldbe marked as hot spots (i.e. click-able by the user). The library canautomatically generate these coordinate maps from a given graph.</P><P> Through out the manual areas of the graph that may be used as ahotspot is given in conjuction with the general description of thatarea.</P><H2><A NAME="6_1">6.1 The basic structure of an image map script</A></H2><P> The standard structure for an HTML page using client side image mapswould be something along the lines of</P><P></P><PRE>// Image map specification with name "mapname"<MAP NAME=...>... specification ...</MAP>// Image tag<img src="..." ISMAP USEMAP="mapname"></PRE><P> This poses an interesting question.</P><P> Since we normally call the graphing script directly in the <img> taghow do we get hold of the image map (which is available only in theimage script) in this "HTML wrapper" script?</P><P> In JpGraph there is actually two ways of solving this.</P><OL><LI> Use the preferred "builtin" way using the modified Stroke() methodGraph::StrokeCSIM() instead of the standard Graph::Stroke() method.</LI><LI> Directly use the Graph::GetHTMLImageMap() which gives you finecontrol at the expense of more complex coding.</LI></OL><P> The first (and preferred) way modifies the stroke method so thatinstead of returning an image (like the standard Stroke() method)StrokeCSIM() actually returns an HTML page containing both the imagemap specification and the correct <IMG> tag.</P><P> This of course means that it is necessary to treat an image mapreturning image script differently from a non-CSIM image script, forexample you can't use it directly as the target for the "src" attributeof the <IMG> tag since it sends back an actual HTML page containingboth an image tag together with an image map.</P><H2><A NAME="6_2">6.2 Specifying targets for image map plots</A></H2><P> To turn a standard image script into a CSIM script the first thingneeded to do is to supply the appropriate URL targets for the hotspotsin the image.</P><P> What the hotspots represent depends on the type of plot you aredoing. The following plot types and graph areas support image maps.</P><UL><LI> Line plots. Markers are hotspots.</LI><LI> Scatter plot. Markers are hotspots.</LI><LI> Pie Plots and 3D Pie plots. Each slice is a hotspot</LI><LI> All types of Bar graphs. Each bar is a hotspot</LI><LI> Legends</LI><LI> Text strings, for example titles and title of axis</LI></UL><P> To specify a link for each hotspot you have to use the <A href="../ref/Plot.html#_PLOT_SETCSIMTARGETS">SetCSIMTargets()</A> method for each plot (or specific area) in thegraph which should be a hotspot.</P><P> There are two arguments to this method</P><OL><LI> $aTargets, an array of valid URL targets. One URL per hot spot, forexample if you have a 10 values bar plot you need 10 URLs. If theSetCSIMTarget() is applied to, for example, a text then of course onlyone URL target should be specified.</LI><LI> $aAlts, an array of valid alt-texts. Many browsers (but not all)will show this text string if the mouse hovers over a hotspot.</LI></OL><P></P><H2><A NAME="6_3">6.3 Using StrokeCSIM()</A></H2><P> The simplest way of creating a creating a CSIM image is with theStrokeCSIM() method. As mentioned before this method actually returns a(small) HTML page containing both the image-tag as well as the imagemap specification. Hence it is<B> not</B> possible to use a script thatends with this method in a standard image-tags src property.</P><P> There are two ways to create CSIM (or get hold of) the image maps</P><OL><LI> Use the CSIM image script as the target in a standard anchorreference, for example <CODE><PRE><a href="mycsimscript.html"></PRE></CODE> This has the drawback that the image page will only contain theimage and nothing else.</LI><LI> The other way will allow the image script to be included in anarbitrary HTML page by just including the image script at the wantedplace in the HTML page using any of the standard "include" phpstatement. For example <CODE><PRE><h2> This is an CSIM image </h2><?phpinclude "mycsimscript.php"?></PRE></CODE></LI></OL><P><DIV class="note"><B>Note:</B> If there are several CSIM images onthe same page it is necessary to use "include_once" in the scripts forthe inclusion of "jpgraph.php" and the other jpgraph library filessince the files will be included multiple times on the same page andone or more "Already defined error" will be displayed.</DIV></P><P> The process to replace Stroke() with StrokeCSIM() is strait forward.Replace all existing calls to Stroke() with the equivalent calls toStrokeCSIM().</P><P> The only difference is that it is necessary ti supply a minimum ofone file name in the StrokeCSIM() method. The first argument must bethe name of the actual image script file including the extension. Sofor example if the image script is called "mycsimscript.php" it isnecessary to write<BR> <DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">StrokeCSIM</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'mycsimscript.php'</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P><BR> However, it is possible to apply a small "trick" here. PHP maintaina special variable called "__FILE__" which is always set to the currentfile name. This means you could use the following construction:</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">StrokeCSIM</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">basename</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">__FILE__</FONT><FONT color="#007700">))</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P>This is a better way since the script can now be renamed withouthaving to change any code in the file which otherwise would be needed.<DIVclass="note"><B>Note:</B> Why does the script name need to be used asthe first parameter? The reason is that in the creation of the HTMLpage which is sent back we need to refer to the script in the imagetag. So why is it not possible to use the PHP_SELF reference? Theproblem with PHP_SELF is that in the case where we include theimage-script in an HTML page and use the PHP_SELF we will get the nameof the HTML page and not the actual script in which the PHP_SELF isused. We also can not use the __FILE__ trick in the library since inthe context __FILE__ is set to "jpgraph.php". Hence, this must bespecified by the client as shown above.</DIV></P><P> The other arguments to StrokeCSIM() are optional. Please note thatif several CSIM images are used in the same HTML page it is alsonecessary to specify the image map name as the second parameter sinceall image maps must be unique to properly match each image map againsteach image. Please consult the class reference <A href="../ref/Graph.html#_GRAPH_STROKECSIM">StrokeCSIM()</A> for more details.</P><H2><A NAME="6_4">6.4 Examples of Image maps</A></H2><P> In the Example/ directory there are a number of examples of how tosetup the various types of image maps. The following examples arecurrently available</P><UL><LI>bar_csimex1.php</LI><LI>bar_csimex2.php</LI><LI>bar_csimex3.php</LI><LI>barline_csimex1.php</LI><LI>barlinefreq_csimex1.php</LI><LI>boxstockcsimex1.php</LI><LI>ganttcsimex01.php</LI><LI>ganttcsimex02.php</LI><LI>imgmarkercsimex1.php</LI><LI>pie3d_csimex1.php</LI><LI>piec_csimex1.php</LI><LI>pie_csimex1.php</LI><LI>scatter_csimex1.php</LI><LI>titlecsimex01.php</LI></UL><P> In order to easily access all of these examples it is possible tocall the<I> testsuit.php</I> example with an additional argument "t=2".By following the link <A href="../../../src/Examples/testsuit.php?t=2" target="blank">testsuit.php?t=2</A> a separate window will open with all the possibleCSIM examples.</P><H2><A NAME="6_5">6.5 How does StrokeCSIM() work?</A></H2><P> Knowledge of the exact technical details of the way StrokeCSIM()works is probably not needed by many people but for completeness weoutline those details in this short section.</P><P> The fundamental issue we have to solve is that we must be able tocall the image script in two modes. When the user includes the imagescript the StrokeCSIM() method should return the HTML page but when theimage script is later called directly in the image tag it must notreturn an HTML page but rather the actual image.</P><P> The way this is solved is by using one HTTP argument which is passedon automatically when we use the image script name in the image-tag.</P><P> If you look at the generated HTML you will see that the argument tothe src-property of the image tag is not simply the script name but thescript name with a additional argument.</P><P> In the JpGraph internal code this pre-defined argument is checkedfor and if it exists the image is send back and not the HTML page.</P><P> The name of this argument is defined by a DEFINE() statement inJpGraph. The define is _CSIM_DISPLAY.</P><H2><A NAME="6_6">6.6 Getting hold of the image map</A></H2><P> In the case where you want to store the image on disk and later useit in an img-tag you need to get hold of the image map. For this youwill have to use the function <A href="../ref/Graph.html#_GRAPH_GETHTMLIMAGEMAP">Graph::GetHTMLImageMap()</A></P><P> An example of the use of this is shown below. With these lines theimage will be written to a file. The script then returns a HTML pagewhich contains the Client side image map and an img-tag which willretrieve the previously stored file.<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Stroke</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"/usr/local/httpd/htdocs/img/image001.png"</FONT><FONT color="#007700">);<BR>echo </FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">GetHTMLImageMap</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"myimagemap001"</FONT><FONT color="#007700">);<BR>echo </FONT><FONT color="#DD0000">"<img src=\"img/image001.png\" ISMAP USEMAP=\"#myimagemap001\" border=0>"</FONT><FONT color="#007700">;</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P></P><H2><A NAME="6_7">6.7 Image maps and the cache system</A></H2><P> For version 1.9 the cache system has been extended to include eventhe CSIM maps. For each CSIM graph two files are stored in the cache,the image file itself as well as the wrapper HTML with the actual imagemap. For further information see the chapter on "Understanding theCache system"</P><H1><A NAME="7">7 Working with orthogonal X,Y-plots</A></H1><P> The purpose of this chapter is to introduce the basic concepts ofcreating scripts with JpGraph that will generate various types of basicplots. Throughout the text it is possible to view the exact source forall the graphs by clicking on the "[src]" link in the caption of theimage shown. This will open the image together with the source in aseparate window. This way it is easy to compare the actual image withthe script that generated the image.</P><H2><A NAME="7_1">7.1 Line plots</A></H2><P> The first example draws a line graph consisting of 10 Y-values. Inthis first example we show the full code. In the following examples wewill only show interesting piece of the code.<DIV class="phpscript">(File: example0.php)<BR><CODE><FONT color="#000000"> <FONT color="#0000BB"><?php<BR></FONT><FONT color="#007700">include (</FONT><FONT color="#DD0000">"../jpgraph.php"</FONT><FONT color="#007700">);<BR>include (</FONT><FONT color="#DD0000">"../jpgraph_line.php"</FONT><FONTcolor="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Some data<BR></FONT><FONT color="#0000BB">$ydata </FONT><FONT color="#007700">= array(</FONT><FONT color="#0000BB">11</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">3</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">8</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">12</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">5</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">1</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">9</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">13</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">5</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">7</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Create the graph. These two calls are always required<BR></FONT><FONT color="#0000BB">$graph </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">Graph</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">350</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">250</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"auto"</FONT><FONTcolor="#007700">); <BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetScale</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"textlin"</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Create the linear plot<BR></FONT><FONT color="#0000BB">$lineplot</FONT><FONT color="#007700">=new </FONT><FONT color="#0000BB">LinePlot</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$ydata</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$lineplot</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONTcolor="#DD0000">"blue"</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Add the plot to the graph<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Add</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$lineplot</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Display the graph<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Stroke</FONT><FONT color="#007700">();<BR></FONT><FONT color="#0000BB">?><BR></FONT></FONT></CODE></DIV><DIV class="example"><BR> <A href="exframes/frame_example0.html" target="blank"><IMG border="0"HEIGHT="250" src="img/img/img/img/img/img/img/img/example0.png" WIDTH="350"></A><BR><B>Figure 4:</B> A simple line graph <A href="exframes/frame_example0.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> You might note a few things</P><UL><LI>Both the X and Y axis have been automatically scaled. We will lateron show how you might control the auto scaling how it determines thenumber of ticks which is displayed.</LI><LI>By default the Y-grid is displayed in a "soft" color</LI><LI>By default the image is bordered and the margins are slightly gray.</LI><LI>By default the 0 label on the Y-axis is not displayed</LI></UL><P> This is a perfect fine graph but looks a little bit "sparse". Tomake it more interesting we might want to add a few things like</P><UL><LI>A title for the graph</LI><LI> Title for the axis</LI><LI>Increase the margins to account for the title of the axis</LI></UL><P> From looking at the previous example you can see that you access allproperties of JpGraph through the objects you create. Graph(),LinePlot() and so on. In general all objects you can see in the graphis accessed through a named instance.</P><P> For example the title of the graph is accessed through the'Graph::title' property. So to specify a title string you make a callto the 'Set()' method on the title property as in:</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">title</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'Example 2'</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P> So by adding just a few more lines to the previous code we get agraph as shown below.<DIV class="example"><BR> <A href="exframes/frame_example2.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example2.png" WIDTH="300"></A><BR><B>Figure 5:</B> Same basic graph as in previous figure but with atitles for graph and axis. <A href="exframes/frame_example2.html" target="blank">[src]</A> <P></P></DIV></P><P>To achieve this we just needed to add a few more lines. (We only showthe part of example 1 we changed, to look at the full source just clickthe [src] link in the caption. )<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> </FONT><FONT color="#FF8000">// Setup margin and titles<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">img</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetMargin</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">40</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">20</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">20</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">40</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"Example 2"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">xaxis</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONTcolor="#007700">(</FONT><FONT color="#DD0000">"X-title"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">yaxis</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONTcolor="#007700">(</FONT><FONT color="#DD0000">"Y-title"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> Again there are a couple of things you should note here</P><UL><LI>A default font and size is used for the text</LI><LI>The default position for the title of the graph is to be centered atthe top</LI><LI>The default position for the title of the x-axis is the far rightand for the y-axis centered and rotated in a 900 angle.</LI></UL><P></P><P> A nice change would now be to have all the titles in a bold font andthe line plot a little bit thicker and in blue color. Let's do that byadding the lines<DIV class="phpscript"><CODE><FONT color="#000000"> <FONTcolor="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONTcolor="#007700">(</FONT><FONT color="#0000BB">FF_FONT1</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FS_BOLD</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">yaxis</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONTcolor="#007700">(</FONT><FONT color="#0000BB">FF_FONT1</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FS_BOLD</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">xaxis</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONTcolor="#007700">(</FONT><FONT color="#0000BB">FF_FONT1</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FS_BOLD</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$lineplot</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONTcolor="#DD0000">"blue"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$lineplot</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetWeight</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">2</FONT><FONT color="#007700">); </FONT><FONT color="#FF8000">// Two pixel wide</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> Again please note the consistent interface. To change font you justhave to invoke the SetFont() method on the appropriate object. Thisprinciple is true for most methods you will learn. The methods may beapplied to a variety of objects in JpGraph. So for example it might notcome as a big surprise that to have the Y-axis in red you have to say:<DIVclass="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">yaxis</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"red"</FONT><FONT color="#007700">)</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P> or perhaps we also want to make the Y-axis a bit wider by<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">yaxis</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetWidth</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">2</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> As a final touch let's add a frame and a drop shadow around theimage since this is by default turned off. This is done with<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetShadow</FONT><FONT color="#007700">()</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P> The result of all these modifications are shown below.<DIV class="example"><BR> <A href="exframes/frame_example3.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example3.png" WIDTH="300"></A><BR><B>Figure 6:</B> Making the image a little bit more interesting byadding som colors and changing the fonts <A href="exframes/frame_example3.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="7_1_1">7.1.1 Adding plot marks to line-plots XXX</A></H3><P> It might sometimes be desirable to highlight the data-points withmarks in the intersection between the given x and Y-coordinates. Thisis accomplished by specifying the wanted plot mark type for the "mark"property of the line graph. A full list of all available marks is givenin the class reference <A href="../ref/PlotMark.html#_PLOTMARK_SETTYPE">PlotMarks</A></P><P> For now let's just add a triangle shape marker to our previous graphby adding the line<DIV class="phpscript"><CODE><FONT color="#000000"> <FONTcolor="#0000BB"> $lineplot</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">mark</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetType</FONT><FONTcolor="#007700">(</FONT><FONT color="#0000BB">MARK_UTRIANGLE</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> This will give the graph as shown below<DIV class="example"><BR> <A href="exframes/frame_example3.1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example3.1.png" WIDTH="300"></A><BR><B>Figure 7:</B> Adding markers to the previous example <A href="exframes/frame_example3.1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> If you like you can of course both change the size, fill-color andframe color of the chosen plot mark.</P><P> The colors of the marks will, if you don't specify them explicitly,follow the line color. Please note that if you want different colorsfor the marks and the line the call to SetColor() for the marks must bedone after the call to the line since the marks color will always bereset to the lines color when you set the line.</P><H3><A NAME="7_1_2">7.1.2 Displaying the values for each data point</A></H3><P> As a final easy modification we can enable the display of the datavalue above each data point. The value is represented by the 'value'property in the plot. (You can read more about the possibilities of the<A href="../ref/DisplayValue.html#_C_DISPLAYVALUE"> display value</A>in the class reference.)</P><P> To enable the display of the value you just need to call the Show()method of the value as in<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $lineplot</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">value</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Show</FONT><FONT color="#007700">()</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> Adding that line to the previous line plot would give the resultshown below.<DIV class="example"><BR> <A href="exframes/frame_example3.3.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example3.3.png" WIDTH="300"></A><BR><B>Figure 8:</B> Displaying the value for each data point <A href="exframes/frame_example3.3.html"target="blank">[src]</A> <P></P></DIV></P><P> We can of course change both color, font and format of the displayedvalue. So for example if we wanted the display values to be dark red,use a bold font and have a '$' in front we need to add the lines<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $lineplot</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">value</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONTcolor="#DD0000">"darkred"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$lineplot</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">value</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">FF_FONT1</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FS_BOLD</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$lineplot</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">value</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFormat</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"$ %0.1f"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> This would then result in the following image<DIV class="example"><BR> <A href="exframes/frame_example3.4.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example3.4.png" WIDTH="300"></A><BR><B>Figure 9:</B> Making the display values a little bit moreinteresting <A href="exframes/frame_example3.4.html" target="blank">[src]</A> <P></P></DIV></P><P><DIV class="note"><B>Note:</B> You can achieve more advancedformatting by using not just the printf() style format string by aformat callback function. This could allow you to change the displayedvalue with more advanced formatting such as displaying money valueswith "," to separate thousands.</DIV></P><H3><A NAME="7_1_3">7.1.3 Adding several plots to the same graph</A></H3><P> What if we want to add a second plot to the graph we just produced?Well, this is quite straightforward and just requires two simple step:</P><OL><LI>Create the second plot</LI><LI>Add it to the graph</LI></OL><P> To create the second plot we need some data (we could of course usethe same data as for the first plot but then we wouldn't be able to seethe new plot!)</P><P> The following lines show how to create the new plot and add it tothe graph (we only show the new lines - not the full script)<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $ydata2 </FONT><FONT color="#007700">= array(</FONT><FONT color="#0000BB">1</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">19</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">15</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">7</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">22</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">14</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">5</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">9</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">21</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">13</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$lineplot2</FONT><FONT color="#007700">=new </FONT><FONT color="#0000BB">LinePlot</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$ydata2</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$lineplot2</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONTcolor="#DD0000">"orange"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$lineplot2</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetWeight</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">2</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Add</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$lineplot2</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> Making these changes to the previous graph script would generate anew graph as illustrated below.<DIV class="example"><BR> <A href="exframes/frame_example4.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example4.png" WIDTH="300"></A><BR><B>Figure 10:</B> Adding a second plot to the previous graph <A href="exframes/frame_example4.html"target="blank">[src]</A> <P></P></DIV></P><P> There is a few things worth noting here</P><UL><LI>The Y-scale has changed to accommodate the larger range of Y-valuesfor the second graph.</LI><LI>If you add several plots to the same graph they should contain thesame number of data points. This is not a requirement (the graph willbe automatically scaled to accommodate the plot with the largest numberof points) but it will not look very good since one of the plot end inthe middle of the graph.</LI></UL><P></P><H3><A NAME="7_1_4">7.1.4 Adding a second Y-scale</A></H3><P> As you saw in the preceding example you could add multiple plots tothe same graph and Y-axis. However what if the two plots you want todisplay in the graph has very different ranges. One might for examplehave Y-values like above but the other might have Y-values in the100:s. Even though it is perfectly possible to add them as above thegraph with the smallest values will have a very low dynamic range sincethe scale must accomplish the bigger dynamic range of the second plot.</P><P> The solution to this is to use a second Y-axis with a differentscale and add the second plot to this Y-axis instead. Let's take a lookat how that is accomplished.</P><P> First we need to create a new data array with large values andsecondly we need to specify a scale for the Y2 axis. This is done bythe lines<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $y2data </FONT><FONT color="#007700">= array(</FONT><FONT color="#0000BB">354</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">200</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">265</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">99</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">111</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">91</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">198</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">225</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">293</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">251</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetY2Scale</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"lin"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> and finally we create a new line plot and add that to the secondY-axis. Note that we here use a new method, AddY2(), since we want thisplot to be added to the second Y-axis. Note that JpGraph will onlysupport two different Y-axis. This is not considered a limitation sinceusing more than two scales in the same graph would make it verydifficult to interpret the meaning of the graph.</P><P> To make the graph a little bit more esthetic pleasing we usedifferent colors for the different plots and let the two differentY-axis get the same colors as the plots.</P><P> The resulting graph is shown below. source)<DIV class="example"><BR> <A href="exframes/frame_example5.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example5.png" WIDTH="300"></A><BR><B>Figure 11:</B> Adding a second Y-scale plot to the same graph <A href="exframes/frame_example5.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="7_1_5">7.1.5 Adding a legend to the graph</A></H3><P> With more than one plot on the same graph it is necessary to somehowindicate which plot is which. This is normally done by adding a legendto the graph.</P><P> You will see that each plot type has a 'SetLegend()' method which isused to name that plot in the legend. SO to name the two plots in theexample we have been working with so far we need to add the lines<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $lineplot</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">SetLegend</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"Plot 1"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$lineplot2</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetLegend</FONT><FONT color="#007700">(</FONT><FONTcolor="#DD0000">"Plot 2"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> to the previous code. The resulting graph is shown below<DIV class="example"><BR> <A href="exframes/frame_example5.1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example5.1.png" WIDTH="300"></A><BR><B>Figure 12:</B> Adding a legend to the graph <A href="exframes/frame_example5.1.html"target="blank">[src]</A> <P></P></DIV></P><P> As you can see the legend gets automatically sized depending on howmany plots there are that have legend texts to display. By default itis placed with it's top right corner close to the upper right edge ofthe image. Depending on the image you might want to adjust this or youmight want to add a larger margin which is big enough to accompany thelegend. Let's do both.</P><P> First we increase the right margin and then we place the legend sothat it is roughly centered. We will also enlarge the overall image sothe plot area doesn't get too squeezed.</P><P> To modify the legend you access the 'legend' property of the graph.For a full reference on all the possibilities (changing colors, layout,etc) see <A href="../ref/Legend.html#_C_LEGEND/">class legend</A> inthe class reference</P><P> For this we use the legends 'SetPos()' method as in<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">legend</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Pos</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">0.05</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0.5</FONT><FONTcolor="#007700">,</FONT><FONT color="#DD0000">"right"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"center"</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> Doing this small modification will give the result shown below<DIV class="example"><BR> <A href="exframes/frame_example6.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example6.png" WIDTH="400"></A><BR><B>Figure 13:</B> Adjusting the layout to give more rooms for thelegend <A href="exframes/frame_example6.html" target="blank">[src]</A> <P></P></DIV></P><P> The above method 'SetPos()' deserves some explanation since it mightnot be obvious. You specify the position as a fraction of the overallwidth and height of the entire image. This makes it possible for you toresize the image within disturbing the relative position of the legend.We will later see that the same method is just to place arbitrary textin the image.</P><P> To give added flexibility one must also specify to what edge of thelegend the position given should be relative to. In the example abovewe have specified "right" edge on the legend for the for the horizontalpositioning and "center" for the vertical position.</P><P> This means that the right edge of the legend should be position 5 %of the image width from the right. If you had specified "left" the thelegends left edge would be positioned 5 % of the image width from theimage left side.</P><P> By default the legends in the legend box gets stacked on top of eachother. The other possibility is to have them sideways. To adjust thisyou use the <A href="../ref/Legend.html#_LEGEND_SETLAYOUT">SetLayout()</A>method. Using a horizontal layout with the previous example give thefollowing result.<DIV class="example"><BR> <A href="exframes/frame_example6.1.html" target="blank"><IMG border="0"HEIGHT="240" src="img/img/img/img/img/img/img/img/example6.1.png" WIDTH="300"></A><BR><B>Figure 14:</B> Using a horizontal layout for the legends <A href="exframes/frame_example6.1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H4>7.1.5.1 Adjusting the layout of the legend</H4><P> For more advanced fomatting of the legend it is possible to adjust</P><UL><LI> The number of columns in the legend</LI><LI> Specify vertical / horizontal margins for legend columns</LI></UL><P> In order to adjust the number of columns used in the legend themethod<I> Legend::SetColumns</I> is used. So for example to have thelegend lined up using three columns the follwing lines have to be addedto teh script<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">legend</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColumns</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">3</FONT><FONTcolor="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><H3><A NAME="7_1_6">7.1.6 Handling null-values in line plots</A></H3><P> JpGraph offers two ways of handling null values (or discontinuities)in the data. You can either have a "whole" in the data or the line maybe extended between the previous and next data point in the graph.</P><P> If the data value is null ("") or the special value "x" then thedata point will not be plotted and will leave a gap in the line.</P><P> If the data value is "-" then the line will be drawn between theprevious and next point in the data ignoring the "-" point.</P><P> The following example shows both these possibilities.</P><P><DIV class="example"><BR> <A href="exframes/frame_nullvalueex01.html" target="blank"><IMG border="0"HEIGHT="250" src="img/img/img/img/img/img/img/img/nullvalueex01.png" WIDTH="400"></A><BR><B>Figure 15:</B> Handling null values in line graphs <A href="exframes/frame_nullvalueex01.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="7_1_7">7.1.7 Using the step-style to render line plots</A></H3><P> Step style refers to an alternate way of rendering line plots by notdrawing a direct line between two adjacent points but rather draw twosegments. The first segment being a horizontal line to the next X-valueand then a vertical line from that point to the correct Y-value. Thisis perhaps easier demonstrated by an example as seen below.</P><P> You specify that you want the plot to be rendered with this style bycalling the method <A href="../ref/LinePlot.html#_LINEPLOT_SETSTEPSTYLE">SetStepStyle()</A> on the lineplot.<DIV class="example"><BR> <A href="exframes/frame_example6.2.html" target="blank"><IMG border="0"HEIGHT="240" src="img/img/img/img/img/img/img/img/example6.2.png" WIDTH="300"></A><BR><B>Figure 16:</B> Rendering a line plot with the step style <A href="exframes/frame_example6.2.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="7_1_8">7.1.8 Using logarithmic scale</A></H3><P> Using a logarithmic scale requires you to include the logarithmicadd on module in "jpgraph_log.php". So you must have the line<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> </FONT><FONT color="#007700">include(</FONT><FONT color="#DD0000">"jpgraph_log.php"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P>on the top of your code. To Illustrate how to use a logarithmic scalelet's make the right Y scale in the previous example a logarithmicscale. This is done by the line<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetY2Scale</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"log"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P>This will then give the following result<DIV class="example"><BR> <A href="exframes/frame_example7.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example7.png" WIDTH="350"></A><BR><B>Figure 17:</B> Using a logarithmic scale for both the Y2 axis <A href="exframes/frame_example7.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> You can of course also use a logarithmic X-scale as well. Thefollowing example shows this.<DIV class="example"><BR> <A href="exframes/frame_loglogex1.html" target="blank"><IMG border="0"HEIGHT="300" src="img/img/img/img/img/img/img/img/loglogex1.png" WIDTH="500"></A><BR><B>Figure 18:</B> Example of using log scale on both X and Y axistogether with a linear Y2 scale <A href="exframes/frame_loglogex1.html" target="blank">[src]</A> <P></P></DIV></P><P> Even though we have so far only shown line graphs logarithmic scalecan also be used for bar, error, scatter plots as well. Even radarplots supports the use of logarithmic plots. The following exampleshows how to use a logarithmic scale for a bar graph.</P><P><DIV class="example"><BR> <A href="exframes/frame_logbarex1.html" target="blank"><IMG border="0"HEIGHT="220" src="img/img/img/img/img/img/img/img/logbarex1.png" WIDTH="400"></A><BR><B>Figure 19:</B> Example of using logarithmic scale togther withbar plots <A href="exframes/frame_logbarex1.html" target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="7_1_9">7.1.9 More on scales</A></H3><P> As you saw in the previous example it is possible to use differenttypes of scales. In JpGraph you can use the following scales</P><UL><LI>Linear scale, the standard "scale"</LI><LI>Logarithmic scale</LI><LI>Integer scale, very similar to linear scale but restricts the scalevalues (and labels) to integer values.</LI><LI>Text scale, Similar to integer scale and used when only thenumbering of items is relevant. A text scale is almost exclusively usedfor the X-axis. A typical example for this is the X-axis for a barplot. The labels for the text scale is usually replaced by usersupplied texts. Text scales can only be used for the X-axis (it doesn'tmake sense for the Y-scale).</LI></UL><P> Any combination of these may be used. Linear and logarithmic scalesare pretty straightforward. The text scale might deserve someexplanation. The easiest way to think of the text scale is as a linearscale consisting of only natural numbers, i.e. 0,1,2,3,4,... . Thisscale is used when you just have a number of Y-values you want to plotin a consecutive order and don't care about the X-values. For the aboveexample it will also work fine to use a linear X-scale (try it!).However, the scale is now treated as consisting or real numbers so theauto scaling, depending on the size of the image an the number of datapoints, might decide to display other labels then the natural numbers.,i.e. a label might be 2.5 say. This is not going to happen if you use atext scale.</P><P> The normal practice for text scale is to specify text strings aslabels instead as the default natural numbers. You can specify textstrings for the labels by calling the <A href="../ref/Axis.html#_AXIS_SETTICKLABELS">SetTickLabels()</A> method on the Axis.</P><P> To specify the scale you use the <A href="../ref/Graph.html#_GRAPH_SETSCALE">SetScale()</A> method. A few examples might help clarify this.</P><UL><LI> "textlin", text-scale for X-axis, Linear scale for Y-axis</LI><LI> "linlin", linear-scale for X-axis, Linear scale for Y-axis</LI><LI> "linlog", linear-scale for X-axis, Logarithmic scale for Y-axis</LI><LI> "loglog", Logarithmic scale for X-axis, Logarithmic scale forY-axis</LI><LI> "textint", text-scale for X-axis, Integer scale for Y-axis</LI><LI> "textlog", Text scale for X-axis, Logarithmic scale for Y-axis</LI></UL><P> As you can see all your graphs will require at least one call toSetScale() in the beginning of your script. Normally it will come rightafter the creation of the Graph().</P><P> To specify the scale for the Y2 axis you use the <A href="../ref/Graph.html#_GRAPH_SETY2SCALE">SetY2Scale()</A> Since you only specify one axis you only specify"half" of the string in the previous examples. So to set a logarithmicY2 scale you will call<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetY2Scale</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"log"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><H3><A NAME="7_1_10">7.1.10 Adjusting the grid lines in the plot</A></H3><P> By default only the Y-axis have grid lines and then only on majorticks, i.e. ticks which have a label. It is of course possible tochange this. Both the X , Y and Y2 can have grid lines. It is alsopossible to let the gridlines also be drawn on the minor tick marks,i.e. ticks without a label. Lets see how we can apply this to the graphabove.</P><P> The grid is modified by accessing the xgrid (or ygrid) component ofthe graph. So to display minor grid lines for the Y graph we make thecall<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">ygrid</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">Show</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">true</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">true</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The first parameter determines if the grid should be displayed atall and the second parameter determines whether or not the minor gridlines should be displayed.</P><P> If you also wanted the grid lines to be displayed for the Y2 axisyou would call<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">y2grid</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Show</FONT><FONTcolor="#007700">(</FONT><FONT color="#0000BB">true</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">true</FONT><FONT color="#007700">)</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P><STRONG> Note.</STRONG> In general it is not a good idea to displayboth the Y and Y2 grid lines since the resulting image becomesdifficult to read for a viewer.</P><P> We can also enable the X-grid lines with the call<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">xgrid</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Show</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">true</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> In the above line we will of course only just enable the major gridlines.</P><P> To bring all this together we will display a graph with grid linesfor both Y and X axis enabled.<DIV class="example"><BR> <A href="exframes/frame_example8.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example8.png" WIDTH="350"></A><BR><B>Figure 20:</B> Enabling major and minor gridlines for Y-axis andmajor grid lines for the X-axis <A href="exframes/frame_example8.html" target="blank">[src]</A> <P></P></DIV></P><P><DIV class="note"><B>Note:</B> If you think the first value of theY-axis is to close to the first label of the X-axis you have the optionof either increasing the margin (with a call to <A href="../ref/Axis.html#_AXIS_SETLABELMARGIN">SetLabelMargin()</A> ) or to hide the first label (with a call to <A href="../ref/Axis.html#_AXIS_HIDEFIRSTTICKLABEL">HideFirstTickLabel()</A> )</DIV></P><H3><A NAME="7_1_11">7.1.11 Using filled grid lines</A></H3><P> Another option for the grid lines is the possibility to have thearea between the grid lines filled with alternating two colors. Theexample below illustrates this.<DIV class="example"><BR> <A href="exframes/frame_filledgridex1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/filledgridex1.png" WIDTH="300"></A><BR><B>Figure 21:</B> Using two alternating colors between the gridlines<A href="exframes/frame_filledgridex1.html" target="blank">[src]</A> <P></P></DIV></P><P> In the example above we have also made use of alpha-blending(requires GD 2.x or higher). By default the filled grid lines aredisabled. To enable this style you have to call the <A href="../ref/Grid.html#_GRID_SETFILL">Grid::SetFill()</A> method.</P><H3><A NAME="7_1_12">7.1.12 Specifying text labels for the X-axis</A></H3><P> You might want to have specific labels you want to use for theX-axis when this has been specified as a "text" scale. In the previousexample each Y-point might represent a specific measurement for each ofthe first 10 month. We might then want to display the name of themonths as X-scale.</P><P> To specify the labels on the scale you make use of the <A href="../ref/Axis.html#_AXIS_SETTICKLABELS">SetTickLabels()</A> method.</P><P> To get a localized version of the name of the month you can use anice feature in JpGraph, the global '$gDateLocal' object which is aninstance of the <A href="../ref/DateLocale.html#_C_DATELOCALE">DateLocale</A></P><P> This class has a number of methods to get localized versions ofrelevant names for dates, (months and weekdays).</P><P> So to specify the X-axis with the short form of the month names weuse the construction<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $a </FONT><FONT color="#007700">= </FONT><FONT color="#0000BB">$gDateLocale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">GetShortMonth</FONT><FONT color="#007700">();<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">xaxis</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetTickLabels</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$a</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> This will, now result in the image displayed below<DIV class="example"><BR> <A href="exframes/frame_example9.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example9.png" WIDTH="350"></A><BR><B>Figure 22:</B> Specifying text labels for the X-axis <A href="exframes/frame_example9.html"target="blank">[src]</A> <P></P></DIV></P><P><DIV class="note"><B>Note:</B> It is also perfectly legal to overridethe default labels for the Y (and Y2) axis in the same way, howeverthere is seldom need for that. Please note that the supplied labelswill be applied to each major tick label. If there are insufficientnumber of supplied labels the non-existent positions will have emptylabels.</DIV></P><H3><A NAME="7_1_13">7.1.13 Adjusting the ticks on a text scale</A></H3><P> As can be seen in the previous example the X-axis is slightlycluttered with the labels very close to each other. We might rectifythis by either enlarging the image or just displaying fewer tick labelon the x-axis.</P><P> Specifying that we only want, for example, to print every secondlabel on the axis is done by a call to the method <A href="../ref/Axis.html#_AXIS_SETTEXTLABELINTERVAL">SetTextLabelInterval()</A> Which would result in the graph<DIV class="example"><BR> <A href="exframes/frame_example9.1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example9.1.png" WIDTH="350"></A><BR><B>Figure 23:</B> Just printing every second label on the X-axis <A href="exframes/frame_example9.1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> If the text labels are long (for example full dates) then anotherway might be to adjust the angle of the text. We could for examplechoose to rotate the labels on the X-axis by 90 degrees. With the helpof the <A href="../ref/Axis.html#_AXIS_SETLABELANGLE"> SetLabelAngle()</A></P><P> Which would then result in the image below<DIV class="example"><BR> <A href="exframes/frame_example9.2.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example9.2.png" WIDTH="350"></A><BR><B>Figure 24:</B> Rotating the X-labels 90 degrees <A href="exframes/frame_example9.2.html"target="blank">[src]</A> <P></P></DIV></P><P><DIV class="note"><B>Note:</B> The internal fonts which we have beenusing so only supports 0 or 90 degrees rotation. To use arbitraryangles you must specify TTF fonts. More on fonts later.</DIV></P><H3><A NAME="7_1_14">7.1.14 Using filled line graphs</A></H3><P> Using a filled line plot is not much different from using a normalline plot, in fact the only difference is that you must call the method<A href="../ref/LinePlot.html#_LINEPLOT_SETFILLCOLOR"> SetFillColor()</A>on a normal line plot. This will then fill the area under the linegraph with the chosen color.</P><P> In the example below we have also, as an example, specified plotmarks (see previous sections).<DIV class="example"><BR> <A href="exframes/frame_filledlineex01.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/filledlineex01.png" WIDTH="300"></A><BR><B>Figure 25:</B> Filled line graph with plot marks <A href="exframes/frame_filledlineex01.html"target="blank">[src]</A> <P></P></DIV></P><P><STRONG> Note 1.</STRONG> If you add multiple filled line plots toone graph make sure you add the one with the highest Y-values firstsince it will otherwise overwrite the other plots and they will not bevisible. Plots are stroked in the order they are added to the graph, sothe graph you want front-most must be added last.</P><P><STRONG> Note 2.</STRONG> When using legends with filled line plotthe legend will show the fill color and not the bounding line color.</P><P><STRONG> Note 3.</STRONG> Filled line plots is only supposed to beused with positive values. Filling line plots which have negative datavalues will probably not have the appearance you expect.</P><P> As you can see from the graph above the grid lines are below thefilled line graph. If you want the grid lines in front of the graph youcan adjust the depth with call to <A href="../ref/Graph.html#_GRAPH_SETGRIDDEPTH">Graph::SetGridDepth()</A> As the following example shows<DIV class="example"><BR> <A href="exframes/frame_filledlineex01.1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/filledlineex01.1.png" WIDTH="300"></A><BR><B>Figure 26:</B> Adjusting the depth of the gridlines <A href="exframes/frame_filledlineex01.1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="7_1_15">7.1.15 Using accumulated line graphs</A></H3><P> Accumulated line graphs are line graphs that are "stacked" on top ofeach other. That is, the values in the supplied data for the Y-axis isnot the absolute value but rather the relative value from graph below.For example if you have two line graphs with three points each, say[3,7,5] and [6,9,7]. The first graph will be plotted on the absoluteY-values [3,7,5] the second plot will be plotted at [3+6, 7+9, 5+7],hence the values of the previous graphs will be used as offsets.</P><P> You may add any number of ordinary line graphs together. If you wantto use three line plots in an accumulated line plot graph you write thefollowing code</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> </FONT><FONT color="#FF8000">// First create the individual plots<BR></FONT><FONT color="#0000BB">$p1 </FONT><FONT color="#007700">= new </FONT><FONTcolor="#0000BB">LinePlot</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$datay_1</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$p2 </FONT><FONT color="#007700">= new </FONT><FONTcolor="#0000BB">LinePlot</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$datay_2</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$p3 </FONT><FONT color="#007700">= new </FONT><FONTcolor="#0000BB">LinePlot</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$datay_3</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Then add them together to form a accumulated plot<BR></FONT><FONT color="#0000BB">$ap </FONT><FONT color="#007700">= new </FONT><FONTcolor="#0000BB">AccLinePlot</FONT><FONT color="#007700">(array(</FONT><FONTcolor="#0000BB">$p1</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$p2</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$p3</FONT><FONTcolor="#007700">));<BR><BR></FONT><FONT color="#FF8000">// Add the accumulated line plot to the graph<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Add</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$ap</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> You might of course also fill each line plot by adding the lines<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $p1</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFillColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"red"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$p2</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFillColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"blue"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$p3</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFillColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"green"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> Using some appropriate data this might then give a graph perhapslike the one showed in the figure below<DIV class="example"><BR> <A href="exframes/frame_example17.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example17.png" WIDTH="300"></A><BR><B>Figure 27:</B> Accumulated filled line graph <A href="exframes/frame_example17.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="7_1_16">7.1.16 Constructing smooth line plots with CubicSplines</A></H3><P> If you only have access to a few data points but still want a smoothcurve between those data points JpGraph can help you achieving that byletting you construct cubic splines. If you never have heard of cubicsplines before, don't worry. You only have to supply the data pointsyou know tell JpGraph how many interpolated points in total you want inthe graph. JpGraph will now take care of constructing a smooth curvebetween all you data points. The new, smooth, curve will be made up ofexactly as many interpolated points as you have specified.</P><P> To construct a spline you need both the X and Y coordinates for theknown data points.</P><P> You start by constructing a new <A href="">Spline</A> instance. Toget access to the Spline class you must first remember to include thefile "jpgraph_regstat.php". You instantiate this class by calling itwith your two known data arrays (X and Y) as follows.<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $spline </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">Spline</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$xdata</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$ydata</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P>This call initializes the spline with the data points you have. Thesedata points are also known as<I> Control points</I> for the spline.This helper class doesn't draw any line itself. Instead it is merelyused to get a new (larger) data array which have all the interpolatedvalues. You then use these new value in your plot. This way give yougreat flexibility in how you want to use this interpolated data.</P><P> Continuing the above line we now use the <A href="">Spline::Get()</A>method to get an interpolated array containing a specified number ofpoints. So for example the line<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> </FONT><FONT color="#007700">list(</FONT><FONT color="#0000BB">$sdatax</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$sdatay</FONT><FONT color="#007700">) = </FONT><FONT color="#0000BB">$spline</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Get</FONT><FONTcolor="#007700">(</FONT><FONT color="#0000BB">50</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P>Will construct the two new data arrays '$sdatax' and '$sdatay' whichcontains 50 data points. These two arrays are constructed from thecontrol point we specified when we created the '$spline' object.</P><P> You would then use these two new data array in exactly the same wayas you would form ordinary data vectors.</P><P> The following example illustrates this<DIV class="example"><BR> <A href="exframes/frame_splineex1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/splineex1.png" WIDTH="300"></A><BR><B>Figure 28:</B> Using spline to get a smooth curve between thecontrol points. <A href="exframes/frame_splineex1.html" target="blank">[src]</A> <P></P></DIV></P><P> In order to make the example more interesting we actually use twoplots. First a line plot to get the smooth curve and then a standardscatter plot which is used to illustrate where the control points are.</P><H3><A NAME="7_1_17">7.1.17 Adding plot marks to a line plot</A></H3><P> To emphasize the specific data points it is possible to add plotmarks at each data point. Plot marks can be either</P><UL><LI> Simple shapes, (e.g. square, circle, cross, etc)</LI><LI> Arbitrary images loaded from a file</LI><LI> One of the built-in images</LI></UL><P> You access the plot mark through the "mark" instance variable in theplot, as in<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $lineplot</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">mark</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONTcolor="#007700">(</FONT><FONT color="#DD0000">"red"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> To choose between the different plot marks you call the <A href="../ref/PlotMark.html#_PLOTMARK_SETTYPE">PlotMark::SetType()</A> method with the correct define to choose theplot type you want to use.</P><P> The simple shape type of plot marks are</P><UL><LI> MARK_SQUARE</LI><LI> MARK_UTRIANGLE</LI><LI> MARK_DTRIANGLE</LI><LI> MARK_DIAMOND</LI><LI> MARK_CIRCLE</LI><LI> MARK_FILLEDCIRCLE</LI><LI> MARK_CROSS</LI><LI> MARK_STAR</LI><LI> MARK_X</LI><LI> MARK_LEFTTRIANGLE</LI><LI> MARK_RIGHTTRIANGLE</LI><LI> MARK_FLASH</LI></UL><P> To specify an arbitrary image you use the special define</P><UL><LI> MARK_IMG</LI></UL><P> In this case you must also specify a image file name and an optionalscaling constant. For example as in<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $lineplot</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">mark</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetTYPE</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">MARK_IMG</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"myimage.jpg"</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">1.5</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> If you want to use one of the built-in images the following imagesare available. Please note that not all images are available in allpossible colors. The available colors for each image is listed below.</P><P> The following shape (the first class) plot marks are available</P><OL><LI>MARK_SQUARE, A filled square</LI><LI>MARK_UTRIANGLE, A triangle pointed upwards</LI><LI>MARK_DTRIANGLE, A triangle pointed downwards</LI><LI>MARK_DIAMOND, A diamond</LI><LI>MARK_CIRCLE, A circle</LI><LI>MARK_FILLEDCIRCLE, A filled circle</LI><LI>MARK_CROSS, A cross</LI><LI>MARK_STAR, A star</LI><LI>MARK_X, An 'X'</LI><LI>MARK_FLASH, A "flash" shape</LI><LI>MARK_IMAGE, Use the image specified with the filename and scale asthe second and third argument as the mark.</LI></OL><P></P><P> For the second class (built-in images) the following table list thedifferent images as well as what color they are available in. For thebuilt-in images you specify the color with the second argument.</P><P> Note that some of the images are available in different sizes. Thereason is that even though you can scale them by the third argumentthere is a visual degradation to scale an image larger than it'soriginal size since some pixels needs to be interpolated. Reducing thesize with a scale < 1.0 gives much better visual apperance.</P><P> The scaling works with both GD 1 and GD 2 but with GD 2 the qualityof the scaling is much better.</P><P> Built-in images and available colors:</P><TABLE border="1"><TR><TH>Type</TH><TH>Description</TH><TH>Colors</TH></TR><TR><TD>MARK_IMG_PUSHPIN, MARK_IMG_SPUSHPIN</TD><TD> Push-pin image</TD><TD>'red','blue','green','pink','orange'</TD></TR><TR><TD>MARK_IMG_LPUSHPIN</TD><TD> A larger Push-pin image</TD><TD>'red','blue','green','pink','orange'</TD></TR><TR><TD>MARK_IMG_BALL, MARK_IMAGE_SBALL</TD><TD>A round 3D rendered ball</TD><TD>'bluegreen','cyan','darkgray','greengray','gray','graypurple','green','greenblue','lightblue','lightred','navy','orange','purple','red','yellow'</TD></TR><TR><TD>MARK_IMAGE_MBALL</TD><TD>A medium sized round 3D rendered ball</TD><TD>'blue','bluegreen','brown','cyan','darkgray','greengray','gray','green','greenblue','lightblue','lightred', 'purple','red','white','yellow'</TD></TR><TR><TD>MARK_IMAGE_LBALL</TD><TD>A large sized round 3D rendered ball</TD><TD>'blue','lightblue','brown','darkgreen','green','purple','red','gray','yellow','silver','gray'</TD></TR><TR><TD>MARK_IMAGE_SQUARE</TD><TD>A 3D rendered square</TD><TD>'bluegreen','blue','green', 'lightblue','orange','purple','red','yellow'</TD></TR><TR><TD>MARK_IMG_STAR</TD><TD>A 3D rendered star image</TD><TD>'bluegreen','lightblue','purple','blue','green','pink','red','yellow'</TD></TR><TR><TD>MARK_IMG_DIAMOND</TD><TD>A 3D rendered diamond</TD><TD>'lightblue','darkblue','gray', 'blue','pink','purple','red','yellow'</TD></TR><TR><TD>MARK_IMG_BEVEL</TD><TD>A 3D rendered bevel style round ring</TD><TD>'green','purple','orange','red','yellow'</TD></TR></TABLE>Below we give two examples of images using these features.<DIV class="example"><BR> <A href="exframes/frame_imgmarkerex1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/imgmarkerex1.png" WIDTH="300"></A><BR><B>Figure 29:</B> Using an arbitrary image as plot mark <A href="exframes/frame_imgmarkerex1.html"target="blank">[src]</A> <P></P></DIV><P></P><P><DIV class="example"><BR> <A href="exframes/frame_builtinplotmarksex1.html" target="blank"><IMGborder="0" HEIGHT="200" src="img/img/img/img/img/img/img/img/builtinplotmarksex1.png" WIDTH="350"></A><BR><B>Figure 30:</B> Using the built-in images <A href="exframes/frame_builtinplotmarksex1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H2><A NAME="7_2">7.2 Bar graphs</A></H2><P> Jpgraph also supports 2D vertical bar plots. Before you can use anybar plots you must make sure that you included the file"jpgraph_bar.php" in your script.</P><P> Using bar plots is quite straightforward and works in much the sameway as line plots which you are already familiar with from the previousexamples. Assuming you have a data array consisting of the values[12,8,19,3,10,5] and you want to display them as a bar plot. This isthe simplest way to do this:<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $datay</FONT><FONT color="#007700">=array(</FONT><FONTcolor="#0000BB">12</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">8</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">19</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">3</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">10</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">5</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$bplot </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">BarPlot</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$datay</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Add</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$bplot</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> If you compare this to the previous line examples you can see thatthe only change necessary was that instead of creating a new line plot(via the new LinePlot(...) call) we used the statement new <A href="../ref/BarPlot.html#_C_BARPLOT">BarPplot().</A></P><P> The other change we should do is to make sure the X-axis have antext-scale (it is perfectly fine to use a linear X-scale but in mostcases this is not the effect you want when you use a bar graph, seemore below). With this two simple change we will now get a bar graph asdisplayed in the following image<DIV class="example"><BR> <A href="exframes/frame_example18.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example18.png" WIDTH="300"></A><BR><B>Figure 31:</B> A very simple bar graph <A href="exframes/frame_example18.html"target="blank">[src]</A> <P></P></DIV></P><P> You can of course modify the appearance of the bar graph. So forexample to change the fill color you would use the <A href="../ref/BarPlot.html#_BARPLOT_SETFILLCOLOR">BarPlot::SetFillColor()</A> method. Making this small change to theprevious example would give the expected effect as can be seen in thenext example.<DIV class="example"><BR> <A href="exframes/frame_example19.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example19.png" WIDTH="300"></A><BR><B>Figure 32:</B> A very simple bar graph with changed fill color <A href="exframes/frame_example19.html"target="blank">[src]</A> <P></P></DIV></P><P><DIV class="note"><B>Note:</B> You should note from the previous twographs that slight change in appearance for the X-scale. The bar graphsgets automatically centered between the tick marks when using as textx-scale. If you were to use a linear scale they would instead start atthe left edge of the X-axis and the X-axis would be labeled with alinear scale. As is illustrated in the (small) example below.</DIV><DIV class="example"><BR> <A href="exframes/frame_example19.1.html" target="blank"><IMG border="0"HEIGHT="100" src="img/img/img/img/img/img/img/img/example19.1.png" WIDTH="260"></A><BR><B>Figure 33:</B> A small example with a bar graph using a linearX-scale <A href="exframes/frame_example19.1.html" target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="7_2_1">7.2.1 Adjusting the width of the bars</A></H3><P> JpGraph allows you to easy customize the appearance of the bargraph, for example to change the width of each bar. The width of eachbar can be specified either as a fraction of the width between eachmajor tick or as an absolute width (in pixels).</P><P> To set the width in fraction you use the method <A href="../ref/BarPlot.html#_BARPLOT_SETWIDTH">SetWidth()</A> and to set the width in pixels you use the <A href="../ref/BarPlot.html#_BARPLOT_SETABSWIDTH">SetAbsWidth()</A></P><P> As an example let's take the previous example and set the width to100% of the distance between the ticks. The example will now become</P><P><DIV class="example"><BR> <A href="exframes/frame_example20.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example20.png" WIDTH="300"></A><BR><B>Figure 34:</B> Setting the width of the bars to 100% of the tickwidth <A href="exframes/frame_example20.html" target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="7_2_2">7.2.2 Displaying the value of each bar</A></H3><P> You can easily choose to display the value (and it's format) on topof each bar by accessing the bar's 'value' property. So for example byjust adding the line<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $barplot</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">value</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Show</FONT><FONT color="#007700">();</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> Will enable the values in it's simplest form and will give theresult<DIV class="example"><BR> <A href="exframes/frame_example20.1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example20.1.png" WIDTH="300"></A><BR><B>Figure 35:</B> Showing the values for each bar <A href="exframes/frame_example20.1.html"target="blank">[src]</A> <P></P></DIV></P><P> You cane see a small nuisance in this graph. The auto scalingalgorithm chooses quite tight limits for the scale so that the barsjust fit. Adding the value on top of the bar makes it collide with thetop of the graph. To remedy this we tell the auto scaling algorithm toallow for more "grace" space at the top of the scale by using themethod <A href="../ref/LinearScale.html#_LINEARSCALE_SETGRACE">SetGrace()</A> which is used to tell the scale to add a percentage (ofthe total scale span) more space to either one end or both ends of thescale. In this case we add 20% more space at the top to make more roomfor the values with the line<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">yaxis</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetGrace</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">20</FONT><FONTcolor="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> This will then give the graph as shown below<DIV class="example"><BR> <A href="exframes/frame_example20.2.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example20.2.png" WIDTH="300"></A><BR><B>Figure 36:</B> Adding some grace space to the top of the Y-scale <Ahref="exframes/frame_example20.2.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P> You can also adjust the general position of the value in respect tothe bar by using the <A href="../ref/BarPlot.html#_BARPLOT_SETVALUEPOS">BarPlot::SetValuePos()</A> method. You can set the position to either'top' (the default) , 'center' or 'bottom'. The graph below shows thevalue being positioned in the center. In this example we have alsoadjusted the format to just display the value as an integer without anydecimals.<DIV class="example"><BR> <A href="exframes/frame_example20.5.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example20.5.png" WIDTH="300"></A><BR><B>Figure 37:</B> Putting the values in the middle of the bar. <A href="exframes/frame_example20.5.html"target="blank">[src]</A> <P></P></DIV></P><P> It is also possible to specify a more fine grained control on howyou want the values presented. You can for example, rotate them, changefont, change color. It is also possible to adjust the actual valuedisplayed by either using a printf()-type format string or with themore advanced technique of a format callback routine.</P><P> To show what you can do we just give another example for you toexamine without much further explanations. Just remember that to havetext at an angle other than 0 or 90 degrees we have to use TTF fonts.Even though we haven't explained the SetFont() method it should befairly obvious.<DIV class="example"><BR> <A href="exframes/frame_example20.3.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example20.3.png" WIDTH="300"></A><BR><B>Figure 38:</B> Making the displayed values more interesting <A href="exframes/frame_example20.3.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="7_2_3">7.2.3 Adding a drop shadow to the bar</A></H3><P> One simple way of making the bar graph more attracting is to add adrop shadow to each bar. This is done by calling the <A href="../ref/BarPlot.html#_BARPLOT_SETSHADOW">SetShadow()</A> method. An example will clarify this.<DIV class="example"><BR> <A href="exframes/frame_example20.4.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example20.4.png" WIDTH="300"></A><BR><B>Figure 39:</B> Adding a drop shadow to each bar <A href="exframes/frame_example20.4.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="7_2_4">7.2.4 Adjusting the alignment of bars on a textscale</A></H3><P> As you have seen from the previous examples bar graphs are normallycentered between the trick marks on a text scale. However, you canmodify this behavior by calling the method <A href="../ref/BarPlot.html#_BARPLOT_SETALIGN">BarPlot::SetAlign()</A></P><H3><A NAME="7_2_5">7.2.5 Using grouped bar plots</A></H3><P> These types of bar graph is used to easy group two or more barstogether around each tick (X-value). The bars will be placedimmediately beside each other and as a group centered on each tickmark. A grouped bar is created by aggregating two or more ordinary bargraphs and creating a <A href="../ref/GroupBarPlot.html#_C_GROUPBARPLOT">GroupBarPlot()</A> From two ordinary bar graphs along the lines of<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> </FONT><FONT color="#FF8000">// Create the bar plots<BR></FONT><FONT color="#0000BB">$b1plot </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">BarPlot</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$data1y</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$b1plot</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFillColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"orange"</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#0000BB">$b2plot </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">BarPlot</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$data2y</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$b2plot</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFillColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"blue"</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Create the grouped bar plot<BR></FONT><FONT color="#0000BB">$gbplot </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">GroupBarPlot</FONT><FONT color="#007700">(array(</FONT><FONT color="#0000BB">$b1plot</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$b2plot</FONT><FONT color="#007700">));<BR><BR></FONT><FONT color="#FF8000">// ...and add it to the graPH<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Add</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$gbplot</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The following example illustrates this type of graph<DIV class="example"><BR> <A href="exframes/frame_example21.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example21.png" WIDTH="310"></A><BR><B>Figure 40:</B> A grouped bar plot <A href="exframes/frame_example21.html"target="blank">[src]</A> <P></P></DIV></P><P> There is no limit on the number of plots you may group together.</P><P> If you use the SetWidth() method on the GroupBarPlot() this willaffect the total width used by all the added plots. Each individual barwidth will be the same for all added bars. The default width forgrouped bar is 70%.</P><P> Setting the grouped with to 0.9 would result in the image below.<DIV class="example"><BR> <A href="exframes/frame_example22.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example22.png" WIDTH="310"></A><BR><B>Figure 41:</B> Adjusting the width for a gropued bar plot. <A href="exframes/frame_example22.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="7_2_6">7.2.6 Using accumulated bar plots</A></H3><P> The final variety of group bars you can have are accumulated bars.They work in much the same way as accumulated line plots describedabove. Each plot is stacked on top of each other.</P><P> You create accumulated bar plots in the same way as grouped barplots by first creating a number of ordinary bar plots that are thenaggregated with a call to <A href="../ref/AccBarPlot.html#_ACCBARPLOT_ACCBARPLOT">AccBarPlot();</A></P><P> An example makes this clear. Let's use the same data as in the twoexamples above but instead of grouping the bars we accumulate (orstack) them. The code would be very similar (actually only one line hasto change)<DIV class="example"><BR> <A href="exframes/frame_example23.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example23.png" WIDTH="310"></A><BR><B>Figure 42:</B> Accumulated bar plots <A href="exframes/frame_example23.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="7_2_7">7.2.7 Using grouped accumulated bar graphs</A></H3><P> It is perfectly possible to combine the previous bar types to havegrouped accumulated bar plots. This is done by just adding thedifferent accumulated plots to a group bar plot, for example thefollowing code would do that.<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> </FONT><FONT color="#FF8000">// Create all the 4 bar plots<BR></FONT><FONT color="#0000BB">$b1plot </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">BarPlot</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$data1y</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$b1plot</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFillColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"orange"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$b2plot </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">BarPlot</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$data2y</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$b2plot</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFillColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"blue"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$b3plot </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">BarPlot</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$data3y</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$b3plot</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFillColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"green"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$b4plot </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">BarPlot</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$data4y</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$b4plot</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFillColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"brown"</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Create the accumulated bar plots<BR></FONT><FONT color="#0000BB">$ab1plot </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">AccBarPlot</FONT><FONT color="#007700">(array(</FONT><FONT color="#0000BB">$b1plot</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$b2plot</FONT><FONT color="#007700">));<BR></FONT><FONT color="#0000BB">$ab2plot </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">AccBarPlot</FONT><FONT color="#007700">(array(</FONT><FONT color="#0000BB">$b3plot</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$b4plot</FONT><FONT color="#007700">));<BR><BR></FONT><FONT color="#FF8000">// Create the grouped bar plot<BR></FONT><FONT color="#0000BB">$gbplot </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">GroupBarPlot</FONT><FONT color="#007700">(array(</FONT><FONT color="#0000BB">$ab1plot</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$ab2plot</FONT><FONT color="#007700">));<BR><BR></FONT><FONT color="#FF8000">// ...and add it to the graph<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Add</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$gbplot</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> Putting this together in an example would then produce the graph asshown below<DIV class="example"><BR> <A href="exframes/frame_example24.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example24.png" WIDTH="310"></A><BR><B>Figure 43:</B> Combining grouped and accumulated bar plots <A href="exframes/frame_example24.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="7_2_8">7.2.8 Horizontal bar graphs</A></H3><P> It can often come in handy to have horizontal bar graphs especiallyif you have a large number of values to display. Even though JpGraphdoesn't directly support horizontal bar graphs this is easy achieved byconstructing a normal vertical bar graph which is then rotated 90degrees.</P><P> The example below shows a simple example of this<DIV class="example"><BR> <A href="exframes/frame_horizbarex3.html" target="blank"><IMG border="0"HEIGHT="500" src="img/img/img/img/img/img/img/img/horizbarex3.png" WIDTH="400"></A><BR><B>Figure 44:</B> A typical horizontal bar graph with the Y-axis atthe bottom <A href="exframes/frame_horizbarex3.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P> In order to achieve this effect you should study the above examplecarefully and you might notice two things</P><UL><LI> We don't simply rotate the graph we also specify that we want therotation center to be the middle of the entire image. The reason forthis is that by default (See the section on rotating plots) the pivotpoint for rotation is the center of<STRONG> the plot area</STRONG>.Since the center of the plot area is not necessary the center of theentire image the rotation might be a little bit difficult to predictsince it will depend on the margins specified. <</LI><LI> The size of the plot area is determined from the original width andheight of the image taking the specified margin into account. When thethe plot area is rotated 90 degrees clockwise what was the left marginnow in effect become the upper margin and so on. This is a small nuancesince we conceptually want to specify the margins directly in therotated plot.<BR> In order to more easily handle the margin with rotated images it isrecommended that the method "Set90AndMargin()" is used. This allows theimage to be rotated as well as specifying the margins in an obviousway.</LI></UL><P> We finally show three more examples of horizontal bar plots. In thefirst plot we have hidden the Y-axis and in the second we havepositioned the Y - axis at top as opposed to the bottom as the firstexample shows.</P><P><DIV class="example"><BR> <A href="exframes/frame_horizbarex1.html" target="blank"><IMG border="0"HEIGHT="500" src="img/img/img/img/img/img/img/img/horizbarex1.png" WIDTH="400"></A><BR><B>Figure 45:</B> Horizontal bar graph with hidden Y axis <A href="exframes/frame_horizbarex1.html"target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_horizbarex2.html" target="blank"><IMG border="0"HEIGHT="500" src="img/img/img/img/img/img/img/img/horizbarex2.png" WIDTH="400"></A><BR><B>Figure 46:</B> Horizontal bar graph with Y axis at the top <A href="exframes/frame_horizbarex2.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> In the final example which is almost similar to the two first weillustrate the use of labels with more than one line.<DIV class="example"><BR> <A href="exframes/frame_horizbarex4.html" target="blank"><IMG border="0"HEIGHT="500" src="img/img/img/img/img/img/img/img/horizbarex4.png" WIDTH="400"></A><BR><B>Figure 47:</B> Horizontal bar graph with manual integer scale aswell as multiple line labels <A href="exframes/frame_horizbarex4.html" target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="7_2_9">7.2.9 Using gradient fill for bar graphs</A></H3><P> It is possible to use color gradient fill for the individual bars inthe bar graph.</P><P> Color gradient fill fills a rectangle with a smooth transitionbetween two colors. In what direction the transition goes (from left toright, down and up, from the middle and out etc) is determined by thestyle of the gradient fill. JpGraph currently supports 8 differentstyles. All supported styles are displayed in the figure below.<DIV class="example"><BR> <A href="exframes/frame_bargradsmallex1.html" target="blank"><IMG border="0"HEIGHT="150" src="img/img/img/img/img/img/img/img/bargradsmallex1.png" WIDTH="200"></A><BR><B>Figure 48:</B> <A href="exframes/frame_bargradsmallex1.html" target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_bargradsmallex2.html" target="blank"><IMG border="0"HEIGHT="150" src="img/img/img/img/img/img/img/img/bargradsmallex2.png" WIDTH="200"></A><BR><B>Figure 49:</B> <A href="exframes/frame_bargradsmallex2.html" target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_bargradsmallex3.html" target="blank"><IMG border="0"HEIGHT="150" src="img/img/img/img/img/img/img/img/bargradsmallex3.png" WIDTH="200"></A><BR><B>Figure 50:</B> <A href="exframes/frame_bargradsmallex3.html" target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_bargradsmallex4.html" target="blank"><IMG border="0"HEIGHT="150" src="img/img/img/img/img/img/img/img/bargradsmallex4.png" WIDTH="200"></A><BR><B>Figure 51:</B> <A href="exframes/frame_bargradsmallex4.html" target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_bargradsmallex5.html" target="blank"><IMG border="0"HEIGHT="150" src="img/img/img/img/img/img/img/img/bargradsmallex5.png" WIDTH="200"></A><BR><B>Figure 52:</B> <A href="exframes/frame_bargradsmallex5.html" target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_bargradsmallex6.html" target="blank"><IMG border="0"HEIGHT="150" src="img/img/img/img/img/img/img/img/bargradsmallex6.png" WIDTH="200"></A><BR><B>Figure 53:</B> <A href="exframes/frame_bargradsmallex6.html" target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_bargradsmallex7.html" target="blank"><IMG border="0"HEIGHT="150" src="img/img/img/img/img/img/img/img/bargradsmallex7.png" WIDTH="200"></A><BR><B>Figure 54:</B> <A href="exframes/frame_bargradsmallex7.html" target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_bargradsmallex8.html" target="blank"><IMG border="0"HEIGHT="150" src="img/img/img/img/img/img/img/img/bargradsmallex8.png" WIDTH="200"></A><BR><B>Figure 55:</B> <A href="exframes/frame_bargradsmallex8.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P> To specify a gradient fill for the bar plots you make use of themethod <A href="../ref/BarPlot.html#_BARPLOT_SETFILLGRADIENT">BarPlot::SetFillGradient()</A> . See the class reference for details ofthis function.</P><P> When using gradient fills there are a couple of caveats you shouldbe aware of:</P><UL><LI>gradient filling is computational expensive. Large plots withgradient fill will take in the order of 6 times longer to fill then fora normal one-color fill. This might to some extent be helped by makinguse of the cache feature of JpGraph so that the graph is only generateda few times.</LI><LI>gradient filling will make use of much more colors (by definition)this will make the color palette for the image bigger and hence makethe overall image larger. It might also have some severe effect onusing anti-aliased line in the same image as color gradient fillingsince anti-aliased lines also have the possibility to make use of manycolors. Hence the color palette might not be big enough for all thecolors you need. So if you use gradient fills you should also be usinga true-color image since you otherwise run out of colors.<BR> This problem is often seen as that for no apparent reason somecolor you have specified in the image does appear as another color.(This is not a bug in JpGraph!) This is something to especially watchout for when enabling anti-aliasing since that also uses a lot ofcolors. Since the numbers of colors used with anti-aliasing depends onthe angle on the lines it is impossible to foresee the number of colorsused for this.</LI></UL><P></P><H3><A NAME="7_2_10">7.2.10 Creating semi-filled bar graphs</A></H3><P> Semi filled bar graphs are in principle the same as normal filledbar graphs but with the additional feature that you can choose to onlyfill a specified range (or ranges) of X-coordinates. The figure belowillustrates this</P><P><DIV class="example"><BR> <A href="exframes/frame_partiallyfilledlineex1.html" target="blank"><IMG border="0" HEIGHT="300" src="img/img/img/img/img/img/img/img/partiallyfilledlineex1.png" WIDTH="400"></A><BR><B>Figure 56:</B> Semi-filled line graph <A href="exframes/frame_partiallyfilledlineex1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> In this example we defined two areas along the X-axis to be filled.You can add filled areas by using the method <A href="../ref/LinePlot.html#_LINEPLOT_ADDAREA">AddArea()</A> and specifying range and color for the filled area.</P><H2><A NAME="7_3">7.3 Error plots</A></H2><P> Error plots are used to visually indicate uncertainty in datapoints. This is done by for each X value by giving both a minimum and amaximum Y-value.</P><P> Before you can use error plots you must remember to include the file"jpgraph_error.php" in your script.</P><P> The following example illustrates a simple error bar. We will have 5points, so we need 10 Y-values. We also would like the error bars to bered and 2 pixels wide. All this is accomplished by creating an <A href="../ref/ErrorPlot.html#_C_ERRORPLOT">ErrorPlot()</A> in much the same way as, for example, a normal lineplot. Doing this would now give the example shown below.</P><P><DIV class="example"><BR> <A href="exframes/frame_example13.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example13.png" WIDTH="300"></A><BR><B>Figure 57:</B> A simple error bar <A href="exframes/frame_example13.html"target="blank">[src]</A> <P></P></DIV></P><P> You might notice that there is one displeasing esthetic quality ofthis graph. The X-scale is just wide enough to just accompany thenumber of error bars and hence the first bar is drawn on the Y-axis andthe and last bar just at the edge of the plot area. To adjust this youmight call the <A href="../ref/Plot.html#_PLOT_SETCENTER"> SetCenter()</A>method which will adjust the X-scale so it does not use the full widthof the X-axis.</P><P> The following example illustrates the use of this feature byapplying this technique to the previous example<DIV class="example"><BR> <A href="exframes/frame_example14.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example14.png" WIDTH="300"></A><BR><B>Figure 58:</B> Adjusting the X-scale not to use the full width ofthe X-axis. <A href="exframes/frame_example14.html" target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="7_3_1">7.3.1 Using line error plots</A></H3><P> A line error plot is an error plot with the addition that a line isdrawn between the average value of each error pair. You use this typeof plot the exact same way you would use an error plot. The only changeis that you must instantiated an <A href="../ref/ErrorPlot.html#_C_ERRORPLOT">ErrorLinePlot()</A> instead and make sure you have included the"jpgraph_line.php" since the line error plot makes use of the line plotclass to stroke the line.</P><P> To control the various properties of the line drawn the "line"property of the error line plot may be accessed. So, for example, ifyou want the line to be 2 pixels wide and blue you would have to addthe following two lines<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $elplot</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">line</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetWeight</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">2</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">$elplot</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">line</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"blue"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P>to generate the graph as shown below<DIV class="example"><BR> <A href="exframes/frame_example15.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example15.png" WIDTH="300"></A><BR><B>Figure 59:</B> Linear error plot <A href="exframes/frame_example15.html"target="blank">[src]</A> <P></P></DIV></P><P> You may of course add legends to none, one or both of the line typesin the above graph. So for example if we wanted the legend "Min/Max"for the red error bars and a legend "Average" for the blue line youwould have to add the lines<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $errplot</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetLegend</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"Min/Max"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$errplot</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">line</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetLegend</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"Average"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The resulting graph will now look like (note that we are using thedefault placement of the legend box)<DIV class="example"><BR> <A href="exframes/frame_example16.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example16.png" WIDTH="300"></A><BR><B>Figure 60:</B> Addding a legend box to the line error plot. <A href="exframes/frame_example16.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H2><A NAME="7_4">7.4 Scatter plots</A></H2><P> Scatter plots are very simple; they plot a number of pointsspecified by their X- and Y-coordinate. Each point is stroked on theimage with a mark as with line plots. The stroked marks can also beconnected with an optional line.<DIV class="note"><B>Note:</B> Eventhough it is only scatter plot that was designed to be used with X,Yplots it is perfectly possible to use use both X,Y coordinates for barand line plots as well.</DIV></P><P> Even though you would normally supply X-coordinates it is stillperfectly possible to use a text-scale for X-coordinates to justenumerate the points. This is especially useful when using the"Impulse" type of scatter plot as is shown below.</P><P> Scatter pots are created by including the jpgraph extension"jpgraph_scatter.php" and then creating an instance of plot type ofScatterPlot(). To specify the mark you want to use you access the markwith the instance variable "mark" in the scatter plot. The default isto use an unfilled small circle.</P><P> To create a scatter plot you will create an instance</P><P> A simple example using just default values will illustrate this</P><P><DIV class="example"><BR> <A href="exframes/frame_scatterex1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/scatterex1.png" WIDTH="300"></A><BR><B>Figure 61:</B> The simplest possible scatter plot <A href="exframes/frame_scatterex1.html"target="blank">[src]</A> <P></P></DIV></P><P>We can easily adjust the size and colors for the markers to getanother effect as shown below<DIV class="example"><BR> <A href="exframes/frame_scatterex2.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/scatterex2.png" WIDTH="300"></A><BR><B>Figure 62:</B> The simplest possible scatter plot with adjustedmarks <A href="exframes/frame_scatterex2.html" target="blank">[src]</A> <P></P></DIV></P><P> Another possible variant of scatter plot is impulse-scatter plots.This is a variant of normal scatter plot where each mark have a linefrom the mark to the Y=0 base line. To change a scatter plot into animpulse scatter plot you have to call the method <A href="../ref/ScatterPlot.html#_SCATTERPLOT_SETIMPULS">SetImpuls()</A> on the scatter plot.</P><P> This type of plots are often used to illustrate signals inconjunction with digital signal processing. The following two examplesillustrates simple use of impulse plots.<DIV class="example"><BR> <A href="exframes/frame_impulsex1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/impulsex1.png" WIDTH="300"></A><BR><B>Figure 63:</B> A simple impuls plot <A href="exframes/frame_impulsex1.html"target="blank">[src]</A> <P></P></DIV></P><P> The next example shows how to modify the color and width of theimpulse plot<DIV class="example"><BR> <A href="exframes/frame_impulsex2.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/impulsex2.png" WIDTH="300"></A><BR><B>Figure 64:</B> A modified impuls plot <A href="exframes/frame_impulsex2.html"target="blank">[src]</A> <P></P></DIV></P><P><DIV class="note"><B>Note:</B> You may draw impulse graphs withoutany mark by specifying the mark type as (-1) . That way only theimpulse lines will be drawn.</DIV></P><P> As a final touch we show two more advanced impulse graphs . In thesegraphs we have used more advanced formatting for the Y-axis labels aswell as adjusted the position of the axis position.<DIV class="example"><BR> <A href="exframes/frame_impulsex3.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/impulsex3.png" WIDTH="400"></A><BR><B>Figure 65:</B> In this imuplsplot we have adjusted the positionof the X-axis to the bottom and also added more decimals to the labelson the Y-axis <A href="exframes/frame_impulsex3.html" target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_impulsex4.html" target="blank"><IMG border="0"HEIGHT="250" src="img/img/img/img/img/img/img/img/impulsex4.png" WIDTH="500"></A><BR><B>Figure 66:</B> In this impuls plot we have also added a lineplotwith a dotted line style. <A href="exframes/frame_impulsex4.html" target="blank">[src]</A> <P></P></DIV></P><P></P><H2><A NAME="7_5">7.5 Field plots</A></H2><P> A variant of scatter plot is the so called<I> Field Plots</I> thisis basically a scatter plot where each scatter point is an arrow with adirection between 0 to 359 degrees. This effectively allows thevisualization of 3 parameters at each point (x,y,angle). As anadditional bonus there is also possible to define a callback for eachscatter plot to also define the color for each point.</P><P> To create a field plot you create an instance of <A href="../ref/FieldPlot.html#_C_FIELDPLOT">FieldPlot</A> in the same way as you created a normal scatter plot. Thearguments to this method are Y-coordinate, X-coordinate and angle. Tospecify a callback you use <A href="../ref/FieldPlot.html#_FIELDPLOT_SETCALLBACK">FieldPlot::SetCallback()</A></P><P> The following example (and code) illustrates the usage of the fieldplot type.</P><P><DIV class="example"><BR> <A href="exframes/frame_fieldscatterex1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/fieldscatterex1.png" WIDTH="300"></A><BR><B>Figure 67:</B> Example of the Field plot type <A href="exframes/frame_fieldscatterex1.html"target="blank">[src]</A> <P></P></DIV></P><P> In addition to the parameters mentioned above you can also adjustboth the general size of the arrow and also the specific size of thearrowhead. The arrow size is specified in pixels and the arrow head isspecified as an integers between 0 and 10. These sizes are specifiedwith a call to <A href="../ref/FieldArrow.html#_FIELDARROW_SETSIZE">FieldPlot::arrow::SetSize()</A></P><H2><A NAME="7_6">7.6 Box and Stock charts</A></H2><P> JpGraph offers two variation on what is usually known as stockcharts, candle-charts or box plot.</P><H3><A NAME="7_6_1">7.6.1 Stock Charts</A></H3><P> Stock charts is used to display data values where one is interestedin 4 different values for each data point. This could for example beused to display a stocks open,close, min and max value during aspecific day. Hence the name Stock chart (or Stock plot).</P><P> The figure below illustrates a sample Stock chart plot<DIV class="example"><BR> <A href="exframes/frame_stockex1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/stockex1.png" WIDTH="300"></A><BR><B>Figure 68:</B> A simple stock plot <A href="exframes/frame_stockex1.html"target="blank">[src]</A> <P></P></DIV></P><P> For this type of plot the Y-data array must be consist of a numberof quadruples of data where each quadruple consists of(open,close,min,max). The open and close values determine the min maxfor the middle bar and the min,max determine the end points of the"error-lines" at the top and bottom of of each bar.</P><P> Note that the data follows the following rules</P><UL><LI> min < max</LI><LI> min < min(open.close)</LI><LI> max > max(open,close)</LI></UL><P> To separate the two cases where "open > close" or "open < close "different colors are used. These colors are specified with the <A href="../ref/StockPlot.html#_STOCKPLOT_SETCOLOR">SetColor()</A> method. By default a positive bar (close > open) have afill color of white and for the negative case where (close < open) thebars have a red color.</P><P> You can specify the width of the bar by setting the width (inpixels) with a call to the method <A href="../ref/StockPlot.html#_STOCKPLOT_SETWIDTH">SetWidth()</A></P><P> The final variation of stock plots you can have is to determinewhether or not the end point for the min,max lines should have thehorizontal line marking the end of the line or not. This can beadjusted with a call to method <A href="../ref/StockPlot.html#_STOCKPLOT_HIDEENDLINES">HideEndLine()</A>.</P><H3><A NAME="7_6_2">7.6.2 BoxPLots : Stock charts with a median line</A></H3><P> A minor variation of stock charts is the "BoxPlot()" this is almostthe same as StockPlot() but with the very small difference that inaddition to the open,close,min, max values you also specify a medianvalue . The median lies between the open and close value and isillustrated as a horizontal line within the bar.<DIV class="example"><BR> <A href="exframes/frame_boxstockex1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/boxstockex1.png" WIDTH="300"></A><BR><B>Figure 69:</B> A simple box type stock plot <A href="exframes/frame_boxstockex1.html"target="blank">[src]</A> <P></P></DIV></P><P> You may modify the median line color for positive and negative datapoints / bars by using the <A href="../ref/BoxPlot.html#_BOXPLOT_SETMEDIANCOLOR">SetMedianColor()</A> method.</P><H3><A NAME="7_6_3">7.6.3 Image maps for Box and Stock charts</A></H3><P> In the same way as for other plots you may associate an image mapwith these plots. The "hot" area for each plot is the mid "bar"section. In the same way as other plot types you use the <A href="../ref/Plot.html#_PLOT_SETCSIMTARGETS">SetCSIMTargets()</A> to set the URLs you want to use.</P><P> These plot types, though normally used without explicit X-values,can of course handle a supplied X-coordinate array without any problem.</P><H2><A NAME="7_7">7.7 Combining different graph types</A></H2><P> It is perfectly legal to add several different plot types to thesame graph. It is therefore possible to mix line plots with (forexample) filled bar graphs. What you should keep in mind doing this isthe order in which these plots are stroked to the image since a laterstroke will overwrite a previous one. All plots are stroked in theorder you add them, i.e. the first plot added will be stroked first.You can therefore control which plot is placed in the background andwhich one is placed in the foreground by the order you add them to theplot.</P><P> To start simple we just mix a filled line plot with a non-filledline plot as the following example shows.</P><P><DIV class="example"><BR> <A href="exframes/frame_example16.1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example16.1.png" WIDTH="400"></A><BR><B>Figure 70:</B> Mixing filled and non-filled line plots in thesame graph <A href="exframes/frame_example16.1.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P> Let's now go to something a little bit more complicated. How to mixbar and line graphs. Let's just take one of our previous bar graphs andadd a line plot to it and see what happens.</P><P><DIV class="example"><BR> <A href="exframes/frame_example16.2.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example16.2.png" WIDTH="400"></A><BR><B>Figure 71:</B> Adding a line to a bar graph <A href="exframes/frame_example16.2.html"target="blank">[src]</A> <P></P></DIV></P><P>Not too bad. But we can't see the line so we change the order inwhich we add the lines to the graph and sees what happens.<DIV class="example"><BR> <A href="exframes/frame_example16.3.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example16.3.png" WIDTH="400"></A><BR><B>Figure 72:</B> Adding a line to a bar graph, in different orderv2<A href="exframes/frame_example16.3.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P> If you want the line points to be aligned in the center of the barsyou can accomplish this is two ways.</P><P> If you use a text scale then you need to call the <A href="../ref/LinePlot.html#_LINEPLOT_SETBARCENTER">LinePlot::SetBarCenter()</A><DIV class="example"><BR> <A href="exframes/frame_linebarcentex1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/linebarcentex1.png" WIDTH="400"></A><BR><B>Figure 73:</B> Centering the line point in the middle of the barsusing LinePlot::SetBarCenter() <A href="exframes/frame_linebarcentex1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> You can also use an integer scale. This places<STRONG> both</STRONG>the bar and the line points centered at the tick marks. As thefollowing example will show</P><P><DIV class="example"><BR> <A href="exframes/frame_example16.4.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example16.4.png" WIDTH="400"></A><BR><B>Figure 74:</B> Using a linear scale <A href="exframes/frame_example16.4.html"target="blank">[src]</A> <P></P></DIV></P><P><DIV class="note"><B>Note:</B> In this example we also haveillustrated the fact that it is possible to add text labels to a linear(or integer) scales as well.</DIV></P><P> As a final example we show how you can combine a scatter plot and aline plot which could be used to illustrate a regression line fitting.<DIVclass="example"><BR> <A href="exframes/frame_example16.6.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example16.6.png" WIDTH="300"></A><BR><B>Figure 75:</B> Combining a scatter plot and a line plot <A href="exframes/frame_example16.6.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H2><A NAME="7_8">7.8 Specifying the scale manually</A></H2><P> Normally the automatic scaling should be doing an adequate job inmost circumstances but there might be cases where you like to manuallyset the scale. For example if you have several graphs where you like tobe able to easily compare them and therefore want them all to have thesame scale.</P><P> To specify a manual scale you have to add arguments to the standard <Ahref="../ref/Graph.html#_GRAPH_SETSCALE"> Graph::SetScale()</A> method.So to specify that you want an Y-scale between 0 and 100 you need towrite<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetScale</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"textlin"</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">100</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P>When you specify a scale manually there is one additional thing youneed to decide. How the tick marks should be positioned. You have threechoices</P><OL><LI> Let JpGraph decide suitable tick marks honoring the exact scale youspecified.<B> This is the default behavior</B> if you don't do anythingelse.</LI><LI> Allow JpGraph to slightly adjust your specified min and max values.With the default method, depending on the min and max values, the endand start of the scale might not fall on an exact tick mark. Foresthetic reasons you might still want the last/first tick mark to fallon the edges of the scale. By calling <A href="../ref/LinearScale.html#_LINEARSCALE_SETAUTOTICKS">LinearScale::SetAutoTicks()</A> you tell JpGraph to make the smallestnecessary adjustment of the end/start points so that they fall on anexact tick mark.</LI><LI> Manually specify the tick marks with a call to <A href="../ref/LinearTicks.html#_LINEARTICKS_SET">LinearTicks::Set()</A> For example<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetScale</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"textlin"</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">100</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">yscale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">ticks</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONTcolor="#007700">(</FONT><FONT color="#0000BB">10</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">5</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV><P>Will set the major tick marks every at 0,10,20,.. And every minortick mark in between (0,5,10,15,20,25,...).</P></LI></OL><P> The three images below illustrates the difference between thepossibilities of ticks for a manual scale.<DIV class="example"><BR> <A href="exframes/frame_manscaleex1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/manscaleex1.png" WIDTH="220"></A><BR><B>Figure 76:</B> Manual scale, manual ticks major=7 minor=2 <A href="exframes/frame_manscaleex1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P><DIV class="example"><BR> <A href="exframes/frame_manscaleex4.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/manscaleex4.png" WIDTH="220"></A><BR><B>Figure 77:</B> Manual scale, automatic ticks with exact limits <A href="exframes/frame_manscaleex4.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P><DIV class="example"><BR> <A href="exframes/frame_manscaleex2.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/manscaleex2.png" WIDTH="220"></A><BR><B>Figure 78:</B> Manual scale, automatic ticks where we allowadjustments of the limits <A href="exframes/frame_manscaleex2.html" target="blank">[src]</A> <P></P></DIV></P><P></P><H2><A NAME="7_9">7.9 Adjusting the automatic tick marks</A></H2><P> You can adjust the automatic tick marks by telling JpGraph how denseyou want them to be. You use the <A href="../ref/Graph.html#_GRAPH_SETTICKDENSITY">Graph::SetTickDensity()</A> method. You can set the density setting infour steps</P><UL><LI> TICKD_VERYSPARSE, Very few ticks</LI><LI> TICKD_SPARSE, Few ticks</LI><LI> TICKD_NORMAL, Standard number of ticks</LI><LI> TICKD_DENSE, Large number of ticks</LI></UL><P> Taking the previous example with the manual scale but automaticticks and using a denser ticks setting gives the following result<DIV class="example"><BR> <A href="exframes/frame_manscaleex3.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/manscaleex3.png" WIDTH="250"></A><BR><B>Figure 79:</B> Manual scale with automatic ticks but with adenser tick settings. <A href="exframes/frame_manscaleex3.html" target="blank">[src]</A> <P></P></DIV></P><P></P><H2><A NAME="7_10">7.10 Handling date/time scales</A></H2><P> With date/time scale we refer to the plotting of data where theindependent variable (X-axis) de-nominates a time value. This could forexample be the temperature measured in intervals during a day.</P><P> From version 1.18 and onwards there are two principal ways ofhandling date/time scales. The manual way and fully automatic using thespecial "dat" scale. For most cases the automatic "dat" scale is thepreferred choice but in rare circumstances it might be more appropriateto use the manual way since it gives slightly more control (but notthat much) of the overall handling of scales.</P><P> To be able to use a date/time scale at all we will assume that thedata points are represented by both an X coordinate (time-value) and aY-value (anything else wouldn't make sense).</P><P> We first start by describing the use of the "dat" scale.</P><H3><A NAME="7_10_1">7.10.1 Using the automatic date/time scale</A></H3><P> The easiest way to get a date time scale for the X-axis is to usethe pre-defined "dat" scale. To be able to use that it is firstnecessary to include the module<I> "jpgraph_date.php"</I> and thespecify the scale, for example as "datlin" in the call to<I> SetScale()</I>as the following code snippet shows.<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> </FONT><FONT color="#007700">require_once(</FONT><FONTcolor="#DD0000">"../jpgraph.php"</FONT><FONT color="#007700">);<BR>require_once(</FONT><FONT color="#DD0000">"../jpgraph_line.php"</FONT><FONTcolor="#007700">);<BR>require_once(</FONT><FONT color="#DD0000">"../jpgraph_date.php"</FONT><FONTcolor="#007700">);<BR>...<BR></FONT><FONT color="#0000BB">$graph </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">Graph</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">540</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">300</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetScale</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'datlin'</FONT><FONT color="#007700">);<BR>...</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The above code snippet would create a date/linear scale for thegraph. We will first show a basic use of the date scale and then go onto illustrate how it is possible to tailor the exact formatting of thedate axis.</P><P> When using the fully automatic formatting the library will use theshortest possible string that uniquely identifieas a date/time. Forexample if the entire intervall falls within the same day only the timevalues will be displayed, if the intervall falls over several days thenalso the date will be added to the label.</P><P> As usual it is also possible to manually force a certain labelformatting to be used this is illustrated below.</P><H4>7.10.1.1 Specifying the input data</H4><P> The first basic example below creates a data set that emulates asample rate every S second and falls over a total period of two days.It is important to note that the input data on the X-axis must be a inthe form of timestamp data, i.e. the number of seconds from the systemepoch. In PHP the current timestamp value is returned by the function<I>time()</I>.</P><P> This means that it is always mandatory to specify two input vectorsfor a plot. For example to specify a line plot<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $line </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">LinePlot</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$data</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">$xdata</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The example below show this in practice<DIV class="example"><BR> <A href="exframes/frame_dateaxisex2.html" target="blank"><IMG border="0"HEIGHT="300" src="img/img/img/img/img/img/img/img/dateaxisex2.png" WIDTH="540"></A><BR><B>Figure 80:</B> Using the special date X-axis with all defaultvalues <A href="exframes/frame_dateaxisex2.html" target="blank">[src]</A> <P></P></DIV></P><P> Please review the script (by following the [src] link) that createsthis graph before continuing since we will base all further examples onthe above example.</P><H4>7.10.1.2 Adjusting the start and end alignment</H4><P> As can be seen from the above example the scale starts slightlybefore the first data point. Why? This is of course by purpose in orderto make the first time label to start on an "even" value, in this caseon an hour. Depending on the entire interval of the graph the startvalue will always be chosen to be the largest "even" time value, thiscould for example be on an even minute, even 30min, even hour, evenday, even week and so on.</P><P> The alignment of the start (and end) vdate alignment can also beadjusted manually by using the two methods</P><UL><LI><I> SetTimeAlign($aStartAlign,$aEndAlign)</I></LI><LI><I> SetDateAlign($aStartAlign,$aEndAlign)</I></LI></UL><P> These method allow the alignment to be made by specifying one of thefollowing constants.</P><P> For the SetTimeAlign() the following symbolic constants can be used</P><OL><LI> Alignment on seconds<UL><LI> MINADJ_1, Align on a single second (This is the lowest resolution)</LI><LI> MINADJ_5, Align on the nearest 5 seconds</LI><LI> MINADJ_10, Align on the nearest 10 seconds</LI><LI> MINADJ_15, Align on the nearest 15 seconds</LI><LI> MINADJ_30, Align on the nearest 30 seconds</LI></UL></LI><LI> Alignment on minutes<UL><LI> MINADJ_1, Align to the nearest minute</LI><LI> MINADJ_5, Align on the nearest 5 minutes</LI><LI> MINADJ_10, Align on the nearest 10 minutes</LI><LI> MINADJ_15, Align on the nearest 15 minutes</LI><LI> MINADJ_30, Align on the nearest 30 minutes</LI></UL></LI><LI> Alignment on hours<UL><LI> HOURADJ_1, Align to the nearest hour</LI><LI> HOURADJ_2, Align to the nearest two hour</LI><LI> HOURADJ_3, Align to the nearest three hour</LI><LI> HOURADJ_4, Align to the nearest four hour</LI><LI> HOURADJ_6, Align to the nearest six hour</LI><LI> HOURADJ_12, Align to the nearest tolw hour</LI></UL></LI></OL><P> For the<I> SetDateAlign()</I> the following symbolic constants canbe used</P><OL><LI> Alignment on a day basis<UL><LI> DAYADJ_1, Align on the start of a day</LI><LI> DAYADJ_7, Align on the start of a week</LI><LI> DAYADJ_WEEK, Synonym to DAYADJ_7</LI></UL></LI><LI> Alignment on a monthly basis<UL><LI> MONTHADJ_1, Align on a month start</LI><LI> MONTHADJ_6, Align on the start of halfyear</LI></UL></LI><LI> Alignment on a yearly basis<UL><LI> YEARADJ_1, Align on a year</LI><LI> YEARADJ_2, Align on a bi-yearly basis</LI><LI> YEARADJ_5, Align on a 5 year basis</LI></UL></LI></OL><P> Some examples will calrify the use of these methods.</P><P><B> Example 1.</B> We want the time adjustment to start on an evenquarter of an hour, i.e. an even 15 minute period.<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">xaxis</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetTimeAlign</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">MINADJ_15</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P><B> Example 2.</B> We want the time to start on an even 2 hour<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">xaxis</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetTimeAlign</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">HOURADJ_2</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P><B> Example 3.</B> We want the start to be on an even day<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">xaxis</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetDateAlign</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">DAYADJ_1</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><H4>7.10.1.3 Adjusting the label format</H4><P> The default label format always tries to use the shortest possibleunique string. To manually set a manual scale the method<I>SetDateFormat()</I> is used for example as in<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">xaxis</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetDateFormat</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'H:i'</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P>The above example will force the labels to be displayed as hour (24h)and minutes.<DIV class="example"><BR> <A href="exframes/frame_dateaxisex4.html" target="blank"><IMG border="0"HEIGHT="300" src="img/img/img/img/img/img/img/img/dateaxisex4.png" WIDTH="540"></A><BR><B>Figure 81:</B> Using specific label format and align time axis tostart and end on an even 10min <A href="exframes/frame_dateaxisex4.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H4>7.10.1.4 Adjusting the date scale density</H4><P> As with the linear scale it is possible to indicate what density ofscale ticks is needed. This is specified as usual with a call to<I>Graph::SetTickDensity()</I><DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetTickDensity</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">TICKD_DENSE</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><H3><A NAME="7_10_2">7.10.2 Specifying a date/time scale with a manualcall-back</A></H3><P> In the following we will assume that all data points are specifiedby a tuple where the date/time is specified as a timestamp in second inthe same format as is returned by the PHP function time().</P><P> The trick here is to use a label formatting callback routine whichgets called to format each label on the scale.</P><P> What we do is that we specify that the X-scale should be an ordinary"int" scale (remember that the data values are timestamps which areintegers). We then install our custom label callback (with a call to <A href="../ref/Axis.html#_AXIS_SETLABELFORMATCALLBACK">SetLabelFormatCallback()</A>) which given a timestamp formats it to asuitable human readable form. In our example we will use the PHPfunction Date() for this purpose.</P><P> The callback we use will be<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> </FONT><FONT color="#FF8000">// The callback that converts timestamp to minutes and seconds<BR></FONT><FONT color="#007700">function </FONT><FONT color="#0000BB">TimeCallback</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$aVal</FONT><FONT color="#007700">) {<BR> return </FONT><FONT color="#0000BB">Date</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'H:i:s'</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">$aVal</FONT><FONT color="#007700">);<BR>}</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> Using some random data we can now generate the following graph<DIV class="example"><BR> <A href="exframes/frame_dateaxisex1.html" target="blank"><IMG border="0"HEIGHT="250" src="img/img/img/img/img/img/img/img/dateaxisex1.png" WIDTH="324"></A><BR><B>Figure 82:</B> Example on how to format an axis to hold adate/time scale using and integer scale and a callback routine <A href="exframes/frame_dateaxisex1.html"target="blank">[src]</A> <P></P></DIV></P><P> In the above example we have specified the X-scale manually to makesure that the min/max values on the X-axis exactly matches the min/maxx-data values.</P><P> SetLabelFormatCallback() will be called for each of the displayedlabels and the argument passed on to the supplied function is thedefault label that the library is assigning that specific label.</P><P> This means that if the data to be displayed is based on, forexample, timestamps which are given in seconds the displayed valuemight not be aligned to how time/date values normally should bedisplayed.</P><P> Using integer scales this will not work very well since the librarydetermines label positions to be at even positions (e.g. every 2,5,10,20,50,100 etc) to suit the auto-scaling since the library will assumethat the data is integers and not timestamp values.</P><P> The best way to solve this is to use an integer X-scale togetherwith a a callback function with a manually specified scale. In order tosetup the scale a bit of manually work is needed. Depending on the datato be displayed one should ensure that the scale starts and ends atsuitable times and that the tick interval chosen fits with an evenmultiple of minutes, hours, days or what is best suited for the timerange that is to be displayed.</P><P> The following code example illustrates this. It creates some "fake"data that is assumed to be sampled time based data and sets up somesuitable scales and tick interval. This script may be used as a basisfor more advanced handling of the time data.<DIV class="phpscript">(File: timestampex01.php)<BR><CODE><FONT color="#000000"> <FONT color="#0000BB"><?php<BR></FONT><FONT color="#FF8000">// Example on how to treat and format timestamp as human readable labels<BR></FONT><FONT color="#007700">require_once(</FONT><FONT color="#DD0000">"../jpgraph.php"</FONT><FONT color="#007700">);<BR>require_once(</FONT><FONT color="#DD0000">"../jpgraph_line.php"</FONT><FONTcolor="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Number of "fake" data points<BR></FONT><FONT color="#0000BB">DEFINE</FONT><FONT color="#007700">(</FONT><FONTcolor="#DD0000">'NDATAPOINTS'</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">500</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Assume data points are sample every 10th second<BR></FONT><FONT color="#0000BB">DEFINE</FONT><FONT color="#007700">(</FONT><FONTcolor="#DD0000">'SAMPLERATE'</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">10</FONT><FONT color="#007700">); <BR><BR></FONT><FONT color="#FF8000">// Callback formatting function for the X-scale to convert timestamps<BR>// to hour and minutes.<BR></FONT><FONT color="#007700">function </FONT><FONT color="#0000BB">TimeCallback</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$aVal</FONT><FONT color="#007700">) {<BR> return </FONT><FONT color="#0000BB">Date</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'H:i'</FONT><FONT color="#007700">, </FONT><FONTcolor="#0000BB">$aVal</FONT><FONT color="#007700">);<BR>}<BR><BR></FONT><FONT color="#FF8000">// Get start time<BR></FONT><FONT color="#0000BB">$start </FONT><FONT color="#007700">= </FONT><FONTcolor="#0000BB">time</FONT><FONT color="#007700">();<BR></FONT><FONT color="#FF8000">// Set the start time to be on the closest minute just before the "start" timestamp<BR></FONT><FONT color="#0000BB">$adjstart </FONT><FONT color="#007700">= </FONT><FONT color="#0000BB">floor</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$start </FONT><FONT color="#007700">/ </FONT><FONT color="#0000BB">60</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Create a data set in range (20,100) and X-positions<BR>// We also apply a simple low pass filter on the data to make it less<BR>// random and a little smoother<BR></FONT><FONT color="#0000BB">$data </FONT><FONT color="#007700">= array();<BR></FONT><FONT color="#0000BB">$xdata </FONT><FONT color="#007700">= array();<BR></FONT><FONT color="#0000BB">$data</FONT><FONT color="#007700">[</FONT><FONTcolor="#0000BB">0</FONT><FONT color="#007700">] = </FONT><FONT color="#0000BB">rand</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">20</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">100</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$xdata</FONT><FONT color="#007700">[</FONT><FONTcolor="#0000BB">0</FONT><FONT color="#007700">] = </FONT><FONT color="#0000BB">$adjstart</FONT><FONT color="#007700">;<BR>for( </FONT><FONT color="#0000BB">$i</FONT><FONT color="#007700">=</FONT><FONTcolor="#0000BB">1</FONT><FONT color="#007700">; </FONT><FONT color="#0000BB">$i </FONT><FONT color="#007700">< </FONT><FONT color="#0000BB">NDATAPOINTS</FONT><FONT color="#007700">; ++</FONT><FONT color="#0000BB">$i </FONT><FONT color="#007700">) {<BR> </FONT><FONT color="#0000BB">$data</FONT><FONT color="#007700">[</FONT><FONTcolor="#0000BB">$i</FONT><FONT color="#007700">] = </FONT><FONT color="#0000BB">rand</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">20</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">100</FONT><FONT color="#007700">)*</FONT><FONT color="#0000BB">0.2 </FONT><FONT color="#007700">+ </FONT><FONTcolor="#0000BB">$data</FONT><FONT color="#007700">[</FONT><FONT color="#0000BB">$i</FONT><FONT color="#007700">-</FONT><FONT color="#0000BB">1</FONT><FONTcolor="#007700">]*</FONT><FONT color="#0000BB">0.8</FONT><FONT color="#007700">;<BR> </FONT><FONT color="#0000BB">$xdata</FONT><FONT color="#007700">[</FONT><FONT color="#0000BB">$i</FONT><FONT color="#007700">] = </FONT><FONTcolor="#0000BB">$adjstart </FONT><FONT color="#007700">+ </FONT><FONT color="#0000BB">$i </FONT><FONT color="#007700">* </FONT><FONT color="#0000BB">SAMPLERATE</FONT><FONT color="#007700">;<BR>}<BR><BR></FONT><FONT color="#FF8000">// Assume that the data points represents data that is sampled every 10s<BR>// when determing the end value on the scale. We also add some extra<BR>// length to end on an even label tick.<BR></FONT><FONT color="#0000BB">$adjend </FONT><FONT color="#007700">= </FONT><FONTcolor="#0000BB">$adjstart </FONT><FONT color="#007700">+ (</FONT><FONT color="#0000BB">NDATAPOINTS</FONT><FONT color="#007700">+</FONT><FONT color="#0000BB">10</FONT><FONTcolor="#007700">)*</FONT><FONT color="#0000BB">10</FONT><FONT color="#007700">;<BR><BR></FONT><FONT color="#0000BB">$graph </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">Graph</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">500</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">250</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetMargin</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">40</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">20</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">30</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">50</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Now specify the X-scale explicit but let the Y-scale be auto-scaled<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetScale</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"intlin"</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$adjstart</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">$adjend</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"Example on TimeStamp Callback"</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Setup the callback and adjust the angle of the labels<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">xaxis</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetLabelFormatCallback</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'TimeCallback'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">xaxis</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetLabelAngle</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">90</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Set the labels every 5min (i.e. 300seconds) and minor ticks every minute<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">xaxis</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">ticks</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">300</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">60</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#0000BB">$line </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">LinePlot</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$data</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">$xdata</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$line</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'lightblue'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Add</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$line</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Stroke</FONT><FONT color="#007700">();<BR></FONT><FONT color="#0000BB">?><BR></FONT></FONT></CODE></DIV></P><H2><A NAME="7_11">7.11 Adjusting labels on a text scale</A></H2><P> In the following section we will work through an number of exampleson how to manipulate labels on a text scale. Primarily we willinvestigate how to best handle the case where you have a large numberof values.</P><P> As a remainder; Text scale is meant to be used on the X-axis whenthe X-axis doesn't have a numeric value, i.e you are only interested inlinear ordering of the data. If you don't specify the labels manuallythey will be set automatically starting from 1 as the example belowshows.</P><P><DIV class="example"><BR> <A href="exframes/frame_bartutex1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/bartutex1.png" WIDTH="300"></A><BR><B>Figure 83:</B> A simple bar plot using an automatic text scale <A href="exframes/frame_bartutex1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> To specify the labels on the X-axis as suitable text strings youcall the method <A href="../ref/Axis.html#_AXIS_SETTICKLABELS">Axis::SetTickLabels()</A> with an array containing the text-labels. Ifthere are more data points than labels the non-specified labels will begiven their ordinal number. If we augment the previous example with thename of the month we get the following new example</P><P><DIV class="example"><BR> <A href="exframes/frame_bartutex2.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/bartutex2.png" WIDTH="300"></A><BR><B>Figure 84:</B> Manually specifying the text scale labels <A href="exframes/frame_bartutex2.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P></P><HR> <SMALL><STRONG> Tip:</STRONG> To get hold of localized version ofthe month names (or weekdays) you can use the <A href="../ref/DateLocale.html#_C_DATELOCALE">DateLocal</A> class available in the global variable $gDateLocale If nolocale has been specified the default locale for the installation willbe used.</SMALL><HR><P> What happen now if we have a larger number of bars? Let's try with25 bars and see what result we get.</P><P><DIV class="example"><BR> <A href="exframes/frame_bartutex3.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/bartutex3.png" WIDTH="300"></A><BR><B>Figure 85:</B> A larger data set <A href="exframes/frame_bartutex3.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> Not all to impressive. The labels are to close and they overlap.Hence it is not a good idea to display every label. To adjust whatlabels are to be displayed you use the <A href="../ref/Axis.html#_AXIS_SETTEXTLABELINTERVAL">SetTextLabelInterval()</A> method. The argument to this method is theinterval between text labels. So to display only every 3 month youwould add the line</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">xaxis</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">SetTextLabelIntervall</FONT><FONTcolor="#007700">(</FONT><FONT color="#0000BB">3</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> Which would give the result shown below<DIV class="example"><BR> <A href="exframes/frame_bartutex4.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/bartutex4.png" WIDTH="300"></A><BR><B>Figure 86:</B> Displaying only every third label <A href="exframes/frame_bartutex4.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> Much better, quite readable.</P><P> If we have an even larger data set it might not longer be meaningfulto display all the tick marks since they would simple become to close.In JpGraph there is a possibility to specify that you only would likeevery<I> n</I>:th tick mark to be visible ( <A href="../ref/Axis.html#_AXIS_SETTEXTTICKINTERVAL">SetTextTickIntervall()</A> ). For bar graphs using text scale however,that might not be such a good idea since the tick marks are between thebars and the labels centered under the bars. If we only were todisplay, say, every 3 tick mark it wouldn't look to good. Not that wecan't do it, as the example below shows, but it just doesn't look verygood.<DIV class="example"><BR> <A href="exframes/frame_bartutex5.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/bartutex5.png" WIDTH="300"></A><BR><B>Figure 87:</B> Displaying just every third tick mark. <A href="exframes/frame_bartutex5.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> A better way to handle large data set is simply to hide the tickmarks all together. Tick marks may be hidden by calling the method <A href="../ref/Axis.html#_AXIS_HIDETICKS">Axis::HideTicks(); <A> If we hide all the ticks on the X-axis we willget the result shown below<DIV class="example"><BR> <A href="exframes/frame_bartutex6.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/bartutex6.png" WIDTH="300"></A><BR><B>Figure 88:</B> Hiding all tick mark. <A href="exframes/frame_bartutex6.html"target="blank">[src]</A> <P></P></DIV></A></A></P><P></P><H2><A NAME="7_12">7.12 Adding arbitrary text strings to the graph</A></H2><P> To add clarification or other information text strings to the graphyou can add arbitrary lines of text anywhere you like onto the graph.The text might have multiple lines and you can choose the paragraphalignment.</P><P> To add text you have to create one or more instances of the <A href="../ref/Text.html#_C_TEXT">Text()</A> object and then add the text object to the graph with the <A href="../ref/Graph.html#_GRAPH_ADDTEXT">AddText()</A> method.</P><P> The position of these text boxes are given as fraction of the widthand height of the graph. When you are positioning these text boxes youmight also choose what part of the text box should be considered theanchor point for the position you specify.</P><P> By default the anchor point is the upper left corner of the boundingbox for the text.</P><P> To show some ways of positioning the text we use a very simple bargraph not to distract from the text. We first just add a single textline with most of the settings their default value by adding thefollowing lines to the graph<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $txt</FONT><FONT color="#007700">=new </FONT><FONTcolor="#0000BB">Text</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"This is a text"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$txt</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Pos</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">$txt</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"red"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">AddText</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$txt</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The result is shown below.<DIV class="example"><BR> <A href="exframes/frame_example25.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example25.png" WIDTH="300"></A><BR><B>Figure 89:</B> Adding a single text string in the upper leftcorner <A href="exframes/frame_example25.html" target="blank">[src]</A> <P></P></DIV></P><P>Not too exiting. Let's make it more interesting by having abackground color, using larger fonts and framing the text box andadding a drop shadow to the text box by using the methods <A href="../ref/Text.html#_TEXT_SETBOX">SetBox()</A> and <A href="../ref/Text.html#_TEXT_SETSHADOW"> SetBox()</A><DIVclass="example"><BR> <A href="exframes/frame_example25.1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example25.1.png" WIDTH="300"></A><BR><B>Figure 90:</B> Making the text more interesting <A href="exframes/frame_example25.1.html"target="blank">[src]</A> <P></P></DIV></P><P> That's better. Now we get some attention. If you want to add a textwith several lines you just need to separate the lines with a newline('\n' character). The default paragraph alignment is left edge but youcan also use right and center alignment.</P><P> As an illustration let's add a couple of more lines to the previoustext, center the text box in the middle of the graph and also usecentered paragraph alignment for the text. To adjust the paragraphalignment of the text you have to use the <A href="../ref/Text.html#_TEXT_PARAGRAPHALIGN">Text::ParagraphAlign()</A><DIV class="example"><BR> <A href="exframes/frame_example25.2.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example25.2.png" WIDTH="300"></A><BR><B>Figure 91:</B> Text with multiple lines and centered paragraphalignment <A href="exframes/frame_example25.2.html" target="blank">[src]</A> <P></P></DIV></P><P> Of course there is no limit to the number of text string you can addto the graph.</P><P> From version 1.12 it is also possible to add text strings to a graphusing the scale coordinates instead. This is accomplished by using the <Ahref="../ref/Text.html#_TEXT_SETSCALEPOS"> Text::SetScalePos()</A> Whichis completely analog to SetPos() with the only difference that thepositions given are interpretated as scale values instead of fractionsof the width and height.</P><H2><A NAME="7_13">7.13 Adding titles and footers to the Graph</A></H2><P> Each graph can have up to three different titles accessed by thethree properties</P><OL><LI> title</LI><LI> subtitle</LI><LI> subsubtitle</LI></OL><P> All of these three properties is a standard text object which meansthat you can have individual font, colors, margins and sizes of thesetree titles.</P><P> The only thing you need to think of is that you probably want to addsome extra margin to make room for the titles (using <A href="../ref/Graph.html#_GRAPH_SETMARGIN">Graph::SetMargin()</A> )</P><P> The individual positioning of these titles are done automaticallyand will adjust to the font size being used.</P><P> If you for, esthetic reasons, would like increase the distance fromthe top where the title is positioned (or the intra distance betweentitle and sub title) you can use the <A href="../ref/Text.html#_TEXT_SETMARGIN">Text::SetMargin()</A> method. For example the line</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">title</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">SetMargin</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">20</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P>will set the distance between the top of the title string and the topof the graph to 20 pixels. If you instead call the SetMargin() methodfor the subtitle it will adjust the distance between the top of thesubtitle and the bottom of the title.</P><P> The titles will be positioned at the top and be centered in thegraph. Each of these titles may have multiple lines each separated by a"\n" (newline) character. By default the paragraph alignment for eachtitle is centered but may of course be changed (using theParagraphAlign()) method.</P><P> Each graph can also have a footer. This footer is actually threefooters. Left, center and right. The 'left' footer is aligned to theleft, the 'center' at the bottom center and the right to the right.</P><P> Each of these three positions is a standard Text object which meansyou can change color, font and size as you please individually on eachof these footer positions.</P><P> You access the footer through the Graph::footer property as thefollowing example shows</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">footer</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">left</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"(C) 2002 KXY"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">footer</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">center</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONTcolor="#007700">(</FONT><FONT color="#DD0000">"CONFIDENTIAL"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">footer</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">center</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"red"</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">footer</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">center</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">FF_FONT2</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FS_BOLD</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">footer</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">right</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONTcolor="#007700">(</FONT><FONT color="#DD0000">"19 Aug 2002"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P><DIV class="note"><B>Note:</B> If you enable the brand timingargument you should leave the left footer empty.</DIV></P><H2><A NAME="7_14">7.14 Adding a tab title</A></H2><P> A variant of the titles is the<I> tab title</I>. This is justanother option you have of putting a name on the graph. The appearanceof this type is a tab on top of the plot area with text inside.</P><P> You can access the tab using the 'tabtitle' property of the graph.</P><P> The following figure shows an example of how this can look.<DIV class="example"><BR> <A href="exframes/frame_tabtitleex1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/tabtitleex1.png" WIDTH="300"></A><BR><B>Figure 92:</B> Using the tabbed title style <A href="exframes/frame_tabtitleex1.html"target="blank">[src]</A> <P></P></DIV></P><P> As usual you have full freedom to specify font and colors for thistype of title. Please see the class reference regarding <A href="../ref/GraphTabTitle.html#_C_GRAPHTABTITLE">GraphTabTitle()</A> for more information.</P><H2><A NAME="7_15">7.15 Using background images</A></H2><P> Instead of having a single color background you can easily have anarbitrary image as the background. The image may be in either PNG, JPGor GIF format depending on what your installation supports.</P><P></P><HR> <SMALL><P><STRONG> A note on GD:</STRONG> If you are using GD 2.xx you mustmake sure that the define USE_TRUECOLOR is set to true. This is alsothe default. Failure to do so in combination with GD 2.xx will make thebackground image just look like a solid black square.</P></SMALL><HR><P> To use a specific image as the background you just have to use themethod <A href="../ref/Graph.html#_GRAPH_SETBACKGROUNDIMAGE">Graph::SetBackgroundImage()</A> The arguments specify file-name, howthe image should be positioned in the graph and finally the format ofthe image (if it is in JPG, PNG or GIF) format. If the format isspecified as "auto" (the default) then the appropriate image formatwill be determined from the extension of the image file.</P><P> The file name is of course obvious but the second argument might notbe. This arguments determine how the image should be copied onto thegraph image. You can specify three different variants here</P><OL><LI> BGIMG_ COPY This will just copy the image unchanged onto the graphfrom the top left corner.</LI><LI> BGIMG_CENTER This will just copy the image unchanged onto the graphbut it will center the image in the graph.</LI><LI> BGIMG_FILLFRAME This will scale the image to exactly fit the wholegraph image.</LI><LI> BGIMG_FILLPLOT This will scale the image to exactly fit just theplot area of the graph.</LI></OL><P></P><P></P><HR><STRONG> The following section only applies to palette based images.True color images can NOT be manipulated this way. Applying thefollowing sections to true-color images will have no affect.</STRONG><HR><P> You might often find yourself wanting to use a background image as a"waterstamp". This usually means taking the original image, import itto some image editing program and then "bleaching" the colorsaturation, reducing the contrast and so on. Finally you save themodified image which you then use as a background image.</P><P> This whole process can be automatically accomplished in JpGraph byusing the method <A href="../ref/Graph.html#_GRAPH_ADJBACKGROUNDIMAGE">Graph::AdjBackgroundImage()</A> which allow you to adjust colorsaturation, brightness and contrast of the background image.</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">AdjBackgroundImage</FONT><FONT color="#007700">(...)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> to achieve the "watercolor" effect to avoid the image being toointrusive in the graph.<DIV class="example"><BR> <A href="exframes/frame_backgroundex03.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/backgroundex03.png" WIDTH="400"></A><BR><B>Figure 93:</B> Example on using a watermark type background image<A href="exframes/frame_backgroundex03.html" target="blank">[src]</A> <P></P></DIV></P><P><DIV class="note"><B>Note:</B> The background image depicts a 1998Triumph Tiger. This bike is a 900cc off-road bike.</DIV></P><H2><A NAME="7_16">7.16 Using a background gradient</A></H2><P> In addition to the background image you can also add a backgroundcolor gradient. This gradient can be covering the entire graph, justthe plot area or just the margins. This flexibility allows you tocombine a background image with a background color gradient. You canfor example use a background image in the plot area and a colorgradient out in the margins.</P><P> You specify a color gradient background by calling the <A href="../ref/Graph.html#_GRAPH_SETBACKGROUNDGRADIENT">Graph::SetBackgroundGradient()</A> method. All details are available inthe class reference (follow the link above). We finally give a quickexample on what kind of effect you can achieve using this feature.<DIV class="example"><BR> <A href="exframes/frame_gradbkgex1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/gradbkgex1.png" WIDTH="300"></A><BR><B>Figure 94:</B> Using a background color gradient with theSetBackgroundGradient() method <A href="exframes/frame_gradbkgex1.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P> Finally we like to mention that in the "/utils/misc/" directory youwill find a small utility script called "mkgrad.php". Running thisscript presents you with a UI that makes it a breeze to create agradient image on it's own.</P><P> The UI for the utility is so obvious that we won't discuss itfurther, we just show it below. <IMG alt="The UI for the mkgrad.php utility"src="img/img/img/img/img/img/img/img/"><I> The UI for the mkgrad.php utility</I></P><P> In the example below this utility is used to get a more interestingplot area.</P><P><DIV class="example"><BR> <A href="exframes/frame_inyaxisex2.html" target="blank"><IMG border="0"HEIGHT="300" src="img/img/img/img/img/img/img/img/inyaxisex2.png" WIDTH="400"></A><BR><B>Figure 95:</B> Example of the use of a gradient background <A href="exframes/frame_inyaxisex2.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H2><A NAME="7_17">7.17 Using callbacks for Plot marks</A></H2><P> An interesting enhancement when using Plotmarks is the possibilityto add a callback function to control the size and color of theplotmarks.</P><P> This callback function will get called with the current Y-value (forthe plotmark) as it's argument. As return value the callback functionmust return an array containing three (possible null) values. Thevalues returned must be</P><OL><LI> Plot mark Weight</LI><LI> Plot mark Color</LI><LI> Plot mark Fill color</LI></OL><P> The exact meaning of the parameters will of course depend on thetype of plot marks being used.</P><P> The callback must be a global function and is installed with a callto <A href="../ref/PlotMark.html#_PLOTMARK_SETCALLBACK">PlotMark::SetCallback()</A></P><P> So for example to install a callback that changes the fill color forall marks with a (Y) value higher than 90 you could add the lines</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> </FONT><FONT color="#007700">function </FONT><FONT color="#0000BB">MarkCallback</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$aVal</FONT><FONT color="#007700">) {<BR> if( </FONT><FONT color="#0000BB">$aVal </FONT><FONT color="#007700">> </FONT><FONT color="#0000BB">90</FONT><FONT color="#007700">) <BR> </FONT><FONT color="#0000BB">$fcolor</FONT><FONT color="#007700">=</FONT><FONT color="#DD0000">"red"<BR> </FONT><FONT color="#007700">else<BR> </FONT><FONT color="#0000BB">$fcolor</FONT><FONT color="#007700">=</FONT><FONT color="#DD0000">""</FONT><FONT color="#007700">;<BR> return array(</FONT><FONT color="#DD0000">""</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">""</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">$fcolor</FONT><FONT color="#007700">);<BR>}<BR>...<BR></FONT><FONT color="#0000BB">$plot</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">mark</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetCallback</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"MarkCallback"</FONT><FONT color="#007700">);<BR>...</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> As you can see in the above example we have left some of the returnvalues blank. Doing this will just ignore any change of these value anduse the global settings for the plotmarks.</P><P> If you also let the (Y) value affect the size of the plot marks youcan get what is sometimes known as a "balloon plot". The example belowis basically a scatter plot that uses filled circles to mark thepoints. A format callback is then used to change the color and sizedepending on the Y-value for each plot.</P><P><DIV class="example"><BR> <A href="exframes/frame_balloonex1.html" target="blank"><IMG border="0"HEIGHT="300" src="img/img/img/img/img/img/img/img/balloonex1.png" WIDTH="400"></A><BR><B>Figure 96:</B> Creating a balloon plot by using plot markcallback function <A href="exframes/frame_balloonex1.html" target="blank">[src]</A> <P></P></DIV></P><P></P><H2><A NAME="7_18">7.18 Rotating graphs 90 degrees</A></H2><P> In section <A href="7adv.html#10_2">10.2</A> you can read aboutarbitrary rotation of the graphs. For most practical purposes rotationof 90 degrees is most useful. This could for example be used to plothorizontal bar graphs.</P><P> The slight complication with general rotation is that the marginsalso rotates, this means that if you rotate a graph 90 degrees the leftmargin in the image was originally the bottom margin. In additional bydefault the center of the rotation is the center of the plot area andnot the entire image (if all the margins are symmetrical then they willof course coincide). This means that depending on your margin thecenter of the rotation will move. You can read more about this and howto manually set the center for rotation in the section about rotation, <Ahref="7adv.html#10_2">10.2</A></P><P> This is just a slight inconvenience which you have to take intoaccount when you need to set an explicit margin with a call to <A href="../ref/Graph.html#_GRAPH_SETMARGIN">Graph::SetMargin()</A></P><P> However, in order to make a rotation of 90 degrees much easier youcan easily rotate a graph 90 degrees and set the correct margin with acall to <A href="../ref/Graph.html#_GRAPH_SET90ANDMARGIN">Graph::Set90AndMargin()</A> The parameter to this method lets youspecify the margins as you will see them in the image without having tothink of what becomes what after the rotation.</P><P> So, the only thing you need to do is call this method and then thegraph will have been rotated 90 degrees.</P><H2><A NAME="7_19">7.19 Formatting the axis</A></H2><P> To get the exact type of axis you want in your graph there are anumber of adjustments available for you. You may change, color, size,position and general appearance.</P><P></P><H3><A NAME="7_19_1">7.19.1 Standard two axis graphs</A></H3><P> Assuming we start with the traditional two axis graph, one X and oneY axis. You may then change the position of each axis by calling <A href="../ref/Axis.html#_AXIS_SETPOS">Axis::SetPos($aPosition)</A> You have to remember that you need tospecify the position on the other axis. SO you need to specify theworld-coordinate for the position. By default the axis are eachpositioned at the 0-point on the other axis, i.e. the axis will crossat the 0,0 point in the graph.</P><P> In addition to the standard positioning you may also use the twospecial position markers "min" and "max". This will position the axisat the minimum (or maximum) position of the other axis.</P><P> For example, to make sure that the X-axis is always at the bottom ofthe graph (at lowest possible Y-value) you would have to add the line</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">xaxis</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">SetPos</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"min"</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> To change the color and width of the axis you have to make use ofthe <A href="../ref/Axis.html#_AXIS_SETCOLOR"> Axis::SetColor()</A> and<A href="../ref/Axis.html#_AXIS_SETWEIGHT"> Axis::SetWeight()</A>methods.</P><HR> <SMALL><STRONG> Invisible axis</STRONG> Even though JpGraph (1.7)doesn't directly support "hidden" axis where the labels are still drawnit is very easy to achieve this effect by setting the colors of theaxis to be the same as the background. See the example barintex2.php inthe Example directory. To completely hide an axis you can make use ofthe <A href="../ref/Axis.html#_AXIS_HIDE"> Hide()</A></SMALL><HR><P> You might also want to add titles to the axis. This is done throughthe <A href="../ref/Axis.html#_AXIS_SETTITLE"> Axis::SetTitle()</A>method. This is actually just a shortcut for accessing the titleproperty direct. Axis::title::Set() which also allow you to set thealignment in one call.</P><P> By default the position of the title is to the far right for theX-axis and in the middle (and 90 degrees rotated) for the Y-axis.</P><P> You can adjust the position of the title with the help of the secondargument to the <A href="../ref/Axis.html#_AXIS_SETTITLE">Axis::SetTitle()</A> method.</P><P> The possible positions are "high","middle" and "low" which refers tothe scale values on the axis.</P><P> One common modification you might want to do to the title is toincrease the margin between the axis and the actual title. This isoften necessary to do for the Y-axis if the values displayed are large.You may adjust the distance (in pixels) between the axis and the titleby using the method <A href="../ref/Axis.html#_AXIS_SETTITLEMARGIN">Axis::SetTitleMargin()</A></P><P> So for example to increase the margin on the Y-axis you might addthe line</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">yaxis</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">SetTitleMargin</FONT><FONTcolor="#007700">(</FONT><FONT color="#0000BB">40</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> to your code.</P><P> Finally we mention something about the positioning of tick marks andlabels on the axis. You have the possibility to choose what side of theaxis the tick marks and the labels should be at. For the X-axis thiscan be specified as either on the the top (inside the plot area) or atbottom (outside of the plotarea). In the same way you can specify forthe Y-axis if the labels ( or ticks) should be on the left or rightside.</P><P> To adjust the label positioning you have to use the method <A href="../ref/Axis.html#_AXIS_SETTITLESIDE">Axis::SetTitleSide()</A> and to adjust the position of the tick markyou have to use the method <A href="../ref/Axis.html#_AXIS_SETTICKSIDE">SetTickSide()</A><DIV class="note"><B>Note:</B> There is also an aliasfor this method, SetTickDirection() which is deprecated from version1.7 but kept for backwards compatibility.</DIV> Valid arguments forthese methods are</P><UL><LI> SIDE_UP</LI><LI> SIDE_DOWN</LI><LI> SIDE_LEFT</LI><LI> SIDE_RIGHT</LI></UL><P> For example, the following lines added to a script would change sideof the labels and tickmarks for the X-axis.</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">xaxis</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">SetLabelPos</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">SIDE_UP</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">xaxis</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetTickSide</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">SIDE_DOWN</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> This technique is for example used if you position the X-axis at thetop of the graph as the following example shows.<DIV class="example"><BR> <A href="exframes/frame_topxaxisex1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/topxaxisex1.png" WIDTH="400"></A><BR><B>Figure 97:</B> Example of both how to adjust the position of theX-axis as well as adjusting the side for the tick and axis title <A href="exframes/frame_topxaxisex1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="7_19_2">7.19.2 Scientific style axis</A></H3><P> In scientific style plots it is often common to duplicate each axisso that all sides of the graph have a labeled axis. This is of coursealso fully supported by JpGraph.</P><P> Before we continue we show a small example to illustrate thisfeature</P><P><DIV class="example"><BR> <A href="exframes/frame_funcex1.html" target="blank"><IMG border="0"HEIGHT="350" src="img/img/img/img/img/img/img/img/funcex1.png" WIDTH="450"></A><BR><B>Figure 98:</B> Example of scientific axis <A href="exframes/frame_funcex1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> The example above shows the basic configuration. There are nowseveral modifications you may do to these axis like</P><UL><LI> Choose if the labels should be inside or outside the plot area</LI><LI> Choose if the tickmarks should be inside or outside the plot area</LI></UL><P> The style of axis is determined by the method <A href="../ref/Graph.html#_GRAPH_SETAXISSTYLE">Graph::SetAxisStyle()</A> The available type of axis are</P><UL><LI> AXSTYLE_SIMPLE, The standard two axis graph</LI><LI> AXSTYLE_BOXIN, Four axis scientific style with labels and tickmarkson the inside</LI><LI> AXSTYLE_BOXOUT, Four axis scientific style with labels andtickmarks on the outside</LI></UL><P></P><H3><A NAME="7_19_3">7.19.3 Adjusting the position of the scale labels</A></H3><P> How to adjust the actual labels are discussed elsewhere in thismanual (see ???,???). However we like to mention here that you canadjust the label margin (distance between the axis and the labels) withthe method <A href="../ref/Axis.html#_AXIS_SETLABELMARGIN">Axis::SetLabelMargin()</A></P><P> to adjust the actual label format (like font, color, angle) you needto access the <A href="../ref/Axis.html#_AXIS_SETFONT"> Axis::SetFont()</A>and the <A href="../ref/Axis.html#_AXIS_SETCOLOR"> Axis::SetColor()</A>methods. If you investigate the <A href="../ref/Axis.html#_C_AXIS">Axis</A> class you will discover more methods to adjust the manyaspects of the axis layout.</P><P> As a final note we also mention the methods <A href="../ref/Axis.html#_AXIS_SETLABELALIGN">Axis::SetLabelAlign()</A> and <A href="../ref/Axis.html#_AXIS_SETLABELANGLE">Axis::SetLabelAngle()</A> This first method is really only mentionedhere for completeness since it is mostly used for internal purposes.However on some occasion you might want to adjust the alignment of thelabels. By default they are centered in respect to the tick mark. Byusing the method you might override this positioning should you chooseto do so.</P><P> The second of these methods adjusts the angle of the label inregards to the axis. This is very useful for X-axis that have longlabels.</P><H3><A NAME="7_19_4">7.19.4 Formatting the scale labels</A></H3><P> In order to have full control over the way that the labels aredisplayed it is possible to define a callback function that will beapplied to all labels. The callback function will be called with thelabel as the only argument and should return the value that will bedisplayed in the graph. This could for example be used to turn seconds(used to position data points) into hour and minutes on the scale. Forfurther reference see the two methods: <A href="../ref/Axis.html#_AXIS_SETLABELFORMATCALLBACK">Graph::SetLabelFormatCallback();</A> and <A href="../ref/Axis.html#_AXIS_SETLABELFORMAT">Graph::SetLabelFormat();</A></P><H3><A NAME="7_19_5">7.19.5 Inverting the Y-axis</A></H3><P> One good way of illustrate the usefulness of label callbacks in aslightly different context is to show how we can achieve the effect ofan inverted Y-scale.</P><P> An inverted Y-scale has the lowest number at the top and the scalevalues increases downwards.</P><P> Even though JpGraph doesn't directly support this feature it isquite easy to achieve with just a few extra lines of code in your imagescript.</P><P> Before we continue we give an example of what we are referring to.</P><P><DIV class="example"><BR> <A href="exframes/frame_inyaxisex2.html" target="blank"><IMG border="0"HEIGHT="300" src="img/img/img/img/img/img/img/img/inyaxisex2.png" WIDTH="400"></A><BR><B>Figure 99:</B> Inverted Y-axis <A href="exframes/frame_inyaxisex2.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> Two achieve this effect there are two simple steps to take:</P><OL><LI> Negate all you Y-value in the data</LI><LI> Create a callback that negates the scale labels so they appear tobe positive.</LI></OL><P> And that's it! We refer you to the code in the example above for thedetails.</P><H2><A NAME="7_20">7.20 Adjusting the auto-scaling limits - grace value</A></H2><P> By default the auto-scaling algorithm tries to make best possibleuse of screen estate by making the scale as large as possible, i.e. theextreme values (min/max) will be on the top and bottom of the scale ifthey happen to fall on a scale-tick. So for example doing a simple lineplot could look like the plot shown in the below.<DIV class="example"><BR> <A href="exframes/frame_example3.2.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example3.2.png" WIDTH="300"></A><BR><B>Figure 100:</B> A typical graph with autoscaling and grace=0 <A href="exframes/frame_example3.2.html"target="blank">[src]</A> <P></P></DIV></P><P> However you might sometime want to add some extra to the minimum andmaximum values so that there is some "air" in the graph between the endof the scale values and the extreme points in the graphs. This can bedone by adding a "grace" percentage to the scale. So for example adding10% to the y-scale in the image above is done by calling the <A href="../ref/LinearScale.html#_LINEARSCALE_SETGRACE">SetGrace()</A> method on the yscale as in</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">yaxis</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetGrace</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">10</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">10</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> These lines add a minimum of 10% to the top and bottom values of thescale. Note that we say "minimum" since depending on the specific tickvalues choose this might be a little bit more to make the end of thescale fall on an even tick mark.</P><P> Adding this line to the previous graph will result in the followingexample</P><P><DIV class="example"><BR> <A href="exframes/frame_example3.2.1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example3.2.1.png" WIDTH="300"></A><BR><B>Figure 101:</B> Adding 10% grace value to top and bottom of theY-scale <A href="exframes/frame_example3.2.1.html" target="blank">[src]</A> <P></P></DIV></P><P> Since we haven't adjusted the position of the X-axis it will remainat Y=0 which might not necessary be what we would like so we thereforalso add the line</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">xaxis</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">SetPos</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"min"</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> So that the X-axis always will remain at the lowest possibleY-value. Doing this will then result in the example below</P><P><DIV class="example"><BR> <A href="exframes/frame_example3.2.2.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example3.2.2.png" WIDTH="300"></A><BR><B>Figure 102:</B> Using grace but also adjusting the position ofthe X-axis <A href="exframes/frame_example3.2.2.html" target="blank">[src]</A> <P></P></DIV></P><P></P><H2><A NAME="7_21">7.21 Adding bands of pattern and color to graphs</A></H2><P> As an additional way of emphasizing certain areas of the graph it ispossible to add bands (either vertical or horizontal) to any one of thestandard X-Y coordinate system based graphs. A band is a rectangulararea that stretches one entire axis. This means that if you define aband between X-coordinates 3 and 5 the band area will occupy an areabetween the X-coordinates and the entire Y-range.</P><P> In order to access this functionality you must first make sure thatyou include the additional library file<I> jpgraph_plotband.php</I></P><P> At the time of this writing (current as of JpGraph 1.8) the tablebelow illustrates the 8 basic types of patterns available. We willshortly show you how you can customize these patterns, To keep theseexamples clear we have only used one pattern in each figure.</P><P></P><TABLE style="margin-left:-4em;"><TR><TD><DIV class="example"><BR> <A href="exframes/frame_smallstaticbandsex1.html" target="blank"><IMGborder="0" HEIGHT="150" src="img/img/img/img/img/img/img/img/smallstaticbandsex1.png" WIDTH="200"></A><BR><B>Figure 103:</B> <A href="exframes/frame_smallstaticbandsex1.html" target="blank">[src]</A> <P></P></DIV><P></P></TD><TD><DIV class="example"><BR> <A href="exframes/frame_smallstaticbandsex2.html" target="blank"><IMGborder="0" HEIGHT="150" src="img/img/img/img/img/img/img/img/smallstaticbandsex2.png" WIDTH="200"></A><BR><B>Figure 104:</B> <A href="exframes/frame_smallstaticbandsex2.html" target="blank">[src]</A> <P></P></DIV><P></P></TD></TR><TR><TD><DIV class="example"><BR> <A href="exframes/frame_smallstaticbandsex7.html" target="blank"><IMGborder="0" HEIGHT="150" src="img/img/img/img/img/img/img/img/smallstaticbandsex7.png" WIDTH="200"></A><BR><B>Figure 105:</B> <A href="exframes/frame_smallstaticbandsex7.html" target="blank">[src]</A> <P></P></DIV><P></P></TD><TD><DIV class="example"><BR> <A href="exframes/frame_smallstaticbandsex6.html" target="blank"><IMGborder="0" HEIGHT="150" src="img/img/img/img/img/img/img/img/smallstaticbandsex6.png" WIDTH="200"></A><BR><B>Figure 106:</B> <A href="exframes/frame_smallstaticbandsex6.html" target="blank">[src]</A> <P></P></DIV><P></P></TD></TR><TR><TD><DIV class="example"><BR> <A href="exframes/frame_smallstaticbandsex9.html" target="blank"><IMGborder="0" HEIGHT="150" src="img/img/img/img/img/img/img/img/smallstaticbandsex9.png" WIDTH="200"></A><BR><B>Figure 107:</B> <A href="exframes/frame_smallstaticbandsex9.html" target="blank">[src]</A> <P></P></DIV><P></P></TD><TD><DIV class="example"><BR> <A href="exframes/frame_smallstaticbandsex10.html" target="blank"><IMGborder="0" HEIGHT="150" src="img/img/img/img/img/img/img/img/smallstaticbandsex10.png" WIDTH="200"></A><BR><B>Figure 108:</B> <A href="exframes/frame_smallstaticbandsex10.html"target="blank">[src]</A> <P></P></DIV><P></P></TD></TR><TR><TD><DIV class="example"><BR> <A href="exframes/frame_smallstaticbandsex3.html" target="blank"><IMGborder="0" HEIGHT="150" src="img/img/img/img/img/img/img/img/smallstaticbandsex3.png" WIDTH="200"></A><BR><B>Figure 109:</B> <A href="exframes/frame_smallstaticbandsex3.html" target="blank">[src]</A> <P></P></DIV><P></P></TD><TD><DIV class="example"><BR> <A href="exframes/frame_smallstaticbandsex8.html" target="blank"><IMGborder="0" HEIGHT="150" src="img/img/img/img/img/img/img/img/smallstaticbandsex8.png" WIDTH="200"></A><BR><B>Figure 110:</B> <A href="exframes/frame_smallstaticbandsex8.html" target="blank">[src]</A> <P></P></DIV><P></P></TD></TR></TABLE><P> To add a one of these patterns to your graph you need to call themethod <A href="../ref/PlotBand.html#_PLOTBAND_PLOTBAND">PlotBand::PlotBand()</A> The arguments is fairly easy to understand.The pattern you would like to use is specified by using the correctconstant. You can see the name of the correct constants in the figuresabove. You also need to specify if the band should stretch along thevertical or horizontal axis as well as the min and max coordinates forthe band. As coordinates you may also use the special values "min" and"max" which automatically sets the value to the minimum/maximum valueof the scale. The specified numeric value will be automaticallytruncated to fit within the plot area.</P><P> We don't discuss the other arguments further here, instead we referyou to the class reference.</P><H3><A NAME="7_21_1">7.21.1 Customizing the patterns</A></H3><P> All patterns can be customized by</P><UL><LI> ... altering the colors of the band<BR> </LI><LI> ... altering the density of the patterns using the method <A href="../ref/PlotBand.html#_PLOTBAND_SETDENSITY">PlotBand::SetDensity()</A> The density is specified as an integer inrange 1 to 100 where a higher number means a higher density (smallerdistance between the lines). For example setting the density of the 3Dplane above to 60 gives the result<DIV class="example"><BR> <A href="exframes/frame_smallstaticbandsex4.html" target="blank"><IMGborder="0" HEIGHT="150" src="img/img/img/img/img/img/img/img/smallstaticbandsex4.png" WIDTH="200"></A><BR><B>Figure 111:</B> Increasing the desnity in a pattern <A href="exframes/frame_smallstaticbandsex4.html"target="blank">[src]</A> <P></P></DIV><P><BR> </P></LI><LI> ... enabling or disabling a frame around the pattern by using themethod <A href="../ref/PlotBand.html#_PLOTBAND_SHOWFRAME">PlotBand::ShowFrame()</A> The band will be given the same color as theband.<BR> </LI><LI> ... finally you can change whether the band should be drawn on topof the plots or beneath, (by default the bands are under the plots),using the <A href="../ref/PlotBand.html#_PLOTBAND_SETORDER">PlotBand::SetOrder()</A> as the following example show<DIV class="example"><BR> <A href="exframes/frame_smallstaticbandsex5.html" target="blank"><IMGborder="0" HEIGHT="150" src="img/img/img/img/img/img/img/img/smallstaticbandsex5.png" WIDTH="200"></A><BR><B>Figure 112:</B> Stroking the pattern on top of the plots <A href="exframes/frame_smallstaticbandsex5.html"target="blank">[src]</A> <P></P></DIV><P></P></LI></UL><P><DIV class="note"><B>Note:</B> 3D planes actually carry anotherpossible modification. You can specify the vanish point to change theperspective used. You can't access the method to change the horizondirectly but you can access it through</DIV><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $band</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">prect</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetHorizon</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$aHorizon</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P><SMALL> assuming that the band is a 3D plane.</SMALL></P><P> To finish this section we give one final, more creative, example onhow to use the bands.<DIV class="example"><BR> <A href="exframes/frame_staticbandbarex7.html" target="blank"><IMG border="0"HEIGHT="300" src="img/img/img/img/img/img/img/img/staticbandbarex7.png" WIDTH="400"></A><BR><B>Figure 113:</B> Combining 3D plane, solid band and a sttaic line <Ahref="exframes/frame_staticbandbarex7.html" target="blank">[src]</A> <P></P></DIV></P><P></P><H2><A NAME="7_22">7.22 Adding static lines to the plot</A></H2><P> In addition to the bands you can also add static lines to the graph.An example of that is actually shown in figure 11 above. You create aline as an instance of <A href="../ref/PlotLine.html#_C_PLOTLINE">class PlotLine</A> . So for example the lines<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $sline </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">PlotLine</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">HORIZONTAL</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"black"</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">2</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Add</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$sline</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> will add a 2-pixel wide horizontal static line at Y-position zero.</P><H1><A NAME="8">8 Working with non X,Y-plots</A></H1><P> Non X,Y plots includes</P><UL><LI> Pie plots (2D and 3D)</LI><LI> Radar plots</LI><LI> Polar plots</LI><LI> Gantt charts</LI></UL><P> The fundamental difference is that these classes makes use of anextended version of the basic Graph class. Therefor you can not mix X,Yplots with non-X,Y plots. For example it is not possible to mix a linegraph with a Polar graph.</P><UL><LI> To create 2d or 3d pie plots you must use the PieGraph class</LI><LI> To create radar plots you must use the RadarGraph() class</LI><LI> To create radar plots you must use the PolarGraph() class</LI><LI> To create gantt plots you must use the GanttGraph() class</LI></UL><P></P><H2><A NAME="8_1">8.1 Radar plots</A></H2><P> Spider plots are most often used to display how a number of resultscompare to some set targets. They make good use of the human ability tospot symmetry (or rather un-symmetry) . the figure below show anexample of a spider (sometimes called a web-plot). Spiderplots are notsuitable if you want very accurate readings from the graph since, byit's nature, it can be difficult to read out very detailed values.<DIV class="example"><BR> <A href="exframes/frame_radarex7.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/radarex7.png" WIDTH="300"></A><BR><B>Figure 114:</B> A typical radar graph with two plots <A href="exframes/frame_radarex7.html"target="blank">[src]</A> <P></P></DIV></P><P></P><UL><LI>There is one axis for each data point</LI><LI>Each axis may have an arbitrary title which is automaticallypositioned</LI><LI>A spider plot may be filled or open</LI><LI>You can control color, weight of lines as you are already used to</LI><LI>A spider plot can, as usual, have a title and a legend</LI><LI>The first axis is always oriented vertical and is the only axis withlabels</LI><LI>Grids may be used (dashed in the figure above)</LI><LI>You may have ticks (although suppressed in the figure above</LI><LI>You can control the size and position within the frame of the graph</LI><LI>You may have several plots within the same graph</LI></UL><P> In the following section we show how to draw both simple and complexradar graph. As we will show all the settings will follow the samepattern as for the more standard linear graphs.</P><H3><A NAME="8_1_1">8.1.1 Simple radar plots</A></H3><P> Let's start by creating a very simple radar plot based on 5 datapoints using mostly default values.</P><P> As the first thing you must remember to include the extension modulethat contains the radar plot. "jpgraph_radar.php".</P><P> A very simple radar plot is created by the code<DIV class="phpscript">(File: radarex1.php)<BR><CODE><FONT color="#000000"> <FONT color="#0000BB"><?php<BR></FONT><FONT color="#007700">include (</FONT><FONT color="#DD0000">"../jpgraph.php"</FONT><FONT color="#007700">);<BR>include (</FONT><FONT color="#DD0000">"../jpgraph_radar.php"</FONT><FONTcolor="#007700">);<BR> <BR></FONT><FONT color="#FF8000">// Some data to plot<BR></FONT><FONT color="#0000BB">$data </FONT><FONT color="#007700">= array(</FONT><FONT color="#0000BB">55</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">80</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">46</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">71</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">95</FONT><FONT color="#007700">);<BR> <BR></FONT><FONT color="#FF8000">// Create the graph and the plot<BR></FONT><FONT color="#0000BB">$graph </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">RadarGraph</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">250</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">200</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"auto"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$plot </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">RadarPlot</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$data</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Add the plot and display the graph<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Add</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$plot</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Stroke</FONT><FONT color="#007700">();<BR></FONT><FONT color="#0000BB">?></FONT></FONT></CODE></DIV></P><P> and would give the result<DIV class="example"><BR> <A href="exframes/frame_radarex1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/radarex1.png" WIDTH="250"></A><BR><B>Figure 115:</B> A first very simple radar plot using defaultsettings <A href="exframes/frame_radarex1.html" target="blank">[src]</A> <P></P></DIV></P><P> To change the size and position of the radar graph is similar to thepie plot and you do it by using the methods <A href="../ref/SpiderGraph.html#_SPIDERGRAPH_SETSIZE">SetSize()</A> and <A href="../ref/SpiderGraph.html#_SPIDERGRAPH_SETCENTER">SetCenter()</A></P><P> If you want a filled radar plot you need to specify the fill colorwith the method <A href="../ref/SpiderPlot.html#_SPIDERPLOT_SETFILLCOLOR">SetFillColor()</A> The following example shows these methods in action<DIVclass="example"><BR> <A href="exframes/frame_radarex2.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/radarex2.png" WIDTH="300"></A><BR><B>Figure 116:</B> Changing size, position and adding fill color tothe radar plot. <A href="exframes/frame_radarex2.html" target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="8_1_2">8.1.2 Specifying titles for the axis and legends forthe plots</A></H3><P> We normally would like something more meaningful as description ofeach axis than it's number. Specifying the titles are accomplishedthrough the use of the method SetTitles() of the graph. Let's say thateach axis corresponds to a month. We could then use the code<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $titles </FONT><FONT color="#007700">= </FONT><FONT color="#0000BB">$gDateLocale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">GetShortMonth</FONT><FONT color="#007700">();<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetTitles</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$titles</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> As you can see the way radar plot is constructed will assign thetitles (and plot points) in a counter-clockwise direction. If you wantthem in clock-wise order you will have to inverse your input data arrayas well as the title array.</P><P> To specify a legend you (as with the other plot) make use of the <A href="../ref/SpiderPlot.html#_SPIDERPLOT_SETLEGEND">SetLegend();</A> method on each radar plot.</P><H3><A NAME="8_1_3">8.1.3 Adding grid line to the radar plot</A></H3><P> Each major tick mark can also be connected together to create agrid. The grid is accessed through the 'grid' property of the graph. Toenable the grid and set the line style to "dotted" you would have toadd the lines<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">grid</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">Show</FONT><FONT color="#007700">();<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">grid</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetLineStyle</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"dotted"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P>and would result in the following graph<DIV class="example"><BR> <A href="exframes/frame_radarex4.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/radarex4.png" WIDTH="250"></A><BR><B>Figure 117:</B> Adding dotted gridlines to the graph <A href="exframes/frame_radarex4.html"target="blank">[src]</A> <P></P></DIV></P><P>By design the plot is above the grid line but beneath the axis inimage depth, hence some part of the grid lines are hidden.</P><P> To have the grid lines more "visible" just change their color, sayto, dark red by invoking the SetColor() method on the grid lines whichwould give the following result</P><P> Another simple change we could do would be to just change thebackground color of the radar graph. This is (not surprisingly) done bya call to the method SetColor() invoked on the graph object.<DIV class="example"><BR> <A href="exframes/frame_radarex6.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/radarex6.png" WIDTH="250"></A><BR><B>Figure 118:</B> Changing the background color <A href="exframes/frame_radarex6.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="8_1_4">8.1.4 Adding several plots to the same radar graph</A></H3><P> You can easily create several radar plot which are added to the sameradar graph. The thing to remember is that if you use filled radarplots and they overlap each other that the order which they are addedwill be the order they are drawn.</P><P> A simple example of this is shown below<DIV class="example"><BR> <A href="exframes/frame_radarex6.1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/radarex6.1.png" WIDTH="250"></A><BR><B>Figure 119:</B> Several radar plots in one radar graph <A href="exframes/frame_radarex6.1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="8_1_5">8.1.5 Adding plotmarks i radar graphs</A></H3><P> In exactly the same way as for line graphs it is possible to addplot marks in radar plots. The mark property is accessed through the<I>RadarPlot::mark</I> The example below adds a red ball as a marker.<DIV class="example"><BR> <A href="exframes/frame_radarmarkex1.html" target="blank"><IMG border="0"HEIGHT="280" src="img/img/img/img/img/img/img/img/radarmarkex1.png" WIDTH="300"></A><BR><B>Figure 120:</B> Adding plotmarks to a radar plot <A href="exframes/frame_radarmarkex1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H2><A NAME="8_2">8.2 Pie plots</A></H2><P> So far we have just show plots based on an X-Y coordinate system.This is not the only types of graphs you can create with JpGraph.Another common type is Pie plots. JpGraph supports both 2D and 3D pieplots. For 2D pie plots there are also 2 versions, but more on thatlater.</P><P> The main difference as compared to the X-Y plots is that to all pieplots are added to the <A href="../ref/PieGraph.html#_C_PIEGRAPH">PieGraph()</A> instead of the Graph() object we used for the X-Y graphswe have drawn so far. For this you must first include the"jpgraph_pie.php" in your script (or "jpgraph_pie3d.php" if you want touse 3-dimensional pies).</P><P> Below you cane see the code needed to create the simplest possiblepie graph just using the default settings.</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> </FONT><FONT color="#007700">include (</FONT><FONT color="#DD0000">"../jpgraph.php"</FONT><FONT color="#007700">);<BR>include (</FONT><FONT color="#DD0000">"../jpgraph_pie.php"</FONT><FONTcolor="#007700">);<BR><BR></FONT><FONT color="#0000BB">$data </FONT><FONT color="#007700">= array(</FONT><FONT color="#0000BB">40</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">60</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">21</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">33</FONT><FONTcolor="#007700">);<BR><BR></FONT><FONT color="#0000BB">$graph </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">PieGraph</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">300</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">200</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetShadow</FONT><FONT color="#007700">();<BR><BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"A simple Pie plot"</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#0000BB">$p1 </FONT><FONT color="#007700">= new </FONT><FONTcolor="#0000BB">PiePlot</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$data</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Add</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$p1</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Stroke</FONT><FONT color="#007700">();<BR></FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The above code would give the following pie graph<DIV class="example"><BR> <A href="exframes/frame_example26.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example26.png" WIDTH="300"></A><BR><B>Figure 121:</B> The simplest possible pie graph <A href="exframes/frame_example26.html"target="blank">[src]</A> <P></P></DIV></P><P> There is a few things worth noting here</P><UL><LI> By default all pie slices have the percentage shown just outsidethe slice.</LI><LI> The colors are automatically assigned to the slices.</LI><LI> The pie have the edges marked by default</LI><LI> The first slice start at 0 degrees (3 o'clock)</LI></UL><P> You can change almost all aspects of appearance of the pie graphs.For example you could change :</P><UL><LI> Change the angle for the first slice, (<A href="../ref/PiePlot.html#_PIEPLOT_SETSTARTANGLE">PiePlot::SetStartAngle()</A>)</LI><LI>Remove the border lines around the pie (<A href="../ref/PiePlot.html#_PIEPLOT_SHOWBORDER">PiePlot::ShowBorder()</A>)</LI><LI>Change the color of the border (<A href="../ref/PiePlot.html#_PIEPLOT_SETCOLOR">PiePlot::SetColor()</A>,</LI><LI>Change the colors of the slices (<A href="../ref/PiePlot.html#_PIEPLOT_SETSLICECOLORS">PiePlot::SetSliceCOlors()</A>)</LI><LI> Change the size and position of the pie (<A href="../ref/PiePlot.html#_PIEPLOT_SETSIZE">PiePlot::SetSize()</A>, <A href="../ref/PiePlot.html#_PIEPLOT_SETCENTER">PiePlot::SetCenter()</A>)</LI><LI> Adjust the labels for the slice (color, font, format, position ) byaccessing the <A href="../ref/DisplayValue.html#_C_DISPLAYVALUE">valueproperty</A> of pie plots, for example (<A href="../ref/DisplayValue.html#_DISPLAYVALUE_SETFONT">PiePlot::value::SetFont()</A>, You can read more about label formattingand how to change what is displayed as a value further down in thischapter.</LI></UL><P></P><P> The next simplest addition we can do is to add a legend to the piegraph. We do this by using the <A href="../ref/PiePlot.html#_PIEPLOT_SETLEGENDS">SetLegends();</A> method. By adding the legends to the previous examplewe get the following image<DIV class="example"><BR> <A href="exframes/frame_example26.1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example26.1.png" WIDTH="300"></A><BR><B>Figure 122:</B> Adding a legend to the pie graph <A href="exframes/frame_example26.1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> (In the figure above we also moved the center of the pie slightly tothe left to make more room for the legend box.)</P><P> The text for the legends can also contain printf() style formatstrings to format a number. This number passed on into this string iseither the absolute value of the slice or the percentage value. How toswitch between the is describe further down in this chapter.</P><P> The next change you might want to change is the size and position ofthe Pie plot. You can change the size with a call to <A href="../ref/PiePlot.html#_PIEPLOT_SETSIZE">SetSize();</A> and the position of the center of the pie plot with acall to <A href="../ref/PiePlot.html#_PIEPLOT_SETCENTER"> SetCenter();</A>The size can be specified as either an absolute size in pixels or as afraction of width/height (whatever is the smallest). The position ofthe pie plot is specified as a fraction of the width and height.</P><P> To put the size and positioning API to use we will show how to putseveral pie plots on the same pie graph. In the following example wehave also adjusted the legends of the slice values to use a smallerfont.</P><P> What we do in this example is quite simple, create 4 pie plots, makethem smaller and put them in the four corner of the graph. This willgive the result as shown in the following example.<DIV class="example"><BR> <A href="exframes/frame_pieex3.html" target="blank"><IMG border="0" HEIGHT="300"src="img/img/img/img/img/img/img/img/pieex3.png" WIDTH="350"></A><BR><B>Figure 123:</B> Multiple pie plots in the same pie graph <A href="exframes/frame_pieex3.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="8_2_1">8.2.1 Adding guide lines to Pie Plots</A></H3><P> For very busy Pie plots it can become too little space for thelabels to be printed just beside the pie slice. For this purpose it ispossible to use guide lines for the labels. The library will then drawa line from the center edge of the slices to the label which will bepositioned further out from the Pie Plot.</P><P> There is one method that is primarily used to handle this,<I>PiePlot::SetGuideLines()</I> the simplest usage of this would be<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $pieplot</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetGuideLines</FONT><FONT color="#007700">();</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> An example of this could then be<DIV class="example"><BR> <A href="exframes/frame_pielabelsex1.html" target="blank"><IMG border="0"HEIGHT="350" src="img/img/img/img/img/img/img/img/pielabelsex1.png" WIDTH="300"></A><BR><B>Figure 124:</B> Using guide lines for PiePlots <A href="exframes/frame_pielabelsex1.html"target="blank">[src]</A> <P></P></DIV></P><P> The above example will give guide lines very similar as what isproduced by other programs, e.g. Excel. In addition to the abovevariant it is also possible to instruct the library to line up thelabels vertically in a way that we think is easier to read. This isachieved by specifying the second parameter to the SetGuideLines() to<I>'false'</I> as in<DIV class="phpscript"><CODE><FONT color="#000000"> <FONTcolor="#0000BB"> $pieplot</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetGuideLines</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">true</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">false</FONT><FONTcolor="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The first parameter is to enable/disable the guide-lines. With thesame example as above this would then produce the image<DIV class="example"><BR> <A href="exframes/frame_pielabelsex2.html" target="blank"><IMG border="0"HEIGHT="350" src="img/img/img/img/img/img/img/img/pielabelsex2.png" WIDTH="300"></A><BR><B>Figure 125:</B> Using guide lines for PiePlots with verticallylined up labels. <A href="exframes/frame_pielabelsex2.html" target="blank">[src]</A> <P></P></DIV></P><P> It is also possible to configure the vertical distance between thelabels. By default the distance between the labels is roughly 40% ofthe labels font height. By using the method<I>PiePlot::SetGuideLinesAdjust()</I> it is possible to specify afractional value which is interpretated as the distance between thebottom of one label to the bottom of the next. This means thatspecifying a value of '1.0' the labels will have no space between themand the bottom of one label will touch the top of another label. Bydefault this value is 1.4.</P><P> By increasing or decreasing this value it is possible to make thelabels become positioned more or less compact. Below we have taken theabove example and reduced the distance to '1.1' and as can be seen thisyields much more compact labeling.<DIV class="example"><BR> <A href="exframes/frame_pielabelsex4.html" target="blank"><IMG border="0"HEIGHT="350" src="img/img/img/img/img/img/img/img/pielabelsex4.png" WIDTH="300"></A><BR><B>Figure 126:</B> Adjusting to a smaller vertical distance betweenthe labels <A href="exframes/frame_pielabelsex4.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P><B> Note:</B> Guide lines is only available in 2D Pie plots.</P><H3><A NAME="8_2_2">8.2.2 Creating 3D pie plots</A></H3><P> So far we have only made use of 2D pie plots, creating 3D pie plotsis no more difficult. Instead of creating the plots with a call toPiePlot() you create the plots with a call to <A href="../ref/PiePlot3D.html#_C_PIEPLOT3D">PiePlot3D()</A> If we just take the first simple pie plot and replacethe call to PiePlot() with a call to PiePlot3D() we get the followingresult.<DIV class="example"><BR> <A href="exframes/frame_example27.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example27.png" WIDTH="300"></A><BR><B>Figure 127:</B> A first example of a 3D pie plot <A href="exframes/frame_example27.html"target="blank">[src]</A> <P></P></DIV></P><P> 3D Pie plots have the same possibilities as the normal pie plotswith the added twist of a 3:rd dimension. You can adjust theperspective angle with the method <A href="../ref/PiePlot3D.html#_PIEPLOT3D_SETANGLE">SetAngle()</A> So for example to make the pie more "flat" you just setit to a smaller angle. Setting the perspective angle to 20 degrees inthe previous example will give the following result.<DIV class="example"><BR> <A href="exframes/frame_example27.1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example27.1.png" WIDTH="300"></A><BR><B>Figure 128:</B> Adjusting the perspective angle <A href="exframes/frame_example27.1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="8_2_3">8.2.3 Exploding pie slices</A></H3><P> One way to attract attention to some specific piece of informationin a pie chart is to "explode" one or more slices. Both 2D and 3D piessupport exploding one or several slices.</P><P> Exploding slices is accomplished by the methods <A href="../ref/PiePlot.html#_PIEPLOT_EXPLODE">Explode()</A> and <A href="../ref/PiePlot.html#_PIEPLOT_EXPLODESLICE">ExplodeSlice()</A> The first method is used if you want to explode morethan one slices and the second is a shorthand to make it easy to justexplode one slice.</P><P> For example to explode one slice the default "explode" radius youwould just have to say<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $pieplot</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">ExplodeSlice</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">1</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The above line would explode the second slice (slices are numberedfrom 0 and upwards) the default amount. Doing this to the two previousexample would result in<DIV class="example"><BR> <A href="exframes/frame_example27.2.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example27.2.png" WIDTH="300"></A><BR><B>Figure 129:</B> Exploding one slice <A href="exframes/frame_example27.2.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P><DIV class="example"><BR> <A href="exframes/frame_example27.3.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example27.3.png" WIDTH="330"></A><BR><B>Figure 130:</B> Exploding one 3D slice <A href="exframes/frame_example27.3.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> To explode all slices at once you can use the <A href="../ref/PiePlot.html#_PIEPLOT_EXPLODEALL">PiePlot::ExplodeAll()</A> method. If you want to explode several slicesyou can use the <A href="../ref/PiePlot.html#_PIEPLOT_EXPLODE">PiePlot::Explode()</A> method and supply a suitable array argument.</P><H3><A NAME="8_2_4">8.2.4 Specifying and adjusting labels on pie plots</A></H3><P> By default the values shown just outside the pie for each slice arethe percentage value for each slice. If you instead wanted the absolutevalue you would just have to use the <A href="../ref/PiePlot.html#_PIEPLOT_SETLABELTYPE">SetLabelType()</A> method. So to use the absolute value you would call</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $pieplot</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetLabelType</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"PIE_VALUE_ABS"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> Furthermore you could enhance the formatting of the value by eitherusing a printf() style format string (using <A href="../ref/DisplayValue.html#_DISPLAYVALUE_SETFORMAT">SetFormat()</A> ) or by providing a formatting function callback (using<A href="../ref/DisplayValue.html#_DISPLAYVALUE_SETFORMATCALLBACK">SetFormatCallback()</A> ) for doing more advanced formatting.</P><P> You can also adjust the position of the labels by means of the <A href="../ref/PiePlot.html#_PIEPLOT_SETLABELPOS">PiePlot::SetLabelPos()</A> method. The argument to this method iseither the fraction of the radius or the string 'auto'. In the lattercase JpGraph automatically determines the best position and the thefirst case The following example illustrates this<DIV class="example"><BR> <A href="exframes/frame_pieex8.html" target="blank"><IMG border="0" HEIGHT="200"src="img/img/img/img/img/img/img/img/pieex8.png" WIDTH="250"></A><BR><B>Figure 131:</B> Example of adjusting the position of the labelsfor the slices <A href="exframes/frame_pieex8.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P> If this formatting is not enough you can also "manually" specify thelabels for each slice individually. You do this by using the <A href="../ref/PiePlot.html#_PIEPLOT_SETLABELS">PiePLot::SetLabels()</A> method. This will let you specify individualtext strings for each label. In each specification you can also add aprintf() formatting specification for a number. The number passed onwill be either the absolute value for the slice or the percentage valuedepending on what was specified in the call to <A href="../ref/PiePlot.html#_PIEPLOT_SETLABELTYPE">SetLabelType()</A></P><P> The SetLabels() method can also take a second parameter, the labelposition parameter. This is just a shortcut to the SetLabelPos() asdescribed above. By default the position will be set to 'auto' if notexplicitely specified.<DIV class="note"><B>Note:</B> The alignment ofthe labels will be different depending on whether they are inside oroutside the pie. When inside the center of the strings will be alignedwith the center of the slice at the specified fraction of the radius.When positioned outside the alignment will depend on the angle to avoidthat the labels inadvertely writes over the pie.</DIV></P><H3><A NAME="8_2_5">8.2.5 Specifying slice colors and using themes</A></H3><P> Another typical change would be to change the colors of the slices.There are two fundamental ways of doing this. You either manuallyspecify the colors for the slices as an array using the method <A href="../ref/PiePlot.html#_PIEPLOT_SETSLICECOLORS">SetSliceColors()</A> If you specify fewer colors than the number ofslices they will just wrap around.</P><P> Another way is to use one of the pre-defined color "themes". This isjust a predefined set of colors that will be used for the slices. Youchoose what "theme" you like to use with the method (<A href="../ref/PiePlot.html#_PIEPLOT_SETTHEME">SetTheme()</A> ) At the time of this writing the available themes are</P><UL><LI> "earth"</LI><LI> "pastel"</LI><LI> "sand"</LI><LI> "water"</LI></UL><P> The following example shows the same pie using the different"themes" in order.<DIV class="example"><BR> <A href="exframes/frame_example28.html" target="blank"><IMG border="0"HEIGHT="150" src="img/img/img/img/img/img/img/img/example28.png" WIDTH="150"></A><BR><B>Figure 132:</B> <A href="exframes/frame_example28.html" target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_example28.1.html" target="blank"><IMG border="0"HEIGHT="150" src="img/img/img/img/img/img/img/img/example28.1.png" WIDTH="150"></A><BR><B>Figure 133:</B> <A href="exframes/frame_example28.1.html" target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_example28.2.html" target="blank"><IMG border="0"HEIGHT="150" src="img/img/img/img/img/img/img/img/example28.2.png" WIDTH="150"></A><BR><B>Figure 134:</B> <A href="exframes/frame_example28.2.html" target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_example28.3.html" target="blank"><IMG border="0"HEIGHT="150" src="img/img/img/img/img/img/img/img/example28.3.png" WIDTH="150"></A><BR><B>Figure 135:</B> <A href="exframes/frame_example28.3.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P> A complete color chart of all available colors in the differentthemes can be found <A href="themes.html"> here</A></P><P> Another simple change is to remove the border ( or change it'scolors ) that separates each slice. This can be done by a call to <A href="../ref/PiePlot.html#_PIEPLOT_SHOWBORDER">ShowBorder()</A></P><H3><A NAME="8_2_6">8.2.6 Adding drop shadows to the slices</A></H3><P> An additional visual enhancements can be made by adding a dropshadow to the individual slices. This is accomplished by means of the <Ahref="../ref/PiePlot.html#_PIEPLOT_SETSHADOW"> PiePlot::SetShadow()</A>method. Adding a drop shadow is often more affective if the pie has oneor more slices exploded as the following example shows<DIV class="example"><BR> <A href="exframes/frame_pieex9.html" target="blank"><IMG border="0" HEIGHT="200"src="img/img/img/img/img/img/img/img/pieex9.png" WIDTH="250"></A><BR><B>Figure 136:</B> Adding a drop hadow to the slices <A href="exframes/frame_pieex9.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="8_2_7">8.2.7 Another variant of 2D Pie plots</A></H3><P> As mentioned in the beginning there are two versions of the 2D pieplots. The normal pie plot created as an instance of <A href="../ref/PiePlot.html#_C_PIEPLOT">class PiePlot</A> and a variant created as an instance of <A href="../ref/PiePlot.html#_C_PIEPLOTC">class PiePlotC</A></P><P> This variant is an extension of the standard PiePlot in the sensethat it also have a filled circle in the center. The following exampleillustrates this</P><P><DIV class="example"><BR> <A href="exframes/frame_piecex1.html" target="blank"><IMG border="0"HEIGHT="300" src="img/img/img/img/img/img/img/img/piecex1.png" WIDTH="300"></A><BR><B>Figure 137:</B> Example of the variant of pie plot with a filledcenter circle <A href="exframes/frame_piecex1.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P> Since the PiePlotC is an extension to the basic pie plot all thenormal formatting you can do for pie plots you can also do for thePiePlotC .</P><P> The additional formatting only concerns the filled middle circle.You have the option of adjusting size, fill color and all fontproperties. You perform these operations with the methods</P><P></P><TABLE><TR><TD><A href="../ref/PiePlotC.html#_PIEPLOTC_SETMIDCOLOR">PiePlotC::SetMidColor()</A></TD><TD>Set fill color of mid circle</TD></TR><TR><TD><A href="../ref/PiePlotC.html#_PIEPLOTC_SETMIDSIZE">PiePlotC::SetMidSize()</A></TD><TD>Set size (fraction of radius)</TD></TR><TR><TD><A href="../ref/PiePlotC.html#_PIEPLOTC_SETMIDTITLE">PiePlotC::SetMidTitle()</A></TD><TD>Set title string (may bemulti-lined)</TD></TR><TR><TD><A href="../ref/PiePlotC.html#_PIEPLOTC_SETMID">PiePlotC::SetMid()</A></TD><TD>Set all parameters in a single methodcall</TD></TR></TABLE><P> In addition to the normal CSIM for PiePlot:s the center area is alsoa CSIM hotspot. You specify the target CSIM with a call to <A href="../ref/PiePlotC.html#_PIEPLOTC_SETMIDCSIM">PiePlotC::SetMidCSIM()</A></P><P> The next example shows an example with some more innovativeformatting. In this example we have :</P><UL><LI> hidden the frame around the pie graph</LI><LI> exploded all the slices</LI><LI> added drop shadow to the individual slices (and the center filledcircle)</LI><LI> specified individual multi line labels.</LI><LI> changed the font for the title to a TTF font.</LI></UL><P><DIV class="example"><BR> <A href="exframes/frame_piecex2.html" target="blank"><IMG border="0"HEIGHT="400" src="img/img/img/img/img/img/img/img/piecex2.png" WIDTH="400"></A><BR><B>Figure 138:</B> PiePlotC with some more innovative formatting tomake it more interesting. <A href="exframes/frame_piecex2.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P></P><H2><A NAME="8_3">8.3 Polar plots</A></H2><P></P><H3><A NAME="8_3_1">8.3.1 Overview</A></H3><P> Each data point in a polar plot is represented by a tuple consistingof a radius and an angle. The polar plot itself can be either outlinedor filled. In addition each point may have a standard marker (the sameas for line and scatter plots).</P><P> The scale for the radius can be either linear or logarithmic.</P><P> A polar graph is created by creating an instance of <A href="../ref/PolarGraph.html#_POLARGRAPH_POLARGRAPH">PolarGraph::PolarGraph()</A>. The polar graph type inherits all thecapabilities of ordinary X-Y graphs, i.e they can have backgroundimages, background gradients, tabbed titles and so on.</P><P> Polar graphs comes in two basic types, they can either show a full360 degree graph or a half 180 degree graph. The two examples belowshow these two basic types of graphs.</P><P><DIV class="example"><BR> <A href="exframes/frame_polarex0.html" target="blank"><IMG border="0"HEIGHT="250" src="img/img/img/img/img/img/img/img/polarex0.png" WIDTH="250"></A><BR><B>Figure 139:</B> A simple 360 degree polar graph <A href="exframes/frame_polarex0.html"target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_polarex0-180.html" target="blank"><IMG border="0"HEIGHT="250" src="img/img/img/img/img/img/img/img/polarex0-180.png" WIDTH="250"></A><BR><B>Figure 140:</B> The 180 degree variant polar plot. <A href="exframes/frame_polarex0-180.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="8_3_2">8.3.2 Adjusting the radius scale</A></H3><P> The radius axis can be shown in either a linear or logarithmicscale. This is controlled, as usual, by a call to <A href="../ref/PolarGraph.html#_POLARGRAPH_SETSCALE">PolarGraph::SetScale()</A> The two examples below show the same plot ineither linear or logarithmic scale</P><P><DIV class="example"><BR> <A href="exframes/frame_polarex3.html" target="blank"><IMG border="0"HEIGHT="300" src="img/img/img/img/img/img/img/img/polarex3.png" WIDTH="300"></A><BR><B>Figure 141:</B> Using a logarithmic scale <A href="exframes/frame_polarex3.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P><DIV class="example"><BR> <A href="exframes/frame_polarex3-lin.html" target="blank"><IMG border="0"HEIGHT="300" src="img/img/img/img/img/img/img/img/polarex3-lin.png" WIDTH="300"></A><BR><B>Figure 142:</B> Using a linear scale <A href="exframes/frame_polarex3-lin.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> Please note that the maximum values of the scales are different.</P><P> By default the scale will be auto scaled depending on the data. Youcan also specify a manual scale by supplying an extra argument to theSetScale() value. The only difference from the manual scaling with theother X-Y-graphs is that for polar graph you only specify a manualmaximum. The minimum will always be 0 for the linear scale and a scaledvalue of 10 (i.e 1, 0.1, 0.001 and so on) for the logarithmic scale.</P><P> The plot is clipped to the plot area so if you specify a smallerscale then the maximum value that part of the plot that are outside theplot area will be clipped.</P><H3><A NAME="8_3_3">8.3.3 Adjusting the grid lines</A></H3><P> As usual you have full freedom to select what grid lines you like toshow (and what colors they should have). There are three differenttypes of grid lines you may adjust. The radius minor and major gridlines and the angle grid lines.</P><P> You select what grid lines to show with a call to <A href="../ref/PolarAxis.html#_POLARAXIS_SHOWGRID">PolarAxis::ShowGrid()</A> The two example below shows a logarithmic plotwith either just major grid lines or both minor and major grid lines.</P><P><DIV class="example"><BR> <A href="exframes/frame_polarex4.html" target="blank"><IMG border="0"HEIGHT="350" src="img/img/img/img/img/img/img/img/polarex4.png" WIDTH="300"></A><BR><B>Figure 143:</B> Using a logarithmic scale with just majorgridlines <A href="exframes/frame_polarex4.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P><DIV class="example"><BR> <A href="exframes/frame_polarex5.html" target="blank"><IMG border="0"HEIGHT="350" src="img/img/img/img/img/img/img/img/polarex5.png" WIDTH="300"></A><BR><B>Figure 144:</B> Using a logarithmic scale with both minor andmajor gridlines <A href="exframes/frame_polarex5.html" target="blank">[src]</A> <P></P></DIV></P><P> The colors of the grid lines are specified with a call to <A href="../ref/PolarAxis.html#_POLARAXIS_SETGRIDCOLOR">PolarAxis::SetGridColor()</A></P><P> For the angle grid lines it is possible to specify the angledivision between each grid line with the method <A href="../ref/PolarAxis.html#_POLARAXIS_SETANGLESTEP">PolarAxis::SetAngleStep()</A> You specify the step distance in degrees.By default the step size is 15 degrees.</P><H3><A NAME="8_3_4">8.3.4 Adjusting the label fonts</A></H3><P> You can individually specify different fonts and colors for theangle and the radius labels. The radius font is specified withPolarAxis::SetFont() and the angle font is specified with a call to <A href="../ref/PolarAxis.html#_POLARAXIS_SETANGLEFONT">PolarAxis::SetAngleFont()</A></P><P> You can adjust the color with the method <A href="../ref/PolarAxis.html#_POLARAXIS_SETCOLOR">PolarAxis::SetColor()</A> ?></P><P> The following example specifies different color for the labels. italso shows that you can add both a radial axis title as well as atabbed title. In this example we have also chosen not to show the framearound the edge of the plot.</P><P><DIV class="example"><BR> <A href="exframes/frame_polarex9.html" target="blank"><IMG border="0"HEIGHT="320" src="img/img/img/img/img/img/img/img/polarex9.png" WIDTH="350"></A><BR><B>Figure 145:</B> Different colors for labels, specifying both atabbed title as well as a axis title <A href="exframes/frame_polarex9.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="8_3_5">8.3.5 Adjusting the labels</A></H3><P> As can be seen from the previous examples the angle labels have asmall superscripted "o" after each label. You can select if you like toshow this degree mark or not with a call to the <A href="../ref/PolarAxis.html#_POLARAXIS_SHOWANGLEDEGREEMARK">PolarAxis::SetANgleDegreeMark()</A> method by which you can enable ordisable that mark after the angels.</P><P> For the radius labels all standard formatting that can be done tothe X-Y axis such as format string or format callbacks are supported.</P><P> A common modification for polar plots is probably to disable thedisplay the last label when using a 360 degree plot since the lastlabel will "collide" with the plot box around the plot area. It ispossible to disable the last label with a call to <A href="../ref/Axis.html#_AXIS_HIDELASTTICKLABEL">Axis::HideLastTickLabel()</A> As you can see this has been used in someof the examples in this chapter.</P><H3><A NAME="8_3_6">8.3.6 Image maps</A></H3><P> If you have specified markers for the polar plot (by setting themark property of the plot) each marker can be a hot spot in a clientside image map. The target URL are as usual specified with theSetCSIMTargets() as the following short code excerpt shows<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> </FONT><FONT color="#FF8000">// Start by specifying the proper URL targets<BR></FONT><FONT color="#0000BB">$targets </FONT><FONT color="#007700">= array(</FONT><FONT color="#DD0000">"#1"</FONT><FONT color="#007700">,</FONT><FONTcolor="#DD0000">"#2"</FONT><FONT color="#007700">, ....... );<BR></FONT><FONT color="#0000BB">$polarplot </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">PoalrPlot</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$data</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$polarplot</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">mark</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetType</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">MARK_SQUARE</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$polarplot</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetCSIMTargets</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">targets</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Add</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$polarplot</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">StrokeCSIM</FONT><FONT color="#007700">();</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><H3><A NAME="8_3_7">8.3.7 A final example</A></H3><P> As a final example we show a full 360 degree polar plot with squaremarkers as well as background color gradient and a legend for the plot.<DIVclass="example"><BR> <A href="exframes/frame_polarex7-2.html" target="blank"><IMG border="0"HEIGHT="400" src="img/img/img/img/img/img/img/img/polarex7-2.png" WIDTH="300"></A><BR><B>Figure 146:</B> A polar plot with both legend and backgroundgradient fill. <A href="exframes/frame_polarex7-2.html" target="blank">[src]</A> <P></P></DIV></P><P></P><H1><A NAME="9">9 Gantt charts</A></H1><P></P><H2><A NAME="9_1">9.1 Why use Gantt charts?</A></H2><P> The cynical view: To explain why your project is over-due andover-budget.</P><P> The pragmatic view: To keep management of our back and know what wehave forgotten</P><P> The common view: As a tool to help identify project issues andhighlight problem areas.</P><P> Basically, Gantt charts are used to show the state of a number ofactivities (possible grouped) against time.</P><H2><A NAME="9_2">9.2 Capabilities in JpGraph Gantt module</A></H2><P></P><UL><LI> Both automatic and manual scaling of date</LI><LI> Full support for independent CSIM for both labels and activity bars</LI><LI> Extremely flexible scales, possibility to use both months, weeks,days, hours and minutes as scales. Furthermore (unlike MS Project) youcan have as may scales displayed at the same time as you like.</LI><LI> Support for visualization of grouped activities</LI><LI> Gantt charts can be automatically sized according to the number ofbars and scale used. This means you don't have to supply a specificsize when creating a graph.</LI><LI> Unlimited number of activities</LI><LI> Supports platform independent Week number calculation according toISO:8601</LI><LI> Rich possibility to display a variety of scales or combination ofscales supports both day, week, month, year. Each scale header istotally configurable in terms of font, size, color, background etc</LI><LI> User configurable date format in the scale headlines</LI><LI> Visualization of constrains between activities, start-to-start,start-to-end, end-to-start and end-to-end</LI><LI> Scales have "intelligent" grids</LI><LI> Supports title and subtitle with user specified font, size andcolor</LI><LI> Activity bars can have multiple patterns and colors</LI><LI> Activity bar may have shadows</LI><LI> Activity bars can have internal progress bars displayed to show howmuch of a given task has been accomplished</LI><LI> Activity titles can have individual fonts, colors and backgrounds</LI><LI> Activity bars can have captions</LI><LI> Activity bars can have specified left- and right end markers</LI><LI> Bar heights can be specified in absolute pixels or in percent ofthe activity line width</LI><LI> Supports milestones with many different marks</LI><LI> Supports vertical marker lines with text</LI><LI> Can easily be localized</LI><LI> Full support for CSIM (or drill down graphs)</LI><LI> Alternate row colors</LI><LI> ... and more</LI></UL><P></P><H2><A NAME="9_3">9.3 A simple Gantt chart</A></H2><P> Time to show you an example of a Gantt chart and how easy it is tomake one. Lets make it the simplest possible Gantt chart. One activity,named "Project", which lasts from "2001-11-01" to "2002-02-20".</P><P> All it takes to do this (using default values for everything) is thefollowing code.<DIV class="phpscript">(File: ganttex00.php)<BR><CODE><FONT color="#000000"> <FONT color="#0000BB"><?php<BR></FONT><FONT color="#007700">include (</FONT><FONT color="#DD0000">"../jpgraph.php"</FONT><FONT color="#007700">);<BR>include (</FONT><FONT color="#DD0000">"../jpgraph_gantt.php"</FONT><FONTcolor="#007700">);<BR><BR></FONT><FONT color="#FF8000">// A new graph with automatic size<BR></FONT><FONT color="#0000BB">$graph </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">GanttGraph</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"auto"</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// A new activity on row '0'<BR></FONT><FONT color="#0000BB">$activity </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">GanttBar</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONTcolor="#DD0000">"Project"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"2001-12-21"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"2002-01-20"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Add</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$activity</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Display the Gantt chart<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Stroke</FONT><FONT color="#007700">();<BR></FONT><FONT color="#0000BB">?><BR></FONT></FONT></CODE></DIV></P><P> The resulting image is shown in Figure 147 below.<DIV style="margin-left:-120px;"><DIV class="example"><BR> <A href="exframes/frame_ganttex00.html" target="blank"><IMG border="0"HEIGHT="112" src="img/img/img/img/img/img/img/img/ganttex00.png" WIDTH="486"></A><BR><B>Figure 147:</B> Your first simple Gantt chart. <A href="exframes/frame_ganttex00.html"target="blank">[src]</A> <P></P></DIV><P></P></DIV></P><P> Let's note a few things with the above image and code:</P><UL><LI> You always need to include both jpgraph.php and jpgraph_gantt.php</LI><LI> A bar is specified a minimum of four parameters, vertical position(more about that in a second), a title, start and end date.</LI><LI> If you don't specify a size for the image it will be automaticallydecided based on the min and max dates for the bars rounded to a fullweek.</LI><LI> By default the week and day scale are displayed.</LI><LI> Weekend background are displayed default in a slightly gray color</LI><LI> Sundays are written in red.</LI><LI> Weeks are numbered according to ISO 8601</LI><LI> Activity bars are rendered as blue stripes on a white background bydefault.</LI></UL><P> So, lets start making this graph a little bit more interesting.First we are going to add a title, then we will add a month scale andfinally we will change the color of the bar.</P><P> All that is taken care of in the code below.<DIV class="phpscript">(File: ganttex01.php)<BR><CODE><FONT color="#000000"> <FONT color="#0000BB"><?php<BR></FONT><FONT color="#007700">include (</FONT><FONT color="#DD0000">"../jpgraph.php"</FONT><FONT color="#007700">);<BR>include (</FONT><FONT color="#DD0000">"../jpgraph_gantt.php"</FONT><FONTcolor="#007700">);<BR><BR></FONT><FONT color="#0000BB">$graph </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">GanttGraph</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"auto"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetShadow</FONT><FONT color="#007700">();<BR><BR></FONT><FONT color="#FF8000">// Add title and subtitle<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"A nice main title"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">FF_ARIAL</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FS_BOLD</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">12</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">subtitle</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"(Draft version)"</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Show day, week and month scale<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">ShowHeaders</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">GANTT_HDAY </FONT><FONT color="#007700">| </FONT><FONT color="#0000BB">GANTT_HWEEK </FONT><FONT color="#007700">| </FONT><FONT color="#0000BB">GANTT_HMONTH</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Instead of week number show the date for the first day in the week<BR>// on the week scale<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">week</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetStyle</FONT><FONTcolor="#007700">(</FONT><FONT color="#0000BB">WEEKSTYLE_FIRSTDAY</FONT><FONTcolor="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Make the week scale font smaller than the default<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">week</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONTcolor="#007700">(</FONT><FONT color="#0000BB">FF_FONT0</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Use the short name of the month together with a 2 digit year<BR>// on the month scale<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">month</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetStyle</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">MONTHSTYLE_SHORTNAMEYEAR2</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Format the bar for the first activity<BR>// ($row,$title,$startdate,$enddate)<BR></FONT><FONT color="#0000BB">$activity </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">GanttBar</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONTcolor="#DD0000">"Project"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"2001-12-21"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"2002-01-20"</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Yellow diagonal line pattern on a red background<BR></FONT><FONT color="#0000BB">$activity</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetPattern</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">BAND_RDIAG</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"yellow"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$activity</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFillColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"red"</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Finally add the bar to the graph<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Add</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$activity</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// ... and display it<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Stroke</FONT><FONT color="#007700">();<BR></FONT><FONT color="#0000BB">?><BR></FONT></FONT></CODE></DIV> The resulting image is shown in Figure148 below.<DIV class="example"><BR> <A href="exframes/frame_ganttex01.html" target="blank"><IMG border="0"HEIGHT="152" src="img/img/img/img/img/img/img/img/ganttex01.png" WIDTH="486"></A><BR><B>Figure 148:</B> Making the Gantt chart a little bit moreinteresting with title and more colors. <A href="exframes/frame_ganttex01.html"target="blank">[src]</A> <P></P></DIV></P><P> From the above example you might note a few things</P><UL><LI> The margins adjust automatically to the added title and subtitle</LI><LI> The height of the scale headers adjust automatically when youchange the font.</LI><LI> You have great flexibility in choosing what format the scale labelswill have. If you for example wanted the full 4 digit year in the monthheader all you have to change is use the constantMONTHSTYLE_SHORTNAMEYEAR2 in the code above toMONTHSTYLE_SHORTNAMEYEAR4</LI><LI> You have full freedom of manipulating headers in terms of font,color, background and size.</LI></UL><P> To show that this is really simple let's show the full year in themonth, and set the header style to be white text on a dark bluebackground by adding the lines<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> </FONT><FONT color="#FF8000">// Use the short name of the month together with a 4 digit year<BR>// on the month scale<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">month</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetStyle</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">MONTHSTYLE_SHORTNAMEYEAR4</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">month</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetTextColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"white"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">month</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetBackgroundColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"blue"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P>to the code above. The resulting image is shown in Figure 149<DIV class="example"><BR> <A href="exframes/frame_ganttex02.html" target="blank"><IMG border="0"HEIGHT="112" src="img/img/img/img/img/img/img/img/ganttex02.png" WIDTH="381"></A><BR><B>Figure 149:</B> Enhancing the scale headers. <A href="exframes/frame_ganttex02.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H2><A NAME="9_4">9.4 The structure of a Gantt chart</A></H2><P> A Gantt chart is made up of four distinct areas.</P><OL><LI>On the left side there is the activity title column.</LI><LI>On the top there is the scale headers (up to four headers may bedisplayed)</LI><LI>The actual plot area where all the Gantt bars and markers go</LI><LI>The margin area, where for example the titles are shown</LI></OL><P> Since a Gantt chart inherits all the usual properties of a JpGraphGraph() you have the access to the same method to formatting the imageas before. For example to have a shadow around the image you callGraph::SetShadow() and to set the margin color you can useGraph::SetMarginColor(). Please refer to the reference documentationfor a full list of supported features.</P><P> To create a Gantt chart you<STRONG> add</STRONG> objects to it. Asof this writing you may add the following object by the use of theGanttChart::Add() method</P><UL><LI> Gantt bars (indicates the length of an activity)</LI><LI> Milestones, a single mark at a specific date</LI><LI> Vertical line, might be use to mark phases in projects</LI></UL><P> All these objects may be extensively modified in terms offormatting. You can specify color (both fill- and frame color), size,titles, style and patterns and so on. All these objects comes with (inmy mind) sensible default so you don't have to specify a lot ofparameters. But if you need a fine grain control or if you disagreewith my taste you<STRONG> can</STRONG>.</P><H2><A NAME="9_5">9.5 Creating a GanttChart</A></H2><P> You create a new Gantt Chart with a call to GanttChart(). Thesignature for GanttGraph is the same as for ordinary JpGraph graphs,i.e<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> </FONT><FONT color="#007700">function </FONT><FONT color="#0000BB">GanttGraph</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$aWidth</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$aHeight</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$aCachedName</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$aTimeOut</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$aInline</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P>The only real difference is that for GanttCharts you can specify oneor both of the dimension parameters (width and height) as -1 in whichcase that dimension will be automatically sized determined by scale andfonts chosen. The following examples shows some possible ways ofcreating a new graph</P><UL><LI> $graph=new GanttGraph()<BR> The size of the graph will be determined automatically, no cachingwill be used and the graph will be generated in-line.</LI><LI> $graph=new GanttGraph(-1,-1,"auto")<BR> The size of the graph will be determined automatically, cachingwill be used (the name will be based on the script name), no timeoutwill be used and the graph will be generated in-line</LI><LI> $graph=new GanttGraph(450,-1,"auto",5)<BR> Same as the previous entry but the width is fixed to 450 points andthe cached image will have a timeout of 5 min.</LI><LI> $graph=new GanttGraph(-1,-1,"auto",5,false)<BR> The image will not be generated in-line, only the cache will beupdated if it has timed out, otherwise nothing will happen.</LI></UL><P> Since GanttGraph() inherits all the methods (that make sense forGanttGraph) from Graph you can specify shadow, color etc of the generalframe.</P><H2><A NAME="9_6">9.6 Positioning objects in the Gantt plot</A></H2><P> Bars and Milestones need both a vertical position and a horizontalposition. The horizontal start position is specified as a date, e.g."2001-06-23", and the vertical positions are specified as a number[0,1,2,3,...]. This vertical number indicates the position from the topwhere the object should be placed. To understand this you might imaginea number of "invisible" horizontal bands with a certain height. If youspecify 0 as the vertical position the bar will be placed in the firstband, specify 3 and the bar will be placed in the fourth band and soon.</P><P> It is perfectly legal, and perhaps even desirable to leave "gaps"when laying out bands to group related activities. So, for example youcould have three activities/bars at positions 1,2,3 and then another 2bars at position 6,7 leaving band 0,4,5 empty.</P><P> All these "invisible bands" have the same height (equ-spaced). Theheight of each band is automatically determined and depends on both themethod of layout ( as specified by (GanttChart::SetLayout()) and theindividual heights of the individual bars and titles. The rules arequite simple:</P><UL><LI> If you use layout=GANTT_FROMTOP (the default and most common) theheight will equal the height (+ a margin) of the highest gantt bar. Theheight calculation of each bar takes into account both the actual bar,the title, and any left- right-marks (more about that later) that maybe present. The name "fromtop" refers to that when you have explicitlyspecified a height the bars will usually be added from band 0 andonwards and hence being added from the top. (This might leave emptyspace at the bottom of the plot area in the graph if the height of thegraph has been explicitly specified).</LI><LI> If you use layout=GANTT_EVEN the bars are evenly (hence the name)spread out over the available height in the gantt chart and noconsideration is taken of the individual bars heights. Note that if youuse automatic sizing you cant use even layout. It just doesn't makesense. Even layout is for those cases when you deliberately specify avery large image and want the bars evenly distributed using the fullheight.</LI></UL><P></P><H2><A NAME="9_7">9.7 Gantt bars</A></H2><P> The most common of all object in a Gantt chart is of course theactivity bar (GanttBar()). In terms of formatting this object has avery large flexibility. The full signature for the GanttBar constructoris<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> </FONT><FONT color="#007700">function </FONT><FONT color="#0000BB">GanttBar</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$aVPos</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$aTitle</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">$aStart</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$aEnd</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">$aCaption</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$aHeight</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P></P><TABLE border="0"><TR><TD valign="top"><!--span style="font-family:times;font-size:85%;font-weight:bold;"--><CODE><FONT color="#000000"> <FONT color="#0000BB"> $aVPos </FONT></FONT></CODE></TD><TD valign="top"> </TD><TD>The vertical position for thebar, [0..n]</TD></TR><TR><TD valign="top"><!--span style="font-family:times;font-size:85%;font-weight:bold;"--><CODE><FONT color="#000000"> <FONT color="#0000BB"> $aTitle </FONT></FONT></CODE></TD><TD valign="top"> </TD><TD>Title for the activity</TD></TR><TR><TD valign="top"><!--span style="font-family:times;font-size:85%;font-weight:bold;"--><CODE><FONT color="#000000"> <FONT color="#0000BB"> $aStart </FONT></FONT></CODE></TD><TD valign="top"> </TD><TD>Start date for the activity givenas string, e.g "2001-09-22"</TD></TR><TR><TD valign="top"><!--span style="font-family:times;font-size:85%;font-weight:bold;"--><CODE><FONT color="#000000"> <FONT color="#0000BB"> $aEnd </FONT></FONT></CODE></TD><TD valign="top"> </TD><TD>End date for activity given as<B> either</B>a date (a string) or as the duration (in days) of the activity, e.gboth "2001-10-15" and 20.5 are valid inputs</TD></TR><TR><TD valign="top"><!--span style="font-family:times;font-size:85%;font-weight:bold;"--><CODE><FONT color="#000000"> <FONT color="#0000BB"> $aCaption </FONT></FONT></CODE></TD><TD valign="top"> </TD><TD>Text string (caption) to appearat the end (right side) of the bar</TD></TR><TR><TD valign="top"><!--span style="font-family:times;font-size:85%;font-weight:bold;"--><CODE><FONT color="#000000"> <FONT color="#0000BB"> $aHeight </FONT></FONT></CODE></TD><TD valign="top"> </TD><TD>Height of bar given as<B> either</B>a value in range [0,1] in which case this is interpretated as whatfraction of the vertical position should the bar occupy. The height canalso be given in absolute pixels [1..200]</TD></TR></TABLE><H3><A NAME="9_7_1">9.7.1 Specifying vertical position</A></H3><P> As described above vertical positions are specified as a numericvalue [0..n] where 'n' is an arbitrary constant. (For practicalpurposes n is most likely < 100)</P><P> Using our previous example we will illustrate this parameter bychanging the position of our 'Project' activity to position 7. Thereforwe change the call to GanttBar() to<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $activity </FONT><FONT color="#007700">= new </FONT><FONTcolor="#0000BB">GanttBar</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">7</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"Project"</FONT><FONTcolor="#007700">,</FONT><FONT color="#DD0000">"2001-12-21"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"2002-02-20"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> and we then get the chart as shown below in Figure 150.</P><P><DIV class="example"><BR> <A href="exframes/frame_ganttex03.html" target="blank"><IMG border="0"HEIGHT="280" src="img/img/img/img/img/img/img/img/ganttex03.png" WIDTH="486"></A><BR><B>Figure 150:</B> Changing the vertical position to 7 <A href="exframes/frame_ganttex03.html"target="blank">[src]</A> <P></P></DIV></P><P> Note that the height of each position (vertical position) willdepend on the actual height of the bar.</P><H3><A NAME="9_7_2">9.7.2 Specifying start and end position for a bar</A></H3><P> Start of bars are given as a date string. The format depends on thecurrent locale. Examples of valid date strings are</P><UL><LI> "2001-10-22"</LI><LI> "22 October 2001"</LI><LI> "22 Oct 2001"</LI></UL><P> Even if several format are supported it is recommended to use allnumeric dates, i.e in the form "2001-10-22".</P><P> Specifying the end position may be done in two different ways,either by the end date in the same way as for the start date. The otherway is to specify the<B> length</B> of the activity in number of days(and fractions thereof). Examples of valid end dates are:</P><UL><LI> "2001-11-15"</LI><LI> "15 Nov 2001"</LI><LI> 22, (specifies duration of 22 days)</LI><LI> 22.7, (specifies duration of 22.7 days)</LI></UL><P> Please note that duration is specified as numerical values and<B>not</B> strings.</P><H3><A NAME="9_7_3">9.7.3 Milestones</A></H3><P> Milestones are similar to bars but have no end date since milestonesjust apply to one single date. Milestones are created much the same wayas activities but using method MileStone() instead.</P><P> The full signature for milestones are<DIV class="phpscript"><CODE><FONTcolor="#000000"> <FONT color="#0000BB"> </FONT><FONT color="#007700">function </FONT><FONT color="#0000BB">MileStone</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$aVPos</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">$aTitle</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$aDate</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$aCaption</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P></P><TABLE border="0"><TR><TD valign="top"><!--span style="font-family:times;font-size:85%;font-weight:bold;"--><CODE><FONT color="#000000"> <FONT color="#0000BB"> $aVPos </FONT></FONT></CODE></TD><TD valign="top"> </TD><TD>The vertical position for thebar, [0..n]</TD></TR><TR><TD valign="top"><!--span style="font-family:times;font-size:85%;font-weight:bold;"--><CODE><FONT color="#000000"> <FONT color="#0000BB"> $aTitle </FONT></FONT></CODE></TD><TD valign="top"> </TD><TD>Title for the activity</TD></TR><TR><TD valign="top"><!--span style="font-family:times;font-size:85%;font-weight:bold;"--><CODE><FONT color="#000000"> <FONT color="#0000BB"> $aDate </FONT></FONT></CODE></TD><TD valign="top"> </TD><TD>Date for the milestone</TD></TR><TR><TD valign="top"><!--span style="font-family:times;font-size:85%;font-weight:bold;"--><CODE><FONT color="#000000"> <FONT color="#0000BB"> $aCaption </FONT></FONT></CODE></TD><TD valign="top"> </TD><TD>Text to the right of themilestone</TD></TR></TABLE><P> Valid milestones are for example</P><UL><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $milestone </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">MileStone</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">3</FONT><FONTcolor="#007700">,</FONT><FONT color="#DD0000">"Code complete"</FONT><FONTcolor="#007700">,</FONT><FONT color="#DD0000">"2001-12-01"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P></P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $milestone </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">MileStone</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">3</FONT><FONTcolor="#007700">,</FONT><FONT color="#DD0000">"Code complete"</FONT><FONTcolor="#007700">,</FONT><FONT color="#DD0000">"2001-12-01"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"(2001-12-01)"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P></P></LI></UL><P> By default milestones are rendered as a filled "Diamond" shape. Thismay be optionally modified. The actual shape is specified by the 'mark'property of milestone which is an instance of the PlotMark() class(same class responsible for the marks in line graphs).</P><P> To change the shape of a milestone to, say a triangle, you use theSetType() method as in<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $milestone</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">mark</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetType</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">MARK_DTRIANGLE</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> Let's put this into practice and add a milestone to our previousexample by adding the following two lines of code which result inFigure 151 shown below.<DIV class="example"><BR> <A href="exframes/frame_ganttex04.html" target="blank"><IMG border="0"HEIGHT="189" src="img/img/img/img/img/img/img/img/ganttex04.png" WIDTH="493"></A><BR><B>Figure 151:</B> Illustration of how to add a milestone to a ganttchart <A href="exframes/frame_ganttex04.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P> You may note that by default the title color is red for milestones.If you like to change this to be instead, say bold black, you wouldinvoke the SetColor() and SetFont() methods on the title property ofmilestones as in<DIV class="phpscript"><CODE><FONT color="#000000"> <FONTcolor="#0000BB"> $milestone</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONTcolor="#007700">(</FONT><FONT color="#0000BB">FF_FONT1</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FF_BOLD</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$milestone</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"black"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> and thew result would now (not surprisingly be)<DIV class="example"><BR> <A href="exframes/frame_ganttex05.html" target="blank"><IMG border="0"HEIGHT="189" src="img/img/img/img/img/img/img/img/ganttex05.png" WIDTH="502"></A><BR><B>Figure 152:</B> Modifying the milestone title color and font <A href="exframes/frame_ganttex05.html"target="blank">[src]</A> <P></P></DIV></P><P> To modify the caption you do exactly the same but act on property'caption' instead of 'title', i.e.<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $milestone</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">caption</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">FF_FONT1</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FF_BOLD</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$milestone</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">caption</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"black"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> It is worth noting that you modify the bar title and caption theexact same way by acting on the 'title' and 'caption' property for thebars.</P><H3><A NAME="9_7_4">9.7.4 Vertical line</A></H3><P> The final object you may add to a Gantt chart is simple, but quiteuseful, a straight vertical line extending over the whole plot height.This could for example be used to illustrate different phases in aproject. You create a line object by a call to GanttVLine()</P><P> The full signature for GanttVLine() is<DIV class="phpscript"><CODE><FONTcolor="#000000"> <FONT color="#0000BB"> </FONT><FONT color="#007700">function </FONT><FONT color="#0000BB">GanttVLine</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$aDate</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">$aTitle</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$aColor</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$aWeight</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$aStyle</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P></P><TABLE border="0"><TR><TD valign="top"><!--span style="font-family:times;font-size:85%;font-weight:bold;"--><CODE><FONT color="#000000"> <FONT color="#0000BB"> $aDate </FONT></FONT></CODE></TD><TD valign="top"> </TD><TD>Date for the milestone</TD></TR><TR><TD valign="top"><!--span style="font-family:times;font-size:85%;font-weight:bold;"--><CODE><FONT color="#000000"> <FONT color="#0000BB"> $aTitle </FONT></FONT></CODE></TD><TD valign="top"> </TD><TD>Title for the line. The title isdisplayed at the bottom of the line</TD></TR><TR><TD valign="top"><!--span style="font-family:times;font-size:85%;font-weight:bold;"--><CODE><FONT color="#000000"> <FONT color="#0000BB"> $aColor </FONT></FONT></CODE></TD><TD valign="top"> </TD><TD>Color for the line</TD></TR><TR><TD valign="top"><!--span style="font-family:times;font-size:85%;font-weight:bold;"--><CODE><FONT color="#000000"> <FONT color="#0000BB"> $aWeight </FONT></FONT></CODE></TD><TD valign="top"> </TD><TD>Line width</TD></TR><TR><TD valign="top"><!--span style="font-family:times;font-size:85%;font-weight:bold;"--><CODE><FONT color="#000000"> <FONT color="#0000BB"> $aStyle </FONT></FONT></CODE></TD><TD valign="top"> </TD><TD>Line style,"dashed", "dotted" andso on</TD></TR></TABLE><P> Valid creations of lines are for example</P><UL><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $vline </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">GanttVLine</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"2001-12-24"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P></P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $vline </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">GanttVLine</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"2001-12-24"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"Phase 1"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P></P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $vline </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">GanttVLine</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"2001-12-24"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"Phase 1"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"darkred"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P></P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $vline </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">GanttVLine</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"2001-12-24"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"Phase 1"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"darkred"</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">5</FONT><FONTcolor="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P></P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $vline </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">GanttVLine</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"2001-12-24"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"Phase 1"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"darkred"</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">5</FONT><FONTcolor="#007700">,</FONT><FONT color="#DD0000">"dotted"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P></P></LI></UL><P> To add the line to the graph you just have to call GanttGraph::Add()as with milestones and bars. Let's illustrate the use of vertical linesby adding a line to the previous example.<DIV class="phpscript"><CODE><FONTcolor="#000000"> <FONT color="#0000BB"> $vline </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">GanttVLine</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"2001-12-24"</FONT><FONT color="#007700">,</FONT><FONTcolor="#DD0000">"Phase 1"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Add</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$vline</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> and the example (See 153) now becomes<DIV class="example"><BR> <A href="exframes/frame_ganttex06.html" target="blank"><IMG border="0"HEIGHT="189" src="img/img/img/img/img/img/img/img/ganttex06.png" WIDTH="502"></A><BR><B>Figure 153:</B> Adding a vertical line with a title to the Ganttchart <A href="exframes/frame_ganttex06.html" target="blank">[src]</A> <P></P></DIV></P><P> From the above figure you can see that by default the line is drawnat the beginning of the day of the specified date and in a 'dashed'style. This can (of course!) be modified so that the line isdrawn/aligned anywhere in the specified day. You modify this byinvoking the method SetDayOffset() with an argument specifying thefraction of the day where you want the line positioned.</P><P> If you, for example, want to display the line in the middle of theday just add the line<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $vline</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetDayOffset</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">0.5</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> to the previous code and the result will be<DIV class="example"><BR> <A href="exframes/frame_ganttex07.html" target="blank"><IMG border="0"HEIGHT="189" src="img/img/img/img/img/img/img/img/ganttex07.png" WIDTH="502"></A><BR><B>Figure 154:</B> Modifying the position of the line within the day<A href="exframes/frame_ganttex07.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P> As usual you may modify the font, size and color by invoking theappropriate method (SetFont(), SetColor()) on the 'title' property oflines.</P><H3><A NAME="9_7_5">9.7.5 Adding markers to a gantt bar</A></H3><P> You can easily add a variety of markers both to the start and end ofthe gantt bar. They could for example be used as an alternate way toillustrate important milestones or anticipated deliveries.</P><P> The left and right markers are accessed through the two properties'leftMark' and 'rightMark'. They are both instances of the general'PlotMark' class which is also used for the milestones (and in linegraphs). The 'PlotMark' class supports several different styles, forexample, diamond (the default for milestones), filled and unfilledcircles, squares, stares, and so on. Please refer to the referencesection for a complete listing.</P><P> Let's illustrate this by adding a right marker to the previousexample. We will use a style of a filled (red) circle with a whitetitle, say, "M5". In order to accomplish this we must augment theprevious example with the following lines:<DIV class="phpscript"><CODE><FONTcolor="#000000"> <FONT color="#0000BB"> $activity</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">rightMark</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Show</FONT><FONT color="#007700">(); <BR></FONT><FONT color="#0000BB">$activity</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">rightMark</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"M5"</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">$activity</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">rightMark</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetType</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">MARK_FILLEDCIRCLE</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$activity</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">rightMark</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetWidth</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">10</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$activity</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">rightMark</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"red"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$activity</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">rightMark</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFillColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"red"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$activity</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">rightMark</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">FF_ARIAL</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FS_BOLD</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">12</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">$activity</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">rightMark</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"white"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> This might seem like a lot of lines but this is as complicated as itpossible can get. As an illustration in the example belwo more or lesseverything that is changeable has been changed, the default font,font-color, fill-color, frame-color and width of marker. The two linesonly really necessary are the first two, showing the mark and setting atitle. One could still get a good result by using default values forthe rest of the properties.</P><P> The resulting image can be seen in Figure 155 below.<DIV class="example"><BR> <A href="exframes/frame_ganttex08.html" target="blank"><IMG border="0"HEIGHT="243" src="img/img/img/img/img/img/img/img/ganttex08.png" WIDTH="502"></A><BR><B>Figure 155:</B> Adding a right marker to a bar. <A href="exframes/frame_ganttex08.html"target="blank">[src]</A> <P></P></DIV></P><P> We have deliberately introduced a "strangeness" here. If theprevious two examples are compared it can bee seen that the lastexample is larger than the previous one. Why?</P><P> The explanation is trivial once we recall that the height of barsare sized relative to the horizontal spacing. The horizontal spacingare based on the highest single bar including title size and, here comethe explanation, marker size. The horizontal spacing has grown sincethe minimum height is now based on 10 points(=the height of the mark).The bar still occupy the same percentage of the height so it seems tohave grown.</P><P> If this behavior is unwanted it is always possible to specify anabsolute size for the bar heigh, say 8 pixels, with a call<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $activity</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">SetHeight</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">8</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P> and achieve the result in Figure 156 below.<DIV class="example"><BR> <A href="exframes/frame_ganttex09.html" target="blank"><IMG border="0"HEIGHT="243" src="img/img/img/img/img/img/img/img/ganttex09.png" WIDTH="502"></A><BR><B>Figure 156:</B> Specifying an absolute size for the height of thebar. <A href="exframes/frame_ganttex09.html" target="blank">[src]</A> <P></P></DIV></P><P> It is worth noting that the height reserved for each bar is stillthe same since we haven't changed the height of the marker and thereserved space is the maximum height used by any bar.</P><H3><A NAME="9_7_6">9.7.6 Adjusting the minimum distance between bars</A></H3><P> Let's see what happens if we set the height of each bar to be 100%of the reserved height by adding another activity/bar below the firstone and set the height of each bar to 100% by adding the lines (We omitthe added lines to add another bar since they are just a copy of thefirst bar)<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $activity</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetHeight</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">1.0</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">$activity2</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetHeight</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">1.0</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> to the previous example. (Note that a value in the range [0..1] isinterpretated as the fraction of the reserved height while a value > 1is interpretated as the absolute size in pixels.)<DIV class="example"><BR> <A href="exframes/frame_ganttex10.html" target="blank"><IMG border="0"HEIGHT="243" src="img/img/img/img/img/img/img/img/ganttex10.png" WIDTH="502"></A><BR><B>Figure 157:</B> Setting the height for each bar to 100% <A href="exframes/frame_ganttex10.html"target="blank">[src]</A> <P></P></DIV></P><P> Aha.. What we are trying to do doesn't really make sense. Since wehave specified that the bar will always occupy 100% of the availablereserved with there will be no distance between the bars. So what if wespecify the bar as 10 pixel absolute by changing the lines to<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $activity</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">SetHeight</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">10</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$activity2</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetHeight</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">10</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> we instead get<DIV class="example"><BR> <A href="exframes/frame_ganttex11.html" target="blank"><IMG border="0"HEIGHT="243" src="img/img/img/img/img/img/img/img/ganttex11.png" WIDTH="502"></A><BR><B>Figure 158:</B> Setting both bars height to 10 pixels <A href="exframes/frame_ganttex11.html"target="blank">[src]</A> <P></P></DIV></P><P> So what can we actually do? Well if you remember the reserved heightfor each bar is the maximum height of all bars including titles. Thisguarantees that no two bars will ever overlap. To guarantee that titlesdon't end up too close together there is a<B> Vertical Label Margin</B>which basically specifies some extra "air" in between the titles. Theamount of air is specified in percent of the title height. To set themargin you use<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> GanttGraph</FONT><FONT color="#007700">::</FONT><FONT color="#0000BB">SetLabelVMarginFactor</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$aMargin</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> As an example let's set that margin in the previous example to 0 andsee what happens.<DIV class="example"><BR> <A href="exframes/frame_ganttex12.html" target="blank"><IMG border="0"HEIGHT="212" src="img/img/img/img/img/img/img/img/ganttex12.png" WIDTH="502"></A><BR><B>Figure 159:</B> Setting the vertical label margin to 0% <A href="exframes/frame_ganttex12.html"target="blank">[src]</A> <P></P></DIV></P><P> As you would perhaps expect the two bars just barely touches nowsince there are no extra margin added. If the two bars hadn't had theextra right marker it would have looked very compressed.</P><P> By default the vertical margin is set to 40%.</P><H2><A NAME="9_8">9.8 Formatting the scale headers</A></H2><P> The scale headers allow you to view up to four different scales atthe same time. The four basic scales are:</P><UL><LI> Day scale</LI><LI> Week scale</LI><LI> Month scale</LI><LI> Year scale</LI></UL><P> You can choose what scale to include and exclude by using theSetScale() method. For example, for a detailed gantt you might chooseto display days and weeks by specifying<DIV class="phpscript"><CODE><FONTcolor="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">ShowHeaders</FONT><FONT color="#007700">( </FONT><FONT color="#0000BB">GANTT_HWEEK </FONT><FONT color="#007700">| </FONT><FONT color="#0000BB">GANTT_DAY </FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P> If you instead wanted "the big picture" it might be enough to showyear and months by specifying<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">ShowHeaders</FONT><FONT color="#007700">( </FONT><FONT color="#0000BB">GANTT_YEAR </FONT><FONT color="#007700">| </FONT><FONT color="#0000BB">GANTT_MONTH </FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> You can choose freely the combination of scales that you want, but achart must at least have one scale of course.</P><P> Once you have decided what level of details you need you can thenfine tune the exact layout/formatting of each of the enabled scales asdescribed below.</P><P> These scale header are all accessed through the graph instancevariables 'scale' as in<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">week</FONT></FONT></CODE></DIV></P><P> or<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">scale</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">day</FONT></FONT></CODE></DIV></P><P>. All these headers share the following properties.</P><UL><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> Show</FONT><FONT color="#007700">()</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P> Determine if the scale should be shown or not</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> SetFont</FONT><FONT color="#007700">()</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P>Font for text in header</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> SetFontColor</FONT><FONT color="#007700">()</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P> Specify the color of the header text</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> SetStyle</FONT><FONT color="#007700">()</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P>Specify what date format should be used, for example in the weekscale it is possible to show either week number, the start date of theweek and so on.</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> SetBackgroundColor</FONT><FONT color="#007700">()</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P>As it says, the background color for the header</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> SetFrameWeight</FONT><FONT color="#007700">()</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P>The line weight of the box around the scale</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> SetFrameColor</FONT><FONT color="#007700">()</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P>The line color for the frame</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> SetTitleVertMargin</FONT><FONT color="#007700">()</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P>The margin, in percent, below and above the title text</P></LI></UL><P> In addition to these methods each scale also has the property 'grid'which determines the appearance of grid lines for that specific scale.You may modify the appearance of grid lines by the "normal" linemethods, i.e. SetColor(),SetWeight() SetStyle() and Show(). So forexample to set the week grid line red you would use<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">week</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">grid</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONTcolor="#007700">(</FONT><FONT color="#DD0000">"red"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> Each of the scales also have some specific formatting possibilitiesas described below.</P><H3><A NAME="9_8_1">9.8.1 Minute scale</A></H3><P> Minute scale is the lowest resolution you can use. It is oftenconvenient to use Minute scale with "GanttScale::SetINtervall()" sinceby default the increment will be 1 minute. The style of minute scalecan be further adjusted by the use<I> style</I> parameters which can beone of</P><OL><LI> "MINUTESTYLE_MM", This will display minutes as a two digit numberwith a leading zero if necessary</LI><LI> "MINUTESTYLE_CUSTOM", This will let you specify you own customminute style by making a call to<I> HeaderProperty:: SetFormatString()</I></LI></OL><P> Minute scale is enabled by adding the GANTT_HMIN in theGanttGraph::ShowHeaders() call. For example as in<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">ShowHeaders</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">GANTT_HDAY </FONT><FONT color="#007700">| </FONT><FONT color="#0000BB">GANTT_HHOUR </FONT><FONT color="#007700">| </FONT><FONT color="#0000BB">GANTT_HMIN</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The code snippet below shows how to set up a minute scale with 30min interval and some custom colors.<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">minute</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetIntervall</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">30</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">minute</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetBackgroundColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'lightyellow:1.5'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">minute</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">FF_FONT0</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">minute</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetStyle</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">MINUTESTYLE_MM</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">minute</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">grid</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'lightgray'</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><H3><A NAME="9_8_2">9.8.2 Hour scale</A></H3><P> The hour scale has more builtin formatting possibilities. Thefollowing formatting options are available</P><OL><LI> "HOURSTYLE_HM24", Will display the only the hour in military time0-24 , for example 13:00</LI><LI> "HOURSTYLE_H24", Will display the hour with both hour and minute inmilitary time 0-24, for example 13</LI><LI>"HOURSTYLE_HMAMPM", Will display the hour and minutes with asuitable am/pm postfix, for example 1:30pm</LI><LI> "HOURSTYLE_HAMPM", Will display only the hour with a suitable am/pmpostfix, for example 1pm</LI><LI>"HOURSTYLE_CUSTOM", Custom defined format as specified with a callto HeaderProperty::SetFormatString()</LI></OL><P> For hours it is possible to specify the interval in either of twoways. With an integer, e.g. 6, or as time interval, e.g. "1:30" whichmakes the interval one and a half hour. The only restriction is thatthe interval must be even dividable for 24 hours since one day is thesmallest possible interval to show. This means that it is allowed touse, for example 2,4,6,"1:30" or "0:45" as intervals but not 7, "2:45".</P><P> The code snippet below shows hot to set up a hour scale to with 45minutes interval and some custom colors<DIV class="phpscript"><CODE><FONTcolor="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">hour</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetBackgroundColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'lightyellow:1.5'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">hour</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONTcolor="#007700">(</FONT><FONT color="#0000BB">FF_FONT1</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">hour</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetStyle</FONT><FONTcolor="#007700">(</FONT><FONT color="#0000BB">HOURSTYLE_HMAMPM</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">hour</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetIntervall</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"0:45"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The example below shows a gantt chart with the day and hour scaleenabled<DIV class="example"><BR> <A href="exframes/frame_gantthourex1.html" target="blank"><IMG border="0"HEIGHT="173" src="img/img/img/img/img/img/img/img/gantthourex1.png" WIDTH="545"></A><BR><B>Figure 160:</B> Using hour scale in the Gantt chart <A href="exframes/frame_gantthourex1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="9_8_3">9.8.3 Day scale</A></H3><P> By default the day scale show the first letter of the week day butit is also posible to format the day scale in a number of differentways. Days can have one of the following scale formats.</P><UL><LI>DAYSTYLE_ONELETTER, On letter week day. Example "M"</LI><LI>DAYSTYLE_LONG, Full week day. Example "Monday"</LI><LI>DAYSTYLE_LONGDAYDATE1, Day with date. Example "Monday 23 Jun"</LI><LI>DAYSTYLE_LONGDAYDATE2, Day with date+year. Example "Monday 23 Jun2003"</LI><LI>DAYSTYLE_SHORT, Short date. Example "Mon"</LI><LI>DAYSTYLE_SHORTDAYDATE1, Short date+date. Example "Mon 23/6"</LI><LI>DAYSTYLE_SHORTDAYDATE2, Short date+date. Example "Mon 23 Jun"</LI><LI>DAYSTYLE_SHORTDAYDATE3,Short date+date. Example "Mon 23"</LI><LI>DAYSTYLE_SHORTDATE1, Short date. Example "23/6"</LI><LI>DAYSTYLE_SHORTDATE2, Short date. Example "23 Jun"</LI><LI>DAYSTYLE_SHORTDATE3, Short date. Example "Mon 23"</LI><LI>DAYSTYLE_SHORTDATE4, Short date. Example "23"</LI><LI>DAYSTYLE_CUSTOM, Custom specified formatting string. Example "M"</LI></UL><P> The formatting is specified by using the SetStyle() method as in<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">day</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetStyle</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">DAYSTYLE_LONG</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The graphical formatting possibilities for days allow thepossibility to specify a different color for the weekend background andalso for the Sunday.</P><UL><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> SetWeekendColor</FONT><FONT color="#007700">()</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P>Set the background color for weekends. (Defaults to light gray)</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> SetSundayFontColor</FONT><FONT color="#007700">()</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P>The Sunday font color. (Defaults to red)</P></LI></UL><P> In addition to this there is also a possibility to choose whether ornot the weekend background should be extended vertically down over theplot area. (the default). Since that is a property more of the wholeplot this behavior is modified with a call to the method<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> UseWeekendBackground</FONT><FONTcolor="#007700">()</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P>of the scale, e.g.<BR> <DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">scale</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">UseWeekendBackground</FONT><FONTcolor="#007700">(</FONT><FONT color="#0000BB">false</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><H3><A NAME="9_8_4">9.8.4 Week scale</A></H3><P> Week scales, if enabled, by default shows the week number in range 1to 53 (as defined by ISO-8601, see the reference section).</P><P> It might be worth pointing out here that the week number calculationis carried out within JpGraph and does not rely on the underlying OSdate libraries. This makes the behavior consistent over several OS:s(at least M$ Windows does<B> not</B> comply to ISO-8601 or supply anyway of doing this through the normal libraries, e.g. strftime())</P><P> You may modify the week behavior in three ways. You can specify(with SetStyle()) a different date format using the constants</P><UL><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> WEEKSTYLE_WNBR</FONT></FONT></CODE></DIV><P> Show week number To further modify the formatting of the actual weeknumber you can optionally supply a format string with a call to<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> SetLabelFormatString</FONT><FONTcolor="#007700">()</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The format of the string should be a standard sprintf() syntaxexpecting an integer (the week number). By default a 'W' is prefixed tothe number.</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> WEEKSTYLE_FIRSTDAY</FONT></FONT></CODE></DIV><P> Show date of first day in week.</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> WEEKSTYLE_FIRSTDAY2</FONT></FONT></CODE></DIV><P> Show date of first day in week and short month</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> WEEKSTYLE_FIRSTDAYWNBR</FONT></FONT></CODE></DIV><P> Show weeknumber of first day in week.</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> WEEKSTYLE_FIRSTDAY2WNBR</FONT></FONT></CODE></DIV><P> Show weeknumber of first day in week and month</P></LI></UL><P></P><H3><A NAME="9_8_5">9.8.5 Month scale</A></H3><P> For month scale you can use the SetStyle() method to choose betweena variety of formats.</P><UL><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> MONTHSTYLE_SHORTNAME</FONT></FONT></CODE></DIV><P>Display the month name in its locale specific short form, i.e Jan,Feb etc</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> MONTHSTYLE_SHORTNAMEYEAR2</FONT></FONT></CODE></DIV><P>Display the month name in its locale specific short form togetherwith a 2 digit year , i.e Jan '01, Feb '01 etc</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> MONTHSTYLE_SHORTNAMEYEAR4</FONT></FONT></CODE></DIV><P>Display the month name in its locale specific short form togetherwith a 4 digit year , i.e Jan 2001, Feb 2001 etc</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> MONTHSTYLE_LONGNAME</FONT></FONT></CODE></DIV><P>Display the month name in its locale specific long name, i.e.January, February</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> MONTHSTYLE_LONGNAMEYEAR2</FONT></FONT></CODE></DIV><P>Display the month name in its locale specific long name together witha 2 digit year , i.e January '01, February '01 etc</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> MONTHSTYLE_LONGNAMEYEAR4</FONT></FONT></CODE></DIV><P>Display the month name in its locale specific long name together witha 4 digit year , i.e January 2001, February 2001 etc</P></LI><LI><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> MONTHSTYLE_FIRSTLETTER</FONT></FONT></CODE></DIV><P>The first letter of the month name</P></LI></UL><P></P><H3><A NAME="9_8_6">9.8.6 Year scale</A></H3><P> Year scale has no extra formatting possibilities.</P><H2><A NAME="9_9">9.9 More formatting for bars</A></H2><P> This section shows some further modification you might do toactivity bars.</P><H3><A NAME="9_9_1">9.9.1 Adding caption to bars</A></H3><P> Caption for bars are placed at the far right side of the bars. Theycan for example be used to indicate the resources assigned to a task,the duration of the task or the progress of the activity.</P><P> Caption text for a bar is specified either when creating a bar orlater by accessing the 'caption' property of bars. So the two lines<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $activity </FONT><FONTcolor="#007700">= new </FONT><FONT color="#0000BB">GanttBar</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONTcolor="#DD0000">"Activity 1"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"2001-11-21"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"2001-12-20"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"[BS,ER]"</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> and<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $activity</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">caption</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONTcolor="#007700">(</FONT><FONT color="#DD0000">"[BS,ER]"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> are both ways of specifying the caption "[BS,ER]" for the activity.Since activity is a standard JpGraph text object you can easily modifyfont, color and size with calls to SetFont() and SetColor(), (e.g.<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $activity</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">caption</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">FF_ARIAL</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FF_BOLD</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">9</FONT><FONTcolor="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> The figure below illustrates the use of caption<DIV class="example"><BR> <A href="exframes/frame_ganttex13.html" target="blank"><IMG border="0"HEIGHT="186" src="img/img/img/img/img/img/img/img/ganttex13.png" WIDTH="409"></A><BR><B>Figure 161:</B> Illustration of the use of captions <A href="exframes/frame_ganttex13.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="9_9_2">9.9.2 Adding progress indicators to bars</A></H3><P> To indicate the progress of a specific activity it is also possibleto add a progress indicator to each bar. This progress indicatorconsists of a smaller bar within the bar. By default this progress baris black and 70% of the height of the bar. These parameter can (ofcourse) all be changed.</P><P> The properties for the progress indicator are accessed through the'progress' property and it's methods.</P><P> To set the progress for a specific activity you only specify thepercent as a fraction. As in<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $activity</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">progress</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">0.4</FONT><FONTcolor="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> In Figure 162 the previous example is modified to indicate theprogress of each activity by the default progress indicator. A solidbar. To make it clearer we have also modified the caption to reflectthe displayed progress. (At the same time we also modified the scaleheaders just to illustrate some more formatting options).<DIV class="example"><BR> <A href="exframes/frame_ganttex14.html" target="blank"><IMG border="0"HEIGHT="191" src="img/img/img/img/img/img/img/img/ganttex14.png" WIDTH="409"></A><BR><B>Figure 162:</B> Adding progress indicators. <A href="exframes/frame_ganttex14.html"target="blank">[src]</A> <P></P></DIV></P><P> To specify a different format for the progress you use theSetPattern() method as in<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $activity</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">progress</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetPattern</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">BAND_RDIAG</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"blue"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> In the reference section you can see the exact parameters and allavailable methods.<DIV class="example"><BR> <A href="exframes/frame_ganttex15.html" target="blank"><IMG border="0"HEIGHT="191" src="img/img/img/img/img/img/img/img/ganttex15.png" WIDTH="409"></A><BR><B>Figure 163:</B> Changing the style of the progress indicators. <A href="exframes/frame_ganttex15.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H2><A NAME="9_10">9.10 Grouping activities</A></H2><P> It is common to group activities. We have used this feature in theexamples of constrains. There is no special type for activity bars thatare used to illustrate grouping. The common way of illustrating this(as have been used above) is to add "half" a triangle marker at bothends of the bar. The special provision that JpGraph does is that if youadd a left or right marker of type MARK_LEFTTRIANGLE orMARK_RIGHTTRIANGLE those triangles will be drawn under the bars to givethe effect as show in the examples above. In the example above we alsohave made the grouping bars have slightly less heigh since the endtriangles will visually "grow" the bar.</P><P> So to get the effect we want for a group bar we have to use the twolines:<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $groupbar</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">leftMark</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetType</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"MARK_LEFTTRIANGLE"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$groupbar</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">rightMark</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetType</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"MARK_RIGHTTRIANGLE"</FONT><FONT color="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> As of the current version There is not yet any formatting support toaccomplish the effect of indentation for the titles so this isaccomplished by using a fixed width font and adding spaces in front ofthe title.</P><H2><A NAME="9_11">9.11 Using multiple columns as titles</A></H2><P> It is often of interest not only to show one title for a gantt barbut often one wants to show, title, start date, end date, duration oreffort and so on. Up until now we have, to keep things simple onlyshown a single title for each activity. We will now show you how youcan specify an arbitrary number of columns as titles for a Gantt chartas well as adding icons in the graph columns.</P><P> First out is an example to help visualize what we will achieve<DIV class="example"><BR> <A href="exframes/frame_gantticonex1.html" target="blank"><IMG border="0"HEIGHT="197" src="img/img/img/img/img/img/img/img/gantticonex1.png" WIDTH="590"></A><BR><B>Figure 164:</B> A Gantt chart with multiple columns <A href="exframes/frame_gantticonex1.html"target="blank">[src]</A> <P></P></DIV></P><P> To use multiple columns there is two steps. First you need to setthe titles (name, color, fonts etc). Thereafter you need to add thetitle columns for each individual bar.</P><P> To set the columns you will have to work with the<I> Activityinformation</I> property of the scale. The following code excerpt showthis<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">scale</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">actinfo</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColTitles</FONT><FONT color="#007700">(<BR> array(</FONT><FONT color="#DD0000">'Note'</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">'Task'</FONT><FONT color="#007700">,</FONT><FONTcolor="#DD0000">'Duration'</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">'Start'</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">'Finish'</FONT><FONT color="#007700">),array(</FONT><FONT color="#0000BB">30</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">100</FONT><FONTcolor="#007700">));</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P>You will notice two things. We fist specify the titles using anarray. We have also specified a second array with the numbers 30 and100. This is an optional array that specifies the minimum width of, inthis case, the first two columns. By default the columns will be wideenough to hold the widest text string in the column. However foresthetic reasons you might sometimes want to increase the minium width.This is what we have done here for the first two columns.</P><P> Furthermore you can also adjust the background colors and the styleand colors of the vertical dividing grid lines. In the previous imagewe used the lines<DIV class="phpscript"><CODE><FONT color="#000000"> <FONTcolor="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">actinfo</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">SetBackgroundColor</FONT><FONTcolor="#007700">(</FONT><FONT color="#DD0000">'green:0.5@0.5'</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">actinfo</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">FF_ARIAL</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FS_NORMAL</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">10</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">actinfo</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">vgrid</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">SetStyle</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'solid'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">actinfo</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">vgrid</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'gray'</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P> The style for the grid lines can also be "dashed", "dotted" or"longdashed" as in other line formatting contexts within the library.You can also adjust if you would like the small "3D" effect in thetitles. By default this is enabled. You can easily turn this of with acall to<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">scale</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">actinfo</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetStyle</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">ACTINFO_2D</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> To adjust the colors of the vertical dividing lines in the title themethod SetColor() is used as in"$graph->scale->actinfo->SetColor('navy');".</P><P> The second thins is to actually populate the columns. This is done(of course) as you add the activity bars to the graph. Previous we justused a string as the title when we wasn't using columns. By simplyreplacing this string with an array we specify the content of thecolumns.</P><P> For example to specify two column titles we just create ahypothetical Gantt bar as In the full example above we put all this inarrays to make for better coding practice since we create several bars.</P><P> In addition to ordinary text you can also add an image or any of thepredefined icons available. In order to add that in a column you firstcreate an instance of<I> IconImage()</I> and then specify that instanceinstead of the text. So in the previous code snippet if we wanted a"open folder" image in the first column we would change the lines to<DIVclass="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $iconopen </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">IconImage</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">GICON_FOLDEROPEN</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0.6</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$title2</FONT><FONT color="#007700">=</FONT><FONTcolor="#DD0000">""</FONT><FONT color="#007700">;<BR></FONT><FONT color="#0000BB">$bar </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">GanttBar</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,array(</FONT><FONTcolor="#0000BB">$iconopen</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$title2</FONT><FONT color="#007700">),</FONT><FONT color="#DD0000">"2003-11-23"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"2003-12-05"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The available builtin icons are</P><UL><LI>GICON_WARNINGRED</LI><LI>GICON_TEXT</LI><LI>GICON_ENDCONS</LI><LI>GICON_MAIL</LI><LI>GICON_STARTCONS</LI><LI>GICON_CALC</LI><LI>GICON_MAGNIFIER</LI><LI>GICON_LOCK</LI><LI>GICON_STOP</LI><LI>GICON_WARNINGYELLOW</LI><LI>GICON_FOLDEROPEN</LI><LI>GICON_FOLDER</LI><LI>GICON_TEXTIMPORTANT</LI></UL><P> In addition you can also use any of you own images if you specifythe argument as a string, for example<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $myicon </FONT><FONT color="#007700">= </FONT><FONTcolor="#0000BB">IconImage</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'myicon.png'</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> If you wonder, the second argument in the<I> IconImage()</I> call isan optional scaling factor which you can use to adjust the size of theimage.</P><H3><A NAME="9_11_1">9.11.1 Adding a title for the columns</A></H3><P> Precisely as before you can also have a title spanning all thecolumns. This title is specified with the property<I> tableTitle</I> ofthe scale. Specifying a table title will automatically adjust theheight of the column titles to fit the table title. The small codesnippet below shows how to add a title.<DIV class="phpscript"><CODE><FONTcolor="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">tableTitle</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'Phase 1'</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">tableTitle</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">FF_ARIAL</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FS_NORMAL</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">12</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetTableTitleBackground</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'darkgreen@0.6'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">tableTitle</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Show</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">true</FONT><FONTcolor="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> A full example of this is shown below<DIV class="example"><BR> <A href="exframes/frame_gantthourminex1.html" target="blank"><IMG border="0"HEIGHT="215" src="img/img/img/img/img/img/img/img/gantthourminex1.png" WIDTH="1200"></A><BR><B>Figure 165:</B> Adding a column titles stratching all titlecolumns. <A href="exframes/frame_gantthourminex1.html" target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="9_11_2">9.11.2 Specifying CSIM entries for column titles</A></H3><P> In exactly the same way as for a single title it is possible tospecify individual CSIM targets for each of the title columns. This isaccomplished by specifying an array for both the target and the alttext instead of a single string as arguments for<I> SetCSIMTarget()</I>The following code snippet shows how to specify that.<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $bar</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetCSIMTarget</FONT><FONT color="#007700">(array(</FONT><FONTcolor="#DD0000">'sometarget1.html'</FONT><FONT color="#007700">,</FONT><FONTcolor="#DD0000">'sometarget1.html'</FONT><FONT color="#007700">),<BR>array(</FONT><FONT color="#DD0000">'alttext1'</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">'alttext2'</FONT><FONT color="#007700">));</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><H2><A NAME="9_12">9.12 More general Gantt formatting</A></H2><P> In this section we will show a few more way by which you maycustomize the gantt chart itself. This includes</P><UL><LI> Adding a table title (not to be confused with the graph title)</LI><LI> Adjusting appearance of the various lines in the bar chart</LI></UL><P></P><H3><A NAME="9_12_1">9.12.1 Adding a table title</A></H3><P> The (default) white area in the top left of the gantt table may havea title. This is accessed by the 'tableTitle' property of the ganttscale. Using this is straightforward as the following lines show.<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">tableTitle</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"(Rev: 1.22)"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">tableTitle</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">FF_FONT1</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FS_BOLD</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetTableTitleBackground</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"silver"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">tableTitle</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Show</FONT><FONT color="#007700">();</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The example lines above also changes the default white background tosilver. Adding these lines to the previous example gives the followingresult:<DIV class="example"><BR> <A href="exframes/frame_ganttex16.html" target="blank"><IMG border="0"HEIGHT="191" src="img/img/img/img/img/img/img/img/ganttex16.png" WIDTH="439"></A><BR><B>Figure 166:</B> Adding a table title. <A href="exframes/frame_ganttex16.html"target="blank">[src]</A> <P></P></DIV></P><P> From the above example you might notice that the width of the leftcolumn (which holds all the titles) have automatically adjusted itselfto make the table title fit.</P><H3><A NAME="9_12_2">9.12.2 Modifying the divider lines</A></H3><P> The vertical and horizontal lines between the titles and the barscan be modified by accessing the 'divider' and 'dividerh' properties ofthe scale. Again, this is straightforward as the following exampleshows:<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">scale</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">divider</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetWeight</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">3</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">divider</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"navy"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">dividerh</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetWeight</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">3</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">dividerh</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"navy"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The effect of this is shown in Figure 167 below<DIV class="example"><BR> <A href="exframes/frame_ganttex17.html" target="blank"><IMG border="0"HEIGHT="191" src="img/img/img/img/img/img/img/img/ganttex17.png" WIDTH="433"></A><BR><B>Figure 167:</B> Modifying the dividing line <A href="exframes/frame_ganttex17.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="9_12_3">9.12.3 Modifying the box around the plot</A></H3><P> In a similar manner to the other plots in JpGraph you modify the Boxround the plot with the standard graph method 'SetBox()' as in<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetBox</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">true</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"navy"</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">3</FONT><FONTcolor="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> which will result in a thicker plot box around the area as shownbelow<DIV class="example"><BR> <A href="exframes/frame_ganttex18.html" target="blank"><IMG border="0"HEIGHT="191" src="img/img/img/img/img/img/img/img/ganttex18.png" WIDTH="433"></A><BR><B>Figure 168:</B> Modifying the box around the plotarea <A href="exframes/frame_ganttex18.html"target="blank">[src]</A> <P></P></DIV></P><P><DIV class="note"><B>Note:</B> You might notice the slightdiscrepancy in design that here you use a method and in the previouscases accessed a property which you modified. This is the unfortunateaffect of the evolving design and development of this library once itwas realised that the original design could be improved upon.</DIV></P><H3><A NAME="9_12_4">9.12.4 Horizontal grids and alternating line colors</A></H3><P> In order to make large charts easier to read it is possible tospecify alternating an horizontal grid and optional alternating linecolors in the background for Gantt charts. The horizontal grid isaccessed through the<I> Graph::hgrid</I> property and the line (used inthe grid) is accessed through the<I> Graph::hgrid::line</I>sub-property</P><P> In order to specify the alternating line colors the<I>SetRowFillColor()</I> method is used. For example, to use alternatingblue background with blue grid line the following lines would have tobe added to the graph script<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> </FONT><FONT color="#FF8000">// Setup a horizontal grid<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">hgrid</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Show</FONT><FONT color="#007700">();<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">hgrid</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">line</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONTcolor="#007700">(</FONT><FONT color="#DD0000">'lightblue'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">hgrid</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetRowFillColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'darkblue@0.9'</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> Below is an example of a Gantt graph using this formatting<DIV class="example"><BR> <A href="exframes/frame_gantthgridex1.html" target="blank"><IMG border="0"HEIGHT="253" src="img/img/img/img/img/img/img/img/gantthgridex1.png" WIDTH="500"></A><BR><B>Figure 169:</B> Adding a horizontal grid to the graph <A href="exframes/frame_gantthgridex1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><H3><A NAME="9_12_5">9.12.5 Adding icons to Gantt graphs</A></H3>As is illustrated in the image above it is also possible (just like fornormal Graph) to add small images (or icons) to a Gantt graph bycreating an IconPlot() instance and then adding it to the graph. In theimage above the following lines were used to add the small image of"tux" in the left lower corner<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $icon </FONT><FONT color="#007700">= new </FONT><FONTcolor="#0000BB">IconPlot</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'penguin.png'</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0.01</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0.95</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">1</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">15</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$icon</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetAnchor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'left'</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">'bottom'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Add</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$icon</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P></P><H3><A NAME="9_12_6">9.12.6 Adjusting the margins with auto-sizing</A></H3>As of version 1.17 it is possible to use Graph::SetMargin() to specifythe margin for a Gantt graph even when the vertical height isdetermined automatically. For example to generate a graph with no left,right or bottom margin the following lines would be needed<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">GanttGraph</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">500</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetMargin</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">30</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV><P></P><H2><A NAME="9_13">9.13 Simplifying the drawing of Gantt graphs</A></H2><P> As we have shown in the previous examples constructing a Gantt chartconsists of a number of repetitive tasks; Create the individualactivity bars and add them to the graph.</P><P> Now when you have a basic understanding of how this works you areready to appreciate a small helper method. <A href="">GanttGraph::CreateSimple()</A>. This method takes a few arrays of datawhich specifies you Gantt chart and then constructs this chart. Byusing this method you sacrifices a few adjustment possibilities forsimplicity. This method is nothing magical it just takes the data forthe activities,(start and end date, titles, progress, any constrainsand so on) and constructs the activities and adds them to the graph.</P><P> The activities are specified in data array which for each activityhave the following fields</P><UL><LI> What row the activity should be on</LI><LI> Activity type, controls the appearance. Can be one of<OL><LI> ACTYPE_NORMAL, A standard activty bar</LI><LI> ACTYPE_GROUP, A Grouping bar</LI><LI> ACTYPE_MILESTONE, A milestone</LI><LI></LI></OL><P></P></LI><LI> Title text</LI><LI> Start date</LI><LI> End date (NOT FOR Milestones!)</LI><LI> Caption</LI></UL><P></P><P> So for example to create a Gantt chart consisting of two activitieswhich are grouped and a milestone one would have to use somethingsimilar to the following code</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $data </FONT><FONT color="#007700">= array(<BR> array(</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">ACTYPE_GROUP</FONT><FONT color="#007700">, </FONT><FONTcolor="#DD0000">"Phase 1"</FONT><FONT color="#007700">, </FONT><FONTcolor="#DD0000">"2001-10-26"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"2001-11-23"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">""</FONT><FONT color="#007700">),<BR> array(</FONT><FONT color="#0000BB">1</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">ACTYPE_NORMAL</FONT><FONT color="#007700">, </FONT><FONTcolor="#DD0000">" Label 2"</FONT><FONT color="#007700">, </FONT><FONTcolor="#DD0000">"2001-10-26"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"2001-11-13"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"[KJ]"</FONT><FONT color="#007700">),<BR> array(</FONT><FONT color="#0000BB">2</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">ACTYPE_NORMAL</FONT><FONT color="#007700">, </FONT><FONTcolor="#DD0000">" Label 3"</FONT><FONT color="#007700">, </FONT><FONTcolor="#DD0000">"2001-11-20"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"2001-11-22"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"[EP]"</FONT><FONT color="#007700">),<BR> array(</FONT><FONT color="#0000BB">3</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">ACTYPE_MILESTONE</FONT><FONT color="#007700">,</FONT><FONTcolor="#DD0000">" Phase 1 Done"</FONT><FONT color="#007700">, </FONT><FONTcolor="#DD0000">"2001-11-23"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"M2"</FONT><FONT color="#007700">) );<BR><BR></FONT><FONT color="#FF8000">// Create the basic graph<BR></FONT><FONT color="#0000BB">$graph </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">GanttGraph</FONT><FONT color="#007700">();<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"Gantt Graph using CreateSimple()"</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Setup scale<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">ShowHeaders</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">GANTT_HYEAR </FONT><FONT color="#007700">| </FONT><FONT color="#0000BB">GANTT_HMONTH </FONT><FONT color="#007700">| </FONT><FONT color="#0000BB">GANTT_HDAY </FONT><FONT color="#007700">| </FONT><FONT color="#0000BB">GANTT_HWEEK</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">week</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetStyle</FONT><FONTcolor="#007700">(</FONT><FONT color="#0000BB">WEEKSTYLE_FIRSTDAY</FONT><FONTcolor="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Add the specified activities<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">CreateSimple</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$data</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// .. and stroke the graph<BR></FONT><FONT color="#0000BB">$graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Stroke</FONT><FONT color="#007700">();<BR></FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> This will then show up as<DIV class="example"><BR> <A href="exframes/frame_ganttsimpleex1.html" target="blank"><IMG border="0"HEIGHT="231" src="img/img/img/img/img/img/img/img/ganttsimpleex1.png" WIDTH="523"></A><BR><B>Figure 170:</B> Using the simplified way via CreateSimple()method <A href="exframes/frame_ganttsimpleex1.html" target="blank">[src]</A> <P></P></DIV></P><P> You may (slightly) modify the appearance of the simple Gantt chartsby means of the methods <A href="">GanttGraph::SetSimpleFont()</A> and <Ahref="">GanttGraph::SetSimpleStyle()</A> But not anything else, rememberthat the purpose with this way of constructing graphs is to be simple.If you need full advanced control you have to construct all theactivities in the "normal" way.</P><P> You can also specify constrains and progress for each bar bysupplying additional data arrays to GanttGraph::CreateSimple().</P><H2><A NAME="9_14">9.14 Adding CSIM (Client side Image Maps) to Ganttcharts</A></H2><P> Gantt charts can have independent (different targets) hot spots inboth the activities and in the associated labels for each activity.</P><P> You specify the target and the associated "Alt" text for an activitybar by calling the <A href="../ref/GanttPlotObject.html#_GANTTPLOTOBJECT_SETCSIMTARGET">GanttBar::SetCSIMTarget()</A> and <A href="../ref/GanttPlotObject.html#_GANTTPLOTOBJECT_SETCSIMALT">GanttBar::SetCSIMAlt()</A></P><P> In a similar way you set the target and Alt texts for the activitytitle as the following code extract shows.<DIV class="phpscript"><CODE><FONTcolor="#000000"> <FONT color="#0000BB"> $bar</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetCSIMTarget</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"http://localhost/abc/"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$bar</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetCSIMAlt</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"Alt Text for the bar"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$bar</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetCSIMTarget</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"http://localhost/abc"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$bar</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">title</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetCSIMAlt</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"Alt Text for the title"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The above code assumes that your activity is available in thevariable 'bar'. In the example directory there is a complete example ofhow to use CSIM together with Gantt charts in the "ganttcsimex1.php"file. (Please note that this example makes use of the simplified Ganttchart specification using the CreateSimple() method.</P><H2><A NAME="9_15">9.15 Adding constrains between your activities</A></H2><P> With Gantt charts there is often the need to illustrate constrainsbetween one or several activities. One of the most common constrain isthat on activity can't start before an other activity finish.</P><P> JpGraph support visualizing the following types of constrains</P><UL><LI> Start to End</LI><LI> Start to Start</LI><LI> End to Start</LI><LI> End to End</LI></UL><P> An example will clarify how to specify a constrain between twoactivities.</P><P> Assume that we start with the Gantt schema as illustrated below<DIV class="example"><BR> <A href="exframes/frame_ganttconstrainex0.html" target="blank"><IMG border="0"HEIGHT="231" src="img/img/img/img/img/img/img/img/ganttconstrainex0.png" WIDTH="523"></A><BR><B>Figure 171:</B> The original Gantt schema we wich to addconstrains to <A href="exframes/frame_ganttconstrainex0.html" target="blank">[src]</A> <P></P></DIV></P><P> We would now like to add the constrains that the activity "Label 3"cant start before activity "Label 2" has finished and that themilestone "Phase 1 done" is depending on when activity "Label 3" isdone.</P><P> The principle of adding constrains is that you for each activity youwant to have a constrain you have to tell to what other activity thisconstrain should be to. That other activity is specified by telling onwhat row that activity lies. Depending on what type of constrain, e.g.Start-to-End, an arrow will now connect the two activities in correctway.</P><P> The way to do this is to call the <A href="../ref/GanttPlotObject.html#_GANTTPLOTOBJECT_SETCONSTRAIN">SetConstrain()</A> method on the activity. In this method you specifythe type of constrain as well as to what other activity this constrainshould be to. If you read the class reference you can also see that youcan specify the type and size of arrow used. For now we will just usethe default sizes and type.</P><P> So for example to add an End-To-Start constrain between "Label 2"and "Label 3" you could write<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $bar2</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetConstrain</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">2</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">CONSTRAIN_ENDSTART</FONT><FONTcolor="#007700">)</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The first parameter in the call above "2" is the row of the targetactivity (i.e. the row where "Label 3") activity is. In the examplebelow we have added the constrains we wanted.<DIV class="example"><BR> <A href="exframes/frame_ganttconstrainex1.html" target="blank"><IMG border="0"HEIGHT="253" src="img/img/img/img/img/img/img/img/ganttconstrainex1.png" WIDTH="523"></A><BR><B>Figure 172:</B> Adding constrains to a gantt chart <A href="exframes/frame_ganttconstrainex1.html"target="blank">[src]</A> <P></P></DIV></P><P> A note: The actual path followed by the arrow is controlled by someheuristics to make it clear what the constrain is. It has been a designdecision that in order to keep the API simple the user has no furtherdetailed controlled on the actual path followed. However, in futureversion the heuristics may be extended and provide someuser-controllable parameters.</P><H2><A NAME="9_16">9.16 Advanced formatting</A></H2><P></P><H3><A NAME="9_16_1">9.16.1 Showing only part of the graph</A></H3><P> You can choose to only display a vertical slice of the overall Ganttchart by explicitly specifying a date range with the methodGanttGraph::SetDateRange(). This will cap any bars to only be displayedin between the start and end date given as parameters. For examplespecifying<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetDateRange</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"2001-12-20"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"2002-01-20"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> will show the part of the Gantt chart between the 20 Dec 2001 and 20of January 2002. Please note that the format depends on the localesetting.</P><H3><A NAME="9_16_2">9.16.2 Specifying start day of week</A></H3><P> You can set the week start day with a call toGanttScale::SetWeekStart(). This method takes an integer [0,6] as inputwhich represents the start day of the week, 0 means Sunday, 1 Monday, 2Tuesday and so on. The default is to start the week on Monday.</P><H2><A NAME="9_17">9.17 Localizing</A></H2><P> Depending on your installation of PHP you might have support forseveral locales. By default the locale is set up to use the defaultlocale on the server.</P><P> To specifically set a locale you specify the wanted locale with alocale string (ala standard PHP), for example American English isspecified with the string 'EN_US', British English with 'EN_UK' 'nl_NL'for Dutch and so on. If your current installation does not support thespecified locale an error message will be given.<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetDateLocale</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"se_SE"</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> The result is displayed below.<DIV class="example"><BR> <A href="exframes/frame_ganttex19.html" target="blank"><IMG border="0"HEIGHT="191" src="img/img/img/img/img/img/img/img/ganttex19.png" WIDTH="431"></A><BR><B>Figure 173:</B> Using swedish locale. (Can you spot thedifference from English?) <A href="exframes/frame_ganttex19.html" target="blank">[src]</A> <P></P></DIV></P><P></P><H2><A NAME="9_18">9.18 Anti-aliasing in JpGraph</A></H2><P> From version 1.2 JpGraph supports drawing of anti-aliased lines.There are a few caveats in order to use this which is discussed in thissection.</P><P><DIV class="note"><B>Note:</B> Note that anti-aliasing will not beused for either horizontal, vertical or 45 degree lines since they areby their nature are sampled at adequate rate.</DIV></P><H3><A NAME="9_18_1">9.18.1 Enabling anti-aliased lines</A></H3><P> Anti-aliased lines are enabled by calling the method <A href="../ref/Image.html#_IMAGE_SETANTIALIASING">SetAntiAliasing()</A> in the <A href="../ref/Image.html#_C_IMAGE">Image class</A> in the script where you want to use anti-aliasing.</P><P> The anti-aliasing for lines works by "smoothing" out the edges onthe line by using a progressive scale of colors interpolated betweenthe background color and the line color.</P><P><DIV class="note"><B>Note:</B> The algorithm used for anti-aliasingof lines is quite simple. It would be possible to achieve even betterresult by doing some real 2D signal processing. However, doing realtime 2D signal processing on a HTTP server would be foolish so thedesign is deliberately kept simple. To achieve best visual resultalways use a dark line color on a light background.</DIV></P><P> An example will show that this, quite simple algorithm, gives areasonable good result. The figures below shows a radar plot with andwithout anti-aliasing.</P><P><DIV class="example"><BR> <A href="exframes/frame_radarex8.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/radarex8.png" WIDTH="300"></A><BR><B>Figure 174:</B> Spiderplot without anti-aliasing <A href="exframes/frame_radarex8.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P><DIV class="example"><BR> <A href="exframes/frame_radarex8.1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/radarex8.1.png" WIDTH="300"></A><BR><B>Figure 175:</B> Spiderplot with anti-aliasing <A href="exframes/frame_radarex8.1.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> One thing you need to keep in mind when deciding to useanti-aliasing is that it could have potentially a dramatic effect onthe time it takes to generate the image. Line drawing withanti-aliasing turned on is roughly 8 times slower than the normal linedrawing so treat this feature wisely.</P><P> Furthermore there are a couple of "gotchas" you should be aware ofwhen using anti-aliasing.</P><OL><LI> Anti-aliased lines uses up more of the available color-palette. Theexact number of colors used is dependent on the line-angle, a nearhorizontal or near vertical line uses more colors (number of lines withdifferent angles uses more colors). Hence it might not be possible touse anti-aliasing with color-gradient fill since the number ofavailable colors in the palette might not be enough. A normal palettecan keep around 256 colors. This means that you are advised to use atrue-color image when using anti-aliasing.</LI><LI> Anti-aliasing does not work very well together with backgroundimages since it assumes a the same solid color on each side of theline. Doing a more advanced anti-aliasing algorithm would simple taketo much processing power.</LI><LI>Anti-aliased lines will ignore the line width specified. They willalways have a width of roughly 1.</LI></OL><P></P><H2><A NAME="9_19">9.19 Rotating the graphs</A></H2><P> JpGraph provide the possibility for you to rotate the generatedgraph an arbitrary angle. This will only affect the actual graph (axis,axis titles, labels and so on) and not fixed elements on the graph liketitle or footer.</P><P> Rotation is probably most used to rotate a graph 90 degrees, forexample a bar graph to get the effect of horizontal bars.</P><P></P><HR> <SMALL><P><STRONG> Performance note:</STRONG> Adding a rotation transformationwill make the graph generation slightly slower since each point of thegraph as to go through a transformation step before being stroked on tothe image. JpGraph optimizes this by using a pre-calculatedtransformation matric and also optimizes the special case 90 degrees.</P></SMALL><HR><P> By default the center of the rotation will be the center of the plotarea, which may or may not coincide with the center of the entireimage.</P><P> To control the rotation you use the two methods</P><UL><LI> <A href="../ref/RotImage.html#_ROTIMAGE_SETANGLE">Graph::image::SetAngle()</A>, Specify rotation angle in degrees.</LI><LI> <A href="../ref/RotImage.html#_ROTIMAGE_SETCENTER">Graph::image::SetCenter()</A>, Specify center of rotation in absoluteimage pixels</LI></UL><P> For example<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">image</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">SetAngle</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">45</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> There is actually a third method that you could use, adding atranslation to the graph<STRONG> after</STRONG> the rotation. Sincethis probably a very little used method we don't discuss it further butrefer the reader to the class reference instead <A href="../ref/RotImage.html#_ROTIMAGE_SETTRANSLATION">Graph:image::SetTranslation()</A></P><P> When you rotate an image you should be aware of that the individuallabels on the axis are not rotated. The design decision behind this is<BR><STRONG> a)</STRONG> Bit mapped font can't be rotated<BR><STRONG> b)</STRONG> Maintain readability</P><P> Please remember that you may still rotate the labels by calling the <Ahref="../ref/Axis.html#_AXIS_SETLABELANGLE"> Axis::SetLabelAngle()</A>method.</P><P> Since the anchor point for labels is by default the optimum forgraph at 0 degree you might want to adjust the anchor point andalignment for the labels on the axis to get a better visual appearanceon you rotated graph. This is accomplished by the method <A href="../ref/Axis.html#_AXIS_SETLABELALIGN">Axis::SetLabelAlign()</A> For a detailed discussion on how to do thisplease see the section on horizontal bar graphs, ( <A href="3030barplot.html">Working with bar plots</A> )</P><P> The table below shows some examples on different kinds of rotationto give you an idea of how changing the angle and rotation center maybe used to generate different effects. The top left graph is theoriginal image. The point of rotation has been marked with a red-crossin each of the images.</P><P><DIV class="example"><BR> <A href="exframes/frame_rotex0.html" target="blank"><IMG border="0" HEIGHT="170"src="img/img/img/img/img/img/img/img/rotex0.png" WIDTH="270"></A><BR><B>Figure 176:</B> Original image <A href="exframes/frame_rotex0.html"target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_rotex1.html" target="blank"><IMG border="0" HEIGHT="170"src="img/img/img/img/img/img/img/img/rotex1.png" WIDTH="270"></A><BR><B>Figure 177:</B> Rotated 45 degrees around center of plot area <A href="exframes/frame_rotex1.html"target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_rotex2.html" target="blank"><IMG border="0" HEIGHT="170"src="img/img/img/img/img/img/img/img/rotex2.png" WIDTH="270"></A><BR><B>Figure 178:</B> Rotated 90 degrees around center of plot area <A href="exframes/frame_rotex2.html"target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_rotex3.html" target="blank"><IMG border="0" HEIGHT="170"src="img/img/img/img/img/img/img/img/rotex3.png" WIDTH="270"></A><BR><B>Figure 179:</B> Rotated 45 degrees around center of the image <A href="exframes/frame_rotex3.html"target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_rotex4.html" target="blank"><IMG border="0" HEIGHT="170"src="img/img/img/img/img/img/img/img/rotex4.png" WIDTH="270"></A><BR><B>Figure 180:</B> Rotated 90 degrees around center of the image <A href="exframes/frame_rotex4.html"target="blank">[src]</A> <P></P></DIV></P><P><DIV class="example"><BR> <A href="exframes/frame_rotex5.html" target="blank"><IMG border="0" HEIGHT="170"src="img/img/img/img/img/img/img/img/rotex5.png" WIDTH="270"></A><BR><B>Figure 181:</B> Rotated -30 degrees around the lower left pointof the plot area <A href="exframes/frame_rotex5.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P> As you can see from the images above if you rotate about any otherpoint than the center of the plot area the plot can be placed outsidethe image after rotation.</P><P> Since the rotation, by design, only affects the plot area it isoften most effective to use when the color of the margin is the same asthe background color.</P><H2><A NAME="9_20">9.20 Adjusting brightness and contrast for images andbackgrounds</A></H2><P><STRONG> The following section only applies to palette images. Thismeans it wont work on true-color images.</STRONG></P><P> It is often desirable to have a background image look a little bit"washed" out so it doesn't take the concentration away from the actualgraph. There are basically two ways of accomplish this</P><OL><LI> Prepare the image with an external images editor to adjust thelevel of brightness and contrasty to a desirable level</LI><LI> Use JpGraph:s built in adjustment for contrast, brightness andcolor saturation.</LI></OL><P> To adjust the background image call The levels for both brightnessand contrast are real numbers in the range [-1, 1] You can choose toadjust for example just the background image or you might also chooseto adjust the whole image. To change the background image just use themethod <A href="../ref/Graph.html#_GRAPH_ADJBACKGROUNDIMAGE">Graph::AdjBackgroundImage()</A> to specify a suitable value. Let's showsome example on what we can do with this. The following example havebeen generated by using the small utility "adjimg.php" which you canfind in the "utils/" directory.</P><P> <IMG alt="" border="0" HEIGHT="244" src="img/img/img/img/img/img/img/img/imgadj_orig.jpg" WIDTH="246"><BR> Brightness=0, contrast=0, saturation = -1 (Original image)</P><P> <IMG alt="" border="0" HEIGHT="244" src="img/img/img/img/img/img/img/img/imgadj_b00c00sat-1.jpg" WIDTH="246"><BR> Brightness=0, contrast=0, saturation = -1 (Black & White image)</P><P> <IMG alt="" border="0" HEIGHT="244" src="img/img/img/img/img/img/img/img/imgadj_b03c-03sat0.jpg" WIDTH="246"><BR> Brightness=0.3, contrast=-0.3, saturation=0</P><P> <IMG alt="" border="0" HEIGHT="244" src="img/img/img/img/img/img/img/img/imgadj_b04c-07sat0.jpg" WIDTH="246"><BR> Brightness=0.4, contrast=-0.7, saturation=0</P><P> <IMG alt="" border="0" HEIGHT="244" src="img/img/img/img/img/img/img/img/imgadj_b04c-07sat-1.jpg" WIDTH="246"><BR> Brightness=0.4, contrast=-0.7, saturation=-1</P><P> <IMG alt="" border="0" HEIGHT="244" src="img/img/img/img/img/img/img/img/imgadj_b0c0sat1.jpg" WIDTH="246"><BR> Brightness=0, contrast=0, saturation=1</P><H2><A NAME="9_21">9.21 Timing the generation of graphs</A></H2><P> During development and optimization it can be very handy to have theactual time it took to generate the image as a footnote. The followingexample shows the usage of this feature<DIV class="example"><BR> <A href="exframes/frame_example11.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/example11.png" WIDTH="300"></A><BR><B>Figure 182:</B> Timing of a graph <A href="exframes/frame_example11.html"target="blank">[src]</A> <P></P></DIV></P><P> To enable this feature you can proceed in two ways.</P><OL><LI> You can either set the global define BRAND_TIMING (in jpgraph.php)to true. This will add the timing string to all graphs generated.</LI><LI> .. or you can enable it for a specific graph by setting the globalvariable $gJpgBrandTiming as in<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $gJpgBrandTiming</FONT><FONT color="#007700">=</FONT><FONTcolor="#0000BB">true</FONT><FONT color="#007700">;</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV><P>in the beginning of the script.</P></LI></OL><P> If you like you might also change the way the timing is formatted bysetting the string defined by BRAND_TIMING_FORMAT (in jpgraph.php).This string represents a standard printf() format string.<DIV class="note"><B>Note:</B> JpGraph contains a utility class called JpgTimer which youcan use yourself should you need ms timing of part of your own code.The API is really simple. The class supports multiple running timersand you start a timer simply by calling the Push() method. This willstart a new timer and put it on the top of the timer stack. To stop thetimer, pop it from the stack and return the timing value simply callPop().</DIV></P><H2><A NAME="9_22">9.22 Using country flags in various context</A></H2><P> JpGraph has built-in support for over 200 country flags, i.e. theyare available to be used in graphs without any external imagedefinitions.</P><P> Country flags can be used in primarily two settings</P><OL><LI> As image markers in line and scatter graphs</LI><LI> As background images for graphs</LI><LI> As a special type of icons (using the IconPlot()) which can beadded to the graph in any arbitrary position. See next section</LI></OL><P> In order to make it easy to find the appropriate country flags theycan be specified with either full or partial name or as an numericindex. The routines in JpGraph are "smart" enough to figure out whichway you are trying to specify a particular flag.</P><P> To specify a country flag as a marker you have to specify thespecial mark type as one of MARK_FLAG1,MARK_FLAG2,MARK_FLAG3 orMARK_FLAG4</P><P> Flags are internally stored in 4 different sizes which is indicatedby the number in the mark types. Flags may also be arbitrary scaledwhen displayed. Since this is partially overlapping functionality youmight very well ask why the flags are stored in four different basicsizes. The reason is of course performance. It you only want a verysmall flag it takes processing time to scale down a large image to,say, a small icon size. At the same time for large flags to be used asbackground a small original flag might not have enough details to bescaled up to a large size. Hence the reason for storing the flags in 4different sizes.</P><P> The example below shows how to use country flags as markers<DIV class="example"><BR> <A href="exframes/frame_markflagex1.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/markflagex1.png" WIDTH="300"></A><BR><B>Figure 183:</B> Using country flags as line plot markers <A href="exframes/frame_markflagex1.html"target="blank">[src]</A> <P></P></DIV></P><P> To use country flags as background one has to use the methodGraph::SetBackgroundCountryFlag(). With this method you can specifyboth how much of the image should be filled as well as how much of theflag should be mixed into the background.</P><P> To see a list of all supported country flags you can run the script"listallcountryflags.php" in the Example directory. This will show youa table with all flags.</P><H2><A NAME="9_23">9.23 Adding icons onto the graph</A></H2><P> In addition to the standard background image you can also add anarbitrary number of icons onto the background of the graph. These iconsare created with a call to the special Plot class<I> IconPlot</I>.</P><P> The image from icons are taken from a file or as one of the builtincountry flags.</P><P> You may control how much of the icon should be blended into thebackground by specifying a percentage (1-100). The example below showshow to mix in the picture of "Tux" into the background of a filled linegraph. Note: This example uses alpha blending and will thereforerequire GD2.<DIV class="example"><BR> <A href="exframes/frame_lineiconex1.html" target="blank"><IMG border="0"HEIGHT="250" src="img/img/img/img/img/img/img/img/lineiconex1.png" WIDTH="400"></A><BR><B>Figure 184:</B> Adding an icon into the background <A href="exframes/frame_lineiconex1.html"target="blank">[src]</A> <P></P></DIV></P><P> To specify any of the roughly 200 country flags as an icon you firstcreate an empty Icon and then call the IconPlot::SetCountryFlag() withthe appropriate parameters. (See the class reference). This isillustrated below by adding the Icelandic flag into the background asan icon<DIV class="example"><BR> <A href="exframes/frame_lineiconex2.html" target="blank"><IMG border="0"HEIGHT="250" src="img/img/img/img/img/img/img/img/lineiconex2.png" WIDTH="400"></A><BR><B>Figure 185:</B> Adding an icon flag into the background <A href="exframes/frame_lineiconex2.html"target="blank">[src]</A> <P></P></DIV></P><P><DIV class="note"><B>Note:</B> Some older versions of PHP pre-4.3.3using the builtin GD have problems rendering blended images. If youhave this problem then you need to upgrade to a more recent version ofPHP.</DIV></P><H1><A NAME="10">10 Working with canvas graphs</A></H1><P> Canvas graphing is an advanced feature that comes in handy where youneed to draw some more arbitrary graphics. To give you a flavor of whatyou can do the following example shows an architecture overview ofJpGraph which was drawn using a canvas.<DIV class="example"><BR> <A href="exframes/frame_canvas_jpgarchex.html" target="blank"><IMG border="0"HEIGHT="650" src="img/img/img/img/img/img/img/img/canvas_jpgarchex.png" WIDTH="700"></A><BR><B>Figure 186:</B> Example of what you can draw on a canvas <A href="exframes/frame_canvas_jpgarchex.html"target="blank">[src]</A> <P></P></DIV></P><P> Working with canvas requires more understanding of JpGraph as wellas more programming and fine tuning.</P><H2><A NAME="10_1">10.1 Introduction</A></H2><P> Canvas graph is really not a graph. It a blank sheet of paper whichyou can use to draw arbitrary shapes and still have access to some ofthe convenient features of JpGraph.</P><P> You can work with a canvas in different levels of complexity. Youcan for example work directly with the Image class which provides alarge number of primitives for drawing but requires that you useabsolute pixel coordinates.</P><P> You can also make life a little bit easier by using a canvas scale.This lets you define your own scale on the canvas which often makes iteasier by letting you work on a grid you have specified yourself. Italso makes it very easy to re-scale you image automatically by justchanging your scale. For example to half the size of you drawing youjust make the scale twice as large.</P><P> To give you some help in working with different canvas you shouldinclude the "jpgraph_canvtools.php" file when working on canvases. Thisis not strictly necessary but it will give you some nice abstraction tohelp you create your masterpieces.</P><P> As another (concrete) example on the use of a canvas the figurebelow is a listing of font styles available with JpGraph.<DIV class="example"><BR> <A href="exframes/frame_listfontsex1.html" target="blank"><IMG border="0"HEIGHT="450" src="img/img/img/img/img/img/img/img/listfontsex1.png" WIDTH="550"></A><BR><B>Figure 187:</B> Another example of using a canvas to draw anumber of text boxes <A href="exframes/frame_listfontsex1.html" target="blank">[src]</A> <P></P></DIV></P><P></P><H2><A NAME="10_2">10.2 Creating a simple canvas</A></H2><P> 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 getaccess to some supporting classes that may (or not) come in handy.</P><P> Creating a canvas gives you the opportunity draw arbitrary shapes ona "white" piece of paper. Let's first show a simple example were wejust draw a text box. We first show you the code which we will walkthrough<DIV class="phpscript">(File: canvasex01.php)<BR><CODE><FONT color="#000000"> <FONT color="#0000BB"><?php<BR></FONT><FONT color="#FF8000">// $Id: canvasex01.php,v 1.3 2002/10/23 08:17:23 aditus Exp $<BR></FONT><FONT color="#007700">include </FONT><FONT color="#DD0000">"../jpgraph.php"</FONT><FONT color="#007700">;<BR>include </FONT><FONT color="#DD0000">"../jpgraph_canvas.php"</FONT><FONTcolor="#007700">;<BR><BR></FONT><FONT color="#FF8000">// Setup a basic canvas we can work <BR></FONT><FONT color="#0000BB">$g </FONT><FONT color="#007700">= new </FONT><FONTcolor="#0000BB">CanvasGraph</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">400</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">300</FONT><FONTcolor="#007700">,</FONT><FONT color="#DD0000">'auto'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetMargin</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">5</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">11</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">6</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">11</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetShadow</FONT><FONT color="#007700">();<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetMarginColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"teal"</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// We need to stroke the plotarea and margin before we add the<BR>// text since we otherwise would overwrite the text.<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">InitFrame</FONT><FONT color="#007700">();<BR><BR></FONT><FONT color="#FF8000">// Draw a text box in the middle<BR></FONT><FONT color="#0000BB">$txt</FONT><FONT color="#007700">=</FONT><FONTcolor="#DD0000">"This\nis\na TEXT!!!"</FONT><FONT color="#007700">;<BR></FONT><FONT color="#0000BB">$t </FONT><FONT color="#007700">= new </FONT><FONTcolor="#0000BB">Text</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$txt</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">200</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">10</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$t</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">FF_ARIAL</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FS_BOLD</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">40</FONT><FONTcolor="#007700">);<BR><BR></FONT><FONT color="#FF8000">// How should the text box interpret the coordinates?<BR></FONT><FONT color="#0000BB">$t</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Align</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'center'</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">'top'</FONT><FONTcolor="#007700">);<BR><BR></FONT><FONT color="#FF8000">// How should the paragraph be aligned?<BR></FONT><FONT color="#0000BB">$t</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">ParagraphAlign</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'center'</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Add a box around the text, white fill, black border and gray shadow<BR></FONT><FONT color="#0000BB">$t</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetBox</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"white"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"black"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"gray"</FONT><FONTcolor="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Stroke the text<BR></FONT><FONT color="#0000BB">$t</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Stroke</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">img</FONT><FONTcolor="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Stroke the graph<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Stroke</FONT><FONT color="#007700">();<BR><BR></FONT><FONT color="#0000BB">?><BR></FONT><BR></FONT></CODE></DIV></P><P> The example above starts by creating a (400x200) sized image. We setthe margins to get a nice frame around the image. For canvases themargins has no effect in the way you enter coordinates. Top left is(0,0) and bottom right (including any potential margin and shadow) isthe maximum. In this case the coordinates are X:0-399, and Y:0-199</P><P> We then call the <A href="../ref/CanvasGraph.html#_CANVASGRAPH_INITFRAME">InitFrame()</A> method which actually strokes the margin and plotareato the graph. Since everything is stroked in the order you issue thecommands you must make sure that the graphical objects you want on topis stroked last. This is different from the way you normally work withJpGraph since it queues up all you addition and then makes sure theyare stroked in the correct order.</P><P> We then create a <A href="../ref/Text.html#_C_TEXT">Text</A> object,setup it's properties, including the absolute screen position where wewant the text, and then stroke it. Her it might be a need for a closerexplanation of the, perhaps misnamed, method <A href="../ref/Text.html#_TEXT_ALIGN">Text::Align()</A> This method states<STRONG> how the text coordinatesshould be interpreted</STRONG> , i.e when we specify (200,10) as thecoordinates for the text paragraph should that be interpreted as thetop left corner, bottom-left corner or something else (of the boundingbox)? In the code above we have chosen to interpret the X-coordinate asbeing 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 graphis aligned with the middle of the top line of the paragraphs boundingbox.</P><P> We also specify that the lines within the paragraph should becentered with a call to <A href="../ref/Text.html#_TEXT_PARAGRAPHALIGN">Text::ParagraphAlign()</A> Since we also choose to have a box aroundthe text we have to make use of the method <A href="../ref/Text.html#_TEXT_SETBOX">Text::SetBox()</A> which is used to specify the fill color, the bordercolor and the shadow color (if you leave out shadow color or set it to'', no shadow will be used).</P><P> Now we are ready to stroke the text onto the canvas. In order to doso we must specify the basic Image drawing class we want to use.Without discussing this further we just state that a suitable imageclass can always be found as the<STRONG> img</STRONG> property of theGraph class.</P><P> Finally we are ready to stroke the entire graph, which in effectsends the canvas back to the browser. Below you can see the effect ofall this code</P><P><DIV class="example"><BR> <A href="exframes/frame_canvasex01.html" target="blank"><IMG border="0"HEIGHT="300" src="img/img/img/img/img/img/img/img/canvasex01.png" WIDTH="400"></A><BR><B>Figure 188:</B> A simple canvas drawing with a text box in themiddle <A href="exframes/frame_canvasex01.html" target="blank">[src]</A> <P></P></DIV></P><P></P><H2><A NAME="10_3">10.3 Adding lines and rectangles to a canvas</A></H2><P> A canvas also makes a good background for using standard graphicprimitives, for example circles and lines. What you first have toremember is that you are (so far) working with absolute screencoordinates and secondly all drawing primitives are found in the <A href="../ref/Image.html#_C_IMAGE">Image Class</A> accessible as a property of the Graph class. So forexample to draw a line between coordinate (0,0) and (100,100) you wouldhave to add the line<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $graph</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">img</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Line</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">0</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">100</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">100</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> To your code. The following example shows some of the graphicprimitives you have access to in the Image class<DIV class="phpscript">(File: canvasex02.php)<BR><CODE><FONT color="#000000"> <FONT color="#0000BB"><?php<BR></FONT><FONT color="#FF8000">// $Id: canvasex02.php,v 1.1 2002/08/27 20:08:57 aditus Exp $<BR></FONT><FONT color="#007700">include </FONT><FONT color="#DD0000">"../jpgraph.php"</FONT><FONT color="#007700">;<BR>include </FONT><FONT color="#DD0000">"../jpgraph_canvas.php"</FONT><FONTcolor="#007700">;<BR><BR></FONT><FONT color="#FF8000">// Setup a basic canvas we can work <BR></FONT><FONT color="#0000BB">$g </FONT><FONT color="#007700">= new </FONT><FONTcolor="#0000BB">CanvasGraph</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">400</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">200</FONT><FONTcolor="#007700">,</FONT><FONT color="#DD0000">'auto'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetMargin</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">5</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">11</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">6</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">11</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetShadow</FONT><FONT color="#007700">();<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetMarginColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"teal"</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// We need to stroke the plotarea and margin before we add the<BR>// text since we otherwise would overwrite the text.<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">InitFrame</FONT><FONT color="#007700">();<BR><BR></FONT><FONT color="#FF8000">// Add a black line<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">img</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'black'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">img</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Line</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">0</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">100</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">100</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// .. and a circle (x,y,diameter)<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">img</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Circle</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">100</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">100</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">50</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// .. and a filled circle (x,y,diameter)<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">img</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'red'</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">img</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">FilledCircle</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">200</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">100</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">50</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// .. add a rectangle<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">img</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'green'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">img</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">FilledRectangle</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">10</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">10</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">50</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">50</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// .. add a filled rounded rectangle<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">img</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'green'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">img</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">FilledRoundedRectangle</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">300</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">30</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">350</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">80</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">10</FONT><FONT color="#007700">);<BR></FONT><FONT color="#FF8000">// .. with a darker border<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">img</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'darkgreen'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">img</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">RoundedRectangle</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">300</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">30</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">350</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">80</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">10</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// Stroke the graph<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Stroke</FONT><FONT color="#007700">();<BR><BR></FONT><FONT color="#0000BB">?><BR></FONT><BR></FONT></CODE></DIV></P><P> Pleas note the way to access these routines through the img propertyof the Graph class. Please also keep in mind that the coordinates areabsolute.</P><P><DIV class="example"><BR> <A href="exframes/frame_canvasex02.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/canvasex02.png" WIDTH="400"></A><BR><B>Figure 189:</B> Example of graphic primitives <A href="exframes/frame_canvasex02.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P></P><HR> <SMALL><P><STRONG> A note on GD</STRONG> For those of you using GD 1.xx youmight notice that the large "filled circle" isn't completely filled.This is because in GD 1.xx there are no low level primitives to fill anellipse or circle so JpGraph tries to make the best out of a badsituation and manually fake a filled circle. For interest of speedJpGraph does not contain a complete (for example) Bresenham-circle fillbut cheats by using some existing GD routines. This is not a perfectsolution and for large filled circles like this you get somemoire-patterns in the circle. If you upgrade to GD 2.x JpGraph will beable to make full use of those new existing methods and the fill willbe perfect.</P></SMALL><HR><P> We refer you to the class reference to find out what other graphicprimitives are available for use.</P><H2><A NAME="10_4">10.4 Using a canvas scale</A></H2><P> The previous method using absolute coordinates works. But nothingmore. It doesn't give you any chance to easily scale the image (unlessyou manually recalculate all used coordinates) , it gets tedious towork with pixel level resolution. Especially if you just like to draw afew basic shapes.</P><P> To help with this you can use a scale for the canvas. This lets youdefine a "work-space" of your choice. You can for example set thecoordinates to be between X:0-10, Y:0-10. This makes it easier toposition objects on the canvas. This also has two additionaladvantages:</P><UL><LI> If you increase the size of the canvas all objects will beautomatically scale to keep their proportions without any changes.</LI><LI> You can shrink/enlarge your drawing (not the image) by just usinganother scale. For example if you originally draw the image using a(0:10, 0:10) scale and then change the scale to (0:20, 0:20) then theeffect will be that you drawings will "shrink" to half their size.</LI></UL><P></P><P> To use this type of scaling you must make sure you include the file"jpgraph_canvtools.php" . In addition to the scaling class their arealso a couple of other utility classes that may come in handy,especially the <A href="../ref/Shape.html#_C_SHAPE"> Shape</A> class.</P><P> Using the scale is quite simple. You first instantiate a scaleobject passing the graph as a parameter and then specify the scale youwant to use. This means you need to add the lines<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $scale </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">CanvasScale</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$scale</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$xmax</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$ymax</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> to your code. You can then use one of the translation methods (forexample <A href="../ref/CanvasScale.html#_CANVASSCALE_TRANSLATE">CanvasScale::Translate()</A>) in the canvas scale class to translatebetween your world coordinates and the absolute screen coordinates.This means you could take the code in the example above and just addthe lines, for example,<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> </FONT><FONT color="#007700">list(</FONT><FONT color="#0000BB">$x1</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$y1</FONT><FONTcolor="#007700">) = </FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">scale</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Translate</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$x1</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$y1</FONT><FONTcolor="#007700">);<BR>list(</FONT><FONT color="#0000BB">$x2</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">$y2</FONT><FONT color="#007700">) = </FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">scale</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">Translate</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$x2</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">$y2</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">img</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Line</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$x1</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">$y1</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$x2</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">$y2</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> Since this pattern has to be repeated for every object that has tobe drawn it makes good sense to encapsulate this in a separate class.This is exactly why the canvas tools file also have a utility classcalled <A href="../ref/Shape.html#_C_SHAPE"> Shape</A> This class ismainly a wrapper around the most commonly used methods in the basicImage class (with one important exception) and does all these thetranslation for you. Please see the class reference for a complete listof the available methods To set up the Shape class you instantiate itwith the graphic context and the scale you want to use as argument asin</P><P><DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $shape </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">Shape</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$g</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">$scale</FONT><FONT color="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> You are then ready to use all the methods in the shape class. Usinga scale and imitating the previous example we would get the sourceshown below.<DIV class="phpscript">(File: canvasex03.php)<BR><CODE><FONT color="#000000"> <FONT color="#0000BB"><?php<BR></FONT><FONT color="#FF8000">// $Id: canvasex03.php,v 1.1 2002/08/27 20:08:57 aditus Exp $<BR></FONT><FONT color="#007700">include </FONT><FONT color="#DD0000">"../jpgraph.php"</FONT><FONT color="#007700">;<BR>include </FONT><FONT color="#DD0000">"../jpgraph_canvas.php"</FONT><FONTcolor="#007700">;<BR>include </FONT><FONT color="#DD0000">"../jpgraph_canvtools.php"</FONT><FONTcolor="#007700">;<BR><BR></FONT><FONT color="#FF8000">// Define work space<BR></FONT><FONT color="#0000BB">$xmax</FONT><FONT color="#007700">=</FONT><FONTcolor="#0000BB">20</FONT><FONT color="#007700">;<BR></FONT><FONT color="#0000BB">$ymax</FONT><FONT color="#007700">=</FONT><FONTcolor="#0000BB">20</FONT><FONT color="#007700">;<BR><BR></FONT><FONT color="#FF8000">// Setup a basic canvas we can work <BR></FONT><FONT color="#0000BB">$g </FONT><FONT color="#007700">= new </FONT><FONTcolor="#0000BB">CanvasGraph</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">400</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">200</FONT><FONTcolor="#007700">,</FONT><FONT color="#DD0000">'auto'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetMargin</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">5</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">11</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">6</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">11</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetShadow</FONT><FONT color="#007700">();<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetMarginColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"teal"</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// We need to stroke the plotarea and margin before we add the<BR>// text since we otherwise would overwrite the text.<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">InitFrame</FONT><FONT color="#007700">();<BR><BR></FONT><FONT color="#FF8000">// Create a new scale<BR></FONT><FONT color="#0000BB">$scale </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">CanvasScale</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$scale</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$xmax</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$ymax</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// The shape class is wrapper around the Imgae class which translates<BR>// the coordinates for us<BR></FONT><FONT color="#0000BB">$shape </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">Shape</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$g</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$scale</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$shape</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'black'</FONT><FONT color="#007700">);<BR><BR><BR></FONT><FONT color="#FF8000">// Add a black line<BR></FONT><FONT color="#0000BB">$shape</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'black'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$shape</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Line</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">20</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">20</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// .. and a circle (x,y,diameter)<BR></FONT><FONT color="#0000BB">$shape</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Circle</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">5</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">14</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">2</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// .. and a filled circle (x,y,diameter)<BR></FONT><FONT color="#0000BB">$shape</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'red'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$shape</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">FilledCircle</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">11</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">8</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">3</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// .. add a rectangle<BR></FONT><FONT color="#0000BB">$shape</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'green'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$shape</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">FilledRectangle</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">15</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">8</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">19</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">14</FONT><FONT color="#007700">);<BR><BR></FONT><FONT color="#FF8000">// .. add a filled rounded rectangle<BR></FONT><FONT color="#0000BB">$shape</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'green'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$shape</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">FilledRoundedRectangle</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">2</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">3</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">8</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">6</FONT><FONT color="#007700">);<BR></FONT><FONT color="#FF8000">// .. with a darker border<BR></FONT><FONT color="#0000BB">$shape</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'darkgreen'</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$shape</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">RoundedRectangle</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">2</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">3</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">8</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">6</FONT><FONT color="#007700">);<BR><BR><BR></FONT><FONT color="#FF8000">// Stroke the graph<BR></FONT><FONT color="#0000BB">$g</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Stroke</FONT><FONT color="#007700">();<BR><BR></FONT><FONT color="#0000BB">?><BR></FONT><BR></FONT></CODE></DIV> The source above gives the following result<DIV class="example"><BR> <A href="exframes/frame_canvasex03.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/canvasex03.png" WIDTH="400"></A><BR><B>Figure 190:</B> Drawing shapes on a canvas using a scale. <A href="exframes/frame_canvasex03.html"target="blank">[src]</A> <P></P></DIV></P><P> If we like to make a smaller image we could just change the imagesize and everything will be rescaled without any further code changes.SO for example making the image half the size would give the result<DIV class="example"><BR> <A href="exframes/frame_canvasex04.html" target="blank"><IMG border="0"HEIGHT="100" src="img/img/img/img/img/img/img/img/canvasex04.png" WIDTH="200"></A><BR><B>Figure 191:</B> Shrinking the image to half the size is easysince the scaling will maintain the relative position of the objects <A href="exframes/frame_canvasex04.html"target="blank">[src]</A> <P></P></DIV></P><P> If we instead wanted to keep the image size but shrink the shapes wecould just make the scale twice as large which would result in<DIV class="example"><BR> <A href="exframes/frame_canvasex05.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/canvasex05.png" WIDTH="400"></A><BR><B>Figure 192:</B> Shrinking hte graphic object by making the scaletwice as large <A href="exframes/frame_canvasex05.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P> We previously mentioned that the Shape class was a wrapper aroundthe image class with one exception. So what is the exception? Well,glad you asked. The exception is that it contain an additional methodwhich draws an "indented rectangle". An indented rectangle is arectangle where one of it's four corners have been moved into therectangle. You create an indented rectangle by calling either <A href="../ref/Shape.html#_SHAPE_INDENTEDRECTANGLE">Shape::IndentedRectangle()</A> or A few examples illustrates what thisshape looks like.<DIV class="example"><BR> <A href="exframes/frame_canvasex06.html" target="blank"><IMG border="0"HEIGHT="200" src="img/img/img/img/img/img/img/img/canvasex06.png" WIDTH="400"></A><BR><B>Figure 193:</B> Examples of filled indented rectangles <A href="exframes/frame_canvasex06.html"target="blank">[src]</A> <P></P></DIV></P><P></P><P> As a final note we mention the class <A href="../ref/CanvasRectangleText.html#_C_CANVASRECTANGLETEXT">CanvasRectangleText</A> Which can be used to add a text with a roundedrectangle (possibly filled) onto the canvas. The previous example whereall the available fonts were drawn were using this class. We don'tdescribe it further but refer the interested reader to the classreference and the 'listfontsex1.php' example file.</P><H2><A NAME="10_5">10.5 Sample application: Drawing DB schema</A></H2><P> As a final example we shortly discuss how the canvas type of graphwas used to generate the DB schema for the DDDA architecture.</P><P> The library php file "utils/misc/imgdbschema.php" included in thedistribution contains some utility classes to make the drawing of tableschemes easier. It contains two basic classes, Class ImgDBTable andClass ImgDBSchema. The first class understand how to draw an imageillustrating a single table. The second class is responsible forautomatically extract all the relevant information from a DB to draw acomplete DB Schema.</P><P> Before going into this a little bit more we show what an example ofthis might look like.<DIV class="example"><BR> <A href="exframes/frame_dbschemaex1.html" target="blank"><IMG border="0"HEIGHT="750" src="img/img/img/img/img/img/img/img/dbschemaex1.png" WIDTH="600"></A><BR><B>Figure 194:</B> Example of using the canvas graph style togetherwith the imgdbschema.php library to semi-automatically generate a DBschema <A href="exframes/frame_dbschemaex1.html" target="blank">[src]</A> <P></P></DIV></P><P></P><P> Before going on it should be noted that the ImgDBSchema assumes thatthe DB can be accessed through a DB abstraction layer modeled after theabstraction layer available in the 'jpdb.php' file in the DDDAarchitecture. This abstraction layer assumes a MySQL database in thebottom. This specific dependency of this particular abstraction layeris the reason why these classes is not included in the generic canvastools file.</P><P> The second thing to note is that this library does not contain acomplete automatic-layout engine but rather a very simple automaticsystem which, if nothing else is specified, just puts the table in arectangular grid. A complete graph layout engine would simple be tomuch to write in this context. This is also a very difficultoptimization problem and sofar not even any of the available researchprograms that tries this can achieve a satisfactory layout withoutmanual intervention.</P><P> The critical lines in the code to generate the above graph is<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $tblposadj</FONT><FONTcolor="#007700">=array(</FONT><FONT color="#0000BB">$tlo</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">$tblwidth</FONT><FONT color="#007700">+</FONT><FONT color="#0000BB">$tlo</FONT><FONT color="#007700">+</FONT><FONT color="#0000BB">2</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">2</FONT><FONT color="#007700">*</FONT><FONTcolor="#0000BB">$tblwidth</FONT><FONT color="#007700">+</FONT><FONT color="#0000BB">$tlo</FONT><FONT color="#007700">+</FONT><FONT color="#0000BB">4</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,-</FONT><FONT color="#0000BB">1</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">16</FONT><FONT color="#007700">,-</FONT><FONT color="#0000BB">1</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">16</FONT><FONTcolor="#007700">);<BR></FONT><FONT color="#0000BB">$dbschema </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">ImgDBSchema</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"jpgraph_doc"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"FormatTblName"</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">"FormatFldName"</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$dbschema</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetMargin</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$leftm</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$topm</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$dbschema</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetTableWidth</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$tblwidth</FONT><FONT color="#007700">);<BR></FONT><FONT color="#0000BB">$dbschema</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Stroke</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">img</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$this</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">iscale</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$tblposadj</FONT><FONT color="#007700">);</FONT><FONTcolor="#0000BB"></FONT></FONT></CODE></DIV></P><P></P><P> The rest of the code in the file is just to setup the canvas, add anindented rectangle to group some tables and generate a footer with thedate and time this image was generated.</P><P> The first line instantiates a new ImgDBSCheme layout engine askingit to draw an image for the database 'jpgraph_doc'. The following twoarguments specify two callback functions for formatting the text forheader and each field in a table.</P><P> The next line specify the top left margin where the drawing of thetables should be started.</P><P> The third line specify the width of a single table. The final linesstarts the engine and draws all tables in the database to the canvas.The final argument requires some further explanation. This is an offset(x,y) from the top left corner how each individual table should bepositioned. If the value is -1 indicates that the default value shouldbe used. If this array is not specified then the tables will simplearranged line by line.</P><P> The full source code for drawing this DB schema example is shownbelow.</P><P><DIV class="phpscript">(File: dbschemaex1.php)<BR><CODE><FONT color="#000000"> <FONT color="#0000BB"><?php<BR></FONT><FONT color="#FF8000">/*=======================================================================<BR>// File: DBSCHEMAEX1.PHP<BR>// Description: Draw a DB schema of the DDDA architecture<BR>// Created: 2002-08-25<BR>// Author: Johan Persson (johanp@aditus.nu)<BR>// Ver: $Id: dbschemaex1.php,v 1.1 2002/08/27 20:08:57 aditus Exp $<BR>//<BR>// License: This code is released under QPL<BR>// Copyright (C) 2001,2002 Johan Persson<BR>// Note: The actual drawing of the tables are semi-automatically<BR>// but you can easily adjust the individual tables position<BR>// with the 'tblposadj' array. <BR>//<BR>//========================================================================<BR>*/<BR></FONT><FONT color="#007700">include </FONT><FONT color="#DD0000">"../jpgraph.php"</FONT><FONT color="#007700">;<BR>include </FONT><FONT color="#DD0000">"../jpgraph_canvas.php"</FONT><FONTcolor="#007700">;<BR>include </FONT><FONT color="#DD0000">"../jpgraph_canvtools.php"</FONT><FONTcolor="#007700">;<BR>include </FONT><FONT color="#DD0000">"../utils/misc/imgdbschema.inc"</FONT><FONTcolor="#007700">;<BR>include </FONT><FONT color="#DD0000">"../utils/jpdocgen/jpdb.php"</FONT><FONTcolor="#007700">;<BR><BR><BR></FONT><FONT color="#FF8000">// Global callback to format the table header names<BR></FONT><FONT color="#007700">function </FONT><FONT color="#0000BB">FormatTblName</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$aName</FONT><FONT color="#007700">) {<BR> </FONT><FONT color="#FF8000">// We want to replace any specifi references to the<BR> // 'JpGraph' project with the generic '<project>'<BR> </FONT><FONT color="#007700">return </FONT><FONT color="#0000BB">str_replace</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'JpGraph'</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">'<project>'</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">$aName</FONT><FONT color="#007700">);<BR>}<BR><BR></FONT><FONT color="#FF8000">// Global callback to format each field name in the table<BR></FONT><FONT color="#007700">function </FONT><FONT color="#0000BB">FormatFldName</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$aName</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$aTable</FONT><FONTcolor="#007700">) {<BR> return </FONT><FONT color="#0000BB">$aName</FONT><FONT color="#007700">;<BR>}<BR><BR><BR>class </FONT><FONT color="#0000BB">Driver </FONT><FONT color="#007700">{<BR><BR> var </FONT><FONT color="#0000BB">$ig</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">$img</FONT><FONT color="#007700">, </FONT><FONTcolor="#0000BB">$iscale</FONT><FONT color="#007700">, </FONT><FONT color="#0000BB">$ishape</FONT><FONT color="#007700">;<BR> var </FONT><FONT color="#0000BB">$iymax</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$ixmax</FONT><FONT color="#007700">;<BR> var </FONT><FONT color="#0000BB">$iwidth</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$iheight</FONT><FONT color="#007700">;<BR><BR> function </FONT><FONT color="#0000BB">Driver</FONT><FONT color="#007700">() {<BR><BR> </FONT><FONT color="#FF8000">// Define Image size and coordinate grid space to work within<BR> </FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">iwidth </FONT><FONT color="#007700">= </FONT><FONTcolor="#0000BB">600</FONT><FONT color="#007700">;<BR> </FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">iheight</FONT><FONT color="#007700">= </FONT><FONTcolor="#0000BB">750</FONT><FONT color="#007700">;<BR> </FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">iymax </FONT><FONT color="#007700">= </FONT><FONTcolor="#0000BB">50</FONT><FONT color="#007700">;<BR> </FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">ixmax </FONT><FONT color="#007700">= </FONT><FONTcolor="#0000BB">55</FONT><FONT color="#007700">;<BR><BR> </FONT><FONT color="#FF8000">// Setup a basic canvas<BR> </FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">ig </FONT><FONT color="#007700">= new </FONT><FONTcolor="#0000BB">CanvasGraph</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">iwidth</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">iheight</FONT><FONT color="#007700">,</FONT><FONTcolor="#DD0000">'auto'</FONT><FONT color="#007700">);<BR> </FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">img </FONT><FONT color="#007700">= </FONT><FONTcolor="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">ig</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">img</FONT><FONTcolor="#007700">;<BR><BR> </FONT><FONT color="#FF8000">// Define the scale to be used<BR> </FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">iscale </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">CanvasScale</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">ig</FONT><FONT color="#007700">);<BR> </FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">iscale</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$this</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">ixmax</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">iymax</FONT><FONT color="#007700">);<BR> </FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">ishape </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">Shape</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">ig</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$this</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">iscale</FONT><FONT color="#007700">);<BR><BR> </FONT><FONT color="#FF8000">// A small frame around the canvas<BR> </FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">ig</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetMargin</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">2</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">3</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">2</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">3</FONT><FONT color="#007700">);<BR> </FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">ig</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetMarginColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"teal"</FONT><FONT color="#007700">);<BR> </FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">ig</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">InitFrame</FONT><FONT color="#007700">();<BR><BR> }<BR><BR> function </FONT><FONT color="#0000BB">Run</FONT><FONT color="#007700">() {<BR><BR> </FONT><FONT color="#0000BB">$leftm</FONT><FONT color="#007700">=</FONT><FONT color="#0000BB">1.5</FONT><FONT color="#007700">; </FONT><FONTcolor="#FF8000">// Left margin (for table schemes) <BR> </FONT><FONT color="#0000BB">$topm</FONT><FONT color="#007700">=</FONT><FONTcolor="#0000BB">5</FONT><FONT color="#007700">; </FONT><FONT color="#FF8000">// Top margin (for table schemes) <BR> </FONT><FONT color="#0000BB">$tblwidth</FONT><FONT color="#007700">=</FONT><FONT color="#0000BB">15</FONT><FONT color="#007700">; </FONT><FONTcolor="#FF8000">// Individual table width<BR> </FONT><FONT color="#0000BB">$tlo</FONT><FONT color="#007700">=</FONT><FONTcolor="#0000BB">1</FONT><FONT color="#007700">; </FONT><FONT color="#FF8000">// Offset for top line<BR><BR> // Add the background color for the project specific tables<BR> </FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">ishape</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">IndentedRectangle</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$leftm</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$topm</FONT><FONT color="#007700">-</FONT><FONT color="#0000BB">1</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">3</FONT><FONT color="#007700">*</FONT><FONT color="#0000BB">$tblwidth</FONT><FONT color="#007700">+</FONT><FONTcolor="#0000BB">$tlo</FONT><FONT color="#007700">+</FONT><FONT color="#0000BB">6</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">45</FONT><FONTcolor="#007700">,<BR> </FONT><FONT color="#0000BB">$tlo</FONT><FONT color="#007700">+</FONT><FONT color="#0000BB">2</FONT><FONT color="#007700">*</FONT><FONTcolor="#0000BB">$tblwidth</FONT><FONT color="#007700">+</FONT><FONT color="#0000BB">2</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">30</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">CORNER_BOTTOMLEFT</FONT><FONTcolor="#007700">,<BR> </FONT><FONT color="#DD0000">'lightblue'</FONT><FONTcolor="#007700">);<BR><BR> </FONT><FONT color="#FF8000">// Stroke the tables (series of x,y offsets, If =-1 then use the<BR> // automtic positioning<BR> </FONT><FONT color="#0000BB">$tblposadj</FONT><FONT color="#007700">=array(</FONT><FONT color="#0000BB">$tlo</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$tblwidth</FONT><FONT color="#007700">+</FONT><FONT color="#0000BB">$tlo</FONT><FONTcolor="#007700">+</FONT><FONT color="#0000BB">2</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">2</FONT><FONT color="#007700">*</FONT><FONT color="#0000BB">$tblwidth</FONT><FONT color="#007700">+</FONT><FONT color="#0000BB">$tlo</FONT><FONTcolor="#007700">+</FONT><FONT color="#0000BB">4</FONT><FONT color="#007700">,<BR> </FONT><FONT color="#0000BB">0</FONT><FONT color="#007700">,-</FONT><FONT color="#0000BB">1</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">16</FONT><FONT color="#007700">,-</FONT><FONT color="#0000BB">1</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">16</FONT><FONTcolor="#007700">);<BR> </FONT><FONT color="#0000BB">$dbschema </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">ImgDBSchema</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'jpgraph_doc'</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">'FormatTblName'</FONT><FONT color="#007700">,</FONT><FONT color="#DD0000">'FormatFldName'</FONT><FONT color="#007700">);<BR> </FONT><FONT color="#0000BB">$dbschema</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetMargin</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$leftm</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$topm</FONT><FONT color="#007700">);<BR> </FONT><FONT color="#0000BB">$dbschema</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">SetTableWidth</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$tblwidth</FONT><FONT color="#007700">);<BR> </FONT><FONT color="#0000BB">$dbschema</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Stroke</FONT><FONT color="#007700">(</FONT><FONTcolor="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">img</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$this</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">iscale</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$tblposadj</FONT><FONT color="#007700">);<BR><BR> </FONT><FONT color="#0000BB">$tt </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">CanvasRectangleText</FONT><FONT color="#007700">();<BR> </FONT><FONT color="#0000BB">$tt</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFillColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">''</FONT><FONT color="#007700">);<BR> </FONT><FONT color="#0000BB">$tt</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">''</FONT><FONT color="#007700">);<BR> </FONT><FONT color="#0000BB">$tt</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFontColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'navy'</FONT><FONT color="#007700">);<BR><BR> </FONT><FONT color="#FF8000">// Add explanation<BR> </FONT><FONT color="#0000BB">$tt</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">FF_ARIAL</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FS_NORMAL</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">12</FONT><FONTcolor="#007700">);<BR> </FONT><FONT color="#0000BB">$tt</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'Project specific tables'</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">$tblwidth</FONT><FONT color="#007700">+</FONT><FONT color="#0000BB">$leftm</FONT><FONT color="#007700">+</FONT><FONT color="#0000BB">3</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">16</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">15</FONT><FONT color="#007700">);<BR> </FONT><FONT color="#0000BB">$tt</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Stroke</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">img</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">iscale</FONT><FONT color="#007700">);<BR><BR> </FONT><FONT color="#FF8000">// Add title<BR> </FONT><FONT color="#0000BB">$tt</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">''</FONT><FONT color="#007700">);<BR> </FONT><FONT color="#0000BB">$tt</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">FF_VERDANA</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FS_BOLD</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">26</FONT><FONTcolor="#007700">);<BR> </FONT><FONT color="#0000BB">$tt</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'DDDA - DB Schema'</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">9</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">0.5</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">30</FONT><FONT color="#007700">);<BR> </FONT><FONT color="#0000BB">$tt</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Stroke</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">img</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">iscale</FONT><FONT color="#007700">);<BR><BR> </FONT><FONT color="#FF8000">// Add a version and date<BR> </FONT><FONT color="#0000BB">$tt</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFillColor</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">'yellow'</FONT><FONT color="#007700">);<BR> </FONT><FONT color="#0000BB">$tt</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">SetFont</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">FF_FONT1</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">FS_NORMAL</FONT><FONT color="#007700">,</FONT><FONT color="#0000BB">10</FONT><FONTcolor="#007700">);<BR> </FONT><FONT color="#0000BB">$tt</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"Generated: "</FONT><FONT color="#007700">.</FONT><FONT color="#0000BB">date</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"ymd H:i"</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">time</FONT><FONT color="#007700">()),</FONT><FONT color="#0000BB">1</FONT><FONT color="#007700">,</FONT><FONTcolor="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">iymax</FONT><FONT color="#007700">*</FONT><FONT color="#0000BB">0.96</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">15</FONT><FONT color="#007700">); <BR> </FONT><FONT color="#0000BB">$tt</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Stroke</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">img</FONT><FONTcolor="#007700">,</FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">iscale</FONT><FONT color="#007700">);<BR><BR> </FONT><FONT color="#0000BB">$this</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">ig</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Stroke</FONT><FONT color="#007700">();<BR> }<BR>}<BR><BR></FONT><FONT color="#0000BB">$driver </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">Driver</FONT><FONT color="#007700">();<BR></FONT><FONT color="#0000BB">$driver</FONT><FONT color="#007700">-></FONT><FONTcolor="#0000BB">Run</FONT><FONT color="#007700">();<BR><BR></FONT><FONT color="#0000BB">?><BR></FONT><BR></FONT></CODE></DIV></P><H1><A NAME="11">11 Anti-Spam Challenges</A></H1><P> JpGraph includes a module to easily generate Anti-Spam challenges.With this we mean an image consisting of numbers and letters which arevery hard to read for an OCR program. This is often used to secure signup for bulletin boards, on-line mail system or mailing lists since thisvery effectively prevent automatic sign up by robots (spam-bots).</P><P> The module in JpGraph responsible for this is<I>jpgraph_antispam.php</I> and behaves as a simplified plot module.</P><P> The example below illustrates how such an image can look like<DIV class="example"><BR> <A href="exframes/frame_antispamex01.html" target="blank"><IMG border="0"HEIGHT="34" src="img/img/img/img/img/img/img/img/antispamex01.png" WIDTH="104"></A><BR><B>Figure 195:</B> Simple illustration of spam challenge image <A href="exframes/frame_antispamex01.html"target="blank">[src]</A> <P></P></DIV></P><P>Anti spam images have less functionality then the usual imagesgenerated with JpGraph in order to keep this utility reasonable small.The primary limitation is that there are now additional formattingoptions for the images and the image generated will always use the<I>JPEG</I> image format. Hence it is not possible to change this to use,for example, PNG.</P><H2><A NAME="11_1">11.1 Generating Anti-Spam challenge</A></H2><P> There are two basic alternatives on how to generate the content ofthe anti-spam image</P><OL><LI> Submit a string that should be used</LI><LI> Automatically generate a random string. If this alternative ischosen then the user of the library should save the created string andcompare it to what the user enters.</LI></OL><P> In order to write a script to generate a new challenge there arefour steps to be completed.</P><P><B> First</B> include the library file<I> jpgraph_antispam.php</I>.Note that there is no need to include the "jpgraph.php" library sinceall functionality is included in this library file.<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> </FONT><FONT color="#007700">require_once </FONT><FONT color="#DD0000">"jpgraph_antispam.php"</FONT><FONTcolor="#007700">;</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P><B> Secondly</B> a new instance of the class<I> AntiSpam</I> must becreated<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> $spam </FONT><FONT color="#007700">= new </FONT><FONT color="#0000BB">AntiSpam</FONT><FONT color="#007700">();</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P><B> Thirdly</B> the string to be used in the challenge must bespecified. To automatically generate a suitable string use<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> </FONT><FONT color="#FF8000">// The argument determines the length of the generated string<BR></FONT><FONT color="#0000BB">$chars </FONT><FONT color="#007700">= </FONT><FONTcolor="#0000BB">$spam</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Rand</FONT><FONT color="#007700">(</FONT><FONT color="#0000BB">5</FONT><FONTcolor="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P> If instead the string to be used should be specified this stringshould be specified in the initial creation of the AntiSpam() or bycalling the<I> Set()</I> method as in<DIV class="phpscript"><CODE><FONT color="#000000"><FONT color="#0000BB"> $spam</FONT><FONT color="#007700">-></FONT><FONT color="#0000BB">Set</FONT><FONT color="#007700">(</FONT><FONT color="#DD0000">"aui8k"</FONT><FONTcolor="#007700">);</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P>Please note that in order to minimize the risk for confusion theletters 'O' and the number '0' (zero) is not allowed since they are tooalike and can be mistaken for each other.</P><P><B> The final and fourth step</B> is to output the image with a callthe method<I> Stroke()</I> on the created instance of the<I> AntiSpam</I>class.<DIV class="phpscript"><CODE><FONT color="#000000"> <FONT color="#0000BB"> </FONT><FONT color="#007700">if( </FONT><FONT color="#0000BB">$spam</FONT><FONTcolor="#007700">-></FONT><FONT color="#0000BB">Stroke</FONT><FONT color="#007700">() === </FONT><FONT color="#0000BB">false </FONT><FONT color="#007700">) {<BR> die(</FONT><FONT color="#DD0000">"Illegal or no data to plot"</FONT><FONTcolor="#007700">);<BR>}</FONT><FONT color="#0000BB"></FONT></FONT></CODE></DIV></P><P>Note that we have put a guard around the output since in the case ofan error this method will result a boolean false value. As with theother graph types it is possible to write the generated image to a fileby submitting a file name as an argument to<I> Stroke()</I>.</P><H1><A NAME="12">12 Code defines in JpGraph</A></H1><P> Various settings in JpGraph are controlled by overall DEFINEs in theconfiguration file "jpg-config.inc". Most of these defines have defaultvalues that should be valid for most usage.</P><P> In the rest of this chapter all constants are described with defaultvalue and usage.</P><P></P><TABLE cellpadding="3" cellspacing="0" class="codedefines"><TR><TH>Define, default value</TH><TH>Comment</TH></TR><TR><TD valign="top">"CACHE_DIR", "/tmp/jpgraph_cache/"</TD><TD>The fullabsolute name of directory to be used as a cache. This directory<STRONG>must</STRONG> be readable and writable for PHP. Must end with '/'</TD></TR><TR><TD valign="top">"TTF_DIR", "/usr/local/fonts/ttf/"</TD><TD>Directory for JpGraph TTF fonts. Must end with '/' The fonts must followthe naming conventions as used by the supplied TTF fonts in JpGraph.</TD></TR><TR><TD valign="top">"CSIMCACHE_DIR", "csimcache/"</TD><TD>Directory forcache directory for CSIM graphs. Must end with '/' Cache directoryspecification for use with CSIM graphs that are using the cache. Thedirectory must be the filesystem name as seen by PHP and the 'http'version must be the same directory but as seen by the HTTP serverrelative to the 'htdocs' directory. If a relative path is specified itis taken to be relative from where the image script is executed. Note:The default setting is to create a subdirectory in the directory fromwhere the image script is executed and store all files there. As usualthis directory must be writable by the PHP process.</TD></TR><TR><TD valign="top">"CSIMCACHE_HTTP_DIR", "csimcache"</TD><TD>Directoryfor JpGraph TTF fonts. Must end with '/' Cache directory specificationfor use with CSIM graphs that are using the cache. The directory mustbe the filesystem name as seen by PHP and the 'http' version must bethe same directory but as seen by the HTTP server relative to the'htdocs' directory. If a relative path is specified it is taken to berelative from where the image script is executed. Note: The defaultsetting is to create a subdirectory in the directory from where theimage script is executed and store all files there. As usual thisdirectory must be writable by the PHP process.</TD></TR><TR><TD valign="top">"CHINESE_TTF_FONT", "bkai00mp.ttf"</TD><TD> Actualname of the TTF file used together with FF_CHINESE aka FF_BIG5 This isthe TTF file being used when the font family is specified as eitherFF_CHINESE or FF_BIG5</TD></TR><TR><TD valign="top">"LANGUAGE_CYRILLIC", false</TD><TD> Special unicodeCyrillic language support.</TD></TR><TR><TD valign="top">"CYRILLIC_FROM_WINDOWS", false</TD><TD> If you aresetting this config to true the conversion will assume that the inputtext is windows 1251, if false it will assume koi8-r</TD></TR><TR><TD valign="top">'MINCHO_TTF_FONT', 'ipam.ttf'</TD><TD> JapaneseTrueType font used with FF_MINCHO</TD></TR><TR><TD valign="top">'PMINCHO_TTF_FONT', 'ipamp.ttf'</TD><TD> JapaneseTrueType font used with FF_PMINCHO</TD></TR><TR><TD valign="top">'GOTHIC_TTF_FONT', 'ipag.ttf'</TD><TD> JapaneseTrueType font used with FF_GOTHIC</TD></TR><TR><TD valign="top">'PGOTHIC_TTF_FONT', 'ipagp.ttf'</TD><TD> JapaneseTrueType font used with FF_PGOTHIC</TD></TR><TR><TD valign="top">"INSTALL_PHP_ERR_HANDLER", false</TD><TD> Determineif the library should also setup the default PHP error handler togenerate a graphic error message. This is useful during development tobe able to see the error message as an image instead as a "red-cross"in a page where an image is expected.</TD></TR><TR><TD valign="top">"CATCH_PHPERRMSG", true</TD><TD> Should the libraryexamine the global php_errmsg string and convert any error in it to agraphical representation. This is handy for the occasions when, forexample, header files cannot be found and this results in the graph notbeing created and just a "red-cross" image would be seen. This shouldbe turned off for a production site.</TD></TR><TR><TD valign="top">"USE_LIBRARY_GD2",false</TD><TD>Specify if weshould use GD 2.x or GD 1.x If you have GD 2.x installed it isrecommended that you use it since it will give a slightly, slightlybetter visual appearance for arcs. If you don't have GD2 installed thismust be set to false!</TD></TR><TR><TD valign="top">'USE_TRUECOLOR',true</TD><TD>Should the image be atruecolor image? Note 1: Can only be used with GD 2.0.2 and above. Note2: GD 2.0.1 + PHP 4.0.6 on Win32 crashes when trying to use truecolor.Truecolor support is to be considered alpha since GD 2.x is still notconsidered stable (especially on Win32). Note 3: MUST be enabled to getbackground images working with GD2 Note 4: If enabled then truetypefonts will look very ugly => You can't have both background images andtruetype fonts in the same image until these bugs has been fixed in GD2.01</TD></TR><TR><TD valign="top">"USE_CACHE",false</TD><TD>Should the cache be usedat all? By setting this to false no files will be generated in thecache directory. The difference from READ_CACHE being that settingREAD_CACHE to false will still create the image in the cache directoryjust not use it. By setting USE_CACHE=false no files will even begenerated in the cache directory.</TD></TR><TR><TD valign="top">"READ_CACHE",true</TD><TD>Should we try to find animage in the cache before generating it? Set this define to false tobypass the reading of the cache and always regenerate the image. Notethat even if reading the cache is disabled the cached will still beupdated with the newly generated image. Set also "USE_CACHE" below.</TD></TR><TR><TD valign="top">"DEFAULT_GFORMAT","auto"</TD><TD>Default graphicformat set to "auto" which will automatically choose the best availableformat in the order png,gif,jpg (The supported format depends on whatyour PHP installation supports)</TD></TR><TR><TD valign="top">"USE_IMAGE_ERROR_HANDLER",true</TD><TD> Determineif the error handler should be image based or purely text based. Imagebased makes it easier since the script will always return an image evenin case of errors.</TD></TR><TR><TD valign="top">"USE_APPROX_COLORS",true</TD><TD>If the colorpalette is full should JpGraph try to allocate the closest match? Ifyou plan on using background image or gradient fills it might be a goodidea to enable this. If not you will otherwise get an error saying thatthe color palette is exhausted. The drawback of using approximations isthat the colors might not be exactly what you specified. Note1: Thisdoes only apply to a palette image, not true color images since theydon't have the limitations of maximum number of colors.</TD></TR><TR><TD valign="top">"ERR_DEPRECATED",false</TD><TD>Should usage ofdeprecated functions and parameters give a fatal error? (Useful tocheck if code is future proof.)</TD></TR><TR><TD valign="top">"BRAND_TIMING",false</TD><TD>Should the time takento generate each picture be branded to the lower left in corner in eachgenerated image? Useful for performance measurements generating graphs</TD></TR><TR><TD valign="top">"BRAND_TIME_FORMAT","Generated in: %01.3fs"</TD><TD>What format should be used for the timing string?</TD></TR></TABLE><P> The following defines should very rarely need to be changed</P><P></P><TABLE cellpadding="3" cellspacing="0" class="codedefines"><TR><TH>Define, default value</TH><TH>Comment</TH></TR><TR><TD valign="top">"CACHE_FILE_GROUP","wwwadmin"</TD><TD>What groupshould the cached file belong to (Set to "" will give the default groupfor the "PHP-user") Please note that the Apache user must be a memberof the specified group since otherwise it is impossible for Apache toset the specified group.</TD></TR><TR><TD valign="top">"CACHE_FILE_MOD",0664</TD><TD>What permissionsshould the cached file have (Set to "" will give the defaultpermissions for the "PHP-user")</TD></TR><TR><TD valign="top">"USE_BRESENHAM",false</TD><TD>Decide if we shoulduse the Bresenham circle algorithm or the built in Arc(). Bresenhamgives better visual appearance of circles but is more CPU intensive andslower then the built in Arc() function in GD. Turned off by defaultfor speed</TD></TR><TR><TD valign="top">"_CSIM_SPECIALFILE","_csim_special_"</TD><TD>Special file name to indicate that we only want to calc the image map inthe call to Graph::Stroke() used internally from the GetHTMLCSIM()method.</TD></TR><TR><TD valign="top">"_CSIM_DISPLAY","_jpg_csimd"</TD><TD>HTTP GETargument that is used with image map to indicate to the script to justgenerate the image and not the full CSIM HTML page.</TD></TR></TABLE> <P> </P><P>&nbsp</P></DIV></BODY></HTML>