NAME

       Chart::Manual::Methods - user API

OVERVIEW

       This are all methods for the chart user.

ALPHABETICALLY

   add_datafile
       Loads all data of a chart (one or more data sets) from a file.  (Works only if no data yet
       added.) You have to either provide a filename or filehandle (old school or in SCALAR).

           $graph->add_dataset( 'file.tsv' );
           $graph->add_dataset( $file_handle );
           $graph->add_dataset( FILE_HANDLE );

       An optional second argument, which defaults to 'set' can change the file format if set to
       'pt'. In 'set' mode every row of the file content is fed to "add_dataset", in 'pt' every
       row get loaded like via "add_pt". In other words: 'pt' transposes the data table.

           $graph->add_dataset( 'file.tsv', 'pt'  );

       The arbitrary named text files have to contain one or several rows of numbers.  The
       numbers need to be separated by spaces or tabs (\t) (mixing allowed).  Perl style comments
       or empty lines will be ignored, but rows containing different amount of numbers will cause
       problems.

   add_dataset
       Adding a list of values as one data set. That is one row in the overall data table. The
       first data set are usually x-axis labels (domain set).  Make sure all sets have the same
       length.

           $graph->add_dataset(  1, 2, 3, ...  );
           $graph->add_dataset( [1, 2, 3, ...] );

       For instances with Points, Lines or Bars one data set is represented by a set of graphic
       items (points, bars or line) of one color.

   add_pt
       Adds (appends) to each already existing data set one value. That is a column in the
       overall data table. In this example it adds to set 0 the value 3, to set 1 the 6 and so
       forth. Make sure that the list lengths matches the number of already existing data sets.

           $graph->add_pt(  3, 6, 9, ...  );
           $graph->add_pt( [3, 6, 9, ...] );

   cgi_jpeg
       Creates same JPEG image as "jpeg", but outputs to STDOUT. Since no file name or handle
       needed, only the optional data argument is acceptable.

           $graph->cgi_jpeg( );

           my @data = ([1, 2, 3],   # data set 0
                       [3, 4, 5]);  # data set 1
           $graph->cgi_jpeg( \@data );

   cgi_png
       Creates same PNG image as "png", but outputs to STDOUT. Since no file name or handle
       needed, only the optional data argument is acceptable.

           $graph->cgi_png( );

           my $data = [[1, 2, 3],   # data set 0
                       [3, 4, 5] ]; # data set 1
           $graph->cgi_png( $data );

   clear_data
       Needs no arguments and deletes all so far added data.

   get_data
       Return all data (array of arrays) given to a graph.

   imagemap_dump
       When creating a chart for web purposes by "cgi_jpeg" or "cgi_png", you maybe want the
       information, where the areas of interests in the image are located, that should react to a
       users click. (HTML tag map).  These areas are bounding boxes around the drawn bars or
       points.  You will get per box the values: x1, y1, x2, y2 in one array.  These arrays are
       again in an Array holding, all boxes from one data set.  The highest level array  again
       holds all arrays of all data sets, beginning with index 1.

       This method can only be called, if the functionality is activated by setting the property:
       imagemap to 'true'.

           $graph->set( imagemap => 'true');
           my $image_map = $graph->imagemap_dump();

           say "coordinates of first bar, first data set:";
           say for @{$image_map->[1][0]};

   jpeg
       Creates an JPEG image from given data and properties. Accepts a file name or a file handle
       (raw or in a SCALAR). The method closes the file handle.

           $graph->jpeg( 'image.jpg' );
           $graph->jpeg( $file_handle );
           $graph->jpeg( FILE_HANDLE );

           $graph->jpeg( 'image.jpg', $data );
           $graph->jpeg( 'image.jpg', 'data_file.tsv' );
           $graph->jpeg( 'image.jpg', $file_handle );
           $graph->jpeg( 'image.jpg', FILE_HANDLE );

       The second, optional argument is the data in form of an array of arrays reference. This
       only works, if there is no data already given to the object.  Alternatively the data can
       also be loaded from a file, just provide the filename or filehandle (modern in SCALAR or
       old school).  Read more about the file format at "add_datafile" and note that this method
       has another option for loading transposed data tables.

   new
       Creates a new chart object. Takes two optional arguments, which are the width and height
       of the to be produced image in pixels.  Defaults for that are 400 x 300.

           my $graph = Chart::Bars->new ( );
           my $graph = Chart::Bars->new (600, 700);

       Instead of Bars, you can also use: Composite, Direction, ErrorBars, HorizontalBars, Lines,
       LinesPoints, Mountain, Pareto, Pie, Points, Split and StackedBars. To know more about them
       read Chart::Manual::Types.

   png
       Creates an PNG image from given data and properties. Accepts a file name or a file handle
       (raw or in a SCALAR). The method closes the file handle.

           $graph->png( 'image.png' );
           $graph->png( $file_handle );
           $graph->png( FILE_HANDLE );

           $graph->png( 'image.png', $data );
           $graph->png( 'image.png', 'data_file.tsv' );
           $graph->png( 'image.png', $file_handle );
           $graph->png( 'image.png', FILE_HANDLE );

       The second, optional argument is the data in form of an array of arrays reference. This
       only works, if there is no data already given to the object.  Alternatively the data can
       also be loaded from a file, just provide the filename or filehandle (modern in SCALAR or
       old school).  Read more about the file format at "add_datafile" and note that this method
       has another option for loading transposed data tables.

   scalar_jpeg
       Creates same JPEG image as "jpeg" but returns the image binary into a variable, not to
       STDOUT or a file.

           my $image_binary = $graph->scalar_jpeg();
           my $image_binary = $graph->scalar_jpeg( $data );

   scalar_png
       Creates same PNG image as "png" but returns the image binary into a variable, not to
       STDOUT or a file.

           my $image_binary = $graph->scalar_png();
           my $image_binary = $graph->scalar_png( $data );

   set
       Method to change one or more chart properties in hash form.

         $chart->set ( property_name => 'new value', ... );
         $chart->set ( %properties );

       Different chart types react to different properties, which are all listed and explained
       under Chart::Manual::Properties.

COPYRIGHT & LICENSE

       Copyright 2022 Herbert Breunung.

       This program is free software; you can redistribute it and/or modify it under same terms
       as Perl itself.

AUTHOR

       Herbert Breunung, <lichtkind@cpan.org>