Skip to content

api

Jump to bottom
CyanideX edited this page Aug 5, 2026 · 2 revisions

API

Public interface for other mods to control WindowUtils programmatically.

Quick Start

local wu = GetMod("WindowUtils")
local api = wu.API

-- Toggle the settings window
api.Toggle()

-- Read and modify settings
local s = api.Get()
print(s.gridEnabled)

api.Set({ gridEnabled = false, animationDuration = 0.3 })

Settings Window Control

Function Description
api.Toggle() Toggle the settings window open/closed
api.Show() Open the settings window
api.Hide() Close the settings window
api.IsVisible() Check if the settings window is currently open

Returns: api.IsVisible() returns boolean

-- Add a button to your mod that opens WindowUtils settings
local WindowUtils = GetMod("WindowUtils")
if WindowUtils then
    if ImGui.Button("Window Utils Settings") then
        WindowUtils.API.Toggle()
    end
end

Settings Access

api.Get()

Get the current master settings table (mutable reference). Changes take effect immediately. Call api.Save() to persist after direct modifications.

Returns: table - live settings table

local s = api.Get()
s.blurOnOverlayOpen = true
api.Save()

api.GetDefaults()

Get the default settings table (read-only reference). Writes will error.

Returns: table - frozen defaults table

local defaults = api.GetDefaults()
print(defaults.gridUnits)  -- inspect default values

api.Set(settingsTable)

Apply multiple settings at once with validation. Validates each key, writes valid ones, saves to disk, and handles side effects (e.g., invalidating the grid cache when gridUnits changes). Invalid keys or values are skipped with a debug message.

Parameter Type Description
settingsTable table Key-value pairs of settings to apply

Returns: boolean - true if any settings were applied

api.Set({
    gridEnabled = true,
    animationDuration = 0.15,
    tooltipsEnabled = false,
})

api.Save()

Persist current settings to disk.

Returns: boolean - success

api.Reset()

Reset all settings to defaults, save to disk, and invalidate the grid cache.

api.Reload()

Reload settings from disk (discards in-memory changes) and invalidate the grid cache. Loaded values are validated, and invalid entries are rejected with a debug log and fall back to their defaults.

Window Registration

Register windows with metadata so WindowUtils can manage them correctly during external window management. Windows with a close button (pOpen) bypass the empty-shell probe state machine.

api.RegisterWindow(windowName, options)

Parameter Type Description
windowName string Window name (supports ### stable ID syntax)
options table|nil { hasCloseButton = boolean }. Optional, defaults to {} (no close button)

Returns: boolean - success

api.RegisterWindow("My Window###mywin", { hasCloseButton = true })

api.UnregisterWindow(windowName)

Parameter Type Description
windowName string Window name to unregister

Returns: boolean - success

api.UnregisterWindow("My Window###mywin")

Window Ignore

Exclude windows from Override All Windows management. Ignored windows are skipped entirely by the external window manager (no probing, no snapping, no Begin calls).

api.IgnoreWindow(windowName, ignored?)

Parameter Type Description
windowName string ImGui window name to ignore/unignore
ignored boolean|nil true to ignore, false to unignore. Omitted means true

Returns: boolean - success (true even if already in requested state)

The ignored flag and the locked flag are written together, so ignoring a window also locks it in the browser and unignoring unlocks it.

Validation:

  • Returns false and logs if windowName is not a non-empty string
  • Returns true without disk write if the window is already in the requested state
-- Ignore your mod's windows so Override All Windows doesn't snap them
local wu = GetMod("WindowUtils")
if wu and wu.API and wu.API.IgnoreWindow then
    wu.API.IgnoreWindow("##MyModTaskbar", true)
    wu.API.IgnoreWindow("##MyModPopup", true)
end

-- Unignore later
wu.API.IgnoreWindow("##MyModTaskbar", false)

Persists to data/windows.json. Takes effect on the next frame (shouldManageWindow() returns false for ignored windows).

Window Overrides

api.SetCloseButton(windowName, value?)

Declare whether a window has a close button (pOpen), bypassing the empty-shell probe. Also locks the window in the browser.

Parameter Type Description
windowName string ImGui window name
value boolean|nil true if the window has a close button. Omitted means true

Returns: boolean - success (false only if windowName is not a non-empty string)

api.SetCloseButton("My Panel###mypanel")

api.SetProbeSkip(windowName, enabled?)

Skip the external probe state machine for a window. Useful for windows that misbehave when probed.

Parameter Type Description
windowName string ImGui window name
enabled boolean|nil true to skip probing, false to resume. Omitted means true

Returns: boolean - success (false only if windowName is not a non-empty string)

Both functions persist to data/windows.json.

Drag-End Callback

Register listeners that fire when a managed window's drag operation completes with a position or size change. Callbacks fire after the snap target is computed but before the snap animation begins, giving consumers the final resting position.

Supports multiple listeners (from different mods). Each listener is wrapped in pcall, so one misbehaving listener cannot break others or WindowUtils itself.

api.OnDragEnd(fn)

Parameter Type Description
fn function Callback function receiving drag-end data

Returns: boolean - true if registration succeeded, false if fn is not a function

Callback Signature

function(windowName, preDrag, postDrag)
Argument Type Description
windowName string ImGui window name (same identifier used by WindowUtils state tracking)
preDrag table Window geometry at drag start: { x, y, w, h }
postDrag table Window geometry at computed final position: { x, y, w, h }

Geometry fields:

  • x, y - window position in pixels
  • w, h - expanded window size (even when collapsed, reports the remembered expanded dimensions)

Invocation timing:

  • With grid enabled: fires after grid-snapped target position is computed, before animation starts
  • With grid disabled: fires with the raw release position

Behavior notes:

  • Does NOT fire when a drag ends without a position or size change (grab and release at same spot)
  • Multiple registrations of the same function will cause it to fire multiple times per event

Example

local wu = GetMod("WindowUtils")

wu.API.OnDragEnd(function(windowName, preDrag, postDrag)
    print(windowName .. " moved from " .. preDrag.x .. "," .. preDrag.y
        .. " to " .. postDrag.x .. "," .. postDrag.y)
    print("Size: " .. postDrag.w .. "x" .. postDrag.h)
end)

Intermod: Window State

Query and control WU-managed windows from other mods. These functions only work on windows WindowUtils has claimed, meaning windows drawn with wu.Begin or windows that call wu.Update() each frame.

api.IsManaged(windowName)

Check if a window is actively managed by WindowUtils (calls core.update each frame).

Parameter Type Description
windowName string ImGui window name

Returns: boolean

api.GetState(windowName)

Read a managed window's current geometry. Returns nil if the window is not managed or hasn't rendered its first frame yet.

Parameter Type Description
windowName string ImGui window name

Returns: table|nil - { x, y, w, h, collapsed }

Field Type Description
x number Window X position
y number Window Y position
w number Expanded width
h number Expanded height
collapsed boolean Whether the window is collapsed 
local state = api.GetState("My Window")
if state then
    print(state.x, state.y, state.w, state.h, state.collapsed)
end

Always reflects the window's actual current-frame geometry, even for windows your mod doesn't own and regardless of draw order between mods.

api.HideWindow(windowName)

Hide a managed window by moving it offscreen (10000, 10000) and collapsing it. Returns the captured geometry so it can be restored later. The move is queued and applied on the window's next update, and grid snap, drag detection, and animation stay suspended until it is restored.

Parameter Type Description
windowName string ImGui window name

Returns: table|nil - captured geometry { x, y, w, h, collapsed }, or nil if not managed

local posData = api.HideWindow("My Window")
-- Later:
api.RestoreWindow("My Window", posData)

The returned geometry comes from GetState internally, so it is always the window's real current-frame position, safe to persist directly.

api.RestoreWindow(windowName, posData)

Restore a hidden window to its previous position, or center it if posData is nil/invalid.

Parameter Type Description
windowName string ImGui window name
posData table|nil Previously captured geometry from HideWindow, or nil to center

Returns: boolean - true if the restore was queued, false if the window is not managed

Coordinates at or beyond 9000 on either axis are treated as the programmatic hide zone and rejected, so the window is centered instead. Centering falls back to 400x300 when posData has no size. The restored window is also focused.

Search and Modal

Re-exports of the search and modal modules for convenience.

Field Description
api.Search Search module (see search)
api.Modal Modal module (see modal) 
local search = api.Search
local modal = api.Modal

Console Helpers

api.Info()

Print all settings keys with their current values to the CET console, sorted alphabetically. Keys that differ from their default also show the default value. Also shows quick-reference examples for api.Get() and api.Set().

-- In the CET console:
GetMod("WindowUtils").API.Info()

Clone this wiki locally