SWF::Chart - Perl interface to the SWF Chart generation tool
use SWF::Chart; my $g = SWF::Chart->new; $g->set_titles(qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec)); # Add a single data set $g->add_dataset(1, 3, 5, 7, 2, 4, 6); # Add multiple datasets $g->add_dataset([qw(1 3 5 7 11 13 17 23 29 31 37 41)], [qw(1 1 2 3 5 8 13 21 34 55 89 144)]); # Add multiple datasets with labels $g->add_dataset('Label 1' => \@set1, 'Label 2' => \@set2); $g->text_properties(bold => 0, size => 10, color => '333333'); $g->chart_rect(positive_color => '555555', positive_alpha => 100); $g->series_color('DEADBE'); print $g->xml;
This module is the Perl interface to the SWF Charts flash graphing tool. It constructs the XML file this flash movie requires via an OO interface. Each configurable option that is listed on the SWF Charts reference page has a companion method in this module. See:
http://www.maani.us/charts/index.php?menu=Reference
When using this module, please be sure to use the latest version of the XML/SWF Charts flash movie. Earlier versions of that flash movie supported a different XML structure for which this module is not backward compatible.
Note that there are a few extra helper functions that this module provides:
The 'chart_data' option has been split into two different methods, 'set_titles' and 'add_dataset'. The original 'chart_data' option held all of this information, but from an interface standpoint, it makes more sense to separate these.
This method sets the 'font', 'bold', 'size' and 'color' properties of all options that effect text ('axis_category', 'axis_value', 'chart_value', 'legend_label' and 'draw_text'). See "text_properties" for more information.
This method employes a hack to hide the legend of a graph since this option does not currently exist in SWF Chart.
The following methods do not have a direct analog to any SWF Chart option.
$g = SWF::Chart->new
Creates a new SWF Chart object. Does not take any parameters.
$g->set_titles
Sets the titles for each column of data. There should be as many titles as data points you pass to 'add_dataset'. If this method is called multiple times, only the last set of titles given will be used.
$g->add_dataset(@row);
$g->add_dataset(\@row1, \@row2, \@row3)
$g->add_dataset('Region A' => \@row1, 'Region B' => \@row2)
Adds rows of data to be charted. Accepts a list of values for a single row, a list of array references for multiple rows or a hash where the key is the row label and the value is an array reference of values for that row. If this method is called more than once, each row is added after the existing rows rather than replacing them.
$g->chart_value_text(@row);
$g->chart_value_text(\@row1, \@row2, \@row3)
Adds alternate text for the values displayed. Accepts a list of values for a single row or a list of array references for multiple rows. If this method is called more than once, each row's alternate text is added after the existing rows rather than replacing them.
$g->hide_legend
This method is a hack to allow easy hiding of the legend. It achives this by setting the legend y-coordinate to -9999, placing it (hopefully) far off canvas. If at some point a native 'hide_legend' is implimented, that will be used instead.
$g->text_properties(%param)
This method sets text properties for all options that affect text. This makes it easy to sets the font for all text in a graph to be 'Arial', or all to a particular point size. The keys to %param are the properties that can be changed:
The font face to use for all text. Arial is the default font and is the only one embedded in the flash movie. If any other font is set here it must be installed on the clients machine or SWF Chart will default to the closest font.
A boolean that determines whether the font is bold or not
The font size in points
The hex color for text
This method acts as a convience method to set all text properties at once. This means that if you call this after setting font properties for a specific option, those values will be overwritten. If you would prefer this to operate as a way to set defaults, then call this method first and then set the additional font prorperites.
The following methods have a direct relationship to the options SWF Charts accepts. Please refer to the SWF Chart reference page for details on these options. These methods are split into three categories:
These methods take a hash of parameters that map to the parameters given on the SWF Chart reference page. If called more than once, each call overwrites the previous parameter values. If a particular parameter is not given, then the previous value for that parameter is retained. Example:
$g->chart_border(color => '00FF00', top_thickness => 0, bottom_thickness => 0);
The 'chart_border' option now has a border color of '00FF00' and zero top and bottom thickness. After this call:
$g->chart_border(top_thickness => 5, bottom_thickness => 5);
The top and bottom thickness will become 5, but the color will remain '00FF00'.
$g->axis_category(%param)
$g->axis_ticks(%param)
$g->axis_value(%param)
$g->chart_border(%param)
$g->chart_data(%param)
$g->chart_grid_h(%param)
$g->chart_grid_v(%param)
$g->chart_pref(%param)
$g->chart_rect(%param)
$g->chart_value(%param)
$g->chart_value_text(%param)
$g->legend_bg(%param)
$g->legend_label(%param)
$g->legend_rect(%param)
$g->link(%param)
$g->link_data(%param)
$g->live_update(%param)
$g->series_gap(%param)
$g->series_switch(%param)
These methods take a scalar value. If called more than once, each call overwrites the previous value.
$g->chart_type($value)
These methods can be called more than once. Each time they are called they add additional data rather than replace existing data. Currently there is no way to change the parameters given on previous calls.
$g->draw($thing1 => $param, $thing2 => $param, ...)
Draw one or more primitives to the chart. Options for $thing are:
Valid options for the $param hash are the parameters given for the elements of the same name within the 'draw' command http://www.maani.us/xml_charts/index.php?menu=Reference&submenu=draw
The only difference is when drawing 'text' you must pass the value for the text via a 'value' key to the $param hash. Example:
$g->draw(text => {bold => 1, x => 20, y => 20, value => 'The quick brown fox', }, line => { ... }, ... )
$g->draw_circle(%param)
Same as $g->draw(circle => \%param)
$g->draw_image(%param)
Same as $g->draw(image => \%param)
$g->draw_line(%param)
Same as $g->draw(line => \%param)
$g->draw_rect(%param)
Same as $g->draw(rect => \%param)
$g->draw_text($text, %param)
Same as $g->draw(text => \%param)
$g->series_color($value)
$g->series_explode($value)
No known bugs
Garth Webb <garth@sixapart.com>
Version 1.3 (11 Jan 2006)
perl, http://www.maani.us/charts/index.php
Copyright 2005, Six Apart, Ltd.
1 POD Error
The following errors were encountered while parsing the POD:
You can't have =items (as at line 187) unless the first thing after the =over is an =item
To install SWF::Chart, copy and paste the appropriate command in to your terminal.
cpanm
cpanm SWF::Chart
CPAN shell
perl -MCPAN -e shell install SWF::Chart
For more information on module installation, please visit the detailed CPAN module installation guide.