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 true;
				  // iterfun must return true to continue
				  // iterating, else stops
				  }
				  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.