NAME
Tk::Chart::Bars - Extension of Canvas widget to create bars graph.
SYNOPSIS
#!/usr/bin/perl
use strict;
use warnings;
use Tk;
use Tk::Chart::Bars;
my $mw = new MainWindow(
-title => 'Tk::Chart::Bars example',
-background => 'white',
);
my $Chart = $mw->Bars(
-title => 'My graph title',
-xlabel => 'X Label',
-ylabel => 'Y Label',
-background => 'snow',
)->pack(qw / -fill both -expand 1 /);
my @data = (
[ '1st', '2nd', '3rd', '4th', '5th', '6th', '7th', '8th', '9th' ],
[ 1, 2, 5, 6, 3, 1, 1, 3, 4 ],
[ 4, 2, 5, 2, 3, 5, 7, 9, 12 ],
[ 1, 2, 12, 6, 3, 5, 1, 23, 5 ]
);
# Add a legend to the graph
my @Legends = ( 'legend 1', 'legend 2', 'legend 3' );
$Chart->set_legend(
-title => 'Title legend',
-data => \@Legends,
-titlecolors => 'blue',
);
# Add help identification
$Chart->set_balloon();
# Create the graph
$Chart->plot( \@data );
MainLoop();
DESCRIPTION
Tk::Chart::Bars is an extension of the Canvas widget. It is an easy way to build an interactive bar 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 bar or its entry in the legend, the bar 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).
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: 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::Lines
Many options allow you to configure your graph as you want. The default configuration is already OK, but you can change it. these are the same option as Tk::Chart::Lines module
- Name: Title
- Class: Title
- Switch: -title
-
Title of your graph.
-title => 'My graph title',
Default : undef
- Name: Titleposition
- Class: TitlePosition
- Switch: -titleposition
-
Position of title : center, left or right
-titleposition => 'left',
Default : center
- Name: Titlecolor
- Class: TitleColor
- Switch: -titlecolor
-
Title color of your graph.
-titlecolor => 'red',
Default : black
- Name: Titlefont
- Class: TitleFont
- Switch: -titlefont
-
Set the font for the title text. See also textfont option.
-titlefont => 'Times 15 {normal}',
Default : {Times} 12 {bold}
- Name: Titleheight
- Class: TitleHeight
- Switch: -titleheight
-
Height for title graph space.
-titleheight => 100,
Default : 40
- Name: Xlabel
- Class: XLabel
- Switch: -xlabel
-
The label to be printed just below the x axis.
-xlabel => 'X label',
Default : undef
- Name: Xlabelcolor
- Class: XLabelColor
- Switch: -xlabelcolor
-
Set x label color. See also textcolor option.
-xlabelcolor => 'red',
Default : black
- Name: Xlabelfont
- Class: XLabelFont
- Switch: -xlabelfont
-
Set the font for the x label text. See also textfont option.
-xlabelfont => 'Times 15 {normal}',
Default : {Times} 10 {bold}
- Name: Xlabelheight
- Class: XLabelHeight
- Switch: -xlabelheight
-
Height for x label space.
-xlabelheight => 50,
Default : 30
- Name: Xlabelskip
- Class: XLabelSkip
- Switch: -xlabelskip
-
Print every xlabelskip number under the tick on the x axis. If you have a dataset wich contain many points, the tick and x values will be overwrite on the graph. This option can help you to clarify your graph. Eg:
# ['leg1', 'leg2', ...'leg1000', 'leg1001', ... 'leg2000'] => There are 2000 ticks and text values on x axis. -xlabelskip => 1 => ['leg1', 'leg3', 'leg5', ...] # => 1000 ticks will be display.
See also -xvaluesregex option.
-xlabelskip => 2,
Default : 0
- Name: Xvaluecolor
- Class: XValueColor
- Switch: -xvaluecolor
-
Set x values colors. See also textcolor option.
-xvaluecolor => 'red',
Default : black
- Name: Xvaluespace
- Class: XValueSpace
- Switch: -xvaluespace
-
Width for x values space.
-xvaluespace => 50,
Default : 30
- Name: Xvalueview
- Class: XvalueView
- Switch: -xvalueview
-
View values on x axis.
-xvalueview => 0, # 0 or 1
Default : 1
- Name: Xvaluesregex
- Class: XValuesRegex
- Switch: -xvaluesregex
-
View the x values which will match with regex. It allows you to display tick on x axis and values that you want. You can combine it with -xlabelskip to perform what you want to display if you have many dataset.
... ['leg1', 'leg2', 'data1', 'data2', 'symb1', 'symb2'] ... -xvaluesregex => qr/leg/i,
On the graph, just leg1 and leg2 will be display.
Default : qr/.+/
- Name: Ylabel
- Class: YLabel
- Switch: -ylabel
-
The labels to be printed next to y axis.
-ylabel => 'Y label',
Default : undef
- Name: Ylabelcolor
- Class: YLabelColor
- Switch: -ylabelcolor
-
Set the color of y label. See also textcolor option.
-ylabelcolor => 'red',
Default : black
- Name: Ylabelfont
- Class: YLabelFont
- Switch: -ylabelfont
-
Set the font for the y label text. See also textfont option.
-ylabelfont => 'Times 15 {normal}',
Default : {Times} 10 {bold}
- Name: Ylabelwidth
- Class: YLabelWidth
- Switch: -ylabelwidth
-
Width of space for y label.
-ylabelwidth => 30,
Default : 5
- Name: Yvaluecolor
- Class: YValueColor
- Switch: -yvaluecolor
-
Set the color of y values. See also valuecolor option.
-yvaluecolor => 'red',
Default : black
- Name: Yvalueview
- Class: YvalueView
- Switch: -yvalueview
-
View values on y axis.
-yvalueview => 0, # 0 or 1
Default : 1
- Name: Labelscolor
- Class: LabelsColor
- Switch: -labelscolor
-
Combine xlabelcolor and ylabelcolor options. See also textcolor option.
-labelscolor => 'red',
Default : undef
- Name: Valuescolor
- Class: ValuesColor
- Switch: -valuescolor
-
Set the color of x, y values in axis. It combines xvaluecolor and yvaluecolor options.
-valuescolor => 'red',
Default : undef
- Name: Textcolor
- Class: TextColor
- Switch: -textcolor
-
Set the color of x, y labels and title text. It combines titlecolor, xlabelcolor and ylabelcolor options.
-textcolor => 'red',
Default : undef
- Name: Textfont
- Class: TextFont
- Switch: -textfont
-
Set the font of x, y labels and title text. It combines titlefont, xlabelfont and ylabelfont options.
-textfont => 'Times 15 {normal}',
Default : undef
- Name: Longticks
- Class: LongTicks
- Switch: -longticks
-
If long_ticks is a true value, ticks will be drawn the same length as the axes.
-longticks => 1, # 0 or 1
Default : 0
- Name: Boxaxis
- Class: BoxAxis
- Switch: -boxaxis
-
Draw the axes as a box.
-boxaxis => 0, # 0 or 1
Default : 1
- Name: Noaxis
- Class: NoAxis
- Switch: -noaxis
-
Hide the axis with ticks and values ticks.
-noaxis => 1, # 0 or 1
Default : 0
- Name: Zeroaxis
- Class: ZeroAxis
- Switch: -zeroaxis
-
If set to a true value, the axis for y values will only 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 zeroaxisonly and boxaxis).
-zeroaxis => 1, # 0 or 1
Default : 0
- Name: Zeroaxisonly
- Class: ZeroAxisOnly
- Switch: -zeroaxisonly
-
If set to a true value, the zero x axis will be drawn and no axis at the bottom of the graph will be drawn. The labels for X values will be placed on the zero x axis. This works if there is at least one negative value in dataset.
-zeroaxisonly => 1, # 0 or 1
Default : 0
- Name: Xtickheight
- Class: XTickHeight
- Switch: -xtickheight
-
Set height of all x ticks.
-xtickheight => 10,
Default : 5
- Name: Xtickview
- Class: XTickView
- Switch: -xtickview
-
View x ticks of graph.
-xtickview => 0, # 0 or 1
Default : 1
- Name: Yticknumber
- Class: YTickNumber
- Switch: -yticknumber
-
Number of ticks to print for the Y axis.
-yticknumber => 10,
Default : 4
- Name: Ytickwidth
- Class: YtickWidth
- Switch: -ytickwidth
-
Set width of all y ticks.
-ytickwidth => 10,
Default : 5
- Name: Ytickview
- Class: YTickView
- Switch: -ytickview
-
View y ticks of graph.
-ytickview => 0, # 0 or 1
Default : 1
- Name: Alltickview
- Class: AllTickView
- Switch: -alltickview
-
View all ticks of graph. Combines xtickview and ytickview options.
-alltickview => 0, # 0 or 1
Default : undef
- Name: Linewidth
- Class: LineWidth
- Switch: -linewidth
-
Set width of all lines graph of dataset.
-linewidth => 10,
Default : 1
- Name: Colordata
- Class: ColorData
- Switch: -colordata
-
This controls the colors of the lines. This should be a reference to an array of color names.
-colordata => [ qw(green pink blue cyan) ],
Default :
[ 'red', 'green', 'blue', 'yellow', 'purple', 'cyan', '#996600', '#99A6CC', '#669933', '#929292', '#006600', '#FFE100', '#00A6FF', '#009060', '#B000E0', '#A08000', 'orange', 'brown', 'black', '#FFCCFF', '#99CCFF', '#FF00CC', '#FF8000', '#006090', ],
The default array contains 24 colors. If you have more than 24 samples, the next line will have the color of the first array case (red).
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.
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;
delete_balloon
- $Chart->delete_balloon
-
If you call this method, you disable help identification which has been enabled with set_balloon method.
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::Bars 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 cleargraph for any reason, it is possible to redraw the graph. Tk::Chart::Bars 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.
...
$fenetre->Button(-text => 'Change xlabel', -command => sub {
$Chart->configure(-xlabel => 'red');
}
)->pack;
...
# xlabel will be changed but not displayed if you not resize the widget.
...
$fenetre->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}
-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 => 0,
Default : 1
-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
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($zoom);
$zoom must be an integer great than 0.
$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
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.
EXAMPLES
overwrite option
#!/usr/bin/perl
use strict;
use warnings;
use Tk;
use Tk::Chart::Bars;
my $mw = new MainWindow(
-title => 'Tk::Chart::Bars - overwrite',
-background => 'white',
);
my $Chart = $mw->Bars(
-title => 'My graph title - overwrite',
-xlabel => 'X Label',
-ylabel => 'Y Label',
-overwrite => 1
)->pack(qw / -fill both -expand 1 /);
my @data = (
[ '1st', '2nd', '3rd', '4th', '5th', '6th', '7th', '8th', '9th' ],
[ 4, 0, 16, 2, 3, 5.5, 7, 5, 02 ],
[ 1, 2, 4, 6, 3, 17.5, 1, 20, 10 ]
);
# Create the graph
$Chart->plot( \@data );
MainLoop();
Cumulate and create a zoom Menu with the graph.
#!/usr/bin/perl
use strict;
use warnings;
use Tk;
use Tk::Chart::Bars;
my $mw = new MainWindow(
-title => 'Tk::Chart::Bars - cumulate + zoom menu',
-background => 'white',
);
my $Chart = $mw->Bars(
-title => 'My graph title',
-xlabel => 'X Label',
-ylabel => 'Y Label',
-linewidth => 2,
-zeroaxisonly => 1,
-cumulate => 1,
)->pack(qw / -fill both -expand 1 /);
my @data = (
[ '1st', '2nd', '3rd', '4th', '5th', '6th', '7th', '8th', '9th' ],
[ 1, 2, 5, 6, 3, 1.5, 1, 3, 4 ],
[ 4, 0, 16, 2, 3, 5.5, 7, 5, 02 ],
[ 1, 2, 4, 6, 3, 17.5, 1, 20, 10 ]
);
# Add a legend to our graph
my @Legends = ( 'legend 1', 'legend 2', 'legend 3' );
$Chart->set_legend(
-title => 'Title legend',
-data => \@Legends,
-titlecolors => 'blue',
);
# I can see the legend text when mouse pass on line and
# the line change color when mouse pass on legend text
$Chart->set_balloon();
# Create the graph
$Chart->plot( \@data );
$Chart->add_data( [ 1 .. 9 ], 'leg4' );
my $menu = Menu( $Chart, [qw/30 50 80 100 150 200/] );
MainLoop();
sub CanvasMenu {
my ( $Canvas, $x, $y, $CanvasMenu ) = @_;
$CanvasMenu->post( $x, $y );
return;
}
sub Menu {
my ( $Chart, $RefData ) = @_;
my %MenuConfig = (
-tearoff => 0,
-takefocus => 1,
-background => 'white',
-menuitems => [],
);
my $Menu = $Chart->Menu(%MenuConfig);
$Menu->add( 'cascade', -label => 'Zoom' );
$Menu->add( 'cascade', -label => 'Zoom X-axis' );
$Menu->add( 'cascade', -label => 'Zoom Y-axis' );
my $SsMenuZoomX = $Menu->Menu(%MenuConfig);
my $SsMenuZoomY = $Menu->Menu(%MenuConfig);
my $SsMenuZoom = $Menu->Menu(%MenuConfig);
for my $Zoom ( @{$RefData} ) {
$SsMenuZoom->add(
'command',
-label => "$Zoom \%",
-command => sub { $Chart->zoom($Zoom); }
);
$SsMenuZoomX->add(
'command',
-label => "$Zoom \%",
-command => sub { $Chart->zoomx($Zoom); }
);
$SsMenuZoomY->add(
'command',
-label => "$Zoom \%",
-command => sub { $Chart->zoomy($Zoom); }
);
}
$Menu->entryconfigure( 'Zoom X-axis', -menu => $SsMenuZoomX );
$Menu->entryconfigure( 'Zoom Y-axis', -menu => $SsMenuZoomY );
$Menu->entryconfigure( 'Zoom', -menu => $SsMenuZoom );
$Chart->Tk::bind( '<ButtonPress-3>',
[ \&CanvasMenu, Ev('X'), Ev('Y'), $Menu, $Chart ] );
return $Menu;
}
No spacingbar and show values
#!/usr/bin/perl
use strict;
use warnings;
use Tk;
use Tk::Chart::Bars;
my $mw = new MainWindow(
-title => 'Tk::Chart::Bars - no spacingbar',
-background => 'white',
);
my $Chart = $mw->Bars(
-title => 'My graph title',
-xlabel => 'X Label',
-ylabel => 'Y Label',
-spacingbar => 0,
-showvalues => 1,
)->pack(qw / -fill both -expand 1 /);
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 ]
);
# Add a legend to the graph
my @Legends = ( 'legend 1', 'legend 2', 'legend 3' );
$Chart->set_legend(
-title => 'Title legend',
-data => \@Legends,
-titlecolors => 'blue',
);
# Add help identification
$Chart->set_balloon();
# Create the graph
$Chart->plot( \@data );
MainLoop();
SEE ALSO
See Tk::Canvas for details of the standard options.
See Tk::Chart, Tk::Chart::FAQ, GD::Graph, Tk::Graph.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Tk::Chart::Bars
You can also look for information at:
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
COPYRIGHT & LICENSE
Copyright 2010 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.