Manual Pages for UNIX Darwin command on man pie

pie(n) tkpiechart pie class pie(n)

NAME

pie - 2D or 3D pie chart object in a canvas

SYNOPSIS

package require ssttoooooopp 44..11 package require sswwiittcchheedd 22..22 package require ttkkppiieecchhaarrtt 66..66 ssttoooooopp::::nneeww ppiiee canvas x y ?options?

sswwiittcchheedd::::ccoonnffiigguurree pieObject ?options?

sswwiittcchheedd::::ccggeett pieObject option

ssttoooooopp::::ddeelleettee 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 per-

centage taken by the slice. The labels are placed by the chosen labeler

object (-llaabbeelleerr option). Each label color matches its related slice.

A pie chart is made of Tk canvas items, found in ppiieeBBooxxLLaabbeelleerr, ppiieePPee-

rriipphheerraallLLaabbeelleerr and ccaannvvaassLLaabbeell 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 ccaann-

vvaass widget must exist. Slice colors are automatically generated, using a default color list

for all pies, unless another list is used (using the -ccoolloorrss option).

When a 3D look is used, the slice edge is darker than its top while using the same color tone. ssttoooooopp::::nneeww ppiiee 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).

sswwiittcchheedd::::ccoonnffiigguurree pieObject ?options?

Configures a pie object or returns all the options with their

current values if no options are passed as parameters.

sswwiittcchheedd::::ccggeett pieObject option

Returns an option value for the specified pie object.

ssttoooooopp::::ddeelleettee pieObject

Deletes the specified pie object.

OOVVEERRVVIIEEWW

The pie class is part of the tkpiechart extension that allows the pro-

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

-aauuttoouuppddaattee 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 ppiiee::::uuppddaattee if you change many slices at once and want to improve performance.

-bbaacckkggrroouunndd color

Slices may or may not fill up the 100% of the pie. The unoccu-

pied 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 -bbaacckkggrroouunndd standard option (see the Tk ooppttiioonnss 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.

-ccoolloorrss 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 -bbaacckk-

ggrroouunndd option.

-hheeiigghhtt 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 ccaannvvaass COORDINATES manual section.

-llaabbeelleerr object

Specifies a placer object for the slice labels, so that, for

example, slice values may be placed next to them. If not speci-

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

-sseelleeccttaabbllee 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 sseelleecctteeddSSlliicceess pie class member

procedure.

-ttiittllee text

Title text to be placed above the pie.

-ttiittlleeffoonntt value

Font for the title text.

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

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

-wwiiddtthh 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 ccaannvvaass COORDINATES manual sec-

tion. MMEEMMBBEERR PPRROOCCEEDDUURREESS

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 -llaabbeelleerr option). The slice itself

is placed after (clockwise) the existing slices. The slice object identifier will be used for sizing and resizing the slice.

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

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

The whole pie, the pie graphics (all slices), and each slice have the

following specific tags: +oppiiee((ppiieeOObbjjeecctt)) +oppiieeSSlliicceess((ppiieeOObbjjeecctt)) +osslliiccee((sslliicceeOObbjjeecctt))

For example, the whole pie can be moved using the ccaannvvaass mmoovvee

command on the pie tag, or bindings on slices can be set using

the slice tags (see the ccaannvvaass manual page ITEM IDS AND TAGS section for more information). SSIIZZEESS

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

fied in the ccaannvvaass COORDINATES manual section. LLIIMMIITTAATTIIOONNSS 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

KKEEYYWWOORRDDSS