Provided by: tklib_0.8~20230222-1_all 
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>