Graph.pm

NAME

Graph - Create GIF graphs from given data.

SYNOPSIS

use Graph; $img = new Graph; $img->data(123,"value 1"); $img->title("Example Graph"); ... $img->output("filename.gif");

DESCRIPTION

This module lets you create charts from data and output them to a GIF image. It uses GD.pm to do the actual image manipulation. The goal of this module is to let you have as much or as little control over the resulting graph as you want. You can just insert a few data points and get a graph, or control every aspect of the graph layout and contents, depending on your needs. It is intended for other modules with different graph types (pie chart, line graph, etc) to be derived from this class. Send the following messages to your Graph object to control the results:

data ( value , label )
Add a data point to the graph. Value is required, label is optional.

set_color ( name , red , green , blue )
Make a color available in other methods. Give it a name and red, green, and blue values from 0-255, and you can then use the name anywhere a color is required.

get_color ( name )
Return a (red,green,blue) array for the given color name

write_to_file ( filename )
Write all current options to a filename for easy retrieval later

load_from_file ( filename )
Read in all options for a graph from a file saved by write_to_file

output ( filename )
Output the graph gig image. With no arguments, the binary image data is returned. GD.pm does not support this on Win32, so with no arguments the data will be printed by STDOUT. With a filename as an argument, the gif image will be saved to disk.

The following methods return the value of the property if given no .argument, or set it if given an argument. Fonts must be one of gdTinyFont, gdSmallFont, gdMediumBoldFont, or gdLargeFont. Colors must have either been defined or be one of the default colors.

width, height
Force the image to be a certain size. This will change other values that you may set in order to squeeze or expand everything to the right size.

title
Text to center at the top of the image as the title.

title_font
Font to use for title.

title_font_color
Color to use for title.

title_padding
The number of pixels to use as 'padding' around the title.

subtitle
Text to center below the title. Also uses subtitle_font, subtitle_font_color, subtitle_padding.

keys_label
Label to put on the X axis, below the keys. Also uses keys_label_font, keys_label_font_color, keys_label_padding.

values_label
Label to put on the Y acis, next to the values. Also uses values_label_font, values_label_font_color, values_label_padding.

keys_font, keys_font_color, keys_padding
Control the properties of the key labels on the X axis.

values_font, values_font_color, values_padding
Control the properties of value labels on the Y axis.

value_label_font, value_label_font_color, value_label_padding
Currently unused. Will be used to label the value of each separate bar on the graph.

value_format
Controls formatting of value labels on the Y axis. Must be in the format of x.y, where x controls how many digits are before the decimal point, and y controls how many digits appear after the decimal point. If followed by a "k" or "K", all values are divided by 1,000. If followed by an "m" or "M" all values are divided by 1,000,000. Any extra text before or after the x.y is retained. For example, if you are graphing money, you may use a format like "$.2", so a "$" precedes all numbers, and they are cut off at two decimal places. You can also use labels, such as ".3 cm" to label values as centimeters.

value_min, value_max
Set these values to force the scale of the Y axis. Any values lower than value_min will not be graphed, and anything greater than value_max will go off the chart.

value_labels
Label on certain values on the Y axis, rather than values at an even interval. If you don't want any values at all to be labeled, set this to 'none'.

bgcolor
A color to use as the background. Ignored if background image is given.

background_image
The full path to an image to be used as the background. The image will be tiled, and bgcolor will be ignored.

color_list
A comma-separated list of colors to cycle through for the colors of the bars. If given "red,green,blue", for example, the first bar will be red, the second will be green, and the third will be blue. The fourth will then go back to red and start over.

line_width
The width of the axis lines. Currently not used.

line_color
The color of the axis lines.

top_gutter, right_gutter, bottom_gutter, left_gutter
The number of pixels to leave empty on each side of the image.

bar_size
The width in pixels of each bar in the chart. If a width is forced, this will be scaled appropriately.

bar_spacing
The width in pixels between each bar in the chart. If a width is forced, this will be scaled appropriately.

bar_shadow_depth
The number of pixels down and to the right that a shadow will be placed behind each bar. Set to 0 for no shadow.

bar_shadow_color
The color of the shadows for each bar.

tick_number
The number of 'ticks' for values to be placed on the Y axis, between the top and bottom values. Ignored if value_labels is set.

tick_width
How wide each 'tick' is in pixels.

tick_padding
The number of empty pixels to be placed next to each 'tick'.

.

THANKS

This module is made possible by the B<excellent> work done by:

Tom Boutell
Author of the original GD libraries written in C. http://www.boutell.com/

Lincoln Stein
Author of GD.pm, the Perl interface to GD. http://www-genome.wi.mit.edu/~lstein/

Dave Roth
Author of the Win32 port of GD. http://www.roth.net/

.

NOTES

This is my first "real" module with pod and all. Keep that in mind :) Set Graph::debug = 1 for some debugging info.

AUTHOR

Matt Kruse <mkruse@netexpress.net>