1Graph(3)              User Contributed Perl Documentation             Graph(3)
2
3
4

NAME

6       GD::Graph - Graph Plotting Module for Perl 5
7

SYNOPSIS

9       use GD::Graph::moduleName;
10

DESCRIPTION

12       GD::Graph is a perl5 module to create charts using the GD module.  The
13       following classes for graphs with axes are defined:
14
15       "GD::Graph::lines"
16           Create a line chart.
17
18       "GD::Graph::bars" and "GD::Graph::hbars"
19           Create a bar chart with vertical or horizontal bars.
20
21       "GD::Graph::points"
22           Create an chart, displaying the data as points.
23
24       "GD::Graph::linespoints"
25           Combination of lines and points.
26
27       "GD::Graph::area"
28           Create a graph, representing the data as areas under a line.
29
30       "GD::Graph::mixed"
31           Create a mixed type graph, any combination of the above. At the
32           moment this is fairly limited. Some of the options that can be used
33           with some of the individual graph types won't work very well. Bar
34           graphs drawn after lines or points graphs may obscure the earlier
35           data, and specifying bar_width will not produce the results you
36           probably expected.
37
38       Additional types:
39
40       "GD::Graph::pie"
41           Create a pie chart.
42

DISTRIBUTION STATUS

44       Distribution has no releases since 2007. It has new maintainer starting
45       of 1.45 and my plan is to keep modules backwards compatible as much as
46       possible, fix bugs with test cases, apply patches and release new
47       versions to the CPAN.
48
49       I got repository from Martien without Benjamin's work, Benjamin
50       couldn't find his repository, so everything else is imported from CPAN
51       and BackPAN.  Now it's all on github <https://github.com/ruz/GDGraph>.
52       May be at some point Benjamin will find his VCS backup and we can
53       restore full history.
54
55       Release 1.44_01 (development release) was released in 2007 by Benjamin,
56       but never made into production version. This dev version contains very
57       nice changes (truecolor, anti-aliasing and alpha support), but due to
58       nature of how GD and GD::Graph works authors had to add third optional
59       argument (truecolor) to all constructors in GD::Graph modules. I think
60       that this should be and can be adjusted to receive named arguments in
61       constructor and still be backwards compatible. If you were using that
62       dev release and want to fast forward inclusion of this work into
63       production release then contact ruz@cpan.org
64
65       Martien also has changes in his repository that were never published to
66       CPAN. These are smaller and well isolated, so I can merge them faster.
67
68       My goal at this moment is to merge existing versions together, get rid
69       of CVS reminders, do some repo cleanup, review existing tickets on
70       rt.cpan.org. Join if you want to help.
71

EXAMPLES

73       See the samples directory in the distribution, and read the Makefile
74       there.
75

USAGE

77       Fill an array of arrays with the x values and the values of the data
78       sets.  Make sure that every array is the same size, otherwise GD::Graph
79       will complain and refuse to compile the graph.
80
81         @data = (
82           ["1st","2nd","3rd","4th","5th","6th","7th", "8th", "9th"],
83           [    1,    2,    5,    6,    3,  1.5,    1,     3,     4],
84           [ sort { $a <=> $b } (1, 2, 5, 6, 3, 1.5, 1, 3, 4) ]
85         );
86
87       If you don't have a value for a point in a certain dataset, you can use
88       undef, and the point will be skipped.
89
90       Create a new GD::Graph object by calling the new method on the graph
91       type you want to create (chart is bars, hbars, lines, points,
92       linespoints, mixed or pie).
93
94         my $graph = GD::Graph::chart->new(400, 300);
95
96       Set the graph options.
97
98         $graph->set(
99             x_label           => 'X Label',
100             y_label           => 'Y label',
101             title             => 'Some simple graph',
102             y_max_value       => 8,
103             y_tick_number     => 8,
104             y_label_skip      => 2
105         ) or die $graph->error;
106
107       and plot the graph.
108
109         my $gd = $graph->plot(\@data) or die $graph->error;
110
111       Then do whatever your current version of GD allows you to do to save
112       the file. For versions of GD older than 1.19 (or more recent than
113       2.15), you'd do something like:
114
115         open(IMG, '>file.gif') or die $!;
116         binmode IMG;
117         print IMG $gd->gif;
118         close IMG;
119
120       and for newer versions (1.20 and up) you'd write
121
122         open(IMG, '>file.png') or die $!;
123         binmode IMG;
124         print IMG $gd->png;
125
126       or
127
128         open(IMG, '>file.gd2') or die $!;
129         binmode IMG;
130         print IMG $gd->gd2;
131
132       Then there's also of course the possibility of using a shorter version
133       (for each of the export functions that GD supports):
134
135         print IMG $graph->plot(\@data)->gif;
136         print IMG $graph->plot(\@data)->png;
137         print IMG $graph->plot(\@data)->gd;
138         print IMG $graph->plot(\@data)->gd2;
139
140       If you want to write something that doesn't require your code to 'know'
141       whether to use gif or png, you could do something like:
142
143         if ($gd->can('png')) { # blabla }
144
145       or you can use the convenience method "export_format":
146
147         my $format = $graph->export_format;
148         open(IMG, ">file.$format") or die $!;
149         binmode IMG;
150         print IMG $graph->plot(\@data)->$format();
151         close IMG;
152
153       or for CGI programs:
154
155         use CGI qw(:standard);
156         #...
157         my $format = $graph->export_format;
158         print header("image/$format");
159         binmode STDOUT;
160         print $graph->plot(\@data)->$format();
161
162       (the parentheses after $format are necessary, to help the compiler
163       decide that you mean a method name there)
164
165       See under "SEE ALSO" for references to other documentation, especially
166       the FAQ.
167

METHODS

169   Methods for all graphs
170       GD::Graph::chart->new([width,height])
171           Create a new object $graph with optional width and height.  Default
172           width = 400, default height = 300. chart is either bars, lines,
173           points, linespoints, area, mixed or pie.
174
175       $graph->set_text_clr(colour name)
176           Set the colour of the text. This will set the colour of the titles,
177           labels, and axis labels to colour name. Also see the options
178           textclr, labelclr and axislabelclr.
179
180       $graph->set_title_font(font specification)
181           Set the font that will be used for the title of the chart.  See
182           "FONTS".
183
184       $graph->plot(\@data)
185           Plot the chart, and return the GD::Image object.
186
187       $graph->set(attrib1 => value1, attrib2 => value2 ...)
188           Set chart options. See OPTIONS section.
189
190       $graph->get(attrib1, attrib2)
191           Returns a list of the values of the attributes. In scalar context
192           returns the value of the first attribute only.
193
194       $graph->gd()
195           Get the GD::Image object that is going to be used to draw on. You
196           can do this either before or after calling the plot method, to do
197           your own drawing.
198
199           Note: as of the current version, this GD::Image object will always
200           be palette-based, even if the installed version of GD supports
201           true-color images.
202
203           Note also that if you draw on the GD::Image object before calling
204           the plot method, you are responsible for making sure that the
205           background colour is correct and for setting transparency.
206
207       $graph->export_format()
208           Query the export format of the GD library in use.  In scalar
209           context, it returns 'gif', 'png' or undefined, which is sufficient
210           for most people's use. In a list context, it returns a list of all
211           the formats that are supported by the current version of GD. It can
212           be called as a class or object method
213
214       $graph->can_do_ttf()
215           Returns true if the current GD library supports TrueType fonts,
216           False otherwise. Can also be called as a class method or static
217           method.
218
219   Methods for Pie charts
220       $graph->set_label_font(font specification)
221       $graph->set_value_font(font specification)
222           Set the font that will be used for the label of the pie or the
223           values on the pie.  See "FONTS".
224
225   Methods for charts with axes.
226       $graph->set_x_label_font(font specification)
227       $graph->set_y_label_font(font specification)
228       $graph->set_x_axis_font(font specification)
229       $graph->set_y_axis_font(font specification)
230       $graph->set_values_font(font specification)
231           Set the font for the x and y axis label, the x and y axis value
232           labels, and for the values printed above the data points.  See
233           "FONTS".
234
235       $graph->get_hotspot($dataset, $point)
236           Experimental: Return a coordinate specification for a point in a
237           dataset. Returns a list. If the point is not specified, returns a
238           list of array references for all points in the dataset. If the
239           dataset is also not specified, returns a list of array references
240           for each data set.  See "HOTSPOTS".
241
242       $graph->get_feature_coordinates($feature_name)
243           Experimental: Return a coordinate specification for a certain
244           feature in the chart.  Currently, features that are defined are
245           axes, the coordinates of the rectangle within the axes; x_label,
246           y1_label and y2_label, the labels printed along the axes, with
247           y_label provided as an alias for y1_label; and title which is the
248           title text box.  See "HOTSPOTS".
249

OPTIONS

251   Options for all graphs
252       width, height
253           The width and height of the canvas in pixels Default: 400 x 300.
254           NB At the moment, these are read-only options. If you want to set
255           the size of a graph, you will have to do that with the new method.
256
257       t_margin, b_margin, l_margin, r_margin
258           Top, bottom, left and right margin of the canvas. These margins
259           will be left blank.  Default: 0 for all.
260
261       logo
262           Name of a logo file. Generally, this should be the same format as
263           your version of GD exports images in.  Currently, this file may be
264           in any format that GD can import, but please see GD if you use an
265           XPM file and get unexpected results.
266
267           Default: no logo.
268
269       logo_resize, logo_position
270           Factor to resize the logo by, and the position on the canvas of the
271           logo. Possible values for logo_position are 'LL', 'LR', 'UL', and
272           'UR'.  (lower and upper left and right).  Default: 'LR'.
273
274       transparent
275           If set to a true value, the produced image will have the background
276           colour marked as transparent (see also option bgclr).  Default: 1.
277
278       interlaced
279           If set to a true value, the produced image will be interlaced.
280           Default: 1.
281
282           Note: versions of GD higher than 2.0 (that is, since GIF support
283           was restored after being removed owing to patent issues) do not
284           support interlacing of GIF images.  Support for interlaced PNG and
285           progressive JPEG images remains available using this option.
286
287   Colours
288       bgclr, fgclr, boxclr, accentclr, shadowclr
289           Drawing colours used for the chart: background, foreground (axes
290           and grid), axis box fill colour, accents (bar, area and pie
291           outlines), and shadow (currently only for bars).
292
293           All colours should have a valid value as described in "COLOURS",
294           except boxclr, which can be undefined, in which case the box will
295           not be filled.
296
297       shadow_depth
298           Depth of a shadow, positive for right/down shadow, negative for
299           left/up shadow, 0 for no shadow (default).  Also see the
300           "shadowclr" and "bar_spacing" options.
301
302       labelclr, axislabelclr, legendclr, valuesclr, textclr
303           Text Colours used for the chart: label (labels for the axes or
304           pie), axis label (misnomer: values printed along the axes, or on a
305           pie slice), legend text, shown values text, and all other text.
306
307           All colours should have a valid value as described in "COLOURS".
308
309       dclrs (short for datacolours)
310           This controls the colours for the bars, lines, markers, or pie
311           slices.  This should be a reference to an array of colour names as
312           defined in GD::Graph::colour ("perldoc GD::Graph::colour" for the
313           names available).
314
315               $graph->set( dclrs => [ qw(green pink blue cyan) ] );
316
317           The first (fifth, ninth) data set will be green, the next pink,
318           etc.
319
320           A colour can be "undef", in which case the data set will not be
321           drawn.  This can be useful for cumulative bar sets where you want
322           certain data series (often the first one) not to show up, which can
323           be used to emulate error bars (see examples 1-7 and 6-3 in the
324           distribution).
325
326           Default: [ qw(lred lgreen lblue lyellow lpurple cyan lorange) ]
327
328       borderclrs
329           This controls the colours of the borders of the bars data sets.
330           Like dclrs, it is a reference to an array of colour names as
331           defined in GD::Graph::colour.  Setting a border colour to "undef"
332           means the border will not be drawn.
333
334       cycle_clrs
335           If set to a true value, bars will not have a colour from "dclrs"
336           per dataset, but per point. The colour sequence will be identical
337           for each dataset. Note that this may have a weird effect if you are
338           drawing more than one data set. If this is set to a value larger
339           than 1 the border colour of the bars will cycle through the colours
340           in "borderclrs".
341
342       accent_treshold
343           Not really a colour, but it does control a visual aspect: Accents
344           on bars are only drawn when the width of a bar is larger than this
345           number of pixels. Accents inside areas are only drawn when the
346           horizontal distance between points is larger than this number.
347           Default 4
348
349   Options for graphs with axes.
350       options for bars, lines, points, linespoints, mixed and area charts.
351
352       x_label, y_label
353           The labels to be printed next to, or just below, the axes. Note
354           that if you use the two_axes option that you need to use y1_label
355           and y2_label.
356
357       long_ticks, tick_length
358           If long_ticks is a true value, ticks will be drawn the same length
359           as the axes.  Otherwise ticks will be drawn with length
360           tick_length. if tick_length is negative, the ticks will be drawn
361           outside the axes.  Default: long_ticks = 0, tick_length = 4.
362
363           These attributes can also be set for x and y axes separately with
364           x_long_ticks, y_long_ticks, x_tick_length and y_tick_length.
365
366       x_ticks
367           If x_ticks is a true value, ticks will be drawn for the x axis.
368           These ticks are subject to the values of long_ticks and
369           tick_length.  Default: 1.
370
371       y_tick_number
372           Number of ticks to print for the Y axis. Use this, together with
373           y_label_skip to control the look of ticks on the y axis.  Default:
374           5.
375
376       y_number_format
377           This can be either a string, or a reference to a subroutine. If it
378           is a string, it will be taken to be the first argument to a
379           sprintf, with the value as the second argument:
380
381               $label = sprintf( $s->{y_number_format}, $value );
382
383           If it is a code reference, it will be executed with the value as
384           the argument:
385
386               $label = &{$s->{y_number_format}}($value);
387
388           This can be useful, for example, if you want to reformat your
389           values in currency, with the - sign in the right spot. Something
390           like:
391
392               sub y_format
393               {
394                   my $value = shift;
395                   my $ret;
396
397                   if ($value >= 0)
398                   {
399                       $ret = sprintf("\$%d", $value * $refit);
400                   }
401                   else
402                   {
403                       $ret = sprintf("-\$%d", abs($value) * $refit);
404                   }
405
406                   return $ret;
407               }
408
409               $graph->set( 'y_number_format' => \&y_format );
410
411           (Yes, I know this can be much shorter and more concise)
412
413           Default: undef.
414
415       y1_number_format, y2_number_format
416           As with y_number_format, these can be either a string, or a
417           reference to a subroutine. These are used as formats for graphs
418           with two y-axis scales so that independent formats can be used.
419
420           For compatibility purposes, each of these will fall back on
421           y_number_format if not specified.
422
423           Default: undef for both.
424
425       x_label_skip, y_label_skip
426           Print every x_label_skipth number under the tick on the x axis, and
427           every y_label_skipth number next to the tick on the y axis.
428           Default: 1 for both.
429
430       x_last_label_skip
431           By default, when x_label_skip is set to something higher than 1,
432           the last label on the axis will be printed, even when it doesn't
433           belong to the normal series that should be printed. Setting this to
434           a true value prevents that.
435
436           For example, when your X values are the months of the year (i.e.
437           Jan - Dec), and you set x_label_skip to 3, the months printed on
438           the axis will be Jan, Apr, Jul, Oct and Dec; even though Dec does
439           not really belong to that sequence. If you do not like the last
440           month to be printed, set x_last_label_skip to a true value.
441
442           This option has no effect in other circumstances. Also see
443           x_tick_offset for another method to make this look better.
444           Default: 0 for both
445
446       x_tick_offset
447           When x_label_skip is used, this will skip the first x_tick_offset
448           values in the labels before starting to print. Let me give an
449           example.  If you have a series of X labels like
450
451             qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec)
452
453           and you set x_label_skip to 3, you will see ticks on the X axis for
454           Jan, Apr, Jul, Oct and Dec. This is not always what is wanted. If
455           you set x_tick_offset to 1, you get Feb, May, Aug, Nov and Dec, and
456           if you set it to 2, you get Mar, Jun Sep and Dec, and this last one
457           definitely looks better. A combination of 6 and 5 also works nice
458           for months.
459
460           Note that the value for x_tick_offset is periodical. This means
461           that it will have the same effect for each integer n in
462           x_tick_offset + n * x_label_skip.
463
464           Also see x_last_label_skip for another method to influence this.
465
466       x_all_ticks
467           Force a print of all the x ticks, even if x_label_skip is set to a
468           value Default: 0.
469
470       x_label_position
471           Controls the position of the X axis label (title). The value for
472           this should be between 0 and 1, where 0 means aligned to the left,
473           1 means aligned to the right, and 1/2 means centered.  Default: 3/4
474
475       y_label_position
476           Controls the position of both Y axis labels (titles). The value for
477           this should be between 0 and 1, where 0 means aligned to the
478           bottom, 1 means aligned to the top, and 1/2 means centered.
479           Default: 1/2
480
481       x_labels_vertical
482           If set to a true value, the X axis labels will be printed
483           vertically.  This can be handy in case these labels get very long.
484           Default: 0.
485
486       x_plot_values, y_plot_values
487           If set to a true value, the values of the ticks on the x or y axes
488           will be plotted next to the tick. Also see x_label_skip,
489           y_label_skip.  Default: 1 for both.
490
491       box_axis
492           Draw the axes as a box, if true.  Default: 1.
493
494       no_axes
495           Draw no axes at all. If this is set to undef, all axes are drawn.
496           If it is set to 0, the zero axis will be drawn, for bar charts
497           only.  If this is set to a true value, no axes will be drawn at
498           all. Value labels on the axes and ticks will also not be drawn, but
499           axis lables are drawn.  Default: undef.
500
501       two_axes
502           Use two separate axes for the first and second data set. The first
503           data set will be set against the left axis, the second against the
504           right axis.  If more than two data sets are being plotted, the
505           use_axis option should be used to specify which data sets use which
506           axis.
507
508           Note that if you use this option, that you need to use y1_label and
509           y2_label, instead of just y_label, if you want the two axes to have
510           different labels. The same goes for some other options starting
511           with the letter 'y' and an underscore.
512
513           Default: 0.
514
515       use_axis
516           If two y-axes are in use and more than two datasets are specified,
517           set this option to an array reference containing a value of 1 or 2
518           (for the left and right scales respectively) for each dataset being
519           plotted.  That is, to plot three datasets with the second on a
520           different scale than the first and third, set this to "[1,2,1]".
521
522           Default: [1,2].
523
524       zero_axis
525           If set to a true value, the axis for y values of 0 will always be
526           drawn. This might be useful in case your graph contains negative
527           values, but you want it to be clear where the zero value is. (see
528           also zero_axis_only and box_axes).  Default: 0.
529
530       zero_axis_only
531           If set to a true value, the zero axis will be drawn (see
532           zero_axis), and no axis at the bottom of the graph will be drawn.
533           The labels for X values will be placed on the zero axis.  Default:
534           0.
535
536       y_max_value, y_min_value
537           Maximum and minimum value displayed on the y axis.
538
539           The range (y_min_value..y_max_value) has to include all the values
540           of the data points, or GD::Graph will die with a message.
541
542           For bar and area graphs, the range (y_min_value..y_max_value) has
543           to include 0. If it doesn't, the values will be adapted before
544           attempting to draw the graph.
545
546           Default: Computed from data sets.
547
548       y1_max_value, y1_min_value, y2_max_value, y2_min_value
549           Maximum and minimum values for left (y1) and right (y2) axes when
550           two_axes is a true value. Take precedence over y_min_value and
551           y_max_value.
552
553           By default 0 of the left axis is aligned with 0 of the right axis,
554           it's not true if any of these options is defined.
555
556           Otherwise behaviour and default values are as with y_max_value and
557           y_min_value.
558
559       y_min_range, y1_min_range, y2_min_range
560           Minimal range between min and max values on y axis that is used to
561           adjust computed y_min_value and y_max_value.
562
563           NOTE that author of the feature implemented this for two_axes case
564           only, patches are wellcome to expand over one y axis.
565
566           If two_axes is a true value, then y1_min_range and y2_min_range
567           take precedence over y_min_range value.
568
569           Default: undef
570
571       axis_space
572           This space will be left blank between the axes and the tick value
573           text.  Default: 4.
574
575       text_space
576           This space will be left open between text elements and the graph
577           (text elements are title and axis labels.
578
579           Default: 8.
580
581       cumulate
582           If this attribute is set to a true value, the data sets will be
583           cumulated. This means that they will be stacked on top of each
584           other. A side effect of this is that "overwrite" will be set to a
585           true value.
586
587           Notes: This only works for bar and area charts at the moment.
588
589           If you have negative values in your data sets, setting this option
590           might produce odd results. Of course, the graph itself would be
591           quite meaningless.
592
593       overwrite
594           If set to 0, bars of different data sets will be drawn next to each
595           other. If set to 1, they will be drawn in front of each other.
596           Default: 0.
597
598           Note: Setting overwrite to 2 to produce cumulative sets is
599           deprecated, and may disappear in future versions of GD::Graph.
600           Instead see the "cumulate" attribute.
601
602       correct_width
603           If this is set to a true value and "x_tick_number" is false, then
604           the width of the graph (or the height for rotated graphs like
605           "GD::Graph::hbar") will be recalculated to make sure that each data
606           point is exactly an integer number of pixels wide. You probably
607           never want to fiddle with this.
608
609           When this value is true, you will need to make sure that the number
610           of data points is smaller than the number of pixels in the plotting
611           area of the chart. If you get errors saying that your horizontal
612           size if too small, you may need to manually switch this off, or
613           consider using something else than a bar type for your chart.
614
615           Default: 1 for bar, calculated at runtime for mixed charts, 0 for
616           others.
617
618   Plotting data point values with the data point
619       Sometimes you will want to plot the value of a data point or bar above
620       the data point for clarity. GD::Graph allows you to control this in a
621       generic manner, or even down to the single point.
622
623       show_values
624           Set this to 1 to display the value of each data point above the
625           point or bar itself. No effort is being made to ensure that there
626           is enough space for the text.
627
628           Set this to a GD::Graph::Data object, or an array reference of the
629           same shape, with the same dimensions as your data object that you
630           pass in to the plot method. The reason for this option is that it
631           allows you to make a copy of your data set, and selectively set
632           points to "undef" to disable plotting of them.
633
634             my $data = GD::Graph::Data->new(
635               [ [ 'A', 'B', 'C' ], [ 1, 2, 3 ], [ 11, 12, 13 ] ]);
636             my $values = $data->copy;
637             $values->set_y(1, 1, undef);
638             $values->set_y(2, 0, undef);
639
640             $graph->set(show_values => $values);
641             $graph->plot($data);
642
643           Default: 0.
644
645       values_vertical
646           If set to a true value, the values will be printed vertically,
647           instead of horizontally. This can be handy if the values are long
648           numbers.  Default: 0.
649
650       values_space
651           Space to insert between the data point and the value to print.
652           Default: 4.
653
654       values_format
655           How to format the values for display. See y_number_format for more
656           information.  Default: undef.
657
658       hide_overlapping_values
659           If set to a true value, the values that goes out of graph space are
660           hidden.  Option is EXPERIMENTAL, works only for bars, text still
661           can overlap with other bars and labels, most useful only with text
662           in the same direction as bars.  Default: undef
663
664   Options for graphs with a numerical X axis
665       First of all: GD::Graph does not support numerical x axis the way it
666       should. Data for X axes should be equally spaced. That understood:
667       There is some support to make the printing of graphs with numerical X
668       axis values a bit better, thanks to Scott Prahl. If the option
669       "x_tick_number" is set to a defined value, GD::Graph will attempt to
670       treat the X data as numerical.
671
672       Extra options are:
673
674       x_tick_number
675           If set to 'auto', GD::Graph will attempt to format the X axis in a
676           nice way, based on the actual X values. If set to a number, that's
677           the number of ticks you will get. If set to undef, GD::Graph will
678           treat X data as labels.  Default: undef.
679
680       x_min_value, x_max_value
681           The minimum and maximum value to use for the X axis.  Default:
682           computed.
683
684       x_min_range
685           Minimal range of x axis.
686
687           Default: undef
688
689       x_number_format
690           See y_number_format
691
692       x_label_skip
693           See y_label_skip
694
695   Options for graphs with bars
696       bar_width
697           The width of a bar in pixels. Also see "bar_spacing".  Use
698           "bar_width" If you want to have fixed-width bars, no matter how
699           wide the chart gets.  Default: as wide as possible, within the
700           constraints of the chart size and "bar_spacing" setting.
701
702       bar_spacing
703           Number of pixels to leave open between bars. This works well in
704           most cases, but on some platforms, a value of 1 will be rounded off
705           to 0.  Use "bar_spacing" to get a fixed amount of space between
706           bars, with variable bar widths, depending on the width of the
707           chart.  Note that if "bar_width" is also set, this setting will be
708           ignored, and automatically calculated.  Default: 0
709
710       bargroup_spacing
711           Number of pixels (in addition to whatever is specified in
712           "bar_spacing") to leave between groups of bars when multiple
713           datasets are being displayed.  Unlike "bar_spacing", however, this
714           parameter will hold its value if "bar_width" is set.
715
716   Options for graphs with lines
717       line_types
718           Which line types to use for lines and linespoints graphs. This
719           should be a reference to an array of numbers:
720
721               $graph->set( line_types => [3, 2, 4] );
722
723           Available line types are 1: solid, 2: dashed, 3: dotted, 4: dot-
724           dashed.
725
726           Default: [1] (always use solid)
727
728       line_type_scale
729           Controls the length of the dashes in the line types. default: 6.
730
731       line_width
732           The width of the line used in lines and linespoints graphs, in
733           pixels.  Default: 1.
734
735       skip_undef
736           For all other axes graph types, the default behaviour is (by their
737           nature) to not draw a point when the Y value is "undef". For line
738           charts the point gets skipped as well, but the line is drawn
739           between the points n-1 to n+1 directly. If "skip_undef" has a true
740           value, there will be a gap in the chart where a Y value is
741           undefined.
742
743           Note that a line will not be drawn unless there are at least two
744           consecutive data points exist that have a defined value. The
745           following data set will only plot a very short line towards the end
746           if "skip_undef" is set:
747
748             @data = (
749               [ qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct ) ],
750               [ 1, undef, 2, undef, 3, undef, 4, undef, 5, 6 ]
751             );
752
753           This option is useful when you have a consecutive gap in your data,
754           or with linespoints charts. If you have data where you have
755           intermittent gaps, be careful when you use this.  Default value: 0
756
757   Options for graphs with points
758       markers
759           This controls the order of markers in points and linespoints
760           graphs.  This should be a reference to an array of numbers:
761
762               $graph->set( markers => [3, 5, 6] );
763
764           Available markers are: 1: filled square, 2: open square, 3:
765           horizontal cross, 4: diagonal cross, 5: filled diamond, 6: open
766           diamond, 7: filled circle, 8: open circle, 9: horizontal line, 10:
767           vertical line.  Note that the last two are not part of the default
768           list.
769
770           Default: [1,2,3,4,5,6,7,8]
771
772       marker_size
773           The size of the markers used in points and linespoints graphs, in
774           pixels.  Default: 4.
775
776   Options for mixed graphs
777       types
778           A reference to an array with graph types, in the same order as the
779           data sets. Possible values are:
780
781             $graph->set( types => [qw(lines bars points area linespoints)] );
782             $graph->set( types => ['lines', undef, undef, 'bars'] );
783
784           values that are undefined or unknown will be set to "default_type".
785
786           Default: all set to "default_type"
787
788       default_type
789           The type of graph to draw for data sets that either have no type
790           set, or that have an unknown type set.
791
792           Default: lines
793
794   Graph legends (axestype graphs only)
795       At the moment legend support is minimal.
796
797       Methods
798
799       $graph->set_legend(@legend_keys);
800           Sets the keys for the legend. The elements of @legend_keys
801           correspond to the data sets as provided to plot().
802
803           If a key is undef or an empty string, the legend entry will be
804           skipped.
805
806       $graph->set_legend_font(font name);
807           Sets the font for the legend text (see "FONTS").  Default:
808           GD::gdTinyFont.
809
810       Options
811
812       legend_placement
813           Where to put the legend. This should be a two letter key of the
814           form: 'B[LCR]|R[TCB]'. The first letter indicates the placement
815           (Bottom or Right), and the second letter the alignment (Left,
816           Right, Center, Top, or Bottom).  Default: 'BC'
817
818           If the legend is placed at the bottom, some calculations will be
819           made to ensure that there is some 'intelligent' wrapping going on.
820           if the legend is placed at the right, all entries will be placed
821           below each other.
822
823       legend_spacing
824           The number of pixels to place around a legend item, and between a
825           legend 'marker' and the text.  Default: 4
826
827       legend_marker_width, legend_marker_height
828           The width and height of a legend 'marker' in pixels.  Defaults: 12,
829           8
830
831       lg_cols
832           If you, for some reason, need to force the legend at the bottom to
833           have a specific number of columns, you can use this.  Default:
834           computed
835
836   Options for pie graphs
837       3d  If set to a true value, the pie chart will be drawn with a 3d look.
838           Default: 1.
839
840       pie_height
841           The thickness of the pie when 3d is true.  Default: 0.1 x height.
842
843       start_angle
844           The angle at which the first data slice will be displayed, with 0
845           degrees being "6 o'clock".  Default: 0.
846
847       suppress_angle
848           If a pie slice is smaller than this angle (in degrees), a label
849           will not be drawn on it. Default: 0.
850
851       label
852           Print this label below the pie. Default: undef.
853

COLOURS

855       All references to colours in the options for this module have been
856       shortened to clr. The main reason for this was that I didn't want to
857       support two spellings for the same word ('colour' and 'color')
858
859       Wherever a colour is required, a colour name should be used from the
860       package GD::Graph::colour. "perldoc GD::Graph::colour" should give you
861       the documentation for that module, containing all valid colour names. I
862       will probably change this to read the systems rgb.txt file if it is
863       available.
864

FONTS

866       Depending on your version of GD, this accepts both GD builtin fonts or
867       the name of a TrueType font file. In the case of a TrueType font, you
868       must specify the font size. See GD::Text for more details and other
869       things, since all font handling in GD::Graph is delegated to there.
870
871       Examples:
872
873           $graph->set_title_font('/fonts/arial.ttf', 18);
874           $graph->set_legend_font(gdTinyFont);
875           $graph->set_legend_font(
876               ['verdana', 'arial', gdMediumBoldFont], 12)
877
878       (The above discussion is based on GD::Text 0.65. Older versions have
879       more restrictive behaviour).
880

HOTSPOTS

882       Note that this is an experimental feature, and its interface may, and
883       likely will, change in the future. It currently does not work for area
884       charts or pie charts.
885
886       A known problem with hotspots for GD::Graph::hbars is that the x and y
887       coordinate come out transposed. This probably won't be fixed until the
888       redesign of this section
889
890       GD::Graph keeps an internal set of coordinates for each data point and
891       for certain features of a chart, like the title and axis labels. This
892       specification is very similar to the HTML image map specification, and
893       in fact exists mainly for that purpose. You can get at these hotspots
894       with the "get_hotspot" method for data point, and
895       "get_feature_coordinates" for the chart features.
896
897       The <get_hotspot> method accepts two optional arguments, the number of
898       the dataset you're interested in, and the number of the point in that
899       dataset you're interested in. When called with two arguments, the
900       method returns a list of one of the following forms:
901
902         'rect', x1, y1, x2, y2
903         'poly', x1, y1, x2, y2, x3, y3, ....
904         'line', xs, ys, xe, ye, width
905
906       The parameters for "rect" are the coordinates of the corners of the
907       rectangle, the parameters for "poly" are the coordinates of the
908       vertices of the polygon, and the parameters for the "line" are the
909       coordinates for the start and end point, and the line width.  It should
910       be possible to almost directly translate these lists into HTML image
911       map specifications.
912
913       If the second argument to "get_hotspot" is omitted, a list of
914       references to arrays will be returned. This list represents all the
915       points in the dataset specified, and each array referred to is of the
916       form outlined above.
917
918         ['rect', x1, y1, x2, y2 ], ['rect', x1, y1, x2, y2], ...
919
920       if both arguments to "get_hotspot" are omitted, the list that comes
921       back will contain references to arrays for each data set, which in turn
922       contain references to arrays for each point.
923
924         [
925           ['rect', x1, y1, x2, y2 ], ['rect', x1, y1, x2, y2], ...
926         ],
927         [
928           ['line', xs, ys, xe, ye, w], ['line', xs, ys, xe, ye, w], ...
929         ],...
930
931       The "get_feature" method, when called with the name of a feature,
932       returns a single array reference with a type and coordinates as
933       described above. When called with no arguments, a hash reference is
934       returned with the keys being all the currently defined and set
935       features, and the values array references with the type and coordinates
936       for each of those features.
937

ERROR HANDLING

939       GD::Graph objects inherit from the GD::Graph::Error class (not the
940       other way around), so they behave in the same manner. The main feature
941       of that behaviour is that you have the error() method available to get
942       some information about what went wrong. The GD::Graph methods all
943       return undef if something went wrong, so you should be able to write
944       safe programs like this:
945
946         my $graph = GD::Graph->new()    or die GD::Graph->error;
947         $graph->set( %attributes )      or die $graph->error;
948         $graph->plot($gdg_data)         or die $graph->error;
949
950       More advanced usage is possible, and there are some caveats with this
951       error handling, which are all explained in GD::Graph::Error.
952
953       Unfortunately, it is almost impossible to gracefully recover from an
954       error in GD::Graph, so you really should get rid of the object, and
955       recreate it from scratch if you want to recover. For example, to adjust
956       the correct_width attribute if you get the error "Horizontal size too
957       small" or "Vertical size too small" (in the case of hbar), you could do
958       something like:
959
960         sub plot_graph
961         {
962             my $data    = shift;
963             my %attribs = @_;
964             my $graph   = GD::Graph::bars->new()
965                or die GD::Graph->error;
966             $graph->set(%attribs)     or die $graph->error;
967             $graph->plot($data)       or die $graph->error;
968         }
969
970         my $gd;
971         eval { $gd = plot_graph(\@data, %attribs) };
972         if ($@)
973         {
974             die $@ unless $@ =~ /size too small/;
975             $gd = plot_graph(\@data, %attribs, correct_width => 0);
976         }
977
978       Of course, you could also adjust the width this way, and you can check
979       for other errors.
980

NOTES

982       As with all Modules for Perl: Please stick to using the interface. If
983       you try to fiddle too much with knowledge of the internals of this
984       module, you could get burned. I may change them at any time.
985

BUGS

987       GD::Graph objects cannot be reused. To create a new plot, you have to
988       create a new GD::Graph object.
989
990       Rotated charts (ones with the X axis on the left) can currently only be
991       created for bars. With a little work, this will work for all others as
992       well. Please, be patient :)
993
994       Other outstanding bugs can (alas) probably be found in the RT queue for
995       this distribution, at
996       http://rt.cpan.org/Public/Dist/Display.html?Name=GDGraph
997
998       If you think you have found a bug, please check first to see if it has
999       already been reported.  If it has not, please do (you can use the web
1000       interface above or send e-mail to <bug-GDGraph@rt.cpan.org>).  Bug
1001       reports should contain as many as possible of the following:
1002
1003       •   a concise description of the buggy behavior and how it differs from
1004           what you expected,
1005
1006       •   the versions of Perl, GD::Graph and GD that you are using,
1007
1008       •   a short demonstration script that shows the bug in action,
1009
1010       •   a patch that fixes it. :-)
1011
1012       Of all of these, the third is probably the single most important, since
1013       producing a test case generally makes the explanation much more concise
1014       and understandable, as well as making it much simpler to show that the
1015       bug has been fixed.  As an incidental benefit, if the bug is in fact
1016       caused by some code outside of GD::Graph, it will become apparent while
1017       you are writing the test case, thereby saving time and confusion for
1018       all concerned.
1019

AUTHOR

1021       Martien Verbruggen <mgjv@tradingpost.com.au>
1022
1023       Current maintenance (including this release) by Benjamin Warfield
1024       <bwarfield@cpan.org>
1025
1026   Copyright
1027        GIFgraph: Copyright (c) 1995-1999 Martien Verbruggen.
1028        Chart::PNGgraph: Copyright (c) 1999 Steve Bonds.
1029        GD::Graph: Copyright (c) 1999 Martien Verbruggen.
1030
1031       All rights reserved. This package is free software; you can
1032       redistribute it and/or modify it under the same terms as Perl itself.
1033
1034   Acknowledgements
1035       Thanks to Steve Bonds for releasing Chart::PNGgraph, and keeping the
1036       code alive when GD reached version 1.20, and I didn't have time to do
1037       something about it.
1038
1039       Thanks to the following people for contributing code, or sending me
1040       fixes: Dave Belcher, Steve Bonds, Mike Bremford, Damon Brodie, Gary
1041       Deschaines, brian d foy, Edwin Hildebrand, Ari Jolma, Tim Meadowcroft,
1042       Honza Pazdziora, Scott Prahl, Ben Tilly, Vegard Vesterheim, Jeremy
1043       Wadsack.
1044
1045       And some people whose real name I don't know, and whose email address
1046       I'd rather not publicise without their consent.
1047

SEE ALSO

1049       GD::Graph::FAQ, GD::Graph::Data, GD::Graph::Error, GD::Graph::colour
1050
1051
1052
1053perl v5.34.0                      2022-02-01                          Graph(3)
Impressum