Basic Techniques

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, a Dict, or an Array of numbers and/or Strings. Note: Dict objects are not supported in an Array return value.

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, String or Dict. 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. A Dict value will be passed as a single argument.

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, compile, etc. Refer to the js and jsui pages in the Max Reference manual for details. If you define, for example, a function named "compile" inside your script, it can’t be executed directly via a message sent to the js object. However, you can still name a function "compile" 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:

error: js: function foo is private