inputs

Input Controls

Text inputs, numeric inputs with step buttons, checkboxes, dropdowns, and search bars.

Quick Start

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

-- Text input with icon
local name, changed = c.InputText(IconGlyphs.Account, "name", settings.name)

-- Checkbox with icon and right-click reset
local enabled, changed = c.Checkbox("Show Grid", settings.gridEnabled, {
    icon = IconGlyphs.Grid, default = true, tooltip = "Toggle grid overlay"
})

-- String-valued dropdown
local interp, changed = c.StringCombo(
    IconGlyphs.SineWave, "interp", settings.interpolationType,
    { "Linear", "Hermite", "CatmullRom", "Cosine" },
    { default = "Hermite", tooltip = "Curve type" }
)

---

InputText(icon, id, text, opts?)

Text input with optional icon, column width, and tooltip.

Parameter	Type	Default	Description
icon	string|nil	-	IconGlyph
id	string	-	Unique input ID
text	string	-	Current text
opts.maxLength	number	256	Max characters
opts.cols	number|nil	nil	Grid columns
opts.default	any|nil	nil	Right-click reset value
opts.tooltip	string|nil	nil	Icon tooltip
opts.alwaysShowTooltip	boolean	true	Show tooltip even when tooltips are disabled globally. Set false to respect the global setting
opts.elementId	string|nil	nil	Tutorial/bounds target ID

Returns: string, boolean - new text, whether changed

InputFloat(icon, id, value, opts?)

Float input with +/- step buttons.

Parameter	Type	Default	Description
opts.step	number	0.1	Small step
opts.stepFast	number	1.0	Large step (holding Ctrl)
opts.format	string	"%.2f"	Display format
opts.cols	number|nil	nil	Grid columns
opts.default	number|nil	nil	Right-click reset value
opts.tooltip	string|nil	nil	Icon tooltip
opts.alwaysShowTooltip	boolean	true	Show tooltip even when tooltips are disabled globally
opts.elementId	string|nil	nil	Tutorial/bounds target ID

Returns: number, boolean - new value, whether changed

InputInt(icon, id, value, opts?)

Integer input with +/- step buttons.

Parameter	Type	Default	Description
opts.step	number	1	Small step
opts.stepFast	number	10	Large step
opts.cols	number|nil	nil	Grid columns
opts.default	number|nil	nil	Right-click reset value
opts.tooltip	string|nil	nil	Icon tooltip
opts.alwaysShowTooltip	boolean	true	Show tooltip even when tooltips are disabled globally
opts.elementId	string|nil	nil	Tutorial/bounds target ID

Returns: number, boolean - new value, whether changed

Shared icon-control options

InputText, InputFloat, InputInt, Combo, and StringCombo all route through the same internal renderer as the sliders and drags, so they share these behaviours:

• opts.tooltip attaches to the icon prefix. With icon = nil there is no icon and no tooltip.
• opts.alwaysShowTooltip defaults to true here. Tooltips on these controls ignore the global tooltip setting unless you explicitly pass false. Checkbox is the exception and defaults to false.
• opts.default is applied on right-click of the control, returning default, true.
• opts.cols picks a 12-column grid width; omit it to fill the remaining width.

Checkbox(label, value, opts?)

Checkbox with optional icon prefix, right-click reset, and tooltip.

Parameter	Type	Default	Description
label	string	-	Checkbox label
value	boolean	-	Current checked state
opts.icon	string|nil	nil	Icon prefix (replaces the old CheckboxWithIcon)
opts.default	boolean|nil	nil	Right-click reset value
opts.tooltip	string|nil	nil	Tooltip text
opts.alwaysShowTooltip	boolean	false	Show tooltip even when tooltips are disabled globally
opts.elementId	string|nil	nil	Tutorial/bounds target ID

Returns: boolean, boolean - new value, whether changed

Unlike the icon-prefixed controls above, Checkbox defaults alwaysShowTooltip to false, so its tooltip respects the global tooltip setting. With opts.icon set the tooltip moves to the icon; without it, the tooltip attaches to the checkbox itself.

-- Simple checkbox
local enabled, changed = c.Checkbox("Enable Feature", settings.enabled)

-- With icon prefix and right-click reset
local v, ch = c.Checkbox("Show Grid", settings.gridEnabled, {
    icon = IconGlyphs.Grid, default = true, tooltip = "Toggle grid overlay"
})

Combo(icon, id, currentIndex, items, opts?)

Dropdown with optional icon, column width, right-click reset.

Parameter	Type	Default	Description
icon	string|nil	-	IconGlyph
id	string	-	Unique combo ID
currentIndex	number	-	Selected index (0-based)
items	table	-	Array of item strings
opts.cols	number|nil	nil	Grid columns
opts.default	number|nil	nil	Right-click reset index
opts.tooltip	string|nil	nil	Icon tooltip
opts.alwaysShowTooltip	boolean	true	Show tooltip even when tooltips are disabled globally
opts.elementId	string|nil	nil	Tutorial/bounds target ID

Returns: number, boolean - new index, whether changed

StringCombo(icon, id, value, items, opts?)

String-valued dropdown. Stores and returns a string instead of a numeric index. Useful when the items list may change order between versions.

Parameter	Type	Default	Description
icon	string|nil	-	IconGlyph
id	string	-	Unique combo ID
value	string	-	Current selected string value
items	table	-	Array of string labels
opts.cols	number|nil	nil	Grid columns
opts.default	string|nil	nil	Right-click reset value
opts.tooltip	string|nil	nil	Icon tooltip
opts.alwaysShowTooltip	boolean	true	Show tooltip even when tooltips are disabled globally
opts.elementId	string|nil	nil	Tutorial/bounds target ID

Returns: string, boolean - new string value, whether changed

If value is not present in items the control shows the first item, and a change returns whatever item was picked. When items is reordered the stored string is unaffected, which is the point of using this over Combo.

local interp, changed = c.StringCombo(
    IconGlyphs.SineWave, "interp", settings.interpolationType,
    { "Linear", "Hermite", "CatmullRom", "Cosine" },
    { default = "Hermite", tooltip = "Curve type" }
)

SearchBar(state, opts?)

Search input with a magnify icon prefix. Integrates with the search module for filtering bound controls. The icon switches to MagnifyClose once the query is non-empty, and clicking it clears the query. Right-clicking the input also clears it.

Parameter	Type	Default	Description
state	table|nil	-	SearchState. Returns "" and renders nothing when nil
opts.searchIcon	string|nil	nil	Icon glyph or IconGlyphs key shown when no query is active. Overrides the default magnify glyph
opts.clearIcon	string|nil	nil	Icon glyph or IconGlyphs key shown when a query is active. Overrides the default MagnifyClose glyph
opts.cols	number|nil	12	Grid columns for the input width
opts.width	number|nil	nil	Total control width in pixels. Icon width plus 4px spacing is subtracted for the input. Overrides cols
opts.elementId	string|nil	nil	Tutorial/bounds target ID

Returns: string - the query text after this frame's edits

The input is fixed at 256 characters. opts.placeholder is accepted by callers but never read here, so it has no effect. Use SearchBarPlain if you want placeholder text. The icon tooltip is hardcoded to "Search settings" / "Clear search".

The input border changes to indicate focus state automatically: blue border on hover, green border and background when the field has keyboard focus. No extra configuration is needed.

opts.elementId is only honoured while bounds reporting is active; unlike other controls it does not fall back to click-target checking.

See search for the search module documentation.

SearchBarPlain(state, opts?)

Search input with inline placeholder text via InputTextWithHint. No icon prefix by default, so the input spans the full width. Right-click the input to clear.

Parameter	Type	Default	Description
state	table|nil	-	SearchState. Returns "" and renders nothing when nil
opts.placeholder	string	"Search..."	Hint text shown while the query is empty
opts.maxLength	number	256	Max characters
opts.clearIcon	boolean|string	false	true = show default close icon; a string is treated as a glyph or IconGlyphs key override AND enables the clear button
opts.cols	number|nil	12	Grid columns for the input width
opts.width	number|nil	nil	Total control width in pixels. Overrides cols. Icon width is subtracted only when the clear icon is showing

Returns: string - the query text after this frame's edits

The input border changes to indicate focus state automatically: blue border on hover, green border and background when the field has keyboard focus. No extra configuration is needed.

opts.elementId is not supported here.

With clearIcon = true the control changes width as the query comes and goes, since the icon only appears when there is something to clear. Pass an explicit width if that shift is distracting.