NAME

Chart - A writer class for Excel Charts.

SYNOPSIS

To create a simple Excel file with a chart using Spreadsheet::WriteExcel:

    #!/usr/bin/perl -w

    use strict;
    use Spreadsheet::WriteExcel;

    my $workbook  = Spreadsheet::WriteExcel->new( 'chart.xls' );
    my $worksheet = $workbook->add_worksheet();

    my $chart     = $workbook->add_chart( name => 'Chart1', type => 'column' );

    # Configure the chart.
    $chart->add_series(
        categories => '=Sheet1!$A$2:$A$7',
        values     => '=Sheet1!$B$2:$B$7',
    );

    # Add the data to the worksheet the chart refers to.
    my $data = [
        [ 'Category', 2, 3, 4, 5, 6, 7 ],
        [ 'Value',    1, 4, 5, 2, 1, 5 ],
    ];

    $worksheet->write( 'A1', $data );

    __END__

DESCRIPTION

The Chart module is an abstract base class for modules that implement charts in Spreadsheet::WriteExcel. The information below is applicable to all of the available subclasses.

The Chart module isn't used directly, a chart object is created via the Workbook add_chart() method where the chart type is specified:

    my $chart = $workbook->add_chart( name => 'Chart1', type => 'column' );

Currently the supported chart types are:

column: Creates a column style (histogram) chart. See Spreadsheet::WriteExcel::Chart::Column.
bar: Creates a Bar style (transposed histogram) chart. See Spreadsheet::WriteExcel::Chart::Bar.
line: Creates a Line style chart. See Spreadsheet::WriteExcel::Chart::Line.
area: Creates an Area (filled line) style chart. See Spreadsheet::WriteExcel::Chart::Area.

More chart types will be supported in time. See the "TODO" section.

Methods that are common to all chart types are documented below.

CHART METHODS

add_series()

In an Excel chart a "series" is a collection of information such as values, x-axis labels and the name that define which data is plotted. These settings are displayed when you select the Chart -> Source Data... menu option.

With a Spreadsheet::WriteExcel chart object the add_series() method is used to set the properties for a series:

    $chart->add_series(
        categories    => '=Sheet1!$A$2:$A$10',
        values        => '=Sheet1!$B$2:$B$10',
        name          => 'Series name',
        name_formula  => '=Sheet1!$B$1',
    );

The properties that can be set are:

    values        (required)
    categories    (optional for most chart types)
    name          (optional)
    name_formula  (optional)

values

This is the most important property of a series and must be set for every chart object. It links the chart with the worksheet data that it displays.
```
    $chart->add_series( values => '=Sheet1!$B$2:$B$10' );
```
Note the format that should be used for the formula. It is the same as is used in Excel. You must also add the worksheet that you are referring to before you link to it, via the workbook add_worksheet() method.
categories

This sets the chart category labels. The category is more or less the same as the X-axis. In most chart types the categories property is optional and the chart will just assume a sequential series from 1 .. n.
```
    $chart->add_series(
        categories    => '=Sheet1!$A$2:$A$10',
        values        => '=Sheet1!$B$2:$B$10',
    );
```
name

Set the name for the series. The name is displayed in the chart legend and in the formula bar. The name property is optional and if it isn't supplied will default to Series 1 .. n.
```
    $chart->add_series(
        ...
        name          => 'Series name',
    );
```

name_formula

Optional, can be used to link the name to a worksheet cell. See "Chart names and links".

    $chart->add_series(
        ...
        name          => 'Series name',
        name_formula  => '=Sheet1!$B$1',
    );

You can add more than one series to a chart. The series numbering and order in the final chart is the same as the order in which that are added.

    # Add the first series.
    $chart->add_series(
        categories => '=Sheet1!$A$2:$A$7',
        values     => '=Sheet1!$B$2:$B$7',
        name       => 'Test data series 1',
    );

    # Add another series. Catogory is the same but values are different.
    $chart->add_series(
        categories => '=Sheet1!$A$2:$A$7',
        values     => '=Sheet1!$C$2:$C$7',
        name       => 'Test data series 2',
    );

set_x_axis()

The set_x_axis() method is used to set properties of the X axis.

    $chart->set_x_axis( name => 'Sample length (m)' );

The properties that can be set are:

    name          (optional)
    name_formula  (optional)

name

Set the name (title or caption) for the axis. The name is displayed below the X axis. This property is optional. The default is to have no axis name.
```
    $chart->set_x_axis( name => 'Sample length (m)' );
```

name_formula

Optional, can be used to link the name to a worksheet cell. See "Chart names and links".

    $chart->set_x_axis(
        name          => 'Sample length (m)',
        name_formula  => '=Sheet1!$A$1',
    );

Additional axis properties such as range, divisions and ticks will be made available in later releases. See the "TODO" section.

set_y_axis()

The set_y_axis() method is used to set properties of the Y axis.

    $chart->set_y_axis( name => 'Sample weight (kg)' );

The properties that can be set are:

    name          (optional)
    name_formula  (optional)

name

Set the name (title or caption) for the axis. The name is displayed to the left of the Y axis. This property is optional. The default is to have no axis name.
```
    $chart->set_y_axis( name => 'Sample weight (kg)' );
```

name_formula

Optional, can be used to link the name to a worksheet cell. See "Chart names and links".

    $chart->set_y_axis(
        name          => 'Sample weight (kg)',
        name_formula  => '=Sheet1!$B$1',
    );

Additional axis properties such as range, divisions and ticks will be made available in later releases. See the "TODO" section.

set_title()

The set_title() method is used to set properties of the chart title.

    $chart->set_title( name => 'Year End Results' );

The properties that can be set are:

    name          (optional)
    name_formula  (optional)

name

Set the name (title) for the chart. The name is displayed above the chart. This property is optional. The default is to have no chart title.
```
    $chart->set_title( name => 'Year End Results' );
```

name_formula

Optional, can be used to link the name to a worksheet cell. See "Chart names and links".

    $chart->set_title(
        name          => 'Year End Results',
        name_formula  => '=Sheet1!$C$1',
    );

Chart names and links

The add_series()), set_x_axis(), set_y_axis() and set_title() methods all support a name property. In general these names can be either a static string or a link to a worksheet cell. If you choose to use the name_formula property to specify a link then you should also the name 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.

Chart names and Unicode

The add_series()), set_x_axis(), set_y_axis() and set_title() methods all support a name 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 name_encoding 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 Spreadsheet::WriteExcel but is semi-deprecated. If you are using Unicode the easiest option is to just use UTF8 in perl 5.8+.

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:

Embedded charts in worksheets. This has the highest priority and will be added first.
Additional chart types. Stock, Pie and Scatter charts are next in line. Send an email if you are interested in other types and they will be added to the queue.
Colours and formatting options. For now you will have to make do with the default Excel colours and formats.
Axis controls, gridlines.
Embedded data in charts for third party application support.

If you are interested in sponsoring a feature let me know.

KNOWN ISSUES

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.

AUTHOR

John McNamara jmcnamara@cpan.org

COPYRIGHT

To install Spreadsheet::WriteExcel, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Spreadsheet::WriteExcel

CPAN shell

perl -MCPAN -e shell
install Spreadsheet::WriteExcel

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

CHART METHODS

add_series()

set_x_axis()

set_y_axis()

set_title()

Chart names and links

Chart names and Unicode

TODO

KNOWN ISSUES

AUTHOR

COPYRIGHT

Module Install Instructions