The Event Object

The Event Object has been supported since Internet Explorer 4.0 and Netscape 3.0 back in 1996. Properties of the event object are available for every event that occurs on every scriptable object within a document. Initially, the property names used were different, which complicated things, but they have since been standardized.

Of course, the most basic "events" in web pages are clicks on links and forms; they were supported in Nexus¹ (the very first browser)! The HTML Anchor tag: <A href="address">text</A>, causes the location url to change to the new "address" when the "text" is clicked. And Submit elements of the HTML Form tag will send data back to a server and display the response. However, those actions can't be chanced; they are not scriptable. So to use JavaScript, we must connect to the Event system via Event Handlers.

Connecting Scripts to Event Handlers

There are several ways to script an event. Most of this is related to history; it started simple and added power as it went.

Inline HTML Attributes

You can add an event handler to an HTML tag by simply including an "on"something attribute. E.g. click here
which looks like this:
click here.

This is generally considered to be a bad idea for several reasons: 1. It mixes HTML and JavaScript which makes both harder to read. 2. If you call a function, it has to be placed in a <script> section above the body to be sure it's defined before it gets called. 3. People decided it's bad and if you defy the group, they might point at you and laugh. So... Only use them for little simple obvious things. Like:

click me to turn this on and off

click me to turn this on and off

Even then, if you were going to do this more than once, it would be better to write a function and apply it via class or other means of selection.

Scripted Event Handler

Right from the start, the better way was to keep the script in the script area, and hook it into the element by selecting the element. e.g.

<P class="hideclass">click me <span>to turn this on and off</span></P>
<P class="hideclass">or click me <span>to hide this other thing</span></P>
<script>
for (x of document.getElementsByClassName("hideclass")){
	x.onclick=function(){
		let y=this.children[0];
		if (y.style.display=='none') {
			y.style.display='inline';
			} 
		else {
			y.style.display='none';
			}
		}
	}
</script>

click me to turn this on and off

addEventListener

One issue with just setting the event handler is that you can only have one. Triggering two different functions on one event would require an "uber" function that calls all the functions in turn. To resolve this, a "DOM Level 2" specification was release in 2000/11/13 which added a new system for attaching (and detaching) multiple functions to an event:
target.addEventListener(type, listener [, options]); Where type is the name of the event (e.g. "click"), listener is the function being added (don't include the () after the function name) and the options are... optional.

<P class="hideclass2">click me <span>to turn this on and off</span></P>
<P class="alertclass">click me to alert with <span>this text</span></P>
<P class="hideclass2 alertclass">click me to alert and hide <span>the text</span></P>
<!-- note that we have select two classes here; no comma between classes -->

<script>
function alertchild() { alert(this.children[0].innerText); }
function showhidechild() {
	let y=this.children[0]
	if (y.style.display=='none') {
		y.style.display='inline'
		} 
	else {
		y.style.display='none'
		}
	}
for (x of document.getElementsByClassName("alertclass")){
	x.addEventListener("click",alertchild )
//notice no () because we are setting the function, not calling it
	}
for (x of document.getElementsByClassName("hideclass2")){
	x.addEventListener("click",showhidechild)
//also notice, it's just click, not onclick
	}
</script>

click me to turn this on and off

click me to alert with this text

click me to alert and hide the text

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:

. . . Here's a paragraph, containing some bold and italic text </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:

. . . ...

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  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.

But we have only captured clicks so far, what other events can be captured?

Common Events

There are gobs and gobs of events. For the full list, see:
https://developer.mozilla.org/en-US/docs/Web/Events

MouseEvent

click, dblclick, mouseup, mousedown.

KeyboardEvent

keydown, keyup

DragEvent

drag

GlobalEvent

load

Comon Event object properties

(Internet Explorer 4.0 and all others)

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:

IE 4-8		IE >9 and all others
Value	Button pressed	Value	Button pressed
0	No mouse button pressed	0	Left mouse button pressed
1	Left mouse button pressed	1	Middle or wheel mouse button pressed
2	Right mouse button pressed	2	Right mouse button pressed
4	Middle button pressed	3	Back mouse button pressed
		4	Forward mouse 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.

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.

key
Returns a DOMString (basically a String) representing the key value of the key represented by the event.

keyCode (depreciated, use .key)
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 text </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.

Original Netscape 4.0 event object properties (old)
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)