display

Display Controls

Progress bars, color pickers, swatch grids, colored text, separators, and section headers.

Quick Start

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

-- Progress bar
c.ProgressBar(0.75, nil, 0, "75%", "success")

-- Color picker with icon and reset
local color, changed = c.ColorEdit4(IconGlyphs.Palette, "accent", settings.accentColor, {
    default = { 0.2, 0.6, 1.0, 1.0 }
})

-- Section header with icon
c.SectionHeader("Settings", 10, 0, {
    icon = "InformationBox",
    tooltip = "Hover for details",
})

---

ProgressBar(fraction, width?, height?, overlay?, styleName?)

Styled progress bar.

Parameter	Type	Default	Description
fraction	number	-	Progress 0-1
width	number|nil	full width	Bar width
height	number	0	Bar height
overlay	string	""	Overlay text
styleName	string|table	"default"	"default", "danger", "success", or custom color table

Custom color table: { fill = {r,g,b,a}, frameBg = {r,g,b,a}, border = {r,g,b,a}, borderSize = 2.0 }

frameBg and border are required when passing a table; they are read without a nil check and a missing one will error. fill and borderSize are optional (borderSize defaults to 2.0, and omitting fill leaves the current PlotHistogram color alone).

ColorEdit4(icon, id, color, opts?)

Color picker with icon prefix and right-click reset.

Parameter	Type	Default	Description
icon	string|nil	-	IconGlyph
id	string	-	Unique picker ID
color	table	-	RGBA color {r,g,b,a}
opts.label	string|nil	nil	Text label before the picker
opts.default	table|nil	nil	Right-click reset color
opts.tooltip	string|nil	nil	Icon tooltip. Always shown regardless of the global tooltip setting
opts.elementId	string|nil	nil	Tutorial/bounds target ID. Only reported while bounds reporting is active

Returns: table, boolean - new {r,g,b,a} color, whether changed

Rendered with NoOptions, so the right-click context menu ImGui normally offers is unavailable; right-click is used for the reset instead. The picker always fills the width remaining after the icon and label.

SwatchGrid(id, colors, selectedHex, onSelect, config?)

Grid of colored swatch buttons with dynamic column layout, optional hue sorting, and category grouping. All pixel values are specified at 1080p baseline and scaled internally to the current display resolution.

Parameter	Type	Default	Description
id	string	-	Unique ImGui ID for this grid instance
colors	table	-	Array of Color_Entry tables
selectedHex	string|nil	nil	Hex of the currently selected color (for highlight)
onSelect	function	-	Callback: onSelect(entry) called when a swatch is clicked
config	table|nil	nil	Swatch_Config overrides (merged with defaults)

Returns immediately without rendering if colors is nil or empty.

Color_Entry format:

Field	Type	Required	Description
name	string	Yes	Identifier for this color, also the tooltip label when displayName is unset
hex	string	Yes	6-character hex code (# prefix tolerated). Invalid values fall back to mid-grey
displayName	string	No	Tooltip label (defaults to name)
category	string	No	Grouping key; entries with the same category are grouped with a labeled separator

Entries without a category are collected into their own unlabeled group, positioned in the order that group was first encountered. Sorting happens within each group, never across groups. hex doubles as the cache fingerprint, so two entries sharing a hex are still rendered separately but the sort result is cached per hex sequence.

Swatch_Config options:

Field	Type	Default	Description
swatchSize	number	24	Base swatch size (1080p px, scaled internally). Max is always 2x this value.
swatchSpacing	number	4	Gap between swatches (1080p px)
borderSize	number	2	Selection highlight border thickness (supports floats)
scaleBorder	boolean	false	Scale border proportionally with swatch size (baseline: borderSize at size 24)
sortMode	string|boolean	false	Sort mode: false/nil/"none", true/"hue", or "lightness"

Caller-provided config fields override defaults; missing fields use defaults.

local myColors = {
    { name = "Sunset Orange", hex = "FD9E51", category = "warm" },
    { name = "Cherry Red",    hex = "CC2244", category = "warm" },
    { name = "Ocean Blue",    hex = "2266AA", category = "cool" },
    { name = "Forest Green",  hex = "228844", category = "cool" },
    { name = "Slate Grey",    hex = "778899", category = "neutral" },
}

c.SwatchGrid("myGrid", myColors, selectedHex, function(entry)
    selectedHex = entry.hex
end, { sortMode = "hue" })

Text Display

Function	Color
TextMuted(text)	Grey
TextSuccess(text)	Green
TextDanger(text)	Red
TextWarning(text)	Yellow

Separator(spacingBefore?, spacingAfter?)

Horizontal separator with optional spacing.

SectionHeader(label, spacingBefore?, spacingAfter?, iconGlyph?, tooltip?, opts?)

Separator + label text with optional spacing, right-justified icon glyph, hover tooltip, and separator positioning.

Parameter	Type	Default	Description
label	string	-	Section title text
spacingBefore	number|nil	nil	Vertical spacing before separator
spacingAfter	number|nil	nil	Vertical spacing after label
iconGlyph	table|nil	nil	HeaderIconGlyph opts table (see below)
tooltip	string|nil	nil	Tooltip text shown when hovering the header label
opts	table|nil	nil	Additional options
opts.separatorAfter	boolean	false	Put separator below text instead of above

The tooltip attaches to the label text itself (not the icon or spacer), so users can hover the header to see usage information.

-- Default: separator above text
c.SectionHeader("Settings", 8, 4)

-- With tooltip on hover
c.SectionHeader("Settings", 8, 4, nil, "Hover tooltip text")

-- Separator below text
c.SectionHeader("Settings", 8, 4, nil, nil, { separatorAfter = true })

HeaderIconGlyph(opts)

Renders a right-justified icon glyph on the current ImGui line. Intended for use after header or section header text to show contextual icons, warnings, or info indicators.

Field	Type	Default	Description
icon	string	-	IconGlyphs key name (e.g. "AlertBox") or raw glyph string
tooltip	string|nil	nil	Tooltip text shown on hover
color	table|nil	nil	RGBA color {r, g, b, a} applied to the icon text
visible	boolean|nil	true	If false, skips rendering entirely
onClick	function|nil	nil	Click callback
alwaysShowTooltip	boolean|nil	false	Show tooltip even when tooltipsEnabled is off

The icon always renders as a frameless button (via styles.PushButtonFrameless), whether or not onClick is set, because hover detection on plain text is unreliable in CET. onClick only decides whether the click does anything.

The icon is placed with SameLine(contentMax - iconWidth), so it lands on the current line. Call it right after the text it belongs to.

Returns nothing. If IconGlyphs is nil (CET not fully loaded), or visible is false, or icon resolves to nil, the function returns immediately without rendering.

-- Info icon with tooltip
controls.SectionHeader("Settings", 10, 0, {
    icon = "InformationBox",
    tooltip = "Hover for details about this section",
    alwaysShowTooltip = true,
})

-- Warning icon with click handler
controls.SectionHeader("Experimental", 10, 0, {
    icon = "AlertBox",
    tooltip = "Click to review disclaimer",
    onClick = function() openDisclaimer() end,
})

-- Conditional visibility
controls.SectionHeader("Constraints", 10, 0, {
    icon = "AlertCircleOutline",
    tooltip = "Active constraints detected",
    color = { 1, 0.8, 0, 1 },
    visible = hasConstraints,
})