NAME

PlotDataset - An extended version of the canvas widget for plotting 2D line graphs. Plots have a legend and zooming capabilities.

SYNOPSIS

 use Tk;
 use Tk::PlotDataset;
 use Tk::LineGraphDataset;

 my $mainWindow = MainWindow -> new;

 my @data1 = (0..25);
 my $dataset1 = LineGraphDataset -> new
                                    (
                                      -name => 'Data Set One',
                                      -yData => \@data1,
                                      -yAxis => 'Y',
                                      -color => 'purple'
                                    );

 my @data2x = (0..25);
 my @data2y = ();
 foreach my $xValue (@data2x)
 {
   push (@data2y, $xValue ** 2);
 }
 my $dataset2 = LineGraphDataset -> new
                                    (
                                      -name => 'Data Set Two',
                                      -xData => \@data2x,
                                      -yData => \@data2y,
                                      -yAxis => 'Y1',
                                      -color => 'blue'
                                    );

 my $graph = $mainWindow -> PlotDataset
                            (
                              -width => 500,
                              -height => 500,
                              -background => 'snow'
                            ) -> pack(-fill => 'both', -expand => 1);

 $graph -> addDatasets($dataset1, $dataset2);

 $graph -> plot();

 MainLoop;

DESCRIPTION

PlotDataset is a quick and easy way to build an interactive plot widget into a Perl application. The module is written entirely in Perl/Tk.

The widget is an extension of the Canvas widget that will plot LineGraphDataset objects as lines onto a 2D graph. The axes can be automaically scaled or set by the code. The axes can have linear or logrithmic scales and there is also an option of an additional y-axis (Y1).

Behaviour

When the cursor is on a plotted line, the line turns red to help identify that line in the plot. Likewise when the cursor is over a Dataset name in the legend the corresponding dataset line plot will turn red. Holding the cursor over a point on the graph will display the point's coordinates in a help balloon. Individual points are not shown when there are more than 20 points in the plot.

The left button (button-1) is used to zoom a graph. Move the cursor to one of the corners of the box into which you want the graph to zoom. Hold down the left button and move to the opposite corner. Release the left button and the graph will zoom into the box. To undo one level of zoom click the left button without moving the mouse.

Options

In addition to the Canvas options, the following option/value pairs are supported. All of these options can be set in the new() function when the PlotDataset object is created or by using the configure method:

-colors

An array of colours to use for the display of the data sets. If there are more data sets than colours in the array then the colours will cycle. These colours will be overwritten if the LineGraphDataset object already has a colour assigned to it.

-borders

An array of four numbers which are the border sizes in pixels of the plot in the canvas. The order is North (top), East (right), South (bottom) and West (right).

-scale

A nine element array of the minimum, maximum and step values of scales on each of the three axes - x, y, and y1. The order of the nine values is xMin, xMax, xStep, yMin, yMax, yStep, y1Min, y1Max and y1Step. The default values for all the axis are 0 to 100 with a step size of 10.

-plottitle

A two element array. The first element is the plot title, the second element is the vertical offset of the title below the top edge of the window. The title is centered in the x direction.

-xlabel

The text label for the X-axis. The text is centered on the X-axis.

-ylabel

The text label for the Y-axis. The text is centered on the Y-axis.

-y1label

The text label for the Y1-axis, which is the optional axis to the right of the plot. The text is centered on the Y1-axis.

-xType

The scale type of the X-axis. Can be linear or log. The default type is linear.

-yType

The scale type of the Y-axis. Can be linear or log. The default type is linear.

-y1Type

The scale type of the y1 axis. Can be linear or log. The default type is linear.

-fonts

A four element array with the font names for the various labels in the plot. The first element is the font of the numbers at the axis ticks, the second is the font for the axis labels (all of them), the third is the plot title font and fourth is the font for the legend.

 $graph -> configure(-fonts => 
                     [
                       'Times 8 bold', 
                       'Courier 8 italic', 
                       'Arial 12 bold', 
                       'Arial 10'
                     ]);

The format for each font string is; the name of the font, followed by its size and then whether it should be in bold, italic or underlined.

-autoScaleX

When set to "On" the X-axis will be scaled to the values to be plotted. Default is "On". "Off" is the other possible value.

-autoScaleY

When set to "On" the Y-axis will be scaled to the values to be plotted. Default is "On". "Off" is the other possible value.

-autoScaleY1

When set to "On" the Y1-axis will be scaled to the values to be plotted. Default is "On". "Off" is the other possible value.

-logMin

Applies to all logrithmic axes. A replacement value for zero or negative values that cannot be plotted on a logarithmic axis.

-redraw

A subroutine that is called when the graph is redrawn. It can be used to redraw widgets, such as buttons, that have been added to the graph's canvas. Without the subroutine anything on the graph would be overwritten.

 $graph -> configure
           (
             -redraw => sub
             {
               my $button = $graph -> Button(-text => 'Button');
               $graph -> createWindow
               (
                 $graph -> cget(-width) - 8, $graph -> cget(-height) - 8,
                 -anchor => 'se', -height => 18, -width => 100,
                 -window => $button
               );
             }
           );

METHODS

addDatasets($dataset1, $dataset2, etc...)

Adds one or more dataset objects to the plot. Call the plot() method afterwards to see the newly added datasets.

clearDatasets()

Removes all the datasets from the plot. Call the plot() method afterwards to clear the graph.

plot()

Updates the graph to include changes to the graph's configuration or datasets.

Note: Changes to the graph's configuration or datasets will also be applied when the graph is rescaled when zooming in or out.

HISTORY

This Tk widget is based on the Tk::LineGraph module by Tom Clifford. Due to trouble with overriding methods that call methods using SUPER:: LineGraph could not be used as a base class.

The main difference between this module and the original is that the graph is created as a widget and not in a separate window. It therefore does not have the drop down menus used to configure the graph in the original.

Other additions/alterations are:

- Used Tk::Balloon to add coordinate pop-ups to data points.

- Running the cursor over a line name in the legend will highlight the curve on the graph.

- Added a clearDatasets method for removing all datasets from a plot.

- Added support for a -noLine boolean attribute of datasets.

- Added support for a -noLegend option for datasets, allowing them to be excluded from the legend.

- Added -redraw option to allow a callback to be added to draw additional items onto the canvas when it is redrawn.

- Option for a logarithmic scale on the x-axis (previously this was only available on the y-axis).

- Removed all bindings for buttons 2 and 3.

A number of bugs in the original code have also been found and fixed:

- Plots could be dragged using button 3 - this is not useful.

- If less than ten colours were provided, then the colour usage failed to cycle and caused an error.

- If the user zooms beyond a range of approximately 1e-15, then it hangs.

- Scale values of 0 were frequently displayed as very small numbers (approximately 1e-17).

- Small grey boxes were sometimes left behind when zooming out.

- In places, -tags was passed a string instead of an array reference, which caused problems especially in the legends method.

- Corrected an issue with the positioning of the Y1 axis label.

- Corrected a divide by zero error occurring when a vertical data line passes through a zoomed plot.

BUGS

Currently there are no known bugs, but there are a couple of the limitations to the module:

- If no data on the graph is plotted on the y-axis, i.e. the y1-axis is used instead, then it is not possible to zoom the graph.

- In the case where the number of points in the x and y axes are different the points with missing values are not plotted.

- Currently, if zero or negative numbers are plotted on a logarithmic scale their values are set to the value of -logMin. This can produce strange looking graphs when using mixed type axes. A future improvement would be to provide an option to omit non-valid points from the graph.

COPYRIGHT

Copyright 2007 I.T. Dev Ltd.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Any code from the original Tk::LineGraph module is the copyright of Tom Clifford.

AUTHOR

Andy Culmer and Tim Culmer. Contact via website - http://www.itdev.co.uk

Original code for the Tk::LineGraph module by Tom Clifford.

SEE ALSO

Tk::LineGraph Tk::LineGraphDataset

KEYWORDS

Plot 2D Axis