pie(3tk)

💖 pie — the 2D/3D pie chart glow-up for your canvas 💖

okay bestie, so this is pie(3tk), the tkpiechart pie class — like, it's the manual page for making actual pie charts in a Tk canvas, and honestly? it's giving data visualization but make it cute. ✨

---

✨ SYNOPSIS ✨

package require stooop 4.1

package require switched 2.2

package require tkpiechart 6.6

stooop::new pie canvas x y ?options?

switched::configure pieObject ?options?

switched::cget pieObject option

stooop::delete pieObject

pie::newSlice pieObject ?labelText?

pie::deleteSlice pieObject sliceObject

pie::sizeSlice pieObject sliceObject unitShare ?displayedValue?

pie::labelSlice pieObject sliceObject string

pie::selectedSlices pieObject

like yes, that's a whole lot of package require but we ate, don't worry 🫶

---

🌸 DESCRIPTION 🌸

So a pie object is literally how you visualize a set of values, usually as shares of a total. Each value gets its own colored slice, and that slice can look 2 dimensional or 3 dimensional, your call, main character energy either way. Each slice comes with a label showing the data name, plus a numerical field showing the percentage that slice takes up. The labels get placed by whichever labeler object you picked (that's the -labeler option, iykyk). And the label color matches its related slice — coordinated, periodt. 💅

A pie chart is made of Tk canvas items, found in pieBoxLabeler, piePeripheralLabeler and canvasLabel objects, and those compose the pie object. The pie constructor creates the pie itself and its background slice inside the parent canvas. Once the pie object exists, you can create and resize slices. Heads up though: at the time the pie is created, the parent Tk canvas widget must already exist. No canvas, no pie, no exceptions. 😭

Slice colors are automatically generated using a default color list for all pies, unless you bring your own list (via the -colors option). And when you go 3D, the slice edge is darker than its top while using the same color tone — subtle, elegant, iconic. 🎀

stooop::new pie canvas x y ?options? Creates a pie object in the specified Tk canvas. The upper left corner of the pie goes at the coordinates you specify in the canvas. You get back the pie object identifier (called pieObject all over this document, so remember that name bestie).

switched::configure pieObject ?options? Configures a pie object, or if you pass no options as parameters, returns all the options with their current values.

switched::cget pieObject option Returns an option value for the specified pie object.

stooop::delete pieObject Deletes the specified pie object. bye bitch 👋 (affectionate)

---

🦋 OVERVIEW 🦋

The pie class is part of the tkpiechart extension, which lets the programmer 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, which is included in tcllib. ngl that's kind of a serve.

---

💅 OPTIONS 💅

• -autoupdate 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 pie::update if you change many slices at once and want to improve performance. (yes, the glow-up can wait, batch it.)
• -background color — 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. You can set the color of this background slice 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, the background of a slice edge is darker than the top and uses the same color tone.
• -colors 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 -background option. (bring your own palette, bestie 🎨)
• -height 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 canvas COORDINATES manual section.
• -labeler object — 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 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. so choose wisely fr fr.
• -selectable 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 selectedSlices pie class member procedure.
• -title text — Title text to be placed above the pie. 👑
• -titlefont value — Font for the title text.
• -titleoffset 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.
• -thickness 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.
• -width 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 canvas COORDINATES manual section.

---

🎀 MEMBER PROCEDURES 🎀

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 -labeler option). 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). adorable, honestly.

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

pie::labelSlice pieObject sliceObject string Updates a slice label. Can be invoked at any time. literally whenever, no rules. ✨

pie::selectedSlices pieObject Returns a list of currently selected slice objects.

---

🌈 TAGS 🌈

The whole pie, the pie graphics (all slices), and each slice have the following specific tags:

• pie(pieObject)
• pieSlices(pieObject)
• slice(sliceObject)

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 (see the canvas manual page ITEM IDS AND TAGS section for more information).

---

🧚 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 colors in this case. (so like… 47 slices, 12 colors, you do the math bestie 😭)

---

🙈 BUGS, IDEAS, FEEDBACK 🙈

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category tkpiechart of the Tklib Trackers [http://core.tcl.tk/tklib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation. (bestie they are asking, go tell them 🫶)

---

⭐ SEE ALSO ⭐

canvasLabel, pieBoxLabeler, piePeripheralLabeler

---

👑 KEYWORDS 👑

canvas, labeler, pie, slice

---

💜 COPYRIGHT 💜

Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free.fr>

---

okay that's the whole thing, no cap. this was pie(3tk) from tklib version 6.6 — go forth and make the prettiest pie charts, bestie, you're literally the main character of data viz now 💖🦋✨