Description

The Event object serves to provide both details about an event and control over the propagation of an event. DOM Level 2 defines a standard Event object, but Internet Explorer 4, 5, and 6 use a proprietary object instead. Netscape 4 has its own proprietary object that is different from the other two. DOM Level 2 does not standardize keyboard events, so the Netscape 4 Event object may be still useful to programmers interested in key events in Netscape 6 and later. The properties of the DOM, IE, and Netscape 4 Event objects are listed in separate sections below.

In the DOM and Netscape event models, an Event object is passed as an argument to the event handler. In the IE event model, the Event object that describes the most recent event is instead stored in the event property of the Window object.

DOM Constants

These constants are the legal values of the eventPhase property; they represent the current phase of event propagation for this event.

Event.CAPTURING_PHASE = 1

The event is in its capturing phase.

Event.AT_TARGET = 2

The event is being handled by its target node.

Event.BUBBLING_PHASE = 3

The event is bubbling.

DOM Properties

All properties of this object are read-only.

altKey

true if the Alt key was held down when an event occurred. Defined for mouse events.

bubbles

true if the event is of a type that bubbles; false otherwise. Defined for all events.

button

Specifies which mouse button changed state during a mousedown, mouseup, or click event. 0 indicates the left button, 1 indicates the middle button, and 2 indicates the right button. Note that this property is only defined when a button changes state: it is not used to report whether a button is held down during a mousemove event, for example. Also, this property is not a bitmap: it cannot tell you if more than one button is held down. Netscape 6.0 uses the values 1, 2, and 3 instead of 0, 1, and 2. This is fixed in Netscape 6.1.

cancelable

true if the default action associated with the event can be canceled with preventDefault( ), false otherwise. Defined for all events.

clientX, clientY

These properties specify the X and Y coordinates of the mouse pointer, relative to the client area of the browser window. Note that these coordinates do not take document scrolling into account. Defined for mouse events.

ctrlKey

true if the Ctrl key was held down when the event occurred. Defined for mouse events.

currentTarget

The document node that is currently handling this event. During capturing and bubbling, this is different than target. Defined for all events.

detail

The click count: 1 for a single click, 2 for a double-click, 3 for a triple click, and so on. Defined for click, mousedown and mouseup events.

eventPhase

The current phase of event propagation. The constants above define the three legal values for this property. Defined for all events.

metaKey

true if the Meta key was held down when the event occurred. Defined for mouse events.

relatedTarget

For mouseover events, this is the document node that the mouse left when it moved over the target. For mouseout events, it is the node that the mouse entered when leaving the target. It is undefined for other types of events.

screenX, screenY

These properties specify the X and Y coordinates of the mouse pointer relative to the upper-left corner of the user's screen. Defined for mouse events.

shiftKey

true if the Shift key was held down when the event occurred. Defined for mouse events.

target

The target for this event; the document node that generated the event. Note that this may be any node, including Text nodes; it is not restricted to Element nodes. Defined for all events.

timeStamp

A Date object that specifies the date and time at which the event occurred. Defined for all events, but implementations are not required to provide a valid timestamp.

type

The type of event that occurred. This is the name of the event handler property with the leading "on" removed. For example, "click", "load", or "mousedown". Defined for all events.

view

The Window object in which the event was generated.

DOM Methods

preventDefault( )

Tells the web browser not to perform the default action (if there is one) associated with this event. If the event is not of a type that is cancelable, this method has no effect. Returns nothing.

stopPropagation( )

Stops the event from propagating any further through the capturing, target, or bubbling phases of event propagation. Returns nothing.

IE 4 Properties

altKey

A boolean value that specifies whether the Alt key was held down when the event occurred.

button

For mouse events, button specifies which mouse button or buttons were pressed. This read-only integer is a bitmask: the 1 bit is set if the left button was pressed. The 2 bit is set if the right button was pressed. The 4 bit is set if the middle button (of a three button mouse) was pressed.

cancelBubble

If an event handler wants to stop an event from being propagated up to containing objects, it must set this property to true.

clientX, clientY

The X and Y coordinates, relative to the web browser page, at which the event occurred.

ctrlKey

A boolean value that specifies whether the Ctrl key was held down when the event occurred.

fromElement

For mouseover and mouseout events, fromElement refers to the object from which the mouse pointer is moving.

keyCode

For keyboard events, keyCode specifies the Unicode character code generated by the key that was struck.

offsetX, offsetY

The X and Y coordinates at which the event occurred, within the coordinate system of the event's source element (see srcElement).

returnValue

If this property is set, its value takes precedence over the value actually returned by an event handler. Set this property to false to cancel the default action of the source element on which the event occurred.

screenX, screenY

The X and Y coordinates, relative to the screen, at which the event occurred.

shiftKey

A boolean value that specifies whether the Shift key was held down when the event occurred.

srcElement

The Window, Document, or Element object that generated the event.

toElement

For mouseover and mouseout events, toElement refers to the object into which the mouse pointer is moving.

type

A string property that specifies the type of the event. Its value is the name of the event handler, minus the "on" prefix. So, when the onclick( ) event handler is invoked, the type property of the Event object is "click".

x, y

The X and Y coordinates at which the event occurred. These properties specify coordinates relative to the innermost containing element that is dynamically positioned using CSS.

Netscape 4 Properties

height

Set only in resize events. Specifies the new height of the window or frame that was resized.

layerX, layerY

Specify the X and Y coordinates, relative to the enclosing layer, at which an event occurred.

modifiers

Specifies which keyboard modifier keys were held down when the event occurred. This numeric value is a bitmask consisting of any of the constants Event.ALT_MASK, Event.CONTROL_MASK, Event.META_MASK, or Event.SHIFT_MASK. Due to a bug, this property is not defined in Netscape 6 or 6.1.

pageX, pageY

The X and Y coordinates, relative to the web browser page, at which the event occurred. Note that these coordinates are relative to the top-level page, not to any enclosing layers.

screenX, screenY

The X and Y coordinates, relative to the screen, at which the event occurred.

target

The Window, Document, Layer, or Element object on which the event occurred.

type

A string property that specifies the type of the event. Its value is the name of the event handler, minus the "on" prefix. So, when the onclick( ) event handler is invoked, the type property of the Event object is "click".

which

For keyboard and mouse events, which specifies which key or mouse button was pressed or released. For keyboard events, this property contains the character encoding of the key that was pressed. For mouse events, it contains 1, 2, or 3, indicating the left, middle, or right buttons.

width

Set only in resize events. Specifies the new width of the window or frame that was resized.

x, y

The X and Y coordinates at which the event occurred. These properties are synonyms for layerX and layerY and specify the position relative to the containing layer (if any).