|
ActiveTcl User Guide
|
|
|
[ Main table Of Contents | Tklib Table Of Contents | Tklib Index ]
pie(n) 6.6 "tkpiechart pie class"
pie - 2D or 3D pie chart object in a canvas
TABLE OF
CONTENTS
SYNOPSIS
DESCRIPTION
OVERVIEW
OPTIONS
MEMBER
PROCEDURES
TAGS
SIZES
LIMITATIONS
SEE ALSO
KEYWORDS
COPYRIGHT
package require stooop 4.1
package require switched 2.2
package require tkpiechart 6.6
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.
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.
- -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.
- 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).
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.
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.
canvasLabel , pieBoxLabeler , piePeripheralLabeler
canvas , labeler , pie , slice
Copyright © 1995-2004 Jean-Luc Fontaine
<jfontain@free.fr>