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