Classes

Last modified: 2013-2-27

Class jsthis

Extends Maxobj.

Jsthis represents the global code in one javascript file. You can't create an Instance of this class.
The js and jsui objects run Javascript version 1.6 inside of Max. This topic covers information about the functions added to the Javascript language that are specific to the js and jsui object implementation. This topic is not a general reference on Javascript programming. A good on-line resource on Javascript is available here:

https://developer.mozilla.org/en/JavaScript/Reference

The Javascript language used by the js and jsui objects does not include web browser-specific functions and properties User interface functions and properties specific to the jsui object are covered in the Javascript Graphics topic. In this topic, unless specifically noted, all information covers both js and jsui even though we will refer only to the js object.

Jsthis in Cycling '74 Reference

Class Summary
Constructor Attributes Constructor Name and Description
<private>  
jsthis()
No Constructor.
Field Summary
Field Attributes Field Name and Description
Boolean get/set 
autowatch
Turns on the automatic file recompilation feature where a file is reloaded and recompiled if it changes.
Maxobj get 
box
Number get/set 
editfontsize
Controls the size of the font shown in the text editing window where you edit a script in points.
Number get 
inlet
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.
Number get/set 
inlets
Specifies how many inlets an instance should have.
Array get 
jsarguments
Allows access to the arguments typed into your object when it was instantiated.
max get 
max
Returns a Javascript representation of the "max" object (i.e.
String get 
messagename
The name of the message to the js object that invoked the method currently running.
Number get/set 
outlets
The number of outlets an object should have.
Fields borrowed from class Maxobj:
background, canhilite, colorindex, fontface, fontname, fontsize, hidden, hint, ignoreclick, js, maxclass, nextobject, patcher, rect, selected, valid, varname
Method Summary
Method Attributes Method Name and Description
abstract void 
anything()
You can define an anything() function that will run if no specific function is found to match the message symbol received by the js object.
Array 
arrayfromargs(message, arguments)
A utility for writing functions that take a variable number of arguments, and/or those that can be called using various messages (such as an anything function).
void 
assist(arguments)
Sets the patcher assist string for a designated inlet or outlet of a js object box designed to be called from the assistance function specified as an argument to the setinletassist() or setoutletassist() method (see example under setoutletassist() below).
abstract void 
bang()
To define a function to respond to a bang, you need to name the function bang().
void 
declareattribute(attributenamex, gettername, settername, embed)
Declare an attribute which can be set, queried, and optionally stored in the patcher file.
void 
embedmessage(function_name, arguments)
The embedmessage method works only inside of your save() function.
abstract mixed 
getvalueof()
Defining a function called getvalueof() permits pattr and related objects to attach to and query an object's current value.
abstract void 
list()
To handle Max lists, i.e.
abstract void 
loadbang()
To invoke a function when a patcher file containing the js or jsui object is loaded, define a function called loadbang().
abstract void 
msg_float(value)
To define a function to respond to a number, you need to name the function msg_int or msg_float.
abstract void 
msg_int(value)
To define a function to respond to a number, you need to name the function msg_int or msg_float.
void 
notifyclients()
Notifies any clients (such as the pattr family of objects), that the object’s current value has changed.
abstract void 
notifydeleted()
the notifydeleted method is called when the js/jsui object is freed.
void 
outlet(outlet_number, anything)
Sends the data after the first argument out the outlet specified by the outlet_number.
abstract void 
save()
Defining a function called save() allows your script to embed state in a patcher file containing your js object.
void 
setinletassist(inlet_number, callback)
Associates either a number, string, or function with the numbered inlet (starting at 0 for the left inlet).
void 
setoutletassist(outlet_number, callback)
Associates either a number, string, or function with the numbered outlet (starting at 0 for the left outlet).
abstract void 
setvalueof(mixed)
SDefining a function called setvalueof() permits pattr and related objects to attach to and set an object's current value, passed as argument(s) to the function.
abstract void 
your_function_name_here(value)
For most messages, a message received in an 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.
Methods borrowed from class Maxobj:
annotation, color, help, message, notify, subpatcher, understands
Class Detail
<private>

jsthis

()
No Constructor. Object created by placing a js box in a patcher. The jsthis object is the this within the context of any function you define that can be invoked from Max as well as your global code. When you define functions, they become methods of your extension of jsthis. When you use variables in your global code, they become its properties. The jsthis object has certain built-in properties and methods that facilitate interacting with and controlling the Max environment.
Field Detail
{Boolean get/set}

autowatch

Turns on the automatic file recompilation feature where a file is reloaded and recompiled if it changes. 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(){
	//code...
}

//end file example.js
Default Value:
0
{Maxobj get}

box

Example:
function bang(){
	var box = this.box();
	post(box.rect.toSource());
	post();
}
{Number get/set}

editfontsize

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:
editfontsize = 10;
{Number get}

inlet

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:
//send an integer to any inlet
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);
	}
}
Default Value:
This property’s value is 0 within global code.
{Number get/set}

inlets

Specifies how many inlets an instance should have. 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.
Example:
//send an integer to any inlet
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);
	}
}
Default Value:
1
{Array get}

jsarguments

Allows access to the arguments typed into your object when it was instantiated. The filename is jsarguments[0], the first typed-in argument is jsarguments[1]. The number of arguments plus one is jsarguments.length. jsarguments[] is available in global code and any function. It never changes after an object is instantiated, unless the Max js object receives the jsargs message with new typed-in arguments. Creating an object with a variable number of outlets based on an argument typed into the js object:
Example:
// set a test default value, protects against
// a bad arg or no args
outlets = 0;
if (jsarguments.length >= 2)
	outlets = jsarguments[1];
if (!outlets)
	outlets = 1; // default value
{max get}

max

Returns a Javascript representation of the "max" object (i.e., the recipient of ; max preempt 1 in a message box). Lets you send any message to the object that controls the Max application. In addition, the max object has js-specific properties listed in the section on js Max Object Properties. Here is an example of sending the max object the preempt message to turn Overdrive on:
Example:
max.preempt(1);
{String get}

messagename

The 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. Here is an example of an anything() function that adds a property to a variable declared in global code. Note the use of the tricky Javascript bracket notation to specify a variable property.
Example:
var stuff;
function anything(val){
	// were there any arguments?
	if (arguments.length)
		stuff[messagename] = val;
}
{Number get/set}

outlets

The number of outlets an 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. jsthis Methods The important methods of the jsthis object are outlet() and post(). The others listed here are typically for more advanced applications.
Example:
outlets = 2;

function anything(){

	// send a string to leftmost outlet
	outlet(0,"this is outlet 0");

	// send a list to the other outlet
	outlet(1,"this","is","outlet","1");

}
Default Value:
1
Method Detail
{abstract void}

anything

()
You can define an anything() function that will run 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 messagename property. If you want to know what inlet received the message, use the inlet property. Both of these properties are discussed in jsthis Properties.
Example:
function anything(){
	val = arrayfromargs(messagename,arguments);
	post("anything was called: " + val.toSource());
	post();
}
Returns:
usually no return value, but you can define it...
{Array}

arrayfromargs

(message, arguments)
A utility for writing functions that take a variable number of arguments, and/or those that can be called using various messages (such as an anything function). 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 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. Here is an example of a function that allows its arguments to be sorted. Note that messagename is a property of the jsthis object that returns the name of the message that invoked the function.
Example:
function anything(){
	var a = arrayfromargs(messagename,arguments);
	a.sort();
	outlet(0,a);
}
Parameters:
{String} message
{Object} arguments
 
{void}

assist

(arguments)
Sets the patcher assist string for a designated inlet or outlet of a js object box designed to be called from the assistance function specified as an argument to the setinletassist() or setoutletassist() method (see example under setoutletassist() below).
Example:
outlets = 2;
// assistance function
function describe_it(num){
	assist("this is outlet number",num);
}
// global code to set it up
setoutletassist(-1,describe_it);
Parameters:
{mixed} arguments
 
{abstract void}

bang

()
To define a function to respond to a bang, you need to name the function bang().
Example:
function bang(){
	post("bang was called \n");
}
Returns:
{void} usually no return value, but you can define it...
{void}

declareattribute

(attributenamex, gettername, settername, embed)
Declare an attribute which can be set, queried, and optionally stored in the patcher file. The attributename, argument is required, but the following arguments are optional. If no getterr or setter methods are specified, default ones will be used. These attributes can also be referenced by pattr. A few example uses are below.
Example:
// default getter/setter
var foo=2;
declareattribute("foo"); //simple

// default getter/setter and embed on save
declareattribute("foo",null,null,1);

// explicit getter/setter
declareattribute("foo","getfoo","setfoo");

function setfoo(v){
	foo = v;
}

function getfoo(){
	return foo;
}

function bang(){
	outlet(0,foo);
}
Parameters:
{String} attributenamex
{String} gettername
{String} settername
{Boolean} embed
 
{void}

embedmessage

(function_name, arguments)
The embedmessage method works only inside of your save() function. You use it to specify the name of a function you want to be called when the js object containing your script is recreated. The function name must be given as a string, followed by the arguments you wish to pass to the function. These arguments will typically be numbers, arrays, or strings (Javascript objects cannot be used in this context) and will reflect the current state of your object.

You may use the embedmessage method as many times as you want to specify multiple functions you wish to invoke to restore object state. Here is an example where functions we assume you’ve defined called numchairs(), numtables(), and roomname() are used in separate embedmessage statements within a save function.

When the js object containing this script is recreated, 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 the String diningroom.
Example:
function save(){
	embedmessage("numchairs",20);
	embedmessage("numtables",2);
	embedmessage("roomname","diningroom");
}
Parameters:
function_name
arguments
 
{abstract mixed}

getvalueof

()
Defining a function called getvalueof() permits pattr and related objects to attach to and query an object's current value. The value of an object returned can be a Number, a String, or an Array of numbers and/or Strings.
Example:
myValue = 100;
// define this function
function getvalueof(){
		return myValue;
}
// define this function
function setvalueof(val){
		myValue = val;
}


// works not only for jsthis/jsui
var flonum = this.patcher.newobject("flonum");
flonum.setvalueof(5.);
post("value: " + flonum.getvalueof() + "\n-\n");
Returns:
mixed type of return value depends on type of Maxobj
{abstract void}

list

()
To handle Max lists, i.e., a message that begins with a number, call your function list. In implementing a list function, you’ll probably want to use the Javascript arguments property, since otherwise you couldn’t handle input of varying length.
Example:
function list(val){

	// here comes a list of values, so a simple
	// variable to get the values does not work
	post("list was called: " + val.toSource() + "\n");

	// get the values with function arrayfromargs()
	val = arrayfromargs(messagename,arguments);

	// val is now an array of values
	post("list was called: " + val.toSource() + "\n");

}
Returns:
{void} usually no return value, but you can define it...
{abstract void}

loadbang

()
To invoke a function when a patcher file containing the js or jsui object is loaded, define a function called loadbang(). 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 max object and do nothing in your loadbang function if it is true. See the Maxobj for more information.
Example:
function loadbang(){
	post("loadbang was called \n");
}
Returns:
{void} usually no return value, but you can define it...
{abstract void}

msg_float

(value)
To define a function to respond to a number, you need to name the function msg_int or msg_float. If you define only msg_int(), any float received will be truncated and passed to msg_int(). Similarly, if only msg_float() exists, an int received will be passed to the msg_float() function.
Example:
function msg_float(a)
{
	post(a);
}
Parameters:
{Float} value
 
Returns:
{void} usually no return value, but you can define it...
{abstract void}

msg_int

(value)
To define a function to respond to a number, you need to name the function msg_int or msg_float. If you define only msg_int(), any float received will be truncated and passed to msg_int(). Similarly, if only msg_float() exists, an int received will be passed to the msg_float() function.
Example:
function msg_int(a)
{
	post(a);
}
Parameters:
{Integer} value
 
Returns:
{void} usually no return value, but you can define it...
{void}

notifyclients

()
Notifies 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 getvalueof() method (if defined – see the special function names listed above for more information). The notifyclients() method is useful for objects that define setvalueof() and getvalueof() functions for pattr compatibility.
{abstract void}

notifydeleted

()
the notifydeleted method is called when the js/jsui object is freed.
Example:
//TODO
{void}

outlet

(outlet_number, anything)
Sends the data after the first argument out the outlet specified by the outlet_number. 0 refers to the leftmost outlet. If the outlet_number is greater than the number of outlets, no output occurs.

If the argument to 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 outlet is an array, it is unrolled (to one level only) and passed as a Max message or list (depending on whether the first element of the array is a number or string).
Example:
outlet(0,"bang");  // sends a bang out the left outlet

outlet(1,4,5,6); // sends a list 4 5 6 out second-from-left
Parameters:
outlet_number
anything
 
{abstract void}

save

()
Defining a function called save() allows your script to embed state in a patcher file containing your js object. You can then 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 a special method of jsthis called embedmessage that only works inside your save function. An example will make this scheme clearer.

Suppose you have a message cowbells that sets the number of cowbells your object currently has

When the patch containing the js object is saved, you would like to preserve the current number of cowbells, so you define a save() function as follows:

Suppose the saved number of cowbells is 5. When it is reloaded, the js object will call your cowbell function with an argument of 5

The first argument to embedmessage is the name of the function you want to call as a string. Additional arguments to embedmessage supply the arguments to this function. These additional arguments will typically be the values of the state you want to save.

For more informaition see the embedmessage method.
Example:
var numcowbells = 1;
function cowbells(a){
	numcowbells = a;
}

// When the patch containing the js object is saved, you would like
// to preserve the current number of cowbells, so you define a save()
// function as follows:

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

setinletassist

(inlet_number, callback)
Associates either a number, string, or function with the numbered inlet (starting at 0 for the left 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 assist() method described above. See example at setoutletassist() below. The setinletassist() and 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.
Example:
inlets = 2;
// assistance function
function describe_it(num){
	assist("this is inlet number",num);
}
// global code to set it up
setinletassist(-1,describe_it);
Parameters:
inlet_number
callback
 
{void}

setoutletassist

(outlet_number, callback)
Associates either a number, string, or function with the numbered outlet (starting at 0 for the left outlet). If -1 is passed as the outlet number, the object argument is used for all outlets. In order to produce any assistance in the patcher, the assistance function needs to call the assist() method described above.
Example:
outlets = 2;
// assistance function
function describe_it(num){
	assist("this is outlet number",num);
}
// global code to set it up
setoutletassist(-1,describe_it);
Parameters:
outlet_number
callback
 
{abstract void}

setvalueof

(mixed)
SDefining a function called setvalueof() permits pattr and related objects to attach to and set an object's current value, passed as argument(s) to the function. Values passed will be of type Number or String. For a value that consists of more than one Number or String, the setvalueof() method will receive multiple arguments. The jsthis object’s arrayfromargs() method is useful to handle values that can contain a variable number of elements.
Example:
myValue = 100;
// define this function
function getvalueof(){
		return myValue;
}
// define this function
function setvalueof(val){
		myValue = val;
}


// works not only for jsthis/jsui
var flonum = this.patcher.newobject("flonum");
flonum.setvalueof(5.);
post("value: " + flonum.getvalueof() + "\n-\n");
Parameters:
{mixed} mixed
Type of parameter depends on type of Maxobj
 
Returns:
void
{abstract void}

your_function_name_here

(value)
For most messages, a message received in an 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. 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, passing 1, 2, and 3 as arguments to the function. If foo were defined as follows, the output in the Max window would be 1 2 3.
Example:
// send message 'foo 1 2 3' from max
function foo(a,b,c) {
	post(a,b,c);
	post();
}
Parameters:
{mixed} value
you define the type of parameter
 
Returns:
{void} usually no return value, but you can define it...
©2012-2013
Max MSP Documentation copied to JsDoc by Tim Schenk SEO Frelancer Berlin. Some examples are by him. Some descriptions of classes, interfaces, properties, methods or events are by him. Until now, most of it is a copy. Published with permission of Cycling '74. This document might be wrong or incomplete. All informations without any warranty. All trademarks are the property of their respective owners. Documentation generated by JsDoc Toolkit on 2013-2-27