CheckBoxLib — Plan9Basic Documentation

CheckBoxLib — CheckBox Control Library

Complete support for checkbox controls in Plan9Basic. Checkboxes are binary toggle controls that allow users to select or deselect options. Features include full font styling, alignment and margins, focus control, drag support, and a comprehensive event system. 108 functions.

Category	Count	Description
Error Handling	4	checkbox_error, checkbox_errormsg$, checkbox_strerror$, checkbox_clearerror
Creation & Destruction	5	checkbox# (4 overloads), checkbox_free
Checked State	2	checkbox_ischecked (get/set)
Text & Font	14	text, fontfamily, fontsize, fontcolor, bold, italic, underline, strikeout (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	6	visible, enabled, opacity (get/set)
Focus	5	isfocused, setfocus#, resetfocus#, taborder (get/set)
Interaction	6	canfocus, hittest, dragmode (get/set)
Tag & Parent	6	tag (get/set), parent# (get/set), bringtofront#, sendtoback#
Events	34	15 event types × set/get + clearcallbacks#

Cross-Platform Support

Platform	Status	Notes
Windows	✅ Full Support	Win32/Win64
Linux	✅ Full Support	GTK-based
Android	✅ Full Support	Mobile-optimized

Error Handling

Function	Signature	Description
`checkbox_error()`	`checkbox_error@`	Last error code (0 = no error)
`checkbox_errormsg$()`	`checkbox_errormsg$@`	Last error message as string
`checkbox_strerror$(code)`	`checkbox_strerror$@n`	Description for a given error code
`checkbox_clearerror()`	`checkbox_clearerror@`	Clear the error state

Code	Description
0	No error
1	Invalid checkbox pointer
2	Invalid parent pointer
3	Invalid value
4	Creation failed

Numeric Values Reference

Control Alignment `checkbox_align#`

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

Drag Mode `checkbox_dragmode#`

Value	Description
0	None (default)
1	Automatic drag enabled

Creation & Destruction

Function	Signature	Description
`checkbox#(parent#)`	`checkbox#@#`	Create checkbox with default settings
`checkbox#(parent#, text$)`	`checkbox#@#$`	Create with label text
`checkbox#(parent#, x, y, w, h)`	`checkbox#@#nnnn`	Create at position and size
`checkbox#(parent#, text$, x, y, w, h)`	`checkbox#@#$nnnn`	Create with text, position, and size
`checkbox_free(chk#)`	`checkbox_free@#`	Destroy checkbox and release resources

╯ plan9basic─◻✕
' Simple creation
let chk# = checkbox#(frm#, "Enable feature")

' With position and size
let chk# = checkbox#(frm#, "Dark mode", 20, 50, 200, 22)

' Position only (no text)
let chk# = checkbox#(frm#, 20, 50, 200, 22)

' Cleanup
checkbox_free(chk#)

Checked State

Function	Signature	Description
`checkbox_ischecked(chk#)`	`checkbox_ischecked@#`	Get checked state (0=unchecked, 1=checked)
`checkbox_ischecked#(chk#, n)`	`checkbox_ischecked#@#n`	Set checked state

╯ plan9basic─◻✕
' Toggle programmatically
checkbox_ischecked#(chk#, 1)  ' Check
checkbox_ischecked#(chk#, 0)  ' Uncheck

' Read state
if checkbox_ischecked(chk#) = 1 then
    println "Checked"
else
    println "Unchecked"
endif

Text & Font

Function	Signature	Description
`checkbox_text$(chk#)`	`checkbox_text$@#`	Get label text
`checkbox_text#(chk#, text$)`	`checkbox_text#@#$`	Set label text
`checkbox_fontfamily$(chk#)`	`checkbox_fontfamily$@#`	Get font family name
`checkbox_fontfamily#(chk#, family$)`	`checkbox_fontfamily#@#$`	Set font family
`checkbox_fontsize(chk#)`	`checkbox_fontsize@#`	Get font size
`checkbox_fontsize#(chk#, size)`	`checkbox_fontsize#@#n`	Set font size
`checkbox_fontcolor$(chk#)`	`checkbox_fontcolor$@#`	Get font color
`checkbox_fontcolor#(chk#, color$)`	`checkbox_fontcolor#@#$`	Set font color
`checkbox_bold(chk#)`	`checkbox_bold@#`	Get bold state (0/1)
`checkbox_bold#(chk#, n)`	`checkbox_bold#@#n`	Set bold (0/1)
`checkbox_italic(chk#)`	`checkbox_italic@#`	Get italic state (0/1)
`checkbox_italic#(chk#, n)`	`checkbox_italic#@#n`	Set italic (0/1)
`checkbox_underline(chk#)`	`checkbox_underline@#`	Get underline state (0/1)
`checkbox_underline#(chk#, n)`	`checkbox_underline#@#n`	Set underline (0/1)
`checkbox_strikeout(chk#)`	`checkbox_strikeout@#`	Get strikeout state (0/1)
`checkbox_strikeout#(chk#, n)`	`checkbox_strikeout#@#n`	Set strikeout (0/1)

╯ plan9basic─◻✕
checkbox_text#(chk#, "Enable notifications")
checkbox_fontfamily#(chk#, "Arial")
checkbox_fontsize#(chk#, 14)
checkbox_fontcolor#(chk#, "#333333")
checkbox_bold#(chk#, 1)

Position & Size

Function	Signature	Description
`checkbox_x(chk#)`	`checkbox_x@#`	Get X position
`checkbox_x#(chk#, x)`	`checkbox_x#@#n`	Set X position
`checkbox_y(chk#)`	`checkbox_y@#`	Get Y position
`checkbox_y#(chk#, y)`	`checkbox_y#@#n`	Set Y position
`checkbox_width(chk#)`	`checkbox_width@#`	Get width
`checkbox_width#(chk#, w)`	`checkbox_width#@#n`	Set width
`checkbox_height(chk#)`	`checkbox_height@#`	Get height
`checkbox_height#(chk#, h)`	`checkbox_height#@#n`	Set height
`checkbox_bounds#(chk#, x, y, w, h)`	`checkbox_bounds#@#nnnn`	Set position and size in one call
`checkbox_move#(chk#, x, y)`	`checkbox_move#@#nn`	Set position only
`checkbox_size#(chk#, w, h)`	`checkbox_size#@#nn`	Set size only

╯ plan9basic─◻✕
checkbox_bounds#(chk#, 20, 50, 200, 22)

' Or separately
checkbox_move#(chk#, 20, 50)
checkbox_size#(chk#, 200, 22)

Alignment & Margins

When checkbox_align# is set to a value other than 0, the checkbox is automatically positioned by its parent. Margins control spacing when alignment is active.

Function	Signature	Description
`checkbox_align(chk#)`	`checkbox_align@#`	Get control alignment mode
`checkbox_align#(chk#, n)`	`checkbox_align#@#n`	Set control alignment (0=none, 1=top, 2=left, 3=right, 4=bottom, 9=client, 11=center)
`checkbox_margin#(chk#, n)`	`checkbox_margin#@#n`	Set uniform margin on all four sides
`checkbox_margins#(chk#, l, t, r, b)`	`checkbox_margins#@#nnnn`	Set individual margins (left, top, right, bottom)
`checkbox_marginleft(chk#)`	`checkbox_marginleft@#`	Get left margin
`checkbox_marginleft#(chk#, n)`	`checkbox_marginleft#@#n`	Set left margin
`checkbox_margintop(chk#)`	`checkbox_margintop@#`	Get top margin
`checkbox_margintop#(chk#, n)`	`checkbox_margintop#@#n`	Set top margin
`checkbox_marginright(chk#)`	`checkbox_marginright@#`	Get right margin
`checkbox_marginright#(chk#, n)`	`checkbox_marginright#@#n`	Set right margin
`checkbox_marginbottom(chk#)`	`checkbox_marginbottom@#`	Get bottom margin
`checkbox_marginbottom#(chk#, n)`	`checkbox_marginbottom#@#n`	Set bottom margin

╯ plan9basic─◻✕
' Stack checkboxes at the top of a panel
checkbox_align#(chk1#, 1)    ' Align top
checkbox_margin#(chk1#, 5)   ' 5px spacing
checkbox_align#(chk2#, 1)
checkbox_margin#(chk2#, 5)

Visibility & State

Function	Signature	Description
`checkbox_visible(chk#)`	`checkbox_visible@#`	Get visibility (0/1)
`checkbox_visible#(chk#, n)`	`checkbox_visible#@#n`	Set visibility (0=hidden, 1=visible)
`checkbox_enabled(chk#)`	`checkbox_enabled@#`	Get enabled state (0/1)
`checkbox_enabled#(chk#, n)`	`checkbox_enabled#@#n`	Set enabled state (0=disabled/grayed, 1=enabled)
`checkbox_opacity(chk#)`	`checkbox_opacity@#`	Get opacity (0.0–1.0)
`checkbox_opacity#(chk#, value)`	`checkbox_opacity#@#n`	Set opacity (0.0=transparent, 1.0=opaque)

╯ plan9basic─◻✕
' Disable a checkbox conditionally
checkbox_enabled#(chkAdvanced#, 0)
checkbox_opacity#(chkAdvanced#, 0.5)

Focus

Function	Signature	Description
`checkbox_isfocused(chk#)`	`checkbox_isfocused@#`	Is this checkbox focused? (0/1)
`checkbox_setfocus#(chk#)`	`checkbox_setfocus#@#`	Give keyboard focus to this checkbox
`checkbox_resetfocus#(chk#)`	`checkbox_resetfocus#@#`	Release focus from this checkbox
`checkbox_taborder(chk#)`	`checkbox_taborder@#`	Get tab order index
`checkbox_taborder#(chk#, n)`	`checkbox_taborder#@#n`	Set tab order index

╯ plan9basic─◻✕
' Set up logical tab order
checkbox_taborder#(chk1#, 1)
checkbox_taborder#(chk2#, 2)
checkbox_taborder#(chk3#, 3)

Interaction

Function	Signature	Description
`checkbox_canfocus(chk#)`	`checkbox_canfocus@#`	Get whether checkbox can receive focus (0/1)
`checkbox_canfocus#(chk#, n)`	`checkbox_canfocus#@#n`	Set whether checkbox can receive focus
`checkbox_hittest(chk#)`	`checkbox_hittest@#`	Get hit-test state (0/1)
`checkbox_hittest#(chk#, n)`	`checkbox_hittest#@#n`	Enable/disable mouse hit testing
`checkbox_dragmode(chk#)`	`checkbox_dragmode@#`	Get drag mode (0=none, 1=automatic)
`checkbox_dragmode#(chk#, n)`	`checkbox_dragmode#@#n`	Set drag mode

╯ plan9basic─◻✕
' Make a checkbox non-focusable (display only)
checkbox_canfocus#(chk#, 0)

' Enable drag support
checkbox_dragmode#(chk#, 1)

Tag & Parent

Function	Signature	Description
`checkbox_tag(chk#)`	`checkbox_tag@#`	Get user-defined integer tag
`checkbox_tag#(chk#, n)`	`checkbox_tag#@#n`	Set user-defined integer tag
`checkbox_parent#(chk#)`	`checkbox_parent#@#`	Get parent control pointer
`checkbox_parent#(chk#, parent#)`	`checkbox_parent#@##`	Move checkbox to a different parent
`checkbox_bringtofront#(chk#)`	`checkbox_bringtofront#@#`	Bring to front of Z-order
`checkbox_sendtoback#(chk#)`	`checkbox_sendtoback#@#`	Send to back of Z-order

╯ plan9basic─◻✕
' Use tags to identify checkboxes in shared callbacks
checkbox_tag#(chkRed#, 1)
checkbox_tag#(chkGreen#, 2)
checkbox_tag#(chkBlue#, 3)

function OnColorChanged(sender#) local tag
    tag = checkbox_tag(sender#)
    if tag = 1 then println "Red: " + str$(checkbox_ischecked(sender#))
    elseif tag = 2 then println "Green: " + str$(checkbox_ischecked(sender#))
    elseif tag = 3 then println "Blue: " + str$(checkbox_ischecked(sender#))
    endif
endfunction

Events

Each event has a setter (checkbox_onXXX#(chk#, func$)) and a getter (checkbox_onXXX$(chk#)). Use checkbox_clearcallbacks#(chk#) to disconnect all callbacks at once.

State & Focus Events

Event Setter	Getter	Callback Signature
`checkbox_onchange#(chk#, func$)`	`checkbox_onchange$(chk#)`	`function name(sender#)`
`checkbox_onclick#(chk#, func$)`	`checkbox_onclick$(chk#)`	`function name(sender#)`
`checkbox_ondblclick#(chk#, func$)`	`checkbox_ondblclick$(chk#)`	`function name(sender#)`
`checkbox_onenter#(chk#, func$)`	`checkbox_onenter$(chk#)`	`function name(sender#)`
`checkbox_onexit#(chk#, func$)`	`checkbox_onexit$(chk#)`	`function name(sender#)`

ⓘ Note: OnChange is the primary event for checkboxes. It fires whenever the checked state toggles, either by user click or by programmatic change via checkbox_ischecked#.

Keyboard Events

Event Setter	Getter	Callback Signature
`checkbox_onkeydown#(chk#, func$)`	`checkbox_onkeydown$(chk#)`	`function name(sender#, key, keychar$, shift$)`
`checkbox_onkeyup#(chk#, func$)`	`checkbox_onkeyup$(chk#)`	`function name(sender#, key, keychar$, shift$)`

Mouse Events

Event Setter	Getter	Callback Signature
`checkbox_onmousedown#(chk#, func$)`	`checkbox_onmousedown$(chk#)`	`function name(sender#, button, x, y, shift$)`
`checkbox_onmouseup#(chk#, func$)`	`checkbox_onmouseup$(chk#)`	`function name(sender#, button, x, y, shift$)`
`checkbox_onmousemove#(chk#, func$)`	`checkbox_onmousemove$(chk#)`	`function name(sender#, x, y, shift$)`
`checkbox_onmouseenter#(chk#, func$)`	`checkbox_onmouseenter$(chk#)`	`function name(sender#)`
`checkbox_onmouseleave#(chk#, func$)`	`checkbox_onmouseleave$(chk#)`	`function name(sender#)`

Other Events

Event Setter	Getter	Callback Signature
`checkbox_onresize#(chk#, func$)`	`checkbox_onresize$(chk#)`	`function name(sender#)`
`checkbox_ondragenter#(chk#, func$)`	`checkbox_ondragenter$(chk#)`	`function name(sender#)`
`checkbox_ondragover#(chk#, func$)`	`checkbox_ondragover$(chk#)`	`function name(sender#)`
`checkbox_ondragdrop#(chk#, func$)`	`checkbox_ondragdrop$(chk#)`	`function name(sender#)`
`checkbox_ondragleave#(chk#, func$)`	`checkbox_ondragleave$(chk#)`	`function name(sender#)`
`checkbox_clearcallbacks#(chk#)`	—	Disconnect all event callbacks

Shift String Values

Value	Meaning
`"S"`	Shift key
`"C"`	Control key
`"A"`	Alt key

Complete Examples

Settings Panel

╯ settings.bas─◻✕
function OnAutoSaveChanged(sender#)
    if checkbox_ischecked(sender#) = 1 then
        println "Auto-save enabled"
    else
        println "Auto-save disabled"
    endif
endfunction

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

let chkAutoSave# = checkbox#(frm#, "Auto-save documents")
checkbox_bounds#(chkAutoSave#, 20, 20, 200, 22)
checkbox_onchange#(chkAutoSave#, "OnAutoSaveChanged")

let chkSpellCheck# = checkbox#(frm#, "Enable spell check")
checkbox_bounds#(chkSpellCheck#, 20, 50, 200, 22)

let chkDarkMode# = checkbox#(frm#, "Dark mode")
checkbox_bounds#(chkDarkMode#, 20, 80, 200, 22)

form_show(frm#)

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

Select All Pattern

╯ select_all.bas─◻✕
function OnSelectAllChanged(sender#) local checked
    checked = checkbox_ischecked(chkSelectAll#)
    checkbox_ischecked#(chkItem1#, checked)
    checkbox_ischecked#(chkItem2#, checked)
    checkbox_ischecked#(chkItem3#, checked)
endfunction

let chkSelectAll# = Pointer#(0)
let chkItem1# = Pointer#(0)
let chkItem2# = Pointer#(0)
let chkItem3# = Pointer#(0)

let frm# = form#("Select Items", 300, 200)
form_position#(frm#, 4)

' Master checkbox
chkSelectAll# = checkbox#(frm#, "Select All")
checkbox_bounds#(chkSelectAll#, 20, 20, 150, 22)
checkbox_bold#(chkSelectAll#, 1)
checkbox_onchange#(chkSelectAll#, "OnSelectAllChanged")

' Child checkboxes (indented)
chkItem1# = checkbox#(frm#, "Item 1")
checkbox_bounds#(chkItem1#, 40, 50, 130, 22)

chkItem2# = checkbox#(frm#, "Item 2")
checkbox_bounds#(chkItem2#, 40, 80, 130, 22)

chkItem3# = checkbox#(frm#, "Item 3")
checkbox_bounds#(chkItem3#, 40, 110, 130, 22)

form_show(frm#)

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

Color Picker with Tag Identification

╯ colors.bas─◻✕
function OnColorChanged(sender#) local tag, checked
    tag = checkbox_tag(sender#)
    checked = checkbox_ischecked(sender#)
    if tag = 1 then println "Red: " + str$(checked)
    elseif tag = 2 then println "Green: " + str$(checked)
    elseif tag = 3 then println "Blue: " + str$(checked)
    endif
endfunction

let frm# = form#("Colors", 300, 200)
form_position#(frm#, 4)

let chk1# = checkbox#(frm#, "Red", 20, 20, 150, 22)
checkbox_tag#(chk1#, 1)
checkbox_fontcolor#(chk1#, "red")
checkbox_onchange#(chk1#, "OnColorChanged")

let chk2# = checkbox#(frm#, "Green", 20, 50, 150, 22)
checkbox_tag#(chk2#, 2)
checkbox_fontcolor#(chk2#, "green")
checkbox_onchange#(chk2#, "OnColorChanged")

let chk3# = checkbox#(frm#, "Blue", 20, 80, 150, 22)
checkbox_tag#(chk3#, 3)
checkbox_fontcolor#(chk3#, "blue")
checkbox_onchange#(chk3#, "OnColorChanged")

form_show(frm#)

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

Dependent Options

╯ dependent.bas─◻✕
function OnMasterChanged(sender#) local on
    on = checkbox_ischecked(sender#)
    checkbox_enabled#(chkSub1#, on)
    checkbox_enabled#(chkSub2#, on)
    if on = 0 then
        checkbox_ischecked#(chkSub1#, 0)
        checkbox_ischecked#(chkSub2#, 0)
    endif
endfunction

let frm# = form#("Dependent Options", 350, 200)
form_position#(frm#, 4)

let chkMaster# = checkbox#(frm#, "Enable notifications", 20, 20, 250, 22)
checkbox_bold#(chkMaster#, 1)
checkbox_onchange#(chkMaster#, "OnMasterChanged")

let chkSub1# = checkbox#(frm#, "Email notifications", 40, 50, 250, 22)
checkbox_enabled#(chkSub1#, 0)

let chkSub2# = checkbox#(frm#, "Push notifications", 40, 80, 250, 22)
checkbox_enabled#(chkSub2#, 0)

form_show(frm#)

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

Best Practices

Practice	Why
Use `checkbox_onchange#` as the primary event	Fires on every state toggle, whether by click or programmatically
Use meaningful, descriptive text	The label should clearly describe what the option does
Group related checkboxes visually	Use indentation and a “Select All” master checkbox for groups
Use `checkbox_tag#` for shared callbacks	Identify which checkbox changed without global variable lookups
Set `checkbox_taborder#`	Enables logical keyboard Tab navigation
Disable sub-options when master is unchecked	Prevents conflicting state; use `checkbox_enabled#`
Initialize pointer variables with `Pointer#(0)`	Required before assigning in callbacks or conditional code

Quick Reference

Function	Signature	Description
`checkbox_error / errormsg$ / strerror$ / clearerror`	`various`	Error handling (4)
`checkbox#(parent#[, text$][, x, y, w, h])`	`various`	Create checkbox (4 overloads)
`checkbox_free(chk#)`	`checkbox_free@#`	Destroy checkbox
`checkbox_ischecked (get/set)`	`various`	Checked state (2)
`checkbox_text / fontfamily / fontsize / fontcolor / bold / italic / underline / strikeout`	`various`	Text & font (16)
`checkbox_x/y/width/height (get/set) / bounds# / move# / size#`	`various`	Position & size (14)
`checkbox_align / margin# / margins# / margin[left/top/right/bottom]`	`various`	Alignment & margins (12)
`checkbox_visible / enabled / opacity`	`various`	Visibility & state (6)
`checkbox_isfocused / setfocus# / resetfocus# / taborder`	`various`	Focus (5)
`checkbox_canfocus / hittest / dragmode`	`various`	Interaction (6)
`checkbox_tag / parent# / bringtofront# / sendtoback#`	`various`	Tag & parent (6)
`checkbox_onchange/onclick/ondblclick/onenter/onexit/onkeydown/onkeyup/onmousedown/onmouseup/onmousemove/onmouseenter/onmouseleave/onresize/ondragenter/ondragover/ondragdrop/ondragleave`	`various`	Events set+get (33)
`checkbox_clearcallbacks#`	`checkbox_clearcallbacks#@#`	Disconnect all events

108 functions. Part of the Plan9Basic GUI library system.