1pie(n) tkpiechart pie class pie(n)
2______________________________________________________________________________
6
8 pie - 2D or 3D pie chart object in a canvas
9
11 package require stooop 4.1
12 package require switched 2.2
14 package require tkpiechart 6.6
16 stooop::new pie canvas x y ?options?
18 switched::configure pieObject ?options?
20 switched::cget pieObject option
22 stooop::delete pieObject
24 pie::newSlice pieObject ?labelText?
26 pie::deleteSlice pieObject sliceObject
28 pie::sizeSlice pieObject sliceObject unitShare ?displayedValue?
30 pie::labelSlice pieObject sliceObject string
32 pie::selectedSlices pieObject
34______________________________________________________________________________
36
38 A pie object is used to visualize a set of values, usually as shares of
39 a total. Each value is represented by a colored slice, which may have a
40 2 dimensional or 3 dimensional look. Each slice is associated with a
41 label displaying the data name, and a numerical field showing the per‐
42 centage taken by the slice. The labels are placed by the chosen labeler
43 object (-labeler option). Each label color matches its related slice.
44 A pie chart is made of Tk canvas items, found in pieBoxLabeler, piePe‐
46 ripheralLabeler and canvasLabel objects, that compose the pie object.
47 The pie constructor creates the pie itself and its background slice
48 within the parent canvas. Once the pie object exists, slices can be
49 created and resized. At the time the pie is created, the parent Tk can‐
50 vas widget must exist.
51 Slice colors are automatically generated, using a default color list
53 for all pies, unless another list is used (using the -colors option).
54 When a 3D look is used, the slice edge is darker than its top while us‐
55 ing the same color tone.
56 stooop::new pie canvas x y ?options?
58 Creates a pie object in the specified Tk canvas. The upper left
59 corner of the pie is placed at the specified coordinates in the
60 canvas. The pie object identifier is returned (referred to as
61 pieObject in this document).
62 switched::configure pieObject ?options?
64 Configures a pie object or returns all the options with their
65 current values if no options are passed as parameters.
66 switched::cget pieObject option
68 Returns an option value for the specified pie object.
69 stooop::delete pieObject
71 Deletes the specified pie object.
72
74 The pie class is part of the tkpiechart extension that allows the pro‐
75 grammer to create and dynamically update 2D or 3D pie charts in a
76 Tcl/Tk application. The tkpiechart package is written in Tcl only, us‐
77 ing object oriented techniques thanks to the stooop package, included
78 in tcllib.
79
81 -autoupdate boolean
82 Boolean value specifying whether all the slices and their labels
83 are redrawn when a slice size is changed. On by default. Turn it
84 off and invoke pie::update if you change many slices at once and
85 want to improve performance.
86 -background color
88 Slices may or may not fill up the 100% of the pie. The unoccu‐
89 pied part of the pie is a slice that takes 100% of the pie. It
90 is by default transparent with a black border. The color of this
91 background slice may be set by the user using color names as in
92 the -background standard option (see the Tk options manual page
93 for more details). When the pie has a 3D look, the background of
94 a slice edge is darker than the top and uses the same color
95 tone.
96 -colors list
98 Specifies a list of colors for slices. In this case, the slice
99 colors will successively be drawn from the list in the list or‐
100 der, cycling through if there are more slices than colors in the
101 list. Colors are specified in the same format as the -background
102 option.
103 -height value
105 Specifies the total height for the pie, including the room taken
106 by the labeler labels. The pie slices are resized when labels
107 are added or deleted (when adding or deleting slices) so that
108 the total height remains constant. This value may be specified
109 in any of the forms described in the canvas COORDINATES manual
110 section.
111 -labeler object
113 Specifies a placer object for the slice labels, so that, for ex‐
114 ample, slice values may be placed next to them. If not speci‐
115 fied, the pieBoxLabeler (see corresponding manual) is used, the
116 other option being the piePeripheralLabeler class. Each labeler
117 has a specific behavior which may be set via its options. The
118 labeler object is automatically deleted when the pie object is
119 itself deleted. The labeler cannot be changed once the pie is
120 created.
121 -selectable boolean
123 Boolean value specifying whether slices are selectable or not.
124 Acceptable values are those defined by the Tcl language itself
125 for boolean values. If selectable, slices can be selected with
126 the first mouse button, by clicking on either the slice or its
127 label. Selection can be extended by using the classical control
128 or shift clicks. The list of currently selected slices can be
129 retrieved at any time using the selectedSlices pie class member
130 procedure.
131 -title text
133 Title text to be placed above the pie.
134 -titlefont value
136 Font for the title text.
137 -titleoffset value
139 Distance between the bottom of the title text and the top of the
140 pie slices. This value may be specified in any of the forms de‐
141 scribed in the sizes section below.
142 -thickness value
144 The thickness is set to 0 by default, giving the pie a simple 2D
145 shape, much faster to display. A positive thickness value will
146 give the pie a 3D look with matched darker colors for the slices
147 edges. These values may be specified in any of the forms de‐
148 scribed in the SIZES section below.
149 -width value
151 Specifies the total width for the pie, including the room taken
152 by the labeler labels. The pie slices are resized when labels
153 are added or deleted (when adding or deleting slices) so that
154 the total width remains constant. This value may be specified in
155 any of the forms described in the canvas COORDINATES manual sec‐
156 tion.
157
159 pie::newSlice pieObject ?labelText?
160 Creates a slice. A unique object identifier is returned (re‐
161 ferred to as sliceObject in this document). The slice color is
162 automatically allocated and the slice label placed using the
163 specified labeler (using the -labeler option). The slice itself
164 is placed after (clockwise) the existing slices. The slice ob‐
165 ject identifier will be used for sizing and resizing the slice.
166 If the label text is not specified, it will be set to "slice n",
168 n being the number of the slice in the order of creation (first
169 slice is number 1).
170 pie::deleteSlice pieObject sliceObject
172 Deletes a slice. The following slices (clockwise) if any are
173 then moved to compensate for the empty space left by the deleted
174 slice.
175 pie::sizeSlice pieObject sliceObject unitShare ?displayedValue?
177 Sizes or resizes a slice. The slice is then automatically recal‐
178 culated so it occupies the proper share of the whole pie. The
179 unitShare parameter is a floating point number expressed in
180 share (between 0 and 1) of the whole pie. The following slices
181 (clockwise) are moved to accommodate the new slice size. The
182 slice size value next to the slice label is also updated with
183 the new share value or displayedValue if specified.
184 pie::labelSlice pieObject sliceObject string
186 Updates a slice label. Can be invoked at any time.
187 pie::selectedSlices pieObject
189 Returns a list of currently selected slice objects.
190
192 The whole pie, the pie graphics (all slices), and each slice have the
193 following specific tags:
194 • pie(pieObject)
196 • pieSlices(pieObject)
198 • slice(sliceObject)
200 For example, the whole pie can be moved using the canvas move command
202 on the pie tag, or bindings on slices can be set using the slice tags
203 (see the canvas manual page ITEM IDS AND TAGS section for more informa‐
204 tion).
205
207 All sizes related to pies are stored as floating point numbers. The co‐
208 ordinates and sizes are specified in screen units, which are floating
209 point numbers optionally followed by one of several letters as speci‐
210 fied in the canvas COORDINATES manual section.
211
213 If the number of slices is too big, identical colors will be used for
214 some of the slices. You may set your own colors in this case.
215
217 canvasLabel, pieBoxLabeler, piePeripheralLabeler
218
220 canvas, labeler, pie, slice
221
223 Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free.fr>
224tkpiechart 6.6 pie(n)