1Excel::Writer::XLSX::ChUasretr::CDoonutgrhinbuutt(e3d)PEexrclelD:o:cWurmietnetra:t:iXoLnSX::Chart::Doughnut(3)
2
3
4

NAME

6       Doughnut - A class for writing Excel Doughnut charts.
7

SYNOPSIS

9       To create a simple Excel file with a Doughnut chart using
10       Excel::Writer::XLSX:
11
12           #!/usr/bin/perl
13
14           use strict;
15           use warnings;
16           use Excel::Writer::XLSX;
17
18           my $workbook  = Excel::Writer::XLSX->new( 'chart.xlsx' );
19           my $worksheet = $workbook->add_worksheet();
20
21           my $chart     = $workbook->add_chart( type => 'doughnut' );
22
23           # Configure the chart.
24           $chart->add_series(
25               categories => '=Sheet1!$A$2:$A$7',
26               values     => '=Sheet1!$B$2:$B$7',
27           );
28
29           # 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
35           $worksheet->write( 'A1', $data );
36
37           __END__
38

DESCRIPTION

40       This module implements Doughnut charts for Excel::Writer::XLSX. The
41       chart object is created via the Workbook "add_chart()" method:
42
43           my $chart = $workbook->add_chart( type => 'doughnut' );
44
45       Once the object is created it can be configured via the following
46       methods that are common to all chart classes:
47
48           $chart->add_series();
49           $chart->set_title();
50
51       These methods are explained in detail in Excel::Writer::XLSX::Chart.
52       Class specific methods or settings, if any, are explained below.
53

Doughnut Chart Methods

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
60           $chart->set_rotation( 90 );
61
62       The angle of rotation must be "0 <= rotation <= 360".
63
64   set_hole_size()
65       The "set_hole_size()" method is used to set the hole size of a Doughnut
66       chart:
67
68           $chart->set_hole_size( 33 );
69
70       The the hole size must be a percentage in the range  "10 <= size <=
71       90".
72
73   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
80           $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
89       See the main Excel::Writer::XLSX::Chart documentation for more details.
90
91       Doughnut charts support leader lines:
92
93           $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
105       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
111   Unsupported Methods
112       A Doughnut chart doesn't have an X or Y axis so the following common
113       chart methods are ignored.
114
115           $chart->set_x_axis();
116           $chart->set_y_axis();
117

EXAMPLE

119       Here is a complete example that demonstrates most of the available
120       features when creating a chart.
121
122           #!/usr/bin/perl
123
124           use strict;
125           use warnings;
126           use Excel::Writer::XLSX;
127
128           my $workbook  = Excel::Writer::XLSX->new( 'chart_doughnut.xlsx' );
129           my $worksheet = $workbook->add_worksheet();
130           my $bold      = $workbook->add_format( bold => 1 );
131
132           # 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
139           $worksheet->write( 'A1', $headings, $bold );
140           $worksheet->write( 'A2', $data );
141
142           # Create a new chart object. In this case an embedded chart.
143           my $chart = $workbook->add_chart( type => 'doughnut', embedded => 1 );
144
145           # 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
153           # Add a title.
154           $chart->set_title( name => 'Popular Doughnut Types' );
155
156           # Set an Excel chart style. Colors with white outline and shadow.
157           $chart->set_style( 10 );
158
159           # Insert the chart into the worksheet (with an offset).
160           $worksheet->insert_chart( 'C2', $chart, 25, 10 );
161
162           __END__
163

AUTHOR

165       John McNamara jmcnamara@cpan.org
166
168       Copyright MM-MMXXI, John McNamara.
169
170       All Rights Reserved. This module is free software. It may be used,
171       redistributed and/or modified under the same terms as Perl itself.
172
173
174
175perl v5.36.0                      2022-0E7x-c2e2l::Writer::XLSX::Chart::Doughnut(3)
Impressum