Section 25.110. Event: information about an event

25.110. Event: information about an event

DOM Level 2 Events, IE: Object Event

25.110.1. Subinterfaces

UIEvent

25.110.2. Standard Properties

The following properties are defined by the DOM Level 2 Events standard. See also KeyEvent, MouseEvent, and UIEvent for additional type-specific event properties:

readonly boolean bubbles

true if the event is of a type that bubbles (unless stopPropagation( ) is called); false otherwise.

readonly boolean cancelable

true if the default action associated with the event can be canceled with preventDefault( ); false otherwise.

readonly Object currentTarget

The Element, Document, or Window that is currently handling this event. During capturing and bubbling, this is different from target.

readonly unsigned short eventPhase

The current phase of event propagation. The value is one of the following three constants, which represent the capturing phase, normal event dispatch, and the bubbling phase:

eventPhase Constant	Value
Event.CAPTURING_PHASE	1
Event.AT_TARGET	2
Event.BUBBLING_PHASE	3

readonly Object target

The target node for this eventi.e., the Element, Document, or Window that generated the event.

readonly Date timeStamp

The date and time at which the event occurred (or, technically, at which the Event object was created). Implementations are not required to provide valid time data in this field, and if they do not, the getTime( ) method of this Date object should return 0. See Date in Part III of this book.

readonly String type

The name of the event that this Event object represents. This is the name under which the event handler was registered, or the name of the event-handler property with the leading "on" removedfor example, "click", "load", or "submit".

25.110.3. IE Properties

Internet Explorer does not (at least as of IE 7) support the standard DOM event model, and IE's Event object defines a completely different set of properties. The IE event model does not define an inheritance hierarchy for different types of events, so all properties relevant to any type of event are listed here:

boolean altKey

Whether the Alt key was held down when the event occurred.

integer button

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

boolean cancelBubble

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

integer clientX, clientY

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

boolean ctrlKey

Whether the Ctrl key was held down when the event occurred.

Element fromElement

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

integer keyCode

For keypress events, this property specifies the Unicode character code generated by the key that was struck. For keydown and keyup events, it specifies the virtual keycode of the key that was struck. Virtual keycodes may be dependent on the keyboard layout in use.

integer offsetX, offsetY

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

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

integer screenX, screenY

Specify the coordinates, relative to the screen, at which the event occurred.

boolean shiftKey

Whether the Shift key was held down when the event occurred.

Object srcElement

A reference to the Window, Document, or Element object that generated the event.

Element toElement

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

String type

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

integer x, y

Specify the X and Y coordinates at which the event occurred relative to the document or the innermost containing element that is dynamically positioned using CSS.

25.110.4. Standard Methods

The following methods are defined by the DOM Level 2 Events specification. In the IE event model, the Event object has no methods:

initEvent( )

Initializes the properties of a newly created Event object.

preventDefault( )

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

stopPropagation( )

Stops the event from propagating any further through the capturing, target, or bubbling phases of event propagation. After this method is called, any other event handlers for the same event on the same node are called, but the event is not dispatched to any other nodes.

25.110.5. Description

The properties of an Event object provide details about an event, such as the element on which the event occurred. The methods of an Event object can control the propagation of the event. The DOM Level 2 Events standard defines a standard event model, which is implemented by all modern browsers except Internet Explorer, which defines its own, incompatible model. This reference page lists the properties of both the standard Event object and also of the IE Event object. See Chapter 17 for further details about the two event models. In particular, however, note that an Event object is passed to event-handler functions in the standard event model but is stored in the event property of the Window object in the IE event model.

In the standard event model, various subinterfaces of Event define additional properties that provide details pertinent to specific types of events. In the IE event model, there is only this one type of Event object, and it is used for events of all types.

25.110.6. See Also

KeyEvent, MouseEvent, UIEvent; Chapter 17