9.0 Introduction

Without events, there would be no Dynamic HTML. A strong statement, perhaps, but given the kinds of document object models we have inherited, it's true. For any dynamism to occur in an HTML page, some kind of trigger is needed.

Two categories of triggers are available: user-generated actions and system-generated actions. Direct user-generated actions are those caused by mouse and keyboard activity. System-generated actions, perhaps more accurately described as document- or browser-generated actions, occur when something significant occurs in the browser, such as the document completing its loading into the browser or an image failing to retrieve its data from the server.

One of your jobs as a DHTML scripter is to determine which events on which elements should trigger scripted actions. Any kind of form button, for example, will usually have some script action associated with it (unless it is just the default actions of submit and reset input element types). Less obvious, perhaps, are events that inspect the characters being typed into a text box, to make sure only allowed characters are permitted to pass. Very common mouse-oriented events detect when the cursor rolls atop an image element (or an a hyperlink element surrounding the image) so that a script can change the image to a highlighted version during this "rollover." A corresponding event for when the cursor rolls off the image reverts the image back to its default version.

9.0.1 The Event-Scripting Process

In scripting terms, you need a way to connect the occurrence of an event to some function that carries out tasks for that event. Events are said to be bound to an element. You instruct an element to be on the lookout for an event of a particular type that comes its way. For example, you can instruct a button to respond to a mouse click on it, while all surrounding elements ignore clicks on them.

Syntax for event binding takes on many forms (see the Discussion for Recipe 9.1), but the basic task for the scripter is to assign a function to a particular event of a particular element. The assignment statement is sometimes called an event handler, and the function assigned to the event handler is called an event handler function. Thus, when the user clicks on a button that has pre-assigned the handleClick( ) function to the click event, that event handler function runs whenever the user clicks on the button.

You can assign functions to as many event types on as many elements as your content and interface design require. For example, you can instruct an image to change its picture to a highlighted version when the user rolls the cursor atop the img element on the page, and then change to a concave image of itself when the user presses down on the image via the mouse button. Upon release of the mouse button, the image goes back to the rollover highlight color. When the cursor leaves the rectangle of the image, the image reverts to its original file. In this case, the img element might have four event handlers assigned to it (for the mouseover, mousedown, mouseup, and mouseout events, respectively) and a different event handler function assigned to each event.

When you refer to an event in your scripting, you typically use a one-word reference that is the name of the event preceded by "on." Therefore, when a button receives a click event, it looks to see if it has an onclick event handler assigned to it; if so, the event handler function starts executing immediately.

9.0.2 Event Types

Knowledge of the range of event types available to you will have a substantial impact on the amount and kind of user interaction you design into your pages. Several event types have been around since at least the days of the Version 4 browsers. These generic events act as a lowest common denominator of events that do not depend on any particular browser or operating system. Table 9-1 lists these event handlers and their browser compatibility ratings, as well as whether the HTML 4 standard recognizes the event handler as a tag attribute. While most of these event types can be bound to any rendered element in the latest browsers, events in earlier browsers (especially IE 3 and Navigator through Version 4) were limited to a handful of elements).

Table 9-1. Event handlers for all DHTML browsers

Event handler

NN

IE/ Win

IE/ Mac

HTML

Description

onabort

3

4

3.01

n/a

The user has interrupted the transfer of an image to the client.

onblur

2

3

3.01

4

An element has lost the input focus because the user clicked out of the element or pressed the Tab key.

onchange

2

3

3.01

4

An element has lost focus and the content of the element has changed since it gained focus.

onclick

2

3

3.01

4

The user has pressed and released a mouse button (or keyboard equivalent) on an element.

ondblclick

4

4

3.01

4

The user has double-clicked a mouse button on an element.

onerror

3

4

4

n/a

An error has occurred in a script or during the loading of some external data.

onfocus

2

3

3.01

4

An element has received the input focus.

onkeydown

4

4

4

4

The user has begun pressing a keyboard character key.

onkeypress

4

4

4

4

The user has pressed and released a keyboard character key.

onkeyup

4

4

4

4

The user has released a keyboard character key.

onload

2

3

3.01

4

A document or other external element has completed downloading all data into the browser.

onmousedown

4

4

4

4

The user has begun pressing a mouse button.

onmousemove

4

4

4

4

The user has rolled the mouse (irrespective of mouse button state).

onmouseout

3

3

3.01

4

The user has rolled the mouse out of an element.

onmouseover

2

3

3.01

4

The user has rolled the mouse atop an element.

onmouseup

4

4

4

4

The user has released the mouse button.

onmove

4

3

4

n/a

The user has moved the browser window.

onreset

3

4

4

4

The user has clicked a Reset button in a form.

onresize

4

4

4

n/a

The user has resized a window or object.

onselect

2

3

3

4

The user is selecting text in an input or textarea element.

onsubmit

2

3

3.01

4

A form is about to be submitted.

onunload

2

3

3.01

4

A document is about to be unloaded from a window or frame.

Beyond the cross-browser events in Table 9-1, Microsoft implements an additional set that allows DHTML scripts to react to more specific user and system actions. Table 9-2 lists the IE-only events that may assist a DHTML applicationalmost all of them assist only the Windows version because of IE's tight integration with the operating system. Not listed in Table 9-2 are the many event handlers that apply only to Internet Explorer's data binding facilities, which allow form elements to be bound to server database sources.

Table 9-2. Internet Explorer DHTML events

Event handler

IE/ Win

IE/ Mac

Description

onbeforecopy

5

n/a

The user has issued a Copy command, but the operation has not yet begun.

onbeforecut

5

n/a

The user has issued a Cut command, but the operation has not yet begun.

onbeforepaste

5

n/a

The user has issued a Paste command, but the operation has not yet begun.

onbeforeprint

5

n/a

The user has issued a Print command, but the document has not yet been sent to the printer.

oncontextmenu

5

n/a

The user has pressed the context menu (i.e., "right-click") mouse button.

oncopy

5

n/a

The user has initiated a Copy command, but the operation has not yet begun.

oncut

5

n/a

The user has issued a Cut command, but the operation has not yet begun.

ondrag

5

n/a

The user is dragging the element.

ondragend

5

n/a

The user has completed dragging the element.

ondragenter

5

n/a

The user has dragged an element into the space of the current element.

ondragleave

5

n/a

The user has dragged an element out of the space of the current element.

ondragover

5

n/a

The user is dragging an element through the space of the current element.

ondrop

5

n/a

The user has dropped a dragged element atop the current element.

onfocusin

6

n/a

The user has acted to give focus to the element, but the actual focus has not yet occurred; the event fires before onfocus.

onfocusout

6

n/a

The user has given focus to another element; the event fires before onblur.

onhelp

4

4

The user has pressed the F1 key or chosen Help from the browser menu.

onmouseenter

5.5

n/a

The user has moved the cursor into the space of the element.

onmouseleave

5.5

n/a

The user has moved the cursor to outside the space of the element.

onmousewheel

6

n/a

The user is rolling the mouse wheel.

onmoveend

5.5

n/a

A positioned element has completed its motion.

onmovestart

5.5

n/a

A positioned element is starting its motion.

onpaste

5

n/a

The user has issued a Paste command, but the operation has not yet begun.

onscroll

4

4

The user has adjusted an element's scrollbar.

onselectstart

4

4

The user is beginning to select an element.

Keeping all of these events and their idiosyncrasies straight is not an easy task. To get into the depths of the more esoteric events, find a good DHTML reference (such as Dynamic HTML: The Definitive Reference, published by O'Reilly).

9.0.3 Event Models

The key to working with events over the long term is knowing how to take advantage of the abstract event object that is created each time an event registers with the browser. An event object contains numerous properties that describe the details of the event, such as the identity of the element receiving the event, mouse coordinates, keyboard characters, and even a self-descriptive property revealing the type of the event. The purpose of this event object is to let event handler functions derive details that could be useful for processing the event. For example, if an onmousemove event handler is being programmed to reposition an element along with the cursor, the event handler function needs to know the coordinates of the mouse at each firing of the mousemove event.

Complicating matters, however, is the fact that the event model that defines what an event object should be and how it should behave is not the same across all DHTML browsers. As of Internet Explorer 6 for Windows and IE 5.x for the Macintosh, Microsoft has not yet implemented the W3C DOM Level 2 event model. Netscape 6 and later, however, has followed the W3C DOM event model, adopting only a couple of IE convenience properties along the way. Each model supports a different way of communicating the event object to an event handler function, so Recipe 9.1 demonstrates how to equalize that discrepancy. You may also need to equalize the properties of the two event objects to make one function operate in both worlds. Table 9-3 provides an overview of the comparative event object properties in the two object models.

Table 9-3. Equivalent properties of the IE and NN 6 event objects

IE property

Description

W3C property or method

altKey

The Alt key was pressed during the event (Boolean).

altKey
button

The mouse button was pressed in the mouse event (integer, but different numbering systems per model).

button
cancelBubble[1]

Whether the event should bubble further.

stopPropagation( )
clientX, clientY

The horizontal and vertical coordinates of the event in the content region of browser window.

clientX, clientY
ctrlKey

The Ctrl key was pressed during the event (Boolean).

ctrlKey
fromElement

The object or element from which the pointer moved for a mouseover or mouseout event.

relatedTarget
keyCode

The keyboard character code of a keyboard event (integer).

keyCode
offsetX, offsetY

The horizontal and vertical coordinates of the event within the element space.

(calculated from other properties)

(calculated from other properties)

The horizontal and vertical coordinates of the event within the document space.

pageX, pageY
returnValue

The value returned to the system by the event (used to prevent default action in IE).

preventDefault( )
screenX, 
screenY

The horizontal and vertical coordinates of the event relative to the screen.

screenX, screenY
shiftKey

The Shift key was pressed during the event (Boolean)

shiftKey
srcElement

The object or element intended to receive the event.

target
toElement

The object or element to which the pointer moved for a mouseover or mouseout event.

relatedTarget
type

The name of the event (without "on" prefix).

type
x, y

The horizontal and vertical coordinates of the event within the body element (for unpositioned target) or the positioned element.

layerX, layerY

[1] Supported in Mozilla-based browsers for convenience.

A few of the recipes in this chapter demonstrate how to equalize the most commonly accessed properties of the IE and W3C DOM event objects.