class jsthis

The global code in one JavaScript file.

You can't create an Instance of this class. It contains functions added to the JavaScript language that are specific to use of JavaScript in the js and jsui object implementation.

For most messages, a message received in the inlet of the Max js object will invoke a method with the same name defined for the JavaScript jsthis object passing anything after the beginning symbol as arguments to the function. The jsthis.bang() and jsthis.list() methods are two examples.

You can also create your own custom message handlers. For example, within Max, sending the message foo 1 2 3 to the js object invokes the foo() method of the jsthis object. In other words, it looks for a function property of jsthis called foo and passes 1, 2, and 3 as arguments to the function.

function foo(a, b, c) {
    post(a, b, c);
}

Properties

autowatch boolean

Whether automatic file reloading is on

This is particularly useful during development of your Javascript code if you have several js instances using the same source file and you want them all to update when the source changes. It can also be used to facilitate the use of an external text editor. When the text editor saves the file, the js object will notice and recompile it. By default, the value of autowatch is 0 (off). If you want to turn on autowatch, it is best to do so in your global code.

Example

// begin file example.js
autowatch = 1;

function loadbang() {
    // your code here
}

// end file example.js

box Maxobj read-only

The current object's box

Example

function bang() {
    var box = this.box();
    post(box.rect.toSource());
}

editfontsize number

Size of the font shown in the text editing window

Controls the size of the font shown in the text editing window where you edit a script in points. By assigning the editfontsize property in your global code, you can override the default font size setting for text editing, which is the same size as the text shown in the Max window.

*

Example

// begin file example.js
editfontsize = 10;

function loadbang() {
    // your code here
}

// end file example.js

inlet number read-only

The inlet number which received the message triggering the currently executing function

During the execution of a function, the inlet property reports the inlet number that received the message that triggered the function, starting at 0 for the leftmost inlet. This property’s value is 0 within global code.

Example

inlets = 3;

function msg_int(val) {
    switch(inlet) {
        case 2:
            post("inlet 3: " + val);
            break;
        case 1:
            post("inlet 2: " + val);\
            break;
        default:
            post("left inlet: " + val);
    }
}

inlets number

Number of inlets of the current object instance

The inlets property must be set in the global code to have any effect. If it isn't set, an object with one inlet will be created.

jsarguments string[] read-only

Access arguments typed into the js object when instantiated

The filename is jsarguments[0], and the first typed-in argument is jsarguments[1], and so on. The jsarguments[] array is available in global code and any function and it doesn't change unless the js object receives the jsargs message with new typed-in arguments.

Example

Creating an object with a variable number of outlets based on an argument typed into the js object

oulets = 0
if (jsarguments.length >= 2) {
    outlets = jsarguments[1];
}
if (!outlets) {
    oulets = 1;
}

max Max read-only

Global Max instance

Gets a JavaScript representation of the "max" object (e.g. the recipient of ; max preempt 1 in a message box). This lets you send any message to the object that controls the Max application.

Example

max.preempt(1);

messagename string read-only

Name of the message to the js object that invoked the method currently running

In global code, this is a nil value. This is generally useful only from within an anything function that will be called when no specific function name matches the message sent to the js object.

Example

Note the use of JavaScript bracket notation to specify a variable property

var stuff;
function anything(val) {
    if (arguments.length) {
        stuff[messagename] = val;
    }
}

outlets number

Number of outlets the js object should have

The outlets property must be set in the global code to have any effect. If it isn’t set, and object with one outlet will be created.

Example

outlets = 2;
function anything() {
    outlet(0, "this is outlet 0");
    outlet(1, "this", "is", "outlet", "1");
}

Methods

anything

The anything function is called if no specific function is found to match the message symbol received by the js object

If you want to know the name of the message that invoked the function, use the message property. If you want to know what inlet received the message, use the inlet property.

anything(): void;

Example

function anything() {
    var val = arrayfromargs(messagename, arguments);
    post("anything() was called: " + val.toSource());
}

arrayfromargs

A utility for writing functions that take a variable number of arguments and/or those that can be called using various messages (like anything)

The function object has an arguments property that can be numerically indexed like an Array but is not an instance of Array. This means that you cannot call Array functions such as sort() on the arguments property or send the arguments property out of an outlet as a list of values. The arrayfromargs method will convert the arguments property to an Array, optionally with message as the zeroth element of the array. This message usage is useful for processing messages as though they are lists beginning with a symbol, as would be typical in your anything function.

arrayfromargs(arguments: object): string[];

Example 1

In this example, the arguments passed to the js object are sorted and sent out the first outlet.

function anything() {
    // messagename is a property of the `jsthis` object and
    // returns the name of the message which invoked the function
    var a = arrayfromargs(messagename, arguments);
    a.sort();
    outlet(0, a);
}

Example 2

In this example, any list sent to the js object is printed as an array.

function list() {
   var a = arrayfromargs(arguments);
   post("received list " + a + "\n");
}

arrayfromargs

A utility for writing functions that take a variable number of arguments and/or those that can be called using various messages (like anything)

The function object has an arguments property that can be numerically indexed like an Array but is not an instance of Array. This means that you cannot call Array functions such as sort() on the arguments property or send the arguments property out of an outlet as a list of values. The arrayfromargs method will convert the arguments property to an Array, optionally with message as the zeroth element of the array. This message usage is useful for processing messages as though they are lists beginning with a symbol, as would be typical in your anything function.

arrayfromargs(message: string, arguments: object): string[];

Example

In this example, the arguments passed to the js object are sorted and sent out the first outlet.

function anything() {
    // messagename is a property of the `jsthis` object and
    // returns the name of the message which invoked the function
    var a = arrayfromargs(messagename, arguments);
    a.sort();
    outlet(0, a);
}

assist

Set the patcher assist string for a designated inlet or outlet of a js object

This method is designed to be called from the assistance function, specified as an argument to jsthis.setinletassist() or jsthis.setoutletassist().

assist(...args: any[]): void;

Example

outlets = 2;

function describe(n) {
    assist("This is outlet number: ", n);
}

setoutletassist(-1, describe);

bang

A function called when the js object receives a bang

bang(): void;

Example

function bang() {
    post("a bang was received\n");
}

declareattribute

Declare an attribute which can be set, queried, and optionally stored in the patcher file

If no getter or setter methods are specified, default ones will be used. These attributes can also be referenced by pattr.

declareattribute(attributeName: string, getterName?: string, setterName?: string, embed?: boolean): void;

Example 1

A simple attribute declaration where default getters and setters are used

var foo = 2;
declareattribute("foo");

function bang() {
    outlet(0, foo);
}

Example 2

A default getter and setter are used and the attribute is stored in the patcher file on save

var foo = 2;
declareattribute("foo", null, null, 1);

function bang() {
    outlet(0, foo);
}

Example 3

An explicit getter and setter are declared

var foo = 2;
declareattribute("foo", "getfoo", "setfoo");

function getfoo() {
    return foo;
}

function setfoo(v) {
    foo = v;
}

function bang() {
    outlet(0, foo);
}

embedmessage

The jsthis.embedmessage() method works only inside of the jsthis.save() function. It is used to specify the name of a function you want to be called when the js object containing the script is recreated.

embedmessage(functionName: string, args: number | number[] | string | string[]): void;

Example

In this example, when the js object containing this script is instantiated, the function numchairs will be called with an argument of 20 followed by the numtables function with an argument of 2. Finally, the roomname function will be called with an argument of "diningroom".

function save() {
    embedmessage("numchairs", 20);
    embedmessage("numtables", 2);
    embedmessage("roomname", "diningroom");
}

function numchairs(v) {
    // ...
}

function numtables(v) {
    // ...
}

function roomname(x) {
    // ...
}

getvalueof

Permit pattr and related objects to attach to and query an object's current value.

The value of an object returned can be a number, string, or an array of numbers and/or strings.

getvalueof(): any | any[];

Example 1

myValue = 100;

function getvalueof() {
    return myValue;
}

Example 2

getvalueof works for other objects, not just js and jsui

var flonum = this.patcher.newobject("flonum");
flonum.setvalueof();
post("value: " + flonum.getvalueof() + "\n");

list

A function called when the js object receives a Max list (i.e. messages that begin with a number)

In implementing a list function, you'll probably want to use the arguments property so you can handle input of varying length.

list(): void;

Example

function list() {
    var val = arrayfromargs(messagename, arguments);
    post("list was called: " + val.toSource() + "\n");
}

loadbang

A function called when a patcher containing the js or jsui object is loaded

This function will not be called when you instantiate a new js or jsui object and add it to a patcher; it will only be called when a pre-existing patcher file containing a js object is loaded - in other words, at the same time that loadbang objects in a patcher are sending out bangs. You may wish to test the loadbangdisabled property of the

loadbang(): void;

Example

function loadbang() {
    post("loadbang was called\n");
}

msg_float

A function called when the js object receives a float

If no jsthis.msg_int() method is defined, all numbers will be passed to the jsthis.msg_float() method and ints will be converted to floats before being used.

msg_float(value: number): void;

Example

function msg_float(v) {
    post(v);
}

msg_int

A function called when the js object receives an integer

If no jsthis.msg_float() method is defined, all numbers will be passed to the jsthis.msg_int() method and ints will be truncated to ints before being used.

msg_int(): void;

Example

function msg_int(v) {
    post(v);
}

notifyclients

Notify any clients (such as the pattr family of objects) that the object's current value has changed

Clients can then take appropriate action (such as sending a js instance the message getvalueof to invoke the jsthis.getvalueof() method if defined). The jsthis.notifyclients() method is useful for othat define jsthis.setvalueof() and jsthis.getvalueof() for pattr compatibility.

notifyclients(): void;

notifydeleted

A function called when the js/jsui object is freed

notifydeleted(): void;

outlet

Send data through an outlet

If the outlet number if greater than the number of outlets, no output occurs.

If the argument to jsthis.outlet() is a JavaScript object, it is passed as the Max message jsobject which is the address of the object. When jsobject followed by a number is sent to a js object, it is parsed and checked to see if the number specifies the address of a valid JavaScript object. If so, the word jsobject disappears and the function sees only the JavaScript object reference.

If the argument to jsthis.outlet() is an array, it is unrolled one level and passed as a Max message or list (depending on whether the first element of the array is a number or string).

outlet(n: number, ...args: any[]): void;

refresh

Copy the contents of this.sketch to the screen

This function is only available when using the jsui object. Call this function after drawing using the Sketch object to move the contents of sketch to the screen. Must be called after making any changes to the drawing in order to see those changes. If you're using MGraphics to draw instead, use MGraphics.redraw()

refresh(): void;

Example

Draw a ball at a randmo position when jsui gets a bang

function bang()
{
	with (Math) {
		with (sketch) {
			shapeslice(vslices);
			moveto((random()-0.5)*2,(random()-0.5)*2,(random()-0.5)*2);
			glcolor(random(),random(),random(),1);
			sphere(random()*0.4);
		}
	}
	refresh();
}

save

Allow your script to embed state in a patcher file containing your js object and restore the state when the patcher is reloaded

Saving your state consists of storing a set of messages that your script will receive shortly after the js object containing it is recreated. These messages are stored using the jsthis.embedmessage() which only words inside your save function.

save(): void;

Example

When the patch containing the js object is saved, preserve the current value of a variable

var numcowbells = 1;
function cowbells(a) {
    numcowbells = 1;
}

function save() {
    embedmessage("cowbells", numcowbells);
}

setinletassist

Associates either a number, string, or function with a numbered inlet

If -1 is passed as the inlet number, the object argument is used for all inlets. In order to produce any assistance text in the patcher window the assistance function needs to call the jsthis.assist() method. For an example use, see jsthis.setoutletassist(). The jsthis.setinletassist() and jsthis.setoutletassist() functions are best called in global code but can be called at any time. You can even replace the assistance function or string dynamically.

setinletassist(n: number, callback: Function): void;

setoutletassist

Associates either a number, string, or function with a numbered outlet

If -1 is passed as the outlet number, the object argument is used for all inlets. In order to produce any assistance text in the patcher window the assistance function needs to call the jsthis.assist() method. The jsthis.setinletassist() and jsthis.setoutletassist() functions are best called in global code but can be called at any time. You can even replace the assistance function or string dynamically.

setoutletassist(n: number, callback: Function): void;

Example

outlets = 2;

function describe(n) {
    assist("This is outlet number: ", n);
}

setoutletassist(-1, describe);

setvalueof

Permit pattr and related objects to attach to and set an object's current value

Values passed will be of type number or string. For a value that consists of more than one number or string, the jsthis.setvalueof() method will receive multiple arguments. The jsthis arrayfromargs method is useful to handle values that can contain a variable number of elements.

setvalueof(...args: number[] | string[]): void;

Example

setvalueof works for other objects, not just js and jsui

var flonum = this.patcher.newobject("flonum");
flonum.setvalueof();
post("value: " + flonum.getvalueof() + "\n");