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.
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.
SEE ALSO¶
canvasLabel, pieBoxLabeler, piePeripheralLabeler
KEYWORDS¶
canvas, labeler, pie, slice
COPYRIGHT¶
Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free.fr>