sources/core/dom/event.js

   1 /**
   2  * @license Copyright (c) 2003-2016, CKSource - Frederico Knabben. All rights reserved.
   3  * For licensing, see LICENSE.md or http://ckeditor.com/license
   4  */
   5
   6 /**
   7  * @fileOverview Defines the {@link CKEDITOR.dom.event} class, which
   8  *              represents the a native DOM event object.
   9  */
  10
  11 /**
  12  * Represents a native DOM event object.
  13  *
  14  * @class
  15  * @constructor Creates an event class instance.
  16  * @param {Object} domEvent A native DOM event object.
  17  */
  18 CKEDITOR.dom.event = function( domEvent ) {
  19         /**
  20          * The native DOM event object represented by this class instance.
  21          *
  22          * @readonly
  23          */
  24         this.$ = domEvent;
  25 };
  26
  27 CKEDITOR.dom.event.prototype = {
  28         /**
  29          * Gets the key code associated to the event.
  30          *
  31          *              alert( event.getKey() ); // '65' is 'a' has been pressed
  32          *
  33          * @returns {Number} The key code.
  34          */
  35         getKey: function() {
  36                 return this.$.keyCode || this.$.which;
  37         },
  38
  39         /**
  40          * Gets a number represeting the combination of the keys pressed during the
  41          * event. It is the sum with the current key code and the {@link CKEDITOR#CTRL},
  42          * {@link CKEDITOR#SHIFT} and {@link CKEDITOR#ALT} constants.
  43          *
  44          *              alert( event.getKeystroke() == 65 );                                                                    // 'a' key
  45          *              alert( event.getKeystroke() == CKEDITOR.CTRL + 65 );                                    // CTRL + 'a' key
  46          *              alert( event.getKeystroke() == CKEDITOR.CTRL + CKEDITOR.SHIFT + 65 );   // CTRL + SHIFT + 'a' key
  47          *
  48          * @returns {Number} The number representing the keys combination.
  49          */
  50         getKeystroke: function() {
  51                 var keystroke = this.getKey();
  52
  53                 if ( this.$.ctrlKey || this.$.metaKey )
  54                         keystroke += CKEDITOR.CTRL;
  55
  56                 if ( this.$.shiftKey )
  57                         keystroke += CKEDITOR.SHIFT;
  58
  59                 if ( this.$.altKey )
  60                         keystroke += CKEDITOR.ALT;
  61
  62                 return keystroke;
  63         },
  64
  65         /**
  66          * Prevents the original behavior of the event to happen. It can optionally
  67          * stop propagating the event in the event chain.
  68          *
  69          *              var element = CKEDITOR.document.getById( 'myElement' );
  70          *              element.on( 'click', function( ev ) {
  71          *                      // The DOM event object is passed by the 'data' property.
  72          *                      var domEvent = ev.data;
  73          *                      // Prevent the click to chave any effect in the element.
  74          *                      domEvent.preventDefault();
  75          *              } );
  76          *
  77          * @param {Boolean} [stopPropagation=false] Stop propagating this event in the
  78          * event chain.
  79          */
  80         preventDefault: function( stopPropagation ) {
  81                 var $ = this.$;
  82                 if ( $.preventDefault )
  83                         $.preventDefault();
  84                 else
  85                         $.returnValue = false;
  86
  87                 if ( stopPropagation )
  88                         this.stopPropagation();
  89         },
  90
  91         /**
  92          * Stops this event propagation in the event chain.
  93          */
  94         stopPropagation: function() {
  95                 var $ = this.$;
  96                 if ( $.stopPropagation )
  97                         $.stopPropagation();
  98                 else
  99                         $.cancelBubble = true;
 100         },
 101
 102         /**
 103          * Returns the DOM node where the event was targeted to.
 104          *
 105          *              var element = CKEDITOR.document.getById( 'myElement' );
 106          *              element.on( 'click', function( ev ) {
 107          *                      // The DOM event object is passed by the 'data' property.
 108          *                      var domEvent = ev.data;
 109          *                      // Add a CSS class to the event target.
 110          *                      domEvent.getTarget().addClass( 'clicked' );
 111          *              } );
 112          *
 113          * @returns {CKEDITOR.dom.node} The target DOM node.
 114          */
 115         getTarget: function() {
 116                 var rawNode = this.$.target || this.$.srcElement;
 117                 return rawNode ? new CKEDITOR.dom.node( rawNode ) : null;
 118         },
 119
 120         /**
 121          * Returns an integer value that indicates the current processing phase of an event.
 122          * For browsers that doesn't support event phase, {@link CKEDITOR#EVENT_PHASE_AT_TARGET} is always returned.
 123          *
 124          * @returns {Number} One of {@link CKEDITOR#EVENT_PHASE_CAPTURING},
 125          * {@link CKEDITOR#EVENT_PHASE_AT_TARGET}, or {@link CKEDITOR#EVENT_PHASE_BUBBLING}.
 126          */
 127         getPhase: function() {
 128                 return this.$.eventPhase || 2;
 129         },
 130
 131         /**
 132          * Retrieves the coordinates of the mouse pointer relative to the top-left
 133          * corner of the document, in mouse related event.
 134          *
 135          *              element.on( 'mousemouse', function( ev ) {
 136          *                      var pageOffset = ev.data.getPageOffset();
 137          *                      alert( pageOffset.x );                  // page offset X
 138          *                      alert( pageOffset.y );                  // page offset Y
 139          *     } );
 140          *
 141          * @returns {Object} The object contains the position.
 142          * @returns {Number} return.x
 143          * @returns {Number} return.y
 144          */
 145         getPageOffset: function() {
 146                 var doc = this.getTarget().getDocument().$;
 147                 var pageX = this.$.pageX || this.$.clientX + ( doc.documentElement.scrollLeft || doc.body.scrollLeft );
 148                 var pageY = this.$.pageY || this.$.clientY + ( doc.documentElement.scrollTop || doc.body.scrollTop );
 149                 return { x: pageX, y: pageY };
 150         }
 151 };
 152
 153 // For the followind constants, we need to go over the Unicode boundaries
 154 // (0x10FFFF) to avoid collision.
 155
 156 /**
 157  * CTRL key (0x110000).
 158  *
 159  * @readonly
 160  * @property {Number} [=0x110000]
 161  * @member CKEDITOR
 162  */
 163 CKEDITOR.CTRL = 0x110000;
 164
 165 /**
 166  * SHIFT key (0x220000).
 167  *
 168  * @readonly
 169  * @property {Number} [=0x220000]
 170  * @member CKEDITOR
 171  */
 172 CKEDITOR.SHIFT = 0x220000;
 173
 174 /**
 175  * ALT key (0x440000).
 176  *
 177  * @readonly
 178  * @property {Number} [=0x440000]
 179  * @member CKEDITOR
 180  */
 181 CKEDITOR.ALT = 0x440000;
 182
 183 /**
 184  * Capturing phase.
 185  *
 186  * @readonly
 187  * @property {Number} [=1]
 188  * @member CKEDITOR
 189  */
 190 CKEDITOR.EVENT_PHASE_CAPTURING = 1;
 191
 192 /**
 193  * Event at target.
 194  *
 195  * @readonly
 196  * @property {Number} [=2]
 197  * @member CKEDITOR
 198  */
 199 CKEDITOR.EVENT_PHASE_AT_TARGET = 2;
 200
 201 /**
 202  * Bubbling phase.
 203  *
 204  * @readonly
 205  * @property {Number} [=3]
 206  * @member CKEDITOR
 207  */
 208 CKEDITOR.EVENT_PHASE_BUBBLING = 3;