[ Tklib Table Of Contents | Tklib Index ]
pie(n) 6.6 "tkpiechart pie class"
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.
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. Please also report any ideas for enhancements you may have for either package and/or documentation.
Copyright
Copyright © 1995-2004 Jean-Luc Fontaine <jfontain@free.fr>