\section{Chart::Base}
\herv{Name:} Chart::Base\\ \\
\herv{File:} Base.pm\\ \\
\herv{Requires:}GD, Carp, FileHandle\\ \\
\herv{Description:} \fett{Base} is the \fett{abstract superclass} of the modules: Bars, Composite, Direction, ErrorBars, HorizontalBars, Lines, LinesPoints, Mountain, Pareto, Pie, Points, Split, StackedBars\\
The class Base provides all public methods and most of the attributs of a chart object.\\
\\
\herv{Constructor:} An instance of a chart object can be created with the constructor new():\\
\fett{\$obj = Chart::\kursiv{Type}->new();}\\
\fett{\$obj = Chart::\kursiv{Type}->new(\kursiv{width}, \kursiv{height});}\\
\\
\kursiv{Type} means the type of chart it returns, i.e. Chart::Bars returns a chart with bars.\\
If \fett{new} has no arguments, the constructor returns an object with the size 300x400 pixels. If new has two arguments \kursiv{width} and \kursiv{height}, it returns a chart object with the desired size. \\ 
\\ 
\label{methods}\herv{Methods:}\\
\\
\fett{\$obj->add\_dataset(@array);}\\ \fett{\$obj->add\_dataset($\backslash$@array\_ref);}\\
Adds a dataset to the object. The parameter is an array or a reference to an array. Generally the first added array are interpreted by chart as the x-tick labels. The following arrays should include the data points. For example if the first call with an bars object is\\
\\
\kursiv{\$obj->add\_dataset('Harry', 'Sally');}  and the second call is\\ \kursiv{\$obj->add\_dataset(5, 8);}\\
\\
then chart will draw a picture with two bars and label them with Harry and Sally.\\ \\
Some modules handle it a little bit different. Look at the respective description of the module to get more information.\\
There are also differences if you want to use the \fett{xy\_plot} option, to create a xy-graph. \\
\\
\\
\fett{\$obj->add\_pt(@array);} \\ \fett{\$obj->add\_pt($\backslash$@array\_ref);}\\
This is another method to add data to a chart object. An argument can be an array or a reference to an array. If you use this method, chart wants the complete data of one data point.\\
For example\\
\\
\kursiv{\$obj->add\_pt('Harry', 5);}\\ 
\kursiv{\$obj->add\_pt('Sally', 8);}\\
\\
would create the same graph as the example for add\_dataset.\\
\\
\\
\fett{\$obj->add\_datafile( "file", \kursiv{type} );} \\
\fett{\$obj->add\_datafile( \$filehandle, \kursiv{type} );} \\
This method adds a complete data file to the chart object.\\
\kursiv{Type} can be 'set' or 'pt'. If the parameter is 'set' then one line in the data file has to be a complete data set. The values of the set has to be separated by whitespaces. For Example the file looks like this:\\
\\
Harry  Sally\\
3      8\\
2      1\\
\\
If the parameter is 'pt' the lines of the file have to look like the parameter arrays of the add\_pt method. Which means the line includes all values of one data point, also separated by whitespaces. For Example:\\
\\
Harry 3 2\\
Sally 8 1\\
\\
\\
\fett{\$obj->get\_data();} \\
If you want a copy of the data that has been added so far, make a call to the get\_data method like so:\\
\\
\kursiv{\$dataref = \$obj->get\_data();}\\
\\
It returns a reference to an array of references to datasets. For Example, you can get the x-tick labels this way:\\
\kursiv{@x\_labels = @\{\$dataref->[0]\};}\\
\\
\\ 
\fett{\$obj->clear\_data();} \\
This is the method to remove all data that may have been entered before.\\
\\
\\
\fett{\$obj->set( \kursiv{attribut 1} => \kursiv{value 1}, ... ,\mbox{\kursiv{attribute n} => \kursiv{value n}} );}\\
\fett{\$obj->set( \%hash );}\\
\fett{\$obj->set( \kursiv{attribut 1}, \kursiv{value 1}, ... ,\mbox{\kursiv{attribute n}, \kursiv{value n}} );}\\
\fett{\$obj->set( @array );}\\
Use this method to change the attributes of the chart object. Set looks for a hash of keys and values or an array of keys and values.\\
For Example\\
\\
\kursiv{\$obj->set( 'title' => 'The title of the image');}\\
\\
would set the title. The same job would do:\\
\\
\kursiv{\%hash = ('title' => 'The title of the image');}\\ 
\kursiv{\$obj->set( \%hash);}\\
\\
\\
\fett{\$obj->png( "file" );} \\
\fett{\$obj->png( \$filehandle );} \\
\fett{\$obj->png( FILEHANDLE );} \\
\fett{\$obj->png( "file", $\backslash$@data );}\\
This method creates the png file. The file parameter can be, the file name, a reference to a filehandle or a filehandle itself. If the file doesn't exist, chart will create a file for you. If there is already a file, chart will overwrite this file.\\
You can also add the data to the chart object in the png method. The @data array should contain references to arrays of data, with the first array reference pointing to an array with x-tick labels. @data could look like this:\\
\\
\kursiv{@data = (['Harry', 'Sally'], [5, 8], [50, 80]);}\\
\\
This would set up an graph with two datasets, and three data points in these sets.\\
\\
\\
\fett{\$obj->jpeg( "file" );} \\
\fett{\$obj->jpeg( \$filehandle );} \\
\fett{\$obj->jpeg( FILEHANDLE );} \\
\fett{\$obj->jpeg( "file", $\backslash$@data );}\\
These are the methods to create jpeg files. They work similar like the png() method. \\
\\
\\
\fett{\$obj->cgi\_png();} \\
\fett{\$obj->cgi\_jpeg();} \\
With the cgi methods you can create dynamic images for your web site. The cgi methods will print the chart, along with the appropriate http header to stdout, allowing you to call chart-generating scripts directly from your html pages (ie. with a <img scr=image.pl>HTML tag).\\
\\
\\
\fett{\$obj->imagemap\_dump();} \\ 
Chart can also return the pixel positioning information so that you can create image maps from the files Chart generates. Simply set the 'imagemap' option to 'true' before you generate the file, then call the imagemap\_dump method to retrieve the information. A structure will be returned almost identical to the @data array described above to pass the data into Chart.\\
\\
\kursiv{\$imagemap\_data = \$obj->imagemap\_dump();}\\
\\
Instead of single data values, you will be passed references to arrays of pixel information. For Bars, HorizontalBars, Pareto and StackedBars charts, the arrays will contain two x-y pairs (specifying the upper left and the lower right corner of the bar), like so\\
\\
\kursiv{( \$x1, \$y1, \$x2, \$y2 ) = @\{ \$imagemap\_data->[\$dataset][\$datapoint] \};}\\
\\ 
For Lines, Points, LinesPoints and Split, the arrays will contain a single xy-pair (specifying the center of the point), like so\\
\\
\kursiv{( \$x, \$y) = @\{ \$imagemap\_data->[\$dataset][\$datapoint] \};}\\
\\
A few caveats apply here. First of all, Chart uses the GD-module by Lincoln Stein to draw lines, circles, strings, and so on. GD treats the upper-left corner of the png/jpeg as the (0,0) point, so positives y values are measured from the top of the png/jpeg, not the bottom. Second, these values will mostly contain long decimal values. GD, of course, has to truncate these to single pixel values. In a worst-case scenario, this will result an error of one pixel on your imagemap. If this is really an issue, your only option is to experiment with it, or to contact Lincoln Stein and ask him. Third, please remember that the 0th dataset will be empty, since that's the place in the @data array for the data point labels.\\
\\
\\   
\label{options}\herv{Attributes/Options:} These are the options which have effects on all types of chart:
\begin{description}
\item ['transparent']Makes the background of the image transparent if set to 'true'. Useful for making web page images. It doesn't work for all browsers. Defaults to false.
\item ['png\_border']Sets the number of pixels used as a border between the graph and the edges of the png/jpeg. Defaults to 10.
\item ['graph\_border']Sets the number of pixels used as a border between the title/labels and the actual graph within the png/jpeg.  Defaults to 10.
\item['text\_space']Sets the amount of space left on the sides of text, to make it more readable.  Defaults to 2.
\item['title']Tells Chart what to use for the title of the graph.  If empty, no title is drawn.  It recognizes '$\backslash$n' as a newline, and acts accordingly. Remember, if you want to use normal quotation marks instead of single quotation marks then you have to quote "`$\backslash\backslash$n"'. Default is empty.
\item['sub\_title']Writes a sub-title under the title in smaller letters.
\item['x\_label']Tells Chart what to use for the x-axis label.  If empty, no label is drawn.  Default is empty.
\item['y\_label', 'y\_label2']Tells Chart what to use for the y-axis labels.  If empty, no label is drawn.  Default is empty.
\item['legend']Specifies the placement of the legend.  Valid values are 'left', 'right', 'top', 'bottom'.  Setting this to 'none' tells chart not to draw a legend.  Default is 'right'.
\item['legend\_labels']Sets the values for the labels for the different datasets. Should be assigned a reference to an array of labels.  For example,\\
\\
@labels = ('foo', 'bar');\\
\$obj->set ('legend\_labels' => $\backslash$@labels);\\
\\
Default is empty, in which case 'Dataset 1', 'Dataset 2', etc. are used as the labels.
\item['tick\_len']Sets the length of the x- and y-ticks in pixels.  Default is 4.
\item['x\_ticks']Specifies how to draw the x-tick labels.  Valid values are 'normal', 'staggered' (staggers the labels vertically), and 'vertical' (the labels are draw upwards).  Default is 'normal'.
\item['min\_y\_ticks']Sets the minimum number of y\_ticks to draw when generating a scale. Default is 6, The minimum is 2.
\item['max\_y\_ticks']Sets the maximum number of y\_ticks to draw when generating a scale. Default is 100. This limit is used to avoid plotting an unreasonably large number of ticks if non-round values are used for the min\_val and max\_val.\\
\\
The value for 'max\_y\_ticks' should be at least 5 times larger than 'min\_y\_ticks'.
\item['max\_x\_ticks', 'min\_x\_ticks'] Works similar as 'max\_y\_ticks' and 'min\_y\_ticks'. Of course, it works only for xy-plots! 
\item['integer\_ticks\_only']Specifies how to draw the x- and y-ticks: as floating point ('false', '0') or as integer numbers ('true', 1). If you want integer ticks, it is maybe better to set the option 'precision' at zero. Default: 'false'
\item['skip\_int\_ticks']If 'integer\_ticks\_only' was set to 'true' the labels and ticks at the y-axis will be drawn every nth tick. Of course in HorizontalBars it affects the x-axis. Default to 1, no skipping.
\item['precision'] Sets the number of numerals after the decimal point. Affects in most cases the y-axis. But also the x-axis if 'xy\_plot' is set and the labels in a pie chart. Defaults to 3.
\item['max\_val']Sets the maximum y-value on the graph, overriding the normal autoscaling.  Does not work for a Split chart. Default is undef.
\item['min\_val']Sets the minimum y-value on the graph, overriding the normal autoscaling.  Does not work for a Split chart. Default is undef.\\
\\
Caution should be used when setting 'max\_val' and 'min\_val' to floating point or non-round numbers. This is because the scale must start \& end on a tick, ticks must have round-number intervals, and include round numbers.\\
\\
Example: Suppose your dataset has a range of 35-114 units, If you specify them as the 'min\_val' \& 'max\_val', The y\_axis will be plot with 80 ticks every 1 unit.. If no 'min\_val' \& 'max\_val', the system will autoscale the range to 30-120 with 10 ticks every 10 units.\\
\\
If the 'min\_val' \& 'max\_val' are specified to exesive precision, they may be overiden by the system, plotting a maximum 'max\_y\_ticks' ticks. 
\item['include\_zero']If 'true', forces the y-axis to include zero if it is not in the dataset range. Default is 'false'.\\
\\
In general, it is better to use this, than to set the 'min\_val' if that is all you want to achieve.
\item['skip\_x\_ticks']Sets the number of x-ticks and x-tick labels to skip.  (ie. if 'skip\_x\_ticks' was set to 4, Chart would draw every 4th x-tick and x-tick label).  Default is undef.
\item['custom\_x\_ticks']This option allows you to specify exactly which x-ticks and x-tick labels should be drawn. It should be assigned a reference to an array of desired ticks.  Just remember that I'm counting from the 0th element of the array.  (e.g., if 'custom\_x\_ticks' is assigned [0,3,4], then the 0th, 3rd, and 4th x-ticks will be displayed) It doesn't work for Split, HorizontalBars and Pie.
\item['f\_x\_tick']Needs a reference to a function which uses the x-tick labels generated by the @data->[0] as the argument. The result of this function can reformat the labels. For instance\\
\\
\$obj -> set ('f\_x\_tick' => $\backslash$\&formatter );\\
\\
An example for the function formatter: x labels are seconds since an event. The referenced function can transform this seconds to hour, minutes and seconds.
\item['f\_y\_tick']The same situation as for 'f\_x\_tick' but now used for y labels.
\item['colors']This option lets you control the colors the chart will use.  It takes a reference to a hash.  The hash should contain keys mapped to references to arrays of rgb values.  For instance,\\
\\
\$obj->set('colors' => {'background' => [255,255,255]});\\
\\
sets the background color to white (which is the default).  Valid keys for this hash are\\
\\
'background' (background color for the png)\\
'title' (color of the title)\\
'text' (all the text in the chart)\\
'x\_label' (color of the x axis label)\\ 
'y\_label' (color of the first y axis label)\\
'y\_label2' (color of the second y axis label)\\
'grid\_lines' (color of the grid lines)\\
'x\_grid\_lines' (color of the x grid lines - for x axis ticks)\\
'y\_grid\_lines' (color of the y grid lines - for to left y axis ticks)\\
'y2\_grid\_lines' (color of the y2 grid lines - for right y axis ticks)\\
'dataset0'..'dataset63' (the different datasets)\\
'misc' (everything else, e.g. ticks, box around the legend)\\
\\
NB. For composite charts, there is a limit of 8 datasets per component. The colors for 'dataset8' through 'dataset15' become the colors for 'dataset0' through 'dataset7' for the second component chart.
\item['title\_font'] This option changes the font of the title. The key has to be a Gd font. e.g. GD::Font->Large 
\item['label\_font'] This option changes the font of the labels. The key has to be a Gd font. 
\item['legend\_font'] This option changes the font of the text of the legend. The key has to be a Gd font. 
\item['tick\_label\_font'] This option changes the font of the ticks. The key has to be a Gd font. 
\item['grey\_background']Puts a nice soft grey background on the actual data plot when set to 'true'.  Default is 'true'.
\item['x\_grid\_lines']Draws grid lines matching up to x ticks if set to 'true'. Default is 'false'.
\item['y\_grid\_lines']Draws grid lines matching up to y ticks if set to 'true'. Default is 'false'.
\item['grid\_lines']Draws grid lines matching up to x and y ticks if set to 'true'. Default is 'false'. 
\item['imagemap']Lets Chart know you're going to ask for information about the placement of the data for use in creating an image map from the png. This information can be retrieved using the imagemap\_dump() method.  NB. that the imagemap\_dump() method cannot be called until after the Chart has been generated (e.g. using the png() or cgi\_png() methods).
\item['ylabel2']The label for the right y-axis (the second component chart).  Default is undef.
\item['no\_cache']Adds Pragma: no-cache to the http header. Be careful with this one, as Netscape 4.5 is unfriendly with POST using this method.
\item['legend\_example\_size'] Sets the length of the example line in the legend. Defaults to 20.
\end{description}

 