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,
63 linespoints, 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])
142 Create a new object $graph with optional width and heigth. Default
143 width = 400, default height = 300. chart is either bars, lines,
144 points, linespoints, area, mixed or pie.
145 $graph->set_text_clr(colour name)
147 Set the colour of the text. This will set the colour of the titles,
148 labels, and axis labels to colour name. Also see the options
149 textclr, labelclr and axislabelclr.
150 $graph->set_title_font(font specification)
152 Set the font that will be used for the title of the chart. See
153 "FONTS".
154 $graph->plot(\@data)
156 Plot the chart, and return the GD::Image object.
157 $graph->set(attrib1 => value1, attrib2 => value2 ...)
159 Set chart options. See OPTIONS section.
160 $graph->get(attrib1, attrib2)
162 Returns a list of the values of the attributes. In scalar context
163 returns the value of the first attribute only.
164 $graph->gd()
166 Get the GD::Image object that is going to be used to draw on. You
167 can do this either before or after calling the plot method, to do
168 your own drawing.
169 Note: as of the current version, this GD::Image object will always
171 be palette-based, even if the installed version of GD supports
172 true-color images.
173 Note also that if you draw on the GD::Image object before calling
175 the plot method, you are responsible for making sure that the
176 background colour is correct and for setting transparency.
177 $graph->export_format()
179 Query the export format of the GD library in use. In scalar
180 context, it returns 'gif', 'png' or undefined, which is sufficient
181 for most people's use. In a list context, it returns a list of all
182 the formats that are supported by the current version of GD. It can
183 be called as a class or object method
184 $graph->can_do_ttf()
186 Returns true if the current GD library supports TrueType fonts,
187 False otherwise. Can also be called as a class method or static
188 method.
189 Methods for Pie charts
191 $graph->set_label_font(font specification)
192 $graph->set_value_font(font specification)
193 Set the font that will be used for the label of the pie or the
194 values on the pie. See "FONTS".
195 Methods for charts with axes.
197 $graph->set_x_label_font(font specification)
198 $graph->set_y_label_font(font specification)
199 $graph->set_x_axis_font(font specification)
200 $graph->set_y_axis_font(font specification)
201 $graph->set_values_font(font specification)
202 Set the font for the x and y axis label, the x and y axis value
203 labels, and for the values printed above the data points. See
204 "FONTS".
205 $graph->get_hotspot($dataset, $point)
207 Experimental: Return a coordinate specification for a point in a
208 dataset. Returns a list. If the point is not specified, returns a
209 list of array references for all points in the dataset. If the
210 dataset is also not specified, returns a list of array references
211 for each data set. See "HOTSPOTS".
212 $graph->get_feature_coordinates($feature_name)
214 Experimental: Return a coordinate specification for a certain
215 feature in the chart. Currently, features that are defined are
216 axes, the coordinates of the rectangle within the axes; x_label,
217 y1_label and y2_label, the labels printed along the axes, with
218 y_label provided as an alias for y1_label; and title which is the
219 title text box. See "HOTSPOTS".
220
222 Options for all graphs
223 width, height
224 The width and height of the canvas in pixels Default: 400 x 300.
225 NB At the moment, these are read-only options. If you want to set
226 the size of a graph, you will have to do that with the new method.
227 t_margin, b_margin, l_margin, r_margin
229 Top, bottom, left and right margin of the canvas. These margins
230 will be left blank. Default: 0 for all.
231 logo
233 Name of a logo file. Generally, this should be the same format as
234 your version of GD exports images in. Currently, this file may be
235 in any format that GD can import, but please see GD if you use an
236 XPM file and get unexpected results.
237 Default: no logo.
239 logo_resize, logo_position
241 Factor to resize the logo by, and the position on the canvas of the
242 logo. Possible values for logo_position are 'LL', 'LR', 'UL', and
243 'UR'. (lower and upper left and right). Default: 'LR'.
244 transparent
246 If set to a true value, the produced image will have the background
247 colour marked as transparent (see also option bgclr). Default: 1.
248 interlaced
250 If set to a true value, the produced image will be interlaced.
251 Default: 1.
252 Note: versions of GD higher than 2.0 (that is, since GIF support
254 was restored after being removed owing to patent issues) do not
255 support interlacing of GIF images. Support for interlaced PNG and
256 progressive JPEG images remains available using this option.
257 Colours
259 bgclr, fgclr, boxclr, accentclr, shadowclr
260 Drawing colours used for the chart: background, foreground (axes
261 and grid), axis box fill colour, accents (bar, area and pie
262 outlines), and shadow (currently only for bars).
263 All colours should have a valid value as described in "COLOURS",
265 except boxclr, which can be undefined, in which case the box will
266 not be filled.
267 shadow_depth
269 Depth of a shadow, positive for right/down shadow, negative for
270 left/up shadow, 0 for no shadow (default). Also see the
271 "shadowclr" and "bar_spacing" options.
272 labelclr, axislabelclr, legendclr, valuesclr, textclr
274 Text Colours used for the chart: label (labels for the axes or
275 pie), axis label (misnomer: values printed along the axes, or on a
276 pie slice), legend text, shown values text, and all other text.
277 All colours should have a valid value as described in "COLOURS".
279 dclrs (short for datacolours)
281 This controls the colours for the bars, lines, markers, or pie
282 slices. This should be a reference to an array of colour names as
283 defined in GD::Graph::colour ("perldoc GD::Graph::colour" for the
284 names available).
285 $graph->set( dclrs => [ qw(green pink blue cyan) ] );
287 The first (fifth, ninth) data set will be green, the next pink,
289 etc.
290 A colour can be "undef", in which case the data set will not be
292 drawn. This can be useful for cumulative bar sets where you want
293 certain data series (often the first one) not to show up, which can
294 be used to emulate error bars (see examples 1-7 and 6-3 in the
295 distribution).
296 Default: [ qw(lred lgreen lblue lyellow lpurple cyan lorange) ]
298 borderclrs
300 This controls the colours of the borders of the bars data sets.
301 Like dclrs, it is a reference to an array of colour names as
302 defined in GD::Graph::colour. Setting a border colour to "undef"
303 means the border will not be drawn.
304 cycle_clrs
306 If set to a true value, bars will not have a colour from "dclrs"
307 per dataset, but per point. The colour sequence will be identical
308 for each dataset. Note that this may have a weird effect if you are
309 drawing more than one data set. If this is set to a value larger
310 than 1 the border colour of the bars will cycle through the colours
311 in "borderclrs".
312 accent_treshold
314 Not really a colour, but it does control a visual aspect: Accents
315 on bars are only drawn when the width of a bar is larger than this
316 number of pixels. Accents inside areas are only drawn when the
317 horizontal distance between points is larger than this number.
318 Default 4
319 Options for graphs with axes.
321 options for bars, lines, points, linespoints, mixed and area charts.
322 x_label, y_label
324 The labels to be printed next to, or just below, the axes. Note
325 that if you use the two_axes option that you need to use y1_label
326 and y2_label.
327 long_ticks, tick_length
329 If long_ticks is a true value, ticks will be drawn the same length
330 as the axes. Otherwise ticks will be drawn with length
331 tick_length. if tick_length is negative, the ticks will be drawn
332 outside the axes. Default: long_ticks = 0, tick_length = 4.
333 These attributes can also be set for x and y axes separately with
335 x_long_ticks, y_long_ticks, x_tick_length and y_tick_length.
336 x_ticks
338 If x_ticks is a true value, ticks will be drawm for the x axis.
339 These ticks are subject to the values of long_ticks and
340 tick_length. Default: 1.
341 y_tick_number
343 Number of ticks to print for the Y axis. Use this, together with
344 y_label_skip to control the look of ticks on the y axis. Default:
345 5.
346 y_number_format
348 This can be either a string, or a reference to a subroutine. If it
349 is a string, it will be taken to be the first argument to a
350 sprintf, with the value as the second argument:
351 $label = sprintf( $s->{y_number_format}, $value );
353 If it is a code reference, it will be executed with the value as
355 the argument:
356 $label = &{$s->{y_number_format}}($value);
358 This can be useful, for example, if you want to reformat your
360 values in currency, with the - sign in the right spot. Something
361 like:
362 sub y_format
364 {
365 my $value = shift;
366 my $ret;
367 if ($value >= 0)
369 {
370 $ret = sprintf("\$%d", $value * $refit);
371 }
372 else
373 {
374 $ret = sprintf("-\$%d", abs($value) * $refit);
375 }
376 return $ret;
378 }
379 $graph->set( 'y_number_format' => \&y_format );
381 (Yes, I know this can be much shorter and more concise)
383 Default: undef.
385 y1_number_format, y2_number_format
387 As with y_number_format, these can be either a string, or a
388 reference to a subroutine. These are used as formats for graphs
389 with two y-axis scales so that independent formats can be used.
390 For compatibility purposes, each of these will fall back on
392 y_number_format if not specified.
393 Default: undef for both.
395 x_label_skip, y_label_skip
397 Print every x_label_skipth number under the tick on the x axis, and
398 every y_label_skipth number next to the tick on the y axis.
399 Default: 1 for both.
400 x_tick_offset
402 When x_label_skip is used, this will skip the first x_tick_offset
403 values in the labels before starting to print. Let me give an
404 example. If you have a series of X labels like
405 qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec)
407 and you set x_label_skip to 3, you will see ticks on the X axis for
409 Jan, Apr, Jul, Oct and Dec. This is not always what is wanted. If
410 you set x_tick_offset to 1, you get Feb, May, Aug, Nov and Dec, and
411 if you set it to 2, you get Mar, Jun Sep and Dec, and this last one
412 definitely looks better. A combination of 6 and 5 also works nice
413 for months.
414 Note that the value for x_tick_offset is periodical. This means
416 that it will have the same effect for each nteger n in
417 x_tick_offset + n * x_label_skip.
418 x_all_ticks
420 Force a print of all the x ticks, even if x_label_skip is set to a
421 value Default: 0.
422 x_label_position
424 Controls the position of the X axis label (title). The value for
425 this should be between 0 and 1, where 0 means aligned to the left,
426 1 means aligned to the right, and 1/2 means centered. Default: 3/4
427 y_label_position
429 Controls the position of both Y axis labels (titles). The value for
430 this should be between 0 and 1, where 0 means aligned to the
431 bottom, 1 means aligned to the top, and 1/2 means centered.
432 Default: 1/2
433 x_labels_vertical
435 If set to a true value, the X axis labels will be printed
436 vertically. This can be handy in case these labels get very long.
437 Default: 0.
438 x_plot_values, y_plot_values
440 If set to a true value, the values of the ticks on the x or y axes
441 will be plotted next to the tick. Also see x_label_skip,
442 y_label_skip. Default: 1 for both.
443 box_axis
445 Draw the axes as a box, if true. Default: 1.
446 no_axes
448 Draw no axes at all. If this is set to undef, all axes are drawn.
449 If it is set to 0, the zero axis will be drawn, for bar charts
450 only. If this is set to a true value, no axes will be drawns at
451 all. Value labels on the axes and ticks will also not be drawn, but
452 axis lables are drawn. Default: undef.
453 two_axes
455 Use two separate axes for the first and second data set. The first
456 data set will be set against the left axis, the second against the
457 right axis. If more than two data sets are being plotted, the
458 use_axis option should be used to specify which data sets use which
459 axis.
460 Note that if you use this option, that you need to use y1_label and
462 y2_label, instead of just y_label, if you want the two axes to have
463 different labels. The same goes for some other options starting
464 with the letter 'y' and an underscore.
465 Default: 0.
467 use_axis
469 If two y-axes are in use and more than two datasets are specified,
470 set this option to an array reference containing a value of 1 or 2
471 (for the left and right scales respectively) for each dataset being
472 plotted. That is, to plot three datasets with the second on a
473 different scale than the first and third, set this to "[1,2,1]".
474 Default: [1,2].
476 zero_axis
478 If set to a true value, the axis for y values of 0 will always be
479 drawn. This might be useful in case your graph contains negative
480 values, but you want it to be clear where the zero value is. (see
481 also zero_axis_only and box_axes). Default: 0.
482 zero_axis_only
484 If set to a true value, the zero axis will be drawn (see
485 zero_axis), and no axis at the bottom of the graph will be drawn.
486 The labels for X values will be placed on the zero exis. Default:
487 0.
488 y_max_value, y_min_value
490 Maximum and minimum value displayed on the y axis. If two_axes is a
491 true value, then y1_min_value, y1_max_value (for the left axis),
492 and y2_min_value, y2_max_value (for the right axis) take precedence
493 over these.
494 The range (y_min_value..y_max_value) has to include all the values
496 of the data points, or GD::Graph will die with a message.
497 For bar and area graphs, the range (y_min_value..y_max_value) has
499 to include 0. If it doesn't, the values will be adapted before
500 attempting to draw the graph.
501 Default: Computed from data sets.
503 axis_space
505 This space will be left blank between the axes and the tick value
506 text. Default: 4.
507 text_space
509 This space will be left open between text elements and the graph
510 (text elements are title and axis labels.
511 Default: 8.
513 cumulate
515 If this attribute is set to a true value, the data sets will be
516 cumulated. This means that they will be stacked on top of each
517 other. A side effect of this is that "overwrite" will be set to a
518 true value.
519 Notes: This only works for bar and area charts at the moment.
521 If you have negative values in your data sets, setting this option
523 might produce odd results. Of course, the graph itself would be
524 quite meaningless.
525 overwrite
527 If set to 0, bars of different data sets will be drawn next to each
528 other. If set to 1, they will be drawn in front of each other.
529 Default: 0.
530 Note: Setting overwrite to 2 to produce cumulative sets is
532 deprecated, and may disappear in future versions of GD::Graph.
533 Instead see the "cumulate" attribute.
534 correct_width
536 If this is set to a true value and "x_tick_number" is false, then
537 the width of the graph (or the height for rotated graphs like
538 "GD::Graph::hbar") will be recalculated to make sure that each data
539 point is exactly an integer number of pixels wide. You probably
540 never want to fiddle with this.
541 When this value is true, you will need to make sure that the number
543 of data points is smaller than the number of pixels in the plotting
544 area of the chart. If you get errors saying that your horizontal
545 size if too small, you may need to manually switch this off, or
546 consider using something else than a bar type for your chart.
547 Default: 1 for bar, calculated at runtime for mixed charts, 0 for
549 others.
550 Plotting data point values with the data point
552 Sometimes you will want to plot the value of a data point or bar above
553 the data point for clarity. GD::Graph allows you to control this in a
554 generic manner, or even down to the single point.
555 show_values
557 Set this to 1 to display the value of each data point above the
558 point or bar itself. No effort is being made to ensure that there
559 is enough space for the text.
560 Set this to a GD::Graph::Data object, or an array reference of the
562 same shape, with the same dimensions as your data object that you
563 pass in to the plot method. The reason for this option is that it
564 allows you to make a copy of your data set, and selectively set
565 points to "undef" to disable plotting of them.
566 my $data = GD::Graph::Data->new(
568 [ [ 'A', 'B', 'C' ], [ 1, 2, 3 ], [ 11, 12, 13 ] ]);
569 my $values = $data->copy;
570 $values->set_y(1, 1, undef);
571 $values->set_y(2, 0, undef);
572 $graph->set(show_values => $values);
574 $graph->plot($data);
575 Default: 0.
577 values_vertical
579 If set to a true value, the values will be printed vertically,
580 instead of horizontally. This can be handy if the values are long
581 numbers. Default: 0.
582 values_space
584 Space to insert between the data point and the value to print.
585 Default: 4.
586 values_format
588 How to format the values for display. See y_number_format for more
589 information. Default: undef.
590 Options for graphs with a numerical X axis
592 First of all: GD::Graph does not support numerical x axis the way it
593 should. Data for X axes should be equally spaced. That understood:
594 There is some support to make the printing of graphs with numerical X
595 axis values a bit better, thanks to Scott Prahl. If the option
596 "x_tick_number" is set to a defined value, GD::Graph will attempt to
597 treat the X data as numerical.
598 Extra options are:
600 x_tick_number
602 If set to 'auto', GD::Graph will attempt to format the X axis in a
603 nice way, based on the actual X values. If set to a number, that's
604 the number of ticks you will get. If set to undef, GD::Graph will
605 treat X data as labels. Default: undef.
606 x_min_value, x_max_value
608 The minimum and maximum value to use for the X axis. Default:
609 computed.
610 x_number_format
612 See y_number_format
613 x_label_skip
615 See y_label_skip
616 Options for graphs with bars
618 bar_width
619 The width of a bar in pixels. Also see "bar_spacing". Use
620 "bar_width" If you want to have fixed-width bars, no matter how
621 wide the chart gets. Default: as wide as possible, within the
622 constraints of the chart size and "bar_spacing" setting.
623 bar_spacing
625 Number of pixels to leave open between bars. This works well in
626 most cases, but on some platforms, a value of 1 will be rounded off
627 to 0. Use "bar_spacing" to get a fixed amount of space between
628 bars, with variable bar widths, depending on the width of the
629 chart. Note that if "bar_width" is also set, this setting will be
630 ignored, and automatically calculated. Default: 0
631 bargroup_spacing
633 Number of pixels (in addition to whatever is specified in
634 "bar_spacing") to leave between groups of bars when multiple
635 datasets are being displayed. Unlike "bar_spacing", however, this
636 parameter will hold its value if "bar_width" is set.
637 Options for graphs with lines
639 line_types
640 Which line types to use for lines and linespoints graphs. This
641 should be a reference to an array of numbers:
642 $graph->set( line_types => [3, 2, 4] );
644 Available line types are 1: solid, 2: dashed, 3: dotted, 4: dot-
646 dashed.
647 Default: [1] (always use solid)
649 line_type_scale
651 Controls the length of the dashes in the line types. default: 6.
652 line_width
654 The width of the line used in lines and linespoints graphs, in
655 pixels. Default: 1.
656 skip_undef
658 For all other axes graph types, the default behaviour is (by their
659 nature) to not draw a point when the Y value is "undef". For line
660 charts the point gets skipped as well, but the line is drawn
661 between the points n-1 to n+1 directly. If "skip_undef" has a true
662 value, there will be a gap in the chart where a Y value is
663 undefined.
664 Note that a line will not be drawn unless there are at least two
666 consecutive data points exist that have a defined value. The
667 following data set will only plot a very short line towards the end
668 if "skip_undef" is set:
669 @data = (
671 [ qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct ) ],
672 [ 1, undef, 2, undef, 3, undef, 4, undef, 5, 6 ]
673 );
674 This option is useful when you have a consecutive gap in your data,
676 or with linespoints charts. If you have data where you have
677 intermittent gaps, be careful when you use this. Default value: 0
678 Options for graphs with points
680 markers
681 This controls the order of markers in points and linespoints
682 graphs. This should be a reference to an array of numbers:
683 $graph->set( markers => [3, 5, 6] );
685 Available markers are: 1: filled square, 2: open square, 3:
687 horizontal cross, 4: diagonal cross, 5: filled diamond, 6: open
688 diamond, 7: filled circle, 8: open circle, 9: horizontal line, 10:
689 vertical line. Note that the last two are not part of the default
690 list.
691 Default: [1,2,3,4,5,6,7,8]
693 marker_size
695 The size of the markers used in points and linespoints graphs, in
696 pixels. Default: 4.
697 Options for mixed graphs
699 types
700 A reference to an array with graph types, in the same order as the
701 data sets. Possible values are:
702 $graph->set( types => [qw(lines bars points area linespoints)] );
704 $graph->set( types => ['lines', undef, undef, 'bars'] );
705 values that are undefined or unknown will be set to "default_type".
707 Default: all set to "default_type"
709 default_type
711 The type of graph to draw for data sets that either have no type
712 set, or that have an unknown type set.
713 Default: lines
715 Graph legends (axestype graphs only)
717 At the moment legend support is minimal.
718 Methods
720 $graph->set_legend(@legend_keys);
722 Sets the keys for the legend. The elements of @legend_keys
723 correspond to the data sets as provided to plot().
724 If a key is undef or an empty string, the legend entry will be
726 skipped.
727 $graph->set_legend_font(font name);
729 Sets the font for the legend text (see "FONTS"). Default:
730 GD::gdTinyFont.
731 Options
733 legend_placement
735 Where to put the legend. This should be a two letter key of the
736 form: 'B[LCR]|R[TCB]'. The first letter indicates the placement
737 (Bottom or Right), and the second letter the alignment (Left,
738 Right, Center, Top, or Bottom). Default: 'BC'
739 If the legend is placed at the bottom, some calculations will be
741 made to ensure that there is some 'intelligent' wrapping going on.
742 if the legend is placed at the right, all entries will be placed
743 below each other.
744 legend_spacing
746 The number of pixels to place around a legend item, and between a
747 legend 'marker' and the text. Default: 4
748 legend_marker_width, legend_marker_height
750 The width and height of a legend 'marker' in pixels. Defaults: 12,
751 8
752 lg_cols
754 If you, for some reason, need to force the legend at the bottom to
755 have a specific number of columns, you can use this. Default:
756 computed
757 Options for pie graphs
759 3d If set to a true value, the pie chart will be drawn with a 3d look.
760 Default: 1.
761 pie_height
763 The thickness of the pie when 3d is true. Default: 0.1 x height.
764 start_angle
766 The angle at which the first data slice will be displayed, with 0
767 degrees being "6 o'clock". Default: 0.
768 suppress_angle
770 If a pie slice is smaller than this angle (in degrees), a label
771 will not be drawn on it. Default: 0.
772 label
774 Print this label below the pie. Default: undef.
775
777 All references to colours in the options for this module have been
778 shortened to clr. The main reason for this was that I didn't want to
779 support two spellings for the same word ('colour' and 'color')
780 Wherever a colour is required, a colour name should be used from the
782 package GD::Graph::colour. "perldoc GD::Graph::colour" should give you
783 the documentation for that module, containing all valid colour names. I
784 will probably change this to read the systems rgb.txt file if it is
785 available.
786
788 Depending on your version of GD, this accepts both GD builtin fonts or
789 the name of a TrueType font file. In the case of a TrueType font, you
790 must specify the font size. See GD::Text for more details and other
791 things, since all font handling in GD::Graph is delegated to there.
792 Examples:
794 $graph->set_title_font('/fonts/arial.ttf', 18);
796 $graph->set_legend_font(gdTinyFont);
797 $graph->set_legend_font(
798 ['verdana', 'arial', gdMediumBoldFont], 12)
799 (The above discussion is based on GD::Text 0.65. Older versions have
801 more restrictive behaviour).
802
804 Note that this is an experimental feature, and its interface may, and
805 likely will, change in the future. It currently does not work for area
806 charts or pie charts.
807 GD::Graph keeps an internal set of coordinates for each data point and
809 for certain features of a chart, like the title and axis labels. This
810 specification is very similar to the HTML image map specification, and
811 in fact exists mainly for that purpose. You can get at these hotspots
812 with the "get_hotspot" method for data point, and
813 "get_feature_coordinates" for the chart features.
814 The <get_hotspot> method accepts two optional arguments, the number of
816 the dataset you're interested in, and the number of the point in that
817 dataset you're interested in. When called with two arguments, the
818 method returns a list of one of the following forms:
819 'rect', x1, y1, x2, y2
821 'poly', x1, y1, x2, y2, x3, y3, ....
822 'line', xs, ys, xe, ye, width
823 The parameters for "rect" are the coordinates of the corners of the
825 rectangle, the parameters for "poly" are the coordinates of the
826 vertices of the polygon, and the parameters for the "line" are the
827 coordinates for the start and end point, and the line width. It should
828 be possible to almost directly translate these lists into HTML image
829 map specifications.
830 If the second argument to "get_hotspot" is omitted, a list of
832 references to arrays will be returned. This list represents all the
833 points in the dataset specified, and each array referred to is of the
834 form outlined above.
835 ['rect', x1, y1, x2, y2 ], ['rect', x1, y1, x2, y2], ...
837 if both arguments to "get_hotspot" are omitted, the list that comes
839 back will contain references to arrays for each data set, which in turn
840 contain references to arrays for each point.
841 [
843 ['rect', x1, y1, x2, y2 ], ['rect', x1, y1, x2, y2], ...
844 ],
845 [
846 ['line', xs, ys, xe, ye, w], ['line', xs, ys, xe, ye, w], ...
847 ],...
848 The "get_feature" method, when called with the name of a feature,
850 returns a single array reference with a type and coordinates as
851 described above. When called with no arguments, a hash reference is
852 returned with the keys being all the currently defined and set
853 features, and the values array references with the type and coordinates
854 for each of those features.
855
857 GD::Graph objects inherit from the GD::Graph::Error class (not the
858 other way around), so they behave in the same manner. The main feature
859 of that behaviour is that you have the error() method available to get
860 some information about what went wrong. The GD::Graph methods all
861 return undef if something went wrong, so you should be able to write
862 safe programs like this:
863 my $graph = GD::Graph->new() or die GD::Graph->error;
865 $graph->set( %attributes ) or die $graph->error;
866 $graph->plot($gdg_data) or die $graph->error;
867 More advanced usage is possible, and there are some caveats with this
869 error handling, which are all explained in GD::Graph::Error.
870 Unfortunately, it is almost impossible to gracefully recover from an
872 error in GD::Graph, so you really should get rid of the object, and
873 recreate it from scratch if you want to recover. For example, to adjust
874 the correct_width attribute if you get the error "Horizontal size too
875 small" or "Vertical size too small" (in the case of hbar), you could do
876 something like:
877 sub plot_graph
879 {
880 my $data = shift;
881 my %attribs = @_;
882 my $graph = GD::Graph::bars->new()
883 or die GD::Graph->error;
884 $graph->set(%attribs) or die $graph->error;
885 $graph->plot($data) or die $graph->error;
886 }
887 my $gd;
889 eval { $gd = plot_graph(\@data, %attribs) };
890 if ($@)
891 {
892 die $@ unless $@ =~ /size too small/;
893 $gd = plot_graph(\@data, %attribs, correct_width => 0);
894 }
895 Of course, you could also adjust the width this way, and you can check
897 for other errors.
898
900 As with all Modules for Perl: Please stick to using the interface. If
901 you try to fiddle too much with knowledge of the internals of this
902 module, you could get burned. I may change them at any time.
903
905 GD::Graph objects cannot be reused. To create a new plot, you have to
906 create a new GD::Graph object.
907 Rotated charts (ones with the X axis on the left) can currently only be
909 created for bars. With a little work, this will work for all others as
910 well. Please, be patient :)
911 Other outstanding bugs can (alas) probably be found in the RT queue for
913 this distribution, at
914 http://rt.cpan.org/Public/Dist/Display.html?Name=GDGraph
915 If you think you have found a bug, please check first to see if it has
917 already been reported. If it has not, please do (you can use the web
918 interface above or send e-mail to <bug-GDGraph@rt.cpan.org>). Bug
919 reports should contain as many as possible of the following:
920 · a concise description of the buggy behavior and how it differs from
922 what you expected,
923 · the versions of Perl, GD::Graph and GD that you are using,
925 · a short demonstration script that shows the bug in action,
927 · a patch that fixes it. :-)
929 Of all of these, the third is probably the single most important, since
931 producing a test case generally makes the explanation much more concise
932 and understandable, as well as making it much simpler to show that the
933 bug has been fixed. As an incidental benefit, if the bug is in fact
934 caused by some code outside of GD::Graph, it will become apparent while
935 you are writing the test case, thereby saving time and confusion for
936 all concerned.
937
939 Martien Verbruggen <mgjv@tradingpost.com.au>
940 Current maintenance (including this release) by Benjamin Warfield
942 <bwarfield@cpan.org>
943 Copyright
945 GIFgraph: Copyright (c) 1995-1999 Martien Verbruggen.
946 Chart::PNGgraph: Copyright (c) 1999 Steve Bonds.
947 GD::Graph: Copyright (c) 1999 Martien Verbruggen.
948 All rights reserved. This package is free software; you can
950 redistribute it and/or modify it under the same terms as Perl itself.
951 Acknowledgements
953 Thanks to Steve Bonds for releasing Chart::PNGgraph, and keeping the
954 code alive when GD reached version 1.20, and I didn't have time to do
955 something about it.
956 Thanks to the following people for contributing code, or sending me
958 fixes: Dave Belcher, Steve Bonds, Mike Bremford, Damon Brodie, Gary
959 Deschaines, brian d foy, Edwin Hildebrand, Ari Jolma, Tim Meadowcroft,
960 Honza Pazdziora, Scott Prahl, Ben Tilly, Vegard Vesterheim, Jeremy
961 Wadsack.
962 And some people whose real name I don't know, and whose email address
964 I'd rather not publicise without their consent.
965
967 GD::Graph::FAQ, GD::Graph::Data, GD::Graph::Error, GD::Graph::colour
968perl v5.12.0 2007-04-26 Graph(3)