GUI

Control panels drawn by Kiln on top of the sketch, and the Parameters their controls edit.

Gui

Gui(title='Controls', x=16, y=16, width=260)

A panel of controls drawn by Kiln on top of the sketch.

Make it in setup and add controls; each control returns the Parameter it edits, so the sketch reads it like a number (param.value sets it)::

def setup(self):
    self.gui = kiln.Gui("Circle")
    self.radius = self.gui.slider("radius", 80.0, 10.0, 200.0)

def draw(self):
    kiln.circle(320, 240, self.radius)

There is no draw call: every panel is drawn after App.draw, on top, on the window (even if an Fbo was left open), with its own transform and style, which are put back afterwards. The panels are drawn on a copy of the frame, never into the sketch’s canvas, so a sketch that keeps its frames (window.auto_clear = False, trails) keeps its art under them. A sketch with no Gui renders exactly as before.

The panels are a tool, not part of the art: save_screen, Image.grab_screen and kiln.testing.render_frames return the sketch without them (render_frames(..., with_gui=True) keeps them, for docs).

Input reaches the panels before the App. A press on a visible panel is theirs, along with the drags and the release that follow it, so mouse_pressed, mouse_dragged and mouse_released never see it; a press elsewhere goes to the App as usual. A scroll over a panel is the panel’s too (the control under the pointer may use it). Mouse moves always reach mouse_moved. A click raises the panel above the others. Tab on its own shows or hides every panel, and still reaches key_pressed. Polling agrees: kiln.mouse.pressed is False while a panel holds the pointer, and kiln.keys leaves out keys a focused text field or an open popup took.

Drag the header to move the panel (it stays inside the window, even after a resize) and click the chevron to collapse it. Sliders: click to jump, drag to adjust, hold Shift to drag a tenth as far, double-click to reset. Toggles flip on a click, buttons call back when released on them, and a folder’s caption folds the controls made inside its with block.

Each control’s Parameter has a path, its folders’ names and its own joined by / ("Flow/speed"). Paths are unique in a panel: making a control whose path is taken raises ValueError, so the same name may appear in different folders but not twice in one.

Hovering a control shows a pointing hand (clickable), a horizontal-resize arrow (slider), a vertical-resize arrow (knob) or a crosshair (XY pad), and after about 0.6 s its tip if it has one. The cursor changes only when the pointer enters or leaves a control, so a sketch that sets its own cursor is not fought every frame.

Parameters

Name	Type	Description	Default
title	str	The header’s text.	`'Controls'`
x	float	The panel’s left edge, in window points.	`16`
y	float	The panel’s top edge, in window points.	`16`
width	float	The panel’s width, in points.	`260`

Raises

Name	Type	Description
	RuntimeError	No App is running: make panels in `setup` (or later).

Attributes

Name	Type	Description
title	str	The header’s text.
x	float	The panel’s left edge, in window points. Dragging the header changes it.
y	float	The panel’s top edge, in window points.
width	float	The panel’s width, in points.
collapsed	bool	Whether only the header shows. The chevron toggles it.

Methods

Name	Description
button	Adds a button that calls `on_click()` once per click.
choice	Adds a choice of one option among several and returns its Parameter.
color	Adds a colour picker and returns its Parameter.
folder	Groups the controls made inside a `with` block under a foldable caption.
graph	Adds a live graph: a line of `fn()` over the last two seconds or so.
keyboard	Adds a piano strip: white and black keys, lit while held.
knobs	Adds a row of rotary knobs and returns their Parameters, one per knob.
label	Adds a read-only row, a name and a value, and returns its Parameter.
load	Sets the controls from a file `save` wrote.
meter	Adds a level meter: a row of segments lit up to `fn()`, a number in [0, 1].
pads	Adds a grid of square pads, lit while held.
range	Adds a range slider, two handles on one track, and returns its Parameter.
remove	Takes the panel off the window: it is no longer drawn and takes no input.
save	Writes every control’s value to a JSON file, keyed by path.
scope	Adds a scope: the waveform of `fn()` as one line across the row.
slider	Adds a slider row and returns its Parameter.
spectrum	Adds a spectrum: one bar per band of `fn()`, with peak caps that hold, then fall.
steps	Adds a step grid and returns its Parameter.
text	Adds a one-line text field and returns its Parameter, a str.
toggle	Adds a pill switch and returns its Parameter.
xy	Adds an XY pad and returns its Parameter.

button

Gui.button(name, on_click, *, tip=None)

Adds a button that calls on_click() once per click.

The click counts on release, when the pointer is still on the button; releasing elsewhere cancels it. The button shows in the accent colour while it is pressed.

Parameters

Name	Type	Description	Default
name	str	The text on the button.	required
on_click	Callable[[], None]	Called with no arguments.	required
tip	str \| None	A tooltip shown after about 0.6 s of hover.	`None`

choice

Gui.choice(name, options, value=None, *, tip=None)

Adds a choice of one option among several and returns its Parameter.

The row picks its own form. Up to four options that each fit their share of the row show whole, as a segmented control: click one to choose it, and the highlight slides over. More options, or longer ones, make a dropdown: the box shows the chosen option, and a click opens the list of all of them above every panel, where a click chooses one. A click anywhere else, or Esc, closes the list and changes nothing.

The Parameter’s value is the chosen option itself, a str: compare it (if shape == "dots":) or set it (shape.value = "rings") to another option. Setting anything that is not an option raises ValueError. Parameters hash by identity, so to key a dict by the choice use .value (or str(p)): PALETTES[palette.value].

Parameters

Name	Type	Description	Default
name	str	The name shown on the row.	required
options	Iterable[str]	The options, as distinct strings, in the order shown.	required
value	str \| None	The option chosen at the start, also the one `reset` restores; None (the default) is the first.	`None`
tip	str \| None	A tooltip shown after about 0.6 s of hover.	`None`

Returns

Name	Type	Description
	Parameter	The Parameter holding the chosen option.

Raises

Name	Type	Description
	ValueError	`options` is empty or has a duplicate, `value` is not one of them, or the panel already has a control at this path.
	TypeError	`options` is a bare str, or an option is not a str.

color

Gui.color(name, value, *, tip=None)

Adds a colour picker and returns its Parameter.

The row shows the colour as a swatch and #RRGGBB. Clicking it opens an HSV square, a hue bar and an alpha bar under it; clicking again closes them. The Parameter holds a kiln.Color, so it goes straight into fill(param) and background(param). Assign a colour (param.value = kiln.Color(...) or a tuple of 0-255 channels) to change it; the picker follows. Don’t change the Color in place: the Parameter will not notice.

Parameters

Name	Type	Description	Default
name	str	The name shown on the row.	required
value	Color \| Iterable[float]	The starting colour, a `kiln.Color` or (r, g, b[, a]) of 0-255 channels, also the default `reset` restores.	required
tip	str \| None	A tooltip shown after about 0.6 s of hover.	`None`

Returns

Name	Type	Description
	Parameter	The Parameter the picker edits.

Raises

Name	Type	Description
	TypeError	`value` is not a colour.
	ValueError	`value` has other than 3 or 4 channels, or the panel already has a control at this path.

folder

Gui.folder(name, collapsed=False, *, tip=None)

Groups the controls made inside a with block under a foldable caption.

Clicking the caption folds the group, and the panel’s height follows. Folders nest::

with self.gui.folder("Flow"):
    self.scale = self.gui.slider("scale", 0.5, 0.0, 1.0)

Parameters

Name	Type	Description	Default
name	str	The caption, shown in capitals.	required
collapsed	bool	Whether the group starts folded.	`False`
tip	str \| None	A tooltip shown after about 0.6 s of hover on the caption.	`None`

graph

Gui.graph(name, fn, min, max, *, tip=None)

Adds a live graph: a line of fn() over the last two seconds or so.

The panel calls fn() once per frame it draws, keeps the last theme.GRAPH_HISTORY values (two seconds at 60 fps) and draws them as one line from min (the bottom) to max (the top); a value outside them is clamped on the graph. The row also shows the current value as text. It is read-only: it takes no input, and a click on it never reaches the App.

Parameters

Name	Type	Description	Default
name	str	The name shown on the row.	required
fn	Callable[[], float]	Called with no arguments, returns a number.	required
min	float	The value at the graph’s bottom.	required
max	float	The value at its top.	required
tip	str \| None	A tooltip shown after about 0.6 s of hover.	`None`

Raises

Name	Type	Description
	ValueError	`min` is not less than `max`.
	TypeError	`fn` is not callable, or a bound is not a number.

keyboard

Gui.keyboard(
    name,
    low='C3',
    octaves=2,
    *,
    on_note=None,
    on_release=None,
    tip=None,
)

Adds a piano strip: white and black keys, lit while held.

Notes are MIDI numbers, and note names follow the convention C4 = 60 (so "A4" is 69). A press calls on_note(note, velocity), the velocity in (0, 1] from where the press landed on the key (lower is louder, as on a real key); letting go calls on_release(note). Dragging across keys releases the old note and plays the new one. A release off the strip still releases, and hiding the panel, removing it or the window losing focus releases every held note, so nothing hangs.

Clicking the strip focuses it (an accent ring shows). While focused, the computer keyboard plays: A W S E D F T G Y H U J K are the keys from the C at or below low up to the next, and Z and X move that octave down and up. Esc, Tab or a click elsewhere ends the focus; no other key reaches the App meanwhile except the ones the strip does not use.

It holds no Parameter, so presets skip it, and a press on it never reaches the App. With kiln.sound, turn the number into Hz for a synth, 440 * 2 ** ((note - 69) / 12): synth.note_on(kiln.note_to_freq(note), velocity) does it.

Parameters

Name	Type	Description	Default
name	str	Names the row (it is not drawn).	required
low	str \| int	The lowest key: a note name (`"C3"`, `"F#2"`, `"Bb1"`) or a MIDI number.	`'C3'`
octaves	int	How many octaves of keys, at least 1.	`2`
on_note	Callable[[int, float], None] \| None	Called with `(note, velocity)` as a key goes down.	`None`
on_release	Callable[[int], None] \| None	Called with `(note)` as it comes up.	`None`
tip	str \| None	A tooltip shown after about 0.6 s of hover.	`None`

Raises

Name	Type	Description
	ValueError	`low` is not a note, `octaves` is less than 1, or the strip goes past MIDI note 127.
	TypeError	A callback is not callable.

knobs

Gui.knobs(*knobs, tip=None)

Adds a row of rotary knobs and returns their Parameters, one per knob.

Each knob is a (name, value, min, max) tuple. Each knob sweeps an arc with a pointer and its name below. Drag vertically: 150 points up moves a knob across its whole range, Shift drags a tenth as far, a double-click resets that knob, and the scroll wheel over a knob nudges it. While a knob is held its name shows its value. As for slider, a knob whose value, min and max are all ints only yields ints.

Parameters

Name	Type	Description	Default
*knobs	tuple[str, float, float, float]	One `(name, value, min, max)` tuple per knob, left to right.	`()`
tip	str \| None	A tooltip for the row, shown after about 0.6 s of hover.	`None`

Returns

Name	Type	Description
	list[Parameter]	The Parameters the knobs edit, in order.

Raises

Name	Type	Description
	ValueError	No knobs, a `min` that is not less than its `max`, a value outside them, or a name already used at this path in the panel.
	TypeError	A knob is not a `(name, value, min, max)` tuple, or has a value that is not a number.

label

Gui.label(name, value='', *, tip=None)

Adds a read-only row, a name and a value, and returns its Parameter.

Set param.value from the sketch (every frame is fine) to change the text; anything you set is shown as text, so a number works. Clicks on it do nothing.

Parameters

Name	Type	Description	Default
name	str	The name shown on the left.	required
value	str	The starting text, shown on the right.	`''`
tip	str \| None	A tooltip shown after about 0.6 s of hover.	`None`

Returns

Name	Type	Description
	Parameter	The Parameter holding the text.

load

Gui.load(path)

Sets the controls from a file save wrote.

Each value goes through its Parameter’s setter, so it is converted and clamped to the Parameter’s range, and on_change listeners run. A control missing from the file keeps its value. A key with no control here, or a value its control cannot take, gives a warning and is skipped; the rest load.

Parameters

Name	Type	Description	Default
path	str \| Path	The file to read.	required

Raises

Name	Type	Description
	FileNotFoundError	There is no such file.
	ValueError	The file is not a JSON object.

meter

Gui.meter(name, fn, *, tip=None)

Adds a level meter: a row of segments lit up to fn(), a number in [0, 1].

The panel calls fn() once per frame it draws; a value outside [0, 1] is clamped. A thin marker holds the highest recent level for about theme.METER_HOLD seconds, then falls back, timed by the frame clock. Read-only, like graph.

Parameters

Name	Type	Description	Default
name	str	The name shown on the row.	required
fn	Callable[[], float]	Called with no arguments, returns a number in [0, 1].	required
tip	str \| None	A tooltip shown after about 0.6 s of hover.	`None`

Raises

Name	Type	Description
	TypeError	`fn` is not callable.

pads

Gui.pads(
    name,
    rows=4,
    cols=4,
    *,
    base=36,
    on_note=None,
    on_release=None,
    tip=None,
)

Adds a grid of square pads, lit while held.

Pad i, counted row by row from the top left, plays base + i: a press calls on_note(base + i, velocity), the velocity in (0, 1] from how far down the pad it landed (lower is louder), and letting go, anywhere, calls on_release(base + i). Hiding the panel or the window losing focus releases a held pad. Pads map naturally to drums: with kiln.sound, drum.hit(velocity). They hold no Parameter, and a press on them never reaches the App.

Parameters

Name	Type	Description	Default
name	str	Names the row (it is not drawn).	required
rows	int	Pad rows, at least 1.	`4`
cols	int	Pad columns, at least 1.	`4`
base	int	The note of the top-left pad (36 is C2, a kick drum’s usual note).	`36`
on_note	Callable[[int, float], None] \| None	Called with `(note, velocity)`.	`None`
on_release	Callable[[int], None] \| None	Called with `(note)`.	`None`
tip	str \| None	A tooltip shown after about 0.6 s of hover.	`None`

Raises

Name	Type	Description
	ValueError	`rows` or `cols` is less than 1, or the grid goes past MIDI note 127 from `base`.
	TypeError	A callback is not callable.

range

Gui.range(name, value, min, max, *, format=None, tip=None)

Adds a range slider, two handles on one track, and returns its Parameter.

A press grabs the nearer handle, the handles never cross, Shift drags a tenth as far and a double-click resets both. The Parameter holds a (low, high) tuple of floats: lo, hi = cut unpacks it. Setting it with the low end above the high one raises ValueError.

Parameters

Name	Type	Description	Default
name	str	The name shown on the left.	required
value	tuple[float, float]	The starting (low, high), also the default a double-click restores.	required
min	float	The value at the left end.	required
max	float	The value at the right end.	required
format	str \| None	A `str.format` pattern for each end of the shown “low to high”, such as `'{:.0f}Hz'`. None shows about three significant digits.	`None`
tip	str \| None	A tooltip shown after about 0.6 s of hover.	`None`

Returns

Name	Type	Description
	Parameter	The Parameter the slider edits.

Raises

Name	Type	Description
	ValueError	`min` is not less than `max`, `value` is outside them or has its low end above its high end, `format` is not a `str.format` pattern for one number, or the panel already has a control at this path.
	TypeError	`value` is not a pair of numbers.

remove

Gui.remove()

Takes the panel off the window: it is no longer drawn and takes no input.

Its Parameters keep working. Removing it again does nothing.

save

Gui.save(path)

Writes every control’s value to a JSON file, keyed by path.

The file is one object, {"radius": 80.0, "Flow/speed": 0.4}: each control’s Parameter.path and its value in a form JSON holds (a colour, a pair and a choice have theirs). Read-only rows (labels, graphs, meters) are not saved.

Parameters

Name	Type	Description	Default
path	str \| Path	The file to write, replacing it if it exists (it is written whole or not at all).	required

scope

Gui.scope(name, fn, *, tip=None)

Adds a scope: the waveform of fn() as one line across the row.

The panel calls fn() once per frame it draws. It returns samples in [-1, 1] (a list or a numpy array); a value outside is clamped and NaN or infinity reads as 0. The first sample is at the left and the last at the right, over a faint centre line, and an empty array draws the centre line alone. The wave is one lines call however many samples it has. Read-only: a click on it never reaches the App.

Parameters

Name	Type	Description	Default
name	str	The name shown on the row.	required
fn	Callable[[], Sequence[float]]	Called with no arguments, returns samples in [-1, 1].	required
tip	str \| None	A tooltip shown after about 0.6 s of hover.	`None`

Raises

Name	Type	Description
	TypeError	`fn` is not callable.

slider

Gui.slider(name, value, min, max, *, format=None, tip=None)

Adds a slider row and returns its Parameter.

The slider is an int slider when value, min and max are all ints (it only ever yields ints), and a float slider otherwise.

The value shown on the row is automatic: an int slider shows whole numbers with thousands separators, and a float slider shows about three significant digits of its range (0 to 5 shows 1.60, 10 to 300 shows 140.0). Pass format to choose the text yourself.

Parameters

Name	Type	Description	Default
name	str	The name shown on the row.	required
value	float	The starting value, also the default a double-click restores.	required
min	float	The value at the left end.	required
max	float	The value at the right end.	required
format	str \| None	A `str.format` pattern for the displayed value, such as `'{:.2f}'`, `'{:.0%}'` or `'{:,} px'`. It applies to int and float sliders alike. None (the default) is the automatic rule.	`None`
tip	str \| None	A tooltip shown after about 0.6 s of hover.	`None`

Returns

Name	Type	Description
	Parameter	The Parameter the slider edits.

Raises

Name	Type	Description
	ValueError	`min` is not less than `max`, `value` is outside them, `format` is not a `str.format` pattern for one number, or the panel already has a control at this path.
	TypeError	A bound or the value is not a number, or `format` is not a str.

spectrum

Gui.spectrum(name, fn, *, bands=None, log=True, tip=None)

Adds a spectrum: one bar per band of fn(), with peak caps that hold, then fall.

The panel calls fn() once per frame it draws. It returns magnitudes in [0, 1], one per frequency band from low to high (a list or a numpy array); a value outside is clamped and NaN or infinity reads as 0. With sound, pass lambda: kiln.master.spectrum(64).

The bars are as many as bands, or as many as fn() returns when it is None. When that equals the array’s length the bands are drawn as given, whatever log says: kiln.master.spectrum(64) is already log-banded, so it plugs in as is. A longer input is reduced to fewer bars, each showing the largest value of its group of input bands. With log=True the groups grow on a log scale, as audio spectra are read (the right choice for a linear FFT of 512 bins into 64 bars); log=False makes every group the same size. The caps stay theme.SPECTRUM_HOLD seconds, then fall at theme.SPECTRUM_FALL per second, timed by the frame clock. The bars are one rects call and the caps another. Read-only: a click on it never reaches the App.

Parameters

Name	Type	Description	Default
name	str	The name shown on the row.	required
fn	Callable[[], Sequence[float]]	Called with no arguments, returns magnitudes in [0, 1].	required
bands	int \| None	How many bars to draw, or None for one per value of `fn()`.	`None`
log	bool	How a longer input is reduced to fewer bars: True groups it on a log scale, False in even groups. Not used when the bar count equals the input length.	`True`
tip	str \| None	A tooltip shown after about 0.6 s of hover.	`None`

Raises

Name	Type	Description
	TypeError	`fn` is not callable, or `bands` is not an int.
	ValueError	`bands` is less than 1.

steps

Gui.steps(name, tracks, steps=16, value=None, *, tip=None)

Adds a step grid and returns its Parameter.

A row per track with its name on the left and a cell per step: off, a hit or an accent. Click a cell to toggle it between off and hit (an accent goes off), Shift-click to make it an accent, and drag to paint the value the press set over the cells you cross, along a row or across rows. A double-click on a track’s name clears its row. A bar line marks every four steps.

The Parameter holds a tuple of rows, each a tuple of steps ints: 0 off, 1 hit, 2 accent. It has tracks; patterns[track], which reads or sets a row in the sequencer’s string form (x hit, X accent, . rest, one character a step); and a playhead that lights a column: set it each frame from your sequencer (grid.playhead = step), or None for none.

Parameters

Name	Type	Description	Default
name	str	The name of the Parameter (the grid shows only its tracks).	required
tracks	Iterable[str]	The row names, top to bottom, each different.	required
steps	int	Cells per row.	`16`
value	Iterable[Iterable[int]] \| None	The starting rows (all off when None), also what `reset` restores.	`None`
tip	str \| None	A tooltip for the grid, shown after about 0.6 s of hover.	`None`

Returns

Name	Type	Description
	GridParameter	The Parameter the grid edits.

Raises

Name	Type	Description
	ValueError	No tracks, repeated track names, `steps` below 1 or too many to fit the panel (a cell under 1 pt wide), `value` of the wrong shape or with a cell that is not 0, 1 or 2, or a name already used at this path in the panel.
	TypeError	`tracks` holds something that is not a string, or `steps` is not an int.

text

Gui.text(name, value='', *, tip=None)

Adds a one-line text field and returns its Parameter, a str.

Click the field to type: the caret goes to the nearest character and blinks. Printable ASCII types at the caret, Backspace and Delete delete, Left, Right, Home and End move the caret, and a held key repeats. The Parameter changes as you type. Return, Esc, Tab or a click anywhere else ends the editing.

While the field is being edited it takes every key: none reaches the App’s key handlers, Esc does not quit and Tab does not hide the panels. A key’s release goes where its press went.

Parameters

Name	Type	Description	Default
name	str	The name shown on the row.	required
value	str	The starting text, which a `reset` restores.	`''`
tip	str \| None	A tooltip shown after about 0.6 s of hover.	`None`

Returns

Name	Type	Description
	Parameter	The Parameter holding the text.

toggle

Gui.toggle(name, value=False, *, tip=None)

Adds a pill switch and returns its Parameter.

A click flips it, and its knob eases across over about 0.12 s. The Parameter is a bool: bool(param) or if param: reads it, and param.value = True sets it.

Parameters

Name	Type	Description	Default
name	str	The name shown on the row.	required
value	bool	The starting state, which a `reset` restores.	`False`
tip	str \| None	A tooltip shown after about 0.6 s of hover.	`None`

Returns

Name	Type	Description
	Parameter	The Parameter the toggle edits.

xy

Gui.xy(name, value=(0.0, 0.0), min=-1.0, max=1.0, *, tip=None)

Adds an XY pad and returns its Parameter.

A square pad with a handle and a crosshair. Click to jump, drag to move, hold Shift to drag a tenth as far, double-click to reset. The pad’s top left is (min, min) and its bottom right (max, max), so y grows downward like window coordinates. The Parameter holds an (x, y) tuple of floats, both clamped to [min, max]: x, y = pad unpacks it and pad.value = (0.5, -0.5) sets it.

Parameters

Name	Type	Description	Default
name	str	The name shown beside the pad.	required
value	tuple[float, float]	The starting (x, y), also the default a double-click restores.	`(0.0, 0.0)`
min	float	The smallest x and y.	`-1.0`
max	float	The largest x and y.	`1.0`
tip	str \| None	A tooltip shown after about 0.6 s of hover.	`None`

Returns

Name	Type	Description
	Parameter	The Parameter the pad edits.

Raises

Name	Type	Description
	ValueError	`min` is not less than `max`, `value` is outside them, or the panel already has a control at this path.
	TypeError	`value` is not a pair of numbers.

Parameter

Parameter(name, value, min=None, max=None, *, kind=None)

A named value with a range, a default and change listeners.

Gui.slider (and every other Gui control) makes one and returns it; read it wherever the sketch needs it. It has one of nine kinds: float, int, bool, str, color, xy, range, choice and grid. The starting value picks int (the value and both bounds are ints), float (other numbers), bool (a toggle’s), str (a label’s or text field’s) and color (a Color); Gui.xy, Gui.range and Gui.choice name theirs. Setting value converts to that kind and clamps to [min, max], so a Parameter never holds a value its control can’t show, whoever set it (the panel, the sketch, or later a preset or an OSC message). numpy numbers and another Parameter are fine values.

A number Parameter reads like the number it holds, so kiln.circle(x, y, radius) works without .value. Arithmetic with numbers (on either side), unary -/+/abs, round, comparisons, float(), int() and bool() all use the current value and give a plain number (or bool), never a Parameter. An int Parameter also works as an index, so range(count) works; a float one raises TypeError there. numpy reads the value too (np.sin(p), arr * p, np.linspace(0, p, 5)). It is not a float subclass, so json.dumps(p) fails: dump p.value. Builtins that return one of their arguments (max, min, sorted, kiln.clamp) can hand back the Parameter itself, which stays live: store float(p) or p.value to keep a number. To set it, assign .value: p += 1 only rebinds the name p to a plain number.

Every kind formats and prints as its value (f"{p:.2f}", str(p)) and compares equal to it. A bool Parameter reads with bool(p) or if p: and a str one with str(p); neither does arithmetic.

== compares values (p == 3.0), but hash stays by identity, so a Parameter can still be a dict key or set member, and two equal Parameters are different keys. To look something up by what a control holds, use .value (or str(p)) as the dict key, not the Parameter. For the same reason list.index and in find an equal Parameter, not necessarily the same one.

Parameters

Name	Type	Description	Default
name	str	The name shown next to the control.	required
value	Any	The starting value, which is also the default.	required
min	float \| numbers.Real \| None	The smallest value, or None for no lower bound.	`None`
max	float \| numbers.Real \| None	The largest value, or None for no upper bound.	`None`
kind	str \| Kind \| None	Only for kinds a value can’t tell apart (`Gui` passes it); leave it out.	`None`

Raises

Name	Type	Description
	TypeError	`value`, `min` or `max` is not a number (a bool or str `value` is also fine, with no bounds).
	ValueError	`value`, `min` or `max` is NaN or infinite, `min` is greater than `max`, or `value` is outside them.

Attributes

Name	Description
`default`	The value it started with, which `reset` goes back to.
`kind`	The kind’s name: `"float"`, `"int"`, `"bool"`, `"str"`, `"color"`, `"xy"`,
`max`	The largest value, or None.
`min`	The smallest value, or None.
`name`	The name shown next to the control.
`options`	A choice’s options, in order, as a tuple; None for every other kind.
`path`	The name with its folders, `"Flow/speed"`: unique in its Gui, the preset key.
`value`	The current value.

Methods

Name	Description
on_change	Calls `fn(value)` whenever the value changes.
reset	Sets the value back to the default (as a double-click on its control does).

on_change

Parameter.on_change(fn)

Calls fn(value) whenever the value changes.

Listeners run in the order they were added, right after the change, whatever changed the value. Setting the value it already has calls nobody. A listener removed during a notification (by an earlier listener) still gets that one notification, and none after it.

Parameters

Name	Type	Description	Default
fn	Callable[[Any], None]	Called with the new value.	required

Returns

Name	Type	Description
	Callable[[], None]	A function that removes this listener: calling it again does nothing, and
	Callable[[], None]	it is safe to call from inside a listener.

reset

Parameter.reset()

Sets the value back to the default (as a double-click on its control does).