1 | /*
|
---|
2 | Copyright (c) 2003-2009, CKSource - Frederico Knabben. All rights reserved.
|
---|
3 | For licensing, see LICENSE.html or http://ckeditor.com/license
|
---|
4 | */
|
---|
5 |
|
---|
6 | /**
|
---|
7 | * @fileOverview Defines the {@link CKEDITOR.event} class, which serves as the
|
---|
8 | * base for classes and objects that require event handling features.
|
---|
9 | */
|
---|
10 |
|
---|
11 | if ( !CKEDITOR.event )
|
---|
12 | {
|
---|
13 | /**
|
---|
14 | * This is a base class for classes and objects that require event handling
|
---|
15 | * features.
|
---|
16 | * @constructor
|
---|
17 | * @example
|
---|
18 | */
|
---|
19 | CKEDITOR.event = function()
|
---|
20 | {};
|
---|
21 |
|
---|
22 | /**
|
---|
23 | * Implements the {@link CKEDITOR.event} features in an object.
|
---|
24 | * @param {Object} targetObject The object in which implement the features.
|
---|
25 | * @example
|
---|
26 | * var myObject = { message : 'Example' };
|
---|
27 | * <b>CKEDITOR.event.implementOn( myObject }</b>;
|
---|
28 | * myObject.on( 'testEvent', function()
|
---|
29 | * {
|
---|
30 | * alert( this.message ); // "Example"
|
---|
31 | * });
|
---|
32 | * myObject.fire( 'testEvent' );
|
---|
33 | */
|
---|
34 | CKEDITOR.event.implementOn = function( targetObject, isTargetPrototype )
|
---|
35 | {
|
---|
36 | var eventProto = CKEDITOR.event.prototype;
|
---|
37 |
|
---|
38 | for ( var prop in eventProto )
|
---|
39 | {
|
---|
40 | if ( targetObject[ prop ] == undefined )
|
---|
41 | targetObject[ prop ] = eventProto[ prop ];
|
---|
42 | }
|
---|
43 | };
|
---|
44 |
|
---|
45 | CKEDITOR.event.prototype = (function()
|
---|
46 | {
|
---|
47 | // Returns the private events object for a given object.
|
---|
48 | var getPrivate = function( obj )
|
---|
49 | {
|
---|
50 | var _ = ( obj.getPrivate && obj.getPrivate() ) || obj._ || ( obj._ = {} );
|
---|
51 | return _.events || ( _.events = {} );
|
---|
52 | };
|
---|
53 |
|
---|
54 | var eventEntry = function( eventName )
|
---|
55 | {
|
---|
56 | this.name = eventName;
|
---|
57 | this.listeners = [];
|
---|
58 | };
|
---|
59 |
|
---|
60 | eventEntry.prototype =
|
---|
61 | {
|
---|
62 | // Get the listener index for a specified function.
|
---|
63 | // Returns -1 if not found.
|
---|
64 | getListenerIndex : function( listenerFunction )
|
---|
65 | {
|
---|
66 | for ( var i = 0, listeners = this.listeners ; i < listeners.length ; i++ )
|
---|
67 | {
|
---|
68 | if ( listeners[i].fn == listenerFunction )
|
---|
69 | return i;
|
---|
70 | }
|
---|
71 | return -1;
|
---|
72 | }
|
---|
73 | };
|
---|
74 |
|
---|
75 | return /** @lends CKEDITOR.event.prototype */ {
|
---|
76 | /**
|
---|
77 | * Registers a listener to a specific event in the current object.
|
---|
78 | * @param {String} eventName The event name to which listen.
|
---|
79 | * @param {Function} listenerFunction The function listening to the
|
---|
80 | * event.
|
---|
81 | * @param {Object} [scopeObj] The object used to scope the listener
|
---|
82 | * call (the this object. If omitted, the current object is used.
|
---|
83 | * @param {Object} [listenerData] Data to be sent as the
|
---|
84 | * {@link CKEDITOR.eventInfo#listenerData} when calling the
|
---|
85 | * listener.
|
---|
86 | * @param {Number} [priority] The listener priority. Lower priority
|
---|
87 | * listeners are called first. Listeners with the same priority
|
---|
88 | * value are called in registration order. Defaults to 10.
|
---|
89 | * @example
|
---|
90 | * someObject.on( 'someEvent', function()
|
---|
91 | * {
|
---|
92 | * alert( this == someObject ); // "true"
|
---|
93 | * });
|
---|
94 | * @example
|
---|
95 | * someObject.on( 'someEvent', function()
|
---|
96 | * {
|
---|
97 | * alert( this == anotherObject ); // "true"
|
---|
98 | * }
|
---|
99 | * , anotherObject );
|
---|
100 | * @example
|
---|
101 | * someObject.on( 'someEvent', function( event )
|
---|
102 | * {
|
---|
103 | * alert( event.listenerData ); // "Example"
|
---|
104 | * }
|
---|
105 | * , null, 'Example' );
|
---|
106 | * @example
|
---|
107 | * someObject.on( 'someEvent', function() { ... } ); // 2nd called
|
---|
108 | * someObject.on( 'someEvent', function() { ... }, null, null, 100 ); // 3rd called
|
---|
109 | * someObject.on( 'someEvent', function() { ... }, null, null, 1 ); // 1st called
|
---|
110 | */
|
---|
111 | on : function( eventName, listenerFunction, scopeObj, listenerData, priority )
|
---|
112 | {
|
---|
113 | // Get the event entry (create it if needed).
|
---|
114 | var events = getPrivate( this ),
|
---|
115 | event = events[ eventName ] || ( events[ eventName ] = new eventEntry( eventName ) );
|
---|
116 |
|
---|
117 | if ( event.getListenerIndex( listenerFunction ) < 0 )
|
---|
118 | {
|
---|
119 | // Get the listeners.
|
---|
120 | var listeners = event.listeners;
|
---|
121 |
|
---|
122 | // Fill the scope.
|
---|
123 | if ( !scopeObj )
|
---|
124 | scopeObj = this;
|
---|
125 |
|
---|
126 | // Default the priority, if needed.
|
---|
127 | if ( isNaN( priority ) )
|
---|
128 | priority = 10;
|
---|
129 |
|
---|
130 | var me = this;
|
---|
131 |
|
---|
132 | // Create the function to be fired for this listener.
|
---|
133 | var listenerFirer = function( editor, publisherData, stopFn, cancelFn )
|
---|
134 | {
|
---|
135 | var ev =
|
---|
136 | {
|
---|
137 | name : eventName,
|
---|
138 | sender : this,
|
---|
139 | editor : editor,
|
---|
140 | data : publisherData,
|
---|
141 | listenerData : listenerData,
|
---|
142 | stop : stopFn,
|
---|
143 | cancel : cancelFn,
|
---|
144 | removeListener : function()
|
---|
145 | {
|
---|
146 | me.removeListener( eventName, listenerFunction );
|
---|
147 | }
|
---|
148 | };
|
---|
149 |
|
---|
150 | listenerFunction.call( scopeObj, ev );
|
---|
151 |
|
---|
152 | return ev.data;
|
---|
153 | };
|
---|
154 | listenerFirer.fn = listenerFunction;
|
---|
155 | listenerFirer.priority = priority;
|
---|
156 |
|
---|
157 | // Search for the right position for this new listener, based on its
|
---|
158 | // priority.
|
---|
159 | for ( var i = listeners.length - 1 ; i >= 0 ; i-- )
|
---|
160 | {
|
---|
161 | // Find the item which should be before the new one.
|
---|
162 | if ( listeners[ i ].priority <= priority )
|
---|
163 | {
|
---|
164 | // Insert the listener in the array.
|
---|
165 | listeners.splice( i + 1, 0, listenerFirer );
|
---|
166 | return;
|
---|
167 | }
|
---|
168 | }
|
---|
169 |
|
---|
170 | // If no position has been found (or zero length), put it in
|
---|
171 | // the front of list.
|
---|
172 | listeners.unshift( listenerFirer );
|
---|
173 | }
|
---|
174 | },
|
---|
175 |
|
---|
176 | /**
|
---|
177 | * Fires an specific event in the object. All registered listeners are
|
---|
178 | * called at this point.
|
---|
179 | * @function
|
---|
180 | * @param {String} eventName The event name to fire.
|
---|
181 | * @param {Object} [data] Data to be sent as the
|
---|
182 | * {@link CKEDITOR.eventInfo#data} when calling the
|
---|
183 | * listeners.
|
---|
184 | * @param {CKEDITOR.editor} [editor] The editor instance to send as the
|
---|
185 | * {@link CKEDITOR.eventInfo#editor} when calling the
|
---|
186 | * listener.
|
---|
187 | * @returns {Boolean|Object} A booloan indicating that the event is to be
|
---|
188 | * canceled, or data returned by one of the listeners.
|
---|
189 | * @example
|
---|
190 | * someObject.on( 'someEvent', function() { ... } );
|
---|
191 | * someObject.on( 'someEvent', function() { ... } );
|
---|
192 | * <b>someObject.fire( 'someEvent' )</b>; // both listeners are called
|
---|
193 | * @example
|
---|
194 | * someObject.on( 'someEvent', function( event )
|
---|
195 | * {
|
---|
196 | * alert( event.data ); // "Example"
|
---|
197 | * });
|
---|
198 | * <b>someObject.fire( 'someEvent', 'Example' )</b>;
|
---|
199 | */
|
---|
200 | fire : (function()
|
---|
201 | {
|
---|
202 | // Create the function that marks the event as stopped.
|
---|
203 | var stopped = false;
|
---|
204 | var stopEvent = function()
|
---|
205 | {
|
---|
206 | stopped = true;
|
---|
207 | };
|
---|
208 |
|
---|
209 | // Create the function that marks the event as canceled.
|
---|
210 | var canceled = false;
|
---|
211 | var cancelEvent = function()
|
---|
212 | {
|
---|
213 | canceled = true;
|
---|
214 | };
|
---|
215 |
|
---|
216 | return function( eventName, data, editor )
|
---|
217 | {
|
---|
218 | // Get the event entry.
|
---|
219 | var event = getPrivate( this )[ eventName ];
|
---|
220 |
|
---|
221 | // Save the previous stopped and cancelled states. We may
|
---|
222 | // be nesting fire() calls.
|
---|
223 | var previousStopped = stopped,
|
---|
224 | previousCancelled = canceled;
|
---|
225 |
|
---|
226 | // Reset the stopped and canceled flags.
|
---|
227 | stopped = canceled = false;
|
---|
228 |
|
---|
229 | if ( event )
|
---|
230 | {
|
---|
231 | var listeners = event.listeners;
|
---|
232 |
|
---|
233 | if ( listeners.length )
|
---|
234 | {
|
---|
235 | // As some listeners may remove themselves from the
|
---|
236 | // event, the original array length is dinamic. So,
|
---|
237 | // let's make a copy of all listeners, so we are
|
---|
238 | // sure we'll call all of them.
|
---|
239 | listeners = listeners.slice( 0 );
|
---|
240 |
|
---|
241 | // Loop through all listeners.
|
---|
242 | for ( var i = 0 ; i < listeners.length ; i++ )
|
---|
243 | {
|
---|
244 | // Call the listener, passing the event data.
|
---|
245 | var retData = listeners[i].call( this, editor, data, stopEvent, cancelEvent );
|
---|
246 |
|
---|
247 | if ( typeof retData != 'undefined' )
|
---|
248 | data = retData;
|
---|
249 |
|
---|
250 | // No further calls is stopped or canceled.
|
---|
251 | if ( stopped || canceled )
|
---|
252 | break;
|
---|
253 | }
|
---|
254 | }
|
---|
255 | }
|
---|
256 |
|
---|
257 | var ret = canceled || ( typeof data == 'undefined' ? false : data );
|
---|
258 |
|
---|
259 | // Restore the previous stopped and canceled states.
|
---|
260 | stopped = previousStopped;
|
---|
261 | canceled = previousCancelled;
|
---|
262 |
|
---|
263 | return ret;
|
---|
264 | };
|
---|
265 | })(),
|
---|
266 |
|
---|
267 | /**
|
---|
268 | * Fires an specific event in the object, releasing all listeners
|
---|
269 | * registered to that event. The same listeners are not called again on
|
---|
270 | * successive calls of it or of {@link #fire}.
|
---|
271 | * @param {String} eventName The event name to fire.
|
---|
272 | * @param {Object} [data] Data to be sent as the
|
---|
273 | * {@link CKEDITOR.eventInfo#data} when calling the
|
---|
274 | * listeners.
|
---|
275 | * @param {CKEDITOR.editor} [editor] The editor instance to send as the
|
---|
276 | * {@link CKEDITOR.eventInfo#editor} when calling the
|
---|
277 | * listener.
|
---|
278 | * @returns {Boolean|Object} A booloan indicating that the event is to be
|
---|
279 | * canceled, or data returned by one of the listeners.
|
---|
280 | * @example
|
---|
281 | * someObject.on( 'someEvent', function() { ... } );
|
---|
282 | * someObject.fire( 'someEvent' ); // above listener called
|
---|
283 | * <b>someObject.fireOnce( 'someEvent' )</b>; // above listener called
|
---|
284 | * someObject.fire( 'someEvent' ); // no listeners called
|
---|
285 | */
|
---|
286 | fireOnce : function( eventName, data, editor )
|
---|
287 | {
|
---|
288 | var ret = this.fire( eventName, data, editor );
|
---|
289 | delete getPrivate( this )[ eventName ];
|
---|
290 | return ret;
|
---|
291 | },
|
---|
292 |
|
---|
293 | /**
|
---|
294 | * Unregisters a listener function from being called at the specified
|
---|
295 | * event. No errors are thrown if the listener has not been
|
---|
296 | * registered previously.
|
---|
297 | * @param {String} eventName The event name.
|
---|
298 | * @param {Function} listenerFunction The listener function to unregister.
|
---|
299 | * @example
|
---|
300 | * var myListener = function() { ... };
|
---|
301 | * someObject.on( 'someEvent', myListener );
|
---|
302 | * someObject.fire( 'someEvent' ); // myListener called
|
---|
303 | * <b>someObject.removeListener( 'someEvent', myListener )</b>;
|
---|
304 | * someObject.fire( 'someEvent' ); // myListener not called
|
---|
305 | */
|
---|
306 | removeListener : function( eventName, listenerFunction )
|
---|
307 | {
|
---|
308 | // Get the event entry.
|
---|
309 | var event = getPrivate( this )[ eventName ];
|
---|
310 |
|
---|
311 | if ( event )
|
---|
312 | {
|
---|
313 | var index = event.getListenerIndex( listenerFunction );
|
---|
314 | if ( index >= 0 )
|
---|
315 | event.listeners.splice( index, 1 );
|
---|
316 | }
|
---|
317 | },
|
---|
318 |
|
---|
319 | /**
|
---|
320 | * Checks if there is any listener registered to a given event.
|
---|
321 | * @param {String} eventName The event name.
|
---|
322 | * @example
|
---|
323 | * var myListener = function() { ... };
|
---|
324 | * someObject.on( 'someEvent', myListener );
|
---|
325 | * alert( someObject.<b>hasListeners( 'someEvent' )</b> ); // "true"
|
---|
326 | * alert( someObject.<b>hasListeners( 'noEvent' )</b> ); // "false"
|
---|
327 | */
|
---|
328 | hasListeners : function( eventName )
|
---|
329 | {
|
---|
330 | var event = getPrivate( this )[ eventName ];
|
---|
331 | return ( event && event.listeners.length > 0 ) ;
|
---|
332 | }
|
---|
333 | };
|
---|
334 | })();
|
---|
335 | }
|
---|