1 /** 2 * @fileOverview JsDoc of classes in Max Javascript 3 * @author Max MSP Documentation copied to JsDoc by <a href="http://www.tim-schenk.de/">Tim Schenk</a> 4 * @version 1.0.0 5 */ 6 7 8 /** 9 * @class 10 * The LiveAPI object provides a means of communicating with the Live API functions from JavaScript. 11 * For background information on this functionality, please see the Live API Overview and Live Object 12 * Model documents, as well as the Reference pages for live.path, live.object and live.observer objects, 13 * which provide the same basic functionality as the LiveAPI object, but from the Max patcher. 14 * 15 * 16 * <br /><br /> 17 * LiveAPI in <a href="http://cycling74.com/docs/max6/dynamic/c74_docs.html#jsliveapi" target="_maxref">Cycling '74 Reference</a> 18 * 19 * @description 20 * LiveAPI Constructor. callback is an optional JavaScript function. This function will be called when the LiveAPI object refers 21 * to a new object in Live (if the LiveAPI object's path change, for instance), or when an observed property 22 * changes. path refers to the object in Live "pointed to" by the LiveAPI object (e.g. "live_set tracks 0 23 * devices 0"). Alternately, a valid id can be used to refer a LiveAPI object to an object in Live. 24 * <br /> 25 * <br /> 26 * <blockquote> 27 * Technical note: you cannot use the LiveAPI object in JavaScript global code. Use the live.thisdevice object 28 * to determine when your Max Device has completely loaded (the object sends a bang from its left outlet when 29 * the Device is fully initialized, including the Live API). 30 * </blockquote> 31 * <br /> 32 * 33 * <blockquote> 34 * Legacy note: previous versions of the LiveAPI object required the jsthis object's this.patcher property as 35 * the first argument. For backward-compatibility, this first argument is still supported, but is no longer necessary. 36 * </blockquote> 37 * <br /> 38 * 39 * <strong>The LiveAPI Object and the Scheduler</strong> 40 * 41 * Beginning with release 6.0 of Max, it is no longer possible to configure JavaScript functions to run in the 42 * high-priority thread of Max's scheduler. The LiveAPI object cannot be created or used in the high-priority 43 * thread, so users should be sure to use the defer or deferlow objects to re-queue messages to the js object. 44 * 45 * @example 46 * 47 * var api = new LiveAPI(sample_callback, "live_set tracks 0"); 48 * if (!api) { 49 * post("no api object\n"); 50 * return; 51 * } 52 * post("api.mode", api.mode ? "follows path" : "follows object", "\n"); 53 * post("api.id is", api.id, "\n"); 54 * post("api.path is", api.path, "\n"); 55 * post("api.children are", api.children, "\n"); 56 * post("api.getcount(\"devices\")", api.getcount("devices"), "\n"); 57 * 58 * api.property = "mute"; 59 * post("api.property is", api.property, "\n"); 60 * post("type of", api.property, "is", api.proptype, "\n"); 61 * 62 * function sample_callback(args){ 63 * post("callback called with arguments:", args, "\n"); 64 * } 65 * 66 */ 67 var LiveApi = Class.create(Maxobj, 68 /** @lends LiveApi.prototype */ 69 { 70 /** 71 *The id of the Live object referred to by the LiveAPI object. These ids are dynamic and awarded in realtime 72 *from the Live application, so should not be stored and used over multiple runs of Max for Live. 73 * 74 * @property id 75 * @type Number get/set 76 */ 77 id:0, 78 /** 79 * The path to the Live object referred to by the LiveAPI object. These paths are dependent on the currently 80 * open Set in Live, but are otherwise stable: live_set tracks 0 devices 0 will always refer to the first 81 * device of the first track of the open Live Set. 82 * 83 * @property id 84 * @type String get/set 85 */ 86 path:0, 87 /** 88 * An array of children of the object at the current path. 89 * @property id 90 * @type Array get 91 */ 92 children:0, 93 /** 94 * The follow mode of the LiveAPI object. 0 (default) means that LiveAPI follows the object referred to by 95 * the path, even if it is moved in the Live user interface. For instance, consider a Live Set with two tracks, 96 * "Track 1" and "Track 2", left and right respectively. If your LiveAPI object's path is live_set tracks 0, 97 * the left-most track, it will refer to "Track 1". Should the position of "Track 1" change, such that it is 98 * now to the right of "Track 2", the LiveAPI object continues to refer to "Track 1". A mode of 1 means that 99 * LiveAPI updates the followed object based on its location in the Live user interface. In the above example, 100 * the LiveAPI object would always refer to the left-most track, updating its id when the object at that 101 * position in the user interface changes. 102 * 103 * @property mode 104 * @type Number get/set 105 */ 106 mode:0, 107 /** 108 * The type of the object at the current path. Please see the 109 * <a href="http://cycling74.com/docs/max6/dynamic/c74_docs.html#live_api_overview" target="_maxref">Live API Overview</a> 110 * and 111 * <a href="http://cycling74.com/docs/max6/dynamic/c74_docs.html#live_object_model" target="_maxref">Live Object Model</a> 112 * documents for more information. 113 * 114 * @property type 115 * @type String get 116 */ 117 type:0, 118 /** 119 * A description of the object at the current path, including id, type, children, properties and functions. 120 * @property info 121 * @type String get 122 */ 123 info:0, 124 /** 125 * The observed property, child or child-list of the object at the current path, if desired. For instance, 126 * if the LiveAPI object refers to "live_set tracks 1", setting the property to "mute" would cause changes 127 * to the "mute" property of the 2nd track to be reported to the callback function defined in the LiveAPI Constructor. 128 * 129 * @property property 130 * @type String get/set 131 */ 132 property:0, 133 /** 134 * The type of the currently observed property or child. The types of the properties and children are given in the 135 * <a href="http://cycling74.com/docs/max6/dynamic/c74_docs.html#live_object_model" target="_maxref">Live Object Model</a>. 136 * @property proptype 137 * @type String get 138 */ 139 proptype:0, 140 /** 141 * The patcher of the LiveAPI object, as passed into the Constructor. 142 * @property patcher 143 * @type Patcher get 144 */ 145 patcher:0, 146 /** 147 * The count of children of the object at the current path, as specified by the child argument. 148 * 149 * @param {Object} child 150 * @type Integer 151 */ 152 getcount:function(child){}, 153 /** 154 * Navigates to the path and causes the id of the object at that path out be sent to the callback 155 * function defined in the Constructor. If there is no object at the path, id 0 is sent. 156 * 157 * @param {String} path 158 * @type void 159 */ 160 goto:function(path){}, 161 /** 162 * Returns the value or list of values of the specified property of the current object. 163 * 164 * @param {String} property 165 * @type mixed 166 */ 167 get:function(property){}, 168 /** 169 * Returns the value or list of values of the specified property of the current object as a String object. 170 * 171 * @param {String} property 172 * @type String 173 */ 174 getstring:function(property){}, 175 /** 176 * Sets the value or list of values of the specified property of the current object. 177 * 178 * @param {String} property 179 * @param {mixed} value 180 * @type void 181 */ 182 set:function(property, value){}, 183 /** 184 * Calls the given function of the current object, optionally with a list of arguments. 185 * 186 * @param {Function} callback 187 * @param {mixed} arguments 188 * @type void 189 */ 190 call:function(callback, arguments){} 191 192 } 193 ); 194 195 196