The Patcher object is a Javascript representation of a Max patcher. You can find, create, modify, and iterate through objects within a patcher, send messages to a patcher that you would use with the thispatcher object, etc.
There are currently three ways to get a Patcher:
- Use the Constructor
- Access the patcher property of a jsthis (accessed as this.patcher)
- Use the subpatcher() method of a Maxobj object
Patcher Constructor
var p = new Patcher(left, top, bottom, right)
left, top, bottom, right: global screen coordinates of the Patcher window
var p = new Patcher()
Uses 100,100,400,400 as default window coordinates
Patcher Properties
box [Maxobj]
If the patcher is a subpatcher, the box property returns the Maxobj that contains it. To traverse up to the top-level patcher:
var prev = 0
var owner = this.patcher.box
while (owner) {
prev = owner
owner = owner.patcher.box
}
if (prev) post("top patcher is", prev.patcher.name)
count [Number]
Number of objects in the patcher
filepath [String]
The patcher’s file path on disk
firstobject [Maxobj]
If the patcher contains objects, this is the first one in its list. You can iterate through all objects in a patcher using the nextobject property of a Maxobj.
name [String]
The patcher's name (its window title, without any brackets that appear for subpatchers)
locked [Boolean]
The patcher's locked state. This property is read-only in the runtime version of Max.
maxclass [String]
Returns “patcher”
parentclass [String]
Returns the Max class name of the parent object if this is a subpatcher, or a nil value if this is a top-level patcher.
parentpatcher [Patcher]
If the patcher is a subpatcher, this returns the parent patcher. Otherwise it returns a nil value.
scrolloffset [Array]
X/Y coordinate array for the scroll offset of a patcher is window
scrollorigin [Array]
X/Y coordinate array for the patcher's fixed origin
wind [Object]
A Javascript representation of the window associated with the patcher. For more information, see the Wind Object.
Patcher Methods Overview
Any message to a patcher that you can send in Max (via the thispatcher object) you can send in Javascript in js.
Examples:
p = this.patcher
p.fullscreen(1) // makes the patcher take up the whole screen
p.dirty() // make an editable patcher dirty
The Patcher methods listed below present a slighly more usable implementation of patcher scripting. You can still script a patcher using the script message, since, as shown above, a Javascript Patcher object can accept any message you can send to a thispatcher object.
Patcher Methods
newobject
Arguments
params [Anything]
Creates a new object of Max class classname in a patcher using the specified parameters and returns a Maxobj (see below) that represents it.
Example:
a = patcher.newobject("toggle", 122, 90, 15, 0)
newdefault
Arguments
top [Number]
classname [String]
arguments [Anything]
Creates a new object of class classname in a patcher using the specified parameters and return a Maxobj (see below) that represents it.
Example:
a = patcher.newdefault(122, 90, "toggle")
The newdefault() method also accepts additional arguments for non-user interface objects that represent the created object’s typed-in arguments.
Example:
a = patcher.newdefault(122, 90, "pack", "rgb", 255, 128, 64)
connect
Arguments
outlet [Number]
to-object [String]
inlet [Number]
Connects two objects (of type Maxobj) in a patcher. Indices for the outlet and inlet arguments start at 0 for the leftmost inlet or outlet.
Example:
p = this.patcher
a = p.newobject("toggle", 122, 90, 15, 0)
b = p.newobject("toggle", 122, 140, 15, 0)
p.connect(a, 0, b, 0)
hiddenconnect
Arguments
outlet [Number]
to-object [String]
inlet [Number]
Connects two objects (of type Maxobj) in a patcher with a hidden patch cord. Arguments are the same as for the connect message above.
disconnect
Arguments
outlet [Number]
to-object [String]
inlet [Number]
Disconnects an existing connection between two objects (of type Maxobj) in a patcher. Indices for the outlet and inlet arguments start at 0 for the leftmost inlet or outlet.
Example: (assuming the connect() example above):
p.disconnect(a, 0, b, 0)
apply
Arguments
For all objects in a patcher, calls the function with the each object's Maxobj as an argument. Does not recurse into subpatchers. The following example prints the name of each object's class in the Max window:
function printobj(a) {
post(a.maxclass)
post()
return true
// iterfun must return true to continue
// iterating, else stops
}
this.patcher.apply(printobj)
applydeep
Arguments
Same as apply() except that applydeep() recurses into subpatchers (depth first).
applyif
Arguments
test_function [String]
For all objects in a patcher, run the test_function for each object's Maxobj as an argument. If the test_function returns true, the action_function is executed with the Maxobj as an argument.
applydeepif
Arguments
test_function [String]
Same as applyif() except that applydeepif() recurses into subpatchers
remove
Arguments
Removes the object (a Maxobj passed as an argument) from a patcher
getnamed
Arguments
Returns the first object found in a patcher with the given name. The name is a local name as specified by the Name... dialog in a patcher, not the name of a send or receive object. You can also set an object's name using the varname property of a Maxobj.
getlogical
Arguments
Calls the function on each object in a patcher, passing it as a Maxobj argument to the function. If the function returns true, the iteration stops and the Maxobj object is returned as the value of the getlogical() method. Otherwise getlogical() returns a nil value. Please note that access to patcher attributes in global code is not supported. This requires the use of loadbang().
Example:
// post the patching rectangle and Max class of each object in the current patch
function logical(a) {
if (a) return 1
else return 0
}
function loadbang() {
e = patcher.getlogical(logical) //uses the return value as an array
if (e && e.length) {
for (var i = 0; i < e.length; i++) {
post(e[i].maxclass + ": " + e[i].rect + "\n")
}
}
}
function bang() {
loadbang()
}
bringtofront
Arguments
Moves the object to the front of the current layer to which it is assigned (either background or foreground). You can change the layer by setting the background property of a Maxobj.
sendtoback
Arguments
Moves the object to the back of the current layer to which it is assigned (either background or foreground). You can change the layer by setting the background property of a Maxobj.
See Also
| Name | Description |
|---|---|
| JavaScript Usage | JavaScript Usage |