TrackBarLib — Plan9Basic Documentation

TrackBarLib — Slider Control Library

Interactive slider controls that let users select a value from a range by dragging a thumb along a track. Supports horizontal and vertical orientations, configurable ranges with tick marks, real-time tracking while dragging, and a full event system including keyboard, mouse, and drag events. 100 functions.

Category	Count	Description
Error Handling	4	trackbar_error, errormsg$, strerror$, clearerror
Creation & Destruction	3	trackbar# (2 overloads), trackbar_free
Value Properties	8	value, min, max, frequency (get/set)
Orientation	2	orientation (get/set)
Position & Size	14	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	10	visible, enabled, opacity, hittest, dragmode (get/set)
Focus	7	isfocused, setfocus#, resetfocus#, canfocus (get/set), taborder (get/set)
Tag & Parent	6	tag (get/set), parent# (get/set), bringtofront#, sendtoback#
Events	34	16 event types × set/get + clearcallbacks#

Cross-Platform Support

Platform	Status	Notes
Windows	✅ Full Support	Win32/Win64
Linux	✅ Full Support	GTK-based
Android	✅ Full Support	Touch-friendly thumb

Error Handling

Function	Signature	Description
`trackbar_error()`	`trackbar_error@`	Last error code (0 = no error)
`trackbar_errormsg$()`	`trackbar_errormsg$@`	Last error message as string
`trackbar_strerror$(code)`	`trackbar_strerror$@n`	Description for a given error code
`trackbar_clearerror()`	`trackbar_clearerror@`	Clear the error state

Numeric Values Reference

Orientation `trackbar_orientation#`

Value	Description	Typical Size
0	Horizontal (default)	Wide × short (e.g., 300 × 30)
1	Vertical	Narrow × tall (e.g., 30 × 180)

Control Alignment `trackbar_align#`

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

Drag Mode `trackbar_dragmode#`

Value	Description
0	None (default)
1	Automatic drag enabled

Creation & Destruction

Function	Signature	Description
`trackbar#(parent#)`	`trackbar#@#`	Create trackbar with default size
`trackbar#(parent#, x, y, w, h)`	`trackbar#@#nnnn`	Create with position and size
`trackbar_free(tb#)`	`trackbar_free@#`	Destroy trackbar and release resources

╯ plan9basic─◻✕
let tb# = trackbar#(frm#, 50, 60, 300, 30)
trackbar_min#(tb#, 0)
trackbar_max#(tb#, 100)
trackbar_value#(tb#, 50)

Value Properties

Function	Signature	Description
`trackbar_value(tb#)`	`trackbar_value@#`	Get current value
`trackbar_value#(tb#, n)`	`trackbar_value#@#n`	Set current value
`trackbar_min(tb#)`	`trackbar_min@#`	Get minimum value
`trackbar_min#(tb#, n)`	`trackbar_min#@#n`	Set minimum value
`trackbar_max(tb#)`	`trackbar_max@#`	Get maximum value
`trackbar_max#(tb#, n)`	`trackbar_max#@#n`	Set maximum value
`trackbar_frequency(tb#)`	`trackbar_frequency@#`	Get tick mark frequency
`trackbar_frequency#(tb#, n)`	`trackbar_frequency#@#n`	Set tick mark frequency

╯ plan9basic─◻✕
' Standard 0-100 slider
trackbar_min#(tb#, 0)
trackbar_max#(tb#, 100)
trackbar_value#(tb#, 50)

' Temperature range with tick marks every 5 degrees
trackbar_min#(tb#, 10)
trackbar_max#(tb#, 35)
trackbar_frequency#(tb#, 5)
trackbar_value#(tb#, 22)

' Read current value
let val = trackbar_value(tb#)
println "Value: " + str$(int(val))

⚠ Warning: Always set min and max before setting value. Setting a value outside the range will clamp it to the nearest boundary.

ⓘ Note: trackbar_frequency# controls the spacing of visual tick marks on the track. A frequency of 10 on a 0–100 range shows ticks at 0, 10, 20, …, 100.

Orientation

Function	Signature	Description
`trackbar_orientation(tb#)`	`trackbar_orientation@#`	Get orientation (0=horizontal, 1=vertical)
`trackbar_orientation#(tb#, n)`	`trackbar_orientation#@#n`	Set orientation

╯ plan9basic─◻✕
' Horizontal slider (default)
let tbH# = trackbar#(frm#, 50, 50, 300, 30)
trackbar_orientation#(tbH#, 0)

' Vertical slider (e.g., equalizer band)
let tbV# = trackbar#(frm#, 50, 50, 30, 180)
trackbar_orientation#(tbV#, 1)

ⓘ Note: When switching to vertical orientation, swap width and height. A horizontal slider of 300×30 becomes a vertical slider of 30×180.

Position & Size

Function	Signature	Description
`trackbar_x(tb#)`	`trackbar_x@#`	Get X position
`trackbar_x#(tb#, x)`	`trackbar_x#@#n`	Set X position
`trackbar_y(tb#)`	`trackbar_y@#`	Get Y position
`trackbar_y#(tb#, y)`	`trackbar_y#@#n`	Set Y position
`trackbar_width(tb#)`	`trackbar_width@#`	Get width
`trackbar_width#(tb#, w)`	`trackbar_width#@#n`	Set width
`trackbar_height(tb#)`	`trackbar_height@#`	Get height
`trackbar_height#(tb#, h)`	`trackbar_height#@#n`	Set height
`trackbar_bounds#(tb#, x, y, w, h)`	`trackbar_bounds#@#nnnn`	Set position and size in one call
`trackbar_move#(tb#, x, y)`	`trackbar_move#@#nn`	Set position only
`trackbar_size#(tb#, w, h)`	`trackbar_size#@#nn`	Set size only

Alignment & Margins

Function	Signature	Description
`trackbar_align(tb#)`	`trackbar_align@#`	Get control alignment
`trackbar_align#(tb#, n)`	`trackbar_align#@#n`	Set alignment
`trackbar_margin#(tb#, n)`	`trackbar_margin#@#n`	Set uniform margin on all four sides
`trackbar_margins#(tb#, l, t, r, b)`	`trackbar_margins#@#nnnn`	Set individual margins
`trackbar_marginleft(tb#)`	`trackbar_marginleft@#`	Get left margin
`trackbar_marginleft#(tb#, n)`	`trackbar_marginleft#@#n`	Set left margin
`trackbar_margintop(tb#)`	`trackbar_margintop@#`	Get top margin
`trackbar_margintop#(tb#, n)`	`trackbar_margintop#@#n`	Set top margin
`trackbar_marginright(tb#)`	`trackbar_marginright@#`	Get right margin
`trackbar_marginright#(tb#, n)`	`trackbar_marginright#@#n`	Set right margin
`trackbar_marginbottom(tb#)`	`trackbar_marginbottom@#`	Get bottom margin
`trackbar_marginbottom#(tb#, n)`	`trackbar_marginbottom#@#n`	Set bottom margin

Visibility & State

Function	Signature	Description
`trackbar_visible(tb#)`	`trackbar_visible@#`	Get visibility (0/1)
`trackbar_visible#(tb#, n)`	`trackbar_visible#@#n`	Set visibility
`trackbar_enabled(tb#)`	`trackbar_enabled@#`	Get enabled state (0/1)
`trackbar_enabled#(tb#, n)`	`trackbar_enabled#@#n`	Set enabled state
`trackbar_opacity(tb#)`	`trackbar_opacity@#`	Get opacity (0.0–1.0)
`trackbar_opacity#(tb#, value)`	`trackbar_opacity#@#n`	Set opacity
`trackbar_hittest(tb#)`	`trackbar_hittest@#`	Get hit-test state (0/1)
`trackbar_hittest#(tb#, n)`	`trackbar_hittest#@#n`	Enable/disable mouse hit testing
`trackbar_dragmode(tb#)`	`trackbar_dragmode@#`	Get drag mode (0=none, 1=auto)
`trackbar_dragmode#(tb#, n)`	`trackbar_dragmode#@#n`	Set drag mode

Focus

Function	Signature	Description
`trackbar_isfocused(tb#)`	`trackbar_isfocused@#`	Is this trackbar focused? (0/1)
`trackbar_setfocus#(tb#)`	`trackbar_setfocus#@#`	Set focus to the trackbar
`trackbar_resetfocus#(tb#)`	`trackbar_resetfocus#@#`	Remove focus from the trackbar
`trackbar_canfocus(tb#)`	`trackbar_canfocus@#`	Get whether trackbar can receive focus (0/1)
`trackbar_canfocus#(tb#, n)`	`trackbar_canfocus#@#n`	Set whether trackbar can receive focus
`trackbar_taborder(tb#)`	`trackbar_taborder@#`	Get tab order index
`trackbar_taborder#(tb#, n)`	`trackbar_taborder#@#n`	Set tab order index

ⓘ Note: When a trackbar has focus, the user can adjust its value with the arrow keys. Left/Down decreases, Right/Up increases.

Tag & Parent

Function	Signature	Description
`trackbar_tag(tb#)`	`trackbar_tag@#`	Get user-defined integer tag
`trackbar_tag#(tb#, n)`	`trackbar_tag#@#n`	Set user-defined integer tag
`trackbar_parent#(tb#)`	`trackbar_parent#@#`	Get parent control pointer
`trackbar_parent#(tb#, parent#)`	`trackbar_parent#@##`	Move trackbar to a different parent
`trackbar_bringtofront#(tb#)`	`trackbar_bringtofront#@#`	Bring to front of Z-order
`trackbar_sendtoback#(tb#)`	`trackbar_sendtoback#@#`	Send to back of Z-order

ⓘ Note: Use trackbar_tag# to distinguish multiple sliders sharing the same callback function. Read it in the handler with trackbar_tag(sender#).

Events

Each event has a setter (trackbar_onXXX#(tb#, func$)) and a getter (trackbar_onXXX$(tb#)). Use trackbar_clearcallbacks#(tb#) to disconnect all callbacks at once.

Value & Focus Events

Event Setter	Getter	Callback Signature	When It Fires
`trackbar_onchange#(tb#, func$)`	`trackbar_onchange$(tb#)`	`function name(sender#)`	When the user releases the thumb (final value)
`trackbar_ontracking#(tb#, func$)`	`trackbar_ontracking$(tb#)`	`function name(sender#)`	Continuously while the user drags the thumb
`trackbar_onclick#(tb#, func$)`	`trackbar_onclick$(tb#)`	`function name(sender#)`	When the trackbar is clicked
`trackbar_ondblclick#(tb#, func$)`	`trackbar_ondblclick$(tb#)`	`function name(sender#)`	When double-clicked
`trackbar_onenter#(tb#, func$)`	`trackbar_onenter$(tb#)`	`function name(sender#)`	When the control receives focus
`trackbar_onexit#(tb#, func$)`	`trackbar_onexit$(tb#)`	`function name(sender#)`	When the control loses focus
`trackbar_onresize#(tb#, func$)`	`trackbar_onresize$(tb#)`	`function name(sender#)`	When the trackbar is resized

⚠ Warning: OnChange vs OnTracking: Use OnTracking for real-time visual feedback (label updates, color previews, live adjustments). Use OnChange for expensive operations that should only run when the user finishes dragging (saving settings, applying filters, network requests). For best UX, connect both events to the same handler for immediate feedback.

Keyboard Events

Event Setter	Getter	Callback Signature
`trackbar_onkeydown#(tb#, func$)`	`trackbar_onkeydown$(tb#)`	`function name(sender#, key, keychar$, shift$)`
`trackbar_onkeyup#(tb#, func$)`	`trackbar_onkeyup$(tb#)`	`function name(sender#, key, keychar$, shift$)`

Mouse Events

Event Setter	Getter	Callback Signature
`trackbar_onmousedown#(tb#, func$)`	`trackbar_onmousedown$(tb#)`	`function name(sender#, button, x, y, shift$)`
`trackbar_onmouseup#(tb#, func$)`	`trackbar_onmouseup$(tb#)`	`function name(sender#, button, x, y, shift$)`
`trackbar_onmousemove#(tb#, func$)`	`trackbar_onmousemove$(tb#)`	`function name(sender#, x, y, shift$)`
`trackbar_onmouseenter#(tb#, func$)`	`trackbar_onmouseenter$(tb#)`	`function name(sender#)`
`trackbar_onmouseleave#(tb#, func$)`	`trackbar_onmouseleave$(tb#)`	`function name(sender#)`

Drag Events

Event Setter	Getter	Callback Signature
`trackbar_ondragenter#(tb#, func$)`	`trackbar_ondragenter$(tb#)`	`function name(sender#, x, y)`
`trackbar_ondragover#(tb#, func$)`	`trackbar_ondragover$(tb#)`	`function name(sender#, x, y)`
`trackbar_ondragdrop#(tb#, func$)`	`trackbar_ondragdrop$(tb#)`	`function name(sender#, x, y)`
`trackbar_ondragleave#(tb#, func$)`	`trackbar_ondragleave$(tb#)`	`function name(sender#)`
`trackbar_clearcallbacks#(tb#)`	—	Disconnect all event callbacks

TrackBar vs ProgressBar

Feature	TrackBar (Slider)	ProgressBar
User Interaction	✅ User drags thumb to select value	❌ Read-only display
Primary Event	`OnChange` / `OnTracking`	None (set programmatically)
Tick Marks	✅ Yes (`frequency`)	❌ No
Focus / Keyboard	✅ Arrow keys adjust value	❌ No
Use Case	Volume, zoom, color selection, settings	Task completion, download progress, levels
Orientation	Horizontal / Vertical	Horizontal / Vertical

Use TrackBar when the user needs to select a value interactively. Use ProgressBar to display a read-only progress indicator.

Complete Examples

Volume Control with Mute

╯ volume.bas─◻✕
let savedVol = 50

function OnVolChange(sender#) local vol
    vol = int(trackbar_value(sender#))
    label_text#(lblVol#, "Volume: " + str$(vol) + "%")
endfunction

function OnMute(sender#) local vol
    vol = trackbar_value(tbVol#)
    if vol > 0 then
        savedVol = vol
        trackbar_value#(tbVol#, 0)
        button_text#(btnMute#, "Unmute")
    else
        trackbar_value#(tbVol#, savedVol)
        button_text#(btnMute#, "Mute")
    endif
    OnVolChange(tbVol#)
endfunction

let frm# = form#("Volume Control", 400, 150)
form_position#(frm#, 4)

let lblVol# = label#(frm#, "Volume: 50%")
label_bounds#(lblVol#, 50, 20, 150, 25)
label_fontsize#(lblVol#, 14)

let tbVol# = trackbar#(frm#, 50, 50, 300, 30)
trackbar_min#(tbVol#, 0)
trackbar_max#(tbVol#, 100)
trackbar_value#(tbVol#, 50)

let btnMute# = button#(frm#, "Mute", 50, 90, 80, 30)

trackbar_ontracking#(tbVol#, "OnVolChange")
trackbar_onchange#(tbVol#, "OnVolChange")
button_onclick#(btnMute#, "OnMute")

form_show(frm#)

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

RGB Color Mixer

╯ colormixer.bas─◻✕
function ToHex$(val) local h$
    h$ = hex$(val)
    if len(h$) = 1 then h$ = "0" + h$
    return h$
endfunction

function OnColorChange(sender#) local r, g, b, color$, tag
    tag = trackbar_tag(sender#)
    r = int(trackbar_value(tbR#))
    g = int(trackbar_value(tbG#))
    b = int(trackbar_value(tbB#))
    if tag = 1 then label_text#(lblR#, "R: " + str$(r))
    if tag = 2 then label_text#(lblG#, "G: " + str$(g))
    if tag = 3 then label_text#(lblB#, "B: " + str$(b))
    color$ = "#" + ToHex$(r) + ToHex$(g) + ToHex$(b)
    rectangle_fill#(rectColor#, color$)
    label_text#(lblHex#, color$)
endfunction

let frm# = form#("RGB Color Mixer", 450, 300)
form_position#(frm#, 4)

let rectColor# = rectangle#(frm#, 300, 30, 120, 120)
rectangle_fill#(rectColor#, "#808080")

let lblR# = label#(frm#, "R: 128")
label_move#(lblR#, 20, 30)
let tbR# = trackbar#(frm#, 70, 25, 200, 30)
trackbar_max#(tbR#, 255)
trackbar_value#(tbR#, 128)
trackbar_tag#(tbR#, 1)

let lblG# = label#(frm#, "G: 128")
label_move#(lblG#, 20, 80)
let tbG# = trackbar#(frm#, 70, 75, 200, 30)
trackbar_max#(tbG#, 255)
trackbar_value#(tbG#, 128)
trackbar_tag#(tbG#, 2)

let lblB# = label#(frm#, "B: 128")
label_move#(lblB#, 20, 130)
let tbB# = trackbar#(frm#, 70, 125, 200, 30)
trackbar_max#(tbB#, 255)
trackbar_value#(tbB#, 128)
trackbar_tag#(tbB#, 3)

let lblHex# = label#(frm#, "#808080")
label_bounds#(lblHex#, 300, 170, 120, 25)
label_textalign#(lblHex#, 0)

trackbar_ontracking#(tbR#, "OnColorChange")
trackbar_ontracking#(tbG#, "OnColorChange")
trackbar_ontracking#(tbB#, "OnColorChange")

form_show(frm#)

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

Equalizer (Vertical Sliders)

╯ equalizer.bas─◻✕
function OnReset(sender#)
    trackbar_value#(tb1#, 50)
    trackbar_value#(tb2#, 50)
    trackbar_value#(tb3#, 50)
    trackbar_value#(tb4#, 50)
    trackbar_value#(tb5#, 50)
endfunction

let frm# = form#("Equalizer", 400, 300)
form_position#(frm#, 4)

let tb1# = trackbar#(frm#, 50, 50, 30, 180)
trackbar_orientation#(tb1#, 1)
trackbar_max#(tb1#, 100)
trackbar_value#(tb1#, 50)

let tb2# = trackbar#(frm#, 100, 50, 30, 180)
trackbar_orientation#(tb2#, 1)
trackbar_max#(tb2#, 100)
trackbar_value#(tb2#, 60)

let tb3# = trackbar#(frm#, 150, 50, 30, 180)
trackbar_orientation#(tb3#, 1)
trackbar_max#(tb3#, 100)
trackbar_value#(tb3#, 70)

let tb4# = trackbar#(frm#, 200, 50, 30, 180)
trackbar_orientation#(tb4#, 1)
trackbar_max#(tb4#, 100)
trackbar_value#(tb4#, 55)

let tb5# = trackbar#(frm#, 250, 50, 30, 180)
trackbar_orientation#(tb5#, 1)
trackbar_max#(tb5#, 100)
trackbar_value#(tb5#, 45)

label#(frm#, "60Hz", 40, 240)
label#(frm#, "250Hz", 85, 240)
label#(frm#, "1kHz", 140, 240)
label#(frm#, "4kHz", 190, 240)
label#(frm#, "16kHz", 235, 240)

let btnReset# = button#(frm#, "Reset", 300, 120, 80, 35)
button_onclick#(btnReset#, "OnReset")

form_show(frm#)

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

Temperature Range Indicator

╯ temperature.bas─◻✕
function OnTempChange(sender#) local temp, status$, color$
    temp = int(trackbar_value(sender#))
    label_text#(lblTemp#, "Temperature: " + str$(temp) + chr$(176) + "C")
    if temp < 16 then
        status$ = "Too Cold" : color$ = "#0000FF"
    elseif temp < 18 then
        status$ = "Cool" : color$ = "#00AAFF"
    elseif temp <= 24 then
        status$ = "Comfortable" : color$ = "#00AA00"
    elseif temp <= 28 then
        status$ = "Warm" : color$ = "#FFAA00"
    else
        status$ = "Too Hot" : color$ = "#FF0000"
    endif
    label_text#(lblRange#, status$)
    label_fontcolor#(lblRange#, color$)
endfunction

let frm# = form#("Temperature Control", 400, 200)
form_position#(frm#, 4)

let lblTemp# = label#(frm#, "Temperature: 20" + chr$(176) + "C")
label_bounds#(lblTemp#, 50, 20, 200, 30)
label_fontsize#(lblTemp#, 16)

let tbTemp# = trackbar#(frm#, 50, 60, 300, 40)
trackbar_min#(tbTemp#, 10)
trackbar_max#(tbTemp#, 35)
trackbar_frequency#(tbTemp#, 5)
trackbar_value#(tbTemp#, 20)

let lblRange# = label#(frm#, "Comfortable")
label_bounds#(lblRange#, 50, 130, 200, 25)
label_fontcolor#(lblRange#, "#00AA00")

trackbar_ontracking#(tbTemp#, "OnTempChange")

form_show(frm#)

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

Best Practices

Practice	Why
Set `min` and `max` before `value`	Ensures the value falls within the valid range
Use `OnTracking` for real-time feedback	Updates labels, colors, and previews while the user drags
Use `OnChange` for expensive operations	Only fires when the user finishes dragging (saves, network, heavy computation)
Connect both events for best UX	`OnTracking` + `OnChange` to the same handler gives immediate and final feedback
Swap width/height for vertical orientation	Height > width for vertical sliders (e.g., 30×180)
Use `frequency` for visual tick marks	Helps users see scale divisions on the track
Use `tag` for shared callbacks	Distinguish multiple sliders in a single handler with `trackbar_tag(sender#)`
Use `int()` when displaying values	TrackBar values may be floating-point; convert for clean display

Quick Reference

Function	Signature	Description
`trackbar_error / errormsg$ / strerror$ / clearerror`	`various`	Error handling (4)
`trackbar#(parent#[, x, y, w, h])`	`various`	Create (2 overloads)
`trackbar_free(tb#)`	`trackbar_free@#`	Destroy
`trackbar_value / min / max / frequency (get/set)`	`various`	Value properties (8)
`trackbar_orientation (get/set)`	`various`	Orientation (2)
`trackbar_x/y/width/height (get/set) / bounds# / move# / size#`	`various`	Position & size (14)
`trackbar_align / margin# / margins# / margin[left/top/right/bottom]`	`various`	Alignment & margins (12)
`trackbar_visible / enabled / opacity / hittest / dragmode`	`various`	Visibility & state (10)
`trackbar_isfocused / setfocus# / resetfocus# / canfocus / taborder`	`various`	Focus (7)
`trackbar_tag / parent# / bringtofront# / sendtoback#`	`various`	Tag & parent (6)
`trackbar_onchange/ontracking/onclick/ondblclick/onenter/onexit/onresize/onkeydown/onkeyup/onmousedown/up/move/enter/leave/ondragenter/over/drop/leave`	`various`	Events set+get (33)
`trackbar_clearcallbacks#`	`trackbar_clearcallbacks#@#`	Disconnect all events

100 functions. Part of the Plan9Basic GUI library system.