{
    "mode": "perldoc",
    "parameter": "Spreadsheet::WriteExcel::Chart",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Spreadsheet%3A%3AWriteExcel%3A%3AChart/json",
    "generated": "2026-06-13T04:37:33Z",
    "synopsis": "To create a simple Excel file with a chart using Spreadsheet::WriteExcel:\n#!/usr/bin/perl -w\nuse strict;\nuse Spreadsheet::WriteExcel;\nmy $workbook  = Spreadsheet::WriteExcel->new( 'chart.xls' );\nmy $worksheet = $workbook->addworksheet();\nmy $chart     = $workbook->addchart( type => 'column' );\n# Configure the chart.\n$chart->addseries(\ncategories => '=Sheet1!$A$2:$A$7',\nvalues     => '=Sheet1!$B$2:$B$7',\n);\n# Add the worksheet data the chart refers to.\nmy $data = [\n[ 'Category', 2, 3, 4, 5, 6, 7 ],\n[ 'Value',    1, 4, 5, 2, 1, 5 ],\n];\n$worksheet->write( 'A1', $data );\nEND",
    "sections": {
        "NAME": {
            "content": "Chart - A writer class for Excel Charts.\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "To create a simple Excel file with a chart using Spreadsheet::WriteExcel:\n\n#!/usr/bin/perl -w\n\nuse strict;\nuse Spreadsheet::WriteExcel;\n\nmy $workbook  = Spreadsheet::WriteExcel->new( 'chart.xls' );\nmy $worksheet = $workbook->addworksheet();\n\nmy $chart     = $workbook->addchart( type => 'column' );\n\n# Configure the chart.\n$chart->addseries(\ncategories => '=Sheet1!$A$2:$A$7',\nvalues     => '=Sheet1!$B$2:$B$7',\n);\n\n# Add the worksheet data the chart refers to.\nmy $data = [\n[ 'Category', 2, 3, 4, 5, 6, 7 ],\n[ 'Value',    1, 4, 5, 2, 1, 5 ],\n];\n\n$worksheet->write( 'A1', $data );\n\nEND\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The \"Chart\" module is an abstract base class for modules that implement charts in\nSpreadsheet::WriteExcel. The information below is applicable to all of the available subclasses.\n\nThe \"Chart\" module isn't used directly, a chart object is created via the Workbook \"addchart()\"\nmethod where the chart type is specified:\n\nmy $chart = $workbook->addchart( type => 'column' );\n\nCurrently the supported chart types are:\n\n*   \"area\": Creates an Area (filled line) style chart. See Spreadsheet::WriteExcel::Chart::Area.\n\n*   \"bar\": Creates a Bar style (transposed histogram) chart. See\nSpreadsheet::WriteExcel::Chart::Bar.\n\n*   \"column\": Creates a column style (histogram) chart. See\nSpreadsheet::WriteExcel::Chart::Column.\n\n*   \"line\": Creates a Line style chart. See Spreadsheet::WriteExcel::Chart::Line.\n\n*   \"pie\": Creates an Pie style chart. See Spreadsheet::WriteExcel::Chart::Pie.\n\n*   \"scatter\": Creates an Scatter style chart. See Spreadsheet::WriteExcel::Chart::Scatter.\n\n*   \"stock\": Creates an Stock style chart. See Spreadsheet::WriteExcel::Chart::Stock.\n\nMore charts and sub-types will be supported in time. See the \"TODO\" section.\n\nMethods that are common to all chart types are documented below.\n",
            "subsections": []
        },
        "CHART METHODS": {
            "content": "addseries()\nIn an Excel chart a \"series\" is a collection of information such as values, x-axis labels and\nthe name that define which data is plotted. These settings are displayed when you select the\n\"Chart -> Source Data...\" menu option.\n\nWith a Spreadsheet::WriteExcel chart object the \"addseries()\" method is used to set the\nproperties for a series:\n\n$chart->addseries(\ncategories    => '=Sheet1!$A$2:$A$10',\nvalues        => '=Sheet1!$B$2:$B$10',\nname          => 'Series name',\nnameformula  => '=Sheet1!$B$1',\n);\n\nThe properties that can be set are:\n\n*   \"values\"\n\nThis is the most important property of a series and must be set for every chart object. It\nlinks the chart with the worksheet data that it displays. Note the format that should be\nused for the formula. See \"Working with Cell Ranges\".\n\n*   \"categories\"\n\nThis sets the chart category labels. The category is more or less the same as the X-axis. In\nmost chart types the \"categories\" property is optional and the chart will just assume a\nsequential series from \"1 .. n\".\n\n*   \"name\"\n\nSet the name for the series. The name is displayed in the chart legend and in the formula\nbar. The name property is optional and if it isn't supplied will default to \"Series 1 .. n\".\n\n*   \"nameformula\"\n\nOptional, can be used to link the name to a worksheet cell. See \"Chart names and links\".\n\nYou can add more than one series to a chart, in fact some chart types such as \"stock\" require\nit. The series numbering and order in the final chart is the same as the order in which that are\nadded.\n\n# Add the first series.\n$chart->addseries(\ncategories => '=Sheet1!$A$2:$A$7',\nvalues     => '=Sheet1!$B$2:$B$7',\nname       => 'Test data series 1',\n);\n\n# Add another series. Category is the same but values are different.\n$chart->addseries(\ncategories => '=Sheet1!$A$2:$A$7',\nvalues     => '=Sheet1!$C$2:$C$7',\nname       => 'Test data series 2',\n);\n\nsetxaxis()\nThe \"setxaxis()\" method is used to set properties of the X axis.\n\n$chart->setxaxis( name => 'Sample length (m)' );\n\nThe properties that can be set are:\n\n*   \"name\"\n\nSet the name (title or caption) for the axis. The name is displayed below the X axis. This\nproperty is optional. The default is to have no axis name.\n\n*   \"nameformula\"\n\nOptional, can be used to link the name to a worksheet cell. See \"Chart names and links\".\n\nAdditional axis properties such as range, divisions and ticks will be made available in later\nreleases. See the \"TODO\" section.\n\nsetyaxis()\nThe \"setyaxis()\" method is used to set properties of the Y axis.\n\n$chart->setyaxis( name => 'Sample weight (kg)' );\n\nThe properties that can be set are:\n\n*   \"name\"\n\nSet the name (title or caption) for the axis. The name is displayed to the left of the Y\naxis. This property is optional. The default is to have no axis name.\n\n*   \"nameformula\"\n\nOptional, can be used to link the name to a worksheet cell. See \"Chart names and links\".\n\nAdditional axis properties such as range, divisions and ticks will be made available in later\nreleases. See the \"TODO\" section.\n\nsettitle()\nThe \"settitle()\" method is used to set properties of the chart title.\n\n$chart->settitle( name => 'Year End Results' );\n\nThe properties that can be set are:\n\n*   \"name\"\n\nSet the name (title) for the chart. The name is displayed above the chart. This property is\noptional. The default is to have no chart title.\n\n*   \"nameformula\"\n\nOptional, can be used to link the name to a worksheet cell. See \"Chart names and links\".\n\nsetlegend()\nThe \"setlegend()\" method is used to set properties of the chart legend.\n\n$chart->setlegend( position => 'none' );\n\nThe properties that can be set are:\n\n*   \"position\"\n\nSet the position of the chart legend.\n\n$chart->setlegend( position => 'none' );\n\nThe default legend position is \"bottom\". The currently supported chart positions are:\n\nnone\nbottom\n\nThe other legend positions will be added soon.\n\nsetchartarea()\nThe \"setchartarea()\" method is used to set the properties of the chart area. In Excel the chart\narea is the background area behind the chart.\n\nThe properties that can be set are:\n\n*   \"color\"\n\nSet the colour of the chart area. The Excel default chart area color is 'white', index 9.\nSee \"Chart object colours\".\n\n*   \"linecolor\"\n\nSet the colour of the chart area border line. The Excel default border line colour is\n'black', index 9. See \"Chart object colours\".\n\n*   \"linepattern\"\n\nSet the pattern of the of the chart area border line. The Excel default pattern is 'none',\nindex 0 for a chart sheet and 'solid', index 1, for an embedded chart. See \"Chart line\npatterns\".\n\n*   \"lineweight\"\n\nSet the weight of the of the chart area border line. The Excel default weight is 'narrow',\nindex 2. See \"Chart line weights\".\n\nHere is an example of setting several properties:\n\n$chart->setchartarea(\ncolor        => 'red',\nlinecolor   => 'black',\nlinepattern => 2,\nlineweight  => 3,\n);\n\nNote, for chart sheets the chart area border is off by default. For embedded charts this is on\nby default.\n\nsetplotarea()\nThe \"setplotarea()\" method is used to set properties of the plot area of a chart. In Excel the\nplot area is the area between the axes on which the chart series are plotted.\n\nThe properties that can be set are:\n\n*   \"visible\"\n\nSet the visibility of the plot area. The default is 1 for visible. Set to 0 to hide the plot\narea and have the same colour as the background chart area.\n\n*   \"color\"\n\nSet the colour of the plot area. The Excel default plot area color is 'silver', index 23.\nSee \"Chart object colours\".\n\n*   \"linecolor\"\n\nSet the colour of the plot area border line. The Excel default border line colour is 'gray',\nindex 22. See \"Chart object colours\".\n\n*   \"linepattern\"\n\nSet the pattern of the of the plot area border line. The Excel default pattern is 'solid',\nindex 1. See \"Chart line patterns\".\n\n*   \"lineweight\"\n\nSet the weight of the of the plot area border line. The Excel default weight is 'narrow',\nindex 2. See \"Chart line weights\".\n\nHere is an example of setting several properties:\n\n$chart->setplotarea(\ncolor        => 'red',\nlinecolor   => 'black',\nlinepattern => 2,\nlineweight  => 3,\n);\n",
            "subsections": []
        },
        "WORKSHEET METHODS": {
            "content": "In Excel a chart sheet (i.e, a chart that isn't embedded) shares properties with data worksheets\nsuch as tab selection, headers, footers, margins and print properties.\n\nIn Spreadsheet::WriteExcel you can set chart sheet properties using the same methods that are\nused for Worksheet objects.\n\nThe following Worksheet methods are also available through a non-embedded Chart object:\n\ngetname()\nactivate()\nselect()\nhide()\nsetfirstsheet()\nprotect()\nsetzoom()\nsettabcolor()\n\nsetlandscape()\nsetportrait()\nsetpaper()\nsetmargins()\nsetheader()\nsetfooter()\n\nSee Spreadsheet::WriteExcel for a detailed explanation of these methods.\n",
            "subsections": []
        },
        "EXAMPLE": {
            "content": "Here is a complete example that demonstrates some of the available features when creating a\nchart.\n\n#!/usr/bin/perl -w\n\nuse strict;\nuse Spreadsheet::WriteExcel;\n\nmy $workbook  = Spreadsheet::WriteExcel->new( 'chartarea.xls' );\nmy $worksheet = $workbook->addworksheet();\nmy $bold      = $workbook->addformat( bold => 1 );\n\n# Add the worksheet data that the charts will refer to.\nmy $headings = [ 'Number', 'Sample 1', 'Sample 2' ];\nmy $data = [\n[ 2, 3, 4, 5, 6, 7 ],\n[ 1, 4, 5, 2, 1, 5 ],\n[ 3, 6, 7, 5, 4, 3 ],\n];\n\n$worksheet->write( 'A1', $headings, $bold );\n$worksheet->write( 'A2', $data );\n\n# Create a new chart object. In this case an embedded chart.\nmy $chart = $workbook->addchart( type => 'area', embedded => 1 );\n\n# Configure the first series. (Sample 1)\n$chart->addseries(\nname       => 'Sample 1',\ncategories => '=Sheet1!$A$2:$A$7',\nvalues     => '=Sheet1!$B$2:$B$7',\n);\n\n# Configure the second series. (Sample 2)\n$chart->addseries(\nname       => 'Sample 2',\ncategories => '=Sheet1!$A$2:$A$7',\nvalues     => '=Sheet1!$C$2:$C$7',\n);\n\n# Add a chart title and some axis labels.\n$chart->settitle ( name => 'Results of sample analysis' );\n$chart->setxaxis( name => 'Test number' );\n$chart->setyaxis( name => 'Sample length (cm)' );\n\n# Insert the chart into the worksheet (with an offset).\n$worksheet->insertchart( 'D2', $chart, 25, 10 );\n\nEND\n",
            "subsections": []
        },
        "Chart object colours": {
            "content": "Many of the chart objects supported by Spreadsheet::WriteExcl allow the default colours to be\nchanged. Excel provides a palette of 56 colours and in Spreadsheet::WriteExcel these colours are\naccessed via their palette index in the range 8..63.\n\nThe most commonly used colours can be accessed by name or index.\n\nblack   =>   8,    green    =>  17,    navy     =>  18,\nwhite   =>   9,    orange   =>  53,    pink     =>  33,\nred     =>  10,    gray     =>  23,    purple   =>  20,\nblue    =>  12,    lime     =>  11,    silver   =>  22,\nyellow  =>  13,    cyan     =>  15,\nbrown   =>  16,    magenta  =>  14,\n\nFor example the following are equivalent.\n\n$chart->setplotarea( color => 10    );\n$chart->setplotarea( color => 'red' );\n\nThe colour palette is shown in \"palette.html\" in the \"docs\" directory of the distro. An Excel\nversion of the palette can be generated using \"colors.pl\" in the \"examples\" directory.\n\nUser defined colours can be set using the \"setcustomcolor()\" workbook method. This and other\naspects of using colours are discussed in the \"Colours in Excel\" section of the main\nSpreadsheet::WriteExcel documentation:\n<http://search.cpan.org/dist/Spreadsheet-WriteExcel/lib/Spreadsheet/WriteExcel.pm#COLOURSINEXC\nEL>.\n",
            "subsections": []
        },
        "Chart line patterns": {
            "content": "Chart lines patterns can be set using either an index or a name:\n\n$chart->setplotarea( weight => 2      );\n$chart->setplotarea( weight => 'dash' );\n\nChart lines have 9 possible patterns are follows:\n\n'none'         => 0,\n'solid'        => 1,\n'dash'         => 2,\n'dot'          => 3,\n'dash-dot'     => 4,\n'dash-dot-dot' => 5,\n'medium-gray'  => 6,\n'dark-gray'    => 7,\n'light-gray'   => 8,\n\nThe patterns 1-8 are shown in order in the drop down dialog boxes in Excel. The default pattern\nis 'solid', index 1.\n",
            "subsections": []
        },
        "Chart line weights": {
            "content": "Chart lines weights can be set using either an index or a name:\n\n$chart->setplotarea( weight => 1          );\n$chart->setplotarea( weight => 'hairline' );\n\nChart lines have 4 possible weights are follows:\n\n'hairline' => 1,\n'narrow'   => 2,\n'medium'   => 3,\n'wide'     => 4,\n\nThe weights 1-4 are shown in order in the drop down dialog boxes in Excel. The default weight is\n'narrow', index 2.\n",
            "subsections": []
        },
        "Chart names and links": {
            "content": "The addseries()), \"setxaxis()\", \"setyaxis()\" and \"settitle()\" methods all support a \"name\"\nproperty. In general these names can be either a static string or a link to a worksheet cell. If\nyou choose to use the \"nameformula\" property to specify a link then you should also the \"name\"\nproperty. This isn't strictly required by Excel but some third party applications expect it to\nbe present.\n\n$chart->settitle(\nname          => 'Year End Results',\nnameformula  => '=Sheet1!$C$1',\n);\n\nThese links should be used sparingly since they aren't commonly used in Excel charts.\n",
            "subsections": []
        },
        "Chart names and Unicode": {
            "content": "The addseries()), \"setxaxis()\", \"setyaxis()\" and \"settitle()\" methods all support a \"name\"\nproperty. These names can be UTF8 strings if you are using perl 5.8+.\n\n# perl 5.8+ example:\nmy $smiley = \"\\x{263A}\";\n\n$chart->settitle( name => \"Best. Results. Ever! $smiley\" );\n\nFor older perls you write Unicode strings as UTF-16BE by adding a \"nameencoding\" property:\n\n# perl 5.005 example:\nmy $utf16bename = pack 'n', 0x263A;\n\n$chart->settitle(\nname          => $utf16bename,\nnameencoding => 1,\n);\n\nThis methodology is explained in the \"UNICODE IN EXCEL\" section of Spreadsheet::WriteExcel but\nis semi-deprecated. If you are using Unicode the easiest option is to just use UTF8 in perl\n5.8+.\n",
            "subsections": []
        },
        "Working with Cell Ranges": {
            "content": "In the section on \"addseries()\" it was noted that the series must be defined using a range\nformula:\n\n$chart->addseries( values => '=Sheet1!$B$2:$B$10' );\n\nThe worksheet name must be specified (even for embedded charts) and the cell references must be\n\"absolute\" references, i.e., they must contain \"$\" signs. This is the format that is required by\nExcel for chart references.\n\nSince it isn't very convenient to work with this type of string programmatically the\nSpreadsheet::WriteExcel::Utility module, which is included with Spreadsheet::WriteExcel,\nprovides a function called \"xlrangeformula()\" to convert from zero based row and column cell\nreferences to an A1 style formula string.\n\nThe syntax is:\n\nxlrangeformula($sheetname, $row1, $row2, $col1, $col2)\n\nIf you include it in your program, using the standard import syntax, you can use the function as\nfollows:\n\n# Include the Utility module or just the function you need.\nuse Spreadsheet::WriteExcel::Utility qw( xlrangeformula );\n...\n\n# Then use it as required.\n$chart->addseries(\ncategories    => xlrangeformula( 'Sheet1', 1, 9, 0, 0 ),\nvalues        => xlrangeformula( 'Sheet1', 1, 9, 1, 1 ),\n);\n\n# Which is the same as:\n$chart->addseries(\ncategories    => '=Sheet1!$A$2:$A$10',\nvalues        => '=Sheet1!$B$2:$B$10',\n);\n\nSee Spreadsheet::WriteExcel::Utility for more details.\n",
            "subsections": []
        },
        "TODO": {
            "content": "Charts in Spreadsheet::WriteExcel are a work in progress. More chart types and features will be\nadded in time. Please be patient. Even a small feature can take a week or more to implement,\ntest and document.\n\nFeatures that are on the TODO list and will be added are:\n\n*   Chart sub-types.\n\n*   Colours and formatting options. For now you will have to make do with the default Excel\ncolours and formats.\n\n*   Axis controls, gridlines.\n\n*   3D charts.\n\n*   Embedded data in charts for third party application support. See Known Issues.\n\n*   Additional chart types such as Bubble and Radar. Send an email if you are interested in\nother types and they will be added to the queue.\n\nIf you are interested in sponsoring a feature let me know.\n",
            "subsections": []
        },
        "KNOWN ISSUES": {
            "content": "*   Currently charts don't contain embedded data from which the charts can be rendered. Excel\nand most other third party applications ignore this and read the data via the links that\nhave been specified. However, some applications may complain or not render charts correctly.\nThe preview option in Mac OS X is an known example. This will be fixed in a later release.\n\n*   When there are several charts with titles set in a workbook some of the titles may display\nat a font size of 10 instead of the default 12 until another chart with the title set is\nviewed.\n\n*   Stock (and other) charts should have the X-axis dates aligned at an angle for clarity. This\nwill be fixed at a later stage.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "John McNamara jmcnamara@cpan.org\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "Copyright MM-MMX, John McNamara.\n\nAll Rights Reserved. This module is free software. It may be used, redistributed and/or modified\nunder the same terms as Perl itself.\n",
            "subsections": []
        }
    },
    "summary": "Chart - A writer class for Excel Charts.",
    "flags": [],
    "examples": [
        "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( 'chartarea.xls' );",
        "my $worksheet = $workbook->addworksheet();",
        "my $bold      = $workbook->addformat( 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->addchart( type => 'area', embedded => 1 );",
        "# Configure the first series. (Sample 1)",
        "$chart->addseries(",
        "name       => 'Sample 1',",
        "categories => '=Sheet1!$A$2:$A$7',",
        "values     => '=Sheet1!$B$2:$B$7',",
        ");",
        "# Configure the second series. (Sample 2)",
        "$chart->addseries(",
        "name       => 'Sample 2',",
        "categories => '=Sheet1!$A$2:$A$7',",
        "values     => '=Sheet1!$C$2:$C$7',",
        ");",
        "# Add a chart title and some axis labels.",
        "$chart->settitle ( name => 'Results of sample analysis' );",
        "$chart->setxaxis( name => 'Test number' );",
        "$chart->setyaxis( name => 'Sample length (cm)' );",
        "# Insert the chart into the worksheet (with an offset).",
        "$worksheet->insertchart( 'D2', $chart, 25, 10 );",
        "END"
    ],
    "see_also": []
}