NAME

Pie.pm - 3D Piechart

SYNOPSIS

    use Chart::ThreeD::Pie;

    # create a new pie
    my $pie = new Chart::ThreeD::Pie (500, 300, "title");

    # add data
    $pie->add (160, '#FFAA00', 'part 1');
    $pie->add (350, '#00FF66', 'part 2');
    $pie->add (100, '#AA00FF', 'part 3');
    $pie->add (300, '#0000FF', 'part 4');
    $pie->add (300, '#DD00FF', 'part 5');
    $pie->add (300, '#00DDFF', 'part 6');

    # add a percentage after each label part.
    $pie->percents (1);

    # only draw parts greater or equal to 3%. All other parts will be
    # concatenated in to a part called "others" (using red color)
    $pie->limit (2, '#FF0000', 'others');

    # thickness of the pie
    $pie->thickness (30);

    # sort the "parts"
    $pie->want_sort (1);

    # foreground and background colors
    $pie->fgcolor ('#FF0000');
    $pie->bgcolor ('#00FFFF');

    # add a border
    $pie->border (1);

    # make sure we are writing to a binary stream
    binmode STDOUT;

    # Draw the pie, Convert the image to GIF and print it on standard output
    print $pie->plot->gif;

DESCRIPTION

    Chart::ThreeD::Pie allows you to create 3D Piecharts very easily
    and emit the drawings as GIF files. You can customize almost everything
    using a large number of methods.

    This module requires the Lincoln D. Stein's GD module available on CPAN.

Method Calls

Creating Pie

new

Chart::ThreeD::Pie::new(width, height, title) class method

To create a new pie, send a new() message to the Chart::ThreeD::Pie class. For example:

        $pie = new Chart::ThreeD::Pie (450, 320, 'my title');

This will create an image that is 450 x 320 pixels wide. If you don't specify the dimensions, a default of 400 x 300 will be chosen. The default title is an empty string (no title). The three parameters can be changed using the corresponding methods specified bellow.

Commands

thickness

Chart::ThreeD::Pie::thickness(val) object method

This allows you to set the thickness (in pixel) of the pie if val is defined. The current value is returned. Default value is 30 pixels.

Example:

      print "Current thickness is ", $pie->thickness, " pixels\n";
      # set it to 20.
      $pie->thickness(20);

want_sort

Chart::ThreeD::Pie::thickness(bool) object method

This will allow you to sort the parts of the pie if bool is non-null. The current value is returned. Default is null;

Example:

      print "Current want_sort value is ", $pie->want_sort, "\n";
      # set it to true
      $pie->want_sort(1);

transparent

Chart::ThreeD::Pie::transparent(bool) object method

This will allow you to make the background of the final picture transparent if bool is non-null. The current value is returned. Default is null;

Example:

      # Background will be transparent.
      $pie->transparent(1);

interlaced

Chart::ThreeD::Pie::interlaced(bool) object method

This will allow you to make the background of the final picture interlaced if bool is non-null. The current value is returned. Default is null;

Example:

      # Picture will be interlaced
      $pie->interlaced(1);

percents

Chart::ThreeD::Pie::percents(bool) object method

This will add percentages after the label of each part of the pie if bool is non-null. The current value is returned. Default is null;

Example:

      # add percents in labels
      $pie->percents(1);

bgcolor

Chart::ThreeD::Pie::bgcolor(bgcolor) object method

Set the background color if bgcolor is defined. The current value is returned. Default value is '#000000' (black). Color is a string composed of a '#' followed by 3 two-digits hexadecimal values, respectively Red, Green and Blue.

Example:

      # set the background color to yellow
      $pie->bgcolor ('#FFFF00');

fgcolor

Chart::ThreeD::Pie::fgcolor(fgcolor) object method

Set the foreground color if fgcolor is defined. The current value is returned. Default value is '#000000' (black). Color is a string composed of a '#' followed by 3 two-digits hexadecimal values, respectively Red, Green and Blue.

Example:

      # set the foreground color to red
      $pie->fgcolor ('#FF0000');

border

Chart::ThreeD::Pie::border(bool) object method

This will allow you to add a border to the final picture if bool is non-null. The current value is returned. Default is null. The color of the boder is specified by fgcolor.

Example:

      # Want a border
      $pie->border(1);

limit

Chart::ThreeD::Pie::limit(val, color, label) object method

This allows you to set the size (in percent) of the smallest part of the pie that will be drawn. All other parts will be merged into a single part labeled by 'label' and using the color 'color'. If 'val' is null, all parts are drawn. Default values are 7, '#FF0000' and 'others'. Current values are returned.

radius

Chart::ThreeD::Pie::radius(rad) object method

Specify the radius of the pie in pixels if rad is non-null. The current value is returned. The default value is a third of the xmax value given to the creation of the pie (first parameter of the constructor).

Example:

      # set radius to 100.
      $pie->radius(100);

xmax

Chart::ThreeD::Pie::xmax(val) object method

This allows you to set the length (in pixel) of the pie if val is defined. The current value is returned.

Example:

      print "Current length is ", $pie->xmax, " pixels\n";
      # set it to 600.
      $pie->xmax(600);

ymax

Chart::ThreeD::Pie::ymax(val) object method

This allows you to set the width (in pixel) of the pie if val is defined. The current value is returned.

Example:

      print "Current width is ", $pie->ymax, " pixels\n";
      # set it to 500.
      $pie->ymax(500);

title

Chart::ThreeD::Pie::title(val) object method

This allows you to change the title of the pie if val is defined. The current value is returned.

Example:

      print "Current title is '", $pie->title, "'\n";
      # set it to 'my own title'.
      $pie->title('my own title');

add

Chart::ThreeD::Pie::add(val, color, label) object method

This method adds a part to a pie. The size of the part is specified by val. Both color and label are optional. The default color is '#DDDDDD' and the default label is ''.

plot

Chart::ThreeD::Pie::plot() object method

Draw the pie. This method returns a GD object (see GD).

gif

Chart::ThreeD::Pie::gif() object method

This returns the image data in GIF format. You can then print it, pipe it to a display program, or write it to a file. You MUST call the plot() method at least once before calling gif().

Example:

    $pie->plot;
    open (PIPE, "| xv -") || die "Error: $!";
    binmode PIPE;
    print PIPE $pie->gif;
    close PIPE;

SEE ALSO

perl, GD

AUTHOR

Fabien Tassin (fta@oleane.net)

COPYRIGHT

Copyright 1998, 1999, Fabien Tassin. All rights reserved. It may be used and modified freely, but I do request that this copyright notice remain attached to the file. You may modify this module as you wish, but if you redistribute a modified version, please attach a note listing the modifications you have made.