dragValue

DragValue is a Luau builder over canvas. Emits a drag-to-change numeric scrubber: background rect + centered numeric readout + an onDrag handler that accumulates the per-frame delta scaled by opts.speed. Range clamping + Shift-fine-drag (10× finer) ride on top. Auto-registers <id>:drag per id (deduped) and dispatches opts.onChange (or the widget id) with { value = newNumber } on every drag tick.

Exports

• dragValue(id: string, value: number?, lo: number?, hi: number?, opts: DragValueOpts?) -> WidgetNode — build the scrubber canvas. Default range is [0, 1]; default speed is 0.01; default format is %.2f.

Types:

• DragValueOpts = { style: DragValueStyle?, width: number?, height: number?, speed: number?, format: string?, onChange: string?, label: string?, classes: (string | { string })?, app: any? }
• DragValueStyle = { width: number?, height: number?, background: string?, color: string?, borderColor: string?, borderRadius: number?, fontSize: number?, [string]: any }
• WidgetNode = { [string]: any }

Usage

local Z = require("@builtin::modules.zui")

Z.dragValue("plug:gain", state.gain, -24, 24, {
    speed    = 0.1,
    format   = "%.1f",
    onChange = "plug:gain",  -- defaults to widget id
})

Notes

• Live value lives in ui.widgetState(id, "value"); the first render seeds it from the caller's value arg.
• Inside a Z.app context the drag handler is auto-registered and deduped per id. Outside, the canvas's onDrag is routed directly to the user's callback id (legacy raw-onCallback mode) — the handler receives the structured drag payload rather than a scalar.
• Inline text-edit on double-click is deferred. If a use case needs typing, swap to Z.input via widgetState.