_source/core/dom/event.js

   1 /*\r
   2 Copyright (c) 2003-2013, 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 {@link CKEDITOR.dom.event} class, which\r
   8  *              represents the a native DOM event object.\r
   9  */\r
  10 \r
  11 /**\r
  12  * Represents a native DOM event object.\r
  13  * @constructor\r
  14  * @param {Object} domEvent A native DOM event object.\r
  15  * @example\r
  16  */\r
  17 CKEDITOR.dom.event = function( domEvent )\r
  18 {\r
  19         /**\r
  20          * The native DOM event object represented by this class instance.\r
  21          * @type Object\r
  22          * @example\r
  23          */\r
  24         this.$ = domEvent;\r
  25 };\r
  26 \r
  27 CKEDITOR.dom.event.prototype =\r
  28 {\r
  29         /**\r
  30          * Gets the key code associated to the event.\r
  31          * @returns {Number} The key code.\r
  32          * @example\r
  33          * alert( event.getKey() );  "65" is "a" has been pressed\r
  34          */\r
  35         getKey : function()\r
  36         {\r
  37                 return this.$.keyCode || this.$.which;\r
  38         },\r
  39 \r
  40         /**\r
  41          * Gets a number represeting the combination of the keys pressed during the\r
  42          * event. It is the sum with the current key code and the {@link CKEDITOR.CTRL},\r
  43          * {@link CKEDITOR.SHIFT} and {@link CKEDITOR.ALT} constants.\r
  44          * @returns {Number} The number representing the keys combination.\r
  45          * @example\r
  46          * alert( event.getKeystroke() == 65 );                                   // "a" key\r
  47          * alert( event.getKeystroke() == CKEDITOR.CTRL + 65 );                   // CTRL + "a" key\r
  48          * alert( event.getKeystroke() == CKEDITOR.CTRL + CKEDITOR.SHIFT + 65 );  // CTRL + SHIFT + "a" key\r
  49          */\r
  50         getKeystroke : function()\r
  51         {\r
  52                 var keystroke = this.getKey();\r
  53 \r
  54                 if ( this.$.ctrlKey || this.$.metaKey )\r
  55                         keystroke += CKEDITOR.CTRL;\r
  56 \r
  57                 if ( this.$.shiftKey )\r
  58                         keystroke += CKEDITOR.SHIFT;\r
  59 \r
  60                 if ( this.$.altKey )\r
  61                         keystroke += CKEDITOR.ALT;\r
  62 \r
  63                 return keystroke;\r
  64         },\r
  65 \r
  66         /**\r
  67          * Prevents the original behavior of the event to happen. It can optionally\r
  68          * stop propagating the event in the event chain.\r
  69          * @param {Boolean} [stopPropagation] Stop propagating this event in the\r
  70          *              event chain.\r
  71          * @example\r
  72          * var element = CKEDITOR.document.getById( 'myElement' );\r
  73          * element.on( 'click', function( ev )\r
  74          *     {\r
  75          *         // The DOM event object is passed by the "data" property.\r
  76          *         var domEvent = ev.data;\r
  77          *         // Prevent the click to chave any effect in the element.\r
  78          *         domEvent.preventDefault();\r
  79          *     });\r
  80          */\r
  81         preventDefault : function( stopPropagation )\r
  82         {\r
  83                 var $ = this.$;\r
  84                 if ( $.preventDefault )\r
  85                         $.preventDefault();\r
  86                 else\r
  87                         $.returnValue = false;\r
  88 \r
  89                 if ( stopPropagation )\r
  90                         this.stopPropagation();\r
  91         },\r
  92 \r
  93         stopPropagation : function()\r
  94         {\r
  95                 var $ = this.$;\r
  96                 if ( $.stopPropagation )\r
  97                         $.stopPropagation();\r
  98                 else\r
  99                         $.cancelBubble = true;\r
 100         },\r
 101 \r
 102         /**\r
 103          * Returns the DOM node where the event was targeted to.\r
 104          * @returns {CKEDITOR.dom.node} The target DOM node.\r
 105          * @example\r
 106          * var element = CKEDITOR.document.getById( 'myElement' );\r
 107          * element.on( 'click', function( ev )\r
 108          *     {\r
 109          *         // The DOM event object is passed by the "data" property.\r
 110          *         var domEvent = ev.data;\r
 111          *         // Add a CSS class to the event target.\r
 112          *         domEvent.getTarget().addClass( 'clicked' );\r
 113          *     });\r
 114          */\r
 115 \r
 116         getTarget : function()\r
 117         {\r
 118                 var rawNode = this.$.target || this.$.srcElement;\r
 119                 return rawNode ? new CKEDITOR.dom.node( rawNode ) : null;\r
 120         },\r
 121 \r
 122         /**\r
 123          * Retrieves the coordinates of the mouse pointer relative to the top-left\r
 124          * corner of the document, in mouse related event.\r
 125          * @returns {Object} The object contains the position.\r
 126          * @example\r
 127          * element.on( 'mousemouse', function( ev )\r
 128          *     {\r
 129          *         var pageOffset = ev.data.getPageOffset();\r
 130          *         alert( pageOffset.x ); // page offset X\r
 131          *         alert( pageOffset.y ); // page offset Y\r
 132          *     });\r
 133          */\r
 134         getPageOffset : function()\r
 135         {\r
 136                 var doc = this.getTarget().getDocument().$;\r
 137                 var pageX = this.$.pageX || this.$.clientX + ( doc.documentElement.scrollLeft || doc.body.scrollLeft );\r
 138                 var pageY = this.$.pageY || this.$.clientY + ( doc.documentElement.scrollTop || doc.body.scrollTop );\r
 139                 return { x : pageX, y : pageY };\r
 140         }\r
 141 };\r
 142 \r
 143 // For the followind constants, we need to go over the Unicode boundaries\r
 144 // (0x10FFFF) to avoid collision.\r
 145 \r
 146 /**\r
 147  * CTRL key (0x110000).\r
 148  * @constant\r
 149  * @example\r
 150  */\r
 151 CKEDITOR.CTRL = 0x110000;\r
 152 \r
 153 /**\r
 154  * SHIFT key (0x220000).\r
 155  * @constant\r
 156  * @example\r
 157  */\r
 158 CKEDITOR.SHIFT = 0x220000;\r
 159 \r
 160 /**\r
 161  * ALT key (0x440000).\r
 162  * @constant\r
 163  * @example\r
 164  */\r
 165 CKEDITOR.ALT = 0x440000;\r