1Graph(3) User Contributed Perl Documentation Graph(3)
2
6 GD::Graph - Graph Plotting Module for Perl 5
7
9 use GD::Graph::moduleName;
10
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 "GD::Graph::lines"
16 Create a line chart.
17 "GD::Graph::bars" and "GD::Graph::hbars"
19 Create a bar chart with vertical or horizontal bars.
20 "GD::Graph::points"
22 Create an chart, displaying the data as points.
23 "GD::Graph::linespoints"
25 Combination of lines and points.
26 "GD::Graph::area"
28 Create a graph, representing the data as areas under a line.
29 "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 Additional types:
39 "GD::Graph::pie"
41 Create a pie chart.
42
44 See the samples directory in the distribution, and read the Makefile
45 there.
46
48 Fill an array of arrays with the x values and the values of the data
49 sets. Make sure that every array is the same size, otherwise GD::Graph
50 will complain and refuse to compile the graph.
51 @data = (
53 ["1st","2nd","3rd","4th","5th","6th","7th", "8th", "9th"],
54 [ 1, 2, 5, 6, 3, 1.5, 1, 3, 4],
55 [ sort { $a <=> $b } (1, 2, 5, 6, 3, 1.5, 1, 3, 4) ]
56 );
57 If you don't have a value for a point in a certain dataset, you can use
59 undef, and the point will be skipped.
60 Create a new GD::Graph object by calling the new method on the graph
62 type you want to create (chart is bars, hbars, lines, points, lines‐
63 points, mixed or pie).
64 my $graph = GD::Graph::chart->new(400, 300);
66 Set the graph options.
68 $graph->set(
70 x_label => 'X Label',
71 y_label => 'Y label',
72 title => 'Some simple graph',
73 y_max_value => 8,
74 y_tick_number => 8,
75 y_label_skip => 2
76 ) or die $graph->error;
77 and plot the graph.
79 my $gd = $graph->plot(\@data) or die $graph->error;
81 Then do whatever your current version of GD allows you to do to save
83 the file. For versions of GD older than 1.19 (or more recent than
84 2.15), you'd do something like:
85 open(IMG, '>file.gif') or die $!;
87 binmode IMG;
88 print IMG $gd->gif;
89 close IMG;
90 and for newer versions (1.20 and up) you'd write
92 open(IMG, '>file.png') or die $!;
94 binmode IMG;
95 print IMG $gd->png;
96 or
98 open(IMG, '>file.gd2') or die $!;
100 binmode IMG;
101 print IMG $gd->gd2;
102 Then there's also of course the possibility of using a shorter version
104 (for each of the export functions that GD supports):
105 print IMG $graph->plot(\@data)->gif;
107 print IMG $graph->plot(\@data)->png;
108 print IMG $graph->plot(\@data)->gd;
109 print IMG $graph->plot(\@data)->gd2;
110 If you want to write something that doesn't require your code to 'know'
112 whether to use gif or png, you could do something like:
113 if ($gd->can('png')) { # blabla }
115 or you can use the convenience method "export_format":
117 my $format = $graph->export_format;
119 open(IMG, ">file.$format") or die $!;
120 binmode IMG;
121 print IMG $graph->plot(\@data)->$format();
122 close IMG;
123 or for CGI programs:
125 use CGI qw(:standard);
127 #...
128 my $format = $graph->export_format;
129 print header("image/$format");
130 binmode STDOUT;
131 print $graph->plot(\@data)->$format();
132 (the parentheses after $format are necessary, to help the compiler
134 decide that you mean a method name there)
135 See under "SEE ALSO" for references to other documentation, especially
137 the FAQ.
138
140 Methods for all graphs
141 GD::Graph::chart->new([width,height])
143 Create a new object $graph with optional width and heigth. Default
144 width = 400, default height = 300. chart is either bars, lines,
145 points, linespoints, area, mixed or pie.
146 $graph->set_text_clr(colour name)
148 Set the colour of the text. This will set the colour of the titles,
149 labels, and axis labels to colour name. Also see the options
150 textclr, labelclr and axislabelclr.
151 $graph->set_title_font(font specification)
153 Set the font that will be used for the title of the chart. See
154 "FONTS".
155 $graph->plot(\@data)
157 Plot the chart, and return the GD::Image object.
158 $graph->set(attrib1 => value1, attrib2 => value2 ...)
160 Set chart options. See OPTIONS section.
161 $graph->get(attrib1, attrib2)
163 Returns a list of the values of the attributes. In scalar context
164 returns the value of the first attribute only.
165 $graph->gd()
167 Get the GD::Image object that is going to be used to draw on. You
168 can do this either before or after calling the plot method, to do
169 your own drawing.
170 Note: as of the current version, this GD::Image object will always
172 be palette-based, even if the installed version of GD supports
173 true-color images.
174 Note also that if you draw on the GD::Image object before calling
176 the plot method, you are responsible for making sure that the back‐
177 ground colour is correct and for setting transparency.
178 $graph->export_format()
180 Query the export format of the GD library in use. In scalar con‐
181 text, it returns 'gif', 'png' or undefined, which is sufficient for
182 most people's use. In a list context, it returns a list of all the
183 formats that are supported by the current version of GD. It can be
184 called as a class or object method
185 $graph->can_do_ttf()
187 Returns true if the current GD library supports TrueType fonts,
188 False otherwise. Can also be called as a class method or static
189 method.
190 Methods for Pie charts
192 $graph->set_label_font(font specification)
194 $graph->set_value_font(font specification)
195 Set the font that will be used for the label of the pie or the val‐
196 ues on the pie. See "FONTS".
197 Methods for charts with axes.
199 $graph->set_x_label_font(font specification)
201 $graph->set_y_label_font(font specification)
202 $graph->set_x_axis_font(font specification)
203 $graph->set_y_axis_font(font specification)
204 $graph->set_values_font(font specification)
205 Set the font for the x and y axis label, the x and y axis value
206 labels, and for the values printed above the data points. See
207 "FONTS".
208 $graph->get_hotspot($dataset, $point)
210 Experimental: Return a coordinate specification for a point in a
211 dataset. Returns a list. If the point is not specified, returns a
212 list of array references for all points in the dataset. If the
213 dataset is also not specified, returns a list of array references
214 for each data set. See "HOTSPOTS".
215 $graph->get_feature_coordinates($feature_name)
217 Experimental: Return a coordinate specification for a certain fea‐
218 ture in the chart. Currently, features that are defined are axes,
219 the coordinates of the rectangle within the axes; x_label, y1_label
220 and y2_label, the labels printed along the axes, with y_label pro‐
221 vided as an alias for y1_label; and title which is the title text
222 box. See "HOTSPOTS".
223
225 Options for all graphs
226 width, height
228 The width and height of the canvas in pixels Default: 400 x 300.
229 NB At the moment, these are read-only options. If you want to set
230 the size of a graph, you will have to do that with the new method.
231 t_margin, b_margin, l_margin, r_margin
233 Top, bottom, left and right margin of the canvas. These margins
234 will be left blank. Default: 0 for all.
235 logo
237 Name of a logo file. Generally, this should be the same format as
238 your version of GD exports images in. Currently, this file may be
239 in any format that GD can import, but please see GD if you use an
240 XPM file and get unexpected results.
241 Default: no logo.
243 logo_resize, logo_position
245 Factor to resize the logo by, and the position on the canvas of the
246 logo. Possible values for logo_position are 'LL', 'LR', 'UL', and
247 'UR'. (lower and upper left and right). Default: 'LR'.
248 transparent
250 If set to a true value, the produced image will have the background
251 colour marked as transparent (see also option bgclr). Default: 1.
252 interlaced
254 If set to a true value, the produced image will be interlaced.
255 Default: 1.
256 Note: versions of GD higher than 2.0 (that is, since GIF support
258 was restored after being removed owing to patent issues) do not
259 support interlacing of GIF images. Support for interlaced PNG and
260 progressive JPEG images remains available using this option.
261 Colours
263 bgclr, fgclr, boxclr, accentclr, shadowclr
265 Drawing colours used for the chart: background, foreground (axes
266 and grid), axis box fill colour, accents (bar, area and pie out‐
267 lines), and shadow (currently only for bars).
268 All colours should have a valid value as described in "COLOURS",
270 except boxclr, which can be undefined, in which case the box will
271 not be filled.
272 shadow_depth
274 Depth of a shadow, positive for right/down shadow, negative for
275 left/up shadow, 0 for no shadow (default). Also see the "shadow‐
276 clr" and "bar_spacing" options.
277 labelclr, axislabelclr, legendclr, valuesclr, textclr
279 Text Colours used for the chart: label (labels for the axes or
280 pie), axis label (misnomer: values printed along the axes, or on a
281 pie slice), legend text, shown values text, and all other text.
282 All colours should have a valid value as described in "COLOURS".
284 dclrs (short for datacolours)
286 This controls the colours for the bars, lines, markers, or pie
287 slices. This should be a reference to an array of colour names as
288 defined in GD::Graph::colour ("perldoc GD::Graph::colour" for the
289 names available).
290 $graph->set( dclrs => [ qw(green pink blue cyan) ] );
292 The first (fifth, ninth) data set will be green, the next pink,
294 etc.
295 A colour can be "undef", in which case the data set will not be
297 drawn. This can be useful for cumulative bar sets where you want
298 certain data series (often the first one) not to show up, which can
299 be used to emulate error bars (see examples 1-7 and 6-3 in the dis‐
300 tribution).
301 Default: [ qw(lred lgreen lblue lyellow lpurple cyan lorange) ]
303 borderclrs
305 This controls the colours of the borders of the bars data sets.
306 Like dclrs, it is a reference to an array of colour names as
307 defined in GD::Graph::colour. Setting a border colour to "undef"
308 means the border will not be drawn.
309 cycle_clrs
311 If set to a true value, bars will not have a colour from "dclrs"
312 per dataset, but per point. The colour sequence will be identical
313 for each dataset. Note that this may have a weird effect if you are
314 drawing more than one data set. If this is set to a value larger
315 than 1 the border colour of the bars will cycle through the colours
316 in "borderclrs".
317 accent_treshold
319 Not really a colour, but it does control a visual aspect: Accents
320 on bars are only drawn when the width of a bar is larger than this
321 number of pixels. Accents inside areas are only drawn when the hor‐
322 izontal distance between points is larger than this number.
323 Default 4
324 Options for graphs with axes.
326 options for bars, lines, points, linespoints, mixed and area charts.
328 x_label, y_label
330 The labels to be printed next to, or just below, the axes. Note
331 that if you use the two_axes option that you need to use y1_label
332 and y2_label.
333 long_ticks, tick_length
335 If long_ticks is a true value, ticks will be drawn the same length
336 as the axes. Otherwise ticks will be drawn with length
337 tick_length. if tick_length is negative, the ticks will be drawn
338 outside the axes. Default: long_ticks = 0, tick_length = 4.
339 These attributes can also be set for x and y axes separately with
341 x_long_ticks, y_long_ticks, x_tick_length and y_tick_length.
342 x_ticks
344 If x_ticks is a true value, ticks will be drawm for the x axis.
345 These ticks are subject to the values of long_ticks and
346 tick_length. Default: 1.
347 y_tick_number
349 Number of ticks to print for the Y axis. Use this, together with
350 y_label_skip to control the look of ticks on the y axis. Default:
351 5.
352 y_number_format
354 This can be either a string, or a reference to a subroutine. If it
355 is a string, it will be taken to be the first argument to a
356 sprintf, with the value as the second argument:
357 $label = sprintf( $s->{y_number_format}, $value );
359 If it is a code reference, it will be executed with the value as
361 the argument:
362 $label = &{$s->{y_number_format}}($value);
364 This can be useful, for example, if you want to reformat your val‐
366 ues in currency, with the - sign in the right spot. Something like:
367 sub y_format
369 {
370 my $value = shift;
371 my $ret;
372 if ($value >= 0)
374 {
375 $ret = sprintf("\$%d", $value * $refit);
376 }
377 else
378 {
379 $ret = sprintf("-\$%d", abs($value) * $refit);
380 }
381 return $ret;
383 }
384 $graph->set( 'y_number_format' => \&y_format );
386 (Yes, I know this can be much shorter and more concise)
388 Default: undef.
390 y1_number_format, y2_number_format
392 As with y_number_format, these can be either a string, or a refer‐
393 ence to a subroutine. These are used as formats for graphs with two
394 y-axis scales so that independent formats can be used.
395 For compatibility purposes, each of these will fall back on y_num‐
397 ber_format if not specified.
398 Default: undef for both.
400 x_label_skip, y_label_skip
402 Print every x_label_skipth number under the tick on the x axis, and
403 every y_label_skipth number next to the tick on the y axis.
404 Default: 1 for both.
405 x_tick_offset
407 When x_label_skip is used, this will skip the first x_tick_offset
408 values in the labels before starting to print. Let me give an exam‐
409 ple. If you have a series of X labels like
410 qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec)
412 and you set x_label_skip to 3, you will see ticks on the X axis for
414 Jan, Apr, Jul, Oct and Dec. This is not always what is wanted. If
415 you set x_tick_offset to 1, you get Feb, May, Aug, Nov and Dec, and
416 if you set it to 2, you get Mar, Jun Sep and Dec, and this last one
417 definitely looks better. A combination of 6 and 5 also works nice
418 for months.
419 Note that the value for x_tick_offset is periodical. This means
421 that it will have the same effect for each nteger n in x_tick_off‐
422 set + n * x_label_skip.
423 x_all_ticks
425 Force a print of all the x ticks, even if x_label_skip is set to a
426 value Default: 0.
427 x_label_position
429 Controls the position of the X axis label (title). The value for
430 this should be between 0 and 1, where 0 means aligned to the left,
431 1 means aligned to the right, and 1/2 means centered. Default: 3/4
432 y_label_position
434 Controls the position of both Y axis labels (titles). The value for
435 this should be between 0 and 1, where 0 means aligned to the bot‐
436 tom, 1 means aligned to the top, and 1/2 means centered. Default:
437 1/2
438 x_labels_vertical
440 If set to a true value, the X axis labels will be printed verti‐
441 cally. This can be handy in case these labels get very long.
442 Default: 0.
443 x_plot_values, y_plot_values
445 If set to a true value, the values of the ticks on the x or y axes
446 will be plotted next to the tick. Also see x_label_skip,
447 y_label_skip. Default: 1 for both.
448 box_axis
450 Draw the axes as a box, if true. Default: 1.
451 no_axes
453 Draw no axes at all. If this is set to undef, all axes are drawn.
454 If it is set to 0, the zero axis will be drawn, for bar charts
455 only. If this is set to a true value, no axes will be drawns at
456 all. Value labels on the axes and ticks will also not be drawn, but
457 axis lables are drawn. Default: undef.
458 two_axes
460 Use two separate axes for the first and second data set. The first
461 data set will be set against the left axis, the second against the
462 right axis. If more than two data sets are being plotted, the
463 use_axis option should be used to specify which data sets use which
464 axis.
465 Note that if you use this option, that you need to use y1_label and
467 y2_label, instead of just y_label, if you want the two axes to have
468 different labels. The same goes for some other options starting
469 with the letter 'y' and an underscore.
470 Default: 0.
472 use_axis
474 If two y-axes are in use and more than two datasets are specified,
475 set this option to an array reference containing a value of 1 or 2
476 (for the left and right scales respectively) for each dataset being
477 plotted. That is, to plot three datasets with the second on a dif‐
478 ferent scale than the first and third, set this to "[1,2,1]".
479 Default: [1,2].
481 zero_axis
483 If set to a true value, the axis for y values of 0 will always be
484 drawn. This might be useful in case your graph contains negative
485 values, but you want it to be clear where the zero value is. (see
486 also zero_axis_only and box_axes). Default: 0.
487 zero_axis_only
489 If set to a true value, the zero axis will be drawn (see
490 zero_axis), and no axis at the bottom of the graph will be drawn.
491 The labels for X values will be placed on the zero exis. Default:
492 0.
493 y_max_value, y_min_value
495 Maximum and minimum value displayed on the y axis. If two_axes is a
496 true value, then y1_min_value, y1_max_value (for the left axis),
497 and y2_min_value, y2_max_value (for the right axis) take precedence
498 over these.
499 The range (y_min_value..y_max_value) has to include all the values
501 of the data points, or GD::Graph will die with a message.
502 For bar and area graphs, the range (y_min_value..y_max_value) has
504 to include 0. If it doesn't, the values will be adapted before
505 attempting to draw the graph.
506 Default: Computed from data sets.
508 axis_space
510 This space will be left blank between the axes and the tick value
511 text. Default: 4.
512 text_space
514 This space will be left open between text elements and the graph
515 (text elements are title and axis labels.
516 Default: 8.
518 cumulate
520 If this attribute is set to a true value, the data sets will be
521 cumulated. This means that they will be stacked on top of each
522 other. A side effect of this is that "overwrite" will be set to a
523 true value.
524 Notes: This only works for bar and area charts at the moment.
526 If you have negative values in your data sets, setting this option
528 might produce odd results. Of course, the graph itself would be
529 quite meaningless.
530 overwrite
532 If set to 0, bars of different data sets will be drawn next to each
533 other. If set to 1, they will be drawn in front of each other.
534 Default: 0.
535 Note: Setting overwrite to 2 to produce cumulative sets is depre‐
537 cated, and may disappear in future versions of GD::Graph. Instead
538 see the "cumulate" attribute.
539 correct_width
541 If this is set to a true value and "x_tick_number" is false, then
542 the width of the graph (or the height for rotated graphs like
543 "GD::Graph::hbar") will be recalculated to make sure that each data
544 point is exactly an integer number of pixels wide. You probably
545 never want to fiddle with this.
546 When this value is true, you will need to make sure that the number
548 of data points is smaller than the number of pixels in the plotting
549 area of the chart. If you get errors saying that your horizontal
550 size if too small, you may need to manually switch this off, or
551 consider using something else than a bar type for your chart.
552 Default: 1 for bar, calculated at runtime for mixed charts, 0 for
554 others.
555 Plotting data point values with the data point
557 Sometimes you will want to plot the value of a data point or bar above
559 the data point for clarity. GD::Graph allows you to control this in a
560 generic manner, or even down to the single point.
561 show_values
563 Set this to 1 to display the value of each data point above the
564 point or bar itself. No effort is being made to ensure that there
565 is enough space for the text.
566 Set this to a GD::Graph::Data object, or an array reference of the
568 same shape, with the same dimensions as your data object that you
569 pass in to the plot method. The reason for this option is that it
570 allows you to make a copy of your data set, and selectively set
571 points to "undef" to disable plotting of them.
572 my $data = GD::Graph::Data->new(
574 [ [ 'A', 'B', 'C' ], [ 1, 2, 3 ], [ 11, 12, 13 ] ]);
575 my $values = $data->copy;
576 $values->set_y(1, 1, undef);
577 $values->set_y(2, 0, undef);
578 $graph->set(show_values => $values);
580 $graph->plot($data);
581 Default: 0.
583 values_vertical
585 If set to a true value, the values will be printed vertically,
586 instead of horizontally. This can be handy if the values are long
587 numbers. Default: 0.
588 values_space
590 Space to insert between the data point and the value to print.
591 Default: 4.
592 values_format
594 How to format the values for display. See y_number_format for more
595 information. Default: undef.
596 Options for graphs with a numerical X axis
598 First of all: GD::Graph does not support numerical x axis the way it
600 should. Data for X axes should be equally spaced. That understood:
601 There is some support to make the printing of graphs with numerical X
602 axis values a bit better, thanks to Scott Prahl. If the option
603 "x_tick_number" is set to a defined value, GD::Graph will attempt to
604 treat the X data as numerical.
605 Extra options are:
607 x_tick_number
609 If set to 'auto', GD::Graph will attempt to format the X axis in a
610 nice way, based on the actual X values. If set to a number, that's
611 the number of ticks you will get. If set to undef, GD::Graph will
612 treat X data as labels. Default: undef.
613 x_min_value, x_max_value
615 The minimum and maximum value to use for the X axis. Default: com‐
616 puted.
617 x_number_format
619 See y_number_format
620 x_label_skip
622 See y_label_skip
623 Options for graphs with bars
625 bar_width
627 The width of a bar in pixels. Also see "bar_spacing". Use
628 "bar_width" If you want to have fixed-width bars, no matter how
629 wide the chart gets. Default: as wide as possible, within the con‐
630 straints of the chart size and "bar_spacing" setting.
631 bar_spacing
633 Number of pixels to leave open between bars. This works well in
634 most cases, but on some platforms, a value of 1 will be rounded off
635 to 0. Use "bar_spacing" to get a fixed amount of space between
636 bars, with variable bar widths, depending on the width of the
637 chart. Note that if "bar_width" is also set, this setting will be
638 ignored, and automatically calculated. Default: 0
639 bargroup_spacing
641 Number of pixels (in addition to whatever is specified in
642 "bar_spacing") to leave between groups of bars when multiple
643 datasets are being displayed. Unlike "bar_spacing", however, this
644 parameter will hold its value if "bar_width" is set.
645 Options for graphs with lines
647 line_types
649 Which line types to use for lines and linespoints graphs. This
650 should be a reference to an array of numbers:
651 $graph->set( line_types => [3, 2, 4] );
653 Available line types are 1: solid, 2: dashed, 3: dotted, 4:
655 dot-dashed.
656 Default: [1] (always use solid)
658 line_type_scale
660 Controls the length of the dashes in the line types. default: 6.
661 line_width
663 The width of the line used in lines and linespoints graphs, in pix‐
664 els. Default: 1.
665 skip_undef
667 For all other axes graph types, the default behaviour is (by their
668 nature) to not draw a point when the Y value is "undef". For line
669 charts the point gets skipped as well, but the line is drawn
670 between the points n-1 to n+1 directly. If "skip_undef" has a true
671 value, there will be a gap in the chart where a Y value is unde‐
672 fined.
673 Note that a line will not be drawn unless there are at least two
675 consecutive data points exist that have a defined value. The fol‐
676 lowing data set will only plot a very short line towards the end if
677 "skip_undef" is set:
678 @data = (
680 [ qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct ) ],
681 [ 1, undef, 2, undef, 3, undef, 4, undef, 5, 6 ]
682 );
683 This option is useful when you have a consecutive gap in your data,
685 or with linespoints charts. If you have data where you have inter‐
686 mittent gaps, be careful when you use this. Default value: 0
687 Options for graphs with points
689 markers
691 This controls the order of markers in points and linespoints
692 graphs. This should be a reference to an array of numbers:
693 $graph->set( markers => [3, 5, 6] );
695 Available markers are: 1: filled square, 2: open square, 3: hori‐
697 zontal cross, 4: diagonal cross, 5: filled diamond, 6: open dia‐
698 mond, 7: filled circle, 8: open circle, 9: horizontal line, 10:
699 vertical line. Note that the last two are not part of the default
700 list.
701 Default: [1,2,3,4,5,6,7,8]
703 marker_size
705 The size of the markers used in points and linespoints graphs, in
706 pixels. Default: 4.
707 Options for mixed graphs
709 types
711 A reference to an array with graph types, in the same order as the
712 data sets. Possible values are:
713 $graph->set( types => [qw(lines bars points area linespoints)] );
715 $graph->set( types => ['lines', undef, undef, 'bars'] );
716 values that are undefined or unknown will be set to "default_type".
718 Default: all set to "default_type"
720 default_type
722 The type of graph to draw for data sets that either have no type
723 set, or that have an unknown type set.
724 Default: lines
726 Graph legends (axestype graphs only)
728 At the moment legend support is minimal.
730 Methods
732 $graph->set_legend(@legend_keys);
734 Sets the keys for the legend. The elements of @legend_keys corre‐
735 spond to the data sets as provided to plot().
736 If a key is undef or an empty string, the legend entry will be
738 skipped.
739 $graph->set_legend_font(font name);
741 Sets the font for the legend text (see "FONTS"). Default:
742 GD::gdTinyFont.
743 Options
745 legend_placement
747 Where to put the legend. This should be a two letter key of the
748 form: 'B[LCR]⎪R[TCB]'. The first letter indicates the placement
749 (Bottom or Right), and the second letter the alignment (Left,
750 Right, Center, Top, or Bottom). Default: 'BC'
751 If the legend is placed at the bottom, some calculations will be
753 made to ensure that there is some 'intelligent' wrapping going on.
754 if the legend is placed at the right, all entries will be placed
755 below each other.
756 legend_spacing
758 The number of pixels to place around a legend item, and between a
759 legend 'marker' and the text. Default: 4
760 legend_marker_width, legend_marker_height
762 The width and height of a legend 'marker' in pixels. Defaults: 12,
763 8
764 lg_cols
766 If you, for some reason, need to force the legend at the bottom to
767 have a specific number of columns, you can use this. Default: com‐
768 puted
769 Options for pie graphs
771 3d If set to a true value, the pie chart will be drawn with a 3d look.
773 Default: 1.
774 pie_height
776 The thickness of the pie when 3d is true. Default: 0.1 x height.
777 start_angle
779 The angle at which the first data slice will be displayed, with 0
780 degrees being "6 o'clock". Default: 0.
781 suppress_angle
783 If a pie slice is smaller than this angle (in degrees), a label
784 will not be drawn on it. Default: 0.
785 label
787 Print this label below the pie. Default: undef.
788
790 All references to colours in the options for this module have been
791 shortened to clr. The main reason for this was that I didn't want to
792 support two spellings for the same word ('colour' and 'color')
793 Wherever a colour is required, a colour name should be used from the
795 package GD::Graph::colour. "perldoc GD::Graph::colour" should give you
796 the documentation for that module, containing all valid colour names. I
797 will probably change this to read the systems rgb.txt file if it is
798 available.
799
801 Depending on your version of GD, this accepts both GD builtin fonts or
802 the name of a TrueType font file. In the case of a TrueType font, you
803 must specify the font size. See GD::Text for more details and other
804 things, since all font handling in GD::Graph is delegated to there.
805 Examples:
807 $graph->set_title_font('/fonts/arial.ttf', 18);
809 $graph->set_legend_font(gdTinyFont);
810 $graph->set_legend_font(
811 ['verdana', 'arial', gdMediumBoldFont], 12)
812 (The above discussion is based on GD::Text 0.65. Older versions have
814 more restrictive behaviour).
815
817 Note that this is an experimental feature, and its interface may, and
818 likely will, change in the future. It currently does not work for area
819 charts or pie charts.
820 GD::Graph keeps an internal set of coordinates for each data point and
822 for certain features of a chart, like the title and axis labels. This
823 specification is very similar to the HTML image map specification, and
824 in fact exists mainly for that purpose. You can get at these hotspots
825 with the "get_hotspot" method for data point, and "get_feature_coordi‐
826 nates" for the chart features.
827 The <get_hotspot> method accepts two optional arguments, the number of
829 the dataset you're interested in, and the number of the point in that
830 dataset you're interested in. When called with two arguments, the
831 method returns a list of one of the following forms:
832 'rect', x1, y1, x2, y2
834 'poly', x1, y1, x2, y2, x3, y3, ....
835 'line', xs, ys, xe, ye, width
836 The parameters for "rect" are the coordinates of the corners of the
838 rectangle, the parameters for "poly" are the coordinates of the ver‐
839 tices of the polygon, and the parameters for the "line" are the coordi‐
840 nates for the start and end point, and the line width. It should be
841 possible to almost directly translate these lists into HTML image map
842 specifications.
843 If the second argument to "get_hotspot" is omitted, a list of refer‐
845 ences to arrays will be returned. This list represents all the points
846 in the dataset specified, and each array referred to is of the form
847 outlined above.
848 ['rect', x1, y1, x2, y2 ], ['rect', x1, y1, x2, y2], ...
850 if both arguments to "get_hotspot" are omitted, the list that comes
852 back will contain references to arrays for each data set, which in turn
853 contain references to arrays for each point.
854 [
856 ['rect', x1, y1, x2, y2 ], ['rect', x1, y1, x2, y2], ...
857 ],
858 [
859 ['line', xs, ys, xe, ye, w], ['line', xs, ys, xe, ye, w], ...
860 ],...
861 The "get_feature" method, when called with the name of a feature,
863 returns a single array reference with a type and coordinates as
864 described above. When called with no arguments, a hash reference is
865 returned with the keys being all the currently defined and set fea‐
866 tures, and the values array references with the type and coordinates
867 for each of those features.
868
870 GD::Graph objects inherit from the GD::Graph::Error class (not the
871 other way around), so they behave in the same manner. The main feature
872 of that behaviour is that you have the error() method available to get
873 some information about what went wrong. The GD::Graph methods all
874 return undef if something went wrong, so you should be able to write
875 safe programs like this:
876 my $graph = GD::Graph->new() or die GD::Graph->error;
878 $graph->set( %attributes ) or die $graph->error;
879 $graph->plot($gdg_data) or die $graph->error;
880 More advanced usage is possible, and there are some caveats with this
882 error handling, which are all explained in GD::Graph::Error.
883 Unfortunately, it is almost impossible to gracefully recover from an
885 error in GD::Graph, so you really should get rid of the object, and
886 recreate it from scratch if you want to recover. For example, to adjust
887 the correct_width attribute if you get the error "Horizontal size too
888 small" or "Vertical size too small" (in the case of hbar), you could do
889 something like:
890 sub plot_graph
892 {
893 my $data = shift;
894 my %attribs = @_;
895 my $graph = GD::Graph::bars->new()
896 or die GD::Graph->error;
897 $graph->set(%attribs) or die $graph->error;
898 $graph->plot($data) or die $graph->error;
899 }
900 my $gd;
902 eval { $gd = plot_graph(\@data, %attribs) };
903 if ($@)
904 {
905 die $@ unless $@ =~ /size too small/;
906 $gd = plot_graph(\@data, %attribs, correct_width => 0);
907 }
908 Of course, you could also adjust the width this way, and you can check
910 for other errors.
911
913 As with all Modules for Perl: Please stick to using the interface. If
914 you try to fiddle too much with knowledge of the internals of this mod‐
915 ule, you could get burned. I may change them at any time.
916
918 GD::Graph objects cannot be reused. To create a new plot, you have to
919 create a new GD::Graph object.
920 Rotated charts (ones with the X axis on the left) can currently only be
922 created for bars. With a little work, this will work for all others as
923 well. Please, be patient :)
924 Other outstanding bugs can (alas) probably be found in the RT queue for
926 this distribution, at http://rt.cpan.org/Public/Dist/Dis‐
927 play.html?Name=GDGraph
928 If you think you have found a bug, please check first to see if it has
930 already been reported. If it has not, please do (you can use the web
931 interface above or send e-mail to <bug-GDGraph@rt.cpan.org>). Bug
932 reports should contain as many as possible of the following:
933 · a concise description of the buggy behavior and how it differs from
935 what you expected,
936 · the versions of Perl, GD::Graph and GD that you are using,
938 · a short demonstration script that shows the bug in action,
940 · a patch that fixes it. :-)
942 Of all of these, the third is probably the single most important, since
944 producing a test case generally makes the explanation much more concise
945 and understandable, as well as making it much simpler to show that the
946 bug has been fixed. As an incidental benefit, if the bug is in fact
947 caused by some code outside of GD::Graph, it will become apparent while
948 you are writing the test case, thereby saving time and confusion for
949 all concerned.
950
952 Martien Verbruggen <mgjv@tradingpost.com.au>
953 Current maintenance (including this release) by Benjamin Warfield
955 <bwarfield@cpan.org>
956 Copyright
958 GIFgraph: Copyright (c) 1995-1999 Martien Verbruggen.
960 Chart::PNGgraph: Copyright (c) 1999 Steve Bonds.
961 GD::Graph: Copyright (c) 1999 Martien Verbruggen.
962 All rights reserved. This package is free software; you can redis‐
964 tribute it and/or modify it under the same terms as Perl itself.
965 Acknowledgements
967 Thanks to Steve Bonds for releasing Chart::PNGgraph, and keeping the
969 code alive when GD reached version 1.20, and I didn't have time to do
970 something about it.
971 Thanks to the following people for contributing code, or sending me
973 fixes: Dave Belcher, Steve Bonds, Mike Bremford, Damon Brodie, Gary
974 Deschaines, brian d foy, Edwin Hildebrand, Ari Jolma, Tim Meadowcroft,
975 Honza Pazdziora, Scott Prahl, Ben Tilly, Vegard Vesterheim, Jeremy Wad‐
976 sack.
977 And some people whose real name I don't know, and whose email address
979 I'd rather not publicise without their consent.
980
982 GD::Graph::FAQ, GD::Graph::Data, GD::Graph::Error, GD::Graph::colour
983perl v5.8.8 2005-12-13 Graph(3)