for a detailed explanation of these methods.
=head1 EXAMPLE
Here is a complete example that demonstrates some of the available features when creating a chart.
#!/usr/bin/perl -w
use strict;
use Spreadsheet::WriteExcel;
my $workbook = Spreadsheet::WriteExcel->new( 'chart_area.xls' );
my $worksheet = $workbook->add_worksheet();
my $bold = $workbook->add_format( bold => 1 );
# Add the worksheet data that the charts will refer to.
my $headings = [ 'Number', 'Sample 1', 'Sample 2' ];
my $data = [
[ 2, 3, 4, 5, 6, 7 ],
[ 1, 4, 5, 2, 1, 5 ],
[ 3, 6, 7, 5, 4, 3 ],
];
$worksheet->write( 'A1', $headings, $bold );
$worksheet->write( 'A2', $data );
# Create a new chart object. In this case an embedded chart.
my $chart = $workbook->add_chart( type => 'area', embedded => 1 );
# Configure the first series. (Sample 1)
$chart->add_series(
name => 'Sample 1',
categories => '=Sheet1!$A$2:$A$7',
values => '=Sheet1!$B$2:$B$7',
);
# Configure the second series. (Sample 2)
$chart->add_series(
name => 'Sample 2',
categories => '=Sheet1!$A$2:$A$7',
values => '=Sheet1!$C$2:$C$7',
);
# Add a chart title and some axis labels.
$chart->set_title ( name => 'Results of sample analysis' );
$chart->set_x_axis( name => 'Test number' );
$chart->set_y_axis( name => 'Sample length (cm)' );
# Insert the chart into the worksheet (with an offset).
$worksheet->insert_chart( 'D2', $chart, 25, 10 );
__END__
=begin html
This will produce a chart that looks like this:
=end html
=head1 Chart object colours
Many of the chart objects supported by Spreadsheet::WriteExcl allow the default colours to be changed. Excel provides a palette of 56 colours and in Spreadsheet::WriteExcel these colours are accessed via their palette index in the range 8..63.
The most commonly used colours can be accessed by name or index.
black => 8, green => 17, navy => 18,
white => 9, orange => 53, pink => 33,
red => 10, gray => 23, purple => 20,
blue => 12, lime => 11, silver => 22,
yellow => 13, cyan => 15,
brown => 16, magenta => 14,
For example the following are equivalent.
$chart->set_plotarea( color => 10 );
$chart->set_plotarea( color => 'red' );
The colour palette is shown in C in the C directory of the distro. An Excel version of the palette can be generated using C in the C directory.
User defined colours can be set using the C workbook method. This and other aspects of using colours are discussed in the "Colours in Excel" section of the main Spreadsheet::WriteExcel documentation: L.
=head1 Chart line patterns
Chart lines patterns can be set using either an index or a name:
$chart->set_plotarea( weight => 2 );
$chart->set_plotarea( weight => 'dash' );
Chart lines have 9 possible patterns are follows:
'none' => 0,
'solid' => 1,
'dash' => 2,
'dot' => 3,
'dash-dot' => 4,
'dash-dot-dot' => 5,
'medium-gray' => 6,
'dark-gray' => 7,
'light-gray' => 8,
The patterns 1-8 are shown in order in the drop down dialog boxes in Excel. The default pattern is 'solid', index 1.
=head1 Chart line weights
Chart lines weights can be set using either an index or a name:
$chart->set_plotarea( weight => 1 );
$chart->set_plotarea( weight => 'hairline' );
Chart lines have 4 possible weights are follows:
'hairline' => 1,
'narrow' => 2,
'medium' => 3,
'wide' => 4,
The weights 1-4 are shown in order in the drop down dialog boxes in Excel. The default weight is 'narrow', index 2.
=head1 Chart names and links
The C, C, C and C methods all support a C property. In general these names can be either a static string or a link to a worksheet cell. If you choose to use the C property to specify a link then you should also the C property. This isn't strictly required by Excel but some third party applications expect it to be present.
$chart->set_title(
name => 'Year End Results',
name_formula => '=Sheet1!$C$1',
);
These links should be used sparingly since they aren't commonly used in Excel charts.
=head1 Chart names and Unicode
The C, C, C and C methods all support a C property. These names can be UTF8 strings if you are using perl 5.8+.
# perl 5.8+ example:
my $smiley = "\x{263A}";
$chart->set_title( name => "Best. Results. Ever! $smiley" );
For older perls you write Unicode strings as UTF-16BE by adding a C property:
# perl 5.005 example:
my $utf16be_name = pack 'n', 0x263A;
$chart->set_title(
name => $utf16be_name,
name_encoding => 1,
);
This methodology is explained in the "UNICODE IN EXCEL" section of L but is semi-deprecated. If you are using Unicode the easiest option is to just use UTF8 in perl 5.8+.
=head1 Working with Cell Ranges
In the section on C it was noted that the series must be defined using a range formula:
$chart->add_series( values => '=Sheet1!$B$2:$B$10' );
The worksheet name must be specified (even for embedded charts) and the cell references must be "absolute" references, i.e., they must contain C<$> signs. This is the format that is required by Excel for chart references.
Since it isn't very convenient to work with this type of string programmatically the L module, which is included with Spreadsheet::WriteExcel, provides a function called C to convert from zero based row and column cell references to an A1 style formula string.
The syntax is:
xl_range_formula($sheetname, $row_1, $row_2, $col_1, $col_2)
If you include it in your program, using the standard import syntax, you can use the function as follows:
# Include the Utility module or just the function you need.
use Spreadsheet::WriteExcel::Utility qw( xl_range_formula );
...
# Then use it as required.
$chart->add_series(
categories => xl_range_formula( 'Sheet1', 1, 9, 0, 0 ),
values => xl_range_formula( 'Sheet1', 1, 9, 1, 1 ),
);
# Which is the same as:
$chart->add_series(
categories => '=Sheet1!$A$2:$A$10',
values => '=Sheet1!$B$2:$B$10',
);
See L for more details.
=head1 TODO
Charts in Spreadsheet::WriteExcel are a work in progress. More chart types and features will be added in time. Please be patient. Even a small feature can take a week or more to implement, test and document.
Features that are on the TODO list and will be added are:
=over
=item * Chart sub-types.
=item * Colours and formatting options. For now you will have to make do with the default Excel colours and formats.
=item * Axis controls, gridlines.
=item * 3D charts.
=item * Embedded data in charts for third party application support. See Known Issues.
=item * Additional chart types such as Bubble and Radar. Send an email if you are interested in other types and they will be added to the queue.
=back
If you are interested in sponsoring a feature let me know.
=head1 KNOWN ISSUES
=over
=item * Currently charts don't contain embedded data from which the charts can be rendered. Excel and most other third party applications ignore this and read the data via the links that have been specified. However, some applications may complain or not render charts correctly. The preview option in Mac OS X is an known example. This will be fixed in a later release.
=item * When there are several charts with titles set in a workbook some of the titles may display at a font size of 10 instead of the default 12 until another chart with the title set is viewed.
=item * Stock (and other) charts should have the X-axis dates aligned at an angle for clarity. This will be fixed at a later stage.
=back
=head1 AUTHOR
John McNamara jmcnamara@cpan.org
=head1 COPYRIGHT
Copyright MM-MMX, John McNamara.
All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.