.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Excel::Writer::XLSX::Chart 3pm"
.TH Excel::Writer::XLSX::Chart 3pm "2012-04-02" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Chart \- A class for writing Excel Charts.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
To create a simple Excel file with a chart using Excel::Writer::XLSX:
.PP
.Vb 1
\&    #!/usr/bin/perl
\&
\&    use strict;
\&    use warnings;
\&    use Excel::Writer::XLSX;
\&
\&    my $workbook  = Excel::Writer::XLSX\->new( \*(Aqchart.xlsx\*(Aq );
\&    my $worksheet = $workbook\->add_worksheet();
\&
\&    # Add the worksheet data the chart refers to.
\&    my $data = [
\&        [ \*(AqCategory\*(Aq, 2, 3, 4, 5, 6, 7 ],
\&        [ \*(AqValue\*(Aq,    1, 4, 5, 2, 1, 5 ],
\&
\&    ];
\&
\&    $worksheet\->write( \*(AqA1\*(Aq, $data );
\&
\&    # Add a worksheet chart.
\&    my $chart = $workbook\->add_chart( type => \*(Aqcolumn\*(Aq );
\&
\&    # Configure the chart.
\&    $chart\->add_series(
\&        categories => \*(Aq=Sheet1!$A$2:$A$7\*(Aq,
\&        values     => \*(Aq=Sheet1!$B$2:$B$7\*(Aq,
\&    );
\&
\&    _\|_END_\|_
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Chart\*(C'\fR module is an abstract base class for modules that implement charts in Excel::Writer::XLSX. The information below is applicable to all of the available subclasses.
.PP
The \f(CW\*(C`Chart\*(C'\fR module isn't used directly. A chart object is created via the Workbook \f(CW\*(C`add_chart()\*(C'\fR method where the chart type is specified:
.PP
.Vb 1
\&    my $chart = $workbook\->add_chart( type => \*(Aqcolumn\*(Aq );
.Ve
.PP
Currently the supported chart types are:
.IP "\(bu" 4
\&\f(CW\*(C`area\*(C'\fR
.Sp
Creates an Area (filled line) style chart. See Excel::Writer::XLSX::Chart::Area.
.IP "\(bu" 4
\&\f(CW\*(C`bar\*(C'\fR
.Sp
Creates a Bar style (transposed histogram) chart. See Excel::Writer::XLSX::Chart::Bar.
.IP "\(bu" 4
\&\f(CW\*(C`column\*(C'\fR
.Sp
Creates a column style (histogram) chart. See Excel::Writer::XLSX::Chart::Column.
.IP "\(bu" 4
\&\f(CW\*(C`line\*(C'\fR
.Sp
Creates a Line style chart. See Excel::Writer::XLSX::Chart::Line.
.IP "\(bu" 4
\&\f(CW\*(C`pie\*(C'\fR
.Sp
Creates an Pie style chart. See Excel::Writer::XLSX::Chart::Pie.
.IP "\(bu" 4
\&\f(CW\*(C`scatter\*(C'\fR
.Sp
Creates an Scatter style chart. See Excel::Writer::XLSX::Chart::Scatter.
.IP "\(bu" 4
\&\f(CW\*(C`stock\*(C'\fR
.Sp
Creates an Stock style chart. See Excel::Writer::XLSX::Chart::Stock.
.IP "\(bu" 4
\&\f(CW\*(C`...\*(C'\fR
.Sp
More charts and sub-types will be supported in time. See the \*(L"\s-1TODO\s0\*(R" section.
.SH "CHART METHODS"
.IX Header "CHART METHODS"
Methods that are common to all chart types are documented below. See the documentation for each of the above chart modules for chart specific information.
.SS "\fIadd_series()\fP"
.IX Subsection "add_series()"
In an Excel chart a \*(L"series\*(R" is a collection of information such as values, x\-axis labels and the formatting that define which data is plotted.
.PP
With a Excel::Writer::XLSX chart object the \f(CW\*(C`add_series()\*(C'\fR method is used to set the properties for a series:
.PP
.Vb 5
\&    $chart\->add_series(
\&        categories => \*(Aq=Sheet1!$A$2:$A$10\*(Aq, # Optional.
\&        values     => \*(Aq=Sheet1!$B$2:$B$10\*(Aq, # Required.
\&        line       => { color => \*(Aqblue\*(Aq },
\&    );
.Ve
.PP
The properties that can be set are:
.IP "\(bu" 4
\&\f(CW\*(C`values\*(C'\fR
.Sp
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. A formula or array ref can be used for the data range, see below.
.IP "\(bu" 4
\&\f(CW\*(C`categories\*(C'\fR
.Sp
This sets the chart category labels. The category is more or less the same as the X\-axis. In most chart types the \f(CW\*(C`categories\*(C'\fR property is optional and the chart will just assume a sequential series from \f(CW\*(C`1 .. n\*(C'\fR.
.IP "\(bu" 4
\&\f(CW\*(C`name\*(C'\fR
.Sp
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 it will default to \f(CW\*(C`Series 1 .. n\*(C'\fR.
.IP "\(bu" 4
\&\f(CW\*(C`line\*(C'\fR
.Sp
Set the properties of the series line type such as colour and width. See the \*(L"\s-1CHART\s0 \s-1FORMATTING\s0\*(R" section below.
.IP "\(bu" 4
\&\f(CW\*(C`border\*(C'\fR
.Sp
Set the border properties of the series such as colour and style. See the \*(L"\s-1CHART\s0 \s-1FORMATTING\s0\*(R" section below.
.IP "\(bu" 4
\&\f(CW\*(C`fill\*(C'\fR
.Sp
Set the fill properties of the series such as colour. See the \*(L"\s-1CHART\s0 \s-1FORMATTING\s0\*(R" section below.
.IP "\(bu" 4
\&\f(CW\*(C`marker\*(C'\fR
.Sp
Set the properties of the series marker such as style and color. See the \*(L"\s-1CHART\s0 \s-1FORMATTING\s0\*(R" section below.
.IP "\(bu" 4
\&\f(CW\*(C`trendline\*(C'\fR
.Sp
Set the properties of the series trendline such as linear, polynomial and moving average types. See the \*(L"\s-1CHART\s0 \s-1FORMATTING\s0\*(R" section below.
.IP "\(bu" 4
\&\f(CW\*(C`data_labels\*(C'\fR
.Sp
Set data labels for the series. See the \*(L"\s-1CHART\s0 \s-1FORMATTING\s0\*(R" section below.
.IP "\(bu" 4
\&\f(CW\*(C`invert_if_negative\*(C'\fR
.Sp
Invert the fill colour for negative values. Usually only applicable to column and bar charts.
.PP
The \f(CW\*(C`categories\*(C'\fR and \f(CW\*(C`values\*(C'\fR can take either a range formula such as \f(CW\*(C`=Sheet1!$A$2:$A$7\*(C'\fR or, more usefully when generating the range programmatically, an array ref with zero indexed row/column values:
.PP
.Vb 1
\&     [ $sheetname, $row_start, $row_end, $col_start, $col_end ]
.Ve
.PP
The following are equivalent:
.PP
.Vb 2
\&    $chart\->add_series( categories => \*(Aq=Sheet1!$A$2:$A$7\*(Aq      ); # Same as ...
\&    $chart\->add_series( categories => [ \*(AqSheet1\*(Aq, 1, 6, 0, 0 ] ); # Zero\-indexed.
.Ve
.PP
You can add more than one series to a chart. In fact, some chart types such as \f(CW\*(C`stock\*(C'\fR require it. The series numbering and order in the Excel chart will be the same as the order in which that are added in Excel::Writer::XLSX.
.PP
.Vb 6
\&    # Add the first series.
\&    $chart\->add_series(
\&        categories => \*(Aq=Sheet1!$A$2:$A$7\*(Aq,
\&        values     => \*(Aq=Sheet1!$B$2:$B$7\*(Aq,
\&        name       => \*(AqTest data series 1\*(Aq,
\&    );
\&
\&    # Add another series. Same categories. Different range values.
\&    $chart\->add_series(
\&        categories => \*(Aq=Sheet1!$A$2:$A$7\*(Aq,
\&        values     => \*(Aq=Sheet1!$C$2:$C$7\*(Aq,
\&        name       => \*(AqTest data series 2\*(Aq,
\&    );
.Ve
.SS "\fIset_x_axis()\fP"
.IX Subsection "set_x_axis()"
The \f(CW\*(C`set_x_axis()\*(C'\fR method is used to set properties of the X axis.
.PP
.Vb 1
\&    $chart\->set_x_axis( name => \*(AqQuarterly results\*(Aq );
.Ve
.PP
The properties that can be set are:
.PP
.Vb 9
\&    name
\&    min
\&    max
\&    minor_unit
\&    major_unit
\&    crossing
\&    reverse
\&    log_base
\&    label_position
.Ve
.PP
These are explained below. Some properties are only applicable to value or category axes, as indicated. See \*(L"Value and Category Axes\*(R" for an explanation of Excel's distinction between the axis types.
.IP "\(bu" 4
\&\f(CW\*(C`name\*(C'\fR
.Sp
Set the name (title or caption) for the axis. The name is displayed below the X axis. The \f(CW\*(C`name\*(C'\fR property is optional. The default is to have no axis name. (Applicable to category and value axes).
.Sp
.Vb 1
\&    $chart\->set_x_axis( name => \*(AqQuarterly results\*(Aq );
.Ve
.Sp
The name can also be a formula such as \f(CW\*(C`=Sheet1!$A$1\*(C'\fR.
.IP "\(bu" 4
\&\f(CW\*(C`min\*(C'\fR
.Sp
Set the minimum value for the axis range. (Applicable to value axes only).
.Sp
.Vb 1
\&    $chart\->set_x_axis( min => 20 );
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`max\*(C'\fR
.Sp
Set the maximum value for the axis range. (Applicable to value axes only).
.Sp
.Vb 1
\&    $chart\->set_x_axis( max => 80 );
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`minor_unit\*(C'\fR
.Sp
Set the increment of the minor units in the axis range. (Applicable to value axes only).
.Sp
.Vb 1
\&    $chart\->set_x_axis( minor_unit => 0.4 );
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`major_unit\*(C'\fR
.Sp
Set the increment of the major units in the axis range. (Applicable to value axes only).
.Sp
.Vb 1
\&    $chart\->set_x_axis( major_unit => 2 );
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`crossing\*(C'\fR
.Sp
Set the position where the y axis will cross the x axis. (Applicable to category and value axes).
.Sp
The \f(CW\*(C`crossing\*(C'\fR value can either be the string \f(CW\*(Aqmax\*(Aq\fR to set the crossing at the maximum axis value or a numeric value.
.Sp
.Vb 3
\&    $chart\->set_x_axis( crossing => 3 );
\&    # or
\&    $chart\->set_x_axis( crossing => \*(Aqmax\*(Aq );
.Ve
.Sp
\&\fBFor category axes the numeric value must be an integer\fR to represent the category number that the axis crosses at. For value axes it can have any value associated with the axis.
.Sp
If crossing is omitted (the default) the crossing will be set automatically by Excel based on the chart data.
.IP "\(bu" 4
\&\f(CW\*(C`reverse\*(C'\fR
.Sp
Reverse the order of the axis categories or values. (Applicable to category and value axes).
.Sp
.Vb 1
\&    $chart\->set_x_axis( reverse => 1 );
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`log_base\*(C'\fR
.Sp
Set the log base of the axis range. (Applicable to value axes only).
.Sp
.Vb 1
\&    $chart\->set_x_axis( log_base => 10 );
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`label_position\*(C'\fR
.Sp
Set the \*(L"Axis labels\*(R" position for the axis. The following positions are available:
.Sp
.Vb 4
\&    next_to (the default)
\&    high
\&    low
\&    none
.Ve
.PP
More than one property can be set in a call to \f(CW\*(C`set_x_axis\*(C'\fR:
.PP
.Vb 5
\&    $chart\->set_x_axis(
\&        name => \*(AqQuarterly results\*(Aq,
\&        min  => 10,
\&        max  => 80,
\&    );
.Ve
.SS "\fIset_y_axis()\fP"
.IX Subsection "set_y_axis()"
The \f(CW\*(C`set_y_axis()\*(C'\fR method is used to set properties of the Y axis. The properties that can be set are the same as for \f(CW\*(C`set_x_axis\*(C'\fR, see above.
.SS "\fIset_title()\fP"
.IX Subsection "set_title()"
The \f(CW\*(C`set_title()\*(C'\fR method is used to set properties of the chart title.
.PP
.Vb 1
\&    $chart\->set_title( name => \*(AqYear End Results\*(Aq );
.Ve
.PP
The properties that can be set are:
.IP "\(bu" 4
\&\f(CW\*(C`name\*(C'\fR
.Sp
Set the name (title) for the chart. The name is displayed above the chart. The name can also be a formula such as \f(CW\*(C`=Sheet1!$A$1\*(C'\fR. The name property is optional. The default is to have no chart title.
.SS "\fIset_legend()\fP"
.IX Subsection "set_legend()"
The \f(CW\*(C`set_legend()\*(C'\fR method is used to set properties of the chart legend.
.PP
.Vb 1
\&    $chart\->set_legend( position => \*(Aqnone\*(Aq );
.Ve
.PP
The properties that can be set are:
.IP "\(bu" 4
\&\f(CW\*(C`position\*(C'\fR
.Sp
Set the position of the chart legend.
.Sp
.Vb 1
\&    $chart\->set_legend( position => \*(Aqbottom\*(Aq );
.Ve
.Sp
The default legend position is \f(CW\*(C`right\*(C'\fR. The available positions are:
.Sp
.Vb 7
\&    none
\&    top
\&    bottom
\&    left
\&    right
\&    overlay_left
\&    overlay_right
.Ve
.IP "\(bu" 4
delete_series
.Sp
This allows you to remove 1 or more series from the the legend (the series will still display on the chart). This property takes an array ref as an argument and the series are zero indexed:
.Sp
.Vb 2
\&    # Delete/hide series index 0 and 2 from the legend.
\&    $chart\->set_legend( delete_series => [0, 2] );
.Ve
.SS "\fIset_chartarea()\fP"
.IX Subsection "set_chartarea()"
The \f(CW\*(C`set_chartarea()\*(C'\fR method is used to set the properties of the chart area.
.PP
This method isn't implemented yet and is only available in Spreadsheet::WriteExcel. However, it can be simulated using the \f(CW\*(C`set_style()\*(C'\fR method, see below.
.SS "\fIset_plotarea()\fP"
.IX Subsection "set_plotarea()"
The \f(CW\*(C`set_plotarea()\*(C'\fR method is used to set properties of the plot area of a chart.
.PP
This method isn't implemented yet and is only available in Spreadsheet::WriteExcel. However, it can be simulated using the \f(CW\*(C`set_style()\*(C'\fR method, see below.
.SS "\fIset_style()\fP"
.IX Subsection "set_style()"
The \f(CW\*(C`set_style()\*(C'\fR method is used to set the style of the chart to one of the 42 built-in styles available on the 'Design' tab in Excel:
.PP
.Vb 1
\&    $chart\->set_style( 4 );
.Ve
.PP
The default style is 2.
.SH "CHART FORMATTING"
.IX Header "CHART FORMATTING"
The following chart formatting properties can be set for any chart object that they apply to (and that are supported by Excel::Writer::XLSX) such as chart lines, column fill areas, plot area borders, markers and other chart elements documented above.
.PP
.Vb 6
\&    line
\&    border
\&    fill
\&    marker
\&    trendline
\&    data_labels
.Ve
.PP
Chart formatting properties are generally set using hash refs.
.PP
.Vb 4
\&    $chart\->add_series(
\&        values     => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        line       => { color => \*(Aqblue\*(Aq },
\&    );
.Ve
.PP
In some cases the format properties can be nested. For example a \f(CW\*(C`marker\*(C'\fR may contain \f(CW\*(C`border\*(C'\fR and \f(CW\*(C`fill\*(C'\fR sub-properties.
.PP
.Vb 10
\&    $chart\->add_series(
\&        values     => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        line       => { color => \*(Aqblue\*(Aq },
\&        marker     => {
\&            type    => \*(Aqsquare\*(Aq,
\&            size    => 5,
\&            border  => { color => \*(Aqred\*(Aq },
\&            fill    => { color => \*(Aqyellow\*(Aq },
\&        },
\&    );
.Ve
.SS "Line"
.IX Subsection "Line"
The line format is used to specify properties of line objects that appear in a chart such as a plotted line on a chart or a border.
.PP
The following properties can be set for \f(CW\*(C`line\*(C'\fR formats in a chart.
.PP
.Vb 4
\&    none
\&    color
\&    width
\&    dash_type
.Ve
.PP
The \f(CW\*(C`none\*(C'\fR property is uses to turn the \f(CW\*(C`line\*(C'\fR off (it is always on by default except in Scatter charts). This is useful if you wish to plot a series with markers but without a line.
.PP
.Vb 4
\&    $chart\->add_series(
\&        values     => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        line       => { none => 1 },
\&    );
.Ve
.PP
The \f(CW\*(C`color\*(C'\fR property sets the color of the \f(CW\*(C`line\*(C'\fR.
.PP
.Vb 4
\&    $chart\->add_series(
\&        values     => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        line       => { color => \*(Aqred\*(Aq },
\&    );
.Ve
.PP
The available colors are shown in the main Excel::Writer::XLSX documentation. It is also possible to set the color of a line with a \s-1HTML\s0 style \s-1RGB\s0 color:
.PP
.Vb 3
\&    $chart\->add_series(
\&        line       => { color => \*(Aq#FF0000\*(Aq },
\&    );
.Ve
.PP
The \f(CW\*(C`width\*(C'\fR property sets the width of the \f(CW\*(C`line\*(C'\fR. It should be specified in increments of 0.25 of a point as in Excel.
.PP
.Vb 4
\&    $chart\->add_series(
\&        values     => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        line       => { width => 3.25 },
\&    );
.Ve
.PP
The \f(CW\*(C`dash_type\*(C'\fR property sets the dash style of the line.
.PP
.Vb 4
\&    $chart\->add_series(
\&        values     => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        line       => { dash_type => \*(Aqdash_dot\*(Aq },
\&    );
.Ve
.PP
The following \f(CW\*(C`dash_type\*(C'\fR values are available. They are shown in the order that they appear in the Excel dialog.
.PP
.Vb 8
\&    solid
\&    round_dot
\&    square_dot
\&    dash
\&    dash_dot
\&    long_dash
\&    long_dash_dot
\&    long_dash_dot_dot
.Ve
.PP
The default line style is \f(CW\*(C`solid\*(C'\fR.
.PP
More than one \f(CW\*(C`line\*(C'\fR property can be specified at time:
.PP
.Vb 8
\&    $chart\->add_series(
\&        values     => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        line       => {
\&            color     => \*(Aqred\*(Aq,
\&            width     => 1.25,
\&            dash_type => \*(Aqsquare_dot\*(Aq,
\&        },
\&    );
.Ve
.SS "Border"
.IX Subsection "Border"
The \f(CW\*(C`border\*(C'\fR property is a synonym for \f(CW\*(C`line\*(C'\fR.
.PP
It can be used as a descriptive substitute for \f(CW\*(C`line\*(C'\fR in chart types such as Bar and Column that have a border and fill style rather than a line style. In general chart objects with a \f(CW\*(C`border\*(C'\fR property will also have a fill property.
.SS "Fill"
.IX Subsection "Fill"
The fill format is used to specify filled areas of chart objects such as the interior of a column or the background of the chart itself.
.PP
The following properties can be set for \f(CW\*(C`fill\*(C'\fR formats in a chart.
.PP
.Vb 2
\&    none
\&    color
.Ve
.PP
The \f(CW\*(C`none\*(C'\fR property is uses to turn the \f(CW\*(C`fill\*(C'\fR property off (it is generally on by default).
.PP
.Vb 4
\&    $chart\->add_series(
\&        values     => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        fill       => { none => 1 },
\&    );
.Ve
.PP
The \f(CW\*(C`color\*(C'\fR property sets the color of the \f(CW\*(C`fill\*(C'\fR area.
.PP
.Vb 4
\&    $chart\->add_series(
\&        values     => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        fill       => { color => \*(Aqred\*(Aq },
\&    );
.Ve
.PP
The available colors are shown in the main Excel::Writer::XLSX documentation. It is also possible to set the color of a fill with a \s-1HTML\s0 style \s-1RGB\s0 color:
.PP
.Vb 3
\&    $chart\->add_series(
\&        fill       => { color => \*(Aq#FF0000\*(Aq },
\&    );
.Ve
.PP
The \f(CW\*(C`fill\*(C'\fR format is generally used in conjunction with a \f(CW\*(C`border\*(C'\fR format which has the same properties as a \f(CW\*(C`line\*(C'\fR format.
.PP
.Vb 5
\&    $chart\->add_series(
\&        values     => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        border     => { color => \*(Aqred\*(Aq },
\&        fill       => { color => \*(Aqyellow\*(Aq },
\&    );
.Ve
.SS "Marker"
.IX Subsection "Marker"
The marker format specifies the properties of the markers used to distinguish series on a chart. In general only Line and Scatter chart types and trendlines use markers.
.PP
The following properties can be set for \f(CW\*(C`marker\*(C'\fR formats in a chart.
.PP
.Vb 4
\&    type
\&    size
\&    border
\&    fill
.Ve
.PP
The \f(CW\*(C`type\*(C'\fR property sets the type of marker that is used with a series.
.PP
.Vb 4
\&    $chart\->add_series(
\&        values     => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        marker     => { type => \*(Aqdiamond\*(Aq },
\&    );
.Ve
.PP
The following \f(CW\*(C`type\*(C'\fR properties can be set for \f(CW\*(C`marker\*(C'\fR formats in a chart. These are shown in the same order as in the Excel format dialog.
.PP
.Vb 11
\&    automatic
\&    none
\&    square
\&    diamond
\&    triangle
\&    x
\&    star
\&    short_dash
\&    long_dash
\&    circle
\&    plus
.Ve
.PP
The \f(CW\*(C`automatic\*(C'\fR type is a special case which turns on a marker using the default marker style for the particular series number.
.PP
.Vb 4
\&    $chart\->add_series(
\&        values     => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        marker     => { type => \*(Aqautomatic\*(Aq },
\&    );
.Ve
.PP
If \f(CW\*(C`automatic\*(C'\fR is on then other marker properties such as size, border or fill cannot be set.
.PP
The \f(CW\*(C`size\*(C'\fR property sets the size of the marker and is generally used in conjunction with \f(CW\*(C`type\*(C'\fR.
.PP
.Vb 4
\&    $chart\->add_series(
\&        values     => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        marker     => { type => \*(Aqdiamond\*(Aq, size => 7 },
\&    );
.Ve
.PP
Nested \f(CW\*(C`border\*(C'\fR and \f(CW\*(C`fill\*(C'\fR properties can also be set for a marker. These have the same sub-properties as shown above.
.PP
.Vb 9
\&    $chart\->add_series(
\&        values     => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        marker     => {
\&            type    => \*(Aqsquare\*(Aq,
\&            size    => 5,
\&            border  => { color => \*(Aqred\*(Aq },
\&            fill    => { color => \*(Aqyellow\*(Aq },
\&        },
\&    );
.Ve
.SS "Trendline"
.IX Subsection "Trendline"
A trendline can be added to a chart series to indicate trends in the data such as a moving average or a polynomial fit.
.PP
The following properties can be set for \f(CW\*(C`trendline\*(C'\fR formats in a chart.
.PP
.Vb 7
\&    type
\&    order       (for polynomial trends)
\&    period      (for moving average)
\&    forward     (for all except moving average)
\&    backward    (for all except moving average)
\&    name
\&    line
.Ve
.PP
The \f(CW\*(C`type\*(C'\fR property sets the type of trendline in the series.
.PP
.Vb 4
\&    $chart\->add_series(
\&        values     => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        trendline  => { type => \*(Aqlinear\*(Aq },
\&    );
.Ve
.PP
The available \f(CW\*(C`trendline\*(C'\fR types are:
.PP
.Vb 6
\&    exponential
\&    linear
\&    log
\&    moving_average
\&    polynomial
\&    power
.Ve
.PP
A \f(CW\*(C`polynomial\*(C'\fR trendline can also specify the \f(CW\*(C`order\*(C'\fR of the polynomial. The default value is 2.
.PP
.Vb 7
\&    $chart\->add_series(
\&        values    => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        trendline => {
\&            type  => \*(Aqpolynomial\*(Aq,
\&            order => 3,
\&        },
\&    );
.Ve
.PP
A \f(CW\*(C`moving_average\*(C'\fR trendline can also the \f(CW\*(C`period\*(C'\fR of the moving average. The default value is 2.
.PP
.Vb 7
\&    $chart\->add_series(
\&        values     => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        trendline  => {
\&            type   => \*(Aqmoving_average\*(Aq,
\&            period => 3,
\&        },
\&    );
.Ve
.PP
The \f(CW\*(C`forward\*(C'\fR and \f(CW\*(C`backward\*(C'\fR properties set the forecast period of the trendline.
.PP
.Vb 8
\&    $chart\->add_series(
\&        values    => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        trendline => {
\&            type     => \*(Aqlinear\*(Aq,
\&            forward  => 0.5,
\&            backward => 0.5,
\&        },
\&    );
.Ve
.PP
The \f(CW\*(C`name\*(C'\fR property sets an optional name for the trendline that will appear in the chart legend. If it isn't specified the Excel default name will be displayed. This is usually a combination of the trendline type and the series name.
.PP
.Vb 7
\&    $chart\->add_series(
\&        values    => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        trendline => {
\&            type => \*(Aqlinear\*(Aq,
\&            name => \*(AqInterpolated trend\*(Aq,
\&        },
\&    );
.Ve
.PP
Several of these properties can be set in one go:
.PP
.Vb 10
\&    $chart\->add_series(
\&        values     => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        trendline  => {
\&            type     => \*(Aqlinear\*(Aq,
\&            name     => \*(AqMy trend name\*(Aq,
\&            forward  => 0.5,
\&            backward => 0.5,
\&            line     => {
\&                color     => \*(Aqred\*(Aq,
\&                width     => 1,
\&                dash_type => \*(Aqlong_dash\*(Aq,
\&            },
\&        },
\&    );
.Ve
.PP
Trendlines cannot be added to series in a stacked chart or pie chart or (when implemented) to 3\-D, radar, surface, or doughnut charts.
.SS "Data Labels"
.IX Subsection "Data Labels"
Data labels can be added to a chart series to indicate the values of the plotted data points.
.PP
The following properties can be set for \f(CW\*(C`data_labels\*(C'\fR formats in a chart.
.PP
.Vb 6
\&    value
\&    category
\&    series_name
\&    position
\&    leader_lines
\&    percentage
.Ve
.PP
The \f(CW\*(C`value\*(C'\fR property turns on the \fIValue\fR data label for a series.
.PP
.Vb 4
\&    $chart\->add_series(
\&        values      => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        data_labels => { value => 1 },
\&    );
.Ve
.PP
The \f(CW\*(C`category\*(C'\fR property turns on the \fICategory Name\fR data label for a series.
.PP
.Vb 4
\&    $chart\->add_series(
\&        values      => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        data_labels => { category => 1 },
\&    );
.Ve
.PP
The \f(CW\*(C`series_name\*(C'\fR property turns on the \fISeries Name\fR data label for a series.
.PP
.Vb 4
\&    $chart\->add_series(
\&        values      => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        data_labels => { series_name => 1 },
\&    );
.Ve
.PP
The \f(CW\*(C`position\*(C'\fR property is used to position the data label for a series.
.PP
.Vb 4
\&    $chart\->add_series(
\&        values      => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        data_labels => { value => 1, position => \*(Aqcenter\*(Aq },
\&    );
.Ve
.PP
Valid positions are:
.PP
.Vb 10
\&    center
\&    right
\&    left
\&    top
\&    bottom
\&    above           # Same as top
\&    below           # Same as bottom
\&    inside_end      # Pie chart mainly.
\&    outside_end     # Pie chart mainly.
\&    best_fit        # Pie chart mainly.
.Ve
.PP
The \f(CW\*(C`percentage\*(C'\fR property is used to turn on the \fIPercentage\fR for the data label for a series. It is mainly used for pie charts.
.PP
.Vb 4
\&    $chart\->add_series(
\&        values      => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        data_labels => { percentage => 1 },
\&    );
.Ve
.PP
The \f(CW\*(C`leader_lines\*(C'\fR property is used to turn on  \fILeader Lines\fR for the data label for a series. It is mainly used for pie charts.
.PP
.Vb 4
\&    $chart\->add_series(
\&        values      => \*(Aq=Sheet1!$B$1:$B$5\*(Aq,
\&        data_labels => { value => 1, leader_lines => 1 },
\&    );
.Ve
.SS "Other formatting options"
.IX Subsection "Other formatting options"
Other formatting options will be added in time. If there is a feature that you would like to see included drop me a line.
.SH "WORKSHEET METHODS"
.IX Header "WORKSHEET METHODS"
In Excel a chartsheet (i.e, a chart that isn't embedded) shares properties with data worksheets such as tab selection, headers, footers, margins and print properties.
.PP
In Excel::Writer::XLSX you can set chartsheet properties using the same methods that are used for Worksheet objects.
.PP
The following Worksheet methods are also available through a non-embedded Chart object:
.PP
.Vb 8
\&    get_name()
\&    activate()
\&    select()
\&    hide()
\&    set_first_sheet()
\&    protect()
\&    set_zoom()
\&    set_tab_color()
\&
\&    set_landscape()
\&    set_portrait()
\&    set_paper()
\&    set_margins()
\&    set_header()
\&    set_footer()
.Ve
.PP
See Excel::Writer::XLSX for a detailed explanation of these methods.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
Here is a complete example that demonstrates some of the available features when creating a chart.
.PP
.Vb 1
\&    #!/usr/bin/perl
\&
\&    use strict;
\&    use warnings;
\&    use Excel::Writer::XLSX;
\&
\&    my $workbook  = Excel::Writer::XLSX\->new( \*(Aqchart.xlsx\*(Aq );
\&    my $worksheet = $workbook\->add_worksheet();
\&    my $bold      = $workbook\->add_format( bold => 1 );
\&
\&    # Add the worksheet data that the charts will refer to.
\&    my $headings = [ \*(AqNumber\*(Aq, \*(AqBatch 1\*(Aq, \*(AqBatch 2\*(Aq ];
\&    my $data = [
\&        [ 2,  3,  4,  5,  6,  7 ],
\&        [ 10, 40, 50, 20, 10, 50 ],
\&        [ 30, 60, 70, 50, 40, 30 ],
\&
\&    ];
\&
\&    $worksheet\->write( \*(AqA1\*(Aq, $headings, $bold );
\&    $worksheet\->write( \*(AqA2\*(Aq, $data );
\&
\&    # Create a new chart object. In this case an embedded chart.
\&    my $chart = $workbook\->add_chart( type => \*(Aqcolumn\*(Aq, embedded => 1 );
\&
\&    # Configure the first series.
\&    $chart\->add_series(
\&        name       => \*(Aq=Sheet1!$B$1\*(Aq,
\&        categories => \*(Aq=Sheet1!$A$2:$A$7\*(Aq,
\&        values     => \*(Aq=Sheet1!$B$2:$B$7\*(Aq,
\&    );
\&
\&    # Configure second series. Note alternative use of array ref to define
\&    # ranges: [ $sheetname, $row_start, $row_end, $col_start, $col_end ].
\&    $chart\->add_series(
\&        name       => \*(Aq=Sheet1!$C$1\*(Aq,
\&        categories => [ \*(AqSheet1\*(Aq, 1, 6, 0, 0 ],
\&        values     => [ \*(AqSheet1\*(Aq, 1, 6, 2, 2 ],
\&    );
\&
\&    # Add a chart title and some axis labels.
\&    $chart\->set_title ( name => \*(AqResults of sample analysis\*(Aq );
\&    $chart\->set_x_axis( name => \*(AqTest number\*(Aq );
\&    $chart\->set_y_axis( name => \*(AqSample length (mm)\*(Aq );
\&
\&    # Set an Excel chart style. Blue colors with white outline and shadow.
\&    $chart\->set_style( 11 );
\&
\&    # Insert the chart into the worksheet (with an offset).
\&    $worksheet\->insert_chart( \*(AqD2\*(Aq, $chart, 25, 10 );
\&
\&    _\|_END_\|_
.Ve
.SH "Value and Category Axes"
.IX Header "Value and Category Axes"
Excel differentiates between a chart axis that is used for series \fBcategories\fR and an axis that is used for series \fBvalues\fR.
.PP
In the example above the x\-axis is the category axis and each of the values is evenly spaced. The y\-axis (in this case) is the value axis and points are displayed according to their value.
.PP
Since Excel treats the axes differently it also handles their formatting differently and exposed different properties for each.
.PP
As such some of \f(CW\*(C`Excel::Writer::XLSX\*(C'\fR axis properties can be set for a value axis, some can be set for a category axis and some properties can be set for both.
.PP
For example the \f(CW\*(C`min\*(C'\fR and \f(CW\*(C`max\*(C'\fR properties can only be set for value axes and \f(CW\*(C`reverse\*(C'\fR can be set for both. The type of axis that a property applies to is shown in the \f(CW\*(C`set_x_axis()\*(C'\fR section of the documentation above.
.PP
Some charts such as \f(CW\*(C`Scatter\*(C'\fR and \f(CW\*(C`Stock\*(C'\fR have two value axes.
.SH "TODO"
.IX Header "TODO"
The chart feature in Excel::Writer::XLSX is under active development. More chart types and features will be added in time.
.PP
Features that are on the \s-1TODO\s0 list and will be added are:
.IP "\(bu" 4
Add more chart sub-types.
.IP "\(bu" 4
Additional formatting options. For now try the \f(CW\*(C`set_style()\*(C'\fR method.
.IP "\(bu" 4
More axis controls and gridlines.
.IP "\(bu" 4
3D charts.
.IP "\(bu" 4
Additional chart types such as Bubble and Radar.
.PP
If you are interested in sponsoring a feature to have it implemented or expedited let me know.
.SH "AUTHOR"
.IX Header "AUTHOR"
John McNamara jmcnamara@cpan.org
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright MM-MMXII, John McNamara.
.PP
All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.