/ 
Tk-PlotDataset-2.03
River stage zero No dependents
/ Tk::PlotDataset

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 $main_window = 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 = $main_window -> PlotDataset
(
  -width => 500,
  -height => 500,
  -background => 'snow'
) -> pack(-fill => 'both', -expand => 1);

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

$graph -> plot;

MainLoop;

STANDARD OPTIONS

-background  -highlightthickness  -takefocus        -selectborderwidth
-borderwidth -insertbackground    -relief           -tile
-cursor      -insertborderwidth   -selectbackground -xscrollcommand
-insertwidth -highlightbackground -insertofftime    -yscrollcommand
-state       -highlightcolor      -insertontime     -selectforeground

WIDGET-SPECIFIC OPTIONS

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

-colors

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

This option only has an effect when datasets are plotted and therefore changing the array will not change the colour of the plots already on the graph. To change existing plots the colour must be set in the LineGraphDataset object or the dataset re-added to the graph.

-pointShapes

An array of point shapes to use for the display of the datasets. If there are more datasets than shapes in the array then the shapes will cycle. These shapes will be overwritten if the LineGraphDataset object already has a point shape assigned to it. Valid shapes are none, circle, square, triangle and diamond.

Like the -colors, this option only has an effect when datasets are plotted and therefore changing the array will not change the point shapes of the plots already on the graph.

-border

An array of four numbers which are the width of the border between the plot area and the canvas. The order is North (top), East (right), South (bottom) and West (left). By default, the borders are 25, 50, 100 and 50 respectively.

-zoomButton

Selects the mouse button used for zooming in and out. The value must be a number from 1 to 5 corresponding to the five potential mouse buttons, any other value will disable zooming on the graph. Typically the left mouse button is 1 (default) and the right is 3.

-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. This option will only affect axes where the auto-scale option has been turned off.

An axis can be reversed by swapping its minimum and maximum values around.

-plotTitle

A two element array. The first element is the plot title, the second element is the vertical offset of the title above the top of the graph. 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. The label will only be displayed if there are datasets using the y1-axis.

-xlabelPos

The vertical position of the x-axis label, relative to the bottom of the plot area. The default for this value is 40.

-ylabelPos

The vertical position of the y-axis label, relative to the left of the plot area. The default for this value is 40.

-y1labelPos

The vertical position of the y1-axis label, relative to the right of the plot area. The default for this value is 40.

-xTickFormat

This option can be used to override the default format strings, as used by sprintf, to generate the tick labels on the x-axis. In linear mode the default is '%.3g', in log mode '1e%3.2d' will be used for values less than zero and '1e+%2.2d' will be used for values of zero or more. If you override this format, it will apply to all values in all modes of the x-axis.

-yTickFormat

This option can be used to override the default format strings, as used by sprintf, to generate the tick labels on the y-axis. In linear mode the default is '%.3g', in log mode '1e%3.2d' will be used for values less than zero and '1e+%2.2d' will be used for values of zero or more. If you override this format, it will apply to all values in all modes of the y-axis.

-y1TickFormat

This option can be used to override the default format strings, as used by sprintf, to generate the tick labels on the y1-axis. In linear mode the default is '%.3g', in log mode '1e%3.2d' will be used for values less than zero and '1e+%2.2d' will be used for values of zero or more. If you override this format, it will apply to all values in all modes of the y1-axis. The y1-axis ticks will only be displayed if there are datasets using the y1-axis.

-balloons

Should be set to a true value (eg. 1) in order to enable coordinate balloons, or a false value (eg. 0) to disable them. Coordinate balloons are enabled by default.

-legendPos

A two element array which specifies the position of the legend. The first element specifies where the legend should be, either 'bottom' for below the chart, and 'side' for the right side of the chart. The second element is the distance from the edge of the chart to the legend. By default, the legend is 80 pixels below the chart.

-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.

-logMin

Applies to all logarithmic axes. A replacement value for zero or negative values that cannot be plotted on a logarithmic axis. The default value is 1e-3.

-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 axes ticks, the second is the font for the axes 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.

-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
    );
  }
);

Tk::LineGraphDataset Options

In addition to the standard options of the LineGraphDataset module, it is also possible to use additional options for use with PlotDataset. Please note that these options will only have an effect on PlotDataset and no other module and hence are not documented in LineGraphDataset.

-pointSize

Sets the size of the points in the dataset's plot. The value can be any positive integer. The default for this value is 3.

-pointStyle

A string which sets the shape of the point for the dataset's plot. Setting this option will override Tk::PlotDataset's -pointShapes option for the dataset. Like the -pointShapes option, valid shapes are none, circle, square, triangle and diamond.

-lineStyle

A string which sets the pattern of the line for the dataset's plot. Valid patterns are normal (solid line), dot, dash, dotdash and none. By default, all lines will be solid.

-fillPoint

A boolean value which determines the appearance of the dataset's points. If the value is true (eg. 1), the point is a solid colour, otherwise (eg. 0) only an outline of the point is shown. By default, all points will be filled.

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 automatically scaled or set by the code. The axes can have linear or logarithmic scales and there is also an option of an additional y-axis (y1).

Behaviour

When the mouse cursor passes over a plotted line or its entry in the legend, the line and its entry will turn red to help identify it. Holding the cursor over a point on the graph will display the point's coordinates in a help balloon (unless disabled). Individual points are not shown when there are more than 20 points in the plot.

By default, 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 mouse button and move to the opposite corner. Release the mouse button and the graph will zoom into the box. To undo one level of zoom click the mouse button without moving the cursor.

WIDGET METHODS

The PlotDataset (or new) method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage, which can be used to enquire and modify the options described above (except -colors and -pointShapes). The widget also inherits all the methods provided by the Tk::Canvas class.

In addition, the module provides its own methods, described below:

$plot_dataset -> addDatasets ( dataset1 , dataset2 , ... )

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

$plot_dataset -> clearDatasets

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

$plot_dataset -> plot ( rescale )

Updates the graph to include changes to the graph's configuration or datasets. The parameter rescale can be one of three options:

'always' to always rescale plot. This is the default.

'never' to never rescale plot.

'not_zoomed' to only rescale when the plot is not zoomed in.

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 optional 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 -noLegend option for datasets, allowing them to be excluded from the legend.

- Added support for the -pointSize, -pointStyle, -lineStyle and -fillPoint LineGraphDataset options.

- 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).

- Changed the legend so that it displays an example line and point. This legend can be either at the bottom or side of the chart.

- Added -xTickFormat, -yTickFormat and -y1TickFormat options to configure the format of the number labels on each axis.

- Removed all bindings to the mouse buttons except for zooming. The mouse button used for zooming can be configured.

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.

- Fixed a memory leak that occurred when the value passed to the configure method was an array reference.

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. It will also not be possible to zoom the graph if y1-axis has a log scale but no data.

- 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.

- The widget does not work with the Tk::Scrolled module.

COPYRIGHT

Copyright 2012 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, Tim Culmer and Stephen Spain. 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