class Patcher

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, and more.

There are currently three ways to get a Patcher:

1. Use the constructor method

2. Access the patcher property of jsthis (e.g. this.patcher)

3. Use the Maxobj.subpatcher() method

Any message to a patcher that you can send in Max (via the thispatcher object), you can send in JavaScript.

Example

p = this.patcher;
p.fullscreen(1); // make the patcher take up the whole screen
p.dirty(); // make an editable patcher dirty

Index

Constructors

• new Patcher()
• new Patcher(left, top, bottom, right)

Properties

• accentcolor
• bgcolor
• bgfillcolor
• box
• bubble_bgcolor
• bubble_outlinecolor
• clearcolor
• color
• count
• darkcolor
• editing_bgcolor
• elementcolor
• filepath
• firstobject
• lightcolor
• locked
• locked_bgcolor
• maxclass
• name
• parentclass
• parentpatcher
• patchlinecolor
• selectioncolor
• stripecolor
• syntax_attrargcolor
• syntax_attributecolor
• syntax_objargcolor
• syntax_objectcolor
• textcolor
• textcolor_inverse
• wind

Methods

• apply(fn)
• applydeep(fn)
• applydeepif(apply_fn, test_fn)
• applyif(applyFn, testFn)
• bringtofront(object)
• connect(fromObj, outlet, toObj, inlet)
• disconnect(fromObj, outlet, toObj, inlet)
• getattr(attrname)
• getattrattr(attrName, attrAttrName)
• getattrnames()
• getlogical(testFn)
• getnamed(name)
• hiddenconnect(fromObj, outlet, toObj, inlet)
• message(name, args)
• newdefault(left, top, classname, args)
• newobject(classname, args)
• remove(object)
• sendtoback(object)
• setattr(attrname, value)
• setattrdefault(attrName)

new Patcher()

new Patcher();

Constructs a new instance of the Patcher class with default window coordinates (100, 100, 400, 400)

new Patcher(left, top, bottom, right)

new Patcher(left: number, top: number, bottom: number, right: number);

Constructs a new instance of the Patcher class

accentcolor number[4] read-only

The accent color in the current style

apply(fn)

For all objects in a patcher, call a given function with each object's Maxobj as an argument

Does not recurse into subpatchers.

apply(fn: Function): void;

Example

The following prints the name of each object's class:

function printobj(obj) {
  post(obj.maxclass);
}
this.patcher.apply(printobj);

applydeep(fn)

For all objects in a patcher, recursing into subpatchers, call a given function with each object's Maxobj as an argument

applydeep(fn: Function): void;

applydeepif(apply_fn, test_fn)

For all objects in a patcher, recursing into subpatchers, call a given function with each object's Maxobj as an argument if a test function returns true

applydeepif(apply_fn: Function, test_fn: Function): void;

applyif(applyFn, testFn)

For all objects in a patcher, call a given function with each object's Maxobj as an argument if a test function returns true

Does not recurse into subpatchers.

applyif(applyFn: Function, testFn: Function): void;

Example

The following prints the name of each object's class if the object is hidden

function printhidden(obj) {
  post(obj.maxclass);
}
function ishidden(obj) {
  return obj.hidden;
}
this.patcher.applyif(printhidden, ishidden);

bgcolor number[4] read-only

The background color in the current style

bgfillcolor Dict read-only

The object background color in the current style

box Maxobj read-only

If the patcher is a subpatcher, the box property returns the Maxobj that contains it.

Example

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);

bringtofront(object)

Move an object to the front of the current layer (background or foreground)

You can change the layer by setting the Maxobj.background property.

bringtofront(object: Maxobj): void;

bubble_bgcolor number[4] read-only

Bubble background color in the current style

bubble_outlinecolor number[4] read-only

Bubble outline color in the current style

clearcolor number[4] read-only

Clear color in the current style

color number[4] read-only

The object color in the current style

connect(fromObj, outlet, toObj, inlet)

Connect two Maxobj objects in a patcher

Indices for the outlet and inlet arguments start at 0 for the leftmost inlet or outlet.

connect(fromObj: Maxobj, outlet: number, toObj: Maxobj, inlet: number): void;

Example

var p = this.patcher;
var a = p.newobject("toggle", 122, 90, 15, 0);
var b = p.newobject("toggle", 122, 140, 15, 0);
p.connect(a, 0, b, 0);

count number read-only

Number of objects in the patcher

darkcolor number[4] read-only

Dark color in the current style

disconnect(fromObj, outlet, toObj, inlet)

Disconnect two connected Maxobj objects in a patcher

Indices for the outlet and inlet arguments start at 0 for the leftmost inlet or outlet.

disconnect(
  fromObj: Maxobj,
  outlet: number,
  toObj: Maxobj,
  inlet: number,
): void;

Example

var p = this.patcher;
var a = p.newobject("toggle", 122, 90, 15, 0);
var b = p.newobject("toggle", 122, 140, 15, 0);
p.connect(a, 0, b, 0);
p.disconnect(a, 0, b, 0);

editing_bgcolor number[4] read-only

Unlocked patcher background color in the current style

elementcolor number[4] read-only

The element color in the current style

filepath string read-only

The patcher's file path on disk

firstobject Maxobj read-only

If the patcher contains objects, this is the first one in its list. You can iterate through all objects in a patcher using the Maxobj.nextobject property.

getattr(attrname)

Get the value of a specified patcher attribute

getattr(attrname: string): string[];

getattrattr(attrName, attrAttrName)

Supported only in the v8 engine.

Get the value of a specified patcher attribute's attribute

getattrattr(
  attrName: string,
  attrAttrName: string,
): number | number[] | string;

getattrnames()

Get an array of all available attributes for the patcher

getattrnames(): string[];

getlogical(testFn)

Collect all objects in a patcher which, when passed to a test function, cause that function to return true

getlogical(testFn: Function): Maxobj[] | undefined;

Example

function logical(a) {
  if (a) {
    return true;
  } else {
    return false;
  }
}

function loadbang() {
  // uses the return value as an array
  var found = patcher.getlogical(logical);
  if (found && found.length) {
    for (var i = 0; i < found.length; i++) {
      post(found[i].maxclass + ": " + found[i].rect + "\n");
    }
  }
}

function bang() {
  loadbang();
}

getnamed(name)

Get the first object found in a patcher with a given name

The name is the local varname specified via the Object > Name... menu or the varname property in the Inspector.

getnamed(name: string): Maxobj;

hiddenconnect(fromObj, outlet, toObj, inlet)

Connect two Maxobj objects in a patcher with a hidden patch cord

Indices for the outlet and inlet arguments start at 0 for the leftmost inlet or outlet.

hiddenconnect(
  fromObj: Maxobj,
  outlet: number,
  toObj: Maxobj,
  inlet: number,
): void;

Example

var p = this.patcher;
var a = p.newobject("toggle", 122, 90, 15, 0);
var b = p.newobject("toggle", 122, 140, 15, 0);
p.hiddenconnect(a, 0, b, 0);

lightcolor number[4] read-only

Light color in the current style

locked boolean

Whether the patcher is locked

This property is read-only in the runtime version of Max.

locked_bgcolor number[4] read-only

Locked patcher background color in the current style

maxclass string read-only

Returns "patcher"

message(name, args)

Send an arbitrary message to the patcher

message(name: string, ...args: any[]): any;

name string

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

newdefault(left, top, classname, args)

Create a new object at a specified location

newdefault(
  left: number,
  top: number,
  classname: string,
  ...args: any[]
): Maxobj;

Examples

var obj = patcher.newdefault(122, 90, "toggle");

The newdefault method also accepts additional arguments for non UI objects that represent the created object's typed-in arguments.

var obj = patcher.newdefault(122, 90, "pack", "rgb", 255, 128, 64);

newobject(classname, args)

Create a new Max object

newobject(classname: string, ...args: any[]): Maxobj;

Example

a = patcher.newobject("toggle", 122, 90, 15, 0);

parentclass string read-only

Get the Max class name of the parent object if this.patcher is a subpatcher, or a nil value if this is a top-level patcher

Example

function bang() {
  var pclass = this.patcher.parentclass;
  if (pclass) {
    post("The parent patcher class is " + pclass);
  } else {
    post("This is a top-level patcher");
  }
}

parentpatcher Patcher | undefined read-only

Get the parent patcher if this.patcher is a subpatcher, otherwise a nil value

patchlinecolor number[4] read-only

Patch cord color in the current style

remove(object)

Remove a Maxobj from the patcher

remove(object: Maxobj): void;

selectioncolor number[4] read-only

The selection color in the current style

sendtoback(object)

Send an object to the back of the current layer (background or foreground)

You can change the layer by setting the Maxobj.background property.

sendtoback(object: Maxobj): void;

setattr(attrname, value)

Set the value of a specified patcher attribute

setattr(attrname: string, value: any): void;

setattrdefault(attrName)

Supported only in the v8 engine.

Set the value of a specified patcher attribute to its default value (if a default value is defined)

setattrdefault(attrName: string): void;

stripecolor number[4] read-only

Stripe color in the current style

syntax_attrargcolor number[4] read-only

Syntax color for attribute arguments in the current style

syntax_attributecolor number[4] read-only

Syntax color for object attributes in the current style

syntax_objargcolor number[4] read-only

Syntax color for object arguments in the current style

syntax_objectcolor number[4] read-only

Syntax color for object names in the current style

textcolor number[4] read-only

The text color in the current style

textcolor_inverse number[4] read-only

The inverse text color in the current style

wind Wind read-only

Get the Wind associated with the patcher