File Coverage

blib/lib/Excel/Writer/XLSX/Chart/Doughnut.pm
Criterion Covered Total %
statement 40 41 97.5
branch 2 4 50.0
condition 1 3 33.3
subroutine 10 10 100.0
pod 1 2 50.0
total 54 60 90.0


line stmt bran cond sub pod time code
1              
2             ###############################################################################
3             #
4             # Doughnut - A class for writing Excel Doughnut charts.
5             #
6             # Used in conjunction with Excel::Writer::XLSX::Chart.
7             #
8             # See formatting note in Excel::Writer::XLSX::Chart.
9             #
10             # Copyright 2000-2021, John McNamara, jmcnamara@cpan.org
11             #
12             # Documentation after __END__
13             #
14              
15             # perltidy with the following options: -mbl=2 -pt=0 -nola
16              
17             use 5.008002;
18 11     11   172 use strict;
  11         29  
19 11     11   44 use warnings;
  11         17  
  11         178  
20 11     11   39 use Carp;
  11         15  
  11         203  
21 11     11   38 use Excel::Writer::XLSX::Chart::Pie;
  11         17  
  11         498  
22 11     11   3974  
  11         24  
  11         2901  
23             our @ISA = qw(Excel::Writer::XLSX::Chart::Pie);
24             our $VERSION = '1.09';
25              
26              
27             ###############################################################################
28             #
29             # new()
30             #
31             #
32              
33             my $class = shift;
34             my $self = Excel::Writer::XLSX::Chart::Pie->new( @_ );
35 11     11 0 22  
36 11         689 $self->{_vary_data_color} = 1;
37             $self->{_hole_size} = 50;
38 11         55 $self->{_rotation} = 0;
39 11         18  
40 11         22 bless $self, $class;
41             return $self;
42 11         19 }
43 11         37  
44              
45             ###############################################################################
46             #
47             # set_hole_size()
48             #
49             # Set the Doughnut chart hole size.
50             #
51              
52             my $self = shift;
53             my $size = shift;
54              
55 2     2 1 6 return if !defined $size;
56 2         4  
57             if ( $size >= 10 && $size <= 90 ) {
58 2 50       4 $self->{_hole_size} = $size;
59             }
60 2 50 33     6 else {
61 2         5 carp "Hole size $size outside Excel range: 10 <= size <= 90";
62             }
63             }
64 0         0  
65              
66             ##############################################################################
67             #
68             # _write_chart_type()
69             #
70             # Override the virtual superclass method with a chart specific method.
71             #
72              
73             my $self = shift;
74              
75             # Write the c:doughnutChart element.
76             $self->_write_doughnut_chart( @_ );
77 11     11   16 }
78              
79              
80 11         28 ##############################################################################
81             #
82             # _write_doughnut_chart()
83             #
84             # Write the <c:doughnutChart> element. Over-ridden method to remove axis_id code
85             # since Doughnut charts don't require val and cat axes.
86             #
87              
88             my $self = shift;
89              
90             $self->xml_start_tag( 'c:doughnutChart' );
91              
92             # Write the c:varyColors element.
93 11     11   15 $self->_write_vary_colors();
94              
95 11         32 # Write the series elements.
96             $self->_write_ser( $_ ) for @{ $self->{_series} };
97              
98 11         76 # Write the c:firstSliceAng element.
99             $self->_write_first_slice_ang();
100              
101 11         23 # Write the c:holeSize element.
  11         78  
102             $self->_write_hole_size();
103              
104 11         71 $self->xml_end_tag( 'c:doughnutChart' );
105             }
106              
107 11         32  
108             ##############################################################################
109 11         26 #
110             # _write_hole_size()
111             #
112             # Write the <c:holeSize> element.
113             #
114              
115             my $self = shift;
116             my $val = $self->{_hole_size};
117              
118             my @attributes = ( 'val' => $val );
119              
120             $self->xml_empty_tag( 'c:holeSize', @attributes );
121 11     11   24 }
122 11         16  
123             1;
124 11         23  
125              
126 11         35  
127              
128             =head1 NAME
129              
130             Doughnut - A class for writing Excel Doughnut charts.
131              
132             =head1 SYNOPSIS
133              
134             To create a simple Excel file with a Doughnut chart using Excel::Writer::XLSX:
135              
136             #!/usr/bin/perl
137              
138             use strict;
139             use warnings;
140             use Excel::Writer::XLSX;
141              
142             my $workbook = Excel::Writer::XLSX->new( 'chart.xlsx' );
143             my $worksheet = $workbook->add_worksheet();
144              
145             my $chart = $workbook->add_chart( type => 'doughnut' );
146              
147             # Configure the chart.
148             $chart->add_series(
149             categories => '=Sheet1!$A$2:$A$7',
150             values => '=Sheet1!$B$2:$B$7',
151             );
152              
153             # Add the worksheet data the chart refers to.
154             my $data = [
155             [ 'Category', 2, 3, 4, 5, 6, 7 ],
156             [ 'Value', 1, 4, 5, 2, 1, 5 ],
157             ];
158              
159             $worksheet->write( 'A1', $data );
160              
161             __END__
162              
163             =head1 DESCRIPTION
164              
165             This module implements Doughnut charts for L<Excel::Writer::XLSX>. The chart object is created via the Workbook C<add_chart()> method:
166              
167             my $chart = $workbook->add_chart( type => 'doughnut' );
168              
169             Once the object is created it can be configured via the following methods that are common to all chart classes:
170              
171             $chart->add_series();
172             $chart->set_title();
173              
174             These methods are explained in detail in L<Excel::Writer::XLSX::Chart>. Class specific methods or settings, if any, are explained below.
175              
176             =head1 Doughnut Chart Methods
177              
178             =head2 set_rotation()
179              
180             The C<set_rotation()> method is used to set the rotation of the first segment of a Pie/Doughnut chart. This has the effect of rotating the entire chart:
181              
182             $chart->set_rotation( 90 );
183              
184             The angle of rotation must be C<< 0 <= rotation <= 360 >>.
185              
186              
187             =head2 set_hole_size()
188              
189             The C<set_hole_size()> method is used to set the hole size of a Doughnut chart:
190              
191             $chart->set_hole_size( 33 );
192              
193             The the hole size must be a percentage in the range C<< 10 <= size <= 90 >>.
194              
195              
196             =head2 User defined colors
197              
198             It is possible to define chart colors for most types of Excel::Writer::XLSX charts via the add_series() method. However, Pie/Doughnut charts are a special case since each segment is represented as a point so it is necessary to assign formatting to each point in the series:
199              
200             $chart->add_series(
201             values => '=Sheet1!$A$1:$A$3',
202             points => [
203             { fill => { color => '#FF0000' } },
204             { fill => { color => '#CC0000' } },
205             { fill => { color => '#990000' } },
206             ],
207             );
208              
209             See the main L<Excel::Writer::XLSX::Chart> documentation for more details.
210              
211             Doughnut charts support leader lines:
212              
213             $chart->add_series(
214             name => 'Doughnut sales data',
215             categories => [ 'Sheet1', 1, 3, 0, 0 ],
216             values => [ 'Sheet1', 1, 3, 1, 1 ],
217             data_labels => {
218             series_name => 1,
219             percentage => 1,
220             leader_lines => 1,
221             position => 'outside_end'
222             },
223             );
224              
225             Note: Even when leader lines are turned on they aren't automatically visible in Excel or Excel::Writer::XLSX. Due to an Excel limitation (or design) leader lines only appear if the data label is moved manually or if the data labels are very close and need to be adjusted automatically.
226              
227             =head2 Unsupported Methods
228              
229             A Doughnut chart doesn't have an X or Y axis so the following common chart methods are ignored.
230              
231             $chart->set_x_axis();
232             $chart->set_y_axis();
233              
234             =head1 EXAMPLE
235              
236             Here is a complete example that demonstrates most of the available features when creating a chart.
237              
238             #!/usr/bin/perl
239              
240             use strict;
241             use warnings;
242             use Excel::Writer::XLSX;
243              
244             my $workbook = Excel::Writer::XLSX->new( 'chart_doughnut.xlsx' );
245             my $worksheet = $workbook->add_worksheet();
246             my $bold = $workbook->add_format( bold => 1 );
247              
248             # Add the worksheet data that the charts will refer to.
249             my $headings = [ 'Category', 'Values' ];
250             my $data = [
251             [ 'Glazed', 'Chocolate', 'Cream' ],
252             [ 50, 35, 15 ],
253             ];
254              
255             $worksheet->write( 'A1', $headings, $bold );
256             $worksheet->write( 'A2', $data );
257              
258             # Create a new chart object. In this case an embedded chart.
259             my $chart = $workbook->add_chart( type => 'doughnut', embedded => 1 );
260              
261             # Configure the series. Note the use of the array ref to define ranges:
262             # [ $sheetname, $row_start, $row_end, $col_start, $col_end ].
263             $chart->add_series(
264             name => 'Doughnut sales data',
265             categories => [ 'Sheet1', 1, 3, 0, 0 ],
266             values => [ 'Sheet1', 1, 3, 1, 1 ],
267             );
268              
269             # Add a title.
270             $chart->set_title( name => 'Popular Doughnut Types' );
271              
272             # Set an Excel chart style. Colors with white outline and shadow.
273             $chart->set_style( 10 );
274              
275             # Insert the chart into the worksheet (with an offset).
276             $worksheet->insert_chart( 'C2', $chart, 25, 10 );
277              
278             __END__
279              
280              
281             =begin html
282              
283             <p>This will produce a chart that looks like this:</p>
284              
285             <p><center><img src="http://jmcnamara.github.io/excel-writer-xlsx/images/examples/doughnut1.jpg" width="483" height="291" alt="Chart example." /></center></p>
286              
287             =end html
288              
289              
290             =head1 AUTHOR
291              
292             John McNamara jmcnamara@cpan.org
293              
294             =head1 COPYRIGHT
295              
296             Copyright MM-MMXXI, John McNamara.
297              
298             All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.