_source/core/eventInfo.js

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