1 if(!dojo._hasResource["dojo._base.connect"]){ //_hasResource checks added by build. Do not use _hasResource directly in your code.
2 dojo._hasResource["dojo._base.connect"] = true;
3 dojo.provide("dojo._base.connect");
4 dojo.require("dojo._base.lang");
6 // this file courtesy of the TurboAjax Group, licensed under a Dojo CLA
8 // low-level delegation machinery
10 // create a dispatcher function
11 getDispatcher: function(){
12 // following comments pulled out-of-line to prevent cloning them
13 // in the returned function.
14 // - indices (i) that are really in the array of listeners (ls) will
15 // not be in Array.prototype. This is the 'sparse array' trick
16 // that keeps us safe from libs that take liberties with built-in
18 // - listener is invoked with current scope (this)
20 var ap=Array.prototype, c=arguments.callee, ls=c._listeners, t=c.target;
21 // return value comes from original target function
22 var r=t && t.apply(this, arguments);
23 // invoke listeners after target function
26 ls[i].apply(this, arguments);
29 // return value comes from original target function
33 // add a listener to an object
34 add: function(/*Object*/ source, /*String*/ method, /*Function*/ listener){
35 // Whenever 'method' is invoked, 'listener' will have the same scope.
36 // Trying to supporting a context object for the listener led to
38 // Non trivial to provide 'once' functionality here
39 // because listener could be the result of a dojo.hitch call,
40 // in which case two references to the same hitch target would not
42 source = source || dojo.global;
43 // The source method is either null, a dispatcher, or some other function
44 var f = source[method];
45 // Ensure a dispatcher
46 if(!f||!f._listeners){
47 var d = dojo._listener.getDispatcher();
48 // original target function is special
50 // dispatcher holds a list of listeners
52 // redirect source to dispatcher
53 f = source[method] = d;
55 // The contract is that a handle is returned that can
56 // identify this listener for disconnect.
58 // The type of the handle is private. Here is it implemented as Integer.
59 // DOM event code has this same contract but handle is Function
60 // in non-IE browsers.
62 // We could have separate lists of before and after listeners.
63 return f._listeners.push(listener) ; /*Handle*/
65 // remove a listener from an object
66 remove: function(/*Object*/ source, /*String*/ method, /*Handle*/ handle){
67 var f = (source||dojo.global)[method];
68 // remember that handle is the index+1 (0 is not a valid handle)
69 if(f && f._listeners && handle--){
70 delete f._listeners[handle];
75 // Multiple delegation for arbitrary methods.
77 // This unit knows nothing about DOM,
78 // but we include DOM aware
79 // documentation and dontFix
80 // argument here to help the autodocs.
81 // Actual DOM aware code is in event.js.
83 dojo.connect = function(/*Object|null*/ obj,
85 /*Object|null*/ context,
86 /*String|Function*/ method,
89 // Create a link that calls one function when another executes.
92 // Connects method to event, so that after event fires, method
93 // does too. All connected functions are passed the same arguments as
94 // the event function was initially called with. You may connect as
95 // many methods to event as needed.
97 // event must be a string. If obj is null, dojo.global is used.
99 // null arguments may simply be omitted.
101 // obj[event] can resolve to a function or undefined (null).
102 // If obj[event] is null, it is assigned a function.
104 // The return value is a handle that is needed to
105 // remove this connection with dojo.disconnect.
108 // The source object for the event function.
109 // Defaults to dojo.global if null.
110 // If obj is a DOM node, the connection is delegated
111 // to the DOM event manager (unless dontFix is true).
114 // String name of the event function in obj.
115 // I.e. identifies a property obj[event].
118 // The object that method will receive as "this".
120 // If context is null and method is a function, then method
121 // inherits the context of event.
123 // If method is a string then context must be the source
124 // object object for method (context[method]). If context is null,
125 // dojo.global is used.
128 // A function reference, or name of a function in context.
129 // The function identified by method fires after event does.
130 // method receives the same arguments as the event.
131 // See context argument comments for information on method's scope.
134 // If obj is a DOM node, set dontFix to true to prevent delegation
135 // of this connection to the DOM event manager.
138 // When obj.onchange(), do ui.update():
139 // | dojo.connect(obj, "onchange", ui, "update");
140 // | dojo.connect(obj, "onchange", ui, ui.update); // same
143 // Using return value for disconnect:
144 // | var link = dojo.connect(obj, "onchange", ui, "update");
146 // | dojo.disconnect(link);
149 // When onglobalevent executes, watcher.handler is invoked:
150 // | dojo.connect(null, "onglobalevent", watcher, "handler");
153 // When ob.onCustomEvent executes, customEventHandler is invoked:
154 // | dojo.connect(ob, "onCustomEvent", null, "customEventHandler");
155 // | dojo.connect(ob, "onCustomEvent", "customEventHandler"); // same
158 // When ob.onCustomEvent executes, customEventHandler is invoked
159 // with the same scope (this):
160 // | dojo.connect(ob, "onCustomEvent", null, customEventHandler);
161 // | dojo.connect(ob, "onCustomEvent", customEventHandler); // same
164 // When globalEvent executes, globalHandler is invoked
165 // with the same scope (this):
166 // | dojo.connect(null, "globalEvent", null, globalHandler);
167 // | dojo.connect("globalEvent", globalHandler); // same
169 // normalize arguments
170 var a=arguments, args=[], i=0;
171 // if a[0] is a String, obj was ommited
172 args.push(dojo.isString(a[0]) ? null : a[i++], a[i++]);
173 // if the arg-after-next is a String or Function, context was NOT omitted
175 args.push(dojo.isString(a1)||dojo.isFunction(a1) ? a[i++] : null, a[i++]);
176 // absorb any additional arguments
177 for(var l=a.length; i<l; i++){ args.push(a[i]); }
178 // do the actual work
179 return dojo._connect.apply(this, args); /*Handle*/
182 // used by non-browser hostenvs. always overriden by event.js
183 dojo._connect = function(obj, event, context, method){
184 var l=dojo._listener, h=l.add(obj, event, dojo.hitch(context, method));
185 return [obj, event, h, l]; // Handle
188 dojo.disconnect = function(/*Handle*/ handle){
190 // Remove a link created by dojo.connect.
192 // Removes the connection between event and the method referenced by handle.
194 // the return value of the dojo.connect call that created the connection.
195 if(handle && handle[0] !== undefined){
196 dojo._disconnect.apply(this, handle);
197 // let's not keep this reference
202 dojo._disconnect = function(obj, event, handle, listener){
203 listener.remove(obj, event, handle);
206 // topic publish/subscribe
210 dojo.subscribe = function(/*String*/ topic, /*Object|null*/ context, /*String|Function*/ method){
212 // Attach a listener to a named topic. The listener function is invoked whenever the
213 // named topic is published (see: dojo.publish).
214 // Returns a handle which is needed to unsubscribe this listener.
216 // Scope in which method will be invoked, or null for default scope.
218 // The name of a function in context, or a function reference. This is the function that
219 // is invoked when topic is published.
221 // | dojo.subscribe("alerts", null, function(caption, message){ alert(caption + "\n" + message); };
222 // | dojo.publish("alerts", [ "read this", "hello world" ]);
224 // support for 2 argument invocation (omitting context) depends on hitch
225 return [topic, dojo._listener.add(dojo._topics, topic, dojo.hitch(context, method))]; /*Handle*/
228 dojo.unsubscribe = function(/*Handle*/ handle){
230 // Remove a topic listener.
232 // The handle returned from a call to subscribe.
234 // | var alerter = dojo.subscribe("alerts", null, function(caption, message){ alert(caption + "\n" + message); };
236 // | dojo.unsubscribe(alerter);
238 dojo._listener.remove(dojo._topics, handle[0], handle[1]);
242 dojo.publish = function(/*String*/ topic, /*Array*/ args){
244 // Invoke all listener method subscribed to topic.
246 // The name of the topic to publish.
248 // An array of arguments. The arguments will be applied
249 // to each topic subscriber (as first class parameters, via apply).
251 // | dojo.subscribe("alerts", null, function(caption, message){ alert(caption + "\n" + message); };
252 // | dojo.publish("alerts", [ "read this", "hello world" ]);
254 // Note that args is an array, which is more efficient vs variable length
255 // argument list. Ideally, var args would be implemented via Array
256 // throughout the APIs.
257 var f = dojo._topics[topic];
259 f.apply(this, args||[]);
263 dojo.connectPublisher = function( /*String*/ topic,
267 // Ensure that everytime obj.event() is called, a message is published
268 // on the topic. Returns a handle which can be passed to
269 // dojo.disconnect() to disable subsequent automatic publication on
272 // The name of the topic to publish.
274 // The source object for the event function. Defaults to dojo.global
277 // The name of the event function in obj.
278 // I.e. identifies a property obj[event].
280 // | dojo.connectPublisher("/ajax/start", dojo, "xhrGet"};
281 var pf = function(){ dojo.publish(topic, arguments); }
282 return (event) ? dojo.connect(obj, event, pf) : dojo.connect(obj, pf); //Handle