NAME

SWF::Chart - Perl interface to the SWF Chart generation tool

SYNOPSIS

  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;

DESCRIPTION

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:

chart_data (set_titles/add_dataset): 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.
text_properties: 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.
hide_legend: This method employes a hack to hide the legend of a graph since this option does not currently exist in SWF Chart.

MODULE SPECIFIC METHODS

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:

font: 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.
bold: A boolean that determines whether the font is bold or not
size: The font size in points
color: 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.

SWF CHART METHODS

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:

Parameter Methods

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)

Value Methods

These methods take a scalar value. If called more than once, each call overwrites the previous value.

•: $g->chart_type($value)

Repeatable Methods

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:

circle
image
line
rect
text

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)

BUGS

No known bugs

AUTHOR

Garth Webb <garth@sixapart.com>

VERSION

Version 1.3 (11 Jan 2006)

COPYRIGHT AND LICENSE

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 71:: You can't have =items (as at line 187) unless the first thing after the =over is an =item