Creates a hidden, script-owned overlay or utility window. Native geometry uses integer physical pixels in the Windows virtual-desktop coordinate space shared by Screen, Mouse, and Window; x/y identify the rendered content's absolute top-left edge. Call Show to display it and Destroy to release it.
Optionaloptions: UIOverlayOptions | null
Optional overlay options; omit or pass null for display-only hud defaults. Fractional geometry, non-positive extents, and invalid enum strings are rejected.
A script-owned handle for the newly created hidden overlay; it remains valid until Destroy, native close, or script shutdown.
Removes all child elements from this container.
Adds a read-only text label. Not persisted.
Adds a display-only progress bar. Not persisted.
Adds a styled layout box. Pass a builder function to populate it immediately. Not persisted.
Adds empty spacing between nearby controls. Not persisted.
Adds a clickable button. Not persisted.
Adds a numeric range slider. max must be greater than min or creation throws. The initial value is min; a finite saved value is restored and clamped to the inclusive range, while an invalid saved value falls back to min. SetValue and UI changes are also clamped before persistence and OnChange receives the clamped value.
Adds a single-line text input. String values are persisted by id and restored on next run. defaultText is used when no saved string exists; a wrong-type saved value also falls back to it.
Adds a boolean toggle switch. Boolean values are persisted by id and restored on next run; a wrong-type saved value falls back to false.
Adds a dropdown selector with a duplicate-free string-array of fixed options; invalid option arrays throw. The value must equal one of options; with no options, only the empty string is valid. The first option (or empty string) is the default and the fallback for a stale saved value.
Adds a multi-line text area. String values are persisted by id and restored on next run. defaultText is used when no saved string exists; a wrong-type saved value also falls back to it.
Adds a color picker. String values are persisted by id and restored on next run. defaultColor is used when no saved string exists; a wrong-type saved value also falls back to it.
Adds a hotkey capture field. The captured keyboard, mouse, or HID trigger is persisted by id and restored on next run, including its active binding.
Adds a file picker dialog button. options must be an object and filters, when supplied, must be a string array; invalid values throw. The selected string path is persisted by id and restored on next run; a wrong-type saved value falls back to an empty string. A user picker action grants this script access to the canonical path on this computer, and that machine-local grant survives restarts. Synced/restored values, another script, and SetValue never grant filesystem access.
Adds a directory picker dialog button. The selected string path is persisted by id and restored on next run; a wrong-type saved value falls back to an empty string. A user picker action grants this script access to the canonical directory on this computer, and that machine-local grant survives restarts. Synced/restored values, another script, and SetValue never grant filesystem access.
Adds a multi-select list box whose fixed choices are items. The selected values are a duplicate-free subset of items, canonicalized to item order, persisted by id, and restored on next run. Duplicate choices, unknown SetValue entries, or non-string arrays throw; stale saved data with the wrong shape or unknown entries falls back to an empty selection.
Adds a data grid with typed columns. columns must be an array of descriptors with unique string keys, string titles, a lowercase declared type, and an optional string buttonText; invalid descriptors throw before any UI node is created. An array of non-null, non-array row objects is persisted by id and restored on next run; a wrong-type saved value falls back to an empty array.
Adds a tabbed container group. Not persisted.
Adds a horizontal row layout container. Children are arranged left-to-right. Not persisted.
Adds a vertical column layout container. Children are stacked top-to-bottom. Not persisted.
Shows or re-shows the overlay and returns only after native visibility is confirmed, so a subsequent synchronous window query needs no additional delay. Optional mutable options are applied first as a partial update; null is treated as no update. The create-time transparent value cannot be changed. For noActivate overlays this does not steal foreground focus. If targetWindowId cannot be resolved, the overlay remains hidden with no virtual-desktop fallback while target-loss handling completes.
Hides the native overlay and returns only after native invisibility is confirmed, so a subsequent synchronous window query needs no additional delay. Content and callbacks are retained; a later Show reuses the same window.
Permanently destroys the overlay, its UI tree, callbacks, and file-picker grants. Closing a system-chrome native window has the same effect. This handle cannot be reused afterward.
Updates any supplied native bounds and leaves omitted fields unchanged. Windows may emit intermediate move/resize events while the native client bounds converge. null is treated as omitted and does not clear a bound. x/y are absolute rendered-content top-left coordinates in physical virtual-desktop pixels; width/height are positive integer rendered-content extents. Invalid, fractional, zero-size, or out-of-range values are rejected.
Moves the rendered content top-left to an absolute physical virtual-desktop coordinate; this is not a relative move. Screen, Mouse, Window, and overlay geometry share the same coordinate space, but callers must preserve reference points: Screen.FindImage returns a match center, while Move expects the overlay's top-left.
const boxWidth = 100;
const boxHeight = 100;
const overlay = UI.CreateOverlay({ width: boxWidth, height: boxHeight });
const match = await Screen.FindImage(selectedPath, 0.8);
if (match) {
overlay.Move(
match.x - Math.floor(boxWidth / 2),
match.y - Math.floor(boxHeight / 2),
);
}
Resizes the rendered client/content area to positive integer physical-pixel extents. Fractional, zero, negative, or out-of-range values are rejected.
Applies a partial option update. Omitted mutable fields retain their values unless mode changes, in which case unspecified mutable fields reset to the new mode's defaults. The create-time transparent value is preserved; attempting to change it throws. Numeric geometry and min/max fields reject null; replace them or change mode to reset defaults. targetWindowId is the exception: null is ignored and an empty string clears it. Geometry changes use the same physical coordinate contract as SetBounds.
Merges CSS-like renderer style into the overlay root. Style dimensions use CSS logical pixels; this does not change native physical window bounds.
Registers the callback invoked once when the current targetWindowId disappears. Target loss also hides the overlay. Register before loss; a later registration replaces the previous callback.
A detached overlay surface and UIContainer. CreateOverlay returns it hidden. Show and Hide may be called repeatedly. Destroy, or closing a system-chrome native window, permanently releases the overlay and makes later calls on this handle fail. HUD overlays are display-only and reject interactive UI controls.