In this section, we describe some general information about writing Javascript code for
the js and jsui objects.
Arguments
After supplying a filename after the word js, you can type in additional
arguments; these are available to your script’s global code or any function
in an array property called jsarguments[]. jsarguments[0] is the filename of
your script, jsarguments[1] is the first typed-in argument. jsarguments.length
is the number of typed-in arguments plus one. In other words, if there are no
typed-in arguments, the value of jsarguments.length will be 1.
The jsui inspector contains an arguments field: enter the arguments
you wish to use here. The first argument you type into the field can be accessed as jsarguments[1].
How Input to the js Object is Handled
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.
function foo(a,b,c)
{
post(a,b,c);
}
post() is a function of the js object that writes the value of one or more
Javascript items to the Max window, described in more detail in
the jsthis Methods section.
Special Function Names
msg_int, msg_float
To define a function to respond to a number, you need to name the function msg_int or msg_float.
Example:
function msg_int(a)
{
post(a);
}
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.
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(a)
{
post("the list contains",arguments.length, "elements");
}
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.
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 Max Object.
for more information.
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:
var myvalue = 0.25;
function getvalueof()
{
return myvalue;
}
setvalueof
Defining 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:
function setvalueof(v)
{
myvalue = v;
}
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:
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);
}
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.
See the description of the embedmessage message to the jsthis object
here.
notifydeleted
the notifydeleted method is called when the js/jsui object is freed.
function notifydeleted()
Reserved Words
The Max js object also responds to special messages that control
the object itself, such as open, read, etc. Refer to the js and jsui pages
in the Max Reference manual for details. If you define, for example, a function
named read inside your script, it can’t be executed directly via a message sent to
the js object. However, you can still name a function read and call the function
from another Javascript function you define/
Global Code
Global code, as we’ve mentioned before, consists of any Javascript statements
that exist outside of any function definition. Your global code is always executed
when your script is loaded or recompiled after you edit it. When a js or jsui object
is being created, the global code is executed before the object is completely created. It won’t
have any inlets or outlets, nor does it know about its context within a patcher. This means you
can use the global code to define how many inlets and/or outlets you’d like to have. However,
it also means that, since outlets don’t exist yet, you can’t use them. If you want to perform
some kind of initialization after your object has outlets, you’ll need to write a loadbang() function
mentioned in the previous section.
What to do in your global code:
Set the number of inlets and outlets you would like (see js Object Properties).
Access the arguments the user typed in with the jsarguments[] property.
Set up the assistance for your inlets and outlets.
Create and initialize global variables/
Use the Max object to access and control the global application environment.
What not to do:
Send things out your outlets.
Refer to your object’s Patcher (see
the Patcher Object
for more information).
Private (Local) Functions
If you do not want a method to be invoked outside of Javascript via a message
to js from Max, you can set its local property to 1. For example, suppose
the function foo() is not something we wish to expose to the outside world.
foo.local = 1;
function foo()
{
post("what does Pd *really* stand for?");
}
Now, when we send the message foo to the js object, we see the following error in the Max window: