Script UI

Scripts can build real windows — status displays, loot toggles, one-click panels. Layout is automatic (top to bottom, or side by side with Row), and controls can bind to functions so they update themselves while the script runs.

How it works

UI.Window(title) creates a window; factory methods on the window (Label, Button, Checkbox, TextBox, Slider, ProgressBar, Separator) add controls in order.
Callbacks (OnClick, OnChange, OnClose) and bindings (ctl:Bind(fn)) run while your script is inside Pause(ms) — a script that never pauses has a frozen window.
win:Run() is the convenience loop for pure UI scripts: it shows the window and pumps until it is closed.
UI.DestroyAll() closes everything a script created — windows are also cleaned up when the script stops.

A complete window

local win = UI.Window('Health Watch')

win:Label('Your vitals:')
local bar = win:ProgressBar(0, 100)
bar:Bind(function() return Player.Hits / Player.HitsMax * 100 end)

win:Row()                                -- next controls share one line
local heal = win:Button('Heal')
heal:OnClick(function()
    local b = Items.FindByType(0xE21)    -- bandages
    if b then Player.UseObject(b.Serial) end
end)
local quit = win:Button('Close')
quit:OnClick(function() win:Close() end)

win:Run()                                -- show + pump until closed

/

Window

window:Button

win:Button(text[, onClick])

Returns: button control table.

Parameter	Meaning
text	Button caption.
onClick optional	Function called when clicked.

Example

win:Button('Heal', function()
    Spells.Cast('Greater Heal')
end)

window:Checkbox

win:Checkbox(text[, checked][, onChange])

The onChange callback receives the new checked state; it can be passed as the second or third argument. Returns: checkbox control table.

Parameter	Meaning
text	Checkbox label.
checked optional	Initial state (default false).
onChange optional	Function called with the new value on toggle.

Example

local auto = win:Checkbox('Auto-heal', true, function(v)
    print('auto-heal: ' .. tostring(v))
end)

window:Close

win:Close()

A win:Run() loop waiting on this window ends when it closes. Returns: true.

Example

win:Button('Done', function() win:Close() end)

window:Hide

win:Hide()

Returns: the window table (chainable).

Example

win:Hide()

window:IsOpen

win:IsOpen()

Returns: boolean.

Example

while win:IsOpen() do
    Pause(100)
end

window:Label

win:Label(textOrFn[, intervalMs])

Pass a string for a static label, or a function returning a string for a live-bound label that refreshes automatically (default every 200 ms; pass intervalMs to change). Returns: label control table.

Parameter	Meaning
textOrFn	Label text, or a function returning the text.
intervalMs optional	Refresh interval for bound labels (default 200).

Example

win:Label(function() return 'HP: ' .. Player.Hits .. '/' .. Player.HitsMax end)

window:OnClose

win:OnClose(fn)

Returns: the window table (chainable).

Parameter	Meaning
fn	Function called when the window closes.

Example

win:OnClose(function()
    Messages.Info('Window closed - stopping.')
    StopScript()
end)

window:ProgressBar

win:ProgressBar([valueOrFn][, intervalMs])

Pass a number for a static value, or a function returning 0..1 for a live-bound bar (default refresh every 200 ms). Returns: progress bar control table.

Parameter	Meaning
valueOrFn optional	Value 0..1, or a function returning it.
intervalMs optional	Refresh interval for bound bars (default 200).

Example

win:ProgressBar(function() return Player.Hits / Player.HitsMax end)

window:Row

win:Row()

The returned row table offers the same element factories as the window (Label, Button, Checkbox, TextBox, Slider, ProgressBar, Separator). Returns: row table.

Example

local row = win:Row()
row:Button('Start', startFn)
row:Button('Stop', stopFn)

window:Run

win:Run([intervalMs])

The convenience main loop for UI scripts: processes button clicks, change events and bindings roughly every 50 ms (or the given interval) until the window closes. Returns: true when the window has closed.

Parameter	Meaning
intervalMs optional	Pump interval in milliseconds (default 50, minimum 20).

Example

local win = UI.Window('My tool')
win:Button('Close', function() win:Close() end)
win:Run()

window:Separator

win:Separator()

Returns: true.

Example

win:Separator()

window:SetPosition

win:SetPosition(x, y)

Returns: the window table (chainable).

Parameter	Meaning
x	Screen X position.
y	Screen Y position.

Example

win:SetPosition(100, 100)

window:SetSize

win:SetSize(width, height)

Returns: the window table (chainable).

Parameter	Meaning
width	New width.
height	New height.

Example

win:SetSize(250, 300)

window:SetTitle

win:SetTitle(title)

Returns: the window table (chainable).

Parameter	Meaning
title	New title text.

Example

win:SetTitle('Helper - running')

window:Show

win:Show()

Returns: the window table (chainable).

Example

win:Show()

window:Slider

win:Slider(min, max[, initial][, onChange])

Returns: slider control table.

Parameter	Meaning
min	Minimum value.
max	Maximum value.
initial optional	Initial value.
onChange optional	Function called with the new value on change.

Example

local threshold = win:Slider(0, 100, 60)

window:TextBox

win:TextBox([text][, onChange])

The onChange callback receives the new text; it can be passed as the first or second argument. Returns: textbox control table.

Parameter	Meaning
text optional	Initial text.
onChange optional	Function called with the new text on change.

Example

local nameBox = win:TextBox('')
nameBox:SetPlaceholder('Pet name...')

Controls

control:Bind

ctl:Bind(fn[, intervalMs])

The function runs periodically (default every 200 ms, minimum 50) and its return value updates the control: a string for labels, a number 0..1 for progress bars. Returns: the control table (chainable).

Parameter	Meaning
fn	Function returning the new value.
intervalMs optional	Refresh interval in milliseconds (default 200).

Example

hpBar:Bind(function() return Player.Hits / Player.HitsMax end, 100)

control:GetText

ctl:GetText()

Returns: string.

Example

local name = nameBox:GetText()

control:GetValue

ctl:GetValue()

Returns: number.

Example

local pct = threshold:GetValue()

control:IsChecked

ctl:IsChecked()

Returns: boolean.

Example

if auto:IsChecked() then
    Spells.Cast('Greater Heal')
end

control:OnChange

ctl:OnChange(fn)

The callback receives the new value: boolean for checkboxes, string for text boxes, number for sliders. Returns: the control table (chainable).

Parameter	Meaning
fn	Function called with the new value.

Example

threshold:OnChange(function(v)
    print('threshold: ' .. v)
end)

control:OnClick

ctl:OnClick(fn)

While a control's callback is still running, further events for the same control are dropped (double-click debounce). During a long callback that calls Pause(), other short callbacks - like a stop button - are still delivered. Returns: the control table (chainable).

Parameter	Meaning
fn	Function called when the button is clicked.

Example

myButton:OnClick(function()
    Messages.Info('Clicked!')
end)

control:SetChecked

ctl:SetChecked(checked)

Returns: the control table (chainable).

Parameter	Meaning
checked	true or false.

Example

auto:SetChecked(false)

control:SetColor

ctl:SetColor(color)

Accepts a hex string ('#FF0000' or 'FF0000') or three numbers r, g, b in the 0-255 range: ctl:SetColor(255, 0, 0). Returns: the control table (chainable).

Parameter	Meaning
color	'#RRGGBB' string, or r, g, b as three numbers.

Example

status:SetColor('#FF4040')

control:SetEnabled

ctl:SetEnabled(enabled)

Returns: the control table (chainable).

Parameter	Meaning
enabled	true to enable, false to gray out.

Example

startButton:SetEnabled(false)

control:SetPassword

ctl:SetPassword([enabled])

With no argument (or true) the text is masked; pass false to show it again. Returns: the control table (chainable).

Parameter	Meaning
enabled optional	true to mask input (default true).

Example

secretBox:SetPassword()

control:SetPlaceholder

ctl:SetPlaceholder(text)

Returns: the control table (chainable).

Parameter	Meaning
text	Placeholder text shown when the box is empty.

Example

nameBox:SetPlaceholder('Enter pet name...')

control:SetText

ctl:SetText(text)

Returns: the control table (chainable).

Parameter	Meaning
text	New text.

Example

status:SetText('Working...')

control:SetValue

ctl:SetValue(value)

Slider values are clamped to the slider's min/max range; progress bar values are 0..1. Returns: the control table (chainable).

Parameter	Meaning
value	New value.

Example

hpBar:SetValue(0.5)

control:SetVisible

ctl:SetVisible(visible)

Returns: the control table (chainable).

Parameter	Meaning
visible	true to show, false to hide.

Example

status:SetVisible(false)

control:SetWidth

ctl:SetWidth(width)

Returns: the control table (chainable).

Parameter	Meaning
width	Width in pixels.

Example

nameBox:SetWidth(180)

Nothing matches that. Try find, gump or wait.