Provided by: tklib_0.8~20230222-1_all bug

NAME

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

SYNOPSIS

       package require stooop  4.1

       package require switched  2.2

       package require tkpiechart  6.6

       stooop::new pie canvas x y ?options?

       switched::configure pieObject ?options?

       switched::cget pieObject option

       stooop::delete pieObject

       pie::newSlice pieObject ?labelText?

       pie::deleteSlice pieObject sliceObject

       pie::sizeSlice pieObject sliceObject unitShare ?displayedValue?

       pie::labelSlice pieObject sliceObject string

       pie::selectedSlices pieObject

_________________________________________________________________________________________________

DESCRIPTION

       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::new pie canvas x y ?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::configure pieObject ?options?
              Configures  a pie object or returns all the options with their current values if no
              options are passed as parameters.

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

       stooop::delete pieObject
              Deletes the specified pie object.

OVERVIEW

       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.

OPTIONS

       -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 canvas COORDINATES 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 canvas COORDINATES manual section.

MEMBER PROCEDURES

       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 "slice n", n being the number
              of the slice in the order of creation (first slice is number 1).

       pie::deleteSlice pieObject sliceObject
              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 pieObject sliceObject unitShare ?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 pieObject sliceObject string
              Updates a slice label. Can be invoked at any time.

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

TAGS

       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 canvas move command on the pie tag, or
       bindings on slices can be set using the slice tags (see the canvas manual  page  ITEM  IDS
       AND TAGS section for more information).

SIZES

       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 canvas COORDINATES manual section.

LIMITATIONS

       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.

BUGS, IDEAS, FEEDBACK

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

SEE ALSO

       canvasLabel, pieBoxLabeler, piePeripheralLabeler

KEYWORDS

       canvas, labeler, pie, slice

COPYRIGHT

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