this reference) in which the handler function is executed. Defaults to the Element.
- * @param {Object} options (optional) An object containing handler configuration properties.
- * This may contain any of the following properties:this reference) in which the handler function is executed. Defaults to the Element.See {@link Ext.Element#addListener} for examples of how to use these options.
- */ - addListener : function(element, eventName, fn, scope, options){ + /** + * Appends an event handler to an element. The shorthand version {@link #on} is equivalent. Typically you will + * use {@link Ext.Element#addListener} directly on an Element in favor of calling this version. + * @param {String/HTMLElement} el The html element or id to assign the event handler to. + * @param {String} eventName The name of the event to listen for. + * @param {Function} handler The handler function the event invokes. This function is passed + * the following parameters:this reference) in which the handler function is executed. Defaults to the Element.
+ * @param {Object} options (optional) An object containing handler configuration properties.
+ * This may contain any of the following properties:this reference) in which the handler function is executed. Defaults to the Element.See {@link Ext.Element#addListener} for examples of how to use these options.
+ */ + addListener : function(element, eventName, fn, scope, options){ if(Ext.isObject(eventName)){ - var o = eventName, e, val; + var o = eventName, e, val; for(e in o){ - val = o[e]; - if(!propRe.test(e)){ - if(Ext.isFunction(val)){ - // shared options - listen(element, e, o, val, o.scope); - }else{ - // individual options - listen(element, e, val); - } + val = o[e]; + if(!propRe.test(e)){ + if(Ext.isFunction(val)){ + // shared options + listen(element, e, o, val, o.scope); + }else{ + // individual options + listen(element, e, val); + } } } } else { - listen(element, eventName, options, fn, scope); - } + listen(element, eventName, options, fn, scope); + } }, /** * Removes an event handler from an element. The shorthand version {@link #un} is equivalent. Typically * you will use {@link Ext.Element#removeListener} directly on an Element in favor of calling this version. - * @param {String/HTMLElement} el The id or html element from which to remove the event - * @param {String} eventName The type of event - * @param {Function} fn The handler function to remove + * @param {String/HTMLElement} el The id or html element from which to remove the listener. + * @param {String} eventName The name of the event. + * @param {Function} fn The handler function to remove. This must be a reference to the function passed into the {@link #addListener} call. + * @param {Object} scope If a scope (this reference) was specified when the listener was added,
+ * then this must refer to the same object.
*/
removeListener : function(element, eventName, fn, scope){
var el = Ext.getDom(element),
id = Ext.id(el),
- wrap;
-
- Ext.each((elHash[id] || {})[eventName], function (v,i,a) {
- if (Ext.isArray(v) && v[0] == fn && (!scope || v[2] == scope)) {
- E.un(el, eventName, wrap = v[1]);
- a.splice(i,1);
- return false;
- }
- });
+ wrap;
+
+ Ext.each((elHash[id] || {})[eventName], function (v,i,a) {
+ if (Ext.isArray(v) && v[0] == fn && (!scope || v[2] == scope)) {
+ E.un(el, eventName, wrap = v[1]);
+ a.splice(i,1);
+ return false;
+ }
+ });
// jQuery workaround that should be removed from Ext Core
- if(eventName == "mousewheel" && el.addEventListener && wrap){
- el.removeEventListener("DOMMouseScroll", wrap, false);
- }
-
- if(eventName == "mousedown" && el == DOC && wrap){ // fix stopped mousedowns on the document
- Ext.EventManager.stoppedMouseDownEvent.removeListener(wrap);
- }
+ if(eventName == "mousewheel" && el.addEventListener && wrap){
+ el.removeEventListener("DOMMouseScroll", wrap, false);
+ }
+
+ if(eventName == "mousedown" && el == DOC && wrap){ // fix stopped mousedowns on the document
+ Ext.EventManager.stoppedMouseDownEvent.removeListener(wrap);
+ }
},
/**
* Removes all event handers from an element. Typically you will use {@link Ext.Element#removeAllListeners}
* directly on an Element in favor of calling this version.
- * @param {String/HTMLElement} el The id or html element from which to remove the event
+ * @param {String/HTMLElement} el The id or html element from which to remove all event handlers.
*/
removeAll : function(el){
- var id = Ext.id(el = Ext.getDom(el)),
- es = elHash[id],
- ename;
-
- for(ename in es){
- if(es.hasOwnProperty(ename)){
- Ext.each(es[ename], function(v) {
- E.un(el, ename, v.wrap);
- });
- }
- }
- elHash[id] = null;
+ var id = Ext.id(el = Ext.getDom(el)),
+ es = elHash[id],
+ ename;
+
+ for(ename in es){
+ if(es.hasOwnProperty(ename)){
+ Ext.each(es[ename], function(v) {
+ E.un(el, ename, v.wrap);
+ });
+ }
+ }
+ elHash[id] = null;
},
/**
- * Fires when the document is ready (before onload and before images are loaded). Can be
+ * Adds a listener to be notified when the document is ready (before onload and before images are loaded). Can be
* accessed shorthanded as Ext.onReady().
- * @param {Function} fn The method the event invokes
- * @param {Object} scope (optional) An object that becomes the scope of the handler
- * @param {boolean} options (optional) An object containing standard {@link #addListener} options
+ * @param {Function} fn The method the event invokes.
+ * @param {Object} scope (optional) The scope (this reference) in which the handler function executes. Defaults to the browser window.
+ * @param {boolean} options (optional) Options object as passed to {@link Ext.Element#addListener}. It is recommended that the options
+ * {single: true} be used so that the handler is removed on first invocation.
*/
onDocumentReady : function(fn, scope, options){
if(docReadyState){ // if it already fired
@@ -299,8 +302,8 @@ Ext.EventManager = function(){
} else {
if(!docReadyEvent) initDocReady();
options = options || {};
- options.delay = options.delay || 1;
- docReadyEvent.addListener(fn, scope, options);
+ options.delay = options.delay || 1;
+ docReadyEvent.addListener(fn, scope, options);
}
},
@@ -309,10 +312,9 @@ Ext.EventManager = function(){
/**
* Appends an event handler to an element. Shorthand for {@link #addListener}.
* @param {String/HTMLElement} el The html element or id to assign the event handler to
- * @param {String} eventName The type of event to listen for
- * @param {Function} handler The handler function the event invokes
- * @param {Object} scope (optional) The scope in which to execute the handler
- * function (the handler function's "this" context)
+ * @param {String} eventName The name of the event to listen for.
+ * @param {Function} handler The handler function the event invokes.
+ * @param {Object} scope (optional) (this reference) in which the handler function executes. Defaults to the Element.
* @param {Object} options (optional) An object containing standard {@link #addListener} options
* @member Ext.EventManager
* @method on
@@ -320,10 +322,11 @@ Ext.EventManager = function(){
pub.on = pub.addListener;
/**
* Removes an event handler from an element. Shorthand for {@link #removeListener}.
- * @param {String/HTMLElement} el The id or html element from which to remove the event
- * @param {String} eventName The type of event
- * @param {Function} fn The handler function to remove
- * @return {Boolean} True if a listener was actually removed, else false
+ * @param {String/HTMLElement} el The id or html element from which to remove the listener.
+ * @param {String} eventName The name of the event.
+ * @param {Function} fn The handler function to remove. This must be a reference to the function passed into the {@link #on} call.
+ * @param {Object} scope If a scope (this reference) was specified when the listener was added,
+ * then this must refer to the same object.
* @member Ext.EventManager
* @method un
*/
@@ -333,10 +336,11 @@ Ext.EventManager = function(){
return pub;
}();
/**
- * Fires when the document is ready (before onload and before images are loaded). Shorthand of {@link Ext.EventManager#onDocumentReady}.
- * @param {Function} fn The method the event invokes
- * @param {Object} scope An object that becomes the scope of the handler
- * @param {boolean} options (optional) An object containing standard {@link #addListener} options
+ * Adds a listener to be notified when the document is ready (before onload and before images are loaded). Shorthand of {@link Ext.EventManager#onDocumentReady}.
+ * @param {Function} fn The method the event invokes.
+ * @param {Object} scope (optional) The scope (this reference) in which the handler function executes. Defaults to the browser window.
+ * @param {boolean} options (optional) Options object as passed to {@link Ext.Element#addListener}. It is recommended that the options
+ * {single: true} be used so that the handler is removed on first invocation.
* @member Ext
* @method onReady
*/
@@ -411,21 +415,21 @@ Ext.EventManager.addListener("myDiv", 'click', handleClick);
*/
Ext.EventObject = function(){
var E = Ext.lib.Event,
- // safari keypress events for special keys return bad keycodes
- safariKeys = {
- 3 : 13, // enter
- 63234 : 37, // left
- 63235 : 39, // right
- 63232 : 38, // up
- 63233 : 40, // down
- 63276 : 33, // page up
- 63277 : 34, // page down
- 63272 : 46, // delete
- 63273 : 36, // home
- 63275 : 35 // end
- },
- // normalize button clicks
- btnMap = Ext.isIE ? {1:0,4:1,2:2} :
+ // safari keypress events for special keys return bad keycodes
+ safariKeys = {
+ 3 : 13, // enter
+ 63234 : 37, // left
+ 63235 : 39, // right
+ 63232 : 38, // up
+ 63233 : 40, // down
+ 63276 : 33, // page up
+ 63277 : 34, // page down
+ 63272 : 46, // delete
+ 63273 : 36, // home
+ 63275 : 35 // end
+ },
+ // normalize button clicks
+ btnMap = Ext.isIE ? {1:0,4:1,2:2} :
(Ext.isWebKit ? {1:0,2:1,3:2} : {0:0,1:1,2:2});
Ext.EventObjectImpl = function(e){
@@ -437,7 +441,7 @@ Ext.EventObject = function(){
Ext.EventObjectImpl.prototype = {
/** @private */
setEvent : function(e){
- var me = this;
+ var me = this;
if(e == me || (e && e.browserEvent)){ // already wrapped
return e;
}
@@ -477,7 +481,7 @@ Ext.EventObject = function(){
* Stop the event (preventDefault and stopPropagation)
*/
stopEvent : function(){
- var me = this;
+ var me = this;
if(me.browserEvent){
if(me.browserEvent.type == 'mousedown'){
Ext.EventManager.stoppedMouseDownEvent.fire(me);
@@ -499,7 +503,7 @@ Ext.EventObject = function(){
* Cancels bubbling of the event.
*/
stopPropagation : function(){
- var me = this;
+ var me = this;
if(me.browserEvent){
if(me.browserEvent.type == 'mousedown'){
Ext.EventManager.stoppedMouseDownEvent.fire(me);
@@ -523,11 +527,11 @@ Ext.EventObject = function(){
getKey : function(){
return this.normalizeKey(this.keyCode || this.charCode)
},
-
- // private
- normalizeKey: function(k){
- return Ext.isSafari ? (safariKeys[k] || k) : k;
- },
+
+ // private
+ normalizeKey: function(k){
+ return Ext.isSafari ? (safariKeys[k] || k) : k;
+ },
/**
* Gets the x coordinate of the event.
@@ -587,37 +591,37 @@ Ext.EventObject = function(){
}
return delta;
},
-
- /**
- * Returns true if the target of this event is a child of el. Unless the allowEl parameter is set, it will return false if if the target is el.
- * Example usage:
- // Handle click on any child of an element
- Ext.getBody().on('click', function(e){
- if(e.within('some-el')){
- alert('Clicked on a child of some-el!');
- }
- });
-
- // Handle click directly on an element, ignoring clicks on child nodes
- Ext.getBody().on('click', function(e,t){
- if((t.id == 'some-el') && !e.within(t, true)){
- alert('Clicked directly on some-el!');
- }
- });
-
+ // Handle click on any child of an element
+ Ext.getBody().on('click', function(e){
+ if(e.within('some-el')){
+ alert('Clicked on a child of some-el!');
+ }
+ });
+
+ // Handle click directly on an element, ignoring clicks on child nodes
+ Ext.getBody().on('click', function(e,t){
+ if((t.id == 'some-el') && !e.within(t, true)){
+ alert('Clicked directly on some-el!');
+ }
+ });
+