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
55 using 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,
77 using 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
100 order, cycling through if there are more slices than colors in
101 the list. Colors are specified in the same format as the -back‐
102 ground 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
114 example, 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
141 described 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
148 described 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
161 (referred to as sliceObject in this document). The slice color
162 is 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
165 object identifier will be used for sizing and resizing the
166 slice.
167 If the label text is not specified, it will be set to "slice n",
169 n being the number of the slice in the order of creation (first
170 slice is number 1).
171 pie::deleteSlice pieObject sliceObject
173 Deletes a slice. The following slices (clockwise) if any are
174 then moved to compensate for the empty space left by the deleted
175 slice.
176 pie::sizeSlice pieObject sliceObject unitShare ?displayedValue?
178 Sizes or resizes a slice. The slice is then automatically recal‐
179 culated so it occupies the proper share of the whole pie. The
180 unitShare parameter is a floating point number expressed in
181 share (between 0 and 1) of the whole pie. The following slices
182 (clockwise) are moved to accommodate the new slice size. The
183 slice size value next to the slice label is also updated with
184 the new share value or displayedValue if specified.
185 pie::labelSlice pieObject sliceObject string
187 Updates a slice label. Can be invoked at any time.
188 pie::selectedSlices pieObject
190 Returns a list of currently selected slice objects.
191
193 The whole pie, the pie graphics (all slices), and each slice have the
194 following specific tags:
195 · pie(pieObject)
197 · pieSlices(pieObject)
199 · slice(sliceObject)
201 For example, the whole pie can be moved using the canvas move command
203 on the pie tag, or bindings on slices can be set using the slice tags
204 (see the canvas manual page ITEM IDS AND TAGS section for more informa‐
205 tion).
206
208 All sizes related to pies are stored as floating point numbers. The
209 coordinates and sizes are specified in screen units, which are floating
210 point numbers optionally followed by one of several letters as speci‐
211 fied in the canvas COORDINATES manual section.
212
214 If the number of slices is too big, identical colors will be used for
215 some of the slices. You may set your own colors in this case.
216
218 canvasLabel, pieBoxLabeler, piePeripheralLabeler
219
221 canvas, labeler, pie, slice
222
224 Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free.fr>
225tkpiechart 6.6 pie(n)