.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SVG::TT::Graph::BarLine 3"
.TH SVG::TT::Graph::BarLine 3 "2014-09-23" "perl v5.16.3" "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::BarLine \- Create presentation quality SVG bar\-line graphs easily
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use SVG::TT::Graph::BarLine;
\&
\&  my @fields = qw(Jan Feb Mar);
\&  my @data_sales_02 = qw(12 45 21);
\&  my @data_sales_03 = (24, 55, 61);
\&
\&  my $graph = SVG::TT::Graph::BarLine\->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,
\&  });
\&
\&  $graph\->add_data({
\&    \*(Aqdata\*(Aq  => \e@data_sales_03,
\&    \*(Aqtitle\*(Aq => \*(AqSales 2003\*(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 bar 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, data elements at each point,
title, subtitle etc.
.SH "METHODS"
.IX Header "METHODS"
.SS "\fInew()\fP"
.IX Subsection "new()"
.Vb 1
\&  use SVG::TT::Graph::BarLine;
\&
\&  # Field names along the X axis
\&  my @fields = qw(Jan Feb Mar);
\&
\&  my $graph = SVG::TT::Graph::BarLine\->new({
\&    # Required
\&    \*(Aqfields\*(Aq                           => \e@fields,
\&
\&    # Optional \- defaults shown
\&    \*(Aqheight\*(Aq                           => \*(Aq500\*(Aq,
\&    \*(Aqwidth\*(Aq                            => \*(Aq300\*(Aq,
\&
\&    \*(Aqshow_data_values\*(Aq                 => 1,
\&
\&    \*(Aqscale_divisions\*(Aq                  => \*(Aq\*(Aq,
\&    \*(Aqmin_scale_value\*(Aq                  => \*(Aq0\*(Aq,
\&    \*(Aqbar_gap\*(Aq                          => 1,
\&
\&    \*(Aqshow_x_labels\*(Aq                    => 1,
\&    \*(Aqstagger_x_labels\*(Aq                 => 0,
\&    \*(Aqrotate_x_labels\*(Aq                  => 0,
\&    \*(Aqshow_y_labels\*(Aq                    => 1,
\&    \*(Aqscale_integers\*(Aq                   => 0,
\&    \*(Aqshow_secondary_y_labels\*(Aq          => 1,
\&    \*(Aqy_label_formatter\*(Aq                => sub { return @_ },
\&    \*(Aqx_label_formatter\*(Aq                => sub { return @_ },
\&
\&    \*(Aqshow_path_title\*(Aq                  => 0,
\&    \*(Aqshow_title_fields\*(Aq                => 0,
\&
\&    \*(Aqshow_x_title\*(Aq                     => 0,
\&    \*(Aqx_title\*(Aq                          => \*(AqX Field names\*(Aq,
\&
\&    \*(Aqshow_y_title\*(Aq                     => 0,
\&    \*(Aqshow_secondary_y_title\*(Aq           => 0,
\&    \*(Aqy_title_text_direction\*(Aq           => \*(Aqbt\*(Aq,
\&    \*(Aqsecondary_y_title_text_direction\*(Aq => \*(Aqbt\*(Aq,
\&    \*(Aqy_title\*(Aq                          => \*(AqY Scale\*(Aq,
\&    \*(Aqsecondary_y_title\*(Aq                => \*(AqY Scale 2\*(Aq,
\&
\&    \*(Aqshow_graph_title\*(Aq                 => 0,
\&    \*(Aqgraph_title\*(Aq                      => \*(AqGraph Title\*(Aq,
\&    \*(Aqshow_graph_subtitle\*(Aq              => 0,
\&    \*(Aqgraph_subtitle\*(Aq                   => \*(AqGraph Sub Title\*(Aq,
\&
\&    \*(Aqkey\*(Aq                              => 0,
\&    \*(Aqkey_position\*(Aq                     => \*(Aqright\*(Aq,
\&
\&    # Stylesheet defaults
\&    \*(Aqstyle_sheet\*(Aq                      => \*(Aq/includes/graph.css\*(Aq, # internal stylesheet
\&    \*(Aqrandom_colors\*(Aq                    => 0,
\&  });
.Ve
.PP
The constructor takes a hash reference, fields (the names for each
field on the X axis) \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.
It can be called several times to add more data sets in,
but the likelihood is you should be using SVG::TT::Graph::Line
as it won't look great!
.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 =item \fIstyle_sheet()\fR" 4
.IX Item "style_sheet() =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 "\fIshow_data_values()\fR" 4
.IX Item "show_data_values()"
Show the value of each element of data on the graph
.IP "\fIbar_gap()\fR" 4
.IX Item "bar_gap()"
Whether to have a gap between the bars or not, default
is '1', set to '0' if you don't want gaps.
.IP "\fIshow_x_labels()\fR" 4
.IX Item "show_x_labels()"
Whether to show labels on the X axis or not, defaults
to 1, set to '0' if you want to turn them off.
.IP "\fIstagger_x_labels()\fR" 4
.IX Item "stagger_x_labels()"
This puts the labels at alternative levels so if they
are long field names they will not overlap so easily.
Default it '0', to turn on set to '1'.
.IP "\fIrotate_x_labels()\fR" 4
.IX Item "rotate_x_labels()"
This turns the X axis labels by 90 degrees.
Default it '0', to turn on set to '1'.
.IP "\fIshow_y_labels()\fR" 4
.IX Item "show_y_labels()"
Whether to show labels on the Y axis or not, defaults
to 1, set to '0' if you want to turn them off.
.IP "\fIscale_integers()\fR" 4
.IX Item "scale_integers()"
Ensures only whole numbers are used as the scale divisions.
Default it '0', to turn on set to '1'. This has no effect if
scale divisions are less than 1.
.IP "\fIshow_secondary_y_labels()\fR" 4
.IX Item "show_secondary_y_labels()"
Whether to show labels on the right hand side Y axis or not, defaults
to 1, set to '0' if you want to turn them off.
.IP "\fImin_scale_value()\fR" 4
.IX Item "min_scale_value()"
The point at which the Y axis starts, defaults to '0',
if set to '' it will default to the minimum data value.
.IP "\fIscale_divisions()\fR" 4
.IX Item "scale_divisions()"
This defines the gap between markers on the Y axis,
default is a 10th of the max_value, e.g. you will have
10 markers on the Y axis. \s-1NOTE:\s0 do not set this too
low \- you are limited to 999 markers, after that the
graph won't generate.
.IP "\fIshow_x_title()\fR" 4
.IX Item "show_x_title()"
Whether to show the title under the X axis labels,
default is 0, set to '1' to show.
.IP "\fIx_title()\fR" 4
.IX Item "x_title()"
What the title under X axis should be, e.g. 'Months'.
.IP "\fIshow_y_title()\fR" 4
.IX Item "show_y_title()"
Whether to show the title on the left hand side Y axis,
default is 0, set to '1' to show.
.IP "\fIshow_secondary_y_title()\fR" 4
.IX Item "show_secondary_y_title()"
Whether to show the title on the right hand side Y axis,
default is 0, set to '1' to show.
.IP "\fIy_title_text_direction()\fR" 4
.IX Item "y_title_text_direction()"
Aligns writing mode for Y axis label. Defaults to 'bt' (Bottom to Top).
Change to 'tb' (Top to Bottom) to reverse.
.IP "\fIsecondary_y_title_text_direction()\fR" 4
.IX Item "secondary_y_title_text_direction()"
Aligns writing mode for right hand Y axis label. Defaults to 'bt' (Bottom to Top).
Change to 'tb' (Top to Bottom) to reverse.
.IP "\fIy_title()\fR" 4
.IX Item "y_title()"
What the title under Y axis should be, e.g. 'Sales in thousands'.
.IP "\fIsecondary_y_title()\fR" 4
.IX Item "secondary_y_title()"
What the title on the right hand side Y axis should be, e.g. 'Number of deals'.
.IP "\fIshow_graph_title()\fR" 4
.IX Item "show_graph_title()"
Whether to show a title on the graph, defaults
to 0, set to '1' to show.
.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, defaults
to 0, set to '1' to show.
.IP "\fIgraph_subtitle()\fR" 4
.IX Item "graph_subtitle()"
What the subtitle on the graph should be.
.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_position()\fR" 4
.IX Item "key_position()"
Where the key should be positioned, defaults to
\&'right', set to 'bottom' if you want to move it.
.IP "x_label_formatter ()" 4
.IX Item "x_label_formatter ()"
A callback subroutine which will format a label on the x axis.  For example:
.Sp
.Vb 1
\&    $graph\->x_label_formatter( sub { return \*(Aq$\*(Aq . $_[0] } );
.Ve
.IP "\fIy_label_formatter()\fR" 4
.IX Item "y_label_formatter()"
A callback subroutine which will format a label on the y axis.  For example:
.Sp
.Vb 1
\&    $graph\->y_label_formatter( sub { return \*(Aq$\*(Aq . $_[0] } );
.Ve
.IP "\fIshow_path_title()\fR" 4
.IX Item "show_path_title()"
Whether to add the title attribute to the data path tags,
which will show \*(L"tooltips\*(R" when hovering over the bar area.
.IP "\fIshow_title_fields()\fR" 4
.IX Item "show_title_fields()"
Whether to show field values as title elements in path tag,
defaults to 0, set to '1' to turn on. Suggest on single
add_data graphs, for overlapping graphs leave off to see
the title value used in the add_data call.
.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 "SEE ALSO"
.IX Header "SEE ALSO"
SVG::TT::Graph,
SVG::TT::Graph::Line,
SVG::TT::Graph::Bar,
SVG::TT::Graph::BarHorizontal,
SVG::TT::Graph::Pie,
SVG::TT::Graph::TimeSeries,
SVG::TT::Graph::XY,
Compress::Zlib,
XML::Tidy