_source/core/eventInfo.js

   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 "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  */