1Excel::Writer::XLSX::ChUasretr::CDoonutgrhinbuutt(e3d)PEexrclelD:o:cWurmietnetra:t:iXoLnSX::Chart::Doughnut(3)
2
6 Doughnut - A class for writing Excel Doughnut charts.
7
9 To create a simple Excel file with a Doughnut chart using
10 Excel::Writer::XLSX:
11 #!/usr/bin/perl
13 use strict;
15 use warnings;
16 use Excel::Writer::XLSX;
17 my $workbook = Excel::Writer::XLSX->new( 'chart.xlsx' );
19 my $worksheet = $workbook->add_worksheet();
20 my $chart = $workbook->add_chart( type => 'doughnut' );
22 # Configure the chart.
24 $chart->add_series(
25 categories => '=Sheet1!$A$2:$A$7',
26 values => '=Sheet1!$B$2:$B$7',
27 );
28 # Add the worksheet data the chart refers to.
30 my $data = [
31 [ 'Category', 2, 3, 4, 5, 6, 7 ],
32 [ 'Value', 1, 4, 5, 2, 1, 5 ],
33 ];
34 $worksheet->write( 'A1', $data );
36 __END__
38
40 This module implements Doughnut charts for Excel::Writer::XLSX. The
41 chart object is created via the Workbook add_chart() method:
42 my $chart = $workbook->add_chart( type => 'doughnut' );
44 Once the object is created it can be configured via the following
46 methods that are common to all chart classes:
47 $chart->add_series();
49 $chart->set_title();
50 These methods are explained in detail in Excel::Writer::XLSX::Chart.
52 Class specific methods or settings, if any, are explained below.
53
55 set_rotation()
56 The set_rotation() method is used to set the rotation of the first
57 segment of a Pie/Doughnut chart. This has the effect of rotating the
58 entire chart:
59 $chart->set_rotation( 90 );
61 The angle of rotation must be "0 <= rotation <= 360".
63 set_hole_size()
65 The set_hole_size() method is used to set the hole size of a Doughnut
66 chart:
67 $chart->set_hole_size( 33 );
69 The the hole size must be a percentage in the range "10 <= size <=
71 90".
72 User defined colors
74 It is possible to define chart colors for most types of
75 Excel::Writer::XLSX charts via the add_series() method. However,
76 Pie/Doughnut charts are a special case since each segment is
77 represented as a point so it is necessary to assign formatting to each
78 point in the series:
79 $chart->add_series(
81 values => '=Sheet1!$A$1:$A$3',
82 points => [
83 { fill => { color => '#FF0000' } },
84 { fill => { color => '#CC0000' } },
85 { fill => { color => '#990000' } },
86 ],
87 );
88 See the main Excel::Writer::XLSX::Chart documentation for more details.
90 Doughnut charts support leader lines:
92 $chart->add_series(
94 name => 'Doughnut sales data',
95 categories => [ 'Sheet1', 1, 3, 0, 0 ],
96 values => [ 'Sheet1', 1, 3, 1, 1 ],
97 data_labels => {
98 series_name => 1,
99 percentage => 1,
100 leader_lines => 1,
101 position => 'outside_end'
102 },
103 );
104 Note: Even when leader lines are turned on they aren't automatically
106 visible in Excel or Excel::Writer::XLSX. Due to an Excel limitation (or
107 design) leader lines only appear if the data label is moved manually or
108 if the data labels are very close and need to be adjusted
109 automatically.
110 Unsupported Methods
112 A Doughnut chart doesn't have an X or Y axis so the following common
113 chart methods are ignored.
114 $chart->set_x_axis();
116 $chart->set_y_axis();
117
119 Here is a complete example that demonstrates most of the available
120 features when creating a chart.
121 #!/usr/bin/perl
123 use strict;
125 use warnings;
126 use Excel::Writer::XLSX;
127 my $workbook = Excel::Writer::XLSX->new( 'chart_doughnut.xlsx' );
129 my $worksheet = $workbook->add_worksheet();
130 my $bold = $workbook->add_format( bold => 1 );
131 # Add the worksheet data that the charts will refer to.
133 my $headings = [ 'Category', 'Values' ];
134 my $data = [
135 [ 'Glazed', 'Chocolate', 'Cream' ],
136 [ 50, 35, 15 ],
137 ];
138 $worksheet->write( 'A1', $headings, $bold );
140 $worksheet->write( 'A2', $data );
141 # Create a new chart object. In this case an embedded chart.
143 my $chart = $workbook->add_chart( type => 'doughnut', embedded => 1 );
144 # Configure the series. Note the use of the array ref to define ranges:
146 # [ $sheetname, $row_start, $row_end, $col_start, $col_end ].
147 $chart->add_series(
148 name => 'Doughnut sales data',
149 categories => [ 'Sheet1', 1, 3, 0, 0 ],
150 values => [ 'Sheet1', 1, 3, 1, 1 ],
151 );
152 # Add a title.
154 $chart->set_title( name => 'Popular Doughnut Types' );
155 # Set an Excel chart style. Colors with white outline and shadow.
157 $chart->set_style( 10 );
158 # Insert the chart into the worksheet (with an offset).
160 $worksheet->insert_chart( 'C2', $chart, 25, 10 );
161 __END__
163
165 John McNamara jmcnamara@cpan.org
166
168 Copyright MM-MMXXI, John McNamara.
169 All Rights Reserved. This module is free software. It may be used,
171 redistributed and/or modified under the same terms as Perl itself.
172perl v5.36.0 2023-0E1x-c2e0l::Writer::XLSX::Chart::Doughnut(3)