Skip to content

utils

Jump to bottom
CyanideX edited this page Aug 5, 2026 · 1 revision

Utils

Low-level helper functions used across WindowUtils modules.

Quick Start

local wu = GetMod("WindowUtils")
local utils = wu.Utils

-- Resolve icon name to glyph
local icon = utils.resolveIcon("ContentSave")  -- returns the glyph character

-- Truncate text to fit a width
local display, wasCut = utils.truncateText("Very long window title here", 120)

-- Parse size specifications (pixels, percentages, or nil)
local px = utils.parseSizeSpec("25%", 800)  -- returns 200

API Reference

resolveIcon(icon)

Resolve an icon name to its glyph character. If IconGlyphs is available and the name matches, returns the glyph. Otherwise returns the input string as-is.

Parameter Type Description
icon string|nil Icon name (e.g. "ContentSave") or raw glyph string

Returns: string|nil - the resolved glyph, or nil if input was nil/empty

local glyph = utils.resolveIcon("ContentSave")  -- IconGlyphs.ContentSave
local raw = utils.resolveIcon("X")               -- "X" (no match, returned as-is)
local none = utils.resolveIcon(nil)              -- nil

truncateText(text, maxWidth)

Binary-search truncation that fits text within a pixel width, appending "..." when truncated. Must be called during onDraw (requires ImGui context for text measurement).

Parameter Type Description
text string The full text
maxWidth number Maximum pixel width

Returns: string, boolean - display text, whether truncation occurred

If maxWidth is too small to fit even the ellipsis, the result is "..." with true. Truncation is byte-based, so multi-byte glyphs can be cut mid-character.

local label, wasTruncated = utils.truncateText(windowTitle, 150)
ImGui.Text(label)
if wasTruncated then
    tooltips.ShowAlways(windowTitle)  -- show full text on hover
end

parseSizeSpec(spec, available)

Parse a size specification into pixels. Supports absolute pixels, percentage strings, or nil (flex).

Parameter Type Description
spec number|string|nil Pixel value, percentage string (e.g. "30%"), or nil
available number Total available space in pixels

Returns: number|nil - computed pixel value, or nil if spec was nil/invalid

utils.parseSizeSpec(200, 800)    -- 200 (absolute pixels)
utils.parseSizeSpec("25%", 800)  -- 200 (percentage of available)
utils.parseSizeSpec(nil, 800)    -- nil (flex / no fixed size)

A string that is not a valid percentage ("200px", "abc") returns nil, same as if it were omitted.

Used internally across the Splitter module (multi, split, and toggle) for panel size, min, and max specifications.

isCtrlHeld()

Check if either Ctrl key is currently held.

Returns: boolean

isShiftHeld()

Check if either Shift key is currently held.

Returns: boolean

isAltHeld()

Check if either Alt key is currently held.

Returns: boolean

snapToIncrement(val, increment?)

Snap a value to the nearest increment.

Parameter Type Default Description
val number - The value to snap
increment number 0.05 The snap increment

Returns: number - snapped value

utils.snapToIncrement(0.37)        -- 0.35 (nearest 0.05)
utils.snapToIncrement(0.37, 0.1)   -- 0.4 (nearest 0.1)

minIconButtonWidth(framePaddingX?)

Compute the minimum usable width for a single icon button based on live ImGui measurements. Must be called during onDraw.

Parameter Type Default Description
framePaddingX number|nil ImGui.GetStyle().FramePadding.x Override frame padding for the calculation

Returns: number - minimum pixel width (icon glyph + frame padding)

Measured from the DotsVertical glyph, falling back to "..." when IconGlyphs is unavailable.

Called once per frame by controls.cacheFrameState() and cached as frameCache.minIconButtonWidth; prefer reading the cache over calling this directly. The Splitter module uses that cached value to auto-detect minimum panel sizes.

getDragSpeed(baseSpeed, multiplier?)

Compute drag speed with shift-precision applied. ImGui natively multiplies drag speed by 10x when Shift is held, so this counters that and applies a configurable multiplier.

Parameter Type Default Description
baseSpeed number - Normal drag speed
multiplier number 0.1 Precision multiplier, only used while Shift is held

Returns: number - effective drag speed for this frame

Without Shift, baseSpeed is returned unchanged. With Shift held the result is baseSpeed * 0.1 * multiplier, so the default multiplier gives 1/100th of the base speed. The extra 0.1 cancels the 10x that ImGui applies to drags on its own when Shift is down.

cachedCalcTextSize(text, charWidth)

Cache ImGui.CalcTextSize results, invalidated when charWidth changes (font/DPI change).

Parameter Type Description
text string|nil Text to measure. nil returns 0 without touching ImGui
charWidth number Current character width for cache invalidation

Returns: number - pixel width of text

The cache holds up to 1024 entries and is dropped wholesale when it fills, so avoid feeding it unbounded generated strings.

cachedTruncateText(label, innerWidth, charWidth)

Cache truncated text results, invalidated when charWidth changes.

Parameter Type Description
label string Text to truncate
innerWidth number Available pixel width. Floored to a whole pixel for the cache key
charWidth number Current character width for cache invalidation

Returns: string, boolean - truncated text, whether truncation occurred

Cached per label, then per rounded width. The cap of 1024 counts distinct labels, not label/width pairs, and the whole cache is dropped when it fills.

Color Conversion

Pure functions for converting between hex, RGB, and HSL color representations. All RGB and HSL values use 0.0-1.0 float ranges.

HexToRGB(hex)

Convert a 6-character hex string to RGB floats. Accepts hex with or without a # prefix. Returns the fallback 0.5, 0.5, 0.5 for invalid input (nil, empty, non-string, wrong length, or non-hex characters).

Parameter Type Description
hex string|nil Hex color string, e.g. "FF8800" or "#FF8800"

Returns: number, number, number - r, g, b each 0.0-1.0

local r, g, b = utils.HexToRGB("FF0000")    -- 1.0, 0.0, 0.0
local r, g, b = utils.HexToRGB("#00FF00")   -- 0.0, 1.0, 0.0
local r, g, b = utils.HexToRGB(nil)         -- 0.5, 0.5, 0.5 (fallback)

RGBToHex(r, g, b)

Convert RGB floats to a 6-character uppercase hex string. Inputs outside [0.0, 1.0] are clamped before conversion.

Parameter Type Description
r number Red channel (0.0-1.0)
g number Green channel (0.0-1.0)
b number Blue channel (0.0-1.0)

Returns: string - 6-character uppercase hex (e.g. "FF8800")

local hex = utils.RGBToHex(1, 0, 0)         -- "FF0000"
local hex = utils.RGBToHex(0.5, 0.5, 0.5)   -- "808080"

RGBToHSL(r, g, b)

Convert RGB floats to HSL floats. Achromatic colors (where r, g, and b are equal) return h=0, s=0.

Parameter Type Description
r number Red channel (0.0-1.0)
g number Green channel (0.0-1.0)
b number Blue channel (0.0-1.0)

Returns: number, number, number - h, s, l each 0.0-1.0

local h, s, l = utils.RGBToHSL(1, 0, 0)       -- 0.0, 1.0, 0.5 (pure red)
local h, s, l = utils.RGBToHSL(1, 1, 1)       -- 0.0, 0.0, 1.0 (white, achromatic)
local h, s, l = utils.RGBToHSL(0.5, 0.5, 0.5) -- 0.0, 0.0, 0.5 (grey, achromatic)

Clone this wiki locally