]>
git.wh0rd.org - tt-rss.git/blob - lib/dojo/_base/connect.js
2 Copyright (c) 2004-2010, The Dojo Foundation All Rights Reserved.
3 Available via Academic Free License >= 2.1 OR the modified BSD license.
4 see: http://dojotoolkit.org/license for details
8 if(!dojo
._hasResource
["dojo._base.connect"]){ //_hasResource checks added by build. Do not use _hasResource directly in your code.
9 dojo
._hasResource
["dojo._base.connect"] = true;
10 dojo
.provide("dojo._base.connect");
11 dojo
.require("dojo._base.lang");
13 // this file courtesy of the TurboAjax Group, licensed under a Dojo CLA
15 // low-level delegation machinery
17 // create a dispatcher function
18 getDispatcher: function(){
19 // following comments pulled out-of-line to prevent cloning them
20 // in the returned function.
21 // - indices (i) that are really in the array of listeners (ls) will
22 // not be in Array.prototype. This is the 'sparse array' trick
23 // that keeps us safe from libs that take liberties with built-in
25 // - listener is invoked with current scope (this)
27 var ap
=Array
.prototype, c
=arguments
.callee
, ls
=c
._listeners
, t
=c
.target
;
28 // return value comes from original target function
29 var r
= t
&& t
.apply(this, arguments
);
30 // make local copy of listener array so it is immutable during processing
34 // invoke listeners after target function
37 lls
[i
].apply(this, arguments
);
40 // return value comes from original target function
44 // add a listener to an object
45 add: function(/*Object*/ source
, /*String*/ method
, /*Function*/ listener
){
46 // Whenever 'method' is invoked, 'listener' will have the same scope.
47 // Trying to supporting a context object for the listener led to
49 // Non trivial to provide 'once' functionality here
50 // because listener could be the result of a dojo.hitch call,
51 // in which case two references to the same hitch target would not
53 source
= source
|| dojo
.global
;
54 // The source method is either null, a dispatcher, or some other function
55 var f
= source
[method
];
56 // Ensure a dispatcher
57 if(!f
|| !f
._listeners
){
58 var d
= dojo
._listener
.getDispatcher();
59 // original target function is special
61 // dispatcher holds a list of listeners
63 // redirect source to dispatcher
64 f
= source
[method
] = d
;
66 // The contract is that a handle is returned that can
67 // identify this listener for disconnect.
69 // The type of the handle is private. Here is it implemented as Integer.
70 // DOM event code has this same contract but handle is Function
71 // in non-IE browsers.
73 // We could have separate lists of before and after listeners.
74 return f
._listeners
.push(listener
); /*Handle*/
76 // remove a listener from an object
77 remove: function(/*Object*/ source
, /*String*/ method
, /*Handle*/ handle
){
78 var f
= (source
|| dojo
.global
)[method
];
79 // remember that handle is the index+1 (0 is not a valid handle)
80 if(f
&& f
._listeners
&& handle
--){
81 delete f
._listeners
[handle
];
86 // Multiple delegation for arbitrary methods.
88 // This unit knows nothing about DOM, but we include DOM aware documentation
89 // and dontFix argument here to help the autodocs. Actual DOM aware code is in
92 dojo
.connect = function(/*Object|null*/ obj
,
94 /*Object|null*/ context
,
95 /*String|Function*/ method
,
96 /*Boolean?*/ dontFix
){
98 // `dojo.connect` is the core event handling and delegation method in
99 // Dojo. It allows one function to "listen in" on the execution of
100 // any other, triggering the second whenever the first is called. Many
101 // listeners may be attached to a function, and source functions may
102 // be either regular function calls or DOM events.
105 // Connects listeners to actions, so that after event fires, a
106 // listener is called with the same arguments passed to the original
109 // Since `dojo.connect` allows the source of events to be either a
110 // "regular" JavaScript function or a DOM event, it provides a uniform
111 // interface for listening to all the types of events that an
112 // application is likely to deal with though a single, unified
113 // interface. DOM programmers may want to think of it as
114 // "addEventListener for everything and anything".
116 // When setting up a connection, the `event` parameter must be a
117 // string that is the name of the method/event to be listened for. If
118 // `obj` is null, `dojo.global` is assumed, meaning that connections
119 // to global methods are supported but also that you may inadvertently
120 // connect to a global by passing an incorrect object name or invalid
123 // `dojo.connect` generally is forgiving. If you pass the name of a
124 // function or method that does not yet exist on `obj`, connect will
125 // not fail, but will instead set up a stub method. Similarly, null
126 // arguments may simply be omitted such that fewer than 4 arguments
127 // may be required to set up a connection See the examples for details.
129 // The return value is a handle that is needed to
130 // remove this connection with `dojo.disconnect`.
133 // The source object for the event function.
134 // Defaults to `dojo.global` if null.
135 // If obj is a DOM node, the connection is delegated
136 // to the DOM event manager (unless dontFix is true).
139 // String name of the event function in obj.
140 // I.e. identifies a property `obj[event]`.
143 // The object that method will receive as "this".
145 // If context is null and method is a function, then method
146 // inherits the context of event.
148 // If method is a string then context must be the source
149 // object object for method (context[method]). If context is null,
150 // dojo.global is used.
153 // A function reference, or name of a function in context.
154 // The function identified by method fires after event does.
155 // method receives the same arguments as the event.
156 // See context argument comments for information on method's scope.
159 // If obj is a DOM node, set dontFix to true to prevent delegation
160 // of this connection to the DOM event manager.
163 // When obj.onchange(), do ui.update():
164 // | dojo.connect(obj, "onchange", ui, "update");
165 // | dojo.connect(obj, "onchange", ui, ui.update); // same
168 // Using return value for disconnect:
169 // | var link = dojo.connect(obj, "onchange", ui, "update");
171 // | dojo.disconnect(link);
174 // When onglobalevent executes, watcher.handler is invoked:
175 // | dojo.connect(null, "onglobalevent", watcher, "handler");
178 // When ob.onCustomEvent executes, customEventHandler is invoked:
179 // | dojo.connect(ob, "onCustomEvent", null, "customEventHandler");
180 // | dojo.connect(ob, "onCustomEvent", "customEventHandler"); // same
183 // When ob.onCustomEvent executes, customEventHandler is invoked
184 // with the same scope (this):
185 // | dojo.connect(ob, "onCustomEvent", null, customEventHandler);
186 // | dojo.connect(ob, "onCustomEvent", customEventHandler); // same
189 // When globalEvent executes, globalHandler is invoked
190 // with the same scope (this):
191 // | dojo.connect(null, "globalEvent", null, globalHandler);
192 // | dojo.connect("globalEvent", globalHandler); // same
194 // normalize arguments
195 var a
=arguments
, args
=[], i
=0;
196 // if a[0] is a String, obj was omitted
197 args
.push(dojo
.isString(a
[0]) ? null : a
[i
++], a
[i
++]);
198 // if the arg-after-next is a String or Function, context was NOT omitted
200 args
.push(dojo
.isString(a1
)||dojo
.isFunction(a1
) ? a
[i
++] : null, a
[i
++]);
201 // absorb any additional arguments
202 for(var l
=a
.length
; i
<l
; i
++){ args
.push(a
[i
]); }
203 // do the actual work
204 return dojo
._connect
.apply(this, args
); /*Handle*/
207 // used by non-browser hostenvs. always overriden by event.js
208 dojo
._connect = function(obj
, event
, context
, method
){
209 var l
=dojo
._listener
, h
=l
.add(obj
, event
, dojo
.hitch(context
, method
));
210 return [obj
, event
, h
, l
]; // Handle
213 dojo
.disconnect = function(/*Handle*/ handle
){
215 // Remove a link created by dojo.connect.
217 // Removes the connection between event and the method referenced by handle.
219 // the return value of the dojo.connect call that created the connection.
220 if(handle
&& handle
[0] !== undefined){
221 dojo
._disconnect
.apply(this, handle
);
222 // let's not keep this reference
227 dojo
._disconnect = function(obj
, event
, handle
, listener
){
228 listener
.remove(obj
, event
, handle
);
231 // topic publish/subscribe
235 dojo
.subscribe = function(/*String*/ topic
, /*Object|null*/ context
, /*String|Function*/ method
){
237 // Attach a listener to a named topic. The listener function is invoked whenever the
238 // named topic is published (see: dojo.publish).
239 // Returns a handle which is needed to unsubscribe this listener.
241 // Scope in which method will be invoked, or null for default scope.
243 // The name of a function in context, or a function reference. This is the function that
244 // is invoked when topic is published.
246 // | dojo.subscribe("alerts", null, function(caption, message){ alert(caption + "\n" + message); });
247 // | dojo.publish("alerts", [ "read this", "hello world" ]);
249 // support for 2 argument invocation (omitting context) depends on hitch
250 return [topic
, dojo
._listener
.add(dojo
._topics
, topic
, dojo
.hitch(context
, method
))]; /*Handle*/
253 dojo
.unsubscribe = function(/*Handle*/ handle
){
255 // Remove a topic listener.
257 // The handle returned from a call to subscribe.
259 // | var alerter = dojo.subscribe("alerts", null, function(caption, message){ alert(caption + "\n" + message); };
261 // | dojo.unsubscribe(alerter);
263 dojo
._listener
.remove(dojo
._topics
, handle
[0], handle
[1]);
267 dojo
.publish = function(/*String*/ topic
, /*Array*/ args
){
269 // Invoke all listener method subscribed to topic.
271 // The name of the topic to publish.
273 // An array of arguments. The arguments will be applied
274 // to each topic subscriber (as first class parameters, via apply).
276 // | dojo.subscribe("alerts", null, function(caption, message){ alert(caption + "\n" + message); };
277 // | dojo.publish("alerts", [ "read this", "hello world" ]);
279 // Note that args is an array, which is more efficient vs variable length
280 // argument list. Ideally, var args would be implemented via Array
281 // throughout the APIs.
282 var f
= dojo
._topics
[topic
];
284 f
.apply(this, args
||[]);
288 dojo
.connectPublisher = function( /*String*/ topic
,
292 // Ensure that every time obj.event() is called, a message is published
293 // on the topic. Returns a handle which can be passed to
294 // dojo.disconnect() to disable subsequent automatic publication on
297 // The name of the topic to publish.
299 // The source object for the event function. Defaults to dojo.global
302 // The name of the event function in obj.
303 // I.e. identifies a property obj[event].
305 // | dojo.connectPublisher("/ajax/start", dojo, "xhrGet");
306 var pf = function(){ dojo
.publish(topic
, arguments
); }
307 return event
? dojo
.connect(obj
, event
, pf
) : dojo
.connect(obj
, pf
); //Handle