pie - 2D or 3D pie chart object in a canvas

       This document, and the package it describes, will undoubtedly contain bugs and  other  problems.   Please
       report  such  in  the  category  tkpiechart  of the TklibTrackers [http://core.tcl.tk/tklib/reportlist].
       Please also report any ideas for enhancements you may have for either package and/or documentation.

       Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free.fr>

tklib                                                  6.6                                              pie(3tk)

       A  pie  object  is  used  to  visualize  a  set  of  values,  usually as shares of a total. Each value is
       represented by a colored slice, which may have a 2 dimensional or  3  dimensional  look.  Each  slice  is
       associated  with  a label displaying the data name, and a numerical field showing the percentage taken by
       the slice. The labels are placed by the chosen labeler object (-labeler option). Each label color matches
       its related slice.

       A pie chart is made of Tk canvas items, found  in  pieBoxLabeler,  piePeripheralLabeler  and  canvasLabel
       objects, that compose the pie object. The pie constructor creates the pie itself and its background slice
       within  the parent canvas. Once the pie object exists, slices can be created and resized. At the time the
       pie is created, the parent Tk canvas widget must exist.

       Slice colors are automatically generated, using a default color list for all pies, unless another list is
       used (using the -colors option). When a 3D look is used, the slice edge is  darker  than  its  top  while
       using the same color tone.

       stooop::newpiecanvasxy ?options?
              Creates a pie object in the specified Tk canvas. The upper left corner of the pie is placed at the
              specified  coordinates  in  the  canvas.  The  pie  object  identifier is returned (referred to as
              pieObject in this document).

       switched::configurepieObject ?options?
              Configures a pie object or returns all the options with their current values  if  no  options  are
              passed as parameters.

       switched::cgetpieObjectoption
              Returns an option value for the specified pie object.

       stooop::deletepieObject
              Deletes the specified pie object.

       canvas, labeler, pie, slice

       If  the  number  of  slices is too big, identical colors will be used for some of the slices. You may set
       your own colors in this case.

       pie::newSlice pieObject ?labelText?
              Creates a slice. A unique object identifier is  returned  (referred  to  as  sliceObject  in  this
              document).  The  slice  color  is  automatically  allocated  and  the slice label placed using the
              specified labeler (using the -labeler option). The slice itself is placed  after  (clockwise)  the
              existing slices. The slice object identifier will be used for sizing and resizing the slice.

              If  the  label text is not specified, it will be set to "slicen", n being the number of the slice
              in the order of creation (first slice is number 1).

       pie::deleteSlice pieObjectsliceObject
              Deletes a slice. The following slices (clockwise) if any are then  moved  to  compensate  for  the
              empty space left by the deleted slice.

       pie::sizeSlice pieObjectsliceObjectunitShare ?displayedValue?
              Sizes  or  resizes a slice. The slice is then automatically recalculated so it occupies the proper
              share of the whole pie. The unitShare parameter is a floating  point  number  expressed  in  share
              (between  0 and 1) of the whole pie. The following slices (clockwise) are moved to accommodate the
              new slice size. The slice size value next to the slice label is also updated with  the  new  share
              value or displayedValue if specified.

       pie::labelSlice pieObjectsliceObjectstring
              Updates a slice label. Can be invoked at any time.

       pie::selectedSlices pieObject
              Returns a list of currently selected slice objects.

       pie - 2D or 3D pie chart object in a canvas

-autoupdate boolean
              Boolean  value specifying whether all the slices and their labels are redrawn when a slice size is
              changed. On by default. Turn it off and invoke pie::update if you change many slices at  once  and
              want to improve performance.

       -background color
              Slices  may or may not fill up the 100% of the pie. The unoccupied part of the pie is a slice that
              takes 100% of the pie. It is by default transparent  with  a  black  border.  The  color  of  this
              background  slice  may  be set by the user using color names as in the -background standard option
              (see the Tk options manual page for more details). When the pie has a 3D look, the background of a
              slice edge is darker than the top and uses the same color tone.

       -colors list
              Specifies a list of colors for slices. In this case, the slice colors will successively  be  drawn
              from the list in the list order, cycling through if there are more slices than colors in the list.
              Colors are specified in the same format as the -background option.

       -height value
              Specifies  the  total  height for the pie, including the room taken by the labeler labels. The pie
              slices are resized when labels are added or deleted (when adding or deleting slices) so  that  the
              total  height  remains  constant. This value may be specified in any of the forms described in the
              canvasCOORDINATES manual section.

       -labeler object
              Specifies a placer object for the slice labels, so that, for example, slice values may  be  placed
              next  to  them.  If not specified, the pieBoxLabeler (see corresponding manual) is used, the other
              option being the piePeripheralLabeler class. Each labeler has a specific behavior which may be set
              via its options. The labeler object is  automatically  deleted  when  the  pie  object  is  itself
              deleted. The labeler cannot be changed once the pie is created.

       -selectable boolean
              Boolean value specifying whether slices are selectable or not. Acceptable values are those defined
              by  the  Tcl  language  itself  for boolean values. If selectable, slices can be selected with the
              first mouse button, by clicking on either the slice or its label. Selection  can  be  extended  by
              using  the  classical  control  or  shift  clicks.  The  list  of currently selected slices can be
              retrieved at any time using the selectedSlices pie class member procedure.

       -title text
              Title text to be placed above the pie.

       -titlefont value
              Font for the title text.

       -titleoffset value
              Distance between the bottom of the title text and the top of the pie slices.  This  value  may  be
              specified in any of the forms described in the sizes section below.

       -thickness value
              The  thickness is set to 0 by default, giving the pie a simple 2D shape, much faster to display. A
              positive thickness value will give the pie a 3D look with matched darker  colors  for  the  slices
              edges. These values may be specified in any of the forms described in the SIZES section below.

       -width value
              Specifies  the  total  width  for the pie, including the room taken by the labeler labels. The pie
              slices are resized when labels are added or deleted (when adding or deleting slices) so  that  the
              total  width  remains  constant.  This value may be specified in any of the forms described in the
              canvasCOORDINATES manual section.

       The  pie  class  is part of the tkpiechart extension that allows the programmer to create and dynamically
       update 2D or 3D pie charts in a Tcl/Tk application. The tkpiechart package is written in Tcl only,  using
       object oriented techniques thanks to the stooop package, included in tcllib.

       canvasLabel, pieBoxLabeler, piePeripheralLabeler

       All  sizes  related to pies are stored as floating point numbers. The coordinates and sizes are specified
       in screen units, which are floating point numbers optionally  followed  by  one  of  several  letters  as
       specified in the canvasCOORDINATES manual section.

       package require stooop4.1

       package require switched2.2

       package require tkpiechart6.6stooop::newpiecanvasxy ?options?

       switched::configurepieObject ?options?

       switched::cgetpieObjectoptionstooop::deletepieObject

       pie::newSlice pieObject ?labelText?

       pie::deleteSlice pieObjectsliceObject

       pie::sizeSlice pieObjectsliceObjectunitShare ?displayedValue?

       pie::labelSlice pieObjectsliceObjectstring

       pie::selectedSlices pieObject

________________________________________________________________________________________________________________

       The whole pie, the pie graphics (all slices), and each slice have the following specific tags:

       •      pie(pieObject)

       •      pieSlices(pieObject)

       •      slice(sliceObject)

       For  example,  the  whole  pie  can be moved using the canvasmove command on the pie tag, or bindings on
       slices can be set using the slice tags (see the canvas manual page ITEMIDSANDTAGS  section  for  more
       information).