| 1 |
|
| 2 |
=encoding UTF-8 |
| 3 |
|
| 4 |
=head1 NAME |
| 5 |
|
| 6 |
Chart::Manual::Methods - user API |
| 7 |
|
| 8 |
=head1 OVERVIEW |
| 9 |
|
| 10 |
This are all methods for the chart user. |
| 11 |
|
| 12 |
=head1 ALPHABETICALLY |
| 13 |
|
| 14 |
=head2 add_datafile |
| 15 |
|
| 16 |
Loads all data of a chart (one or more data sets) from a file. |
| 17 |
(Works only if no data yet added.) You have to either provide a filename |
| 18 |
or filehandle (OLD_SCHOOL or $scalar). |
| 19 |
|
| 20 |
$graph->add_dataset( 'file.tsv' ); |
| 21 |
$graph->add_dataset( $file_handle ); |
| 22 |
$graph->add_dataset( FILE_HANDLE ); |
| 23 |
|
| 24 |
An optional second argument, which defaults to C<'set'> can change the |
| 25 |
file format if set to C<'pt'>. In C<'set'> mode every row of the |
| 26 |
file content is fed to L</add_dataset>, in C<'pt'> every row get loaded |
| 27 |
like via L</add_pt>. In other words: C<'pt'> transposes the data table. |
| 28 |
|
| 29 |
$graph->add_dataset( 'file.tsv', 'pt' ); |
| 30 |
|
| 31 |
The arbitrary named text files have to contain one or several rows of numbers. |
| 32 |
The numbers need to be separated by spaces or tabs (\t) (mixing allowed). |
| 33 |
Perl style comments or empty lines will be ignored, but rows containing |
| 34 |
different amount of numbers will cause problems. |
| 35 |
|
| 36 |
=head2 add_dataset |
| 37 |
|
| 38 |
Adding a list of values as one data set. That is one row in the overall |
| 39 |
data table. The first data set are usually x-axis labels (domain set). |
| 40 |
Make sure all sets have the same length. |
| 41 |
|
| 42 |
$graph->add_dataset( 1, 2, 3, ... ); |
| 43 |
$graph->add_dataset( [1, 2, 3, ...] ); |
| 44 |
|
| 45 |
For instances with L<Points|Chart::Manual::Types/Points>, |
| 46 |
L<Lines|Chart::Manual::Types/Lines> or |
| 47 |
L<Bars|Chart::Manual::Types/Bars> one data set is represented by a set |
| 48 |
of graphic items (points, bars or line) of one color. |
| 49 |
|
| 50 |
=head2 add_pt |
| 51 |
|
| 52 |
Adds (appends) to each already existing data set one value. That is |
| 53 |
a column in the overall data table. In this example it adds to set 0 |
| 54 |
the value 3, to set 1 the 6 and so forth. Make sure that the list lengths |
| 55 |
matches the number of already existing data sets. |
| 56 |
|
| 57 |
$graph->add_pt( 3, 6, 9, ... ); |
| 58 |
$graph->add_pt( [3, 6, 9, ...] ); |
| 59 |
|
| 60 |
=head2 cgi_jpeg |
| 61 |
|
| 62 |
Creates same JPEG image as L</jpeg>, but outputs to STDOUT. Since no file |
| 63 |
name or handle needed, only the optional data argument is acceptable. |
| 64 |
|
| 65 |
$graph->cgi_jpeg( ); |
| 66 |
|
| 67 |
my @data = ([1, 2, 3], # data set 0 |
| 68 |
[3, 4, 5]); # data set 1 |
| 69 |
$graph->cgi_jpeg( \@data ); |
| 70 |
|
| 71 |
=head2 cgi_png |
| 72 |
|
| 73 |
Creates same PNG image as L</png>, but outputs to STDOUT. Since no file |
| 74 |
name or handle needed, only the optional data argument is acceptable. |
| 75 |
|
| 76 |
$graph->cgi_png( ); |
| 77 |
|
| 78 |
my $data = [[1, 2, 3], # data set 0 |
| 79 |
[3, 4, 5] ]; # data set 1 |
| 80 |
$graph->cgi_png( $data ); |
| 81 |
|
| 82 |
=head2 clear_data |
| 83 |
|
| 84 |
Needs no arguments and deletes all so far added data. |
| 85 |
|
| 86 |
=head2 get_data |
| 87 |
|
| 88 |
Return all data (array of arrays) given to a graph. |
| 89 |
|
| 90 |
=head2 imagemap_dump |
| 91 |
|
| 92 |
When creating a chart for web purposes by L</cgi_jpeg> or L</cgi_png>, |
| 93 |
you maybe want the information, where the areas of interests in the |
| 94 |
image are located, that should react to a users click. (HTML tag map). |
| 95 |
These areas are bounding boxes around the drawn bars or points. |
| 96 |
You will get per box the values: x1, y1, x2, y2 in one array. |
| 97 |
These arrays are again in an Array holding, all boxes from one data set. |
| 98 |
The highest level array again holds all arrays of all data sets, |
| 99 |
beginning with index C<1>. |
| 100 |
|
| 101 |
This method can only be called, if the functionality is activated by |
| 102 |
setting the property: L<imagemap|Chart::Manual::Properties/imagemap> to C<'true'>. |
| 103 |
|
| 104 |
$graph->set( imagemap => 'true'); |
| 105 |
my $image_map = $graph->imagemap_dump(); |
| 106 |
|
| 107 |
say "coordinates of first bar, first data set:"; |
| 108 |
say for @{$image_map->[1][0]}; |
| 109 |
|
| 110 |
=head2 jpeg |
| 111 |
|
| 112 |
Creates an JPEG image from given data and properties. Accepts a file name |
| 113 |
or a file handle (raw or in a SCALAR). The method closes the file handle. |
| 114 |
|
| 115 |
$graph->jpeg( 'image.jpg' ); |
| 116 |
$graph->jpeg( $file_handle ); |
| 117 |
$graph->jpeg( FILE_HANDLE ); |
| 118 |
|
| 119 |
$graph->jpeg( 'image.jpg', $data ); |
| 120 |
$graph->jpeg( 'image.jpg', 'data_file.tsv' ); |
| 121 |
$graph->jpeg( 'image.jpg', $file_handle ); |
| 122 |
$graph->jpeg( 'image.jpg', FILE_HANDLE ); |
| 123 |
|
| 124 |
The second, optional argument is the data in form of an array of arrays |
| 125 |
reference. This only works, if there is no data already given to the object. |
| 126 |
Alternatively the data can also be loaded from a file, just provide |
| 127 |
the filename or filehandle (modern in SCALAR or old school). |
| 128 |
Read more about the file format at L</add_datafile> and note that |
| 129 |
this method has another option for loading transposed data tables. |
| 130 |
|
| 131 |
=head2 new |
| 132 |
|
| 133 |
Creates a new chart object. Takes two optional arguments, |
| 134 |
which are the width and height of the to be produced image in pixels. |
| 135 |
Defaults for that are 400 x 300. |
| 136 |
|
| 137 |
my $graph = Chart::Bars->new ( ); |
| 138 |
my $graph = Chart::Bars->new (600, 700); |
| 139 |
|
| 140 |
Instead of Bars, you can also use: Composite, Direction, ErrorBars, |
| 141 |
HorizontalBars, Lines, LinesPoints, Mountain, Pareto, Pie, Points, Split |
| 142 |
and StackedBars. To know more about them read L<Chart::Manual::Types>. |
| 143 |
|
| 144 |
=head2 png |
| 145 |
|
| 146 |
Creates an PNG image from given data and properties. Accepts a file name |
| 147 |
or a file handle (raw or in a SCALAR). The method closes the file handle. |
| 148 |
|
| 149 |
$graph->png( 'image.png' ); |
| 150 |
$graph->png( $file_handle ); |
| 151 |
$graph->png( FILE_HANDLE ); |
| 152 |
|
| 153 |
$graph->png( 'image.png', $data ); |
| 154 |
$graph->png( 'image.png', 'data_file.tsv' ); |
| 155 |
$graph->png( 'image.png', $file_handle ); |
| 156 |
$graph->png( 'image.png', FILE_HANDLE ); |
| 157 |
|
| 158 |
|
| 159 |
The second, optional argument is the data in form of an array of arrays |
| 160 |
reference. This only works, if there is no data already given to the object. |
| 161 |
Alternatively the data can also be loaded from a file, just provide |
| 162 |
the filename or filehandle (modern in SCALAR or old school). |
| 163 |
Read more about the file format at L</add_datafile> and note that |
| 164 |
this method has another option for loading transposed data tables. |
| 165 |
|
| 166 |
=head2 scalar_jpeg |
| 167 |
|
| 168 |
Creates same JPEG image as L</jpeg> but returns the image binary into a |
| 169 |
variable, not to STDOUT or a file. |
| 170 |
|
| 171 |
my $image_binary = $graph->scalar_jpeg(); |
| 172 |
my $image_binary = $graph->scalar_jpeg( $data ); |
| 173 |
|
| 174 |
=head2 scalar_png |
| 175 |
|
| 176 |
Creates same PNG image as L</png> but returns the image binary into a |
| 177 |
variable, not to STDOUT or a file. |
| 178 |
|
| 179 |
my $image_binary = $graph->scalar_png(); |
| 180 |
my $image_binary = $graph->scalar_png( $data ); |
| 181 |
|
| 182 |
=head2 set |
| 183 |
|
| 184 |
Method to change one or more chart properties in hash form. |
| 185 |
|
| 186 |
$chart->set ( property_name => 'new value', ... ); |
| 187 |
$chart->set ( %properties ); |
| 188 |
|
| 189 |
Different chart types react to different properties, which are all listed |
| 190 |
and explained under L<Chart::Manual::Properties>. |
| 191 |
|
| 192 |
|
| 193 |
=head1 COPYRIGHT & LICENSE |
| 194 |
|
| 195 |
Copyright 2022 Herbert Breunung. |
| 196 |
|
| 197 |
This program is free software; you can redistribute it and/or modify it |
| 198 |
under same terms as Perl itself. |
| 199 |
|
| 200 |
=head1 AUTHOR |
| 201 |
|
| 202 |
Herbert Breunung, <[email protected]> |
| 203 |
|
| 204 |
=cut |
| 205 |
|