]>
git.wh0rd.org - tt-rss.git/blob - lib/dojo/_base/connect.js
7e8006221f810cf0c2d7b90379c040a88b8f83e7
2 Copyright (c) 2004-2011, 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");
14 // this file courtesy of the TurboAjax Group, licensed under a Dojo CLA
16 // low-level delegation machinery
18 // create a dispatcher function
19 getDispatcher: function(){
20 // following comments pulled out-of-line to prevent cloning them
21 // in the returned function.
22 // - indices (i) that are really in the array of listeners (ls) will
23 // not be in Array.prototype. This is the 'sparse array' trick
24 // that keeps us safe from libs that take liberties with built-in
26 // - listener is invoked with current scope (this)
28 var ap
= Array
.prototype, c
= arguments
.callee
, ls
= c
._listeners
, t
= c
.target
,
29 // return value comes from original target function
30 r
= t
&& t
.apply(this, arguments
),
31 // make local copy of listener array so it is immutable during processing
32 i
, lls
= [].concat(ls
)
35 // invoke listeners after target function
38 lls
[i
].apply(this, arguments
);
41 // return value comes from original target function
45 // add a listener to an object
46 add: function(/*Object*/ source
, /*String*/ method
, /*Function*/ listener
){
47 // Whenever 'method' is invoked, 'listener' will have the same scope.
48 // Trying to supporting a context object for the listener led to
50 // Non trivial to provide 'once' functionality here
51 // because listener could be the result of a dojo.hitch call,
52 // in which case two references to the same hitch target would not
54 source
= source
|| dojo
.global
;
55 // The source method is either null, a dispatcher, or some other function
56 var f
= source
[method
];
57 // Ensure a dispatcher
58 if(!f
|| !f
._listeners
){
59 var d
= dojo
._listener
.getDispatcher();
60 // original target function is special
62 // dispatcher holds a list of listeners
64 // redirect source to dispatcher
65 f
= source
[method
] = d
;
67 // The contract is that a handle is returned that can
68 // identify this listener for disconnect.
70 // The type of the handle is private. Here is it implemented as Integer.
71 // DOM event code has this same contract but handle is Function
72 // in non-IE browsers.
74 // We could have separate lists of before and after listeners.
75 return f
._listeners
.push(listener
); /*Handle*/
77 // remove a listener from an object
78 remove: function(/*Object*/ source
, /*String*/ method
, /*Handle*/ handle
){
79 var f
= (source
|| dojo
.global
)[method
];
80 // remember that handle is the index+1 (0 is not a valid handle)
81 if(f
&& f
._listeners
&& handle
--){
82 delete f
._listeners
[handle
];
87 // Multiple delegation for arbitrary methods.
89 // This unit knows nothing about DOM, but we include DOM aware documentation
90 // and dontFix argument here to help the autodocs. Actual DOM aware code is in
93 dojo
.connect = function(/*Object|null*/ obj
,
95 /*Object|null*/ context
,
96 /*String|Function*/ method
,
97 /*Boolean?*/ dontFix
){
99 // `dojo.connect` is the core event handling and delegation method in
100 // Dojo. It allows one function to "listen in" on the execution of
101 // any other, triggering the second whenever the first is called. Many
102 // listeners may be attached to a function, and source functions may
103 // be either regular function calls or DOM events.
106 // Connects listeners to actions, so that after event fires, a
107 // listener is called with the same arguments passed to the original
110 // Since `dojo.connect` allows the source of events to be either a
111 // "regular" JavaScript function or a DOM event, it provides a uniform
112 // interface for listening to all the types of events that an
113 // application is likely to deal with though a single, unified
114 // interface. DOM programmers may want to think of it as
115 // "addEventListener for everything and anything".
117 // When setting up a connection, the `event` parameter must be a
118 // string that is the name of the method/event to be listened for. If
119 // `obj` is null, `dojo.global` is assumed, meaning that connections
120 // to global methods are supported but also that you may inadvertently
121 // connect to a global by passing an incorrect object name or invalid
124 // `dojo.connect` generally is forgiving. If you pass the name of a
125 // function or method that does not yet exist on `obj`, connect will
126 // not fail, but will instead set up a stub method. Similarly, null
127 // arguments may simply be omitted such that fewer than 4 arguments
128 // may be required to set up a connection See the examples for details.
130 // The return value is a handle that is needed to
131 // remove this connection with `dojo.disconnect`.
134 // The source object for the event function.
135 // Defaults to `dojo.global` if null.
136 // If obj is a DOM node, the connection is delegated
137 // to the DOM event manager (unless dontFix is true).
140 // String name of the event function in obj.
141 // I.e. identifies a property `obj[event]`.
144 // The object that method will receive as "this".
146 // If context is null and method is a function, then method
147 // inherits the context of event.
149 // If method is a string then context must be the source
150 // object object for method (context[method]). If context is null,
151 // dojo.global is used.
154 // A function reference, or name of a function in context.
155 // The function identified by method fires after event does.
156 // method receives the same arguments as the event.
157 // See context argument comments for information on method's scope.
160 // If obj is a DOM node, set dontFix to true to prevent delegation
161 // of this connection to the DOM event manager.
164 // When obj.onchange(), do ui.update():
165 // | dojo.connect(obj, "onchange", ui, "update");
166 // | dojo.connect(obj, "onchange", ui, ui.update); // same
169 // Using return value for disconnect:
170 // | var link = dojo.connect(obj, "onchange", ui, "update");
172 // | dojo.disconnect(link);
175 // When onglobalevent executes, watcher.handler is invoked:
176 // | dojo.connect(null, "onglobalevent", watcher, "handler");
179 // When ob.onCustomEvent executes, customEventHandler is invoked:
180 // | dojo.connect(ob, "onCustomEvent", null, "customEventHandler");
181 // | dojo.connect(ob, "onCustomEvent", "customEventHandler"); // same
184 // When ob.onCustomEvent executes, customEventHandler is invoked
185 // with the same scope (this):
186 // | dojo.connect(ob, "onCustomEvent", null, customEventHandler);
187 // | dojo.connect(ob, "onCustomEvent", customEventHandler); // same
190 // When globalEvent executes, globalHandler is invoked
191 // with the same scope (this):
192 // | dojo.connect(null, "globalEvent", null, globalHandler);
193 // | dojo.connect("globalEvent", globalHandler); // same
195 // normalize arguments
196 var a
=arguments
, args
=[], i
=0;
197 // if a[0] is a String, obj was omitted
198 args
.push(dojo
.isString(a
[0]) ? null : a
[i
++], a
[i
++]);
199 // if the arg-after-next is a String or Function, context was NOT omitted
201 args
.push(dojo
.isString(a1
)||dojo
.isFunction(a1
) ? a
[i
++] : null, a
[i
++]);
202 // absorb any additional arguments
203 for(var l
=a
.length
; i
<l
; i
++){ args
.push(a
[i
]); }
204 // do the actual work
205 return dojo
._connect
.apply(this, args
); /*Handle*/
208 // used by non-browser hostenvs. always overriden by event.js
209 dojo
._connect = function(obj
, event
, context
, method
){
210 var l
=dojo
._listener
, h
=l
.add(obj
, event
, dojo
.hitch(context
, method
));
211 return [obj
, event
, h
, l
]; // Handle
214 dojo
.disconnect = function(/*Handle*/ handle
){
216 // Remove a link created by dojo.connect.
218 // Removes the connection between event and the method referenced by handle.
220 // the return value of the dojo.connect call that created the connection.
221 if(handle
&& handle
[0] !== undefined){
222 dojo
._disconnect
.apply(this, handle
);
223 // let's not keep this reference
228 dojo
._disconnect = function(obj
, event
, handle
, listener
){
229 listener
.remove(obj
, event
, handle
);
232 // topic publish/subscribe
236 dojo
.subscribe = function(/*String*/ topic
, /*Object|null*/ context
, /*String|Function*/ method
){
238 // Attach a listener to a named topic. The listener function is invoked whenever the
239 // named topic is published (see: dojo.publish).
240 // Returns a handle which is needed to unsubscribe this listener.
242 // Scope in which method will be invoked, or null for default scope.
244 // The name of a function in context, or a function reference. This is the function that
245 // is invoked when topic is published.
247 // | dojo.subscribe("alerts", null, function(caption, message){ alert(caption + "\n" + message); });
248 // | dojo.publish("alerts", [ "read this", "hello world" ]);
250 // support for 2 argument invocation (omitting context) depends on hitch
251 return [topic
, dojo
._listener
.add(dojo
._topics
, topic
, dojo
.hitch(context
, method
))]; /*Handle*/
254 dojo
.unsubscribe = function(/*Handle*/ handle
){
256 // Remove a topic listener.
258 // The handle returned from a call to subscribe.
260 // | var alerter = dojo.subscribe("alerts", null, function(caption, message){ alert(caption + "\n" + message); };
262 // | dojo.unsubscribe(alerter);
264 dojo
._listener
.remove(dojo
._topics
, handle
[0], handle
[1]);
268 dojo
.publish = function(/*String*/ topic
, /*Array*/ args
){
270 // Invoke all listener method subscribed to topic.
272 // The name of the topic to publish.
274 // An array of arguments. The arguments will be applied
275 // to each topic subscriber (as first class parameters, via apply).
277 // | dojo.subscribe("alerts", null, function(caption, message){ alert(caption + "\n" + message); };
278 // | dojo.publish("alerts", [ "read this", "hello world" ]);
280 // Note that args is an array, which is more efficient vs variable length
281 // argument list. Ideally, var args would be implemented via Array
282 // throughout the APIs.
283 var f
= dojo
._topics
[topic
];
285 f
.apply(this, args
||[]);
289 dojo
.connectPublisher = function( /*String*/ topic
,
293 // Ensure that every time obj.event() is called, a message is published
294 // on the topic. Returns a handle which can be passed to
295 // dojo.disconnect() to disable subsequent automatic publication on
298 // The name of the topic to publish.
300 // The source object for the event function. Defaults to dojo.global
303 // The name of the event function in obj.
304 // I.e. identifies a property obj[event].
306 // | dojo.connectPublisher("/ajax/start", dojo, "xhrGet");
307 var pf = function(){ dojo
.publish(topic
, arguments
); }
308 return event
? dojo
.connect(obj
, event
, pf
) : dojo
.connect(obj
, pf
); //Handle