Author: Jean-Luc Fontaine
Description: user and reference manual for using the tkpiechart Tcl extension

# tkpiechart

### Contents

- About this document
- Introduction
- Required software
- Architecture
- Classes

- pie
- pieBoxLabeler
- piePeripheralLabeler
- canvasLabel

- Future developments
- Miscellaneous information

### About this document

This document contains general information, reference information and examples designed to help the programmer use the tkpiechart Tcl extension.

### Introduction

Tkpiechart is a Tcl only extension that allows the programmer to create and dynamically update 2D or 3D pie charts in a Tcl/Tk application (obviously Tk is required).

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/.

### Required software

For the current version (5.4), the following packages must be installed before attempting to use tkpiechart (make sure to check the INSTALL file for the latest information):

- Tcl/Tk version 8.0 or above (at http://www.scriptics.com/)

The stooop library source file is included, but should you want to get more information on that extension, you could find the latest version at http://jfontain.free.fr/.

If you want to use tkpiechart as a Tcl package, you must get the stooop software (version 3.7, see above), 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 and tkpiechart packages are properly installed, insert the following code around the beginning of your application (before you create any pie):

    package require stooop 3.7
    namespace import stooop::*
    package require switched 1.4
    package require tkpiechart 5.4

### Architecture

The tkpiechart extension is composed of several Tcl source files, one for each class (such as pie, slice, pieBoxLabeler, ...) used to build a pie.

Tkpiechart can be installed as a Tcl package: a pkgIndex.tcl file is provided. Please refer to the INSTALL file for more information.

### Classes

#### pie

##### Synopsis:

new pie canvasPathName x y width height ?options?

##### 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 containing text describing the meaning of the value, and a numerical field showing the percentage taken by the slice. The labels are placed according to the -labeler option. Each label color matches its related slice. The pie and its labels are implemented using canvas items.

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.

##### Creation Parameters:

The constructor takes several arguments: the parent canvas, the pie coordinates and sizes, and eventually some options.

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.

##### Options:

-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.

##### Tags:

The whole pie, the pie graphics (all slices), and each slice have the following specific tags (see the canvas manual page ITEM IDS AND TAGS section for more information):

- pie($pieId)
- pieSlices($pieId)
- slice($sliceId)

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.

##### Slice creation:

Slices are created using:

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).

##### Slice resizing:

Slices are sized and resized using:

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.

##### Slice deletion:

Slices are deleted using:

pie::deleteSlice pieId sliceId

The following slices (clockwise) if any are then moved to compensate for the empty space left by the deleted slice.

##### Slice label:

Slice labels can be updated at any time using:

pie::labelSlice pieId sliceId string

##### 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 color slices in this case.
Pie resizing is not implemented (maybe when and if canvas coordinate system scaling is implemented).

#### pieBoxLabeler

A pie box style labeler class.

##### Synopsis:

new pieBoxLabeler canvasPathName ?options?

##### Description:

The pie box style labeler object is used as a slice label placer for a pie object and is passed to the pie constructor through its -labeler option (see the pie class description).

The labels are arranged in 2 columns below the pie graphics. Each label text is enclosed in 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.

##### Options:

-font
Specifies a font for the slice labels. If not specified, the default font is system dependent.

-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.

##### Tags:

The labeler has the following specific tag (see the canvas manual page ITEM IDS AND TAGS section for more information):

- pieBoxLabeler($labelerId)

#### piePeripheralLabeler

A pie peripheral style labeler class.

##### Synopsis:

new piePeripheralLabeler canvasPathName ?options?

##### Description:

The pie peripheral style labeler object is used as a slice label placer for a pie object and is passed to the pie constructor through its -labeler option (see the pie class information).

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.

##### Options:

-font
Specifies a font for the slice description labels. If not specified, the default font is system dependent.

-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 %".

##### Tags:

The labeler has the following specific tag (see the canvas manual page ITEM IDS AND TAGS section for more information):

- piePeripheralLabeler($labelerId)

#### canvasLabel

The canvas label class.

##### Synopsis:

new canvasLabel canvasPathName x y ?options?

##### Description:

The canvasLabel class brings some Tk label widget functionality to the canvas text item, such as a background and a border.

If the style (see -style option) is box, the canvasLabel is built with a background rectangle, which itself contains a bullet rectangle placed on the left side and used for selection, as the following 2 images show:

If the style is split, the canvasLabel is built with a bullet rectangle on the left side of the text, whose background 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.

##### Creation parameters:

The constructor takes several arguments: the parent canvas, the label coordinates, and eventually some options.

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.

##### Options:

-anchor
Specifies the anchor position of the rectangle and the text, relative to the positioning point. The behavior is similar to the -anchor option of the canvas text item, except that the rectangle is taken into account. The default is center.

-background
Specifies the background color of the 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
For box style, specifies the width of the embedded rectangle used for selection. For split style, 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.

-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 (also see -selectcolor option).

-selectcolor
Specifies the color of the select rectangle for box style, or the bullet rectangle for split style, when the label is selected (see -select option).

-stipple
Specifies the stipple pattern filling the rectangle, as in the -stipple option of the canvas rectangle item. There is no bitmap by default.

-style
Specifies whether the rectangle encloses the text (box style) or is placed to the left of the text (split style) as a colored marker.

-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.

-width
Specifies a maximum line length for the text, as in the -width option of the canvas text item. The default is zero.

##### Configuration:

The canvasLabel class features two member functions that can be used to configure or retrieve the configuration of the label. Their use is very similar to the configure and cget Tk widget commands, except that they take the label object identifier as the first parameter, and that configuration requires a value for each option. See the Options section for supported options.

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]

##### Tags:

The label has the following specific tag (see the canvas manual page ITEM IDS AND TAGS section for more information):

- canvasLabel($labelId)

##### Limitations:

There is no relief option.

### Future developments

- more sophisticated labeler algorithms
- other types of labelers

I welcome any suggestion for new features that you may need in your specific use of tkpiechart.

### Miscellaneous information

For downloading Tcl software (such as stooop, scwoop, moodss, ...), visit my web page.

Send your comments, complaints, ... to Jean-Luc Fontaine.