View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Djibril Ousmanou > Tk-Chart > Tk::Chart::Boxplots



Annotate this POD


Open  1
View/Report Bugs
Module Version: 1.06   Source  


Tk::Chart::Boxplots - Extension of Canvas widget to create boxplots graph.


  use strict;
  use warnings;
  use Tk;
  use Tk::Chart::Boxplots;
  my $mw = MainWindow->new(
    -title      => 'Tk::Chart::Boxplots example',
    -background => 'white',
  my $chart = $mw->Boxplots(
    -title      => 'My graph title',
    -xlabel     => 'X Label',
    -ylabel     => 'Y Label',
    -background => 'snow',
  )->pack(qw / -fill both -expand 1 /);
  my $one   = [ 210 .. 275 ];
  my $two   = [ 180, 190, 200, 220, 235, 245 ];
  my $three = [ 40, 140 .. 150, 160 .. 180, 250 ];
  my $four  = [ 100 .. 125, 136 .. 140 ];
  my $five  = [ 10 .. 50, 100, 180 ];
  my @data = (
    [ '1st', '2nd', '3rd',  '4th', '5th' ],
    [ $one,  $two,  $three, $four, $five ],
    [ [-25, 1..15], [-45, 25..45, 100], [70, 42..125], undef, [180..250] ],
    # ...
  # Add a legend to the graph
  my @legends = ( 'legend 1', 'legend 2' );
    -title       => 'Title legend',
    -data        => \@legends,
  # Add help identification
  # Create the graph
  $chart->plot( \@data );


Tk::Chart::Boxplots is an extension of the Canvas widget. It is an easy way to build interactive boxplots (also known as a box-and-whisker diagram or plot) graph into your Perl Tk widget. The module is written entirely in Perl/Tk.

You can set a background gradient color.

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.

When the mouse cursor passes over a boxplot, its outlier or its entry in the legend, the boxplot and its entry will be turned to a color (that you can change) to help identify it.

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


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.

      -start_color => '#6585ED',
      -end_color   => '#FFFFFF',

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


-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


Name: BoxplotLinescolor
Class: BoxplotLinesColor
Switch: -boxplotlinescolor

Color of lines of boxplots.

 -boxplotlinescolor => 'red',

Default : black

Name: Spacingbar
Class: SpacingBar
Switch: -spacingbar

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

 -spacingbar => 0, # 0 or 1

Default : 1

WIDGET-SPECIFIC OPTIONS for graphs with axes. ^



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.


$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.



Use this method if you want to get the informations about all boxplots (25th percentile (Q1), 75th percentile (Q3), smallest non-outlier, largest non-outlier, median and mean). This method returns an array reference. The informations are stored in a hash reference.

  my $ref_array_information = $chart->boxplot_information();
  # Print information of boxplot @{$data[2][3]} (2th sample, 4th data )
  print "Boxplot @{$data[2][3]} (2th sample, 4th data )\n";
  print "Outliers : @{$ref_array_information->[1][3]->{outliers}}\n";
  print '25th percentile (Q1) : ', $ref_array_information->[1][3]->{Q1}, "\n";
  print '75th percentile (Q3) :',  $ref_array_information->[1][3]->{Q3}, "\n";
  print 'Smallest non-outlier : ',
    $ref_array_information->[1][3]->{smallest_non_outlier}, "\n";
  print 'Largest non-outlier :', $ref_array_information->[1][3]->{largest_non_outlier},
  print 'Median : ', $ref_array_information->[1][3]->{median}, "\n";
  print 'Mean : ',   $ref_array_information->[1][3]->{mean},   "\n";

if you have this data :

  my @data = (
      [ '1st', '2nd', '3rd',  '4th', '5th' ],
      [ [ list data00 ],  [list data01],  [list data02], ],
      [ [ list data10 ],  [list data11],  [list data12], ],
      [ [ list data20 ],  [list data21],  [list data22], ],

To get the informations about boxplot list data21, you have to read hash reference like this :

  $ref_hash_information = $ref_array_information->[2][1];
  # 25th percentile (Q1)
  print $ref_hash_information->{Q1};
  # Smallest non-outlier
  print $ref_hash_information->{smallest_non_outlier};

The quantile is calculated with the same algorithm as Excel and type 7 quantile R package.



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.



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



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




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->plot(\@data, ?arg)

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


Redraw the graph.

If you have used clearchart for any reason, it is possible to redraw the graph. Tk::Chart::Boxplots 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.

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


$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.


$chart->set_legend(? %options)

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



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. 


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


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


In the demo directory, you have a lot of script examples with their screenshot. See also the web page of Tk::Chart.


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

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


Djibril Ousmanou, <djibel at>


Please report any bugs or feature requests to bug-Tk-Chart at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


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

    perldoc Tk::Chart::Boxplots

You can also look for information at:



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.

syntax highlighting: