Chapter 12 DOM Events
The DOM Level 2 Event Model was designed with two main goals. The first goal was to offer a generic model that would allow the registration of event handlers, flow for events to follow, and basic contextual information regarding the event. The second goal was to provide backward compatibility with the event models of DOM Level 0 and Level 1.
DocumentEvent
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
DOM Event object.
Description
The DocumentEvent object provides a mechanism by which the user can create an Event of a type supported by the implementation. It is expected that the DocumentEvent interface will be implemented on the same object which implements the Document interface in an implementation that supports the Event model. Contents of the EventException object are as follows:
Type | Item | Description |
Method |
| Creates a new event. |
Example
Listing 12.1 shows the creation of a mouse event object using the createEvent() of the DocumentEvent object. The event is then initialized using the initEvent() method.
Listing 12.1 Creating and Initializing a Mouse Event Using the createEvent() Method of the DocumentEvent Object
<html>
<script language="JScript">
<!--
var mouseEvent = DocumentEvent.createEvent("MouseEvent");
mouseEvent.initEvent("MouseEvent", true, false);
// -->
</script>
</html>
DocumentEvent.createEvent()
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
DocumentEvent.createEvent(eventType)
Description
The createEvent() method of the DocumentEvent object creates a new event of the specified eventType.
Example
Listing 12.2 shows the creation of a mouse event object using the CreateEvent() of the DocumentEvent object. The event is then initialized using the initEvent() method.
Listing 12.2 Creating and Initializing a Mouse Event Using the createEvent() Method of the DocumentEvent Object
<html>
<script language="JScript">
<!--
var mouseEvent = DocumentEvent.createEvent("MouseEvent");
mouseEvent.initEvent("MouseEvent", true, false);
// -->
</script>
</html>
Event
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
DOM Event object.
Description
The Event interface is used to provide contextual information about an event to the handler processing the event. An object that implements the Event interface is generally passed as the first parameter to an event handler. More specific context information is passed to event handlers by deriving additional interfaces from Event, which contain information directly relating to the type of event they accompany. The object passed to the event listener also implements these derived interfaces.
An Event is created by using the createEvent() method of the DocumentEvent object. Table 12.1 lists all constants, methods and properties of the Event object.
Table 12.1 Contents ofEvent Object
Example
Listing 12.3 illustrates the creation of an event using the createEvent() method of the DocumentEvent object.
Listing 12.3 Creating an Event Object
<html>
<script language="JScript">
<!--
var mouseEvent = DocumentEvent.createEvent("MouseEvent");
mouseEvent.initMouseEvent();
// -->
</script>
</html>
Event.type
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
eventObj.type
Description
The type property of the Event object identifies the name of the event.
Example
Listing 12.4 illustrates the creation of an EventListener function and checks the type property of an Event to see how it should be handled.
Listing 12.4 Reading the type Property of the Event Object
<html>
<script language="JScript">
<!--
function GenericEventHandler(evt) {
if(evt.type. == "MouseEvent") {
processMouseEvent(evt);
} else if(evt.type == "MutationEvent") {
processMutationEvent(evt);
}
}
// -->
</script>
</html>
Event.bubbles
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
eventObj.bubbles
Description
The bubbles property of the Event object is of type boolean and indicates whether this event can bubble.
Example
Listing 12.5 illustrates the creation of an EventListener function and checks the bubbles property of the evt parameter to determine whether the event bubbles.
Listing 12.5 Reading the bubbles Property of the Event Object
<html>
<script language="JScript">
<!--
function GenericEventHandler(evt) {
if(evt.bubbles)
handleBubblesEvent(evt);
}
// -->
</script>
</html>
Event.cancelable
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
eventObj.cancelable
Description
Used to indicate whether an event can have its default action prevented. If the default action can be prevented, the value is true; otherwise the value is false.
Example
Listing 12.6 illustrates the creation of an EventListener function and checks the cancelable property of the evt parameter to determine whether the event’s default action can be canceled.
Listing 12.6 Reading the cancelable Property of the Event Object
<html>
<script language="JScript">
<!--
function GenericEventHandler(evt) {
if(evt.cancelable)
handleCancelableEvent(evt);
}
// -->
</script>
</html>
Event.currentTarget
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
eventObj.currentTarget
Description
The target property of an Event object indicates the EventTarget object to which this event is currently being dispatched.
Example
Listing 12.7 illustrates the creation of an EventListener function and checks the currentTarget property of the Event object to see how the event should be handled.
Listing 12.7 Reading the currentTarget Property of the Event Object
<html>
<script language="JScript">
<!--
function GenericEventHandler(evt) {
var currentTarget = evt.currentTarget;
if(currentTarget.type == "TextArea")
handleTextAreaEvent(target);
}
// -->
</script>
</html>
Event.eventPhase
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
eventObj.eventPhase
Description
Indicates which phase of the event flow is being evaluated: Event.CAPTURING_PHASE, Event.AT_TARGET, or Event.BUBBLING_PHASE.
Example
Listing 12.8 illustrates the creation of an EventListener function and checks the eventPhase property of the evt parameter to determine at what phase the event is in.
Listing 12.8 Reading the eventPhase Property of the Event Object
<html>
<script language="JScript">
<!--
function GenericEventHandler(evt) {
if(evt.eventPhase == Event.bubblingPhase)
processEventAtBubblingPhase(evt);
}
// -->
</script>
</html>
Event.initEvent()
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
eventObj.initEvent(eventType, canBubble, cancelable)
Description
The initEvent() method of the Event object is used to initialize the value of an Event
created using the createEvent() of the DocumentEvent object. This method can only be called before the Event has been dispatched via the dispatchEvent() method, although it can be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence. If called from a subclass of the Event
interface, only the values specified in the initEvent() method are modified: All other attributes are left unchanged. The eventType parameter is a string that specifies the event type,canBubble specifies whether this event can bubble, and cancelable specifies whether the event’s default action can be prevented.
Example
Listing 12.9 shows the creation of a mouse event object using the CreateEvent() of the DocumentEvent object. The event is then initialized using the initEvent() method.
Listing 12.9 Creating and Initializing a Mouse Event Using the initEvent() Method of the Event Object
<html>
<script language="JScript">
<!--
var mouseEvent = DocumentEvent.createEvent("MouseEvent");
mouseEvent.initEvent("MouseEvent", true, false);
// -->
</script>
</html>
Event.preventDefault()
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
eventObj.preventDefault()
Description
If an event is cancelable, the preventDefault() method of the Event object is used to signify that the event is to be canceled, meaning any default action normally taken by the implementation as a result of the event will not occur. If, during any stage of event flow, the preventDefault() method is called, the event is canceled. Any default action associated with the event will not occur. Calling this method for a non-cancelable event has no effect. After preventDefault() has been called, it will remain in effect throughout the remainder of the event’s propagation. This method can be used during any stage of event flow.
Example
Listing 12.10 illustrates the prevention of the default behavior if an event is cancelable.
Listing 12.10 Invoking the preventDefault() Method of the Event Object
<html>
<script language="JScript">
<!--
function GenericEventHandler(evt) {
if(evt.cancelable)
evt.preventDefault();
}
// -->
</script>
</html>
Event.stopPropagation()
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
eventObj.stopPropagation()
Description
The stopPropagation() method of the Event object is used prevent further propagation of an event during event flow. If any EventListener calls this method, the event will cease propagating through the tree. The event will complete dispatch to all listeners on the current EventTarget before event flow stops. This method can be used during any stage of event flow.
Example
Listing 12.11 illustrates the stoppage of the event flow of an event currently in the AT_TARGET phase.
Listing 12.11 Calling the stopPropagation() Method of the Event Object
<html>
<script language="JScript">
<!--
function GenericEventHandler(evt) {
if(evt.eventPhase = Event.AT_TARGET)
evt.stopPropagation();
}
// -->
</script>
</html>
Event.target
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
eventObj.target;
Description
The target property of the Event object indicates the EventTarget object to which this event was originally dispatched.
Example
Listing 12.12 illustrates the creation of an EventListener function and checks the target property of the Event object to see how the event should be handled.
Listing 12.12 Reading the target Property of the Event Object
<html>
<script language="JScript">
<!--
function GenericEventHandler(evt) {
var target = evt.target;
if(target.type == "TextArea")
handleTextAreaEvent(target);
}
// -->
</script>
</html>
Event.timeStamp
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
eventObj.timeStamp
Description
The timeStamp property of the Event object is used to specify the time (in milliseconds relative to the epoch) at which the event was created. Because some systems might not provide this information, the value of timeStamp might not be available for all events. When not available, a value of 0 will be returned. Examples of epoch time are the time of the system start or 0:0:0 UTC 1st January 1970. The timeStamp property is an object of type Date.
Example
Listing 12.13 illustrates the creation of an event handler that behaves differently depending on the time when the event originated.
Listing 12.13 Reading the timeStamp Property of the Event Object
<html>
<script language="JScript">
<!--
function GenericEventHandler(evt) {
if(evt.timeStamp < '11/24/2000')
handleTS(evt.timeStamp);
}
// -->
</script>
</html>
EventException
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
DOM Event object.
Description
The EventException object is thrown when an exception condition is met while evaluating certain methods of other DOM Event objects. Table 12.2 lists the constants and properties for the EventException object.
Table 12.2 Contents of EventException Object
Example
Listing 12.14 illustrates the catching of an EventException object and reading its code property.
Listing 12.14 Declaring an EventListener Function
<html>
<script language="JScript">
<!--
function MouseEventHandler(evt) {
if(evt.type == "MouseEvent") {
if(evt.clientX ==5) && (evt.clientY ==5)
showDialog();
}
}
try {
var htmlDocument =
HTMLDOMImplementation.createHTMLDocument("My HTML Page");
var textArea = htmlDocument.createElement("TextArea");
textArea.addEventListener("MouseEvent", MouseEventHandler ,false);
var mouseEvent = DocumentEvent.createEvent("MouseEvent");
mouseEvent.initMouseEvent();
textArea.dispatchEvent(mouseEvent);
}catch(evt) {
if(evt.code == EventException.UNSPECIFIED_EVENT_TYPE_ERR)
handleUnexpectedEvent(evt);
}
// -->
</script>
</html>
EventException.code
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
eventExceptionObj.code
Description
The code property of the EventException object contains the numeric code representing the actual exception.
Example
Listing 12.15 illustrates the catching of an EventException object and reading its code property.
Listing 12.15 Declaring an EventListener Function
<html>
<script language="JScript">
<!--
function MouseEventHandler(evt) {
if(evt.type == "MouseEvent") {
if(evt.clientX ==5) && (evt.clientY ==5)
showDialog();
}
}
try {
var htmlDocument =
HTMLDOMImplementation.createHTMLDocument("My HTML Page");
var textArea = htmlDocument.createElement("TextArea");
textArea.addEventListener("MouseEvent", MouseEventHandler ,false);
var mouseEvent = DocumentEvent.createEvent("MouseEvent");
mouseEvent.initMouseEvent();
textArea.dispatchEvent(mouseEvent);
}catch(evt) {
if(evt.code == EventException.UNSPECIFIED_EVENT_TYPE_ERR)
handleUnexpectedEvent(evt);
}
// -->
</script>
</html>
EventListener
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
DOM Event object.
Description
The EventListener is simply a function reference that takes an object of type Event as an argument. When the event listener is registered, the body of the function will be executed when an specified type of event occurs.
Example
Listing 12.16 shows the declaration of an EventListener and then illustrates the registration of the listener with a TextArea object.
Listing 12.16 Declaring an EventListener Function
<html>
<script language="JScript">
<!--
function MouseEventHandler(evt) {
if(evt.type == "MouseEvent") {
if(evt.clientX ==5) && (evt.clientY ==5)
showDialog();
}
}
var htmlDocument =
HTMLDOMImplementation.createHTMLDocument("My HTML Page");
var textArea = htmlDocument.createElement("TextArea");
textArea.addEventListener("MouseEvent", MouseEventHandler ,false);
var mouseEvent = DocumentEvent.createEvent("MouseEvent");
mouseEvent.initMouseEvent();
textArea.dispatchEvent(mouseEvent);
// -->
</script>
</html>
EventTarget
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
DOM Event object.
Description
Specified by an Event object’s target attribute, the EventTarget represents the object that an event is directed to by the DOM implementation. When the event reaches the target, all appropriate EventListeners are triggered.
All Node objects from a DOM implementation that supports the DOM Level 2 Event Model inherit from EventTarget. Table 12.1 shows all methods available for the EventTarget object. Table 12.3 lists all of the methods of the EventTarget object.
Table 12.3 Contents of the EventTarget Object
Example
Listing 12.17 demonstrates the assignment of an event target and fires off an event.
Listing 12.17 Assigning and Sending an Event Using the dispatchEvent() Method of the EventTarget Object
<html>
<script language="JScript">
<!--
function MouseEventHandler(evt) {
if(evt.type == "MouseEvent") {
if(evt.clientX ==5) && (evt.clientY ==5)
showDialog();
}
}
var htmlDocument = HTMLDOMImplementation.createHTMLDocument("My HTML Page");
var textArea = htmlDocument.createElement("TextArea");
textArea.addEventListener("MouseEvent", MouseEventHandler ,false);
var mouseEvent = DocumentEvent.createEvent("MouseEvent");
mouseEvent.initMouseEvent();
textArea.dispatchEvent(mouseEvent);
// -->
</script>
EventTarget.addEventListener()
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
targetObj.addEventListener(type, listener, useCapture);
Description
The addEventListener() method of the EventTarget object adds an event listener to this target. Type is the event type to be listened for, the listener parameter is the actual listener function call, and useCapture is a Boolean field that determines whether the event can be intercepted by an event listener found in an ancestor of the target.
Example
Listing 12.18 demonstrates the assignment of an event listener and fires off an event.
Listing 12.18 Assigning and Sending an Event Using the addEventListener() Method of the EventTarget Object
<html>
<script language="JScript">
<!--
function MouseEventHandler(evt) {
if(evt.type == "MouseEvent") {
if(evt.clientX ==5) && (evt.clientY ==5)
showDialog();
}
}
var htmlDocument = HTMLDOMImplementation.createHTMLDocument("My HTML Page");
var textArea = htmlDocument.createElement("TextArea");
textArea.addEventListener("MouseEvent", MouseEventHandler ,false);
var mouseEvent = DocumentEvent.createEvent("MouseEvent");
mouseEvent.initMouseEvent();
textArea.dispatchEvent(mouseEvent);
// -->
</script>
</html>
EventTarget.dispatchEvent()
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
eventTargetObj.dispatchEvent(evt);
Description
The dispatchEvent() method of the EventTarget object directs the event evt to this EventTarget object.
Example
Listing 12.19 demonstrates using the dispatchEvent() method to direct a mouse event to an HTML TextArea object.
Listing 12.19 Dispatching a MouseEvent Using the dispatchEvent() Method of the EventTarget Object
<html>
<script language="JScript">
<!--
function MouseEventHandler(evt) {
if(evt.type == "MouseEvent") {
if(evt.clientX ==5) && (evt.clientY ==5)
showDialog();
}
}
var htmlDocument = HTMLDOMImplementation.createHTMLDocument("My HTML Page");
var textArea = htmlDocument.createElement("TextArea");
textArea.addEventListener("MouseEvent", MouseEventHandler ,false);
var mouseEvent = DocumentEvent.createEvent("MouseEvent");
mouseEvent.initMouseEvent();
textArea.dispatchEvent(mouseEvent);
// -->
</script>
</html>
EventTarget.removeEventListener()
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
eventListenerObj.removeListener(type, listener, useCapture)
Description
The removeEventListener() method of the EventTarget object removes the described and referenced listener from the list of event listeners maintained by this event target. type is the event type to being listened for, the listener parameter is the actual listener function call, and useCapture is a Boolean field that determines whether the event can be intercepted by an event listener found in an ancestor of the target.
Example
Listing 12.20 demonstrates removing an event listener from the first TextArea object that appears in an HTML document.
Listing 12.20 Removing an Event Listener Using the removeEventListener() Method of the EventTarget Object
<html>
<script language="JScript">
<!--
function MouseEventHandler(evt) {
if(evt.type == "MouseEvent") {
if(evt.clientX ==5) && (evt.clientY ==5)
showDialog();
}
}
var htmlDocument = HTMLDOMImplementation.createHTMLDocument("My HTML Page");
var textAreaList = htmlDocument.getElementsByTagName("TextArea");
var firstTextArea = textAreaList.index(0);
firstTextArea.removeEventListener("MouseEvent", MouseEventHandler, false);
// -->
</script>
</html>
MouseEvent
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
DOM Event object.
Description
The MouseEvent object provides specific contextual information associated with mouse events. The MouseEvent object inherits all properties and methods from the UIMethod object. Table 12.4 lists all of the properties and methods of the MouseEvent object.
Table 12.4 Contents of MouseEvent Object
Example
Listing 12.21 shows the creation of a mouse event object using the createEvent() method of the DocumentEvent object. The event is then initialized using the initEvent() method.
Listing 12.21 Creating and Initializing a MouseEvent
<html>
<script language="JScript">
<!--
var mouseEvent = DocumentEvent.createEvent("MouseEvent");
mouseEvent.initMouseEvent("click", true, false, );
// -->
</script>
</html>
MouseEvent.altKey
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
mouseEventObj.altKey
Description
Used to indicate whether the Alt key was depressed during the firing of the event. On some platforms, this key might map to an alternative key name.
Example
Listing 12.22 illustrates an event listener method as well as inspecting the altKey property if the event is a "click" mouse event.
Listing 12.22 Event Listener Inspecting altKey
<html>
<script language="JScript">
<!--
function handleMouseEvent(evt) {
if((evt.type == "click") && (evt.altKey))
processClickAndCTRL(evt);
// -->
</script>
</html>
MouseEvent.button
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
mouseEventObj.Button
Description
During mouse events caused by the depression or release of a mouse button, button is used to indicate which mouse button changed state. The values for button range from 0 to indicate the left button of the mouse, 1 to indicate the middle button if present, and 2 to indicate the right button. In mice configured for left-handed use in which the button actions are reversed, the values are instead read from right to left.
Example
Listing 12.23 illustrates an event listener method as well as inspecting which mouse button was pressed if the event is a "click" mouse event.
Listing 12.23 Event Listener Inspecting the button Property of the MouseEvent Object
<html>
<script language="JScript">
<!--
function handleMouseEvent(evt) {
if((evt.type == "click") && (evt.button == 0))
processLeftMouseClick(evt);
if((evt.type == "click") && (evt.button == 1))
processMiddleMouseClick(evt);
if((evt.type == "click") && (evt.button == 2))
processRightMouseClick(evt);
// -->
</script>
</html>
MouseEvent.clientX
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
mouseEventObj.clientX
Description
The clientX property of the MouseEvent object represents the horizontal coordinate at which the event occurred relative to the DOM implementation’s client area.
Example
Listing 12.24 illustrates an event listener method as well as inspecting the clientX property if the event is a "click" mouse event.
Listing 12.24 Event Listener Inspecting clientX
<html>
<script language="JScript">
<!--
function handleMouseEvent(evt) {
if(evt.type == "click")
processXLocation(evt.clientX);
}
// -->
</script>
</html>
MouseEvent.clientY
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
mouseEventObj.clientY
Description
The clientY property of the MouseEvent object represents the vertical coordinate at which the event occurred relative to the DOM implementation’s client area.
Example
Listing 12.25 illustrates an event listener method as well as inspecting the clientY property if the event is a "click" mouse event.
Listing 12.25 Event Listener Inspecting clientY
<html>
<script language="JScript">
<!--
function handleMouseEvent(evt) {
if(evt.type == "click")
processXLocation(evt.clientY);
}
// -->
</script>
</html>
MouseEvent.ctrlKey
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
mouseEventObj.ctrlKey
Description
Used to indicate whether the CTRL key was depressed during the firing of the event.
Example
Listing 12.26 illustrates an event listener method as well as inspecting the ctrlKey property if the event is a "click" mouse event.
Listing 12.26 Event Listener Inspecting ctrlKey
<html>
<script language="JScript">
<!--
function handleMouseEvent(evt) {
if((evt.type == "click") && (evt.ctrlKey))
processClickAndCTRL(evt);
// -->
</script>
</html>
MouseEvent.initMouseEvent()
JavaScript 1.5+, JScript
5.0+ Nav6+, IE5+
Syntax
mouseEventObj.initMouseEvent(type, canBubble, cancelable, view, detail,
screenX, screenY, clientX, clientY, ctrlKey, altKey, shiftKey, metaKey,
button, relatedTarget)
Description
The initMouseEvent() method of the MouseEvent object is used to initialize the value of a MouseEvent created through the DocumentEvent object. This method can only be called before the MouseEvent has been dispatched via the dispatchEvent() method, although it can be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence.
The following types of mouse events are supported by DOM Level 2: click, mouseup, mousedown, mouseover, mousemove, and mouseout.
Example
Listing 12.27 shows the creation of a mouse event object using the createEvent() of the DocumentEvent object. The event is then initialized using the initEvent() method to initialize it.
Listing 12.27 Creating and Initializing a Mouse Event
<html>
<script language="JScript">
<!--
var mouseEvent = DocumentEvent.CreateEvent("MouseEvent");
mouseEvent.initMouseEvent("click", true, false, );
// -->
</script>
</html>
MouseEvent.metaKey
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
mouseEventObj.metaKey
Description
The metaKey property of the MouseEvent object is used to indicate whether the META key was depressed during the firing of the event. On some platforms, this key might map to an alternative key name.
Example
Listing 12.28 illustrates an event listener method as well as inspecting the metaKey property if the event is a "click" mouse event.
Listing 12.28 Event Listener Inspecting metaKey
<html>
<script language="JScript">
<!--
function handleMouseEvent(evt) {
if((evt.type == "click") && (evt.metaKey))
processClickAndCTRL(evt);
// -->
</script>
</html>
MouseEvent.relatedTarget
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
mouseEvent.relatedTarget
Description
The relatedTarget property of the MouseEvent object is used to identify a secondary EventTarget related to a UI event. Currently, this attribute is used with the mouseover event to indicate the EventTarget, which the pointing device exited, and with the mouseout event to indicate the EventTarget, which the pointing device entered.
Example
Listing 12.29 illustrates reading the relatedTarget property of the MouseEvent object.
Listing 12.29 Event Listener Inspecting relatedTarget
<html>
<script language="JScript">
<!--function handleMouseEvent(evt) {
if(evt.relatedTarget == otherTarget
processSecondaryTarget(otherTarget);
}
// -->
</script>
</html>
MouseEvent.screenX
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
mouseEventObj.screenX
Description
The screenX property of the MouseEvent object represents the horizontal coordinate at which the event occurred relative to the origin of the screen coordinate system.
Example
Listing 12.30 illustrates an event listener method as well as inspecting the screenX property if the event is a "click" mouse event.
Listing 12.30 Event Listener Inspecting screenX
<html>
<script language="JScript">
<!--
function handleMouseEvent(evt) {
if(evt.type == "click")
processXLocation(evt.ScreenX);
}
// --> </script>
</html>
MouseEvent.screenY
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
mouseEventObj.screenY
Description
The screenY property of the MouseEvent object represents the vertical coordinate at which the event occurred relative to the origin of the screen coordinate system.
Example
Listing 12.31 illustrates an event listener method as well as inspecting the screenY property if the event is a "click" mouse event.
Listing 12.31 Event Listener Inspecting screenY
<html>
<script language="JScript">
<!--
function handleMouseEvent(evt) {
if(evt.type == "click")
processXLocation(evt.screenY);
}
// --> </script>
</html>
MouseEvent.shiftKey
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
mouseEventObj.shiftKey
Description
The shiftKey property of the MouseEvent object is used to indicate whether the Shift key was depressed during the firing of the event.
Example
Listing 12.32 illustrates an event listener method as well as inspecting the shiftKey property if the event is a "click" mouse event.
Listing 12.32 Event Listener Inspecting shiftKey
<html>
<script language="JScript">
<!--
function handleMouseEvent(evt) {
if((evt.type == "click") && (evt.shiftKey))
processClickAndSHIFT(evt);
// -->
</script>
</html>
MutationEvent
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
DOM Event object.
Description
The MutationEvent object is designed to allow notification of any changes to the structure of a document, including Attr and Text modifications. It might be noted that none of the mutation events listed are designated as cancelable. This stems from the fact that it is very difficult to make use of existing DOM objects that cause document modifications if any change to the document might or might not take place because of the cancellation of the related event. Although this is still a desired capability, it was decided that it would be better left until the addition of transactions into the DOM. Many single modifications of the tree can cause multiple mutation events to be fired. Rather than attempt to specify the ordering of mutation events because of every possible modification of the tree, the ordering of these events is left to the implementation.
A DOM application can use the hasFeature() method of the DOMImplementation object with parameter values MutationEvents and 2.0 (respectively) to determine whether the mutation event module is supported by the implementation. Table 12.5 lists all of the constants, properties, and methods of the MutationEvent object.
Table 12.5 Contents of the MutationEventObject
Example
Listing 12.33 shows the creation of a mutation event object using the createEvent() of the DocumentEvent object. The event is then initialized using the initEvent() method to initialize it.
Listing 12.33 Creating and Initializing a Mutation Event
<html>
<script language="JScript">
<!--
var mutationEvent = DocumentEvent.createEvent("MutationEvent");
mutationEvent.initEvent("DOMNodeInserted", true, false, relatedNode,
prevValue, newValue, attrName, attrChange);
// -->
</script>
</html>
MutationEvent.relatedNode
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
mutationEventObj.relatedNode
Description
The relatedNode property of the MutationEvent object is used to identify a secondary node related to a mutation event. For example, if a mutation event is dispatched to a node indicating that its parent has changed, the relatedNode is the changed parent. If an event is instead dispatched to a subtree indicating a node was changed within it, the relatedNode is the changed node. In the case of the DOMAttrModified event it indicates the Attr node which was modified, added, or removed.
Example
Listing 12.34 shows the creation of a mutation event object using the createEvent() of the DocumentEvent object. The event is then initialized using the initEvent() method to initialize it.
Listing 12.34 Creating and Initializing a Mutation Event
<html>
<script language="JScript">
<!--
var mutationEvent = DocumentEvent.createEvent("MutationEvent");
mutationEvent.initEvent("DOMNodeInserted", true, false, relatedNode,
prevValue, newValue, attrName, attrChange);
// -->
</script>
</html>
MutationEvent.attrChange
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
mutationEvent.attrChange
Description
The attrChange property of the MutationEvent object indicates the type of change that triggered the DOMAttrModified event. The values can be MODIFICATION, ADDITION, or REMOVAL.
Example
Listing 12.35 checks the attrChange property to determine how an attribute was modified and handles the event accordingly.
Listing 12.35 Examining the attrChange Property
<html>
<script language="JScript">
<!--
function handleMutation(evt) {
if(evt.attrChange == MutationEvent.ADDITION)
handleTextAreaAddition(evt);
// -->
</script>
</html>
MutationEvent.attrName
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
mutationEvent.attrName
Description
The attrName property of the MutationEvent object indicates the name of the changed Attr node in a DOMAttrModified event.
Example
Listing 12.36 checks the attrName property to determine if the modified attribute is a TextArea. If so, the event is handled appropriately.
Listing 12.36 Examining the attrName Property
<html>
<script language="JScript">
<!--
function handleMutation(evt) {
if(evt.attrName == "TextArea")
handleTextAreaModification(evt);
// -->
</script>
</html>
MutationEvent.initMutationEvent()
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
mutationEventObj.initMutationEvent(type, canBubble, cancelable,
relatedNode, prevValue, newValue, attrName, attrChange)
Description
The initMutationEvent() method is used to initialize the value of a MutationEvent created using the DocumentEvent object. This method can only be called before the MutationEvent has been dispatched via the dispatchEvent() method, though it can be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence.
The possible values for type are DOMSubTreeModified, DOMNodeInserted, and DOMNodeRemoved.
Example
Listing 12.37 shows the creation of a mutation event object using the createEvent() of the DocumentEvent object. The event is then initialized using the initEvent() method to initialize it.
Listing 12.37 Creating and Initializing a MutationEvent
<html>
<script language="JScript">
<!--
var mutationEvent = DocumentEvent.createEvent("MutationEvent");
mutationEvent.initMutationEvent
("DOMNodeInserted", true, false, relatedNode,
prevValue, newValue, attrName, attrChange);
// -->
</script>
</html>
MutationEvent.newValue
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
mutationEventObj.newValue
Description
The newValue property of the MutationEvent object indicates the new value of the Attr node in DOMAttrModified events and of the CharacterData node in DOMCharDataModified events.
Example
Listing 12.38 checks the prevValue and newValue properties to determine whether any actual changes have occurred to the Attr in question.
Listing 12.38 Comparing prevValue and newValue
<html>
<script language="JScript">
<!--
function handleMutation(evt) {
if(evt.prevValue == evt.newValue)
handleUnchangedEvent(evt);
// -->
</script>
</html>
MutationEvent.prevValue
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
mutationEventObj.prevValue
Description
The prevValue property indicates the previous value of the Attr node in DOMAttrModified events, and of the CharacterData node in DOMCharDataModified events.
Example
Listing 12.39 checks the prevValue and newValue properties to determine whether any actual changes have occurred to the Attr in question.
Listing 12.39 Comparing prevValue and newValue
<html>
<script language="JScript">
<!--
function handleMutation(evt) {
if(evt.prevValue == evt.newValue)
handleUnchangedEvent(evt);
// -->
</script>
</html>
UIEvent
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
DOM Event object.
Description
The UIEvent object provides specific contextual information associated with User Interface events. The UIEvent object inherits all properties and methods from the Event object. Table 12.6 lists the properties and methods of the UIEvent object.
Table 12.6 Contents of the UIEvent Object
Example
Listing 12.40 shows the creation of a user interface event object using the createEvent() method of the DocumentEvent object. The event is then initialized using the initUIEvent() method.
Listing 12.40 Creating and Initializing a User Interface Event Using the initUIEvent() Method of the UIEvent Object
<html>
<script language="JScript">
<!--
var uiEvent = DocumentEvent.createEvent("UIEvent");
uiEvent.initUIEvent("DOMFocusOut", true, false, );
// -->
</script>
</html>
UIEvent.detail
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
uiEventObj.detail
Description
The detail property of the UIEvent object specifies some detail information about the Event, depending on the type of event.
Example
Listing 12.41 shows the creation of a user interface event object using the createEvent() method of the DocumentEvent object. The event is then initialized using the initEvent() method. After initialization, the detail property is written to.
Listing 12.41 Writing the detail Property of the UIEvent Object
<html>
<script language="JScript">
<!--
var uiEvent = DocumentEvent.createEvent("UIEvent");
uiEvent.initUIEvent("DOMFocusOut", true, false, );
uiEvent.detail =
// -->
</script>
</html>
UIEvent.initUIEvent()
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
uiEventObj.initUIEvent(type , canBubble, cancelable, view, detail)
Description
The initUIEvent() method of the UIEvent object is used to initialize the value of an UIEvent created through the DocumentEvent object. This method can only be called before the UIEvent has been dispatched via the dispatchEvent() method, although it can be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence.
The type parameter is a string that can be DOMFocusIn, DOMFocusOut, or DOMActivate. The canBubble parameter indicates whether this event can bubble, the cancelable parameter indicates whether this event can be canceled,view is the AbstractView object in which this UIEvent originated, and detail is a number that represents some type of detailed information regarding an UIEvent of the specified type.
Example
Listing 12.42 shows the creation and initialization of a UIEvent using the initUIEvent() method.
Listing 12.42 Creating and Initializing a User Interface Event
<html>
<script language="JScript">
<!--
var mouseEvent = DocumentEvent.createEvent("UIEvent");
mouseEvent.initUIEvent("DOMFocusOut", true, false, );
// -->
</script>
</html>
UIEvent.view
JavaScript 1.5+, JScript 5.0+
Nav6+, IE5+
Syntax
uiEventObj.view
Description
The view property of the UIEvent object identifies the AbstractView from which the event was generated.
Example
Listing 12.43 show the writing of the view property of the UIEvent object.
Listing 12.43 Creating and Initializing a User Interface Event
<html>
<script language="JScript">
<!--
var uiEvent = DocumentEvent.CreateEvent("UIEvent");
uiEvent.InitUIEvent("DOMFocusOut", true, false, );
uiEvent.view = "display";
// -->
</script>
</html>