GD::Graph(3pm) - phpMan

Command: man perldoc info search(apropos)  


Graph(3pm)                     User Contributed Perl Documentation                     Graph(3pm)

NAME
       GD::Graph - Graph Plotting Module for Perl 5

SYNOPSIS
       use GD::Graph::moduleName;

DESCRIPTION
       GD::Graph is a perl5 module to create charts using the GD module.  The following classes
       for graphs with axes are defined:

       "GD::Graph::lines"
           Create a line chart.

       "GD::Graph::bars" and "GD::Graph::hbars"
           Create a bar chart with vertical or horizontal bars.

       "GD::Graph::points"
           Create an chart, displaying the data as points.

       "GD::Graph::linespoints"
           Combination of lines and points.

       "GD::Graph::area"
           Create a graph, representing the data as areas under a line.

       "GD::Graph::mixed"
           Create a mixed type graph, any combination of the above. At the moment this is fairly
           limited. Some of the options that can be used with some of the individual graph types
           won't work very well. Bar graphs drawn after lines or points graphs may obscure the
           earlier data, and specifying bar_width will not produce the results you probably
           expected.

       Additional types:

       "GD::Graph::pie"
           Create a pie chart.

DISTRIBUTION STATUS
       Distribution has no releases since 2007. It has new maintainer starting of 1.45 and my
       plan is to keep modules backwards compatible as much as possible, fix bugs with test
       cases, apply patches and release new versions to the CPAN.

       I got repository from Martien without Benjamin's work, Benjamin couldn't find his
       repository, so everything else is imported from CPAN and BackPAN.  Now it's all on github
       <https://github.com/ruz/GDGraph>. May be at some point Benjamin will find his VCS backup
       and we can restore full history.

       Release 1.44_01 (development release) was released in 2007 by Benjamin, but never made
       into production version. This dev version contains very nice changes (truecolor, anti-
       aliasing and alpha support), but due to nature of how GD and GD::Graph works authors had
       to add third optional argument (truecolor) to all constructors in GD::Graph modules. I
       think that this should be and can be adjusted to receive named arguments in constructor
       and still be backwards compatible. If you were using that dev release and want to fast
       forward inclusion of this work into production release then contact ruz AT cpan.org

       Martien also has changes in his repository that were never published to CPAN. These are
       smaller and well isolated, so I can merge them faster.

       My goal at this moment is to merge existing versions together, get rid of CVS reminders,
       do some repo cleanup, review existing tickets on rt.cpan.org. Join if you want to help.

EXAMPLES
       See the samples directory in the distribution, and read the Makefile there.

USAGE
       Fill an array of arrays with the x values and the values of the data sets.  Make sure that
       every array is the same size, otherwise GD::Graph will complain and refuse to compile the
       graph.

         @data = (
           ["1st","2nd","3rd","4th","5th","6th","7th", "8th", "9th"],
           [    1,    2,    5,    6,    3,  1.5,    1,     3,     4],
           [ sort { $a <=> $b } (1, 2, 5, 6, 3, 1.5, 1, 3, 4) ]
         );

       If you don't have a value for a point in a certain dataset, you can use undef, and the
       point will be skipped.

       Create a new GD::Graph object by calling the new method on the graph type you want to
       create (chart is bars, hbars, lines, points, linespoints, mixed or pie).

         my $graph = GD::Graph::chart->new(400, 300);

       Set the graph options.

         $graph->set(
             x_label           => 'X Label',
             y_label           => 'Y label',
             title             => 'Some simple graph',
             y_max_value       => 8,
             y_tick_number     => 8,
             y_label_skip      => 2
         ) or die $graph->error;

       and plot the graph.

         my $gd = $graph->plot(\@data) or die $graph->error;

       Then do whatever your current version of GD allows you to do to save the file. For
       versions of GD older than 1.19 (or more recent than 2.15), you'd do something like:

         open(IMG, '>file.gif') or die $!;
         binmode IMG;
         print IMG $gd->gif;
         close IMG;

       and for newer versions (1.20 and up) you'd write

         open(IMG, '>file.png') or die $!;
         binmode IMG;
         print IMG $gd->png;

       or

         open(IMG, '>file.gd2') or die $!;
         binmode IMG;
         print IMG $gd->gd2;

       Then there's also of course the possibility of using a shorter version (for each of the
       export functions that GD supports):

         print IMG $graph->plot(\@data)->gif;
         print IMG $graph->plot(\@data)->png;
         print IMG $graph->plot(\@data)->gd;
         print IMG $graph->plot(\@data)->gd2;

       If you want to write something that doesn't require your code to 'know' whether to use gif
       or png, you could do something like:

         if ($gd->can('png')) { # blabla }

       or you can use the convenience method "export_format":

         my $format = $graph->export_format;
         open(IMG, ">file.$format") or die $!;
         binmode IMG;
         print IMG $graph->plot(\@data)->$format();
         close IMG;

       or for CGI programs:

         use CGI qw(:standard);
         #...
         my $format = $graph->export_format;
         print header("image/$format");
         binmode STDOUT;
         print $graph->plot(\@data)->$format();

       (the parentheses after $format are necessary, to help the compiler decide that you mean a
       method name there)

       See under "SEE ALSO" for references to other documentation, especially the FAQ.

METHODS
   Methods for all graphs
       GD::Graph::chart->new([width,height])
           Create a new object $graph with optional width and height.  Default width = 400,
           default height = 300. chart is either bars, lines, points, linespoints, area, mixed or
           pie.

       $graph->set_text_clr(colour name)
           Set the colour of the text. This will set the colour of the titles, labels, and axis
           labels to colour name. Also see the options textclr, labelclr and axislabelclr.

       $graph->set_title_font(font specification)
           Set the font that will be used for the title of the chart.  See "FONTS".

       $graph->plot(\@data)
           Plot the chart, and return the GD::Image object.

       $graph->set(attrib1 => value1, attrib2 => value2 ...)
           Set chart options. See OPTIONS section.

       $graph->get(attrib1, attrib2)
           Returns a list of the values of the attributes. In scalar context returns the value of
           the first attribute only.

       $graph->gd()
           Get the GD::Image object that is going to be used to draw on. You can do this either
           before or after calling the plot method, to do your own drawing.

           Note: as of the current version, this GD::Image object will always be palette-based,
           even if the installed version of GD supports true-color images.

           Note also that if you draw on the GD::Image object before calling the plot method, you
           are responsible for making sure that the background colour is correct and for setting
           transparency.

       $graph->export_format()
           Query the export format of the GD library in use.  In scalar context, it returns
           'gif', 'png' or undefined, which is sufficient for most people's use. In a list
           context, it returns a list of all the formats that are supported by the current
           version of GD. It can be called as a class or object method

       $graph->can_do_ttf()
           Returns true if the current GD library supports TrueType fonts, False otherwise. Can
           also be called as a class method or static method.

   Methods for Pie charts
       $graph->set_label_font(font specification)
       $graph->set_value_font(font specification)
           Set the font that will be used for the label of the pie or the values on the pie.  See
           "FONTS".

   Methods for charts with axes.
       $graph->set_x_label_font(font specification)
       $graph->set_y_label_font(font specification)
       $graph->set_x_axis_font(font specification)
       $graph->set_y_axis_font(font specification)
       $graph->set_values_font(font specification)
           Set the font for the x and y axis label, the x and y axis value labels, and for the
           values printed above the data points.  See "FONTS".

       $graph->get_hotspot($dataset, $point)
           Experimental: Return a coordinate specification for a point in a dataset. Returns a
           list. If the point is not specified, returns a list of array references for all points
           in the dataset. If the dataset is also not specified, returns a list of array
           references for each data set.  See "HOTSPOTS".

       $graph->get_feature_coordinates($feature_name)
           Experimental: Return a coordinate specification for a certain feature in the chart.
           Currently, features that are defined are axes, the coordinates of the rectangle within
           the axes; x_label, y1_label and y2_label, the labels printed along the axes, with
           y_label provided as an alias for y1_label; and title which is the title text box.  See
           "HOTSPOTS".

OPTIONS
   Options for all graphs
       width, height
           The width and height of the canvas in pixels Default: 400 x 300.  NB At the moment,
           these are read-only options. If you want to set the size of a graph, you will have to
           do that with the new method.

       t_margin, b_margin, l_margin, r_margin
           Top, bottom, left and right margin of the canvas. These margins will be left blank.
           Default: 0 for all.

       logo
           Name of a logo file. Generally, this should be the same format as your version of GD
           exports images in.  Currently, this file may be in any format that GD can import, but
           please see GD if you use an XPM file and get unexpected results.

           Default: no logo.

       logo_resize, logo_position
           Factor to resize the logo by, and the position on the canvas of the logo. Possible
           values for logo_position are 'LL', 'LR', 'UL', and 'UR'.  (lower and upper left and
           right).  Default: 'LR'.

       transparent
           If set to a true value, the produced image will have the background colour marked as
           transparent (see also option bgclr).  Default: 1.

       interlaced
           If set to a true value, the produced image will be interlaced.  Default: 1.

           Note: versions of GD higher than 2.0 (that is, since GIF support was restored after
           being removed owing to patent issues) do not support interlacing of GIF images.
           Support for interlaced PNG and progressive JPEG images remains available using this
           option.

   Colours
       bgclr, fgclr, boxclr, accentclr, shadowclr
           Drawing colours used for the chart: background, foreground (axes and grid), axis box
           fill colour, accents (bar, area and pie outlines), and shadow (currently only for
           bars).

           All colours should have a valid value as described in "COLOURS", except boxclr, which
           can be undefined, in which case the box will not be filled.

       shadow_depth
           Depth of a shadow, positive for right/down shadow, negative for left/up shadow, 0 for
           no shadow (default).  Also see the "shadowclr" and "bar_spacing" options.

       labelclr, axislabelclr, legendclr, valuesclr, textclr
           Text Colours used for the chart: label (labels for the axes or pie), axis label
           (misnomer: values printed along the axes, or on a pie slice), legend text, shown
           values text, and all other text.

           All colours should have a valid value as described in "COLOURS".

       dclrs (short for datacolours)
           This controls the colours for the bars, lines, markers, or pie slices.  This should be
           a reference to an array of colour names as defined in GD::Graph::colour
           ("perldocGD::Graph::colour" for the names available).

               $graph->set( dclrs => [ qw(green pink blue cyan) ] );

           The first (fifth, ninth) data set will be green, the next pink, etc.

           A colour can be "undef", in which case the data set will not be drawn.  This can be
           useful for cumulative bar sets where you want certain data series (often the first
           one) not to show up, which can be used to emulate error bars (see examples 1-7 and 6-3
           in the distribution).

           Default: [ qw(lred lgreen lblue lyellow lpurple cyan lorange) ]

       borderclrs
           This controls the colours of the borders of the bars data sets. Like dclrs, it is a
           reference to an array of colour names as defined in GD::Graph::colour.  Setting a
           border colour to "undef" means the border will not be drawn.

       cycle_clrs
           If set to a true value, bars will not have a colour from "dclrs" per dataset, but per
           point. The colour sequence will be identical for each dataset. Note that this may have
           a weird effect if you are drawing more than one data set. If this is set to a value
           larger than 1 the border colour of the bars will cycle through the colours in
           "borderclrs".

       accent_treshold
           Not really a colour, but it does control a visual aspect: Accents on bars are only
           drawn when the width of a bar is larger than this number of pixels. Accents inside
           areas are only drawn when the horizontal distance between points is larger than this
           number.  Default 4

   Options for graphs with axes.
       options for bars, lines, points, linespoints, mixed and area charts.

       x_label, y_label
           The labels to be printed next to, or just below, the axes. Note that if you use the
           two_axes option that you need to use y1_label and y2_label.

       long_ticks, tick_length
           If long_ticks is a true value, ticks will be drawn the same length as the axes.
           Otherwise ticks will be drawn with length tick_length. if tick_length is negative, the
           ticks will be drawn outside the axes.  Default: long_ticks = 0, tick_length = 4.

           These attributes can also be set for x and y axes separately with x_long_ticks,
           y_long_ticks, x_tick_length and y_tick_length.

       x_ticks
           If x_ticks is a true value, ticks will be drawn for the x axis.  These ticks are
           subject to the values of long_ticks and tick_length.  Default: 1.

       y_tick_number
           Number of ticks to print for the Y axis. Use this, together with y_label_skip to
           control the look of ticks on the y axis.  Default: 5.

       y_number_format
           This can be either a string, or a reference to a subroutine. If it is a string, it
           will be taken to be the first argument to a sprintf, with the value as the second
           argument:

               $label = sprintf( $s->{y_number_format}, $value );

           If it is a code reference, it will be executed with the value as the argument:

               $label = &{$s->{y_number_format}}($value);

           This can be useful, for example, if you want to reformat your values in currency, with
           the - sign in the right spot. Something like:

               sub y_format
               {
                   my $value = shift;
                   my $ret;

                   if ($value >= 0)
                   {
                       $ret = sprintf("\$%d", $value * $refit);
                   }
                   else
                   {
                       $ret = sprintf("-\$%d", abs($value) * $refit);
                   }

                   return $ret;
               }

               $graph->set( 'y_number_format' => \&y_format );

           (Yes, I know this can be much shorter and more concise)

           Default: undef.

       y1_number_format, y2_number_format
           As with y_number_format, these can be either a string, or a reference to a subroutine.
           These are used as formats for graphs with two y-axis scales so that independent
           formats can be used.

           For compatibility purposes, each of these will fall back on y_number_format if not
           specified.

           Default: undef for both.

       x_label_skip, y_label_skip
           Print every x_label_skipth number under the tick on the x axis, and every
           y_label_skipth number next to the tick on the y axis.  Default: 1 for both.

       x_last_label_skip
           By default, when x_label_skip is set to something higher than 1, the last label on the
           axis will be printed, even when it doesn't belong to the normal series that should be
           printed. Setting this to a true value prevents that.

           For example, when your X values are the months of the year (i.e. Jan - Dec), and you
           set x_label_skip to 3, the months printed on the axis will be Jan, Apr, Jul, Oct and
           Dec; even though Dec does not really belong to that sequence. If you do not like the
           last month to be printed, set x_last_label_skip to a true value.

           This option has no effect in other circumstances. Also see x_tick_offset for another
           method to make this look better.  Default: 0 for both

       x_tick_offset
           When x_label_skip is used, this will skip the first x_tick_offset values in the labels
           before starting to print. Let me give an example.  If you have a series of X labels
           like

             qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec)

           and you set x_label_skip to 3, you will see ticks on the X axis for Jan, Apr, Jul, Oct
           and Dec. This is not always what is wanted. If you set x_tick_offset to 1, you get
           Feb, May, Aug, Nov and Dec, and if you set it to 2, you get Mar, Jun Sep and Dec, and
           this last one definitely looks better. A combination of 6 and 5 also works nice for
           months.

           Note that the value for x_tick_offset is periodical. This means that it will have the
           same effect for each integer n in x_tick_offset + n * x_label_skip.

           Also see x_last_label_skip for another method to influence this.

       x_all_ticks
           Force a print of all the x ticks, even if x_label_skip is set to a value Default: 0.

       x_label_position
           Controls the position of the X axis label (title). The value for this should be
           between 0 and 1, where 0 means aligned to the left, 1 means aligned to the right, and
           1/2 means centered.  Default: 3/4

       y_label_position
           Controls the position of both Y axis labels (titles). The value for this should be
           between 0 and 1, where 0 means aligned to the bottom, 1 means aligned to the top, and
           1/2 means centered.  Default: 1/2

       x_labels_vertical
           If set to a true value, the X axis labels will be printed vertically.  This can be
           handy in case these labels get very long.  Default: 0.

       x_plot_values, y_plot_values
           If set to a true value, the values of the ticks on the x or y axes will be plotted
           next to the tick. Also see x_label_skip, y_label_skip.  Default: 1 for both.

       box_axis
           Draw the axes as a box, if true.  Default: 1.

       no_axes
           Draw no axes at all. If this is set to undef, all axes are drawn. If it is set to 0,
           the zero axis will be drawn, for bar charts only.  If this is set to a true value, no
           axes will be drawn at all. Value labels on the axes and ticks will also not be drawn,
           but axis lables are drawn.  Default: undef.

       two_axes
           Use two separate axes for the first and second data set. The first data set will be
           set against the left axis, the second against the right axis.  If more than two data
           sets are being plotted, the use_axis option should be used to specify which data sets
           use which axis.

           Note that if you use this option, that you need to use y1_label and y2_label, instead
           of just y_label, if you want the two axes to have different labels. The same goes for
           some other options starting with the letter 'y' and an underscore.

           Default: 0.

       use_axis
           If two y-axes are in use and more than two datasets are specified, set this option to
           an array reference containing a value of 1 or 2 (for the left and right scales
           respectively) for each dataset being plotted.  That is, to plot three datasets with
           the second on a different scale than the first and third, set this to "[1,2,1]".

           Default: [1,2].

       zero_axis
           If set to a true value, the axis for y values of 0 will always be drawn. This might be
           useful in case your graph contains negative values, but you want it to be clear where
           the zero value is. (see also zero_axis_only and box_axes).  Default: 0.

       zero_axis_only
           If set to a true value, the zero axis will be drawn (see zero_axis), and no axis at
           the bottom of the graph will be drawn.  The labels for X values will be placed on the
           zero axis.  Default: 0.

       y_max_value, y_min_value
           Maximum and minimum value displayed on the y axis.

           The range (y_min_value..y_max_value) has to include all the values of the data points,
           or GD::Graph will die with a message.

           For bar and area graphs, the range (y_min_value..y_max_value) has to include 0. If it
           doesn't, the values will be adapted before attempting to draw the graph.

           Default: Computed from data sets.

       y1_max_value, y1_min_value, y2_max_value, y2_min_value
           Maximum and minimum values for left (y1) and right (y2) axes when two_axes is a true
           value. Take precedence over y_min_value and y_max_value.

           By default 0 of the left axis is aligned with 0 of the right axis, it's not true if
           any of these options is defined.

           Otherwise behaviour and default values are as with y_max_value and y_min_value.

       y_min_range, y1_min_range, y2_min_range
           Minimal range between min and max values on y axis that is used to adjust computed
           y_min_value and y_max_value.

           NOTE that author of the feature implemented this for two_axes case only, patches are
           wellcome to expand over one y axis.

           If two_axes is a true value, then y1_min_range and y2_min_range take precedence over
           y_min_range value.

           Default: undef

       axis_space
           This space will be left blank between the axes and the tick value text.  Default: 4.

       text_space
           This space will be left open between text elements and the graph (text elements are
           title and axis labels.

           Default: 8.

       cumulate
           If this attribute is set to a true value, the data sets will be cumulated. This means
           that they will be stacked on top of each other. A side effect of this is that
           "overwrite" will be set to a true value.

           Notes: This only works for bar and area charts at the moment.

           If you have negative values in your data sets, setting this option might produce odd
           results. Of course, the graph itself would be quite meaningless.

       overwrite
           If set to 0, bars of different data sets will be drawn next to each other. If set to
           1, they will be drawn in front of each other.  Default: 0.

           Note: Setting overwrite to 2 to produce cumulative sets is deprecated, and may
           disappear in future versions of GD::Graph.  Instead see the "cumulate" attribute.

       correct_width
           If this is set to a true value and "x_tick_number" is false, then the width of the
           graph (or the height for rotated graphs like "GD::Graph::hbar") will be recalculated
           to make sure that each data point is exactly an integer number of pixels wide. You
           probably never want to fiddle with this.

           When this value is true, you will need to make sure that the number of data points is
           smaller than the number of pixels in the plotting area of the chart. If you get errors
           saying that your horizontal size if too small, you may need to manually switch this
           off, or consider using something else than a bar type for your chart.

           Default: 1 for bar, calculated at runtime for mixed charts, 0 for others.

   Plotting data point values with the data point
       Sometimes you will want to plot the value of a data point or bar above the data point for
       clarity. GD::Graph allows you to control this in a generic manner, or even down to the
       single point.

       show_values
           Set this to 1 to display the value of each data point above the point or bar itself.
           No effort is being made to ensure that there is enough space for the text.

           Set this to a GD::Graph::Data object, or an array reference of the same shape, with
           the same dimensions as your data object that you pass in to the plot method. The
           reason for this option is that it allows you to make a copy of your data set, and
           selectively set points to "undef" to disable plotting of them.

             my $data = GD::Graph::Data->new(
               [ [ 'A', 'B', 'C' ], [ 1, 2, 3 ], [ 11, 12, 13 ] ]);
             my $values = $data->copy;
             $values->set_y(1, 1, undef);
             $values->set_y(2, 0, undef);

             $graph->set(show_values => $values);
             $graph->plot($data);

           Default: 0.

       values_vertical
           If set to a true value, the values will be printed vertically, instead of
           horizontally. This can be handy if the values are long numbers.  Default: 0.

       values_space
           Space to insert between the data point and the value to print.  Default: 4.

       values_format
           How to format the values for display. See y_number_format for more information.
           Default: undef.

       hide_overlapping_values
           If set to a true value, the values that goes out of graph space are hidden.  Option is
           EXPERIMENTAL, works only for bars, text still can overlap with other bars and labels,
           most useful only with text in the same direction as bars.  Default: undef

   Options for graphs with a numerical X axis
       First of all: GD::Graph does not support numerical x axis the way it should. Data for X
       axes should be equally spaced. That understood: There is some support to make the printing
       of graphs with numerical X axis values a bit better, thanks to Scott Prahl. If the option
       "x_tick_number" is set to a defined value, GD::Graph will attempt to treat the X data as
       numerical.

       Extra options are:

       x_tick_number
           If set to 'auto', GD::Graph will attempt to format the X axis in a nice way, based on
           the actual X values. If set to a number, that's the number of ticks you will get. If
           set to undef, GD::Graph will treat X data as labels.  Default: undef.

       x_min_value, x_max_value
           The minimum and maximum value to use for the X axis.  Default: computed.

       x_min_range
           Minimal range of x axis.

           Default: undef

       x_number_format
           See y_number_format

       x_label_skip
           See y_label_skip

   Options for graphs with bars
       bar_width
           The width of a bar in pixels. Also see "bar_spacing".  Use "bar_width" If you want to
           have fixed-width bars, no matter how wide the chart gets.  Default: as wide as
           possible, within the constraints of the chart size and "bar_spacing" setting.

       bar_spacing
           Number of pixels to leave open between bars. This works well in most cases, but on
           some platforms, a value of 1 will be rounded off to 0.  Use "bar_spacing" to get a
           fixed amount of space between bars, with variable bar widths, depending on the width
           of the chart.  Note that if "bar_width" is also set, this setting will be ignored, and
           automatically calculated.  Default: 0

       bargroup_spacing
           Number of pixels (in addition to whatever is specified in "bar_spacing") to leave
           between groups of bars when multiple datasets are being displayed.  Unlike
           "bar_spacing", however, this parameter will hold its value if "bar_width" is set.

   Options for graphs with lines
       line_types
           Which line types to use for lines and linespoints graphs. This should be a reference
           to an array of numbers:

               $graph->set( line_types => [3, 2, 4] );

           Available line types are 1: solid, 2: dashed, 3: dotted, 4: dot-dashed.

           Default: [1] (always use solid)

       line_type_scale
           Controls the length of the dashes in the line types. default: 6.

       line_width
           The width of the line used in lines and linespoints graphs, in pixels.  Default: 1.

       skip_undef
           For all other axes graph types, the default behaviour is (by their nature) to not draw
           a point when the Y value is "undef". For line charts the point gets skipped as well,
           but the line is drawn between the points n-1 to n+1 directly. If "skip_undef" has a
           true value, there will be a gap in the chart where a Y value is undefined.

           Note that a line will not be drawn unless there are at least two consecutive data
           points exist that have a defined value. The following data set will only plot a very
           short line towards the end if "skip_undef" is set:

             @data = (
               [ qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct ) ],
               [ 1, undef, 2, undef, 3, undef, 4, undef, 5, 6 ]
             );

           This option is useful when you have a consecutive gap in your data, or with
           linespoints charts. If you have data where you have intermittent gaps, be careful when
           you use this.  Default value: 0

   Options for graphs with points
       markers
           This controls the order of markers in points and linespoints graphs.  This should be a
           reference to an array of numbers:

               $graph->set( markers => [3, 5, 6] );

           Available markers are: 1: filled square, 2: open square, 3: horizontal cross, 4:
           diagonal cross, 5: filled diamond, 6: open diamond, 7: filled circle, 8: open circle,
           9: horizontal line, 10: vertical line.  Note that the last two are not part of the
           default list.

           Default: [1,2,3,4,5,6,7,8]

       marker_size
           The size of the markers used in points and linespoints graphs, in pixels.  Default: 4.

   Options for mixed graphs
       types
           A reference to an array with graph types, in the same order as the data sets. Possible
           values are:

             $graph->set( types => [qw(lines bars points area linespoints)] );
             $graph->set( types => ['lines', undef, undef, 'bars'] );

           values that are undefined or unknown will be set to "default_type".

           Default: all set to "default_type"

       default_type
           The type of graph to draw for data sets that either have no type set, or that have an
           unknown type set.

           Default: lines

   Graph legends (axestype graphs only)
       At the moment legend support is minimal.

       Methods

       $graph->set_legend(@legend_keys);
           Sets the keys for the legend. The elements of @legend_keys correspond to the data sets
           as provided to plot().

           If a key is undef or an empty string, the legend entry will be skipped.

       $graph->set_legend_font(font name);
           Sets the font for the legend text (see "FONTS").  Default: GD::gdTinyFont.

       Options

       legend_placement
           Where to put the legend. This should be a two letter key of the form: 'B[LCR]|R[TCB]'.
           The first letter indicates the placement (Bottom or Right), and the second letter the
           alignment (Left, Right, Center, Top, or Bottom).  Default: 'BC'

           If the legend is placed at the bottom, some calculations will be made to ensure that
           there is some 'intelligent' wrapping going on. if the legend is placed at the right,
           all entries will be placed below each other.

       legend_spacing
           The number of pixels to place around a legend item, and between a legend 'marker' and
           the text.  Default: 4

       legend_marker_width, legend_marker_height
           The width and height of a legend 'marker' in pixels.  Defaults: 12, 8

       lg_cols
           If you, for some reason, need to force the legend at the bottom to have a specific
           number of columns, you can use this.  Default: computed

   Options for pie graphs
       3d  If set to a true value, the pie chart will be drawn with a 3d look.  Default: 1.

       pie_height
           The thickness of the pie when 3d is true.  Default: 0.1 x height.

       start_angle
           The angle at which the first data slice will be displayed, with 0 degrees being "6
           o'clock".  Default: 0.

       suppress_angle
           If a pie slice is smaller than this angle (in degrees), a label will not be drawn on
           it. Default: 0.

       label
           Print this label below the pie. Default: undef.

COLOURS
       All references to colours in the options for this module have been shortened to clr. The
       main reason for this was that I didn't want to support two spellings for the same word
       ('colour' and 'color')

       Wherever a colour is required, a colour name should be used from the package
       GD::Graph::colour. "perldocGD::Graph::colour" should give you the documentation for that
       module, containing all valid colour names. I will probably change this to read the systems
       rgb.txt file if it is available.

FONTS
       Depending on your version of GD, this accepts both GD builtin fonts or the name of a
       TrueType font file. In the case of a TrueType font, you must specify the font size. See
       GD::Text for more details and other things, since all font handling in GD::Graph is
       delegated to there.

       Examples:

           $graph->set_title_font('/fonts/arial.ttf', 18);
           $graph->set_legend_font(gdTinyFont);
           $graph->set_legend_font(
               ['verdana', 'arial', gdMediumBoldFont], 12)

       (The above discussion is based on GD::Text 0.65. Older versions have more restrictive
       behaviour).

HOTSPOTS
       Note that this is an experimental feature, and its interface may, and likely will, change
       in the future. It currently does not work for area charts or pie charts.

       A known problem with hotspots for GD::Graph::hbars is that the x and y coordinate come out
       transposed. This probably won't be fixed until the redesign of this section

       GD::Graph keeps an internal set of coordinates for each data point and for certain
       features of a chart, like the title and axis labels. This specification is very similar to
       the HTML image map specification, and in fact exists mainly for that purpose. You can get
       at these hotspots with the "get_hotspot" method for data point, and
       "get_feature_coordinates" for the chart features.

       The <get_hotspot> method accepts two optional arguments, the number of the dataset you're
       interested in, and the number of the point in that dataset you're interested in. When
       called with two arguments, the method returns a list of one of the following forms:

         'rect', x1, y1, x2, y2
         'poly', x1, y1, x2, y2, x3, y3, ....
         'line', xs, ys, xe, ye, width

       The parameters for "rect" are the coordinates of the corners of the rectangle, the
       parameters for "poly" are the coordinates of the vertices of the polygon, and the
       parameters for the "line" are the coordinates for the start and end point, and the line
       width.  It should be possible to almost directly translate these lists into HTML image map
       specifications.

       If the second argument to "get_hotspot" is omitted, a list of references to arrays will be
       returned. This list represents all the points in the dataset specified, and each array
       referred to is of the form outlined above.

         ['rect', x1, y1, x2, y2 ], ['rect', x1, y1, x2, y2], ...

       if both arguments to "get_hotspot" are omitted, the list that comes back will contain
       references to arrays for each data set, which in turn contain references to arrays for
       each point.

         [
           ['rect', x1, y1, x2, y2 ], ['rect', x1, y1, x2, y2], ...
         ],
         [
           ['line', xs, ys, xe, ye, w], ['line', xs, ys, xe, ye, w], ...
         ],...

       The "get_feature" method, when called with the name of a feature, returns a single array
       reference with a type and coordinates as described above. When called with no arguments, a
       hash reference is returned with the keys being all the currently defined and set features,
       and the values array references with the type and coordinates for each of those features.

ERROR HANDLING
       GD::Graph objects inherit from the GD::Graph::Error class (not the other way around), so
       they behave in the same manner. The main feature of that behaviour is that you have the
       error() method available to get some information about what went wrong. The GD::Graph
       methods all return undef if something went wrong, so you should be able to write safe
       programs like this:

         my $graph = GD::Graph->new()    or die GD::Graph->error;
         $graph->set( %attributes )      or die $graph->error;
         $graph->plot($gdg_data)         or die $graph->error;

       More advanced usage is possible, and there are some caveats with this error handling,
       which are all explained in GD::Graph::Error.

       Unfortunately, it is almost impossible to gracefully recover from an error in GD::Graph,
       so you really should get rid of the object, and recreate it from scratch if you want to
       recover. For example, to adjust the correct_width attribute if you get the error
       "Horizontal size too small" or "Vertical size too small" (in the case of hbar), you could
       do something like:

         sub plot_graph
         {
             my $data    = shift;
             my %attribs = @_;
             my $graph   = GD::Graph::bars->new()
                or die GD::Graph->error;
             $graph->set(%attribs)     or die $graph->error;
             $graph->plot($data)       or die $graph->error;
         }

         my $gd;
         eval { $gd = plot_graph(\@data, %attribs) };
         if ($@)
         {
             die $@ unless $@ =~ /size too small/;
             $gd = plot_graph(\@data, %attribs, correct_width => 0);
         }

       Of course, you could also adjust the width this way, and you can check for other errors.

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

BUGS
       GD::Graph objects cannot be reused. To create a new plot, you have to create a new
       GD::Graph object.

       Rotated charts (ones with the X axis on the left) can currently only be created for bars.
       With a little work, this will work for all others as well. Please, be patient :)

       Other outstanding bugs can (alas) probably be found in the RT queue for this distribution,
       at http://rt.cpan.org/Public/Dist/Display.html?Name=GDGraph

       If you think you have found a bug, please check first to see if it has already been
       reported.  If it has not, please do (you can use the web interface above or send e-mail to
       <bug-GDGraph AT rt.org>).  Bug reports should contain as many as possible of the
       following:

       o   a concise description of the buggy behavior and how it differs from what you expected,

       o   the versions of Perl, GD::Graph and GD that you are using,

       o   a short demonstration script that shows the bug in action,

       o   a patch that fixes it. :-)

       Of all of these, the third is probably the single most important, since producing a test
       case generally makes the explanation much more concise and understandable, as well as
       making it much simpler to show that the bug has been fixed.  As an incidental benefit, if
       the bug is in fact caused by some code outside of GD::Graph, it will become apparent while
       you are writing the test case, thereby saving time and confusion for all concerned.

AUTHOR
       Martien Verbruggen <mgjv AT tradingpost.au>

       Current maintenance (including this release) by Benjamin Warfield <bwarfield AT cpan.org>

   Copyright
        GIFgraph: Copyright (c) 1995-1999 Martien Verbruggen.
        Chart::PNGgraph: Copyright (c) 1999 Steve Bonds.
        GD::Graph: Copyright (c) 1999 Martien Verbruggen.

       All rights reserved. This package is free software; you can redistribute it and/or modify
       it under the same terms as Perl itself.

   Acknowledgements
       Thanks to Steve Bonds for releasing Chart::PNGgraph, and keeping the code alive when GD
       reached version 1.20, and I didn't have time to do something about it.

       Thanks to the following people for contributing code, or sending me fixes: Dave Belcher,
       Steve Bonds, Mike Bremford, Damon Brodie, Gary Deschaines, brian d foy, Edwin Hildebrand,
       Ari Jolma, Tim Meadowcroft, Honza Pazdziora, Scott Prahl, Ben Tilly, Vegard Vesterheim,
       Jeremy Wadsack.

       And some people whose real name I don't know, and whose email address I'd rather not
       publicise without their consent.

SEE ALSO
       GD::Graph::FAQ, GD::Graph::Data, GD::Graph::Error, GD::Graph::colour

perl v5.32.1                                2022-02-04                                 Graph(3pm)

Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2024-10-16 01:25 @3.237.15.145 CrawledBy CCBot/2.0 (https://commoncrawl.org/faq/)
Valid XHTML 1.0!Valid CSS!