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