Event Docs

The event library provides a uniform API across the various browsers for attaching multiple events to HTML Elements.

API

isSupported()

Determine if the event library is fully supported by the browser. Returns true if so and false otherwise.

To determine complete support you must include the Fork scroll library because it is used to determine mouse position for an event. Because Fork.Scroll.isSupported() can only be called after the document's body element has been parsed that also means that FORK.Event.isSupported() must be called only after the document's body element has been parsed. See the scroll docs for more information.

Examples

if (FORK.Event.isSupported()) {
  FORK.Event.addListener("myDiv", "mouseover", function(){alert('hi');});
} else {
  alert('Your browser is not capable using the FORK event library.');
}





addListener(element, event, handler, options)

All listeners added through addListener will automatically be removed by the window.unload event. This is to avoid the memory leak in Internet Explorer.

In the Fork Event library there is a workaround for versions of Safari. This has implications when dealing with click and dblclick events. Read more


  element

  
HTMLElement or string id of an element.

  event

  
string

  handler

  
function to be executed when the event occurs. This function will be passed the event object as the first argument.

  options

  
object. optional argument. There are two independent options. You can use none or one or both. The scope option is an object that will be used as this when the handler executes. The value of the argument option will be sent to the handler as the second argument. argument can be a primitive or object (so can be an array or function since these are objects in JavaScript.)


Examples
  
function alertEventType(e) {
  alert(e.type);
}

var div = document.getElementById('myDiv');

FORK.Event.addListener(div, 'mouseover', alertEventType);


var foo = {
  age: 34,
  sayAge: function() {
         alert(this.age);
       }
};

FORK.Event.addListener('myDiv', 'click', foo.sayAge, {scope:foo});


FORK.Event.addListener("myDiv", "click", function(e, arg){alert(arg.b);}, {argument:{b:99}});


It is possible to define the function inline like the following example but then it may not be possible to use removeListener

FORK.Event.addListener("myDiv", "click", function(){alert("a click!");});



removeListener(element, event, handler)


  element

  
HTMLElement or string id of an element.

  event

  
string

  handler

  
function to be executed when the event occurs.


Examples

function alertEventType(e) {
  alert(e.type);
}

var div = document.getElementById('myDiv');

FORK.Event.addListener(div, 'mouseover', alertEventType);

// somewhere later in the execution
FORK.Event.removeListener(div, 'mouseover', alertEventType);


var foo = {
  age: 34,
  sayAge: function() {
         alert(this.age);
       }
};

FORK.Event.addListener('myDiv', 'click', foo.sayAge, {scope:foo});

// somewhere later in the execution
FORK.Event.removeListener('myDiv', 'click', foo.sayAge);



purgeElement(element, options)

purgeElement removes all or optionally some of the event handlers registered thorough addListener on the element and optionally on its descendent nodes.


  element

  
HTMLElement or string id of an element.

  options

  
object. optional argument. There are two independent options. You can use none or one or both. If the deep option is true then all child nodes of the object will also be purged of their handlers. The type option is a string that limits which type of event handlers will be purged.


Examples

FORK.Event.purge('myDiv');

FORK.Event.purge(myDiv);

FORK.Event.purge('myDiv', {deep:true});

FORK.Event.purge(myDiv, {type:'click'});

FORK.Event.purge(myDiv, {type:'click', deep:'true});



stopPropagation(event)

Stops the propagation of the event as it bubbles up the DOM tree.


  event

  
The event to be stopped.


Examples

function childHandler(e) {
  alert('childHandler');
  FORK.Event.stopPropagation(e);
}

function parentHandler(e) { // this won't execute
  alert('parentHandler');
}

var div = document.getElementById('myDiv');

FORK.Event.addListener(div, 'click', childHandler);
FORK.Event.addListener(div.parentNode, 'click', parentHandler);



preventDefault(event)

For events that have a default browser action, preventDefault stops this action.


  event

  
The event for which the default should be stopped.


Examples

A typical use of prevent default is to stop a link from being followed for a click event. In this example imagine an element <a href="http://prototype.conio.net/" id="protoLink">Prototype<\a>


function clickHandler(e) {
  alert("Don't make yourself suffer!");
  FORK.Event.preventDefault(e);
}

var a = document.getElementById('protoLink');

FORK.Event.addListener(a, 'click', clickHandler);



getTarget(event)

Returns the target of the event. The target is the most distant descendent HTML Element of the DOM root element that received the event.


  event

  
The event.


Examples

function clickHandler(e) {
  alert(FORK.Event.getTarget(e).tagName);
}

FORK.Event.addListener('myDiv, 'click', clickHandler);



getRelatedTarget(event)

Returns the related target of a mouseover or mouseout event. For a mouseout event the returned HTML Element is the element that the mouse has just entered. For a mouseover event the related target is the element that the mouse has just exited.


  event

  
The event.


Examples

function handler(e) {
  alert(FORK.Event.getRelatedTarget(e).tagName);
}

FORK.Event.addListener('myDiv, 'mouseover', handler);



getPageX(event)

Returns the horizontal position of the event in page coordinates. This is equivalent to Netscape Navigator 4 event.pageX property. If the particular browser is incapable of determining the page coordinates then NaN is returned. I don't know of a browser with the advanced event capabilities required by this library that will return NaN.

To use this function include the 
scroll.js
 file that is part of Fork.


  event

  
The event.


Examples

function handler(e) {
  alert(FORK.Event.getPageX(e));
}

FORK.Event.addListener('myDiv, 'click', handler);



getPageY(event)

Analogous to getPageX.

Design

click and dblclick events

Two bugs in Safari play a major role in designing the addEventListener function. In Safari 1.3 and I am also told early versions of Safari 2, it is not possible to attach a dblclick event listener using the W3C standard addEventListener. The second bug is that if a click event handler is attached using addEventListener then a call to preventDefault inside that handler will not actually prevent the browser's default behavior. To work around these two bugs the Fork event library uses a workaround for attaching click and dblclick events in all browsers. This technique was inspired by the Yahoo! UI event utility but the implementation is different in Fork. The YUI library only uses the workaround for Safari which means behavior in Safari could be drastically different then in other browsers. The Fork library is designed for uniform cross browser behavior.

The workaround happens behind the scenes of the Fork event library and the API is uniform for all types of events. There is a consequences of this workaround for click and dblclick events that must be known: Any inline DOM0 click or dblclick event handlers will be overwritten if the FORK.Event.addListener is used to attach the same kind of event to the same element. This was chosen as the best design compromise after considering other options. If a better approach appears in the future then this compromise can be removed and will be backwards compatible. However it should be relatively easy to live with this compromise and many people may not encounter the consequences at all.

For example, in the following code snip in any browser, there will never be an alert that says "DOM0 click" because the "DOM2 click" handler will have overwritten it. There will be both the "DOM0 mouseover" and "DOM2 mousover" alerts.

<p id="myPara" onmouseover="alert('DOM0 mouseover');" onclick="alert('DOM0 click')">
  a little paragraph
</p>

<script type="text/javascript">
  FORK.Event.addListener('myPara',
                         'mouseover',
                         function(){alert('DOM2 mouseover');});

  FORK.Event.addListener('myPara',
                         'click',
                         function(){alert('DOM2 click');});
</script>

You can still attach more than one click or dblclick event handler to an element using FORK.Event.addListener and they will all execute as you would expect.

Credits

The Yahoo! UI Event utility contains the majority of ideas in this library. On comp.lang.javascript, David Golightly suggested calling the handlers from inside try-catch blocks.