      1 ﻿/*
      2 Copyright (c) 2003-2009, 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  * This class is not really part of the API. It just illustrates the features
     14  * of the event object passed to event listeners by a {@link CKEDITOR.event}
     15  * based object.
     16  * @name CKEDITOR.eventInfo
     17  * @constructor
     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