controls

Controls

Grid-based layout, styled buttons, sliders, inputs, hold-to-confirm buttons, bound controls, and layout helpers.

Quick Start

local wu = GetMod("WindowUtils")
local c = wu.Controls

-- Slider with icon, 8-column width, right-click reset
local val, changed = c.SliderFloat(IconGlyphs.Reload, "mySlider", value, 0, 100, {
    format = "%.1f", cols = 8, default = 50, tooltip = "Brightness"
})

-- Full-width styled button
if c.Button("Apply", "active", -1) then apply(val) end

Controls Reference

All controls are accessed via controls.* (or wu.Controls.* from external mods).

Control	Description
controls.Button(label, style?, width?, height?)	Styled button
controls.ToggleButton(label, isActive, width?, height?)	Active/inactive toggle button
controls.FullWidthButton(label, style?)	Button filling available width
controls.DisabledButton(label, width?, height?)	Non-interactive greyed-out button
controls.DynamicButton(label, icon, opts?)	Adaptive button (text, truncated, or icon)
controls.StatusBar(label, value?, opts?)	Non-interactive status display
controls.ButtonRow(defs, opts?)	Row of buttons with auto width distribution
controls.ButtonBlock(defs, opts?)	Wrapping/grid multi-button layout
controls.IconButton(icon, clickable?)	Icon glyph on a transparent button background
controls.SliderFloat(icon, id, value, min, max, opts?)	Float slider with icon
controls.SliderInt(icon, id, value, min, max, opts?)	Integer slider with icon
controls.SliderDisabled(icon?, label)	Greyed-out slider placeholder
controls.TimeSlider(icon, id, value, opts?)	Time-of-day slider (AM/PM format)
controls.DragFloat(icon, id, value, min, max, opts?)	Float drag with Shift precision
controls.DragInt(icon, id, value, min, max, opts?)	Integer drag with Shift precision
controls.DragFloatRow(icon, id, drags, opts?)	Multi-drag float row with theming
controls.DragIntRow(icon, id, drags, opts?)	Multi-drag integer row with theming
controls.TimeDrag(icon, id, value, opts?)	Time-of-day drag (AM/PM format)
controls.InputText(icon, id, text, opts?)	Text input with icon
controls.InputFloat(icon, id, value, opts?)	Float input with step buttons
controls.InputInt(icon, id, value, opts?)	Integer input with step buttons
controls.Checkbox(label, value, opts?)	Checkbox with icon and reset
controls.Combo(icon, id, index, items, opts?)	Dropdown with icon
controls.StringCombo(icon, id, value, items, opts?)	String-valued dropdown with icon
controls.SearchBar(state, opts?)	Search input with magnify/clear icon
controls.SearchBarPlain(state, opts?)	Search input with placeholder text
controls.ProgressBar(fraction, width?, height?, overlay?, style?)	Styled progress bar
controls.ColorEdit4(icon, id, color, opts?)	Color picker with icon
controls.SwatchGrid(id, colors, selectedHex, onSelect, config?)	Color swatch grid
controls.HoldButton(id, label, opts?)	Hold-to-confirm button
controls.ActionButton(id, label, opts?)	Primary click + secondary hold button
controls.StatusRow(id, label, labelStyle?, actionDef?, opts?)	Non-interactive status label with optional hold-action icon
controls.getHoldProgress(id)	Hold progress of a hold button, or nil
controls.ShowHoldProgress(sourceId, width?, style?)	Progress bar for another button's hold
controls.getFirstActiveHoldProgress(ids)	Progress + source ID of first active hold
controls.ShowFirstActiveHoldProgress(ids, width?, style?)	Progress bar for first active hold
controls.resetHoldState(id) / controls.resetAllHoldStates()	Clear hold state
controls.Panel(id, contentFn, opts?)	Styled child window panel
controls.getPanelAutoHeight(id)	Cached measured height for height = "auto" panels
controls.PanelGroup(id, contentFn, opts?)	Group-based panel (no nested scroll)
controls.BeginFillChild(id, opts?)	Fill remaining vertical space
controls.EndFillChild(id)	End fill child region
controls.Row(id, defs, opts?)	Horizontal child window layout
controls.MultiRow(id, rows, defs, opts?)	Multi-row cell layout
controls.Column(id, defs, opts?)	Vertical child window layout
controls.Separator(spacingBefore?, spacingAfter?)	Horizontal separator
controls.SectionHeader(label, spacingBefore?, spacingAfter?, iconGlyph?, tooltip?, opts?)	Separator + label
controls.HeaderIconGlyph(opts)	Right-justified icon on current line
controls.TextMuted(text)	Grey text
controls.TextSuccess(text)	Green text
controls.TextDanger(text)	Red text
controls.TextWarning(text)	Yellow text
controls.bind(data, defaults?, onSave?, opts?)	Create bound control context
controls.unbind(ctx)	Return bind context to pool
controls.ColWidth(cols, gap?, hasIcon?)	Column grid width calculator
controls.RemainingWidth(offset?)	Remaining available width
controls.Scaled(value)	Scale 1080p value to current resolution

The controls table aggregates every control submodule, so every control above resolves through it. Keys reachable on it that are not documented here are internal wiring and not supported API.

Sub-File Index

File	Contents
buttons	Button, ToggleButton, FullWidthButton, DisabledButton, StatusBar, DynamicButton, ButtonRow
sliders	SliderFloat, SliderInt, SliderDisabled, TimeSlider
drags	DragFloat, DragInt, DragFloatRow, DragIntRow, TimeDrag, Preset Colors
inputs	InputText, InputFloat, InputInt, Checkbox, Combo, StringCombo, SearchBar, SearchBarPlain
holdbuttons	HoldButton, ActionButton, StatusRow, hold progress helpers
display	ProgressBar, ColorEdit4, SwatchGrid, Text*, Separator, SectionHeader, HeaderIconGlyph
layout	Row, MultiRow, Column, BeginFillChild/EndFillChild, Panel, PanelGroup
bind	bind/unbind, all bound methods

Grid System

Controls uses a 12-column grid (Bootstrap-style) to calculate widths relative to available space.

ColWidth(cols, gap?, hasIcon?)

Calculate pixel width for a column span.

Parameter	Type	Default	Description
cols	number	12	Columns to span (1-12)
gap	number	ItemSpacing.x	Gap between elements in pixels
hasIcon	boolean	false	Adjust for icon prefix width

Returns: number - width in pixels (minimum 20px)

-- Half-width button
c.Button("Save", "active", c.ColWidth(6))

-- Three equal buttons on one line
for i, label in ipairs({"A", "B", "C"}) do
    if i > 1 then ImGui.SameLine() end
    c.Button(label, "inactive", c.ColWidth(4))
end

RemainingWidth(offset?)

Returns available width minus optional offset.

Scaled(value)

Scale a 1080p baseline value to the current display resolution.

Architecture

The controls module is split into focused sub-modules under modules/controls/:

Sub-Module	Contents
core.lua	Shared foundation: frameCache, Scaled, ColWidth, IconButton, time helpers
display.lua	ProgressBar, ColorEdit4, SwatchGrid, Text*, Separator, SectionHeader
buttons.lua	Button, ToggleButton, FullWidthButton, DisabledButton, StatusBar, DynamicButton, ButtonRow
sliders.lua	SliderFloat, SliderInt, SliderDisabled, TimeSlider
holdbuttons.lua	HoldButton, ActionButton, hold progress helpers
inputs.lua	InputText, InputFloat, InputInt, Checkbox, Combo, SearchBar, SearchBarPlain
drags.lua	DragFloat, DragInt, DragFloatRow, DragIntRow, TimeDrag
layout.lua	Row, MultiRow, Column, BeginFillChild, EndFillChild
panels.lua	PanelGroup, Panel
bind.lua	bind/unbind, bindMethods

A thin aggregator at modules/controls.lua re-exports all sub-module APIs into a single controls table. No API changes for consumers: all controls.* calls work identically.

SearchBar and SearchBarPlain (previously in search.lua) are now part of the controls system in inputs.lua. See search for the updated search module scope.

Frame Cache

cacheFrameState()

Populates the per-frame style/metric cache. Called automatically once per onDraw frame by WindowUtils before any control rendering. You do not need to call this yourself unless you are using Controls outside of the standard WindowUtils draw loop.

getFrameCache()

Returns the cached frame metrics table. Useful for dynamic sizing that scales with font/DPI.

Returns: table with fields:

Field	Source	Description
itemSpacingX	Style.ItemSpacing.x	Horizontal spacing between items
itemSpacingY	Style.ItemSpacing.y	Vertical spacing between items
framePaddingX	Style.FramePadding.x	Horizontal frame padding
windowPaddingX	Style.WindowPadding.x	Horizontal window padding
windowPaddingY	Style.WindowPadding.y	Vertical window padding
frameHeight	GetFrameHeight()	Height of a framed widget
textLineHeight	GetTextLineHeightWithSpacing()	Text line height with spacing
frameRounding	Style.FrameRounding	Corner rounding for framed widgets
minIconButtonWidth	Computed	Minimum icon button width (icon + 2x framePadding)
charWidth	CalcTextSize("M")	Width of reference character "M"
ellipsisWidth	CalcTextSize("...")	Width of truncation ellipsis
displayWidth	GetDisplayResolution()	Screen width in pixels
displayHeight	GetDisplayResolution()	Screen height in pixels

local cache = c.getFrameCache()
local headerH = cache.frameHeight  -- scales with font/DPI