The Event Object

The Event Object is supported by both Internet Explorer 4.0 and Netscape (from 3.0). Properties of the event object are available for every event that occurs on every scriptable object within a document. However, while both browsers support it, the property names supported by each are different, which complicates things slightly. Below is a description of the properties, with a section for each browser.

Internet Explorer 4.0 event object properties.
altKey
The altKey property has a boolean value, which is true if the Alt key was pressed at the time of the event occuring, false if it wasn't.

button
The button property contains an integer value which represents which of the mouse buttons were used when the event occurred. The possible values are:

Value Button pressed
0 No mouse button pressed
1 Left mouse button pressed
2 Right mouse button pressed
4 Middle button pressed

cancelBubble
For events that 'bubble', the cancelBubble property can be used to allow the event to bubble, or to prevent the event from bubbling. It takes boolean values of true or false.

Hold on, what's 'Event Bubbling'?
Within a document, when certain events occur on elements, if that element doesn't have an event handler set for the event that occurred, then the event will rise successive levels in the document hierarchy, until it finds an event handler for the particular event. When it finds an event handler, it will perform whatever scripting is set for the event. If it rises ('bubbles') to the top of the document hierarchy (i.e. reaches the <BODY> element without finding an event handler, then nothing happens for the event. For example, consider the following document:

. . .
<P OnClick="alert ('P clicked')">Here's a paragraph, containing <STRONG OnClick="alert ('STRONG clicked')">some bold and <EM OnClick="alert ('EM clicked')">italic</EM> text</STRONG>
</BODY>

which displays as:

Here's a paragraph, containing some bold and italic text

Whichever section of the document you click on, a variety of Onclick event will occur. Play around, clicking different parts to see what happens. To prevent an event from bubbling, the cancelBubble property of the event needs to be set to true. For example, if we add:

. . .
<EM OnClick="alert ('EM clicked');self.event.cancelBubble=true">
...

Then we get:

Here's a paragraph, containing some bold and italic text

Now, clicking on the italicised text will prevent the event from 'bubbling' and so only one alert will be presented. Clicking on the contents of the <STRONG> element will still allow the event to bubble though.

Knowledge of event bubbling only really becomes a serious requirement if you have nested event handlers of the same type (as above). If you don't consider what happens when events bubble, then things may not happen as you wish them to.

clientX
The clientX property of the event object returns the horizontal position of the mouse when the event occurred, relative to the origin of the current viewing area. Note that this is subtly different to the offsetX and X properties. See the X-positioning example below.

clientY
The clientY property of the event object returns the vertical position of the mouse when the event occurred, relative to the origin of the current viewing area. Note that this is subtly different to the offsetY and Y properties. The X-positioning example below also applies to the *y position properties of the event object.

ctrlKey
The ctrlKey property has a boolean value, which is true if the Ctrl key was pressed at the time of the event occuring, false if it wasn't.

fromElement
The fromElement property of the event object is of use for onmouseover and onmouseout events. It contains a reference to the element object that the mouse cursor has moved from in order for the respective onmouseover or onmouseout event to occur.

keyCode
The keyCode property contains the UNICODE key character associated with the key that was pressed to cause the onkeypress, onkeydown or onkeyup event to occur. Note that setting this property in any event handler code causes the new code to be sent with the event object should the event 'bubble' up the document hierarchy.

offsetX
The offsetX property contains a value which represents the mouse position relative to the srcElement's containing element in the object hierarchy. See the X-positioning example below.

offsetY
The offsetY property contains a value which represents the mouse position relative to the srcElement's containing element in the object hierarchy. The X-positioning example below also applies to the *y position properties of the event object.

reason
When data bound element objects submit data back to the data source, the reason property of the event object contains an integer value representing the reason for the data-transfer completion. Its values can be:

Value Reason
0 Data transfer was successful
1 Data transfer aborted
2 A data transfer error occurred

For more information on data binding, see the Data binding.

returnValue
The returnValue property of the event object represents the return value for the event object. It accepts a boolean value and setting the returnValue property to false will cancel the default action of the event on the element that received it. For example, the default action on clicking a link is to navigate to the URL in the HREF attribute of the link. If self.event.returnValue=false is set for the onclick event handler in an <A> element, then the new document navigation will no occur.

screenX
The screenX property represents the mouse position at the time of the event occuring, relative to the left-most edge of the users screen. See the X-positioning example below.

screenY
The screenY property represents the mouse position at the time of the event occuring, relative to the top of the users screen. The X-positioning example below also applies to the *y position properties of the event object.

shiftKey
The shiftKey property has a boolean value, which is true if the Shift key was pressed at the time of the event occuring, false if it wasn't.

srcElement
The srcElement property contains a reference to the element object that originally received the event. It's useful when handling events at a top-level. For example, within a document, all onclick events could be handled by the Document Object and the srcElement property could be use to determine what object was clicked and act accordingly.

srcFilter
The srcFilter property contains a reference to the Filter caused the onfilterchange event to occur.

toElement
The toElement property of the event object is of use for onmouseover and onmouseout events. It contains a reference to the element object that the mouse cursor is moving to in order for the respective onmouseover or onmouseout event to occur.

type
The type property contains a string value, which defines the event that has occurred (i.e. 'click' for an onclick event etc.)

x
The x property represents the mouse cursors horizontal position, relative to the next style sheet positioned element up the element hierarchy. (For information about the Style Sheet positioning attributes, see the Positioning attributes topic.) If no element above the source element has been positioned using Style Sheet positioning, then the x property reflects the horizontal mouse position relative to the documents <BODY> element.

y
The y property represents the mouse cursors vertical position, relative to the next style sheet positioned element up the element hierarchy. (For information about the Style Sheet positioning attributes, see the Positioning attributes topic.) If no element above the source element has been positioned using Style Sheet positioning, then the y property reflects the vertical mouse position relative to the documents <BODY> element.

Example for the *x properties
Consider the following document fragment:

<TABLE ID="TABLE1">
<TR ID="TR1">
<TD="TD1">
Here's some <STRONG OnClick="showPos()">strong text</STRONG>
</TD>
</TR>
</TABLE>

which displays as:

Here's some strong text

clicking on the 'strong text' section will display the offsetX, clientX, screenX and x properties of the event object when the onclick event is fired. The offsetX value represents the horizontal position of the mouse relative to the event source elements containing element (i.e the <TD> element). The clientX property represents the horizontal position of the mouse relative to the current viewing area (i.e. the left-most edge of the 'content' frame. The screenX property returns the x-position relative to the screen and the x position returns the same as clientX, as the <TD> element has not been positioned using CSS positioning attributes.


Netscape 4.0 event object properties.
data
If a DragDrop event occurs (firing an ondragdrop event for the Window Object, then the data property contains an array of string values, representing the URL's of all the objects that were dropped on the navigator window.

layerX
The layerX property represents the mouse cursors horizontal position relative to the left-most edge of the layer object in which the event occurred.

layerY
The layerY property represents the mouse cursors vertical position relative to the left-most edge of the layer object in which the event occurred.

modifiers
The modifiers property covers the various special keyboard keys that can be pressed when an event occurs. The modifiers property returns a string value of either ALT_MASK, CONTROL_MASK, SHIFT_MASK or META_MASK depending on which of the keys were pressed when the event occurred. (c.f. altKey, ctrlKey and shiftKey for Internet Explorer 4.0)

pageX
The pageX property reflects the mouse cursors horizontal position at the time of the event occuring, relative to the current viewing window. (c.f. clientX for Internet Explorer 4.0)

pageY
The pageY property reflects the mouse cursors vertical position at the time of the event occuring, relative to the current viewing window. (c.f. clientY for Internet Explorer 4.0)

screenX
The screenX property reflects the mouse cursors horizontal position at the time of the event occuring, relative to the users screen. (c.f. screenY for Internet Explorer 4.0)

screenY
The screenY property reflects the mouse cursors vertical position at the time of the event occuring, relative to the users screen. (c.f. screenX for Internet Explorer 4.0)

target
The target property contains a string value representing the object to which the event was originally sent (e.g. for an <A> anchor object, the target property will return a string, corresponding to the HREF attribute value setting for the <A> element clicked.)

type
The type property returns a string representing the event type that occurred (i.e. 'click' for an onclick event etc.)

which
The which property returns a number specifying which mouse button was pressed at the time of the event occuring, or the ASCII code of the key that was pressed. (c.f. button, keyCode for Internet Explorer 4.0)