Debian Codegraph @

lib/Chart/Manual/Methods.pod

raw
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