A newer version of Max is available. Click here to access the latest version of the Max documentation

The Patcher Object

The Patcher Object

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]

g/s(get)

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]

g/s(get)

Number of objects in the patcher

filepath [String]

g/s(get)

The patcher’s file path on disk

firstobject [Maxobj]

g/s(get)

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]

g/s(get)

Returns “patcher”

parentclass [String]

g/s(get)

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]

g/s(get)

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]

g/s(get)

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

classname [String]
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

left [Number]
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

from-object [String]
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

from-object [String]
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

from-object [String]
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

function [String]

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
}
this.patcher.apply(printobj)

applydeep

Arguments

function [String]

Same as apply() except that applydeep() recurses into subpatchers (depth first).

applyif

Arguments

action_function [String]
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

action_function [String]
test_function [String]

Same as applyif() except that applydeepif() recurses into subpatchers

remove

Arguments

object [String]

Removes the object (a Maxobj passed as an argument) from a patcher

getnamed

Arguments

name [String]

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

function [String]

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

object [String]

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

object [String]

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.

getattrnames

Returns an Array value containing the names of available attributes for the Patcher.

getattr

Arguments

attribute_name [string]

Returns the value of the Patcher attribute specified by attribute_name. Lists are returned as JS Array objects.

setattr

Arguments

attribute_name [string]
anything [string]

Sets the value of the Patcher attribute specified by attribute_name.

See Also

Name Description
JavaScript Usage JavaScript Usage