1pie(n)                       tkpiechart pie class                       pie(n)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

11       package require stooop  4.1
12
13       package require switched  2.2
14
15       package require tkpiechart  6.6
16
17       stooop::new pie canvas x y ?options?
18
19       switched::configure pieObject ?options?
20
21       switched::cget pieObject option
22
23       stooop::delete pieObject
24
25       pie::newSlice pieObject ?labelText?
26
27       pie::deleteSlice pieObject sliceObject
28
29       pie::sizeSlice pieObject sliceObject unitShare ?displayedValue?
30
31       pie::labelSlice pieObject sliceObject string
32
33       pie::selectedSlices pieObject
34
35______________________________________________________________________________
36

DESCRIPTION

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
45       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
52       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
57       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
63       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
67       switched::cget pieObject option
68              Returns an option value for the specified pie object.
69
70       stooop::delete pieObject
71              Deletes the specified pie object.
72

OVERVIEW

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

OPTIONS

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
87       -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
97       -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
104       -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
112       -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
122       -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
132       -title text
133              Title text to be placed above the pie.
134
135       -titlefont value
136              Font for the title text.
137
138       -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
143       -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
150       -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

MEMBER PROCEDURES

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
168              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
172       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
177       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
186       pie::labelSlice pieObject sliceObject string
187              Updates a slice label. Can be invoked at any time.
188
189       pie::selectedSlices pieObject
190              Returns a list of currently selected slice objects.
191

TAGS

193       The whole pie, the pie graphics (all slices), and each slice  have  the
194       following specific tags:
195
196       ·      pie(pieObject)
197
198       ·      pieSlices(pieObject)
199
200       ·      slice(sliceObject)
201
202       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

SIZES

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

LIMITATIONS

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

SEE ALSO

218       canvasLabel, pieBoxLabeler, piePeripheralLabeler
219

KEYWORDS

221       canvas, labeler, pie, slice
222
224       Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free.fr>
225
226
227
228
229tkpiechart                            6.6                               pie(n)
Impressum