Log inGet started
Package

knob.module

Newest version

This package holds more than this page lists. See all of its files in its world.

README.md

knob

Rotary knob built on canvas interaction props. Renders a 270° dial as a track polyline + fill polyline + needle line, and wires drag/reset handlers via widgetState. Auto-registers per-id handlers on the current Z.app so callers only need to supply onChange.

Exports

  • knob(id: string, value: number, lo: number?, hi: number?, opts: KnobOpts?) -> WidgetNode — module returns the builder function directly.

Options:

  • defaultValue: number? — restored on double-click. Omit to disable reset.
  • onChange: string? — callback id; fires with { value = number } on drag/reset commit.
  • tooltip: string? — when set, wraps the canvas in a transparent tooltip panel.
  • width: number?, height: number? — canvas size. Default 34 × 34.
  • arcWidth: number? — track/fill stroke width. Default 4.
  • trackColor: string?, fillColor: string?, capColor: string? — palette overrides.
  • style: table?, app: App? — standard plumbing.

Usage

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

Z.knob("master-gain", state.gain, 0, 1, {
    defaultValue = 0.75,
    onChange     = "audio:gain",
    tooltip      = "Master gain",
})

Notes

  • Vertical drag updates the value: 1px = 0.5% of span, or 0.05% when Shift is held (10× finer for fine adjustment). Drag up increases.
  • Double-click restores defaultValue if set; otherwise no-op.
  • Live state lives in ui.widgetState(id, "value") — first render seeds from the supplied value, thereafter the drag handler owns it. This mirrors the Z.collapsible auto-stash pattern.
  • Handlers are registered once per id via app._knobHandlers; subsequent renders are no-ops on the handler side.
  • The fill polyline is omitted when only one segment is filled so the renderer's min-2-points guard isn't tripped.
  • The tooltip wrap is only added when opts.tooltip is set so non-tooltip knobs stay flat.