1 /** 2 * The Render Engine 3 * Events 4 * 5 * @fileoverview Methods for handling events (adding & removing) and keycodes for 6 * special keys like the arrows and function keys. 7 * 8 * @author: Brett Fattori (brettf@renderengine.com) 9 * 10 * @author: $Author: bfattori $ 11 * @version: $Revision: 1555 $ 12 * 13 * Copyright (c) 2011 Brett Fattori (brettf@renderengine.com) 14 * 15 * Permission is hereby granted, free of charge, to any person obtaining a copy 16 * of this software and associated documentation files (the "Software"), to deal 17 * in the Software without restriction, including without limitation the rights 18 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 19 * copies of the Software, and to permit persons to whom the Software is 20 * furnished to do so, subject to the following conditions: 21 * 22 * The above copyright notice and this permission notice shall be included in 23 * all copies or substantial portions of the Software. 24 * 25 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 26 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 27 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 28 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 29 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 30 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 31 * THE SOFTWARE. 32 * 33 */ 34 "use strict"; 35 36 // The class this file defines and its required classes 37 R.Engine.define({ 38 "class":"R.engine.Events", 39 "requires":[] 40 }); 41 42 /** 43 * @class A static object for uniformly handling events within all browser 44 * platforms. The event engine is an abstraction of the jQuery event 45 * system. Methods are provided for adding and removing events in 46 * a programmatic way. Additionally the engine has key codes for 47 * common keys which aren't part of the letters or numbers. 48 * <p/> 49 * While the engine provides a low-level way to attach events, when 50 * working with game objects methods are provided to manage events 51 * better than with the engine itself. 52 * <p/> 53 * Adding an event: 54 * <pre> 55 * var t = $(".myElement"); 56 * R.engine.Events.setHandler(t, "click", function(event) { 57 * MyObject.evtHandler(); 58 * }); 59 * </pre> 60 * @see R.engine.BaseObject#addEvent 61 * @see R.engine.BaseObject#removeEvent 62 */ 63 R.engine.Events = Base.extend(/** @scope R.engine.Events.prototype */{ 64 65 /** @private */ 66 constructor:null, 67 68 /** 69 * Set an event handler on a target. The handler function will 70 * be called whenever the event occurs. 71 * 72 * @param target {String/jQuery} The target for the event. This should either be a 73 * CSS selector, or a jQuery object. 74 * @param [data] {Array} Optional data to pass to the handler when it is invoked. 75 * @param name {String} The event to handle. ie: "click" or "mouseover" 76 * @param handler {Function} The handler function to assign to the target 77 * @memberOf R.engine.Events 78 */ 79 setHandler:function (target, data, name, handler) { 80 if (typeof data == "string") { 81 handler = name; 82 name = data; 83 data = null; 84 } 85 86 if (target == document.body) { 87 target = document; 88 } 89 90 jQuery(target).bind(name, data || handler, handler); 91 }, 92 93 /** 94 * Clear an event handler that was previously assigned to the target. If no 95 * specific handler is assigned, all event handlers will be removed from the target. 96 * 97 * @param target {String/jQuery} The target for the event. This should either be a 98 * CSS selector, or a jQuery object. 99 * @param name {String} The event to handle. ie: "click" or "mouseover" 100 * @param handler {Function} The handler function to unassign from the target 101 * @memberOf R.engine.Events 102 */ 103 clearHandler:function (target, name, handler) { 104 if (target == document.body) { 105 target = document; 106 } 107 jQuery(target).unbind(name, handler); 108 }, 109 110 /** 111 * Get the key code for the provided character. The value returned 112 * will be for the uppercase key value, unless the second argument is 113 * set to <code>true</code> which will return the exact key code for the 114 * provided character. 115 * @param charStr {String} A single character to get the key code for 116 * @param [literal] {Boolean} <code>true</code> to return the literal code without 117 * first converting the character to lower case. 118 * @return {Number} The key code for the given character 119 * @memberOf R.engine.Events 120 */ 121 keyCodeForChar:function (charStr, literal) { 122 return (literal ? charStr : charStr.toUpperCase()).charCodeAt(0); 123 }, 124 125 /** 126 * Returns true if the key pressed is either the lower or upper case version of 127 * the key specified in "keyStr". 128 * @param eventObj 129 * @param keyStr 130 */ 131 isKey:function (eventObj, keyStr) { 132 return (eventObj.which == R.engine.Events.keyCodeForChar(keyStr) || 133 eventObj.which == R.engine.Events.keyCodeForChar(keyStr, true)); 134 }, 135 136 //==================================================================================================================== 137 // MOUSE BUTTON CONSTANTS 138 139 /** No mouse button pressed. 140 * @type {Number} 141 */ 142 MOUSE_NO_BUTTON:-1, 143 144 /** Left mouse button. 145 * @type {Number} 146 */ 147 MOUSE_LEFT_BUTTON:1, 148 149 /** Right mouse button. 150 * @type {Number} 151 */ 152 MOUSE_RIGHT_BUTTON:3, 153 154 /** Middle mouse button. 155 * @type {Number} 156 */ 157 MOUSE_MIDDLE_BUTTON:2, 158 159 //==================================================================================================================== 160 // KEY CODE CONSTANTS 161 162 /** Constant for the "Tab" key 163 * @type {Number} 164 */ 165 KEYCODE_TAB:9, 166 167 /** Constant for the "Enter" key 168 * @type {Number} 169 */ 170 KEYCODE_ENTER:13, 171 172 /** Constant for the "Delete" key 173 * @type {Number} 174 */ 175 KEYCODE_DELETE:46, 176 177 /** Constant for the "Space" key 178 * @type {Number} 179 */ 180 KEYCODE_SPACE:32, 181 182 /** Constant for the "Backspace" 183 * @type {Number} 184 */ 185 KEYCODE_BACKSPACE:8, 186 187 /** Constant for the "Up" key 188 * @type {Number} 189 */ 190 KEYCODE_UP_ARROW:38, 191 192 /** Constant for the "Down" key 193 * @type {Number} 194 */ 195 KEYCODE_DOWN_ARROW:40, 196 197 /** Constant for the "Left" key 198 * @type {Number} 199 */ 200 KEYCODE_LEFT_ARROW:37, 201 202 /** Constant for the "RIGHT" key 203 * @type {Number} 204 */ 205 KEYCODE_RIGHT_ARROW:39, 206 207 /** Constant for the "Plus" key 208 * @type {Number} 209 */ 210 KEYCODE_KEYPAD_PLUS:61, 211 212 /** Constant for the "Minus" key 213 * @type {Number} 214 */ 215 KEYCODE_KEYPAD_MINUS:109, 216 217 /** Constant for the "Home" key 218 * @type {Number} 219 */ 220 KEYCODE_HOME:36, 221 222 /** Constant for the "End" key 223 * @type {Number} 224 */ 225 KEYCODE_END:35, 226 227 /** Constant for the "F1" key 228 * @type {Number} 229 */ 230 KEYCODE_F1:112, 231 232 /** Constant for the "F2" key 233 * @type {Number} 234 */ 235 KEYCODE_F2:113, 236 237 /** Constant for the "F3" key 238 * @type {Number} 239 */ 240 KEYCODE_F3:114, 241 242 /** Constant for the "F4" key 243 * @type {Number} 244 */ 245 KEYCODE_F4:115, 246 247 /** Constant for the "F5" key 248 * @type {Number} 249 */ 250 KEYCODE_F5:116, 251 252 /** Constant for the "F6" key 253 * @type {Number} 254 */ 255 KEYCODE_F6:117, 256 257 /** Constant for the "F7" key 258 * @type {Number} 259 */ 260 KEYCODE_F7:118, 261 262 /** Constant for the "F8" key 263 * @type {Number} 264 */ 265 KEYCODE_F8:119, 266 267 /** Constant for the "F9" key 268 * @type {Number} 269 */ 270 KEYCODE_F9:120, 271 272 /** Constant for the "F10" key 273 * @type {Number} 274 */ 275 KEYCODE_F10:121, 276 277 /** Constant for the "F11" key 278 * @type {Number} 279 */ 280 KEYCODE_F11:122, 281 282 /** Constant for the "F12" key 283 * @type {Number} 284 */ 285 KEYCODE_F12:123, 286 287 /** Constant for the "Context Menu" key (Windows) 288 * @type {Number} 289 */ 290 KEYCODE_MENU:93, 291 292 /** Constant for the "Windows" key (Windows) 293 * @type {Number} 294 */ 295 KEYCODE_WINDOW:91 296 297 }); 298