The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Chart::Pie - a pie charting module

SYNOPSIS

    use Chart::Pie;

    $obj = Chart::Pie->new;
    $obj = Chart::Pie->new ( $gif_width, $gif_height );
   
    $obj->set ( $key_1, $val_1, ... ,$key_n, $val_n );
    $obj->set ( $key_1 => $val_1,
           ...
           $key_n => $val_n );
    $obj->set ( %hash );

    # GIFgraph.pm-style API
    @data = ( \@x_tick_labels, \@dataset1, ... , \@dataset_n );
    $obj->gif ( "filename", \@data );
    $obj->gif ( $filehandle, \@data );
    $obj->gif ( FILEHANDLE, \@data );
    $obj->cgi_gif ( \@data );

    # Graph.pm-style API
    $obj->add_pt ($label, $val_1, ... , $val_n);
    $obj->add_dataset ($val_1, ... , $val_n);
    $obj->gif ( "filename" );
    $obj->gif ( $filehandle );
    $obj->gif ( FILEHANDLE );
    $obj->cgi_gif ();

DESCRIPTION

This module builds upon David Bonner's Chart v0.99 module, and provides a Pie charting ability. The original Chart module already provides lines, bars, stackedbars, etc. Even most of this POD was scalped from his Chart.pod document.

I tried to make the API for this module as similar to the other Chart modules as possible, reusing as many of it's functions as I could, and only adding options and optional values as necessary. I really like David Bonner's Chart module, and using his code as a template, came up with the Pie module in about a day.

Like GIFgraph, Chart uses Lincoln Stein's GD module for all of its graphics primitives calls, which means the Pie module does, also.

use-ing Chart::Pie

There's really no Chart::Pie module, but like the other chart types provided, it is really just a new class inheriting from the Chart::Base class.

For example,

  use Chart::Pie;

would invoke the Pie module.

Getting an object

The new method can either be called without arguments, in which case it returns an object with the default image size (400x300 pixels), or you can specify the width and height of the image. For example,

  $obj = Chart::Pie (600,400);

would return a Chart::Pie object containing a 600x400 pixel image. New also initializes most of the default variables, which you can subsequently change with the set method.

Setting different options

Almost all of the different set options are available from the main Chart module. Please refer to Chart.pod for a description of those. I will describe here the options and new values pertaining only to the Pie module.

The following are all of the currently supported options:

'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' => \@labels);

Default is empty, in which case 'Dataset 1', 'Dataset 2', etc. are used as the labels.

For a pie graph, this option is NOT ignored. The values for the legend labels are used as the labels for the pie slices. I'll explain later why I use the legend_labels rather than the dataset0, or x_tick_labels value for the pie slice labels.

'x_ticks'

Default is 'normal'. But, a new valid value for Pie charts is 'none'. This will keep the ticks and tick labels along the x-axis from being drawn, as tick labels are not usually useful for pie charts.

'y_ticks'

Default is 6. But, a new valid value for Pie charts is 'none'. This will keep the ticks and tick labels along the y-axis from being drawn, as tick labels are not usually useful for pie charts.

'imagemap'

This option is currently unsupported by the Pie chart module.

'label_values'

Default is undef. This is used to optionally display the numerical value or percentage value of each pie slice in a pie chart along with the label. Valid values are 'percent', 'value', or 'both'.

EXAMPLE 1 - Simple Pie Chart

   use Chart::Pie;

   my $chart = Chart::Pie->new(640,480);

   $chart->set( 'title'   => 'A Day in the Life',
                'x_label' => 'X Axis Label',
                'y_label' => 'Y Axis Label' ,
                'label_values' => 'percent', # tell me percentage of
                                             # each day spent on
                                             # each activity
                'x_ticks'  => 'none',
                'y_ticks'  => 'none',
   );

   $chart->add_dataset( qw(Junk_X_Tick_Label) );
   $chart->add_dataset( qw(8) );
   $chart->add_dataset( qw(8) );
   $chart->add_dataset( qw(2) );
   $chart->add_dataset( qw(6) );


   $chart->set('legend_labels' => [ 'Sleep', 'Work', 'Eat', 'Watch TV' ]);
   $chart->gif('output.gif');

EXAMPLE 2 - Another Pie Chart

This is an example as to why the pie slice labels come from the legend labels, rather than the x tick values.

   use Chart::Pie;

   my $chart = Chart::Pie->new(640,480);

   $chart->set( 'title'   => 'A Week in the Life',
                'x_label' => 'X Axis Label',
                'y_label' => 'Y Axis Label' ,
                'label_values' => 'value', # tell me how many hours
                                           # for each activity
                'x_ticks'  => 'none',
                'y_ticks'  => 'none',
   );

   # Now, you will see below the same data that could be
   # passed to a Bars or StackedBars chart. I felt that
   # a pie chart of this data was more meaningful
   # if it told me how much time I spent working, eating,
   # etc..., rather than that Monday was a 24 hour day,
   # Tuesday was a 24 hour day, and Saturday was 22 hour
   # day.  By using the legend (or dataset) labels for the
   # pie slices, I get a more meaningful chart.
   $chart->add_dataset( qw(Mon Tue Wed Thu Fri Sat Sun) );
   $chart->add_dataset( qw(8   8   8   8   8   10  10 ) );
   $chart->add_dataset( qw(8   8   9   8   7   0   0  ) );
   $chart->add_dataset( qw(2   2   2   2   3   3   3  ) );
   $chart->add_dataset( qw(6   6   5   6   6   9   9  ) );


   $chart->set('legend_labels' => [qw(Sleep Work Eat WatchTV)]);
   $chart->gif('output.gif');

BUGS

Probably quite a few, since this is my very first module. As usual, please mail me with any bugs, patches, suggestions, comments, flames, death threats, etc.

Since I never use the data captured in dataset0, I should probably make adding the first dataset optional.

AUTHOR

Karlon West (karlon@netcom.com)

COPYRIGHT

Copyright(c) 1999 by Karlon West. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.