NAME

Chart::Plot::Annotated - Subclass of Chart::Plot that allows text annotation of data-points.

SYNOPSIS

  use Chart::Plot::Annotated;

  # initialize same as Chart::Plot
  my $img = Chart::Plot::Annotated->new();
  my $anotherImg =
    Chart::Plot::Annotated->new($image_width, $image_height);

  # setData() method uses extra initial argument of datapoint
  # annotation strings. Must be the same length as the number of
  # points. Can use undef or '' to indicate no annotation for a given
  # point.

  $img->setAnnoData (\@annotations, \@dataset)
     or die( $img->error() );
  $img->setAnnoData (\@annotations, \@xdataset, \@ydataset);
  $img->setAnnoData (\@yetmoreAnnos, \@xanotherdataset, \@yanotherdataset,
                     'Blue SolidLine NoPoints');

  # note the new keys allowed for setGraphOptions:
  $img->setGraphOptions ('horGraphOffset' => 75,
                         'vertGraphOffset' => 100,
                         'title' => 'My Graph Title',
                         'horAxisLabel' => 'my X label',
                         'vertAxisLabel' => 'my Y label',

      # now there are new keys allowed:
                         'anno_color' => [ 255, 0, 0 ], # red anno
                                                        # text!
                         'anno_xpix_offset' => 2,
                         'anno_ypix_offset' => -2,
                         # using anno_font requires that GD be 'use'd
                         # in this module to name fonts
                         'anno_font' => gdMediumBoldFont,
                         );

  # can still use Chart::Plot's methods:
  $img->setData (\@anotherdataset, 'red_dashedline_points');
  my ($xmin, $ymin, $xmax, $ymax) = $img->getBounds();

  # prints annotated Chart
  print $img->draw();

DESCRIPTION

A subclass of Chart::Plot that provides a new method allowing text annotations on groups of datapoints.

Features

Additional methods

In addition to those methods provided by Chart::Plot, this class provides the following additional methods:

setAnnoData

  $img->setAnnoData (\@annos, \@data);
  $img->setAnnoData (\@annos, \@xdata, \@ydata);
  $img->setAnnoData (\@annos, \@data, 'red_dashedline_points');
  $img->setAnnoData (\@annos, \@xdata, \@ydata, 'blue solidline');

Like parent class (see Chart::Plot), but takes additional initial argument arrayref of the text annotations for the datapoints.

Unlike parent class (in some scenarios), the positions of the annotations are fixed when passed to this function, so if you modify the data after passing it in, the parent class data-plotting may move the datapoints, but the annotations will consistently remain where the datapoints were when entered. Caveat user. (and see the notes on this subject in Chart::Plot's documentation).

Note that for un-annotated datasets, you can still use the setData method from the parent class on Chart::Plot::Annotated objects, even in the same image.

Additional graph options

In addition to the graph options provided by Chart::Plot, this module also provides the following graph-wide options:

anno_color

Requires an arrayref with 3 values indicating the (R,G,B) values for the desired color. This color applies to all the datapoint annotations in the plot.

anno_font

Requires a GD::Font object as a value. The default is gdTinyFont.

anno_xpix_offset

The number of horizontal pixels from the data point to set the annotations. This can be negative or positive. Default is 0.

anno_ypix_offset

The number of vertical pixels from the data point to set the annotations. This can be negative or positive. Default is 0.

TO DO

allow colors to be set per annotation group

This would be nice.

allow font variation per anno group

Nice to have, as well. Should probably have the same per-annotation group treatment that color should get.

HISTORY

0.01

Original version; created by h2xs 1.21 with options

  -CAX
        Chart::Plot::Annotated

AUTHOR

Jeremy Kahn, <kahn@cpan.org>

SEE ALSO

Chart::Plot by Sanford Morton.

perl.