ProControls — Documentation

New here? See the Getting Started page for HTML setup, script tags, a minimal sketch, and the common options table.

Panel ModalPanel Bevel MessageDialog InputDialog

Panel Container

A clipping container that groups ProControls into a positioned, optionally scrollable surface. Controls added with .add() are positioned relative to the panel's top-left corner — a slider at (10, 10) appears 10px from the panel edge, not the canvas edge. When child controls extend beyond the panel bounds, thin scrollbars appear automatically; the scroll wheel pans the view when no child control is hovered.

Constructor options

Option	Type	Default	Description
x, y	number	20, 20	Panel top-left position on the canvas.
width	number	300	Panel width in pixels.
height	number	200	Panel height in pixels.
visible	boolean	true	Initial visibility. Set `panel.visible = false` to hide the panel and suppress all child events.
label	string	''	Title shown in a bar at the top of the panel. When set, the scrollable content area starts below the bar and a minimize/maximize button appears on the right side of the bar. No title bar is shown when empty.
minimized	boolean	false	Initial minimized state. When `true` the panel starts collapsed to just the title bar.
minimizable	boolean	true	When `false` the −/+ toggle button is hidden and the panel cannot be collapsed.
movable	boolean	true	When `false` dragging the title bar does not reposition the panel.
resizable	boolean	false	When `true` a resize grip appears in the bottom-right corner; drag it to change the panel's `width` and `height` at runtime.
onChange	function	null	`onChange({ fieldName: value, … }[, panel])` — called with a snapshot of all child values whenever any child changes. See onChange / values below.
onRelease	function	null	`onRelease({ fieldName: value, … }[, panel])` — called with the same snapshot on release.
theme	object	{}	Partial theme override. See Themes.

Methods & properties

Name	Description
`.add(control)`	Attach a ProControl to the panel. The control is removed from the global registry and managed by the panel from that point on. Returns the `control` so you can capture it: `const s = pnl.add(new AnalogSlider(…))`.
`.onChange`	Callback fired as `onChange(snapshot[, panel])` whenever any child changes. Can be set at construction or assigned later.
`.onRelease`	Callback fired as `onRelease(snapshot[, panel])` when the user releases any child control. Can be set at construction or assigned later.
`.values`	Read-only getter. Returns a fresh `{ fieldName: value, … }` snapshot of every child control's current value — same object shape as the `onChange` and `onRelease` arguments. Useful for polling the panel state without setting up a callback.
`.visible`	Get/set panel visibility. When set to `false` the panel and all children stop drawing and receiving events.
`.minimized`	Get/set minimized state. When `true` the panel collapses to only the title bar; the small −/+ button in the title bar also toggles this.
`.minimizable`	Read/write. Hides the toggle button and disables collapse when `false`.
`.movable`	Read/write. Prevents title-bar dragging when `false`.
`.resizable`	Read/write. When `true`, a grip appears in the bottom-right corner allowing the user to drag-resize the panel.
`.scrollX / .scrollY`	Current scroll offset in pixels. Read or write to programmatically scroll the panel.
`.clone()`	Returns a new Panel with identical options and a deep copy of all child controls. The copy is positioned to the right of the original (or below if it would overflow the canvas). Each cloned child is independent — changing values on the copy does not affect the original.

onChange / onRelease / values

When onChange or onRelease are set, the panel listens to every child control and fires the respective callback — with a single snapshot object — on change or release. The same object is always available via panel.values.

Field names are derived from each control's label option with spaces and punctuation stripped (e.g. "Low Cut" → LowCut). Controls without a label are named by class and a per-class counter: the first unlabelled AnalogSlider becomes AnalogSlider1, the second AnalogSlider2, and so on. MultiSlider and MultiDial follow the same rule — the slider/dial keys within their own values object also have spaces and punctuation stripped from the label.

Values per control type:

Control	Value in snapshot
AnalogSlider, Dial	`number`
Switch	Current state label string (e.g. `"On"`)
Selector, SliderSelector	Selected option string
MultiSlider, MultiDial	`{ name: value, … }` object
GridPad	2-D array of cell values
TagSelector	Array of selected tag strings
RangeSlider	`{ low, high }`
XYPad	`{ x, y }`
IconButton	`boolean` state
Markup, Menu, VUMeter, LEDMeter, ADSRDisplay	omitted

Note: set any per-control onChange callbacks before calling panel.add(). Callbacks assigned after add() will work for the individual control but the panel notification will wrap the value that was set at add-time.

Scrolling

Scrollbars appear automatically when children extend beyond the panel boundaries. The scroll wheel scrolls the panel when the pointer is over the panel but not over a focused child control. If a child control (e.g. a Dial) is hovered, the scroll wheel is forwarded to that child instead. You can also drag the scrollbar thumbs directly.

Example — onChange

const pnl = new Panel({
  x: 20, y: 18,
  width: 280, height: 180,
  label: 'SYNTH',
  onChange: data => console.log(data),
});
pnl.add(new Dial({
  x: 20, y: 20,
  size: 70, min: 20, max: 20000, value: 440,
  label: 'Freq', readout: 'raw', decimals: 0,
}));
pnl.add(new AnalogSlider({
  x: 120, y: 20,
  width: 44, height: 140,
  min: 0, max: 1, value: 0.8,
  label: 'Gain', readout: 'db',
}));
pnl.add(new Switch({
  x: 190, y: 50,
  width: 52,
  states: ['OFF', 'ON'], state: 1,
  label: 'Power',
}));
// Read all values at any time:
// pnl.values  →  { Freq: 440, Gain: 0.8, Power: 'ON' }

Example — grouped controls

const pnl = new Panel({
  x: 20, y: 18,
  width: 280, height: 200,
  label: 'PANEL',
});
pnl.add(new Dial({
  x: 20, y: 20,
  size: 70, min: 0, max: 100, value: 65,
  label: 'FREQ', readout: 'raw', decimals: 0,
}));
pnl.add(new AnalogSlider({
  x: 120, y: 20,
  width: 44, height: 150,
  min: 0, max: 1, value: 0.75,
  label: 'GAIN', readout: 'db',
}));
pnl.add(new AnalogSwitch({
  x: 190, y: 50,
  width: 52,
  states: ['OFF', 'ON'],
  state: 1,
  label: 'POWER',
}));

Example — scrollable content

const pnl = new Panel({
  x: 20, y: 18,
  width: 220, height: 160,
  label: 'SCROLL',
});
// 8 dials arranged in two rows — wider than the panel
for (let i = 0; i < 4; i++) {
  pnl.add(new Dial({
    x: 20 + i * 80, y: 20,
    size: 65, min: 0, max: 100, value: 40 + i * 15,
    label: ['BASS','MID','TREB','PRES'][i],
    readout: 'raw', decimals: 0,
  }));
  pnl.add(new Dial({
    x: 20 + i * 80, y: 120,
    size: 65, min: 0, max: 100, value: 60 - i * 10,
    label: ['VOL','PAN','SND','RET'][i],
    readout: 'raw', decimals: 0,
  }));
}

ModalPanel Container

A promise-based modal dialog that blocks all other controls while open. Add any ProControls to it with .add(), then call await modal.show() from an async function to display it. The canvas dims and all other control events are suspended until the user clicks Save (resolves with a values snapshot) or Cancel (resolves with null). Options can be re-supplied to show() to change the title or size on each invocation.

new ModalPanel(opts)

Constructor options

Option	Type	Default	Description
label	string	''	Title shown in the header bar of the dialog.
width	number	380	Dialog width in pixels. Height is computed automatically from the controls added.
x, y	number	centered	Dialog position. When omitted the dialog is centered on the canvas each time `show()` is called.

Methods & properties

Name	Description
`.add(control)`	Adds a ProControl to the modal. The control is detached from the global registry and managed by the modal. Returns the control for chaining. Call this at setup time, not inside `show()`.
`.show(opts?)`	Opens the modal and returns a `Promise`. Optionally pass `{ label, width, x, y }` to override constructor values for this invocation. The promise resolves with a `{ name: value, … }` snapshot when Save is clicked, or `null` when Cancel is clicked. Must be called with `await` from an `async` function.
`.isOpen`	Read-only boolean. `true` while the dialog is visible. Use this to guard against opening a modal that is already showing.

Values snapshot

When the user clicks Save, show() resolves with an object keyed by each child control's name. Value types follow the same rules as Panel.values: sliders return a number, switches return their state string, XYPad returns { x, y }, and so on. Controls without a name are included under an auto-generated key. Display-only controls (Markup, VUMeter, LEDMeter, ADSRDisplay, Menu) are omitted.

Async requirement

Note: show() returns a Promise. The await keyword only works inside an async function. p5.js event handlers (mousePressed, keyPressed, etc.) support async — just declare them async function mousePressed() { … }. The sketch's draw() loop continues running normally while the modal is open, so animations and meters keep updating behind the backdrop.

Example

editable — click the canvas to open the modal

let modal;
function setup() {
  createCanvas(340, 310);
  modal = new ModalPanel({ label: 'Settings', width: 300 });
  modal.add(new AnalogSlider({ name: 'volume', label: 'Volume', value: 75, min: 0, max: 100 }));
  modal.add(new Switch({ name: 'muted', label: 'Muted', states: ['Off', 'On'], state: 0 }));
}
function draw() { background(220); }
async function mousePressed() {
  if (modal.isOpen) return;
  const result = await modal.show();
  if (result) console.log('Saved:', JSON.stringify(result));
  else        console.log('Cancelled');
}

Re-opening with different options

const modal = new ModalPanel({ width: 300 });
modal.add(new AnalogSlider({ name: 'gain', label: 'Gain', value: 80, min: 0, max: 100 }));

// Change the title each time it opens
let count = 0;
async function mousePressed() {
  if (modal.isOpen) return;
  count++;
  const result = await modal.show({ label: `Settings (open #${count})` });
  if (result) console.log('Saved:', result);
}

Bevel Cosmetic

A decorative separator line that draws a bevel edge across the canvas or a parent Panel. Pass x to draw a vertical bevel; pass y to draw a horizontal bevel. Both can be passed together. Values are pixels from the top-left of the container, or a percentage string such as '50%' resolved against the canvas width/height or the parent Panel's content area. Three visual styles are available.

new Bevel(opts)

Options

Option	Type	Default	Description
x	number \| string	—	Position of a vertical bevel line. Pixels from the left edge, or a percent string (`'50%'`). Omit to skip the vertical line.
y	number \| string	—	Position of a horizontal bevel line. Pixels from the top edge, or a percent string (`'50%'`). Omit to skip the horizontal line.
style	string	'thin'	`'thin'` — 2px edge (1px dark shadow + 1px light highlight). `'deep'` — 4px edge (2px darker shadow + 2px thin bevel), for a heavier inset look. `'color'` — 2px edge using the current theme's accent color.
label	string	''	Optional text centered on the bevel line. The background behind the text is filled with the panel color to cut the line, making the label appear to sit on the bevel. On a vertical bevel (`x`) the text is rotated 90°.
theme	object	{}	Partial theme override. The `'color'` style uses `theme.capIndicator`; labels use `theme.scaleText` and `theme.panel`.

Notes

Bevel has no interaction — it never consumes mouse or touch events.
When added to a Panel via panel.add(), percent values resolve against the Panel's content area. On the canvas they resolve against width / height.
Bevel does not contribute to Panel scroll size — it will not cause scrollbars to appear.

Example

editable — changes update the preview

new Bevel({ y: 95, label: 'AUX' });
new Bevel({ x: 130, label: 'FX' });
new Dial({ x: 45,  y: 14,  size: 40, label: 'GAIN',   readout: 'raw', decimals: 0 });
new Dial({ x: 150, y: 14,  size: 40, label: 'PAN',    readout: 'raw', decimals: 0 });
new Dial({ x: 45,  y: 108, size: 40, label: 'SEND',   readout: 'raw', decimals: 0 });
new Dial({ x: 150, y: 108, size: 40, label: 'RETURN', readout: 'raw', decimals: 0 });

Inside a Panel

editable — changes update the preview

const pnl = new Panel({
  x: 20, y: 10,
  width: 220, height: 170,
  label: 'CHANNEL',
});
// Horizontal bevel at 50% of the panel height
pnl.add(new Bevel({ y: '50%' }));
pnl.add(new Dial({ x: 30, y: 10, size: 65, label: 'GAIN', readout: 'raw', decimals: 0 }));
pnl.add(new Dial({ x: 125, y: 10, size: 65, label: 'PAN', readout: 'raw', decimals: 0 }));
pnl.add(new Dial({ x: 30, y: 95, size: 65, label: 'SEND', readout: 'raw', decimals: 0 }));
pnl.add(new Dial({ x: 125, y: 95, size: 65, label: 'RETURN', readout: 'raw', decimals: 0 }));

MessageDialog Container

A self-sizing, movable dialog that displays a formatted text message and optional action buttons. The message string is word-wrapped to fit the dialog width. Buttons are arranged in a single row at the bottom; if multiple buttons are provided the dialog widens automatically to fit them all on one line. Drag the title bar to reposition.

new MessageDialog(opts)

Options

Option	Type	Default	Description
message	string	''	The text to display. Use `\n` for explicit line breaks. Long lines are wrapped automatically to fit the dialog width.
buttons	string[]	[]	Button labels shown in a row at the bottom of the dialog. Omit or pass an empty array for a message-only dialog.
x, y	number	20, 20	Canvas position.
width	number	auto	Dialog width. Defaults to at least 220 px or wide enough to fit all buttons on one row, whichever is larger.
label	string	''	Title bar text. When set a styled title bar is shown at the top and the dialog can be repositioned by dragging it.
movable	boolean	true	When `false` the dialog cannot be dragged.
onButton	function	null	`onButton(index, label[, control])` — called when a button is clicked.
disabled	boolean	false	Disables interaction and renders a translucent overlay.
theme	object	{}	Partial theme override. See Themes.

Properties

Property	Description
`.message`	Read/write. Reassigning triggers a layout rebuild on the next draw so the dialog resizes to fit the new text.
`.buttons`	Read/write. Reassigning the array rebuilds the button row on the next draw.
`.movable`	Read/write. Toggle whether the dialog can be dragged at runtime.

Example

editable — changes update the preview

const dlg = new MessageDialog({
  x: 20, y: 20,
  label: 'Confirm',
  message: 'Are you sure you want to discard all unsaved changes? This cannot be undone.',
  buttons: ['Cancel', 'Discard'],
  onButton: (i, lbl) => console.log(i, lbl),
});

InputDialog Container

Extends MessageDialog with a single-line text input field between the message and the buttons. Clicking the input field captures keyboard events for typing, cursor movement, and editing. The cursor blinks and the text scrolls horizontally when the value overflows the field width. Pressing Enter fires onSubmit; clicking outside the field removes focus.

new InputDialog(opts)

Options

Option	Type	Default	Description
message	string	''	Instructional text above the input. Supports `\n` and auto word-wraps.
inputValue	string	''	Initial text in the input field.
inputPlaceholder	string	''	Greyed hint text shown when the field is empty and unfocused.
buttons	string[]	[]	Button labels in a row at the bottom.
x, y	number	20, 20	Canvas position.
width	number	auto	Dialog width. Defaults to at least 220 px or wide enough to fit all buttons.
label	string	''	Title bar text. When set the dialog can be dragged.
movable	boolean	true	When `false` the dialog cannot be dragged.
onButton	function	null	`onButton(index, label, value[, control])` — called when a button is clicked. `value` is the current input field text.
onSubmit	function	null	`onSubmit(value[, control])` — called with the current input text when `Enter` is pressed.
disabled	boolean	false	Disables all interaction.
theme	object	{}	Partial theme override. See Themes.

Properties

Property	Description
`.inputValue`	Read/write. The current text in the field. Reassign to change it programmatically.
`.inputPlaceholder`	Read/write. Hint text shown when the field is empty and unfocused.
`.message`	Read/write. Reassigning triggers a layout rebuild on the next draw.
`.buttons`	Read/write. Reassigning rebuilds the button row on the next draw.

Keyboard interaction

Key	Effect
Printable characters	Inserted at the cursor position.
`Backspace` / `Delete`	Removes the character before / after the cursor.
`←` / `→`	Moves the cursor one character.
`Home` / `End`	Jumps to the start or end of the text.
`Enter`	Fires `onSubmit(value[, control])`.

Example

editable — changes update the preview

const dlg = new InputDialog({
  x: 20, y: 20,
  label: 'Rename',
  message: 'Enter a new name for the channel:',
  inputPlaceholder: 'Channel name...',
  buttons: ['Cancel', 'OK'],
  onSubmit: (v) => console.log('submit', v),
  onButton: (i, lbl, v) => console.log(i, lbl, v),
});

Panels

Panel Container

Constructor options

Methods & properties

onChange / onRelease / values

Scrolling

Example — onChange

Example — grouped controls

Example — scrollable content

ModalPanel Container

Constructor options

Methods & properties

Values snapshot

Async requirement

Example

Re-opening with different options

Bevel Cosmetic

Options

Notes

Example

Inside a Panel

MessageDialog Container

Options

Properties

Example

InputDialog Container

Options

Properties

Keyboard interaction

Example