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

Constructors

new Patcher();

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

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

Constructs a new instance of the Patcher class

Properties

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)

count number read-only

Number of objects in the patcher

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.

locked boolean

Whether the patcher is locked

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

maxclass string read-only

Returns "patcher"

name string

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

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

scrolloffset [number, number]

The x-y coordinate array for the scroll offset of a patcher window

scrollorigin [number, number]

The x-y coordinate array of the patcher's fixed origin

wind Wind read-only

Get the Wind associated with the patcher

Methods

apply

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

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

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

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

bringtofront

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;

connect

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

disconnect

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

getattr

Get the value of a specified patcher attribute

getattr(attrname: string): string[];

getattrattr

Get the value of a specified patcher attribute's attribute

This method is only available in the new v8 javascript engine objects.

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

getattrnames

Get an array of all available attributes for the patcher

getattrnames(): string[];

getlogical

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

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

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

newdefault

Create a new object at a specified location

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

Example 1

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

Example 2

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

Create a new Max object

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

Example

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

remove

Remove a Maxobj from the patcher

remove(object: Maxobj): void;

sendtoback

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

Set the value of a specified patcher attribute

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

setattrdefault

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

This method is only available in the new v8 javascript engine objects.

setattrdefault(attrName: string): void;