1 /*
  2 Copyright (c) 2003-2012, CKSource - Frederico Knabben. All rights reserved.
  3 For licensing, see LICENSE.html or http://ckeditor.com/license
  4 */
  5 
  6 /**
  7  * @fileOverview Defines the "virtual" {@link CKEDITOR.eventInfo} class, which
  8  *		contains the defintions of the event object passed to event listeners.
  9  *		This file is for documentation purposes only.
 10  */
 11 
 12 /**
 13  * (Virtual Class) Do not call this constructor. This class is not really part
 14  * of the API.
 15  * @class Virtual class that illustrates the features of the event object to be
 16  * passed to event listeners by a {@link CKEDITOR.event} based object.
 17  * @name CKEDITOR.eventInfo
 18  * @example
 19  * // Do not do this.
 20  * var myEvent = new CKEDITOR.eventInfo();  // Error: CKEDITOR.eventInfo is undefined
 21  */
 22 
 23 /**
 24  * The event name.
 25  * @name CKEDITOR.eventInfo.prototype.name
 26  * @field
 27  * @type String
 28  * @example
 29  * someObject.on( 'someEvent', function( event )
 30  *     {
 31  *         alert( <b>event.name</b> );  // "someEvent"
 32  *     });
 33  * someObject.fire( 'someEvent' );
 34  */
 35 
 36 /**
 37  * The object that publishes (sends) the event.
 38  * @name CKEDITOR.eventInfo.prototype.sender
 39  * @field
 40  * @type Object
 41  * @example
 42  * someObject.on( 'someEvent', function( event )
 43  *     {
 44  *         alert( <b>event.sender</b> == someObject );  // "true"
 45  *     });
 46  * someObject.fire( 'someEvent' );
 47  */
 48 
 49 /**
 50  * The editor instance that holds the sender. May be the same as sender. May be
 51  * null if the sender is not part of an editor instance, like a component
 52  * running in standalone mode.
 53  * @name CKEDITOR.eventInfo.prototype.editor
 54  * @field
 55  * @type CKEDITOR.editor
 56  * @example
 57  * myButton.on( 'someEvent', function( event )
 58  *     {
 59  *         alert( <b>event.editor</b> == myEditor );  // "true"
 60  *     });
 61  * myButton.fire( 'someEvent', null, <b>myEditor</b> );
 62  */
 63 
 64 /**
 65  * Any kind of additional data. Its format and usage is event dependent.
 66  * @name CKEDITOR.eventInfo.prototype.data
 67  * @field
 68  * @type Object
 69  * @example
 70  * someObject.on( 'someEvent', function( event )
 71  *     {
 72  *         alert( <b>event.data</b> );  // "Example"
 73  *     });
 74  * someObject.fire( 'someEvent', <b>'Example'</b> );
 75  */
 76 
 77 /**
 78  * Any extra data appended during the listener registration.
 79  * @name CKEDITOR.eventInfo.prototype.listenerData
 80  * @field
 81  * @type Object
 82  * @example
 83  * someObject.on( 'someEvent', function( event )
 84  *     {
 85  *         alert( <b>event.listenerData</b> );  // "Example"
 86  *     }
 87  *     , null, <b>'Example'</b> );
 88  */
 89 
 90 /**
 91  * Indicates that no further listeners are to be called.
 92  * @name CKEDITOR.eventInfo.prototype.stop
 93  * @function
 94  * @example
 95  * someObject.on( 'someEvent', function( event )
 96  *     {
 97  *         <b>event.stop()</b>;
 98  *     });
 99  * someObject.on( 'someEvent', function( event )
100  *     {
101  *         // This one will not be called.
102  *     });
103  * alert( someObject.fire( 'someEvent' ) );  // "false"
104  */
105 
106 /**
107  * Indicates that the event is to be cancelled (if cancelable).
108  * @name CKEDITOR.eventInfo.prototype.cancel
109  * @function
110  * @example
111  * someObject.on( 'someEvent', function( event )
112  *     {
113  *         <b>event.cancel()</b>;
114  *     });
115  * someObject.on( 'someEvent', function( event )
116  *     {
117  *         // This one will not be called.
118  *     });
119  * alert( someObject.fire( 'someEvent' ) );  // "true"
120  */
121 
122 /**
123  * Removes the current listener.
124  * @name CKEDITOR.eventInfo.prototype.removeListener
125  * @function
126  * @example
127  * someObject.on( 'someEvent', function( event )
128  *     {
129  *         <b>event.removeListener()</b>;
130  *			// Now this function won't be called again by 'someEvent'
131  *     });
132  */
133