Registers an element under a unique string id and returns the element table (the same spec, now with .id set). Adding with an existing id replaces it.

Removes the element registered under id. Does nothing if no such element exists.

Returns the registered element table for id. Mutating the returned table changes the element live.

Toggles the overlay open/closed (same as Shift+Tab). Takes no parameters.

Opens the overlay. Takes no parameters.

Closes the overlay (and clears any text-field focus). Takes no parameters.

Whether the overlay is currently open. Takes no parameters. Returns a boolean.

Sets a user override for an element's visibility mode. Ignored for elements whose lockMode is true.

Returns the user override mode for an element.

Gives keyboard focus to a textbox widget. Useful right after creating an element so the user can type immediately.

Width of the window in pixels — use it to centre or right-align things. Takes no parameters.

Height of the window in pixels. Takes no parameters.

How tall text will be once it is wrapped into a box w wide at size font, in pixels. This is the engine's own wrapper, not a rule that matches it — so a row laid out around the answer cannot drift from what gets drawn.

Use it to size a wrapping label, or to grow a row to fit one. A label given too little height loses its tail silently, which reads as the text simply being wrong.

local h = overlay.textHeight(s.label, 336, 14)
kids[#kids+1] = { type = "label", x = 18, y = y, w = 336, h = h, text = s.label }
y = y + math.max(46, h + 14)

The same measurement as a line count rather than a pixel height. Useful when the count itself is the decision — "does this still fit on one line?".

The element's position and size in pixels, with any units resolved for the window as it is now — nil if there is no such element. A paint element placed in units needs it: its self.x is the string it was written as ("5sw"), and this is the number to draw at. In the element's own pixels, the same ones paint draws in, even while it is shrunk to fit.

overlay.add("mymod.hud", { mode = "pinned", x = "2sw", y = "2sh", w = "20sw", h = "6sh",
    paint = function(d, self)
        local x, y, w, h = overlay.bounds(self.id)
        d:rect(x, y, w, h, 20, 24, 34, 220)
    end })

Pointer X, or -1 until the mouse has moved once. Lets an element work out where inside itself the cursor is — which row of a list it is over, say — rather than only that it is somewhere inside. Still reported while the pointer is auto-hidden. Takes no parameters.

Asked from an element's own code — its paint, the "OverlayElement" hook, its mouse callbacks, a widget's onClick — it answers in that element's coordinates, the ones it draws in. An element shrunk to fit a small window (see Fitting the window) therefore compares the pointer against its own numbers and gets the right row. Anywhere else it is window pixels.

Pointer Y, or -1 until the mouse has moved once — in the asking element's coordinates, exactly as mouseX. Takes no parameters.