pie(n)                       tkpiechart pie class                       pie(n)



______________________________________________________________________________

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:

       o      pie(pieObject)

       o      pieSlices(pieObject)

       o      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>




tklib                                 6.6                               pie(n)
