this paragraph is used for the examples below
$('addEventExample').addEvent('click', function() {
alert('click!');
});
Why use this instead of just doing //$('addEventExample').onclick = alert('click');// ? Well, using event listeners like this allows you to have more than one. If you do //.onclick = myFunction()// then you can only have one event watching that click. Click might not be a great example there, but certainly something like //window.onload// is something you might want to have numerous events monitoring.
//Element.addEvents// is the same only the argument is an object:
$('addEventExample').addEvents({
mouseover: function() {this.setStyle('color','#f00')},
mouseout: function() {this.setStyle('color','#000')}
});
The only argument passed to the argument you define is the event object, which you can inspect and/or stop. There's more on [[05-event|the native Event class page]], including examples.
===== Element.removeEvent, removeEvents =====
You can also use //Element.removeEvent// to remove an event listener. //.removeEvents// will remove all the events on an element. For //removeEvent// you must pass in the function that you passed in when you added the event. This means you can't use anonymous functions:
$(el).addEvent('click', function(){alert('clicked!')});
//this won't work:
$(el).removeEvent('click', function(){alert('clicked!')});
//instead
var sayClicked = function(){alert('clicked')};
$(el).addEvent('click', sayClicked);
$(el).removeEvent('click', sayClicked);
===== Element.fireEvent =====
Fires the specified event on an element. For instance, if you set up an event for clicking an element, you can execute that even if the user doesn't click it:
$('fireEventExample').addEvent('click', function(){alert('click!')});
$('fireEventExample').fireEvent('click'); //alerts 'click!'
===== Element.cloneEvents =====
//Element.clone// does not clone the events associated with that element. It's not that often that you want to do this, but if you need to, //.cloneEvents// will do the trick:
$(new).cloneEvents(old); //copies the events from old to new
$(new).cloneEvents(old, 'click');//copies only the click events from old to new
===== Custom Events =====
MooTools 1.1 adds the concept of custom events. These are events that are fired when a set of conditions that you code occur. A good example of this is //window.addEvent('domready'..//. domready is not a browser defined event; it is an event that MooTools defines.
Adding a custom event is pretty easy. Here's the custom event for "mouseenter":
Element.Events.extend({
'mouseenter': {
type: 'mouseover',
map: function(event){
event = new Event(event);
if (event.relatedTarget == this || this.hasChild(event.relatedTarget)) return;
this.fireEvent('mouseenter', event);
}
}
});
The "type" specifies when the event should be tested. In this case, the event defined in the "map" method is tested anytime the //mouseover// event occurs for the element. The function is tested to see if the relative target for the mouseover event is the current element or one of its children and, if not, it fires mouseenter.
MooTools defines, by default, 4 custom events: //mouseenter, mouseleave, mousewheel,// and [[01-domready|//domready//]].
===== Function.bindWithEvent =====
With //bindWithEvent// you'll get the mootools //Event// wrapper as the first argument:
function fn(event){
//event is the mootools event, that supports all the cool stuff like
event.page.y //position of the mouse in the page
event.key //the key pressed
event.shift //if shift has been pressed to trigger the event
//and tons of others, refer to the docs, Native/Event.js
//the keyword this is the element, because we used element in the bindWithEvent argument.
};
element.onclick = fn.bindWithEvent(element);
Basically bind //withEvent// will do this automatically for you:
function fn(event){
event = new Event(event);
};
element.onclick = fn;