pie(n)

💖 pie(n) — the tkpiechart pie class, but make it make sense ✨

okay bestie, so this is the manual for <rainbow>pie(n)</rainbow>, aka the tkpiechart pie class — and yes it's the Tcl/Tk one, not the dessert (sadly 😭). It's giving very much "my chart ate" energy. Let's get into it 🫶

---

🌸 NAME 🌸

pie — a 2D or 3D pie chart object that lives in a canvas. That's it, that's the whole vibe 💅

---

✨ SYNOPSIS ✨

so first you gotta require the packages, and the versions matter, don't @ me:

package require stooop  4.1

package require switched  2.2

package require tkpiechart  6.6

and then the actual calls, in all their glory:

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

---

💜 DESCRIPTION 💜

So a pie object is literally there to visualize a set of values — usually as shares of a total, iykyk. Each value? That's a colored slice 🍓, and it can have a 2 dimensional or 3 dimensional look. Every slice gets a label showing the data name, plus a numerical field showing the percentage that slice takes up. The labels are placed by whichever labeler object you picked (the -labeler option), and each label's color matches its related slice. color-coordinated, main character energy 👑

A pie chart is made of Tk canvas items — found in pieBoxLabeler, piePeripheralLabeler and canvasLabel objects — that compose the pie object. The pie constructor creates the pie itself and its background slice inside the parent canvas. Once the pie object exists, slices can be created and resized. And important: at the time the pie is created, the parent Tk canvas widget must already exist. no cap, it has to be there first 🫶

Slice colors are automatically generated using a default color list for all pies — unless you use another list via the -colors option. When you go 3D, the slice edge is darker than its top, but it keeps the same color tone. aesthetic ✨

stooop::new pie canvas x y ?options? — Creates a pie object in the specified Tk canvas. The upper left corner of the pie is placed at those coordinates in the canvas. It returns the pie object identifier (referred to as pieObject in this document). 🎀

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

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

stooop::delete pieObject — Deletes the specified pie object. bye bestie 💀

---

🦋 OVERVIEW 🦋

The pie class is part of the tkpiechart extension, which lets you 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. Tcl-only, no compiled nonsense, we love that for us 💖

---

💅 OPTIONS 💅

• -autoupdate boolean — Boolean value saying whether all the slices and their labels get redrawn when a slice size changes. On by default. Turn it off and call pie::update if you're changing a bunch of slices at once and want better performance. performance queen 🏃‍♀️
• -background color — Slices may or may not fill up 100% of the pie. The unoccupied part of the pie is a slice that takes 100% of the pie. It's transparent by default with a black border. You can set the color of this background slice using color names, same as the standard -background option (peep 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 that case, slice colors get drawn successively from the list in list order, cycling through if there are more slices than colors in the list. Colors use the same format as the -background option. 🎨
• -height value — Specifies the total height for the pie, including the room taken by the labeler labels. The pie slices get resized when labels are added or deleted (i.e. when adding or deleting slices) so the total height stays 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 you don't specify one, pieBoxLabeler is used (see corresponding manual) — the other option being the piePeripheralLabeler class. Each labeler has its own specific behavior which may be set via its options. The labeler object is automatically deleted when the pie object itself is deleted. And heads up: the labeler cannot be changed once the pie is created. 🙈
• -selectable boolean — Boolean value saying whether slices are selectable or not. Acceptable values are the ones the Tcl language itself defines for boolean values. If selectable, slices can be selected with the first mouse button, by clicking either the slice or its label. Selection can be extended using the classical Ctrl 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. (that's the SIZES section, bestie, keep scrolling 💜)
• -thickness value — Thickness is set to 0 by default, which gives the pie a simple 2D shape, much faster to display. A positive thickness value gives the pie a 3D look with matched darker colors for the slice 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 get resized when labels are added or deleted (i.e. when adding or deleting slices) so the total width stays 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. Returns a unique object identifier (referred to as sliceObject in this document). The slice color is automatically allocated and the slice label is placed using the specified labeler (via the -labeler option). The slice itself is placed after (clockwise) the existing slices. That slice object identifier is what you'll use for sizing and resizing the slice. 🍰

If the label text isn't specified, it gets set to "slice n", where n is the number of the slice in the order of creation (first slice is number 1).

pie::deleteSlice pieObject sliceObject — Deletes a slice. The following slices (clockwise), if any, are then moved to compensate for the empty space the deleted slice left behind. 💀

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 as a 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 with displayedValue if you specified it. 🔥

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

---

⭐ TAGS ⭐

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

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

So 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 (peep the canvas manual page ITEM IDS AND TAGS section for more info). 💫

---

🌸 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. In that case you may set your own colors. yeah. it's giving "we ran out of crayons" 😭

---

🙈 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 at http://core.tcl.tk/tklib/reportlist. Please also report any ideas for enhancements you may have for either the package and/or the documentation. we appreciate you fr fr 🫶

---

🌈 SEE ALSO 🌈

canvasLabel, pieBoxLabeler, piePeripheralLabeler — go read those next, bestie 💖

---

🔑 KEYWORDS 🔑

canvas, labeler, pie, slice

---

👑 COPYRIGHT 👑

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

---

okay that's the whole page, no skips, no "etc." — every flag, every number, every path is in there 💅

and that's a wrap, bestie 🎀 this one's from tklib, version 6.6, and the doc itself is the pie(n) page from the tkpiechart pie class — periodt. 💖🦋