PieLib — Plan9Basic Documentation

PieLib — Pie/Wedge Shape Library

Pies are filled sectors of an ellipse defined by start and end angles. Unlike arcs, pies include the center point, creating a filled wedge shape. Ideal for pie charts, gauges, circular menus, progress meters, and decorative elements like Pac-Man. 86 functions.

Category	Count	Description
Error Handling	4	pie_error, errormsg$, strerror$, clearerror
Creation & Destruction	4	pie# (3 overloads), pie_free
Pie Angles	5	startangle, endangle (get/set), angles#
Fill	3	fill$ (get), fill# (set), fillnone#
Stroke	11	stroke$ / stroke# / strokenone#, thickness, dash, cap, join (get/set)
Position & Size	11	x, y, width, height (get/set), bounds#, move#, size#
Alignment & Margins	12	align (get/set), margin#, margins#, marginleft/top/right/bottom (get/set)
Visibility & State	8	visible, enabled, opacity, hittest (get/set)
Tag, Rotation & Parent	9	tag, rotation (get/set), parent# (get/set), bringtofront#, sendtoback#, invalidate#
Events	19	9 event types × set/get + clearcallbacks#

Cross-Platform Support

Platform	Status	Notes
Windows	✅ Full Support	Win32/Win64
Linux	✅ Full Support	GTK-based
Android	✅ Full Support	Hardware-accelerated

Error Handling

Function	Signature	Description
`pie_error()`	`pie_error@`	Last error code (0 = no error)
`pie_errormsg$()`	`pie_errormsg$@`	Last error message as string
`pie_strerror$(code)`	`pie_strerror$@n`	Description for a given error code
`pie_clearerror()`	`pie_clearerror@`	Clear the error state

Angle System

Angles are measured in degrees. The pie wedge is drawn clockwise from start angle to end angle:

Angle	Position	Clock Position
0°	Right	3 o’clock
90°	Bottom	6 o’clock
180°	Left	9 o’clock
270°	Top	12 o’clock
360°	Full circle	Back to 3 o’clock

Function	Signature	Description
`pie_startangle(pie#)`	`pie_startangle@#`	Get start angle in degrees
`pie_startangle#(pie#, angle)`	`pie_startangle#@#n`	Set start angle
`pie_endangle(pie#)`	`pie_endangle@#`	Get end angle in degrees
`pie_endangle#(pie#, angle)`	`pie_endangle#@#n`	Set end angle
`pie_angles#(pie#, start, end)`	`pie_angles#@#nn`	Set both angles at once

╯ plan9basic─◻✕
' Quarter circle starting from the right
pie_angles#(pie#, 0, 90)

' Half circle starting from the top
pie_angles#(pie#, 270, 450)

' Start from top using negative angle
pie_angles#(pie#, -90, 144)

ⓘ Note: Negative angles are supported and can simplify positioning. For example, -90 is equivalent to 270 (the top/12 o’clock position).

Pie vs Arc

Feature	Pie (PieLib)	Arc (ArcLib)
Shape	Filled wedge (includes center point)	Curved segment only
Fill	Fills the wedge area from center to edge	Fills only the arc band
Outline	Strokes wedge including radii to center	Strokes only the curved edges
Use cases	Pie charts, gauges, Pac-Man	Progress rings, speedometers

Numeric Values Reference

Control Alignment `pie_align#`

Value	Description
0	None (absolute positioning)
1	Top
2	Left
3	Right
4	Bottom
9	Client (fill parent)

Stroke Dash Style `pie_strokedash#`

Value	Style
0	Solid
1	Dash
2	Dot
3	DashDot
4	DashDotDot

Stroke Cap Style `pie_strokecap#`

Value	Style
0	Flat
1	Round

Stroke Join Style `pie_strokejoin#`

Value	Style
0	Miter
1	Round
2	Bevel

Creation & Destruction

Function	Signature	Description
`pie#(parent#)`	`pie#@#`	Create with default size
`pie#(parent#, w, h)`	`pie#@#nn`	Create with specified size
`pie#(parent#, x, y, w, h)`	`pie#@#nnnn`	Create with position and size
`pie_free(pie#)`	`pie_free@#`	Destroy pie shape

╯ plan9basic─◻✕
' Quarter-circle wedge
let pie# = pie#(frm#, 50, 50, 200, 200)
pie_startangle#(pie#, 0)
pie_endangle#(pie#, 90)
pie_fill#(pie#, "#e74c3c")
pie_stroke#(pie#, "#c0392b")
pie_strokethickness#(pie#, 2)

ⓘ Note: Use equal width and height for circular pies. Unequal dimensions create elliptical wedge shapes.

Fill Properties

Function	Signature	Description
`pie_fill$(pie#)`	`pie_fill$@#`	Get fill color as hex string
`pie_fill#(pie#, color$)`	`pie_fill#@#$`	Set fill color ("#RRGGBB" or "#AARRGGBB")
`pie_fillnone#(pie#)`	`pie_fillnone#@#`	Remove fill (transparent wedge)

Stroke Properties

Function	Signature	Description
`pie_stroke$(pie#)`	`pie_stroke$@#`	Get stroke color
`pie_stroke#(pie#, color$)`	`pie_stroke#@#$`	Set stroke color
`pie_strokenone#(pie#)`	`pie_strokenone#@#`	Remove stroke (no border)
`pie_strokethickness(pie#)`	`pie_strokethickness@#`	Get stroke thickness
`pie_strokethickness#(pie#, n)`	`pie_strokethickness#@#n`	Set stroke thickness
`pie_strokedash(pie#)`	`pie_strokedash@#`	Get dash style (0–4)
`pie_strokedash#(pie#, n)`	`pie_strokedash#@#n`	Set dash style
`pie_strokecap(pie#)`	`pie_strokecap@#`	Get cap style (0=Flat, 1=Round)
`pie_strokecap#(pie#, n)`	`pie_strokecap#@#n`	Set cap style
`pie_strokejoin(pie#)`	`pie_strokejoin@#`	Get join style (0=Miter, 1=Round, 2=Bevel)
`pie_strokejoin#(pie#, n)`	`pie_strokejoin#@#n`	Set join style

ⓘ Note: The stroke outlines the entire wedge including both radii lines from edge to center. Use pie_strokenone# for borderless pie segments in charts.

Position & Size

Function	Signature	Description
`pie_x(pie#)`	`pie_x@#`	Get X position
`pie_x#(pie#, x)`	`pie_x#@#n`	Set X position
`pie_y(pie#)`	`pie_y@#`	Get Y position
`pie_y#(pie#, y)`	`pie_y#@#n`	Set Y position
`pie_width(pie#)`	`pie_width@#`	Get width
`pie_width#(pie#, w)`	`pie_width#@#n`	Set width
`pie_height(pie#)`	`pie_height@#`	Get height
`pie_height#(pie#, h)`	`pie_height#@#n`	Set height
`pie_bounds#(pie#, x, y, w, h)`	`pie_bounds#@#nnnn`	Set position and size
`pie_move#(pie#, x, y)`	`pie_move#@#nn`	Set position only
`pie_size#(pie#, w, h)`	`pie_size#@#nn`	Set size only

Alignment & Margins

Function	Signature	Description
`pie_align(pie#)`	`pie_align@#`	Get alignment
`pie_align#(pie#, n)`	`pie_align#@#n`	Set alignment
`pie_margin#(pie#, n)`	`pie_margin#@#n`	Set uniform margin on all four sides
`pie_margins#(pie#, l, t, r, b)`	`pie_margins#@#nnnn`	Set individual margins
`pie_marginleft(pie#)`	`pie_marginleft@#`	Get left margin
`pie_marginleft#(pie#, n)`	`pie_marginleft#@#n`	Set left margin
`pie_margintop(pie#)`	`pie_margintop@#`	Get top margin
`pie_margintop#(pie#, n)`	`pie_margintop#@#n`	Set top margin
`pie_marginright(pie#)`	`pie_marginright@#`	Get right margin
`pie_marginright#(pie#, n)`	`pie_marginright#@#n`	Set right margin
`pie_marginbottom(pie#)`	`pie_marginbottom@#`	Get bottom margin
`pie_marginbottom#(pie#, n)`	`pie_marginbottom#@#n`	Set bottom margin

Visibility & State

Function	Signature	Description
`pie_visible(pie#)`	`pie_visible@#`	Get visibility (0/1)
`pie_visible#(pie#, n)`	`pie_visible#@#n`	Set visibility
`pie_enabled(pie#)`	`pie_enabled@#`	Get enabled state (0/1)
`pie_enabled#(pie#, n)`	`pie_enabled#@#n`	Set enabled state
`pie_opacity(pie#)`	`pie_opacity@#`	Get opacity (0.0–1.0)
`pie_opacity#(pie#, n)`	`pie_opacity#@#n`	Set opacity
`pie_hittest(pie#)`	`pie_hittest@#`	Get hit-test state (0/1)
`pie_hittest#(pie#, n)`	`pie_hittest#@#n`	Enable/disable mouse hit testing

⚠ Warning: Set pie_hittest#(pie#, 1) before assigning mouse event handlers. Without hit testing, the pie will not receive mouse events.

Tag, Rotation & Parent

Function	Signature	Description
`pie_tag(pie#)`	`pie_tag@#`	Get user-defined integer tag
`pie_tag#(pie#, n)`	`pie_tag#@#n`	Set user-defined integer tag
`pie_rotation(pie#)`	`pie_rotation@#`	Get rotation angle in degrees
`pie_rotation#(pie#, angle)`	`pie_rotation#@#n`	Set rotation angle
`pie_parent#(pie#)`	`pie_parent#@#`	Get parent control pointer
`pie_parent#(pie#, parent#)`	`pie_parent#@##`	Move to a different parent
`pie_bringtofront#(pie#)`	`pie_bringtofront#@#`	Bring to front of Z-order
`pie_sendtoback#(pie#)`	`pie_sendtoback#@#`	Send to back of Z-order
`pie_invalidate#(pie#)`	`pie_invalidate#@#`	Force the pie to redraw

ⓘ Note: pie_rotation# rotates the entire control visually, which is different from changing the start/end angles. Rotation applies a visual transform around the control’s center, while angles define which sector of the ellipse is drawn.

Events

Each event has a setter (pie_onXXX#) and a getter (pie_onXXX$). Use pie_clearcallbacks#(pie#) to disconnect all callbacks at once.

Mouse Events

Event Setter	Getter	Callback Signature
`pie_onclick#(pie#, func$)`	`pie_onclick$(pie#)`	`function name(sender#)`
`pie_ondblclick#(pie#, func$)`	`pie_ondblclick$(pie#)`	`function name(sender#)`
`pie_onmousedown#(pie#, func$)`	`pie_onmousedown$(pie#)`	`function name(sender#, button, x, y, shift$)`
`pie_onmouseup#(pie#, func$)`	`pie_onmouseup$(pie#)`	`function name(sender#, button, x, y, shift$)`
`pie_onmousemove#(pie#, func$)`	`pie_onmousemove$(pie#)`	`function name(sender#, x, y, shift$)`
`pie_onmouseenter#(pie#, func$)`	`pie_onmouseenter$(pie#)`	`function name(sender#)`
`pie_onmouseleave#(pie#, func$)`	`pie_onmouseleave$(pie#)`	`function name(sender#)`
`pie_onmousewheel#(pie#, func$)`	`pie_onmousewheel$(pie#)`	`function name(sender#, delta)`

Other Events

Event Setter	Getter	Callback Signature
`pie_onresize#(pie#, func$)`	`pie_onresize$(pie#)`	`function name(sender#)`
`pie_clearcallbacks#(pie#)`	—	Disconnect all event callbacks

Complete Examples

Simple Pie Chart

╯ piechart.bas─◻✕
let frm# = form#("Pie Chart", 400, 400)
form_position#(frm#, 4)

' Segment 1: 40% (144 degrees)
let p1# = pie#(frm#, 100, 100, 200, 200)
pie_angles#(p1#, 0, 144)
pie_fill#(p1#, "#e74c3c")
pie_stroke#(p1#, "#c0392b")

' Segment 2: 35% (126 degrees)
let p2# = pie#(frm#, 100, 100, 200, 200)
pie_angles#(p2#, 144, 270)
pie_fill#(p2#, "#3498db")
pie_stroke#(p2#, "#2980b9")

' Segment 3: 25% (90 degrees)
let p3# = pie#(frm#, 100, 100, 200, 200)
pie_angles#(p3#, 270, 360)
pie_fill#(p3#, "#2ecc71")
pie_stroke#(p3#, "#27ae60")

form_show(frm#)

while form_visible(frm#) = 1
    processmessages()
end while

Interactive Pie Segment

╯ interactive.bas─◻✕
let frm# = form#("Interactive Pie", 350, 350)
form_position#(frm#, 4)

let pie# = pie#(frm#, 75, 75, 200, 200)
pie_angles#(pie#, 0, 120)
pie_fill#(pie#, "#9b59b6")
pie_stroke#(pie#, "#8e44ad")
pie_hittest#(pie#, 1)

pie_onclick#(pie#, "OnPieClick")
pie_onmouseenter#(pie#, "OnPieEnter")
pie_onmouseleave#(pie#, "OnPieLeave")

form_show(frm#)

function OnPieClick(sender#) local currentEnd
    let currentEnd = pie_endangle(sender#)
    if currentEnd >= 360 then
        pie_endangle#(sender#, 120)
    else
        pie_endangle#(sender#, currentEnd + 30)
    end if
endfunction

function OnPieEnter(sender#)
    pie_opacity#(sender#, 0.8)
endfunction

function OnPieLeave(sender#)
    pie_opacity#(sender#, 1.0)
endfunction

while form_visible(frm#) = 1
    processmessages()
end while

Pac-Man Animation

╯ pacman.bas─◻✕
let frm# = form#("Pac-Man", 300, 300)
form_position#(frm#, 4)

let pac# = pie#(frm#, 50, 50, 200, 200)
pie_fill#(pac#, "#f1c40f")
pie_strokenone#(pac#)

let mouthOpen = 1
let tmr# = timer#()
timer_interval#(tmr#, 200)
timer_ontimer#(tmr#, "OnTimer")
timer_enabled#(tmr#, 1)

form_show(frm#)

function OnTimer(sender#)
    if mouthOpen = 1 then
        pie_angles#(pac#, 30, 330)
        mouthOpen = 0
    else
        pie_angles#(pac#, 0, 360)
        mouthOpen = 1
    end if
endfunction

while form_visible(frm#) = 1
    processmessages()
end while

Progress Meter

╯ progress.bas─◻✕
' Pie-based progress meter showing 65%
let frm# = form#("Progress", 300, 300)
form_position#(frm#, 4)

' Background (full circle)
let bg# = pie#(frm#, 50, 50, 200, 200)
pie_angles#(bg#, 0, 360)
pie_fill#(bg#, "#ecf0f1")
pie_strokenone#(bg#)

' Progress: 65% = 234 degrees, starting from top
let prog# = pie#(frm#, 50, 50, 200, 200)
pie_angles#(prog#, -90, 144)
pie_fill#(prog#, "#27ae60")
pie_strokenone#(prog#)

form_show(frm#)

while form_visible(frm#) = 1
    processmessages()
end while

Best Practices

Practice	Why
Use equal width and height for circular pies	Unequal dimensions create elliptical wedge shapes
Use `pie_angles#` to set both at once	More efficient than two separate calls
Use `pie_strokenone#` for borderless chart segments	Clean look for multi-segment pie charts
Set `hittest = 1` for interactive pies	Required for mouse events to fire on the pie
Start from top with `-90` or `270`	More intuitive for charts (starts at 12 o’clock)
Overlay a circle for donut charts	Place a smaller filled circle at center to create a ring effect
Use `pie_rotation#` for visual rotation	Rotates the entire control; different from changing start/end angles
Use `pie_opacity#` for hover effects	Subtle transparency changes give good visual feedback

Quick Reference

Function	Signature	Description
`pie_error / errormsg$ / strerror$ / clearerror`	`various`	Error handling (4)
`pie#(parent#[, w, h] \| [, x, y, w, h])`	`various`	Create (3 overloads)
`pie_free(pie#)`	`pie_free@#`	Destroy
`pie_startangle / endangle / angles#`	`various`	Angle control (5)
`pie_fill$ / fill# / fillnone#`	`various`	Fill (3)
`pie_stroke$ / stroke# / strokenone# / strokethickness / strokedash / strokecap / strokejoin`	`various`	Stroke (11)
`pie_x/y/width/height (get/set) / bounds# / move# / size#`	`various`	Position & size (11)
`pie_align / margin# / margins# / margin[left/top/right/bottom]`	`various`	Alignment & margins (12)
`pie_visible / enabled / opacity / hittest`	`various`	Visibility & state (8)
`pie_tag / rotation / parent# / bringtofront# / sendtoback# / invalidate#`	`various`	Tag, rotation & parent (9)
`pie_onclick/ondblclick/onmousedown/up/move/enter/leave/onmousewheel/onresize`	`various`	Events set+get (18)
`pie_clearcallbacks#`	`pie_clearcallbacks#@#`	Disconnect all events

86 functions. Part of the Plan9Basic GUI shape library system.