Basic Javascript programming: Global Methods

cpost

Arguments

Prints a message to the system console window. See post() below for further details about arguments.

error

Arguments

Sends a red tinged message to the Max window.

messnamed

Arguments

Sends a message to the named Max object. A named Max object is an object associated with a global symbol (not an object with a patcher-specific name). For example, Max receive objects are bound to global symbols. The following code would send the message bang to the named object flower.

Example:

messnamed("flower","bang”);

post

Arguments

Prints a representation of the arguments in the Max window. If post() has no arguments, it prints starting on the next line. Otherwise it prints the input on the current line separated by spaces. Arrays are unrolled to one level as with outlet.

Example:

a = new Array(900, 1000, 1100)
post(1, 2, 3, "violet", a)
post()
post(4, 5, 6)

These statements produce the following output in the Max window:

1 2 3 violet 900 1000 1100 4 5 6

If you want a line break in the middle of a call to post() you can use "\n" within a string (this is now a general feature of Max). Also, post() begins a new line if the last person to write to the Max window was not the js object.

arrayfromargs

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)
}

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).

declareattribute

Arguments

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)
}

embedmessage

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.

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

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.

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.

outlet

Arguments

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.

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

If the argument to outlet() is a Javascript object, it is passed as the Max message jsobject <jsvalue> 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).

setinletassist

Arguments

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.

setoutletassist

Arguments

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:

// assistance function
function describe_it(num) {
  assist("this is outlet number", num)
}
// global code to set it up
setoutletassist(-1, describe_it)