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, 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.name);

count (Number, get)

Number of objects in the patcher

filepath (String, get)

The patcher’s file path on disk

firstobject (Maxobj, 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, get/set)

The patcher's name (its window title, without any brackets that appear for subpatchers)

locked (Boolean, get/set)

The patcher's locked state. This property is read-only in the runtime version of Max.

maxclass (String, get)

Returns “patcher”

parentclass (String, 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, get)

If the patcher is a subpatcher, this returns the parent patcher. Otherwise it returns a nil value.

scrolloffset (Array, get/set)

X/Y coordinate array for the scroll offset of a patcher is window

scrollorigin (Array, get/set)

X/Y coordinate array for the patcher's fixed origin

wind (Wind, get)

A Javascript representation of the window associated with the patcher. For more information, see the Wind Object.

Patcher Methods

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.

newobject (classname,params)

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 (left,right,classname, additional arguments)

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 (from_object, outlet, to_object, inlet)

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 (from_object, outlet, to_object, inlet)

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 (from_object, outlet, to_object, inlet)

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 (function)

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 (function)

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

applyif (action_function, test_function)

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 (action_function, test_function)

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

remove (object)

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

getnamed (name)

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 (function)

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.

Example:

  // search for an object with a negative left coordinate
  function neg_left(a)
  {
    r = a.rect;
  // rect is a property that returns an array
    if (r[0] < 0)
      return 1;
    else
      return 0;
  }
  e = patcher.getlogical(neg_left);
  if (e)
    e.rect[0] = 0;

bringtofront (object)

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 (object)

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.