LabelLib — Label Control Library

Complete functionality for creating and managing text label controls in Plan9Basic. Labels display static or dynamic text with full font styling, alignment, word wrap, rotation, and mouse event support. 89 functions.

CategoryCountDescription
Error Handling4label_error, label_errormsg$, label_strerror$, label_clearerror
Creation & Destruction5label# (4 overloads), label_free
Text Content2label_text$ (get), label_text# (set)
Font Properties14fontfamily, fontsize, fontcolor, bold, italic, underline, strikeout (get/set)
Text Alignment4textalign, vertalign (get/set)
Word Wrap & Auto Size4wordwrap, autosize (get/set)
Position & Size14x, y, width, height (get/set), bounds#, move#, size#
Alignment & Margins12align (get/set), margin#, margins#, marginleft/top/right/bottom (get/set)
Visibility & Behavior8visible, enabled, opacity, hittest (get/set)
Tag & Rotation4tag, rotation (get/set)
Parent & Z-Order4parent# (get/set), bringtofront#, sendtoback#
Events188 event types × set/get + clearcallbacks#

Cross-Platform Support

PlatformStatusNotes
Windows✅ Full SupportWin32/Win64
Linux✅ Full SupportGTK-based
Android✅ Full SupportMobile-optimized

Error Handling

FunctionSignatureDescription
label_error()label_error@Last error code (0 = no error)
label_errormsg$()label_errormsg$@Last error message as string
label_strerror$(code)label_strerror$@nDescription for a given error code
label_clearerror()label_clearerror@Clear the error state
╯ plan9basic
─◻✕
let lbl# = label#(frm#, "Hello")
if label_error() <> 0 then
    println "Error: " + label_errormsg$()
endif

Numeric Values Reference

Plan9Basic does not have built-in constants. You can define your own named values for readability:

╯ plan9basic
─◻✕
' Text alignment
let ALIGN_CENTER = 0
let ALIGN_LEADING = 1
let ALIGN_TRAILING = 2

' Control alignment
let CTRL_NONE = 0
let CTRL_TOP = 1
let CTRL_CLIENT = 9

Text Horizontal Alignment label_textalign#

ValueDescription
0Center
1Leading (Left for LTR languages)
2Trailing (Right for LTR languages)

Text Vertical Alignment label_vertalign#

ValueDescription
0Center
1Leading (Top)
2Trailing (Bottom)

Control Alignment label_align#

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

Creation & Destruction

FunctionSignatureDescription
label#(parent#)label#@#Create an empty label
label#(parent#, text$)label#@#$Create with text
label#(parent#, text$, x, y)label#@#$nnCreate with text and position
label#(parent#, text$, x, y, w, h)label#@#$nnnnCreate with text, position, and size
label_free(lbl#)label_free@#Destroy label and release resources
╯ plan9basic
─◻✕
' Empty label
let lbl# = label#(frm#)

' With text
let lbl# = label#(frm#, "Hello, World!")

' With text and position
let lbl# = label#(frm#, "Status:", 20, 50)

' Full creation
let lbl# = label#(frm#, "Description", 20, 80, 300, 60)

' Cleanup
label_free(lbl#)
ⓘ Note: Text is always the second parameter when provided. The parent# must be a valid form or container control (panel, layout).

Text Content

FunctionSignatureDescription
label_text$(lbl#)label_text$@#Get the label text
label_text#(lbl#, text$)label_text#@#$Set the label text
╯ plan9basic
─◻✕
label_text#(lbl#, "Processing...")
println "Label says: " + label_text$(lbl#)

Font Properties

FunctionSignatureDescription
label_fontfamily$(lbl#)label_fontfamily$@#Get font family name
label_fontfamily#(lbl#, family$)label_fontfamily#@#$Set font family
label_fontsize(lbl#)label_fontsize@#Get font size
label_fontsize#(lbl#, size)label_fontsize#@#nSet font size
label_fontcolor$(lbl#)label_fontcolor$@#Get font color
label_fontcolor#(lbl#, color$)label_fontcolor#@#$Set font color
label_bold(lbl#)label_bold@#Get bold state (0/1)
label_bold#(lbl#, n)label_bold#@#nSet bold (0/1)
label_italic(lbl#)label_italic@#Get italic state (0/1)
label_italic#(lbl#, n)label_italic#@#nSet italic (0/1)
label_underline(lbl#)label_underline@#Get underline state (0/1)
label_underline#(lbl#, n)label_underline#@#nSet underline (0/1)
label_strikeout(lbl#)label_strikeout@#Get strikeout state (0/1)
label_strikeout#(lbl#, n)label_strikeout#@#nSet strikeout (0/1)
╯ plan9basic
─◻✕
label_fontfamily#(lbl#, "Arial")
label_fontsize#(lbl#, 18)
label_fontcolor#(lbl#, "#0066CC")
label_bold#(lbl#, 1)
label_italic#(lbl#, 1)

println "Font: " + label_fontfamily$(lbl#) + " " + str$(label_fontsize(lbl#)) + "pt"

Text Alignment

FunctionSignatureDescription
label_textalign(lbl#)label_textalign@#Get horizontal alignment (0=center, 1=left, 2=right)
label_textalign#(lbl#, n)label_textalign#@#nSet horizontal alignment
label_vertalign(lbl#)label_vertalign@#Get vertical alignment (0=center, 1=top, 2=bottom)
label_vertalign#(lbl#, n)label_vertalign#@#nSet vertical alignment
╯ plan9basic
─◻✕
' Center text both horizontally and vertically
label_textalign#(lbl#, 0)   ' Horizontal center
label_vertalign#(lbl#, 0)   ' Vertical center

' Top-left alignment
label_textalign#(lbl#, 1)   ' Leading (left)
label_vertalign#(lbl#, 1)   ' Leading (top)

Word Wrap & Auto Size

FunctionSignatureDescription
label_wordwrap(lbl#)label_wordwrap@#Get word wrap state (0/1)
label_wordwrap#(lbl#, n)label_wordwrap#@#nEnable/disable word wrap
label_autosize(lbl#)label_autosize@#Get auto-size state (0/1)
label_autosize#(lbl#, n)label_autosize#@#nEnable/disable auto-sizing
╯ plan9basic
─◻✕
' Auto-size: label adjusts to fit text
label_autosize#(lbl#, 1)
label_text#(lbl#, "Short")
println "Width: " + str$(label_width(lbl#))  ' Shrinks to fit

' Word wrap: text wraps within a fixed width
label_autosize#(lbl#, 0)
label_size#(lbl#, 200, 80)
label_wordwrap#(lbl#, 1)
label_text#(lbl#, "This is a longer piece of text that will wrap within the label boundaries.")
⚠ Warning: Word wrap requires label_autosize#(lbl#, 0) and a fixed width. If auto-size is enabled, the label grows horizontally instead of wrapping.

Position & Size

FunctionSignatureDescription
label_x(lbl#)label_x@#Get X position
label_x#(lbl#, x)label_x#@#nSet X position
label_y(lbl#)label_y@#Get Y position
label_y#(lbl#, y)label_y#@#nSet Y position
label_width(lbl#)label_width@#Get width
label_width#(lbl#, w)label_width#@#nSet width
label_height(lbl#)label_height@#Get height
label_height#(lbl#, h)label_height#@#nSet height
label_bounds#(lbl#, x, y, w, h)label_bounds#@#nnnnSet position and size in one call
label_move#(lbl#, x, y)label_move#@#nnSet position only
label_size#(lbl#, w, h)label_size#@#nnSet size only
╯ plan9basic
─◻✕
label_bounds#(lbl#, 20, 50, 300, 60)

' Or separately
label_move#(lbl#, 20, 50)
label_size#(lbl#, 300, 60)

println "At: " + str$(label_x(lbl#)) + ", " + str$(label_y(lbl#))

Alignment & Margins

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

FunctionSignatureDescription
label_align(lbl#)label_align@#Get control alignment mode
label_align#(lbl#, n)label_align#@#nSet control alignment (0=none, 1=top, 2=left, 3=right, 4=bottom, 9=client, 11=center)
label_margin#(lbl#, n)label_margin#@#nSet uniform margin on all four sides
label_margins#(lbl#, l, t, r, b)label_margins#@#nnnnSet individual margins (left, top, right, bottom)
label_marginleft(lbl#)label_marginleft@#Get left margin
label_marginleft#(lbl#, n)label_marginleft#@#nSet left margin
label_margintop(lbl#)label_margintop@#Get top margin
label_margintop#(lbl#, n)label_margintop#@#nSet top margin
label_marginright(lbl#)label_marginright@#Get right margin
label_marginright#(lbl#, n)label_marginright#@#nSet right margin
label_marginbottom(lbl#)label_marginbottom@#Get bottom margin
label_marginbottom#(lbl#, n)label_marginbottom#@#nSet bottom margin
╯ plan9basic
─◻✕
' Dock a label to the top of a form as a header
label_align#(lbl#, 1)       ' Align top
label_height#(lbl#, 40)
label_margin#(lbl#, 5)      ' 5px spacing all sides

Visibility & Behavior

FunctionSignatureDescription
label_visible(lbl#)label_visible@#Get visibility (0/1)
label_visible#(lbl#, n)label_visible#@#nSet visibility (0=hidden, 1=visible)
label_enabled(lbl#)label_enabled@#Get enabled state (0/1)
label_enabled#(lbl#, n)label_enabled#@#nSet enabled state (0=disabled/grayed, 1=enabled)
label_opacity(lbl#)label_opacity@#Get opacity (0.0–1.0)
label_opacity#(lbl#, value)label_opacity#@#nSet opacity (0.0=transparent, 1.0=opaque)
label_hittest(lbl#)label_hittest@#Get hit-test state (0/1)
label_hittest#(lbl#, n)label_hittest#@#nEnable/disable mouse hit testing (0=click-through, 1=clickable)
⚠ Warning: Labels have hittest = 0 by default, meaning they do not receive mouse events. You must call label_hittest#(lbl#, 1) before assigning click, double-click, or mouse callbacks.

Tag & Rotation

FunctionSignatureDescription
label_tag(lbl#)label_tag@#Get user-defined integer tag
label_tag#(lbl#, n)label_tag#@#nSet user-defined integer tag
label_rotation(lbl#)label_rotation@#Get rotation angle in degrees
label_rotation#(lbl#, angle)label_rotation#@#nSet rotation angle in degrees (0–360)
╯ plan9basic
─◻✕
' Rotated label for a vertical sidebar effect
label_rotation#(lbl#, 270)     ' 270 degrees = vertical, reading bottom-to-top

' Use tags to identify labels in shared callbacks
label_tag#(lblName#, 1)
label_tag#(lblEmail#, 2)

Parent & Z-Order

FunctionSignatureDescription
label_parent#(lbl#)label_parent#@#Get parent control pointer
label_parent#(lbl#, parent#)label_parent#@##Move label to a different parent
label_bringtofront#(lbl#)label_bringtofront#@#Bring to front of Z-order
label_sendtoback#(lbl#)label_sendtoback#@#Send to back of Z-order
╯ plan9basic
─◻✕
' Move a label from the form into a panel
label_parent#(lbl#, panel#)

' Ensure label is drawn on top
label_bringtofront#(lbl#)

Events

Each event has a setter (label_onXXX#(lbl#, func$)) and a getter (label_onXXX$(lbl#)) to assign or read the callback name. Use label_clearcallbacks#(lbl#) to disconnect all callbacks at once.

⚠ Warning: Labels have hittest = 0 by default. You must call label_hittest#(lbl#, 1) before any mouse event will fire.
Event SetterGetterCallback Signature
label_onclick#(lbl#, func$)label_onclick$(lbl#)function name(sender#)
label_ondblclick#(lbl#, func$)label_ondblclick$(lbl#)function name(sender#)
label_onmousedown#(lbl#, func$)label_onmousedown$(lbl#)function name(sender#, button, x, y, shift$)
label_onmouseup#(lbl#, func$)label_onmouseup$(lbl#)function name(sender#, button, x, y, shift$)
label_onmousemove#(lbl#, func$)label_onmousemove$(lbl#)function name(sender#, x, y, shift$)
label_onmouseenter#(lbl#, func$)label_onmouseenter$(lbl#)function name(sender#)
label_onmouseleave#(lbl#, func$)label_onmouseleave$(lbl#)function name(sender#)
label_onresize#(lbl#, func$)label_onresize$(lbl#)function name(sender#)
label_clearcallbacks#(lbl#)—Disconnect all event callbacks
╯ plan9basic
─◻✕
' Make a label clickable (hyperlink style)
label_hittest#(lbl#, 1)    ' Required!
label_onclick#(lbl#, "OnLabelClick")

function OnLabelClick(sender#)
    println "Label clicked: " + label_text$(sender#)
endfunction
╯ plan9basic
─◻✕
' Mouse hover effect on a label
label_hittest#(lbl#, 1)
label_onmouseenter#(lbl#, "OnHover")
label_onmouseleave#(lbl#, "OnLeave")

function OnHover(sender#)
    label_fontcolor#(sender#, "#0066CC")
    label_underline#(sender#, 1)
endfunction

function OnLeave(sender#)
    label_fontcolor#(sender#, "#000000")
    label_underline#(sender#, 0)
endfunction

Complete Examples

Styled Labels

╯ styled.bas
─◻✕
let frm# = form#("Styled Labels", 400, 300)
form_position#(frm#, 4)

' Title label
let lblTitle# = label#(frm#, "Welcome to Plan9Basic")
label_move#(lblTitle#, 50, 30)
label_fontsize#(lblTitle#, 24)
label_fontcolor#(lblTitle#, "#0066CC")
label_bold#(lblTitle#, 1)

' Subtitle
let lblSub# = label#(frm#, "A modern BASIC interpreter")
label_move#(lblSub#, 50, 70)
label_fontsize#(lblSub#, 14)
label_italic#(lblSub#, 1)
label_fontcolor#(lblSub#, "gray")

' Description with word wrap
let lblDesc# = label#(frm#, "Create cross-platform applications easily.")
label_bounds#(lblDesc#, 50, 120, 300, 100)
label_wordwrap#(lblDesc#, 1)
label_autosize#(lblDesc#, 0)

form_show(frm#)

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

Clickable Hyperlink Label

╯ clickable.bas
─◻✕
function OnLabelClick(sender#)
    label_text#(sender#, "Clicked!")
    label_fontcolor#(sender#, "red")
endfunction

let frm# = form#("Clickable Label", 400, 200)
form_position#(frm#, 4)

let lbl# = label#(frm#, "Click me!")
label_move#(lbl#, 150, 80)
label_fontsize#(lbl#, 18)
label_fontcolor#(lbl#, "blue")
label_underline#(lbl#, 1)
label_hittest#(lbl#, 1)
label_onclick#(lbl#, "OnLabelClick")

form_show(frm#)

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

Dynamic Status Display

╯ status.bas
─◻✕
function OnStart(sender#)
    label_text#(lblStatus#, "Running...")
    label_fontcolor#(lblStatus#, "green")
endfunction

function OnStop(sender#)
    label_text#(lblStatus#, "Stopped")
    label_fontcolor#(lblStatus#, "red")
endfunction

let frm# = form#("Status Demo", 400, 200)
form_position#(frm#, 4)

let lblStatus# = label#(frm#, "Ready")
label_move#(lblStatus#, 150, 30)
label_fontsize#(lblStatus#, 16)

let btnStart# = button#(frm#, "Start", 100, 100, 80, 30)
let btnStop# = button#(frm#, "Stop", 220, 100, 80, 30)
button_onclick#(btnStart#, "OnStart")
button_onclick#(btnStop#, "OnStop")

form_show(frm#)

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

Text Alignment Showcase

╯ alignment.bas
─◻✕
let frm# = form#("Alignment Demo", 500, 300)
form_position#(frm#, 4)

' Left aligned
let lbl1# = label#(frm#, "Left aligned text")
label_bounds#(lbl1#, 50, 50, 400, 30)
label_textalign#(lbl1#, 1)

' Center aligned
let lbl2# = label#(frm#, "Center aligned text")
label_bounds#(lbl2#, 50, 100, 400, 30)
label_textalign#(lbl2#, 0)

' Right aligned
let lbl3# = label#(frm#, "Right aligned text")
label_bounds#(lbl3#, 50, 150, 400, 30)
label_textalign#(lbl3#, 2)

form_show(frm#)

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

Rotated Labels

╯ rotation.bas
─◻✕
let frm# = form#("Rotation Demo", 400, 400)
form_position#(frm#, 4)

let lbl0# = label#(frm#, "0 degrees", 180, 20)
label_fontsize#(lbl0#, 14)
label_rotation#(lbl0#, 0)

let lbl45# = label#(frm#, "45 degrees", 280, 80)
label_fontsize#(lbl45#, 14)
label_rotation#(lbl45#, 45)

let lbl90# = label#(frm#, "90 degrees", 350, 180)
label_fontsize#(lbl90#, 14)
label_rotation#(lbl90#, 90)

let lbl270# = label#(frm#, "270 degrees", 20, 180)
label_fontsize#(lbl270#, 14)
label_rotation#(lbl270#, 270)

form_show(frm#)

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

Best Practices

PracticeWhy
Call label_hittest#(lbl#, 1) before assigning mouse eventsLabels ignore mouse events by default
Use label_autosize#(lbl#, 1) for dynamic textLabel automatically resizes to fit content
Disable auto-size for fixed layouts with word wrapSet size manually with label_bounds#, then enable label_wordwrap#
Use label_tag# to identify labels in shared callbacksAvoids global variables for distinguishing multiple labels
Set font properties after creationFonts are applied immediately and affect auto-size calculations
Use label_textalign# together with fixed widthText alignment only matters when the label is wider than the text

Quick Reference

FunctionSignatureDescription
label_error / errormsg$ / strerror$ / clearerrorvariousError handling (4)
label#(parent#[, text$][, x, y][, w, h])variousCreate label (4 overloads)
label_free(lbl#)label_free@#Destroy label
label_text$ / text#label_text$@#, label_text#@#$Text get/set
label_fontfamily / fontsize / fontcolor / bold / italic / underline / strikeoutvariousFont properties (14)
label_textalign / vertalignvariousText alignment (4)
label_wordwrap / autosizevariousWrap & sizing (4)
label_x/y/width/height (get/set)variousPosition & size (8)
label_bounds# / move# / size#variousBatch position/size (3)
label_align / margin# / margins# / margin[left/top/right/bottom]variousAlignment & margins (12)
label_visible / enabled / opacity / hittestvariousVisibility & behavior (8)
label_tag / rotationvariousTag & rotation (4)
label_parent# / bringtofront# / sendtoback#variousParent & Z-order (4)
label_onclick/ondblclick/onmousedown/onmouseup/onmousemove/onmouseenter/onmouseleave/onresizevariousEvents set+get (17)
label_clearcallbacks#label_clearcallbacks#@#Disconnect all events

89 functions. Part of the Plan9Basic GUI library system.