NAME

Tk::Chart::Mixed - Extension of Canvas widget to create mixed graph.

SYNOPSIS

  #!/usr/bin/perl
  use strict;
  use warnings;
  use Tk;
  use Tk::Chart::Mixed;
  
  my $mw = MainWindow->new(
    -title      => 'Tk::Chart::Mixed',
    -background => 'white',
  );
  
  my @types = ( 'areas', 'bars', 'lines', 'points', 'bars', 'dashlines' );
  my $chart = $mw->Mixed(
    -title      => 'Tk::Chart::Mixed',
    -xlabel     => 'X Label',
    -ylabel     => 'Y Label',
    -background => '#D0D0FF',
    -linewidth  => 2,
    -typemixed  => \@types,
    -markers    => [ 3, 5, 6 ],
  
    -longticks => 1,
  )->pack(qw / -fill both -expand 1 /);
  
  my @data = (
    [ '1st', '2nd', '3rd', '4th', '5th', '6th', '7th', '8th', '9th' ],
    [ 90,    29,    25,    6,     -20,   1,     1,     3,     4 ],
    [ 15,    10,    5,     2,     3,     5,     7,     9,     12 ],
    [ 1,     2,     12,    6,     3,     5,     1,     23,    5 ],
    [ 15,    12,    24,    33,    19,    8,     6,     15,    21 ],
    [ 15,    2,     52,    6,     3,     17.5,  1,     43,    10 ],
    [ 30,    2,     5,     6,     3,     1.5,   1,     3,     4 ],
    [ 24,    12,    35,    20,    13,    31.5,  41,    6,     25 ],
  
  );
  
  # Add a legend to the graph
  my @legends = @types;
  $chart->set_legend(
    -title       => "Title legend",
    -data        => [ 'legend 1', 'legend 2', 'legend 3', 'legend 4', 'legend 5', 'legend 6', 'legend 7', ],
    -titlecolors => "blue",
  );
  
  # Add help identification
  $chart->set_balloon();
  
  # Create the graph
  $chart->plot( \@data );
  
  # background order wanted
  $chart->display_order( [qw/ areas lines bars  dashlines points /] );
  
  MainLoop();

DESCRIPTION

Tk::Chart::Mixed is an extension of the Canvas widget. It is an easy way to build an interactive graph into your Perl Tk widget. The module is written entirely in Perl/Tk.

You can set a background gradient color.

In the same graph, you can create lines, bars, areas, line points, points. You can change the color, font of title, labels (x and y) of the graph. You can set an interactive legend. The axes can be automatically scaled or set by the code.

You can use 3 methods to zoom (vertically, horizontally or both).

BACKGROUND GRADIENT COLOR

You can set a background gradient color by using all methods of Tk::Canvas::GradientColor. By default, it is not enabled.

To enabled background gradient color the first time, you firstly have to call enabled_gradientcolor method and configure your color and type of gradient with set_gradientcolor.

  $chart->enabled_gradientcolor();
  $chart->set_gradientcolor(
      -start_color => '#6585ED',
      -end_color   => '#FFFFFF',
  );

Please, read "WIDGET-SPECIFIC METHODS" in Tk::Canvas::GradientColor documentation to know all available configurations.

STANDARD OPTIONS

-background -borderwidth -closeenough -confine -cursor -height -highlightbackground -highlightcolor -highlightthickness -insertbackground -insertborderwidth -insertofftime -insertontime -insertwidth -relief -scrollregion -selectbackground -selectborderwidth -selectforeground -takefocus -width -xscrollcommand -xscrollincrement -yscrollcommand -yscrollincrement

WIDGET-SPECIFIC OPTIONS

Name: Typemixed
Class: TypeMixed
Switch: -typemixed

This controls the graph types to display in the same order as data set. This should be a reference to an array of graph types.

The different types are : areas, bars, lines, dashlines and points

 -typemixed => [ 'areas', 'bars', 'lines' ]
 -typemixed => [ 'lines',  undef, 'areas' ]

values that are undefined will be set to -defaulttype option.

Default : undef

Name: Defaulttype
Class: DefaultType
Switch: -defaulttype

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

The different types are : areas, bars, lines, dashlines or points

 -defaulttype => 'bars',

Default : 'lines'

WIDGET-SPECIFIC OPTIONS like Tk::Chart::Points

These options are specific to point lines graph creation.

Name: Pointline
Class: PointLine
Switch: -pointline

Set a true value to create point lines graph.

 -pointline => 1, # 0 or 1

Default : 0

Name: Markersize
Class: MarkerSize
Switch: -markersize

The size of the markers used in points graphs, in pixels.

 -markersize => 10, # integer

Default : 8

Name: Markers
Class: Markers
Switch: -markers

This controls the order of markers in points graphs. This should be a reference to an array of numbers:

 -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

Default : [1,2,3,4,5,6,7,8] Note that the last two are not part of the default list.

WIDGET-SPECIFIC OPTIONS for graphs with axes.

See "WIDGET-SPECIFIC OPTIONS" in Tk::Chart::Lines

WIDGET-SPECIFIC OPTIONS like Tk::Chart::Spline

Name: Bezier
Class: Bezier
Switch: -bezier

To create lines graph as Bézier curve. The curve crosses only by the extreme points (the first and the last).

 -bezier => 1, # 0 or 1

Default : 0

Name: Spline
Class: Spline
Switch: -spline

To create lines graph as Bézier curve. The curve crosses by all points. The -bezier option has to be set to 1.

 -spline => 1, # 0 or 1

Default : 0

WIDGET-SPECIFIC OPTIONS like Tk::Chart::Bars

Name: Overwrite
Class: OverWrite
Switch: -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.

 -overwrite => 1, # 0 or 1

Default : 0

Name: Cumulate
Class: Cumulate
Switch: -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.

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.

 -cumulate => 1, # 0 or 1

Default : 0

Name: Showvalues
Class: ShowValues
Switch: -showvalues

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.

If -overwrite or -cumulate set to 1, some text value could be hide by bars.

 -showvalues => 0, # 0 or 1

Default : 1

Name: Spacingbar
Class: SpacingBar
Switch: -spacingbar

Set this to 1 to display remove space between each bar.

 -spacingbar => 0, # 0 or 1

Default : 1

Name: Outlinebar
Class: OutlineBar
Switch: -outlinebar

Change color of border bars.

  -outlinebar => 'blue',

Default : 'black'

WIDGET-SPECIFIC OPTIONS like Tk::Chart::Areas

Name: Viewsection
Class: ViewSection
Switch: -viewsection

If set to true value, we will see area sections separate by dash lines.

 -viewsection => 1, # 0 or 1

Default : 0

Name: Outlinearea
Class: OutlineArea
Switch: -outlinearea

Change color of border area.

  -outlinearea => 'blue',

Default : 'black'

WIDGET METHODS

The Canvas method creates a widget object. This object supports the configure and cget methods described in Tk::options which can be used to enquire and modify the options described above.

add_data

$chart->add_data(\@NewData, ?$legend)

This method allows you to add data in your graph. If you have already plot data using plot method and if you want to add new data, you can use this method. Your graph will be updade.

  • Data array reference

    Fill an array of arrays with the values of the datasets (\@data). Make sure that every array has the same size, otherwise Tk::Chart::Lines will complain and refuse to compile the graph.

     my @NewData = (1,10,12,5,4);
     $chart->add_data(\@NewData);

    If your last graph has a legend, you have to add a legend entry for the new dataset. Otherwise, the legend graph will not be display (see below).

  • $legend

     my @NewData = (1,10,12,5,4);
     my $legend = 'New data set';
     $chart->add_data(\@NewData, $legend);

clearchart

$chart->clearchart

This method allows you to clear the graph. The canvas will not be destroy. It's possible to redraw your last graph using the redraw method.

delete_balloon

$chart->delete_balloon

If you call this method, you disable help identification which has been enabled with set_balloon method.

disabled_automatic_redraw

$chart->disabled_automatic_redraw

When the graph is created and the widget size changes, the graph is automatically re-created. Call this method to avoid resizing.

  $chart->disabled_automatic_redraw;  

display_order

$chart->display_order(?\@types)

Manage the display order of the various graphs.

  $chart->display_order( [qw/ bars areas lines dashlines points /] );

In this example, the bars will be in the background, followed by areas, lines, dashlines and points.

  $chart->display_order; # Default configuration

Default : [qw/ areas bars lines dashlines points /]

display_values

$chart->display_values(\@data_point_value)

To plot the value of data near the point (Line, Spline, Point, Area graph), call this method to control in a generic manner.

  my @data_point_value = (
    [ 9,   2,   5,     6,   3,   1,   1,   3,   4 ],        # The first line data
    undef,                                                  # The second line data
    [ 'A', 'B', undef, 'D', 'E', 'F', 'G', 'H', undef ],    # The third line data
  );
  $chart->display_values( \@data_point_value );

In this example, values are added above each point of the first and third graph. The second line is undef, no values are printed in the graph. B value is printed above the second point of the third line data.

enabled_automatic_redraw

$chart->enabled_automatic_redraw

Use this method to allow your graph to be recreated automatically when the widget size change. When the graph is created for the first time, this method is called.

  $chart->enabled_automatic_redraw;  

plot

$chart->plot(\@data, ?arg)

To display your graph the first time, plot the graph by using this method.

  • \@data

    Fill an array of arrays with the x values and the values of the datasets (\@data). Make sure that every array have the same size, otherwise Tk::Chart::Mixed will complain and refuse to compile the graph.

     my @data = (
         [ '1st', '2nd', '3rd', '4th', '5th', '6th', '7th', '8th', '9th' ],
         [ 1,     2,     5,     6,     3,     1.5,   1,     3,     4  ],
         [ 4,     2,     5,     2,     3,     5.5,   7,     9,     4  ],
         [ 1,     2,     52,    6,     3,     17.5,  1,     43,    10 ]
     );

    @data have to contain a least two arrays, the x values and the values of the datasets.

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

     [ 1,     undef,     5,     6,     3,     1.5,   undef,     3,     4 ]
  • -substitutionvalue => real number,

    If you have a no real number value in a dataset, it will be replaced by a constant value.

    Default : 0

     my @data = (
          [     '1st',   '2nd', '3rd', '4th', '5th', '6th', '7th', '8th', '9th' ],
          [         1,    '--',     5,     6,     3,   1.5,     1,     3,     4 ],
          [ 'mistake',       2,     5,     2,     3,  'NA',     7,     9,     4 ],
          [         1,       2,    52,     6,     3,  17.5,     1,    43,     4 ],
     );
     $chart->plot( \@data,
       -substitutionvalue => '12',
     );
      # mistake, -- and NA will be replace by 12

    -substitutionvalue have to be a real number (Eg : 12, .25, 02.25, 5.2e+11, ...)

redraw

Redraw the graph.

If you have used clearchart for any reason, it is possible to redraw the graph. Tk::Chart::Mixed supports the configure and cget methods described in the Tk::options manpage. If you use configure method to change a widget specific option, the modification will not be display. If the graph was already displayed and if you not resize the widget, call redraw method to resolv the bug.

  ...
  $mw->Button(
  -text    => 'Change xlabel', 
  -command => sub { 
      $chart->configure(-xlabel => 'red'); 
    }, 
  )->pack;
  ...
  # xlabel will be changed but not displayed if you not resize the widget.
    
  ...
  $mw->Button(
    -text => 'Change xlabel', 
    -command => sub { 
      $chart->configure(-xlabel => 'red'); 
      $chart->redraw; 
    } 
  )->pack;
  ...
  # OK, xlabel will be changed and displayed without resize the widget.

set_balloon

$chart->set_balloon(? %options)

If you call this method, you enable help identification. When the mouse cursor passes over a plotted line or its entry in the legend, the line and its entry will be turn into a color (that you can change) to help the identification. set_legend method must be set if you want to enabled identification.

  • -background => string

    Set a background color for the balloon.

     -background => 'red',

    Default : snow

  • -colordatamouse => Array reference

    Specify an array reference wich contains 2 colors. The first color specifies the color of the line when mouse cursor passes over a entry in the legend. If the line has the same color, the second color will be used.

     -colordatamouse => ['blue', 'green'],

    Default : -colordatamouse => [ '#7F9010', '#CB89D3' ]

set_legend

$chart->set_legend(? %options)

View a legend for the graph and allow to enabled identification help by using set_balloon method.

  • -title => string

    Set a title legend.

     -title => 'My title',

    Default : undef

  • -titlecolors => string

    Set a color to legend text.

     -titlecolors => 'red',

    Default : black

  • -titlefont => string

    Set the font to legend title text.

     -titlefont => '{Arial} 8 {normal}',

    Default : {Times} 8 {bold}

  • -legendcolor => color

    Color of legend text.

     -legendcolor => 'white',

    Default : 'black'

  • -legendfont => string

    Set the font to legend text.

     -legendfont => '{Arial} 8 {normal}',

    Default : {Times} 8 {normal}

  • -box => boolean

    Set a box around all legend.

     -box => 1, # or 0

    Default : 0

  • -legendmarkerheight => integer

    Change the heigth of marker for each legend entry.

     -legendmarkerheight => 5,

    Default : 10

  • -legendmarkerwidth => integer

    Change the width of marker for each legend entry.

     -legendmarkerwidth => 5,

    Default : 10

  • -heighttitle => integer

    Change the height title legend space.

     -heighttitle => 75,

    Default : 30

zoom

$chart->zoom(integer);

Zoom the graph. The x-axis and y-axis will be zoomed. If your graph has a 300*300 size, after a zoom(200), the graph will have a 600*600 size.

  $chart->zoom(50); # size divide by 2 => 150*150
  ...
  $chart->zoom(200); # size multiplie by 2 => 600*600
  ...
  $chart->zoom(120); # 20% add in each axis => 360*360
  ...
  $chart->zoom(100); # original resize 300*300. 

zoomx

Zoom the graph the x-axis.

 # original canvas size 300*300
 $chart->zoomx(50); # new size : 150*300
 ...
 $chart->zoom(100); # new size : 300*300

zoomy

Zoom the graph the y-axis.

 # original canvas size 300*300
 $chart->zoomy(50); # new size : 300*150
 ...
 $chart->zoom(100); # new size : 300*300

EXAMPLES

In the demo directory, you have a lot of script examples with their screenshot. See also the http://search.cpan.org/dist/Tk-Chart/MANIFEST web page of Tk::Chart.

SEE ALSO

See Tk::Canvas for details of the standard options.

See Tk::Chart, Tk::Chart::FAQ, GD::Graph, Tk::Graph.

AUTHOR

Djibril Ousmanou, <djibel at cpan.org>

BUGS

Please report any bugs or feature requests to bug-Tk-Chart at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Tk-Chart. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Tk::Chart::Mixed

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2011 Djibril Ousmanou, all rights reserved.

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