Skip to content

Home

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

WindowUtils

A universal ImGui window management library for Cyber Engine Tweaks mods. Provides grid snapping, smooth animations, collapse-safe window sizing, styled controls, and a master settings GUI.

WUBanner

Features

  • Grid Snapping - Windows snap to a configurable grid on drag release
  • Smooth Animations - Multiple easing functions (linear, easeIn, easeOut, easeInOut, bounce)
  • Collapse-Safe Sizing - Windows remember their size when collapsed/expanded
  • Expand Panels - Toggle panels that grow/shrink the window with three size modes
  • Controls Library - Styled buttons, sliders, drags, checkboxes, combos, color pickers, search, tabs, modals, notifications, drag-drop, lists
  • Master Settings GUI - Central control panel for all mods using WindowUtils
  • Window Browser - Browse, toggle, hide, and ignore all discovered CET windows
  • Per-Window Configuration - Override settings for individual windows
  • Tutorial System - Step-by-step guided tutorials with spotlight and persistence
  • External Window Management - Grid snap all CET windows via Window Manager plugin

Installation

Extract to bin/x64/plugins/cyber_engine_tweaks/mods/WindowUtils/. The settings window appears when the CET overlay opens.

Quick Start

Replace ImGui.Begin/ImGui.End with wu.Begin/wu.End. That's it.

local wu = nil

registerForEvent("onInit", function()
    wu = GetMod("WindowUtils") or ImGui
end)

registerForEvent("onDraw", function()
    if wu.Begin("My Window") then
        ImGui.Text("Content here")
    end
    wu.End()
end)

WindowUtils handles grid snapping, animation, registration, and collapsed-window tracking automatically. No separate Update() call needed.

Optional Dependency

The or ImGui fallback means your mod works identically whether WindowUtils is installed or not. Extra arguments (like the opts table) are silently discarded by CET's native ImGui binding.

Options Table

Pass an opts table as the last argument to control behavior per-window:

-- Skip grid management when docked (e.g. full-width bottom panel)
wu.Begin("Timeline", true, flags, { skip = isDocked })

-- Mark a window as permanently ignored (no management, no grid snap)
wu.Begin("##overlay", { ignored = true })
Option Type Description
skip boolean Temporarily skip Update() this frame (window stays registered). Only the literal value true skips
ignored boolean Permanently mark as ignored (first call writes to disk)
pOpen boolean Register the window as having a close button without passing pOpen positionally

Locking Windows

There is no standalone lock function. Windows become locked as a side effect of the calls that pin their state:

wu.API.IgnoreWindow("##drag")           -- ignored + locked
wu.API.SetCloseButton("##overlay")      -- probeOverride + locked
wu.Begin("##drag", { ignored = true })  -- ignored + locked on first call

Locked windows appear under the "Locked" section in the browser with all controls disabled.

Window Tags

Append a tag to any window name to control how WindowUtils handles it. Works with both wu.Begin and raw ImGui.Begin, including inside ImGui's ## ID syntax.

Tag Effect
-wui Ignored - no management, no browser entry
-wuo Override - window gets a close button (probeOverride) 
-- Ignored utility overlay
ImGui.Begin("##drag-wui")

-- Ignored with a visible title
ImGui.Begin("Depth Selection##wb-wui")

See begin for details.

Close Button Detection

If you pass pOpen (boolean) as the second arg, WindowUtils automatically registers the window with hasCloseButton = true:

-- Detected as having a close button
local visible, open = wu.Begin("My Panel", true, flags)

Manual Control (Advanced)

For cases where you need explicit control over grid snapping, you can still use the traditional pattern:

wu.SetConstraints(200, 150, 600, 800, "My Window")

if ImGui.Begin("My Window") then
    ImGui.Text("Content here")
end
wu.Update("My Window")
ImGui.End()

This gives you access to SetConstraints and per-call Update options but requires more boilerplate.

Public API

Core Window Management

Function Description
wu.Begin(name, ...) Drop-in replacement for ImGui.Begin with automatic grid management
wu.End() Drop-in replacement for ImGui.End
wu.Update(name, opts?) Manual window state processing (grid snap, animation, drag detection)
wu.SetConstraints(minW, minH, maxW, maxH, name?) Grid-aligned size constraints
wu.SetConstraintsPct(minW%, minH%, maxW%, maxH%, name?) Percentage-based constraints
wu.SnapToGrid(value, name?) Snap a value to nearest grid point
wu.GridAlignMin(value, name?) Align minimum constraint to grid
wu.GridAlignMax(value, name?) Align maximum constraint to grid
wu.Lerp(a, b, t) Linear interpolation
wu.ApplyEasing(t, name?) Apply configured easing function

State Queries

Function Description
wu.IsAnimating(name) Check if snap animation is playing
wu.GetExpandedSize(name) Get remembered expanded size
wu.CompleteAnimation(name) Force-finish animation
wu.ResetWindow(name) Clear all tracking state
wu.InvalidateGridCache(name?) Clear cached grid calculations
wu.isShowcaseOpen() Check if the Showcase test window is enabled
wu.isDevToolsOpen() Check if the Dev Tools window is enabled

Constraint Animations

Function Description
wu.AnimateConstraint(name, prop, target, opts?) Start smooth constraint transition
wu.UpdateConstraint(prop, normal, expanded, isExpanded) Drive animation each frame
wu.IsConstraintAnimating(prop) Check if property is animating
wu.IsAnyConstraintAnimating() Check if any animation is active
wu.IsWindowConstraintAnimating(name) Check if window has active animations

Configuration

Function Description
wu.SetDefaults(config) Override global defaults
wu.SetWindowConfig(name, config) Per-window overrides
wu.ClearWindowConfig(name) Remove per-window overrides
wu.GetConfig(name, key) Get effective config value

Priority chain: Master Override > Per-Window Config > Defaults

Sub-Modules

Module Description Docs
wu.API External mod API (settings control, window registration) api
wu.Begin / wu.End Drop-in Begin/End with auto registration, grid snap, and collapse tracking begin
wu.Controls Styled controls (buttons, sliders, drags, inputs, layout) controls
wu.Styles ImGui style push/pop helpers styles
wu.Tooltips Tooltip rendering utilities tooltips
wu.Utils Shared utilities (truncation, color conversion, key state) utils
wu.Splitter Draggable panel dividers (2-panel, multi, toggle) splitter
wu.Expand Automatic window resizing for toggle panels expand
wu.Tabs Styled tab bars with badges tabs
wu.DragDrop Drag and drop utilities dragdrop
wu.Notify Toast notification system notifications
wu.Search Multi-word search state management search
wu.Modal Centered popup dialogs modal
wu.Lists Scrollable item lists with drag reorder lists
wu.Popout Detachable popout windows popout
wu.IconBrowser Icon glyph browser iconbrowser
wu.Tutorial Step-by-step guided tutorials tutorial
wu.Hint Pulsing element hints hint

Other Exports

Name Description
wu.ReportBounds(elementId, padRight?) Report an element's screen bounds for tutorial spotlights and hints. No-op unless a tutorial is running or a click target is registered for that id
wu.NAME, wu.ICON, wu.VERSION Display name, icon glyph, and version string
wu.runtimeData { cetOpen = boolean }, updated on overlay open/close

Configuration Keys

Key Type Default Description
gridUnits number 2 Grid multiplier (grid = gridUnits * 20px)
gridEnabled boolean true Enable grid snapping
snapCollapsed boolean true Snap collapsed windows
animationEnabled boolean true Enable snap animations
animationDuration number 0.2 Animation duration (seconds)
easeFunction string "easeOut" Easing function name

Structure

WindowUtils/
├── init.lua              # Entry point and public API
├── data/
│   ├── settings.json     # Master settings
│   ├── windows.json      # Per-window overrides/hidden/ignored
│   └── window_cache.json # Cached window dimensions
├── docs/                 # Per-module documentation
├── core/
│   ├── core.lua          # Window state, grid snap, animations, constraints
│   ├── settings.lua      # Configuration and persistence
│   ├── external.lua      # External window management (probe, drag, snap)
│   ├── effects.lua       # Blur, dim, grid visualization
│   ├── discovery.lua     # Window enumeration via RedCetWM
│   ├── bounds.lua        # UI element bounds tracking
│   ├── framecontext.lua  # Per-frame timing
│   └── registry.lua      # Window metadata registry
├── modules/
│   ├── begin.lua         # Begin/End wrapper (auto registration, update, ignore)
│   ├── controls/         # Control sub-modules (buttons, sliders, drags, etc.)
│   ├── splitter/         # Splitter sub-modules (core, split, toggle)
│   ├── expand.lua        # Expand panel window resizing
│   ├── styles.lua        # ImGui style helpers
│   ├── tooltips.lua      # Tooltip utilities
│   ├── tabs.lua          # Tab bars
│   ├── modal.lua         # Modal dialogs
│   ├── notifications.lua # Toast notifications
│   ├── search.lua        # Search state
│   ├── tutorial.lua      # Tutorial engine
│   ├── hint.lua          # Element hints
│   └── ...               # Other modules
└── ui/
    ├── ui.lua            # Settings window
    ├── uidefs.lua        # Setting metadata
    ├── browser.lua       # Window browser
    └── iconwindow.lua    # Icon browser window

Optional Dependencies

  • BlurUtils (CyanideX) - Background blur effects
  • Window Manager / RedCetWM (RED4ext plugin) - External window management and browser

License

Copyright (c) 2026 CyanideX https://next.nexusmods.com/profile/theCyanideX/mods

Clone this wiki locally