The tkpiechart package is written using object oriented techniques thanks to the stooop package (http://jfontain.free.fr/). Pie charts are made of Tk canvas items and therefore require a parent canvas to be displayed in.
Tkpiechart is free software. You can redistribute it and/or modify it under the terms described in the COPYRIGHT file.
The tkpiechart extension is used in the moodss (Modular Object Oriented Dynamic SpreadSheet) application. HTML documentation, screen shots and the software itself are available at http://jfontain.free.fr/.
If you want to use tkpiechart as a Tcl package, you must get the stooop software version 4.0.1 or above (available at my web site), install it as a package, then install tkpiechart itself as a package (the tkpiechart INSTALL file contains the latest information on package installation procedures). Once the stooop (including switched) and tkpiechart packages are properly installed, insert the following code around the beginning of your application (before you create any pie):
package require stooop 4.1 namespace import stooop::* package require switched 2.2 package require tkpiechart 6.3
Tkpiechart can be installed as a Tcl package: a pkgIndex.tcl file is provided. Please refer to the INSTALL file for more information.
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 canvas widget must exist.
Slices colors are automatically generated, using a default color list for all pies, unless another list is used (through the -colors option). When a 3D look is used, the slice edge is darker than its top while using the same color tone.
When the pie is deleted, all the canvas items composing the pie and its labels are destroyed.
The pie coordinates are those of the upper left corner of the bounding region that encloses the pie and its labels. The coordinates can be retrieved using the pie tag (see the tags section below), which can also be used to move the pie using the canvas facilities.
The graphical part of the pie is defined using the size parameters, and has its own tag. The width and height parameters define the elliptical shape of the pie. These values may be specified in any of the forms described in the sizes section below.
-background
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, as for all slices, the background slice edge is darker than its top and uses the same color tone.
-colors
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
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 (by 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
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 description later in this document) is used, the other option being the piePeripheralLabeler class. Each labeler has a specific behavior which may be set through its constructor 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 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
Title text to be placed above the pie.
-titlefont
Font for the title text.
-titleoffset
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
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
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 (by 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 pieId ?labelText?
A unique object identifier is returned. The slice color is automatically allocated and the slice label and its current slice size in % is placed within one of the 2 labels columns below the pie graphics. 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::sizeSlice pieId sliceId unitShare ?displayedValue?
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::deleteSlice pieId sliceId
The following slices (clockwise) if any are then moved to compensate for the empty space left by the deleted slice.
pie::labelSlice pieId sliceId string
The labels are arranged in 2 columns below the pie graphics. Each label text is placed to the right of a rectangle, the background color of which matches its corresponding slice. The slice share value is placed to the right of the label text, separated by a semicolon. Each label is actually a canvasLabel object (see the canvasLabel class information for further information).
There is no need to delete a pieBoxLabeler object as it is automatically handled by the pie class.
-justify
Specified how to justify labels within their own column. Must be one of left, center or right. Defaults to left. For example, if justification is right, all column labels right edges are aligned.
-offset
Specifies the distance between the pie graphics and the closest slice label. This value may be specified in any of the forms described in the canvas COORDINATES manual section.
The slice description text labels are arranged in 2 columns below the pie graphics, whereas the slice values are placed next to the slice and actually follow the slice as the pie is updated. Each description label text is placed to the right of a rectangle, the background color of which matches its corresponding slice. Each description label is actually a canvasLabel object.
There is no need to delete a piePeripheralLabeler object as it is automatically handled by the pie class if passed as the -labeler option parameter.
-justify
Specified how to justify labels within their own column. Must be one of left, center or right. Defaults to left. For example, if justification is right, all column labels right edges are aligned.
-offset
Specifies the distance between the pie graphics and the closest slice label. This value may be specified in any of the forms described in the canvas COORDINATES manual section.
-smallfont
Specifies a font for the slice values. It is usually a small font in order to avoid values overlapping when 2 slices are very close to each other. If not specified, the description label font (-font option) is used.
-widestvaluetext
Specifies a string of maximum width for slice values (placed around the pie next to the slices), so that enough room is allocated for these value labels when the pie width and height are set. It defaults to 00.0. For example, it could be set to "00.00 %".
The canvasLabel is built with a bullet rectangle on the left side of the text, whose relief changes according to the select state, as the following 2 images show:
The label has a specific tag, which can be used to retrieve the coordinates of the object or move it, thanks to the canvas facilities.
The coordinates are those of a point used to position the label (see the -anchor option for more information). They 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.
-background
Specifies the background color of the bullet rectangle, as in the -fill option of the canvas rectangle item. The default is transparent (empty string).
-bordercolor
Specifies the border color of the rectangle, as in the -outline option of the canvas rectangle item. The default is black.
-borderwidth
Specifies the border width of the rectangle, as in the -width option of the canvas rectangle item. By default, the width is 1 pixel, which is the minimum width.
-bulletwidth
Specifies the width of the rectangle placed to the left of the text. Defaults to 10.
-font
Specifies the font of the text, as in the -font option of the canvas text item. The default is system dependent.
-foreground
Specifies the color of the text, as in the -fill option of the canvas text item. The default is black.
-justify
Specifies how to justify the text, as in the -justify option of the canvas text item. The default is left.
-minimumwidth
The total label width will not go below the specified value, but may be larger in the label text requires it.
-padding
Specifies how much space to leave between the text and the closest rectangle edge. Units are identical to those specified in the canvas COORDINATES manual section.
-scale
List of 2 floating point numbers used to set the scaling factor in the x and y axis. Scaling is applied immediately and defaults to 1.
-select
Boolean which sets the label state.
-selectrelief
Either flat, raised or sunken. Specifies the 3D effect desired for the text area when the label is selected.
-stipple
Specifies the stipple pattern filling the rectangle, as in the -stipple option of the canvas rectangle item. There is no bitmap by default.
-text
Specifies the string to be displayed in the text area, as in the -text option of the canvas text item. The default is an empty string.
-textbackground
Specifies the color of the text area background.
-width
Specifies a maximum line length for the text, as in the -width option of the canvas text item. The default is zero.
Synopsis:
switched::configure labelId option value ?option value ...?
switched::cget labelId option
examples:
switched::configure $labelId -text "Some Text" -background white set anchor [switched::cget $labelId -anchor]
Send your comments, complaints, ... to Jean-Luc Fontaine.