Microsoft AJAX Library: Sys.UI.DomEvent Remarks

I believe DomEvent and DomElement are two most essential building blocks in the MS AJAX Library. The library is about building rich client UIs, and you hardly do anything without manipulating the DOM.

Let’s take a look at event properties. I’ll use the same contrived example of an article with some content and a “read more” link.

For example, I want to display the rest of the article when Read more… is clicked, so let’s set up an event handler on the hyperlink:

function processClick (e)
{
 // ... Do something meaningful here ...
 Sys.Debug.traceDump (e);
 e.preventDefault();
}
$addHandler ($get('readmore'), 'click', processClick);

Note that in processClick, e is of type Sys.UI.DomEvent (which wraps a native DOM event) and has a number of interesting properties.

Suppose, I click Read more… right where the letter “m” is. To help you understand what’s going on, refer to the screenshot below (click for a bigger image):

clientX and clientY

These are (x, y) coordinates of where the click occurred relative to the visible document area (aka client area) of the browser window. In the screen shot, the page is scrolled, and the scrolled height is not taken into account.

offsetX and offsetY

(x, y) coordinates relative to the upper left corner of the object that raised the event, i.e. the hyperlink.

What’s this for? As Danny Goodman suggests in The JavaScript Bible (4th ed), “This is how, for example, you could determine the click point on an image” regardless of how the image is positioned.

screenX and screenY

To quote The JavaScript Bible again:

“The screenX and screenY properties return the pixel coordinates of the event on the entire video screen. These properties may be useful if IE provided more window dimension properties. In any case, because mouse events fire only when the cursor is somewhere in the content region of the browser window, don’t expect to get screen values of anywhere outside this region.”

rawEvent

This is another important property, although it’s not listed at the official MS AJAX site. rawEvent points to the native DOM event that was raised.

target

This is a very important property. It points to the DOM element that raised the event. “Because the event may trickle down and bubble up through the element containment hierarchy and be processed at any level along the way, having a property that points back to the element from which the event originated is comforting.” (The JavaScript Bible)

As a helpful aside, to determine the absolute position of the target element within the browser window, call Sys.UI.DomElement.getLocation(e.target).

Another way to find out mouse coordinates when the event occurred (borrowed from Prototype):

var x = e.rawEvent.pageX || 
 (e.rawEvent.clientX + 
  (document.documentElement.scrollLeft || document.body.scrollLeft));
  
var y = e.rawEvent.pageY || 
 (e.rawEvent.clientY + 
  (document.documentElement.scrollLeft || document.body.scrollLeft));

button and charCode

button indicates which mouse button caused the event and allows you to compare it to the handy Sys.UI.MouseButton enumeration.

charCode gets the character code of the key that raised the associated event.

function myClickHandler(e) {
  if (e.button === Sys.UI.MouseButton.leftButton) {
  //...
  }
}

function myKeyUpHandler(e) {
  if (e.charCode === Sys.UI.Key.enter) {
  //...
  }
}

(Sample shamelessly stolen from Bertrand Le Roy).