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