Classes

Last modified: 2012-12-5

Class LiveApi

The LiveAPI object provides a means of communicating with the Live API functions from JavaScript. For background information on this functionality, please see the Live API Overview and Live Object Model documents, as well as the Reference pages for live.path, live.object and live.observer objects, which provide the same basic functionality as the LiveAPI object, but from the Max patcher.

LiveAPI in Cycling '74 Reference

Class Summary
Constructor Attributes Constructor Name and Description
 
LiveApi()
LiveAPI Constructor.
Field Summary
Field Attributes Field Name and Description
Array get 
children
An array of children of the object at the current path.
Number get/set 
id
The id of the Live object referred to by the LiveAPI object.
String get 
info
A description of the object at the current path, including id, type, children, properties and functions.
Number get/set 
mode
The follow mode of the LiveAPI object.
Patcher get 
patcher
The patcher of the LiveAPI object, as passed into the Constructor.
String get/set 
path
The path to the Live object referred to by the LiveAPI object.
String get/set 
property
The observed property, child or child-list of the object at the current path, if desired.
String get 
proptype
The type of the currently observed property or child.
String get 
type
The type of the object at the current path.
Method Summary
Method Attributes Method Name and Description
void 
call(callback, arguments)
Calls the given function of the current object, optionally with a list of arguments.
mixed 
get(property)
Returns the value or list of values of the specified property of the current object.
Integer 
getcount(child)
The count of children of the object at the current path, as specified by the child argument.
String 
getstring(property)
Returns the value or list of values of the specified property of the current object as a String object.
void 
goto(path)
Navigates to the path and causes the id of the object at that path out be sent to the callback function defined in the Constructor.
void 
set(property, value)
Sets the value or list of values of the specified property of the current object.
Class Detail

LiveApi

()
LiveAPI Constructor. callback is an optional JavaScript function. This function will be called when the LiveAPI object refers to a new object in Live (if the LiveAPI object's path change, for instance), or when an observed property changes. path refers to the object in Live "pointed to" by the LiveAPI object (e.g. "live_set tracks 0 devices 0"). Alternately, a valid id can be used to refer a LiveAPI object to an object in Live.

Technical note: you cannot use the LiveAPI object in JavaScript global code. Use the live.thisdevice object to determine when your Max Device has completely loaded (the object sends a bang from its left outlet when the Device is fully initialized, including the Live API).

Legacy note: previous versions of the LiveAPI object required the jsthis object's this.patcher property as the first argument. For backward-compatibility, this first argument is still supported, but is no longer necessary.

The LiveAPI Object and the Scheduler Beginning with release 6.0 of Max, it is no longer possible to configure JavaScript functions to run in the high-priority thread of Max's scheduler. The LiveAPI object cannot be created or used in the high-priority thread, so users should be sure to use the defer or deferlow objects to re-queue messages to the js object.
Example:
var api = new LiveAPI(sample_callback, "live_set tracks 0");
if (!api) {
	post("no api object\n");
	return;
}
post("api.mode", api.mode ? "follows path" : "follows object", "\n");
post("api.id is", api.id, "\n");
post("api.path is", api.path, "\n");
post("api.children are", api.children, "\n");
post("api.getcount(\"devices\")", api.getcount("devices"), "\n");

api.property = "mute";
post("api.property is", api.property, "\n");
post("type of", api.property, "is", api.proptype, "\n");

function sample_callback(args){
	post("callback called with arguments:", args, "\n");
}
Field Detail
{Array get}

children

An array of children of the object at the current path.
{Number get/set}

id

The id of the Live object referred to by the LiveAPI object. These ids are dynamic and awarded in realtime from the Live application, so should not be stored and used over multiple runs of Max for Live.
{String get}

info

A description of the object at the current path, including id, type, children, properties and functions.
{Number get/set}

mode

The follow mode of the LiveAPI object. 0 (default) means that LiveAPI follows the object referred to by the path, even if it is moved in the Live user interface. For instance, consider a Live Set with two tracks, "Track 1" and "Track 2", left and right respectively. If your LiveAPI object's path is live_set tracks 0, the left-most track, it will refer to "Track 1". Should the position of "Track 1" change, such that it is now to the right of "Track 2", the LiveAPI object continues to refer to "Track 1". A mode of 1 means that LiveAPI updates the followed object based on its location in the Live user interface. In the above example, the LiveAPI object would always refer to the left-most track, updating its id when the object at that position in the user interface changes.
{Patcher get}

patcher

The patcher of the LiveAPI object, as passed into the Constructor.
{String get/set}

path

The path to the Live object referred to by the LiveAPI object. These paths are dependent on the currently open Set in Live, but are otherwise stable: live_set tracks 0 devices 0 will always refer to the first device of the first track of the open Live Set.
{String get/set}

property

The observed property, child or child-list of the object at the current path, if desired. For instance, if the LiveAPI object refers to "live_set tracks 1", setting the property to "mute" would cause changes to the "mute" property of the 2nd track to be reported to the callback function defined in the LiveAPI Constructor.
{String get}

proptype

The type of the currently observed property or child. The types of the properties and children are given in the Live Object Model.
{String get}

type

The type of the object at the current path. Please see the Live API Overview and Live Object Model documents for more information.
Method Detail
{void}

call

(callback, arguments)
Calls the given function of the current object, optionally with a list of arguments.
Parameters:
{Function} callback
{mixed} arguments
 
{mixed}

get

(property)
Returns the value or list of values of the specified property of the current object.
Parameters:
{String} property
 
{Integer}

getcount

(child)
The count of children of the object at the current path, as specified by the child argument.
Parameters:
{Object} child
 
{String}

getstring

(property)
Returns the value or list of values of the specified property of the current object as a String object.
Parameters:
{String} property
 
{void}

goto

(path)
Navigates to the path and causes the id of the object at that path out be sent to the callback function defined in the Constructor. If there is no object at the path, id 0 is sent.
Parameters:
{String} path
 
{void}

set

(property, value)
Sets the value or list of values of the specified property of the current object.
Parameters:
{String} property
{mixed} value
 
©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 2012-12-5