File: //usr/local/ssl/local/share/man/man3/SVG::TT::Graph::Pie.3
.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
.\"
.\" 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 "SVG::TT::Graph::Pie 3"
.TH SVG::TT::Graph::Pie 3 "2013-02-04" "perl v5.8.8" "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"
SVG::TT::Graph::Pie \- Create presentation quality SVG pie graphs easily
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use SVG::TT::Graph::Pie;
\&
\& my @fields = qw(Jan Feb Mar);
\& my @data_sales_02 = qw(12 45 21);
\&
\& my $graph = SVG::TT::Graph::Pie\->new({
\& \*(Aqheight\*(Aq => \*(Aq500\*(Aq,
\& \*(Aqwidth\*(Aq => \*(Aq300\*(Aq,
\& \*(Aqfields\*(Aq => \e@fields,
\& });
\&
\& $graph\->add_data({
\& \*(Aqdata\*(Aq => \e@data_sales_02,
\& \*(Aqtitle\*(Aq => \*(AqSales 2002\*(Aq,
\& });
\&
\& print "Content\-type: image/svg+xml\en\en";
\& print $graph\->burn();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This object aims to allow you to easily create high quality
\&\s-1SVG\s0 pie graphs. You can either use the default style sheet
or supply your own. Either way there are many options which can
be configured to give you control over how the graph is
generated \- with or without a key, display percent on pie chart,
title, subtitle etc.
.SH "METHODS"
.IX Header "METHODS"
.SS "\fInew()\fP"
.IX Subsection "new()"
.Vb 1
\& use SVG::TT::Graph::Pie;
\&
\& # Field names along the X axis
\& my @fields = qw(Jan Feb Mar);
\&
\& my $graph = SVG::TT::Graph::Pie\->new({
\& # Required
\& \*(Aqfields\*(Aq => \e@fields,
\&
\& # Optional \- defaults shown
\& \*(Aqheight\*(Aq => \*(Aq500\*(Aq,
\& \*(Aqwidth\*(Aq => \*(Aq300\*(Aq,
\&
\& \*(Aqshow_graph_title\*(Aq => 0,
\& \*(Aqgraph_title\*(Aq => \*(AqGraph Title\*(Aq,
\& \*(Aqshow_graph_subtitle\*(Aq => 0,
\& \*(Aqgraph_subtitle\*(Aq => \*(AqGraph Sub Title\*(Aq,
\&
\& \*(Aqshow_shadow\*(Aq => 1,
\& \*(Aqshadow_size\*(Aq => 1,
\& \*(Aqshadow_offset\*(Aq => 15,
\&
\& \*(Aqkey_placement\*(Aq => \*(AqR\*(Aq,
\&
\& # data by pie chart wedges:
\& \*(Aqshow_data_labels\*(Aq => 0,
\& \*(Aqshow_actual_values\*(Aq => 0,
\& \*(Aqshow_percent\*(Aq => 1,
\& \*(Aqrollover_values\*(Aq => 0,
\&
\& # data on key:
\& \*(Aqshow_key_data_labels\*(Aq => 1,
\& \*(Aqshow_key_actual_values\*(Aq => 1,
\& \*(Aqshow_key_percent\*(Aq => 0,
\&
\& \*(Aqexpanded\*(Aq => 0,
\& \*(Aqexpand_greatest\*(Aq => 0,
\&
\& # Stylesheet defaults
\& \*(Aqstyle_sheet\*(Aq => \*(Aq/includes/graph.css\*(Aq, # internal stylesheet
\& \*(Aqstyle_sheet_field_names\*(Aq => 0,
\& \*(Aqrandom_colors\*(Aq => 0,
\&
\& });
.Ve
.PP
The constructor takes a hash reference, fields (the name for each
slice on the pie) \s-1MUST\s0 be set, all other values are defaulted to those
shown above \- with the exception of style_sheet which defaults
to using the internal style sheet.
.SS "\fIadd_data()\fP"
.IX Subsection "add_data()"
.Vb 1
\& my @data_sales_02 = qw(12 45 21);
\&
\& $graph\->add_data({
\& \*(Aqdata\*(Aq => \e@data_sales_02,
\& \*(Aqtitle\*(Aq => \*(AqSales 2002\*(Aq,
\& });
.Ve
.PP
This method allows you to add data to the graph object, only
the first data set added will be used!
.SS "\fIclear_data()\fP"
.IX Subsection "clear_data()"
.Vb 1
\& my $graph\->clear_data();
.Ve
.PP
This method removes all data from the object so that you can
reuse it to create a new graph but with the same config options.
.SS "\fIburn()\fP"
.IX Subsection "burn()"
.Vb 1
\& print $graph\->burn();
.Ve
.PP
This method processes the template with the data and
config which has been set and returns the resulting \s-1SVG\s0.
.PP
This method will croak unless at least one data set has
been added to the graph object.
.SS "config methods"
.IX Subsection "config methods"
.Vb 2
\& my $value = $graph\->method();
\& my $confirmed_new_value = $graph\->method($value);
.Ve
.PP
The following is a list of the methods which are available
to change the config of the graph object after it has been
created.
.IP "\fIheight()\fR" 4
.IX Item "height()"
Set the height of the graph box, this is the total height
of the \s-1SVG\s0 box created \- not the graph it self which auto
scales to fix the space.
.IP "\fIwidth()\fR" 4
.IX Item "width()"
Set the width of the graph box, this is the total width
of the \s-1SVG\s0 box created \- not the graph it self which auto
scales to fix the space.
.IP "\fIcompress()\fR" 4
.IX Item "compress()"
Whether or not to compress the content of the \s-1SVG\s0 file (Compress::Zlib required).
.IP "\fItidy()\fR" 4
.IX Item "tidy()"
Whether or not to tidy the content of the \s-1SVG\s0 file (XML::Tidy required).
.IP "\fIstyle_sheet()\fR" 4
.IX Item "style_sheet()"
Set the path to an external stylesheet, set to '' if
you want to revert back to using the defaut internal version.
.Sp
The default stylesheet handles up to 12 data sets. All data series over
the 12th will have no style and be in black. If you have over 12 data
sets you can assign them all random colors (see the \fIrandom_color()\fR
method) or create your own stylesheet and add the additional settings
for the extra data sets.
.Sp
To create an external stylesheet create a graph using the
default internal version and copy the stylesheet section to
an external file and edit from there.
.IP "\fIrandom_colors()\fR" 4
.IX Item "random_colors()"
Use random colors in the internal stylesheet
.IP "\fIstyle_sheet_field_names()\fR" 4
.IX Item "style_sheet_field_names()"
If you use the \fIstyle_sheet_field_names()\fR option then you can
use the field names within your stylesheet. This allows
consistent use of styles. The names should be:
.RS 4
.IP "<field>_dataPoint" 4
.IX Item "<field>_dataPoint"
.PD 0
.IP "<field>_key" 4
.IX Item "<field>_key"
.RE
.RS 4
.RE
.IP "\fIshow_graph_title()\fR" 4
.IX Item "show_graph_title()"
.PD
Whether to show a title on the graph, default is '0'.
.IP "\fIgraph_title()\fR" 4
.IX Item "graph_title()"
What the title on the graph should be.
.IP "\fIshow_graph_subtitle()\fR" 4
.IX Item "show_graph_subtitle()"
Whether to show a subtitle on the graph, default is '0'.
.IP "\fIgraph_subtitle()\fR" 4
.IX Item "graph_subtitle()"
What the subtitle on the graph should be.
.IP "\fIshow_shadow()\fR" 4
.IX Item "show_shadow()"
Turn the shadow on and off, default to '1', set
to '0' if you don't want it. It is automatically
turned off if you extract one section of the pie.
.IP "\fIshadow_size()\fR" 4
.IX Item "shadow_size()"
Size of the shadow if shown, measured as
percentage of pie chart radius, default of 1
being the same size as the pie.
.IP "\fIshadow_offset()\fR" 4
.IX Item "shadow_offset()"
Offset (in pixels) of shadow to bottom-right
in relation to the center of the pie chart.
.IP "\fIkey()\fR" 4
.IX Item "key()"
Whether to show a key, defaults to 0, set to
\&'1' if you want to show it.
.IP "\fIkey_placement()\fR" 4
.IX Item "key_placement()"
Defaults to 'R' \- right, can be
\&'R', 'L', 'T' or 'B'.
.IP "\fIshow_data_labels()\fR" 4
.IX Item "show_data_labels()"
Show label on pie chart, defaults
to '0', can be set to '1'.
.IP "\fIshow_actual_values()\fR" 4
.IX Item "show_actual_values()"
Show values on pie chart, defaults
to '0', can be set to '1'.
.IP "\fIshow_percent()\fR" 4
.IX Item "show_percent()"
Show percent (rounded) on the pie chart, defaults
to '1', can be set to '0'.
.IP "\fIrollover_values()\fR" 4
.IX Item "rollover_values()"
Shows data field and value when the mouse is over a piechart wedge.
.IP "\fIshow_key_data_labels()\fR" 4
.IX Item "show_key_data_labels()"
Show label on the key, defaults
to '1', can be set to '0'.
.IP "\fIshow_key_actual_values()\fR" 4
.IX Item "show_key_actual_values()"
Show value on the key, defaults
to '1', can be set to '0'.
.IP "\fIshow_key_percent()\fR" 4
.IX Item "show_key_percent()"
Show percent (rounded) on the key, defaults
to '0', can be set to '1'.
.IP "\fIexpanded()\fR" 4
.IX Item "expanded()"
All slices of pie are exploded out, defaults
to '0'. Do not set to '1' if you are going to
use \fIexpanded_greatest()\fR.
.IP "\fIexpand_greatest()\fR" 4
.IX Item "expand_greatest()"
The largest slice of pie is exploded out
from the pie, defaults to '0'. Useful if you are
only showing the percentages (which are rounded) but
still want to visually show which slice was largest.
.Sp
Do not set to '1' if you are going to
use \fIexpanded()\fR.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
For examples look at the project home page
http://leo.cuckoo.org/projects/SVG\-TT\-Graph/
.SH "EXPORT"
.IX Header "EXPORT"
None by default.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Thanks to Foxtons for letting us put this on \s-1CPAN\s0, Todd Caine for heads up on
reparsing the template (but not using atm), David Meibusch for TimeSeries and a
load of other ideas, Stephen Morgan for creating the \s-1TT\s0 template and \s-1SVG\s0, and
thanks for all the patches by Andrew Ruthven and others.
.SH "AUTHOR"
.IX Header "AUTHOR"
Leo Lapworth <LLAP@cuckoo.org>
.SH "MAINTAINER"
.IX Header "MAINTAINER"
Florent Angly <florent.angly@gmail.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2003, Leo Lapworth
.PP
This module is free software; you can redistribute it or
modify it under the same terms as Perl itself.
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to bug\-graph\-svg\-tt@rt.cpan.org, or
through the web interface at http://rt.cpan.org.
.PP
The Graph::SVG::TT development repository is located on GitHub at
http://github.com/ranguard/svg\-tt\-graph <http://github.com/ranguard/svg-tt-graph>. Get the latest development version
using: git clone git://github.com/ranguard/svg\-tt\-graph.git
.SH "SEE ALSO"
.IX Header "SEE ALSO"
SVG::TT::Graph,
SVG::TT::Graph::Line,
SVG::TT::Graph::Bar,
SVG::TT::Graph::BarHorizontal,
SVG::TT::Graph::BarLine,
SVG::TT::Graph::TimeSeries,
SVG::TT::Graph::XY,
Compress::Zlib,
XML::Tidy