NAME

Tk::Chart::Pie - Extension of Canvas widget to create a pie graph.

DESCRIPTION

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

You can set a background gradient color.

When the mouse cursor passes over a pie slice or its entry in the legend, the pie slice turn to a color (that you can change) and a balloon box display 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.

SYNOPSIS

  #!/usr/bin/perl
  use strict;
  use warnings;
  
  use Tk;
  use Tk::Chart::Pie;
  my $mw = MainWindow->new( -title => 'Tk::Chart::Pie example', );
  
  my $chart = $mw->Pie(
    -title => 'Registered public CPAN countries sites' . "\n"
      . 'around the World (266 sites, 61 countries in 19 July 2011)',
    -background => 'white',
    -linewidth  => 2,
  )->pack(qw / -fill both -expand 1 /);
  
  my @data = (
    [ 'Africa', 'Asia', 'Central America', 'Europe', 'North America', 'Oceania', 'South America' ],
    [ 2,        16,     1,                 32,       3,               3,         4 ],
  );
  
  $chart->plot( \@data );
  
  MainLoop();

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

Many options allow you to configure your graph as you want. The default configuration is already OK, but you can change it.

Name: Title

Class: Title

Switch: -title

Title of your graph.

  -title => 'My pie 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: Linewidth

Class: LineWidth

Switch: -linewidth

Set width of all lines slice pie inthe graph.

  -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 contain 24 colors. If you have more than 24 samples, the next line will have the color of the first array case (red).

Name: Piesize

Class: PieSize

Switch: -piesize

The piesize represents the size of the pie graph. It must be between 1 and 360 degrees. You can change this value to draw a pie graph in a full circle, a semicircle, quadrant...

  -piesize => 180, # Pie graph will be display in a half circle

Default : 360

Name: Startangle

Class: StartAngle

Switch: -startangle

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

  -startangle => 90,

Default : 0

Name: verbose

Class: Verbose

Switch: -verbose

Warning will be print if necessary.

  -verbose => 0,

Default : 1

Name: Legendcolor

Class: LegendColor

Switch: -legendcolor

Color of legend text.

  -legendcolor => 'white',

Default : 'black'

Name: Legendfont

Class: Legendfont

Switch: -legendfont

Font of text legend.

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

Default : {Times} 8 {normal}

Name: Setlegend

Class: SetLegend

Switch: -setlegend

If set to true value, the legend will be display.

  -setlegend => 0,

Default : 1

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.

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;

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;

clearchart

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

plot

$pie_chart->plot(\@data, ?arg): Use this method to create your pie graph.

\@data

Fill an array of arrays with the legend values and the values of the datasets (\@data). Make sure that every array have the same size, otherwise Tk::Chart::Pie will complain and refuse to compile the graph.
```
  my @data = (
     [ '1st', '2nd', '3rd', '4th', '5th', '6th', '7th', '8th', '9th' ],
     [ 1,     2,     52,    6,     3,     17.5,  1,     43,    10 ]
  );
```
@data have to contain two arrays, the legend 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 ],
  );
  $pie_chart->plot( \@data,
    -substitutionvalue => '12',
  );
  # mistake, -- and NA will be replace by 12

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

redraw

Redraw the graph.

If you have used clearchart for any reason, it is possible to redraw the graph. Tk::Chart::Pie 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 title', 
  -command => sub { 
      $pie_chart->configure(-title  => 'other title'); 
    }, 
  )->pack;
  ...
  # title will be changed but not displayed if you not resize the widget.
    
  ...
  $mw->Button(
    -text => 'Change title', 
    -command => sub { 
      $pie_chart->configure(-title  => 'other title'); 
      $pie_chart->redraw; 
    } 
  )->pack;
  ...
  # OK, title will be changed and displayed without resize the widget.

zoom

$pie_chart->zoom(integer);

Zoom the graph (vertical and horizontal zoom).

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

zoomx

Horizontal zoom.

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

zoomy

Vertical zoom.

  # original canvas size 300*300
  $pie_chart->zoomy(50); # new size : 300*150
  ...
  $pie_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.

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::Pie

You can also look for information at:

RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Tk-Chart
AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Tk-Chart
CPAN Ratings

http://cpanratings.perl.org/d/Tk-Chart
Search CPAN

http://search.cpan.org/dist/Tk-Chart/

COPYRIGHT & LICENSE

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

To install Tk::Chart, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Tk::Chart

CPAN shell

perl -MCPAN -e shell
install Tk::Chart

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

BACKGROUND GRADIENT COLOR

SYNOPSIS

STANDARD OPTIONS

WIDGET-SPECIFIC OPTIONS

WIDGET METHODS

disabled_automatic_redraw

enabled_automatic_redraw

clearchart

plot

redraw

zoom

zoomx

zoomy

EXAMPLES

SEE ALSO

AUTHOR

BUGS

SUPPORT

COPYRIGHT & LICENSE

NAME

DESCRIPTION

BACKGROUND GRADIENT COLOR

SYNOPSIS

STANDARD OPTIONS

WIDGET-SPECIFIC OPTIONS

WIDGET METHODS

disabled_automatic_redraw

enabled_automatic_redraw

clearchart

plot

redraw

zoom

zoomx

zoomy

EXAMPLES

SEE ALSO

AUTHOR

BUGS

SUPPORT

COPYRIGHT & LICENSE

Module Install Instructions