Introduction

The js and jsui objects run Javascript version 1.8.5 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.

How Javascript Works in the js Object

Javascript is a textual language that is “compiled” into a script. Scripts have global code and functions. Any Javascript expressions and statements that aren’t inside functions are considered to be in global code

Example:

var a = 2 // global code
function assign(x) {
  a = x // statement in a function, not global code
}

Global code is executed immediately after a Javascript source file is compiled. This allows you to initialize a global variable or property. Functions can be called by global code, as well as from within other functions, but they can also be called via messages sent to the js object. This makes implementing new Max objects in Javascript very straightforward because the name you give to a function is the same as the message name a Max user would use to invoke it.

For example, if the Javascript source above were compiled into a js object, we could click on the message box in the patch shown below to invoke the assign() function with an argument of 10.

The js object only uses Javascript saved in a text file. You can write Javascript code using a separate editor, or use the text window built into Max. If you use the built-in window, the js object will recompile its Javascript source each time you save the file. If you use another text editor, you can recompile the source from the text file by sending the message compile to the js object. Or you can send the message autowatch 1 to the js object, and every time the file is saved, the object will recompile it automatically

Overview of js Object Extensions to Javascript

Javascript is a language designed to control the software in which it is embedded. Put another way, it is a language designed to script an application. Javascript code always executes within a script context that can add new properties and functions - this is, for example, how Netscape added browser-specific features familiar to Web developers.

In order to understand the script context in the Max js object, it is important to realize that there is a Javascript model of the Max world that you will be manipulating. Perhaps the most important aspect of this model is that there is a Javascript version of the Max js object itself. This object, which we refer to in this documentation as the jsthis object, is the “base” on which you build properties and methods when you write functions and global code. Some examples should make this clear. Consider the Javascript we listed above again:

var a = 2 // global code
function assign(x) {
  a = x // statement in a function, not global code
}

The function assign() becomes a method of jsthis, and the variable a becomes its property. In Javascript a method can be invoked by using a dot notation on an object. We could rewrite the above example as follows using the optional Javascript this keyword to make the object-oriented nature of the environment more apparent. We’ve also added a new function provoke() that invokes assign()

this.a = 2 // global code
function assign(x) {
  this.a = x
  // statement in a function, not global code
}
function provoke() {
  this.assign(1000)
}

However, you shouldn’t really need to concern yourself with these semantic details if you have an irrational hatred of object-oriented terminology and concepts

The Javascript jsthis object has certain built-in properties and methods you will need to use in order to work within the Max environment. For example, there is an outlet() method to send data out an outlet. You can also access the Max js object’s typed-in arguments, find out which inlet received a message, and define the number of inlets and outlets the object has. These features are documented in the section on the jsthis object described in the basic techniques vignette.

While the word this in generally optional, you may need to use it when passing the current jsthis instance to functions. For example, you can send a reference to your jsthis object out an outlet, or use it in creating a Task object (see below for more about Tasks)

In addition to jsthis, the notion of a Javascript Max model is completed with a series of Javascript classes defined as part of the context. One of the primary reasons for the js object was to provide a more powerful interface for the patcher scripting features where you can create, connect and move new objects. The Max, Patcher, Wind, and Maxobj classes are used in scripting and Max application control. The Task object provides a convenient Javascript interface to the Max scheduler. The Folder class allows you to enumerate files. And the Global class allows different js instances to communicate with each other and share data, as well as interface to Max send and receive objects

Before we enumerate the properties and functions for these Javascript classes, we’ll review how you handle Javascript source text files for the js and jsui objects

Assigning a File to js and jsui

Applies to the js object only: If you type js into an object box with no arguments, you will get an object that can’t do anything and has a single inlet and outlet. The first argument to the js object is a filename of some Javascript source. By convention, Javascript source files end in the extension .js. In fact, if you like, you can name a file something like myscript.js and type js myscript. Assuming the file myscript.js is in the Max search path, the js object will find it

Applies to the jsui object only: There are several ways to assign a Javascript source file to the jsui object.

• Select the jsui object. Click on the Inspector button in the Patcher Window toolbar to show the Inspector. Click on the Choose... button in the Value column of the JavaScript File Setting and select it from the standard open file dialog window.
• Right-click or control-click on a selected jsui object to see a contextual menu. You will see several choices specific to the jsui object, including the names of Javascript source files in the jsui-library folder inside the Cycling ’74 folder. Choose one of these files, or choose Load New File… to select another file using a standard open file dialog window.
• Right-click or control-click on a selected jsui object and click to see a contextual menu. Choose Open Editor from the contextual menu. After typing some Javascript, save the text window. The name you gave the file is now assigned to the jsui object and will be recorded when the patcher containing the jsui is saved.