GUI controls

User-facing controls and message boxes, driven by the GUI value protocol.

25 objects. Every entry is pulled directly from the engine registry, which reads the ADD_DESCRIPTION / INLET_DOC / OUTLET_DOC / PARAM_DOC macros in the libYSE source; the longer notes under each summary are ported from the libYSE documentation. The ~ prefix marks DSP / audio-rate objects; . marks control-rate objects. Links into the patcher guide (messages, time, data, files, …) lead to the libYSE documentation, which also has this category’s page.

.b

A button. Any bang or number sends a bang and lights the button until the host next reads it.

Dart:

Obj.gButton

Kind:

Control-rate

Every bang, int or float sends a bang, whatever the number.

The GUI value is on once after a press and off otherwise. Reading it clears the press, so poll it from one place only, or presses get lost. The value cannot be written back, and .preset skips the button. For a momentary control whose value can be saved, use .led momentary or .textbutton momentary. See GUI controls and presets.

Inlets

#	Label	Accepts	Range	Description
0	trigger	FLOAT, INT, BANG	—	A bang, int or float presses the button.

Outlets

#	Label	Type	Range	Description
0	out	BANG	—	A bang for every press.

.dial

A knob with its own output range. It takes a position from 0 to 1 and sends it mapped onto minimum-maximum, optionally bent into a curve by an exponent and rounded to an int.

Dart:

Obj.gDial

Kind:

Control-rate

The inlet takes the knob position from 0 to 1, as .slider does, and the outlet sends that position mapped onto the range:

out = minimum + (maximum - minimum) * position ^ exponent

[.dial 20 20000 3]   0.5  =>  2517.5

An exponent above 1 gives finer control at the bottom of the range, which suits a frequency or a gain; one below 1 does the opposite. The range may run from high to low. When minimum equals maximum the dial sends minimum, and a result that is not a finite number sends 0. With intMode set to 1 the result is rounded to the nearest whole number (a half rounds away from 0) and sent as an int.

With the default arguments (0, 1, exponent 1, float) the dial behaves exactly like .slider.

The GUI value is the position, not the mapped value, so a host that displays “440 Hz” needs the arguments as well. Restoring the value works as described under .slider.

Inlets

#	Label	Accepts	Range	Description
0	position	FLOAT, INT, BANG, LIST	0.0-1.0	A number sets the knob position, clamped to 0-1, and sends the mapped value; a bang sends it again. Also takes its GUI value back, as a one-number list or ‘set 0 <value>’.

Outlets

#	Label	Type	Range	Description
0	out	ANY	minimum-maximum	The position mapped onto the range.

Parameters

Name	Default	Range	Description
minimum	0	any float	The value sent at position 0.
maximum	1	any float	The value sent at position 1.
exponent	1	any float	Curve of the mapping; 1 is a straight line.
intMode	0	0 or 1	1 rounds the result and sends an int; 0 sends a float.

.f

A float number box. A number on the left inlet stores it and sends it, a bang sends it again, and the right inlet stores a number without sending it.

Dart:

Obj.gFloat

Kind:

Control-rate

The right inlet stores a number without sending it; send a bang to the left inlet to send it later. An int becomes a float. Restoring the value works as described under .slider.

Inlets

#	Label	Accepts	Range	Description
0	set/bang	FLOAT, INT, BANG, LIST	any float	A number sets the value and sends it; a bang sends it again. Also takes its GUI value back, as a one-number list or ‘set 0 <value>’.
1	silent set	FLOAT, INT	any float	Stores a number without sending it.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	The value.

Parameters

Name	Default	Range	Description
value	0	any float	The value the box starts with.

.function

A breakpoint function, for drawing envelopes and curves. It stores sorted (x, y, curve) points, answers an x with the y between them, and on a bang sends the whole shape as a ramp for .line or .bline. Its points are saved with the patch.

Dart:

Obj.gFunction

Kind:

Control-rate

A function holds up to points breakpoints. Each point has an x, a y and a curve. The points are kept sorted by x, and there is one point per x.

• x is never below 0: a negative x is stored as 0.

• y is clamped to the range set by the arguments, 0 to 1 by default.

• The curve is clamped to -1 to 1.

Messages

• a number: the x to look up. The y at that x leaves the left outlet. Below the first point the first y is sent, past the last point the last y. An empty function sends nothing.

• bang: send the whole function from the middle outlet (see below).

• <x> <y>: add a point with curve 0. A point already at that x is replaced.

• three numbers per point, <x> <y> <curve> ...: replace every point.

• set <index> <x> <y> [<curve>]: rewrite the point at that position, counted from 0 in x order. Without a curve it keeps its curve. The point moves to its new place in the order.

• setcurve <index> <curve>: change one point’s curve.

• nth <index>: send that point’s y from the left outlet.

• clear: remove every point. clear <index>: remove one.

• dump: send every point from the right outlet as <index> <x> <y> <curve>, in x order.

Edits send nothing, so drawing into a function that feeds a .line does not restart the ramp. A list of any other length is ignored. When the function is full, a new point is ignored.

Curves

A segment is shaped by the curve of the point at its right end; the first point’s curve is not used. Between two points, at a fraction t of the way along, the y moves by t ^ ((1 + c) / (1 - c)) of the distance. A curve of 0 is a straight line. A positive curve leaves the first value slowly and moves late; a negative one moves early and arrives slowly. A curve of 1 holds the first value until the end of the segment, and -1 jumps at once.

The ramp

A bang sends the function as <y> <time> pairs, the form .line and .bline read. The first time is 0, so the ramp jumps to the first y; each later time is the distance in x from the point before.

[.function]   0 0,  100 1,  300 0.5,  bang  =>  0. 0. 1. 100. 0.5 200.
              50  =>  0.5

The ramp is made of straight segments: curves only shape the values sent for a looked-up x.

Saving

The points are saved with the patch and come back when it loads (see What is saved with the patch). The GUI value has one cell per point, <x> <y> <curve>; an empty function reports the word clear. Writing that value back to the inlet restores the points and sends nothing.

A message that arrives while another thread is changing the points is ignored, and a GUI read at that moment comes back empty (see GUI controls and presets).

Inlets

#	Label	Accepts	Range	Description
0	function	FLOAT, INT, BANG, LIST	x >= 0, y in minimum-maximum, curve -1 to 1	A number is an x and sends its y; a bang sends the ramp; ‘<x> <y>’ adds a point; 3 numbers per point replace them all; ‘set’, ‘setcurve’, ‘nth’, ‘clear’ and ‘dump’ edit and query points. Edits send nothing.

Outlets

#	Label	Type	Range	Description
0	y	FLOAT	minimum-maximum	The y for an x arriving on the inlet, or for ‘nth <index>’. Always a float.
1	ramp	LIST	target time pairs	On a bang, the whole function as ‘<y> <time>’ pairs for .line or .bline: the first time is 0, each later one the distance in x from the point before.
2	dump	LIST	index x y curve	On ‘dump’, every point as ‘<index> <x> <y> <curve>’, in x order.

Parameters

Name	Default	Range	Description
points	128	2-1024, optional minimum, optional maximum	How many points the function can hold, then optionally the lowest and highest y (default 0 and 1).

.i

An integer number box. A number on the left inlet stores it and sends it, a bang sends it again, and the right inlet stores a number without sending it. Floats are truncated.

Dart:

Obj.gInt

Kind:

Control-rate

The right inlet stores a number without sending it; send a bang to the left inlet to send it later. A float is truncated toward 0, so 2.9 is stored as 2. Restoring the value works as described under .slider.

Inlets

#	Label	Accepts	Range	Description
0	set/bang	FLOAT, INT, BANG, LIST	any int	A number sets the value and sends it; a bang sends it again. Also takes its GUI value back, as a one-number list or ‘set 0 <value>’.
1	silent set	FLOAT, INT	any int	Stores a number without sending it.

Outlets

#	Label	Type	Range	Description
0	out	INT	any int	The value.

Parameters

Name	Default	Range	Description
value	0	any int	The value the box starts with.

.incdec

A stepper over a whole number. ‘inc’ and ‘dec’, or a signed step count on the middle inlet, move the value inside a range that clamps or wraps; a number sets it without sending and a bang sends it.

Dart:

Obj.gIncdec

Kind:

Control-rate

Messages

On the left inlet:

• bang: send the value without moving it.

• a number, or set <n>: set the value without sending it. A float is truncated.

• inc / dec: move one step up or down and send the result.

The middle inlet moves several steps at once: an int n moves n steps, down when it is negative, and sends the result. A MIDI encoder that sends +1 and -1 can drive it directly. 0 moves nothing and just sends the value.

The right inlet sets the step size. A negative step makes inc go down, and a step of 0 never moves the value.

The range

The value always stays between minimum and maximum, given in either order. With wrap 0 it stops at the ends. With wrap 1 it carries round to the other end, and both ends are reachable, so one step past the maximum is the minimum:

[.incdec 1 0 11 1]   at 11, inc  =>  0

Without arguments the range is the whole int range, and the value stops at its ends instead of overflowing.

The value is kept inside the range even before anything moves it: an .incdec 1 60 72 starts at 60. With wrap on, an untouched stepper starts wherever 0 wraps to (65 for 60-72), so send set first when the starting point matters.

The GUI value is the number. A one-number list or set 0 <value> sets it without sending, so a restore is silent (see GUI controls and presets).

Inlets

#	Label	Accepts	Range	Description
0	value	FLOAT, INT, BANG, LIST	any int, ‘inc’, ‘dec’, ‘set <n>’	A bang sends the value without moving it. A number, or ‘set <n>’, sets it without sending. ‘inc’ and ‘dec’ move one step up or down and send. Also takes its GUI value back, as a one-number list or ‘set 0 <value>’.
1	nudge	FLOAT, INT, LIST	any int	An int n moves n steps (negative moves down) and sends the result; 0 just sends the value. A float is truncated.
2	step	FLOAT, INT, LIST	any int	Sets the step size. A negative step makes ‘inc’ go down. A float is truncated.

Outlets

#	Label	Type	Range	Description
0	out	INT	minimum-maximum	The value, whenever it moves or is read.

Parameters

Name	Default	Range	Description
step	1	any int	How far one step moves the value; a negative step reverses ‘inc’ and ‘dec’.
minimum	-2147483648	any int	The bottom of the range.
maximum	2147483647	any int	The top of the range.
wrap	0	0 or 1	0 stops at the ends of the range; 1 wraps around to the other end.

.kslider

A piano keyboard. A pitch on the left inlet presses that key at the stored velocity and sends velocity and pitch; velocity 0 releases it. The state is the velocity held on each of the 128 keys.

Dart:

Obj.gKslider

Kind:

Control-rate

The state is the keyboard: the velocity held on each of the 128 keys, with 0 for a key that is up.

Messages

On the left inlet:

• a pitch: press that key at the stored velocity.

• <pitch> <velocity>: store the velocity, then play the pitch with it. Velocity 0 releases the key.

• set <pitch> <velocity>: the same, but the stored velocity stays as it was.

• 128 numbers: set every key at once, and send a pair only for each key that changed.

• clear: release every held key, sending velocity 0 for each.

• bang: send the pair for every held key, from low to high.

The right inlet stores the velocity for the pitches that follow. It sends nothing.

A pitch outside 0-127 is ignored; a velocity is clamped to 0-127. A float is truncated, and a list of any other length is ignored.

[.kslider]   60    =>  100, then 60
             60 0  =>  0, then 60

A single-key message sends even when the velocity has not changed, so playing the same note twice sends two note-ons.

Output

The velocity is sent before the pitch, so the pair can be wired straight into .noteon, .makenote or .flush, which take the velocity on a cold inlet. There is no mode that holds one note at a time.

The GUI value has 128 cells, one velocity per key. Held keys are not saved with the patch; only the velocity argument is.

Inlets

#	Label	Accepts	Range	Description
0	pitch	FLOAT, INT, BANG, LIST	0-127	A pitch presses that key at the stored velocity; ‘<pitch> <velocity>’ plays it at that velocity, and velocity 0 releases it. Also 128 numbers (the whole keyboard), ‘set <pitch> <velocity>’, ‘clear’ and bang.
1	velocity	FLOAT, INT, LIST	0-127	The velocity for pitches that arrive after it. Sends nothing. Clamped to 0-127; a float is truncated.

Outlets

#	Label	Type	Range	Description
0	pitch	INT	0-127	The pitch of the key that moved. Sent after the velocity.
1	velocity	INT	0-127	The key’s new velocity: 0 for a release. Sent before the pitch, so it pairs with the pitch in the next object.

Parameters

Name	Default	Range	Description
velocity	100	0-127	The velocity a bare pitch is played at, until the right inlet or a ‘<pitch> <velocity>’ list changes it.

.l

A list box. A bang sends the stored list; a list arriving on the inlet replaces it without sending it.

Dart:

Obj.gList

Kind:

Control-rate

Unlike .m, the box always sends its text as a list, even when it is a single number or starts with a word.

Inlets

#	Label	Accepts	Range	Description
0	trigger/set	BANG, LIST	—	A bang sends the stored list; a list replaces it silently.

Outlets

#	Label	Type	Range	Description
0	out	LIST	—	The stored list.

Parameters

Name	Default	Range	Description
message	—	any text	The list the box starts with.

.led

A labelled on/off indicator. It latches by default (a number sets it, a bang flips it) or registers presses with the ‘momentary’ keyword, and sends its state and its label.

Dart:

Obj.gLed

Kind:

Control-rate

.led and .textbutton are the same object under two names. A host draws .led as a lamp and .textbutton as a labelled button; they take the same arguments and messages.

Arguments

An optional momentary keyword, then the label. The words of the label are joined with single spaces, so .textbutton filter cutoff is one control called “filter cutoff”. A label cannot start with the word momentary. The label is fixed: changing the arguments replaces the object.

Latching and momentary

Without momentary the control latches: a number sets the state (0 off, anything else on) and a bang flips it.

With momentary every number or bang is a press, whatever the number. The state stays 1 until the host next reads the GUI value, which clears it. Poll it from one place only.

In both modes, a one-number list or set 0 <value> sets the state outright. In momentary mode that is the only way to clear a press without reading it.

Output

Every message sends: the label from the right outlet first, then the state from the left outlet. A control without a label sends an empty list. Wire a bank of labelled controls into one .route and the label says which one fired:

[.textbutton mute]   bang  =>  right: mute,  left: 1

A message starting with any other word changes nothing, and the state is still sent. There is no message to change the label, and no way to set the state without sending it.

The GUI value is 0 or 1. A host or .preset can write it back; in momentary mode, restoring a value taken during a press replays the press (see GUI controls and presets).

Inlets

#	Label	Accepts	Range	Description
0	state	FLOAT, INT, BANG, LIST	0 or 1	Latching: a number sets the state (0 off, anything else on) and a bang flips it. Momentary: any number or bang is a press. In both modes a one-number list or ‘set 0 <value>’ sets the state outright. Everything here sends.

Outlets

#	Label	Type	Range	Description
0	state	INT	0 or 1	The state. Sent last.
1	label	LIST	the label, or empty	The label, so a bank of controls wired into one object can say which one fired. Empty when the control has no label. Sent first.

Parameters

Name	Default	Range	Description
label	—	optional ‘momentary’, then any text	An optional ‘momentary’ keyword, then the label. The words of the label are joined with single spaces.

.m

A message box. A bang sends the stored text as the message it spells: a number, a bang, a list or a command. A message arriving on the inlet replaces the text without sending it.

Dart:

Obj.gMessage

Kind:

Control-rate

The text is sent as the message it spells:

[.m 440]       =>  the int 440
[.m 0.5]       =>  the float 0.5
[.m 1 2 3]     =>  a list
[.m stop]      =>  the command stop, to objects that take one

A list, or text starting with a word, that arrives on the inlet replaces the stored text without sending it. .l always sends its text as a list.

Inlets

#	Label	Accepts	Range	Description
0	trigger/set	BANG, LIST	—	A bang sends the stored message; a list or a word message replaces it silently.

Outlets

#	Label	Type	Range	Description
0	out	ANY	—	The stored message, as the message it spells: one number is an int or a float, the word ‘bang’ is a bang, a list starting with a number is a list, and text starting with any other word is a command to objects that take one (‘stop’ to ‘~line’, ‘allnotesoff’ to ‘.midiout’) and a list to every other object.

Parameters

Name	Default	Range	Description
message	—	any text	The text the box starts with.

.matrixctrl

A grid of cells, columns by rows, such as a step pattern or a routing patchbay. ‘<column> <row> <value>’ sets a cell, and every change is sent in that same form, so the grid can drive .matrix or .router directly.

Dart:

Obj.gMatrixctrl

Kind:

Control-rate

Arguments

columns rows minimum maximum: each axis 1-256, default 8, and a cell range of 0 to 1 by default. A count outside 1-256 is clamped with a warning. Changing the arguments replaces the object, and every cell starts at 0 again.

Messages

The inlet takes lists and bangs only:

• <column> <row> <value>: set that cell.

• one number per cell, columns * rows of them: set the whole grid.

• set <index> <value>: set one cell by index, where the index of (column, row) is column * rows + row.

• clear: set every cell to 0 (or to the bound nearest 0).

• getrow <row> / getcolumn <column>: send that row’s or column’s values from the right outlet as one list.

• bang: send every cell.

A cell outside the grid, or a list of any other length, is ignored. Values are clamped to the range. On a grid of exactly three cells, a three-number list sets the whole grid; use set to address one cell.

Output

Every change is sent from the left outlet as <column> <row> <value>: one list for a one-cell change, and one per cell, column by column, for a whole grid, a clear or a bang. That is the form the control inlets of .matrix and .router take, so the grid can drive either directly.

[.matrixctrl 4 4]   2 1 1     =>  2 1 1.
                    set 9 1   =>  2 1 1.

The GUI value has one cell per grid cell, in index order. There is no mode that allows only one active cell per row or column.

Inlets

#	Label	Accepts	Range	Description
0	grid	BANG, LIST	minimum-maximum	‘<column> <row> <value>’ sets one cell; a list of every cell sets the whole grid; ‘set <index> <value>’ sets one cell by index; ‘clear’, ‘getrow <row>’, ‘getcolumn <column>’ and bang. Lists and bangs only.

Outlets

#	Label	Type	Range	Description
0	cell	LIST	column row value	Changed cells as ‘<column> <row> <value>’: one list per cell, ready for the control inlet of .matrix or .router.
1	line	LIST	minimum-maximum	One row’s or one column’s values as a list, in answer to ‘getrow’ or ‘getcolumn’.

Parameters

Name	Default	Range	Description
columns	8	1-256, optional rows 1-256, optional minimum, optional maximum	The number of columns, then optionally the number of rows (default 8) and the lowest and highest value a cell can hold (default 0 and 1).

.multislider

A bank of sliders, such as the steps of a sequencer or the bands of an equaliser. A list sets the cells and the bank size, ‘set <index> <value>’ sets one cell, and every message sends the whole bank as a list.

Dart:

Obj.gMultislider

Kind:

Control-rate

Messages

• a list: set the cells from its numbers, and make the bank as long as the list (up to 1024 cells).

• a number: set every cell to it.

• set <index> <value>: set one cell.

• fetch <index>: send that cell’s value from the right outlet.

• bang: send the bank again.

Every message sends the whole bank from the left outlet, after a fetch answer. An index outside the bank is ignored, and every value is clamped to the range.

Size

The size argument sets the starting number of cells, 1 to 1024. A list of another length changes it. Shrinking hides the cells at the end rather than clearing them, so lengthening the bank again brings their values back.

Changing the range takes effect at once: an untouched .multislider 4 20 20000 reads back as four 20s. The values and the live size are not saved with the patch. To sum, sort or scale the bank, process the list it sends with .zl.

Inlets

#	Label	Accepts	Range	Description
0	bank	FLOAT, INT, BANG, LIST	minimum-maximum	A list sets the cells and the bank size; a number sets every cell; ‘set <index> <value>’ sets one cell; ‘fetch <index>’ asks for one cell; a bang sends again. Everything here sends the bank.

Outlets

#	Label	Type	Range	Description
0	bank	LIST	minimum-maximum	The whole bank as one list, after every message.
1	cell	FLOAT	minimum-maximum	One cell’s value, in answer to ‘fetch <index>’. Sent before the bank.

Parameters

Name	Default	Range	Description
size	8	1-1024	How many cells the bank starts with. A list of another length changes it later.
minimum	0	any float	The lowest value a cell can hold.
maximum	127	any float	The highest value a cell can hold.

.nodes

Blends between circular nodes in a 2D field. Move a cursor with ‘x y’ and it sends each node’s distance and a weight that falls from 1 at the node’s centre to 0 at its edge, scaled so the weights add up to 1.

Dart:

Obj.gNodes

Kind:

Control-rate

The field holds up to 64 nodes, each a circle with an x, a y and a radius. A new .nodes 4 has four nodes at 0 0 with radius 1.

Messages

• <x> <y>: move the cursor and send.

• three or more numbers, <x> <y> <radius> ...: set every node, and make the field as long as the number of complete triples. A partial triple at the end is ignored.

• set <index> <x> <y> [<radius>]: move one node; without a radius it keeps its radius.

• bang: send again.

There is no int or float message: build the cursor pair with .pack 0. 0., or wire in the right outlet of .xyslider, which sends x y.

Output

The right outlet sends the distance from the cursor to each node, then the left outlet sends one weight per node. A node’s closeness is 1 at its centre, falls in a straight line to 0 at its edge, and is 0 outside it. Each weight is that closeness divided by the sum over all nodes:

• inside at least one node the weights add up to 1, so a crossfade built on them keeps its level as the cursor moves;

• outside every node all weights are 0. There is no fallback to the nearest node.

A node with a radius of 0 or less never gets any weight, which mutes it without deleting it.

[.nodes 2]   0 0 1  1 0 1,  then 0.5 0  =>  right: 0.5 0.5,  left: 0.5 0.5

The GUI value has one cell per node, <x> <y> <radius>. Writing the whole value back restores the number of nodes as well. Positions are not saved with the patch; only the count argument is.

Inlets

#	Label	Accepts	Range	Description
0	field	BANG, LIST	any float	‘x y’ moves the cursor; three or more numbers set every node as ‘x y radius’ triples; ‘set <index> <x> <y> [<radius>]’ moves one node; a bang sends again. Everything here sends.

Outlets

#	Label	Type	Range	Description
0	weights	LIST	0.0-1.0, summing to 1 or all 0	One weight per node, as a list. The weights add up to 1 while the cursor is inside at least one node, and are all 0 outside every node. Sent last.
1	distances	LIST	0 and up	The distance from the cursor to each node, as a list. Sent first.

Parameters

Name	Default	Range	Description
count	4	1-64	How many nodes the field starts with. A field list of another length changes it later.

.nslider

A note on a staff: a pitch and how it is spelled. It sends the pitch and its accidental (1 sharp, -1 flat, 0 natural); a black key follows the ‘spelling’ argument unless a message chooses otherwise.

Dart:

Obj.gNslider

Kind:

Control-rate

The state is a pitch and how it is spelled. MIDI pitch 61 can be written as C sharp or as D flat; the accidental says which, so a host knows the sign to draw and, from pitch - accidental, the line or space to draw it on.

Spelling

A white key is always natural (0). A black key is spelled with the accidental the last message chose, or else by the spelling argument: 0 or above for a sharp, below 0 for a flat. Only the sign of an accidental counts.

Messages

• a number: a pitch, spelled the default way again.

• <pitch> <accidental>: a pitch with its spelling.

• set 0 <pitch>: move the note and keep the chosen spelling.

• set 1 <accidental>: re-spell the note without moving it.

• bang: send again.

The pitch is clamped to minimum-maximum (given in either order, within 0-127). Every message sends the accidental from the right outlet, then the pitch from the left.

[.nslider 0 127 -1]   61    =>  -1, then 61    (D flat)
                      61 1  =>  1, then 61     (C sharp)

A patch in a flat key sets spelling to -1 once, and a single note re-spelled as a sharp does not change it. There is no empty state and no chords: the staff always shows one note.

Inlets

#	Label	Accepts	Range	Description
0	note	FLOAT, INT, BANG, LIST	minimum-maximum	A number is a pitch, spelled the default way; ‘<pitch> <accidental>’ chooses the spelling; ‘set 0 <pitch>’ moves the note and ‘set 1 <accidental>’ re-spells it; a bang sends again. Everything here sends.

Outlets

#	Label	Type	Range	Description
0	pitch	INT	minimum-maximum	The pitch. Sent after the accidental.
1	accidental	INT	-1, 0 or 1	How the pitch is spelled: 1 sharp, -1 flat, 0 natural (always 0 for a white key). Sent first.

Parameters

Name	Default	Range	Description
minimum	0	0-127	The lowest pitch the staff covers.
maximum	127	0-127	The highest pitch the staff covers.
spelling	1	1 for sharps, -1 for flats	How a black key is spelled when no message chooses: 0 or above for a sharp, below 0 for a flat.

.preset

Stores and recalls snapshots of the patch’s controls. ‘store <n>’ captures every control whose value can be restored into slot n, and a number recalls that slot. The slots are saved with the patch.

Dart:

Obj.gPreset

Kind:

Control-rate

store <n> captures every control whose GUI value can be written back, in the whole patch including subpatchers, and a recall sends each one its value again. Presets covers the messages, what a slot captures, and when a recall runs. The slots are saved with the patch, but loading does not recall one (see What is saved with the patch).

[.preset 8]   store 0  ...  0  =>  every control back as it was, then 0

The GUI value is the active slot, or -1 when none is active. It is read-only. A recall is instant: there is no blending between slots.

Inlets

#	Label	Accepts	Range	Description
0	control	FLOAT, INT, BANG, LIST	slot 0 to slots-1	A number, or ‘recall <n>’, recalls that slot; a bang recalls the active slot again; ‘store <n>’ captures the patch into slot n; ‘clear <n>’, ‘clear’ and ‘clearall’ empty slots.

Outlets

#	Label	Type	Range	Description
0	recalled	INT	0 to slots-1	The slot just recalled, sent once every value is back in place. Nothing for an empty slot.
1	stored	INT	0 to slots-1	The slot just stored.

Parameters

Name	Default	Range	Description
slots	32	1-1024	How many slots the bank holds. Changing it replaces the object, and the new one starts with empty slots.

.radiogroup

Radio buttons, or check boxes with ‘multi’, over named items. It works exactly like .umenu; a host draws it as a group of buttons.

Dart:

Obj.gRadiogroup

Kind:

Control-rate

It works exactly like .umenu; see there. A host draws radio buttons, or check boxes with multi: .radiogroup multi 8 is eight check boxes. In multi mode a number toggles that box, and a list of one 0 or 1 per box sets them all.

Inlets

#	Label	Accepts	Range	Description
0	selection	FLOAT, INT, BANG, LIST	0 to item count - 1	A number selects that item (toggles it with ‘multi’); an item name selects that item; a list of numbers sets the whole selection; ‘set <index> <value>’ writes one cell; a bang sends again. Everything here sends.

Outlets

#	Label	Type	Range	Description
0	index	INT	0 to item count - 1	The item number: the selection, or with ‘multi’ the item just changed. Sent last.
1	item	LIST	one item name	The name of that item.
2	state	LIST	the index, or one flag per item	The whole selection, as the GUI value spells it: the item number, or with ‘multi’ a 0 or 1 per item. Sent first.

Parameters

Name	Default	Range	Description
items	—	optional ‘multi’, then either item names or a single item count 1-256	An optional ‘multi’ keyword, then the item names. A single number is a count of items named by their numbers; no items gives two.

.rslider

A range control: two ends inside minimum-maximum, such as a key split or a velocity layer. It sends the lower end, the higher end and both as a list, whichever way round the ends were set.

Dart:

Obj.gRslider

Kind:

Control-rate

The two ends are set separately, and either may be the higher one: the object always sends the lower end from the left outlet and the higher end from the middle one, with the pair, lower first, from the right outlet. The outlets fire right to left.

[.rslider]   20 -> right inlet, then 100 -> left inlet  =>  20. 100.,  100,  20

• a number on the left inlet sets that inlet’s end and sends.

• a number on the right inlet sets the other end silently.

• a list sets both ends from its first two numbers; a single number sets the left inlet’s end.

• set 0 <value> moves the current low end and set 1 <value> the high end.

• bang: send again.

Both ends are clamped to minimum-maximum, which may be given in either order. The GUI value has two cells, low end first.

Inlets

#	Label	Accepts	Range	Description
0	end/range	FLOAT, INT, BANG, LIST	minimum-maximum	A number sets one end; a list sets both ends; ‘set <0|1> <value>’ moves the low or the high end; a bang sends again. Everything here sends.
1	end	FLOAT, INT	minimum-maximum	Sets the other end without sending.

Outlets

#	Label	Type	Range	Description
0	low	FLOAT	minimum-maximum	The lower end. Sent last.
1	high	FLOAT	minimum-maximum	The higher end.
2	range	LIST	minimum-maximum	Both ends as a list, lower first. Sent first.

Parameters

Name	Default	Range	Description
minimum	0	any float	The lowest value either end can reach.
maximum	127	any float	The highest value either end can reach.

.slider

A slider holding a position from 0 to 1. A number sets the position, clamped to that range, and sends it; a bang sends it again.

Dart:

Obj.gSlider

Kind:

Control-rate

The position runs from 0 to 1. A number outside that range is clamped, so an int sets 0 or 1. Every message sends the position. For another range, use .dial or put .scale after the slider.

Restoring a value

.slider, .dial, .i, .f and .t take their own GUI value back on the left inlet, which is how a host or .preset restores them:

• a list holding one value sets it. That is exactly the string the host read.

• set 0 <value> sets it too. 0 is the cell number; any other cell number is ignored.

Both work like a number on the inlet: clamped the same way, and the value is sent. Only the first number of a longer list is used. A list starting with any other word changes nothing, and the value is sent again. See GUI controls and presets for the protocol as a whole.

Inlets

#	Label	Accepts	Range	Description
0	set/bang	FLOAT, INT, BANG, LIST	0.0-1.0	A number sets the position and sends it; a bang sends it again. Also takes its GUI value back, as a one-number list or ‘set 0 <value>’.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	0.0-1.0	The position.

.t

An on/off toggle. An int sets it (0 is off, any other number on), a bang flips it, and every message sends the state as 0 or 1.

Dart:

Obj.gToggle

Kind:

Control-rate

An int sets the state: 0 is off, any other number is on. A bang flips it. Every message sends the state as 0 or 1.

The GUI value is on or off. The left inlet takes that word back, or a number, alone or after set 0, and sets the state without flipping it. Restoring works as described under .slider.

Inlets

#	Label	Accepts	Range	Description
0	set/toggle	INT, BANG, LIST	0 or 1	An int sets the state (0 off, anything else on); a bang flips it. Also takes its GUI value back: ‘on’, ‘off’ or a number, alone or after ‘set 0’.

Outlets

#	Label	Type	Range	Description
0	out	INT	0 or 1	The state.

.tab

A row of tabs over named items. It works exactly like .umenu; a host draws it as tabs.

Dart:

Obj.gTab

Kind:

Control-rate

It works exactly like .umenu; see there. A host draws a row of tabs. Wire the name outlet into .route to switch between named pages of a patch.

Inlets

#	Label	Accepts	Range	Description
0	selection	FLOAT, INT, BANG, LIST	0 to item count - 1	A number selects that item (toggles it with ‘multi’); an item name selects that item; a list of numbers sets the whole selection; ‘set <index> <value>’ writes one cell; a bang sends again. Everything here sends.

Outlets

#	Label	Type	Range	Description
0	index	INT	0 to item count - 1	The item number: the selection, or with ‘multi’ the item just changed. Sent last.
1	item	LIST	one item name	The name of that item.
2	state	LIST	the index, or one flag per item	The whole selection, as the GUI value spells it: the item number, or with ‘multi’ a 0 or 1 per item. Sent first.

Parameters

Name	Default	Range	Description
items	—	optional ‘multi’, then either item names or a single item count 1-256	An optional ‘multi’ keyword, then the item names. A single number is a count of items named by their numbers; no items gives two.

.text

A comment in the patch. It holds its text for a host to display and has no inlets or outlets.

Dart:

Obj.gText

Kind:

Control-rate

Parameters

Name	Default	Range	Description
text	—	any text	The text to display.

.textbutton

A button carrying a text label. It works exactly like .led; a host draws it as a labelled button instead of a lamp.

Dart:

Obj.gTextbutton

Kind:

Control-rate

It works exactly like .led; see there. A host draws a button with the label on it.

Inlets

#	Label	Accepts	Range	Description
0	state	FLOAT, INT, BANG, LIST	0 or 1	Latching: a number sets the state (0 off, anything else on) and a bang flips it. Momentary: any number or bang is a press. In both modes a one-number list or ‘set 0 <value>’ sets the state outright. Everything here sends.

Outlets

#	Label	Type	Range	Description
0	state	INT	0 or 1	The state. Sent last.
1	label	LIST	the label, or empty	The label, so a bank of controls wired into one object can say which one fired. Empty when the control has no label. Sent first.

Parameters

Name	Default	Range	Description
label	—	optional ‘momentary’, then any text	An optional ‘momentary’ keyword, then the label. The words of the label are joined with single spaces.

.textedit

An editable text field. Text arriving on the inlet replaces the stored text and is sent on; a bang sends it again. It holds up to 256 characters.

Dart:

Obj.gTextedit

Kind:

Control-rate

Everything that arrives is text. A list is stored word for word: no word is a command, so a field can hold set or clear like any other text. A number is stored as the text that spells it, and an empty list clears the field. Every message sends the text from the outlet, as a list.

The field holds at most 256 characters. Longer text is ignored and the stored text is kept (and sent again). A starting text longer than that is ignored with an error in the log.

The text is never turned back into a number: a field holding 440 sends the text 440. Put .fromsymbol after it to read a number, or .tosymbol to join the words into one.

The GUI value is the text. It is written back as plain text, with no set form (see GUI controls and presets). The live text is not saved with the patch; the text argument is only the starting text.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	any text up to 256 characters	A list becomes the text, word for word, and is sent on; a number becomes its text; a bang sends the text again. An empty list clears it.

Outlets

#	Label	Type	Range	Description
0	out	LIST	—	The text, as a list, after every message.

Parameters

Name	Default	Range	Description
text	—	any text up to 256 characters	The text the field starts with.

.umenu

A menu of named items. A number or an item name selects an item, and it sends the item number, its name and the whole selection. With ‘multi’, several items can be selected at once.

Dart:

Obj.gUmenu

Kind:

Control-rate

.umenu, .radiogroup and .tab are the same object under three names. A host draws .umenu as a pop-up menu, .radiogroup as radio buttons or check boxes and .tab as a row of tabs; they take the same arguments and messages.

Arguments

An optional multi keyword, then the items:

• no items: two items, named 0 and 1.

• a single number of 1 or more: that many items, named by their numbers.

• anything else: one item per word, up to 256. A longer list is cut short with a warning.

With multi, several items can be selected at once. The first item cannot be named multi, and an item named set cannot be selected by name. The items are fixed: changing the arguments replaces the object. There are no messages to add or remove items.

Messages

• a number: select that item. With multi it toggles the item instead. A number outside the list is ignored.

• an item name: select that item. An unknown name is ignored.

• a list of numbers: the whole selection, as the right outlet spells it. Without multi that is the item number; with multi it is one 0 or 1 per item, and a shorter list leaves the remaining items as they are.

• set <index> <value>: without multi, set 0 <item> selects an item; with multi, set <item> <0|1> sets one item.

• bang: send again.

Output

Every message sends, right to left: the whole selection, then the name of the item, then its number. With multi the number is the item that just changed, or after a whole-selection write the lowest selected item.

[.umenu sine square saw]   saw  =>  2,  saw,  2

The GUI value is the selection: one cell with the item number, or with multi one cell per item.

Inlets

#	Label	Accepts	Range	Description
0	selection	FLOAT, INT, BANG, LIST	0 to item count - 1	A number selects that item (toggles it with ‘multi’); an item name selects that item; a list of numbers sets the whole selection; ‘set <index> <value>’ writes one cell; a bang sends again. Everything here sends.

Outlets

#	Label	Type	Range	Description
0	index	INT	0 to item count - 1	The item number: the selection, or with ‘multi’ the item just changed. Sent last.
1	item	LIST	one item name	The name of that item.
2	state	LIST	the index, or one flag per item	The whole selection, as the GUI value spells it: the item number, or with ‘multi’ a 0 or 1 per item. Sent first.

Parameters

Name	Default	Range	Description
items	—	optional ‘multi’, then either item names or a single item count 1-256	An optional ‘multi’ keyword, then the item names. A single number is a count of items named by their numbers; no items gives two.

.xyslider

A two-dimensional pad holding an x and a y, each inside its own bounds, so two parameters move as one gesture. It sends x, y and the pair as a list.

Dart:

Obj.gXyslider

Kind:

Control-rate

x and y are independent, each clamped to its own pair of arguments, which may be given in either order. The position is never sorted: the first cell is always x.

• a number on the left inlet sets x and sends.

• a number on the right inlet sets y silently.

• a list x y sets both; a single number sets x.

• set 0 <value> sets x and set 1 <value> sets y.

• bang: send again.

The outlets fire right to left: the pair, then y, then x. The pair is the cursor message .nodes takes, so one cord turns the pad into a morph control.

Inlets

#	Label	Accepts	Range	Description
0	x/position	FLOAT, INT, BANG, LIST	xminimum-xmaximum	A number sets x; a list ‘x y’ sets both; ‘set <0|1> <value>’ sets x or y; a bang sends again. Everything here sends.
1	y	FLOAT, INT	yminimum-ymaximum	Sets y without sending.

Outlets

#	Label	Type	Range	Description
0	x	FLOAT	xminimum-xmaximum	The x value. Sent last.
1	y	FLOAT	yminimum-ymaximum	The y value.
2	position	LIST	per-axis bounds	Both values as the list ‘x y’. Sent first.

Parameters

Name	Default	Range	Description
xminimum	0	any float	The lowest value of x.
xmaximum	127	any float	The highest value of x.
yminimum	0	any float	The lowest value of y.
ymaximum	127	any float	The highest value of y.