Dynamic HTML: The Definitive Reference, 2rd Ed.Dynamic HTML: The Definitive ReferenceSearch this book

Chapter 10. Event Reference

Contents:

Alphabetical Event Reference

The purpose of this chapter is to provide a list of every event type implemented in Version 4 and later of both Netscape Navigator and Internet Explorer, as well as those specified in the W3C recommendation for the Events module of DOM Level 2. So that you can readily see whether a particular entry applies to the browser(s) you must support, a version table accompanies each term listed in the following pages. This table tells you at a glance the version of Navigator, Internet Explorer, and W3C DOM specification in which the term was first introduced.

If a listing for IE signifies Win or Mac, it means that the event is supported only for the Windows or Macintosh operating system version. Note that a large number of event types are supported only in IE for Windows, and many of those apply only to data binding applications. If you are concerned with cross-browser deployment, pay very close attention to the browser compatibility charts to find the events that work on a broad array of browser brands and versions. Chapter 6 contains many guidelines and examples for blending otherwise incompatible event mechanisms into routines that work on many browser types.

In the listings below, the "Bubbles" category indicates whether the event follows event bubbling propagation (in browsers that support event bubbling), while the "Cancelable" category means that the default action usually associated with the event (such as navigating to a new URL when clicking on an a element) can be canceled by script statements, thus averting the normal operation. The category named "Typical Targets" usually points to broad types of elements to which the event type may be applied. For more specific element support for each event type, consult Chapter 15: DOM Method Index.

10.1. Alphabetical Event Reference

 
DOMActivateNN n/a IE n/a DOM 2

Bubbles: Yes; Cancelable: Yes
Fires when a user begins interacting with an element, such as clicking a button or typing a character into a text box. The event object's detail property passes an integer that contains more information about the event: 1 for unmodified single clicks; 2 for actions with modifier keys or double clicks (what the DOM specification calls hyperactivation).

Typical Targets

All rendered elements that are capable of receiving focus normally (such as form controls and links), plus any other rendered element for which the tabindex attribute is assigned a value.

 
DOMAttrModifiedNN 6 IE n/a DOM 2

Bubbles: Yes; Cancelable: No
Fires after a script adds, removes, or changes the value of an element's attribute. Adding or removing an attribute must be done by the setAttribute( ) and removeAttribute( ) methods, but changing an existing attribute may be accomplished either by the setAttribute( ) method or assigning a new value to an element object's property that corresponds to an attribute. Numerous event object properties convey details about the event. See the following properties of the event object in
Chapter 9: attrName, attrChange, prevValue, newValue, and relatedNode.

Typical Targets

All rendered elements.

 
DOMCharacterDataModifiedNN 6 IE n/a DOM 2

Bubbles: Yes; Cancelable: No
Fires after a script changes the value of a CharacterData type of node. See the following properties of the event object in
Chapter 9: prevValue and newValue.

Typical Targets

CharacterData nodes.

 
DOMFocusIn, DOMFocusOutNN n/a IE n/a DOM 2

Bubbles: Yes; Cancelable: No
Fires when the current element receives focus (DOMFocusIn) or loses focus (DOMFocusOut). These events fire prior to the focus and blur events, respectively. Similar to the IE onfocusin and onfocusout events.

Typical Targets

All rendered elements that are capable of receiving focus normally (such as form controls and links), plus any other rendered element for which the tabindex attribute is assigned a value.

 
DOMNodeInsertedNN 6 IE n/a DOM 2

Bubbles: Yes; Cancelable: No
Fires on a node when that node is explicitly inserted into an existing node container. If you assign an event listener for this event to an element that is the recipient of an inserted (including appended) node, the DOMNodeInserted event fires on the node being inserted (the srcElement of the event object). If the event bubbles further (i.e., away from the point of insertion), the event listener function can still find out about the new container by reading the relatedNode event property. Note that if the incoming node comes from another location in the same document, the removal of the node from its original container fires the DOMNodeRemoved event on the removed node before it leaves its original container (so that the event can bubble up to its original container).

Typical Targets

All rendered nodes.

 
DOMNodeInsertedIntoDocumentNN 6 IE n/a DOM 2

Bubbles: No; Cancelable: No
Fires on a node when that node is inserted into an existing node container, but the origin of the node is from another document. If you assign an event listener for this event and the DOMNodeInserted event, the DOMNodeInsertedIntoDocument event fires first. Note that if the incoming node comes from another location in another document, the removal of the node from its original document fires the DOMNodeRemovedFromDocument and DOMNodeRemoved events on the removed node before it leaves its original container (so that the event can bubble up to its original container).

Typical Targets

All rendered nodes.

 
DOMNodeRemovedNN 6 IE n/a DOM 2

Bubbles: Yes; Cancelable: No
Fires on a node when that node is explicitly removed from a node container. If you assign an event listener for this event to an element that is the container of a removed node, the DOMNodeRemoved event fires on the node being removed (the srcElement of the event object). If the event bubbles further (i.e., away from the original node location), the event listener function can still find out about the old container by reading the relatedNode event property.

Typical Targets

All rendered nodes.

 
DOMNodeRemovedFromDocumentNN 6 IE n/a DOM 2

Bubbles: No; Cancelable: No
Fires on a node when the node is removed because it is being inserted into another document, meaning the node is exiting its original document entirely. If you assign an event listener for this event and the DOMNodeRemoved event, the DOMNodeRemovedFromDocument event fires last.

Typical Targets

All rendered nodes.

 
DOMSubtreeModifiedNN 6 IE n/a DOM 2

Bubbles: No; Cancelable: No
Fires on a node that is inside the document tree and that changes its nested node structure. This event acts like a generic event for the more specific node mutation events, and fires last. Implementing event listeners for this event may cause problems in early versions of Netscape 6.

Typical Targets

All rendered nodes.

 
onabortNN 3 IE 4 DOM 2

Bubbles: No; Cancelable: No
Fires if an img element's content fails to complete loading due to user interruption (e.g., clicking Stop or rapidly navigating to another page) or other failure (e.g., timeout due to network traffic). The W3C DOM applies this event only to the object element, which, in the W3C standards view (but not yet widely supported in browsers), is the desired way to embed an image into a page.

Typical Targets

The img element.

 
onactivateNN n/a IE 5.5(Win) DOM n/a

Bubbles: Yes; Cancelable: No
Fires when an object becomes the active object. Giving an object focus makes it active, but a rendered element can be the active element without having focus. Only one element at a time may be active. See the setActive( ) method of shared objects in
Chapter 9. If an element has received focus, the onactivate event fires before the onfocus event.

Typical Targets

All rendered elements, plus the document and window objects.

 
onafterprint, onbeforeprintNN n/a IE 5(Win) DOM n/a

Bubbles: No; Cancelable: No
Fires after the user clicks the Print button in the Print dialog box before content is assembled for the printer (onbeforeprint) and after the data has been sent to the printer (onafterprint). You can use these events to trigger functions that modify a style sheet or other content rendering of a page (so that a potentially different-looking page reaches the printer) and then restore the page for viewing on the screen. This technique can work in lieu of style sheet media settings.

Typical Targets

The body and frameset elements, plus the window object.

 
onafterupdateNN n/a IE 4(Win) DOM n/a

Bubbles: Yes; Cancelable: No
Fires after data being sent to a writable data source object (through the IE data binding mechanism) has successfully updated the database.

Typical Targets

Elements that accept data input and support data binding.

 
onbeforeactivateNN n/a IE 6(Win) DOM n/a

Bubbles: Yes; Cancelable: Sometimes
Fires just before an object is to become the active object. Giving an object focus makes it active, but a rendered element can be the active element without having focus. Only one element at a time may be active. See the setActive( ) method of shared objects in
Chapter 9. If an element received focus, related events fire in the following sequence: onbeforeactivate, onactivate, and onfocus.

If you cancel the onbeforeactivate event, the element does not become active, nor does it receive focus, but only if the intended focus action occurs from explicit user action (clicking and tabbing). An element blocked from receiving focus causes the focus to go to another element: to the next focusable element in tabbing order (when the user tabs to the blocked element) or to the next outermost focusable parent element in the document tree (when a user clicks on the blocked element). Activating or giving focus to an element via the setActive( ) or focus( ) methods cannot be blocked by canceling this event.

Typical Targets

All rendered elements, plus the document and window objects.

 
onbeforecopyNN n/a IE 5(Win) DOM n/a

Bubbles: Yes; Cancelable: Yes
Fires just before a user-initiated Copy command (via the Edit menu, a keyboard shortcut, or a context menu) completes the task of moving the selected content to the system clipboard. At this point in the copy sequence, a function invoked by this event handler can perform additional or substitute processing for the normal system copy action. For example, additional information from the element, such as effective style information of the element containing selected text), can be preserved in the IE clipboardData object (see
Chapter 9) for later processing with the help of the onbeforepaste event handler. Canceling the onbeforecopy event does not prevent user copying of a selection.

Typical Targets

Rendered elements except form controls.

 
onbeforecutNN n/a IE 5(Win) DOM n/a

Bubbles: Yes; Cancelable: Yes
Fires just before a user-initiated Cut command (via the Edit menu, a keyboard shortcut, or a context menu) completes the task of removing the content from its current location and moving the selected content to the system clipboard (assuming the browser is in edit mode for body content). At this point in the cut sequence, a function invoked by this event handler can perform additional or substitute processing for the normal system cut action. For example, additional information from the element, such as effective style information of the element containing selected text), can be preserved in the IE clipboardData object (see
Chapter 9) for later processing with the help of the onbeforepaste event handler. Canceling the onbeforecut event does not prevent user cutting of a selection.

Typical Targets

All rendered elements.

 
onbeforedeactivateNN n/a IE 5.5(Win) DOM n/a

Bubbles: Yes; Cancelable: Yes
Fires just before an object is about to yield activation to another object because the user clicked on another element, tabbed to another element, or a script invoked the setActive( ) or focus( ) method of another element. If an element has focus and is the active element, the following event sequence fires en route to losing focus: onbeforedeactivate, ondeactivate, and onblur. Because onbeforedeactivate is cancelable (but ondeactivate is not), cancel this event to prevent an element from deactivating or losing focus—provided you have a good reason to do this other than annoying your visitors.

Typical Targets

All rendered elements, plus the document and window objects.

 
onbeforeeditfocusNN n/a IE 5(Win) DOM n/a

Bubbles: Yes; Cancelable: Yes
Fires just before an editable element receives official focus by a user clicking or tabbing to the element. Editable elements include text-oriented form controls and body elements set to be editable (see the IE 5.5 contentEditable property of all elements in
Chapter 9). A function invoked from this event handler can perform additional scripted actions, such as setting the color of the element text, before the user begins editing the content.

Typical Targets

Text form controls; rendered elements in edit mode (IE 5.5 or later); content governed by the DHTML Editing ActiveX control (see http://msdn.microsoft.com/workshop/browser/mshtml/).

 
onbeforepasteNN n/a IE 5(Win) DOM n/a

Bubbles: Yes; Cancelable: Yes
Fires just before a user-initiated Paste command (via the Edit menu, a keyboard shortcut, or a context menu) completes the task of pasting the content from the system clipboard to the current selection. If you are trying to paste custom information from the clipboardData object (saved there in an onbeforecopy, oncopy, onbeforecut, or oncut event handler), you need to have the onbeforepaste and onpaste event handler functions working together. Set event.returnValue to false in the onbeforepaste event handler so that the Paste item in the Edit (and context) menu is activated, even for a noneditable paste target. When the user selects the Paste menu choice, your onpaste event handler retrieves information from the clipboardData object and perhaps modifies the selected element's HTML content:

function handleBeforePaste( ) {
    event.returnValue = false;
}
function handlePaste( ) {
    if (event.srcElement.className == "OK2Paste") {
        event.srcElement.innerText = clipboardData.getData("Text");
    }
}

In the above paste operation, the system clipboard never plays a role because your scripts handle the entire data transfer—all without having to go into edit mode.

Typical Targets

All rendered elements and the document object.

 
onbeforeprint

See onafterprint.

 
onbeforeunloadNN n/a IE 4(Win)/5(Mac) DOM n/a

Bubbles: No; Cancelable: Yes
Fires just before the current document begins to unload due to impending navigation to a new page, form submission, or window closure. This event fires before the onunload event, and gives your scripts and users a chance to cancel the unload action. Some of this activity is automatic to prevent nefarious scripts from trapping users on a page.

In the onbeforeunload event handler, assign a string to the event.returnValue property to force IE to display a dialog box that lets the user choose whether the page should stay where it is or the navigation or window closure action that the user requested continues as expected. The string assigned to the event property becomes part of the dialog box message (other text in the message is hardwired by the browser and may not be removed or modified). The resulting action is controlled by the user's button choice in the dialog box.

Typical Targets

The body and frameset elements, plus the window object.

 
onbeforeupdateNN n/a IE 4(Win) DOM n/a

Bubbles: Yes; Cancelable: Yes
Fires just prior to sending data to a writable data source object (through the IE data binding mechanism). You can perform data validation and cancel the update.

Typical Targets

Elements that accept data input and support data binding.

 
onblurNN 2 IE 3 DOM 2

Bubbles: No; Cancelable: No
Fires after the current element loses focus (due to some other element receiving focus) or invoking the blur( ) method of the current element. The onblur event fires before the onfocus event in the other element.

Avoid using the onblur event in text input fields to trigger form validation, especially if the validation routine displays an alert dialog box upon discovering an error. Interaction among the onblur and onfocus events, along with the display and hiding of an alert dialog box can put you into an infinite loop. Use onchange instead.

Although the onblur event has been supported for form controls and window objects since the early days of scriptable browsers, modern browsers can fire the event on virtually any other rendered element, provided the tabindex attribute is set for the element. Note that IE for Windows is known to omit firing the onblur event on window objects.

Typical Targets

For all browsers, input (of type text and password), textarea, select, and window objects; for IE 5 or later and Netscape 6, add any rendered element for which the tabindex attribute is assigned a value.

 
onbounceNN n/a IE 4 DOM n/a

Bubbles: No; Cancelable: Yes
Fires each time the text in a marquee element, whose behavior is set to alternate, touches a boundary and changes direction.

Typical Targets

The marquee element.

 
oncellchangeNN n/a IE 5(Win) DOM n/a

Bubbles: Yes; Cancelable: No
Fires on the element hosting a data binding data source object (usually the object element) each time data in the remote database changes its value.

Typical Targets

The object and applet elements.

 
onchangeNN 2 IE 3 DOM 2

Bubbles: No (IE); Yes (NN 6); Cancelable: Yes (IE); No (NN 6)
Fires when a text-oriented form control or select element loses focus, and its content or chosen item is different from what it was when the element most recently gained focus. Use this event in text-type input and textarea elements to validate an entry for that one field. But also include form-wide validation with the form element's onsubmit event handler. This event fires before the onblur event.

Typical Targets

Text-type input, textarea, and select elements.

 
onclickNN 2 IE 3 DOM 2

Bubbles: Yes; Cancelable: Yes
Fires after the user effects a mouse click or equivalent action. Click equivalents occur naturally on focusable elements (buttons and links for most browsers) by pressing the Enter key (and frequently the spacebar) when the item has focus. In modern browsers that support the accesskey attribute, typing the access key combination also triggers a click equivalent.

For mouse click actions, the onclick event fires only if the mouse button is pressed and released with the pointer atop the same element. In that case, the primary mouse events fire in this order: onmousedown, onmouseup, and onclick.

An event object created from a mouse event has numerous properties filled with details such as coordinates of the click and whether any modifier keys were held down during the event. Information about the button used is more reliably accessed through the onmousedown or onmouseup events. The event handler function can inspect these properties as needed.

Although the onclick event has been supported for button-oriented form controls and link objects since the early days of scriptable browsers, modern browsers can fire the event on virtually any other rendered element. Note that in Netscape 6, mouse events can fire on child text nodes of container-type elements, meaning that the event object's target property references the node, rather than the element. See Chapter 6 for details about the impact of this W3C DOM-endorsed behavior and cross-browser solutions.

Typical Targets

For all browsers, input (of type button, radio, checkbox, reset, and submit), a, and area objects; Version 4 and later support the event for the document and window objects; for IE 4 or later and Netscape 6, add any rendered element, as well as text nodes for Netscape 6.

 
oncontextmenuNN n/a IE 5(Win) DOM n/a

Bubbles: Yes; Cancelable: Yes
Fires after the user clicks the right mouse button (or the button designated the secondary mouse button in the mouse control panel). This mouse button displays the context menu for the item beneath the pointer. To block the display of the context menu (and perhaps display a custom one of your own design via DHTML), set event.returnValue to false in the oncontextmenu event handler. While hiding the context menu may make it more difficult for users to view the source of a page or save an image (assuming you have already opened a document in a window bereft of the menubar), it is not a foolproof way to guard against determined users capturing your page's content. Any scripted solution fails the instant the user disables scripting.

Typical Targets

All rendered elements and the document object.

 
oncontrolselectNN n/a IE 5.5(Win) DOM n/a

Bubbles: Yes; Cancelable: Yes
Fires when the user selects an editable element (not its content) while the page is in edit mode. See onmove for a demonstration of this event.

Typical Targets

All rendered elements and the document object.

 
oncopyNN n/a IE 5(Win) DOM n/a

Bubbles: Yes; Cancelable: Yes
Fires after the user initiates the Copy command (via the Edit menu, a keyboard shortcut, or a context menu) to place a copy of the selected content into the system clipboard. An event handler function for this event can supplement the copy action by placing additional data of your choice into the clipboardData object (which the onpaste event handler can read and handle as needed).

To give users access to a Copy menu command for an otherwise uneditable element, set event.returnValue to false in the onbeforecopy event handler for the same object as the oncopy event handler. On the other hand, to prevent user copying of body content, set event.returnValue to false for the oncopy event handler. Just don't regard this tactic as a foolproof way to prevent users from copying your prized content.

Typical Targets

Rendered elements except form controls.

 
oncutNN n/a IE 5(Win) DOM n/a

Bubbles: Yes; Cancelable: Yes
Fires after the user initiates the Cut command (via the Edit menu, a keyboard shortcut, or a context menu) to place a copy of the selected content into the system clipboard. To cut body content, the containing element must be in edit mode (see the shared contendEditable property in
Chapter 9). An event handler function for this event can supplement the cut action by placing additional data of your choice into the clipboardData object (which the onpaste event handler can read and handle as needed).

To give users access to a Cut menu command for an otherwise uneditable element, set event.returnValue to false in the onbeforecut event handler for the same object as the oncut event handler. On the other hand, to prevent user cutting of body or form control content, set event.returnValue to false for the oncut event handler.

Typical Targets

All rendered elements.

 
ondataavailable, ondatasetchanged, ondatasetcompleteNN n/a IE 4(Win) DOM n/a

Bubbles: Yes; Cancelable: No
Fire on the element hosting a data binding data source object (usually the object element) each time the remote data source signals it has new data ready for retrieval (ondataavailable), a data set has been modified (ondatasetchanged), or a data set has received all data form the query (ondatasetcomplete). These events are available only for data source object types capable of asynchronous connections with their remote sources.

Typical Targets

The object and applet elements; the xml element in IE 5 and later.

 
ondblclickNN 4 IE 4 DOM n/a

Bubbles: Yes; Cancelable: Yes
Fires after the user effects a second successive mouse click or equivalent action (see onclick for click equivalents). A double click requires a specific sequence of mouse events leading up to it. The sequence is: onmousedown, onmouseup, onclick, onmouseup, and ondblclick. The amount of time that can elapse between the two clicks is determined by the client computer's mouse control panel settings.

Because the onclick event fires ahead of ondblclick, the associated onclick event handler (if any) should perform only innocuous actions, such as highlighting an element, much like the way operating system desktop icons operate. If an item requires a double click, that is the only event that should do something significant.

Typical Targets

Support for this event in Navigator 4 is limited to the a element (but not on the Macintosh); IE 4 or later and Netscape 6 support the event on renderable elements and the document object.

 
ondeactivateNN n/a IE 5.5(Win) DOM n/a

Bubbles: Yes; Cancelable: No
Fires after an object has yielded activation to another object because the user clicked on another element, tabbed to another element, or a script invoked the setActive( ) or focus( ) method of another element. If an element has focus and is the active element, the following event sequence fires en route to losing focus: onbeforedeactivate, ondeactivate, and onblur. To prevent an element from deactivating or losing focus, cancel the companion onbeforedeactivate event.

Typical Targets

All rendered elements, plus the document and window objects.

 
ondrag, ondragend, ondragstartNN n/a IE 5(Win) DOM n/a

Bubbles: Yes; Cancelable: Yes
When the user starts dragging a selection, the browser fires one ondragestart event on the selection's parent element, followed by a series of ondrag events, and then one ondragend event when the user releases the mouse button. All three event types fire on the same element during the drag.

During the drag operation, the user sees the cursor in one of its various forms, rather than seeing the actual element float around the page. As long as the user keeps the mouse button down following an initial drag action, the ondrag event keeps firing. Other drag-related events fire on other elements along the way (events such as ondragenter for an element that finds the dragged cursor in its airspace), but the ondrag event also fires at various instances.

An element with content that is dragged receives events in the following sequence: ondragstart, ondrag (perhaps many times), and ondragend. Elements in the path of the drag action receive ondragenter, ondragover, and ondragleave events, while the element at the end of the drag receives the ondrop event (which fires before the ondragend event of the dragged element). The speed of the drag action and client system speed impacts the number of event firings of all drag types. A fast drag on a slow machine may result in some events not firing.

Typical Targets

All rendered elements and document object.

 
ondragdropNN |4| IE n/a DOM n/a

Bubbles: No; Cancelable: No
Fires (in Navigator 4 only) if the user drags a desktop file to the document. With signed scripts, the browser can read the filename of the dragged item.

Typical Targets

The window object.

 
ondragend

See ondrag.

 
ondragenter, ondragleave, ondragoverNN n/a IE 5(Win) DOM n/a

Bubbles: Yes; Cancelable: Yes
Elements in the path of a drag action usually receive ondragenter, ondragover, and ondragleave events in that order. The speed of the drag action and client system impact the number of event firings of all drag types. A fast drag on a slow machine may result in some events not firing.

If your scripts will be performing customized actions upon the user dropping the dragged item onto a target in the document, you should prevent default actions of the ondragenter and ondragover events so that the target's ondrop event can do its job without interference from the normal system response to dragging. See the dataTransfer object in Chapter 9 for an example of drag-related event interaction.

Typical Targets

All rendered elements and document object.

 
ondragstart

See ondrag.

 
ondropNN n/a IE 5(Win) DOM n/a

Bubbles: Yes; Cancelable: Yes
Fires on the drop target element when the user releases the mouse button after a drag action. Fires just before the ondragend event of the owner of the dragged content. Prevent default actions of the drop target's ondragenter and ondragover events (by setting event.returnValue to false in their respective event handler functions) so that the target's ondrop event can do its job without interference from the normal system response to dragging. See the dataTransfer object in
Chapter 9 for an example of drag-related event interaction, including the effectAllowed property, which controls the cursor shape at the drop target.

Typical Targets

All rendered elements and document object.

 
onerrorNN 3 IE 4 DOM 2

Bubbles: No; Cancelable: Yes
Fires after one of a variety of errors occurs, depending on the element or object to which the event handler is assigned. For elements that load external content, such as the img element, errors during loading (such as an invalid URL) fire the onerror event on the img element. When assigned to the window object (including direct assignment in the <body> tag), overall runtime script errors (not compile-time syntax errors) also fire the onerror event. A technique that some scripters used in earlier browsers that plastered script error messages inside intrusive alert dialog boxes was to trap all runtime errors in the following manner:

function doNothing( ) {return true;}
window.onerror = doNothing;

This isn't good for debugging because you need to find errors during development. See the Error object in Chapter 9 for more details on processing errors from this event handler. Eventually, there will enough browsers deployed that use more modern exception handling.

Typical Targets

Elements that load external content, plus the window object.

 
onerrorupdateNN n/a IE 4(Win) DOM n/a

Bubbles: Yes; Cancelable: No
Fires if an error occurs while sending data to a writable data source object (through the data binding mechanism).

Typical Targets

Elements that accept data input and support data binding.

 
onfilterchangeNN n/a IE 4(Win) DOM n/a

Bubbles: No; Cancelable: No
Fires when an element's filter changes its state and when a transition or blend filter completes its action. You can use the event to cascade a sequence of transitions.

Typical Targets

Most rendered elements.

 
onfinishNN n/a IE 4 DOM n/a

Bubbles: No; Cancelable: Yes
Fires after the scrolling text in a looping marquee element comes to rest after its final motion.

Typical Targets

The marquee element.

 
onfocusNN 2 IE 3 DOM 2

Bubbles: No; Cancelable: No
Fires when the current element receives focus due to user action (clicking or tabbing) or invoking of the focus( ) method. The onblur event of the next previously focused element fires before the onfocus event in the current element.

Although the onfocus event has been supported for form controls and window objects since the early days of scriptable browsers, modern browsers can fire the event on virtually any other rendered element, provided the tabindex attribute is set for the element. Note that IE for Windows is known to omit firing the onfocus event on window objects.

Typical Targets

For all browsers, input (of type text and password), textarea, select, and window objects; for IE 5 or later and Netscape 6, add any rendered element for which the tabindex attribute is assigned a value.

 
onfocusin, onfocusoutNN n/a IE 6 DOM n/a

Bubbles: Yes; Cancelable: No
Fire when the current element receives focus (onfocusin) or loses focus (onfocusout). These events fire prior to the focus and blur events, respectively. Microsoft suggests that you can use these event handlers to perform style changes (anywhere in the document) in anticipation of an element receiving or losing focus, without disturbing the normal focus and blur actions.

Typical Targets

All rendered elements that are capable of receiving focus normally (such as form controls and links), plus any other rendered element for which the tabindex attribute is assigned a value.

 
onhelpNN n/a IE 4 DOM n/a

Bubbles: Yes; Cancelable: Yes
Fires when the user presses the F1 function key. If an element has focus at the time, that is the element that receives the event. You can prevent the default action (displaying the IE Help window) and generate your own DHTML-based help system if you like.

Typical Targets

All rendered elements, plus document and window objects, except in IE for Macintosh, which limits this event to the window object.

 
onkeydown, onkeyupNN 4 IE 4 DOM 3

Bubbles: Yes; Cancelable: Yes
Fire when the user presses (onkeydown) and releases (onkeyup) a keyboard key. These two events fire on a focusable element or object for almost every key of the keyboard, including function and navigation keys. The instance of the event object for these events contains information about the key (not the character) pressed. See
Chapter 6 for details on cross-browser handling of keyboard events. You cannot reliably inhibit critical Ctrl character sequences, but if you prevent the default action of the onkeypress event for a text form control, the character does not arrive at the text field.

Typical Targets

All focusable rendered elements, plus document and window objects.

 
onkeypressNN 4 IE 4 DOM 3

Bubbles: Yes; Cancelable: Yes
Fires after the user presses and releases a keyboard character key. The event sequence is: onkeydown, onkeyup, and onkeypress. The instance of the event object for these events contains information about the character of the pressed key. See
Chapter 6 for details on cross-browser handling of keyboard events.

Typical Targets

All focusable rendered elements, plus the document object.

 
onlayoutcompleteNN n/a IE 5.5(Win) DOM n/a

Bubbles: Yes; Cancelable: Yes
Fires when a print preview LayoutRect object finishes rendering its content. For details on this XML enhancement for IE 5.5 and later for Windows, visit
http://msdn.microsoft.com/workshop/browser/hosting/printpreview/reference/reference.asp.

Typical Targets

An XML LayoutRect object.

 
onloadNN 2 IE 3 DOM 2

Bubbles: No; Cancelable: No
Fires when external content belonging to the current element or object finishes loading and initializing. This event handler for the window object is perhaps the most important because it signals that all content of the document and its elements (including external content) has loaded before the event fires. When that event fires, your scripts can reference any document tree object without error.

The event fires for a frameset element only after the onload events for all frames have fired (but the event is not bubbling from frame to frameset). Note that if the user or a script loads a new page into a frame after the frameset's initial load, the onload event does not fire again for the frameset (but it does for the frame).

Although the onload event has been supported for window objects since the early days of scriptable browsers, modern browsers fire the event on virtually any other rendered element that loads external content.

Typical Targets

For all browsers, window objects; for Version 4 browsers or later the img element; for IE 4 or later and Netscape 6, add any rendered element capable of loading external content.

 
onlosecaptureNN n/a IE 5(Win) DOM n/a

Bubbles: No; Cancelable: No
Fires when event capture mode for the element becomes disengaged. See the shared setCapture( ) method in
Chapter 9.

Typical Targets

All rendered elements.

 
onmousedown, onmouseupNN 4 IE 4 DOM 2

Bubbles: Yes; Cancelable: Yes
Fires when the user presses down (onmousedown) or releases (onmouseup) a mouse button. Events related to mouse click actions fire in this order: onmousedown, onmouseup, and onclick.

An event object created from a mouse event has numerous properties filled with details such as coordinates of the click, the mouse button used, and whether any modifier keys were held down during the event. The event handler function can inspect these properties as needed.

Note that in Netscape 6, mouse events can fire on child text nodes of container-type elements, meaning that the event object's target property references the node, rather than the element. See Chapter 6 for details about the impact of this W3C DOM-endorsed behavior and cross-browser solutions.

Typical Targets

All rendered elements, except in Navigator 4, where the events are limited to button-style input elements, plus a and area elements.

 
onmouseenter, onmouseleaveNN n/a IE 5.5(Win) DOM n/a

Bubbles: No; Cancelable: No
Fire when the user rolls the mouse pointer into (onmouseenter) or out of (onmouseleave) an element's space (including border or padding, but not margin). Each event fires just once per entry and exit. These variations on the onmouseover and onmouseout events do not bubble.

Typical Targets

All rendered elements.

 
onmousemoveNN 4 IE 4 DOM 2

Bubbles: Yes; Cancelable: No
Fires while the user rolls the mouse pointer atop an element's space, with the mouse button up or down. Note that the event fires repeatedly, although the frequency of firing depends on the speed of the mouse motion and system resources.

An event object created from a mouse event has numerous properties filled with details such as coordinates of the pointer and whether any modifier keys were held down during the event. The event handler function can inspect these properties as needed.

In Navigator 4, this event type can be assigned to the window, document, and layer object, but only in the explicitly defined event capture mode. Note that in Netscape 6, mouse events can fire on child text nodes of container-type elements, meaning that the event object's target property references the node, rather than the element. See Chapter 6 for details about the impact of this W3C DOM-endorsed behavior and cross-browser solutions.

Typical Targets

All rendered elements, except as noted above for Navigator 4.

 
onmouseout, onmouseoverNN 2 IE 3 DOM 2

Bubbles: Yes; Cancelable: Yes
Fire when the user rolls the mouse pointer into (onmouseover) or out of (onmouseout) an element's space (including border or padding, but not margin). Each event fires just once per entry and exit (except in Navigator 4 for Windows, in which the event fires repeatedly, similar to onmousemove).

Because the onmouseout event doesn't officially fire until another element in the window fires its onmouseover event (whether you have a handler for it or not), the onmouseout event may not fire if the target element is at the edge of a window or frame, and the user whisks the pointer outside of the current frame without the first frame's body element ever receiving the onmouseover event. If you use onmouseout events to restore image swaps, the user could see a stuck image. Leave sufficient space around your swappable images to account for this behavior.

An event object created from a mouse event has numerous properties filled with details such as coordinates of the click, the mouse button used, whether any modifier keys were held down during the event, and where the incoming pointer came from or outgoing pointer has gone. The event handler function can inspect these properties as needed.

Note that in Netscape 6, mouse events can fire on child text nodes of container-type elements, meaning that the event object's target property references the node, rather than the element. See Chapter 6 for details about the impact of this W3C DOM-endorsed behavior and cross-browser solutions.

Although these events have been supported in one form or another since the early days of scriptable browsers, only modern browsers can fire the event on virtually any other rendered element. For older browsers, the events were limited to a and area elements (where a elements surrounded images to be swapped).

Typical Targets

All rendered elements, except as noted above.

 
onmousewheelNN n/a IE 6(Win) DOM n/a

Bubbles: No; Cancelable: No
Fires as the user spins the mouse wheel (on a mouse equipped with a wheel). The event object's wheelDelta property reveals details about the direction and amount of rotation.

Typical Targets

All rendered elements and the document object.

 
onmoveNN |4| IE n/a DOM n/a

Bubbles: No; Cancelable: No
Fires (in Navigator 4 only) if the user or script moves the browser window.

Typical Targets

The window object.

 
onmove, onmoveend, onmovestartNN n/a IE 5.5(Win) DOM n/a

Bubbles: Yes; Cancelable: No
When in edit mode, a positionable element set up for dragging receives these events in the following sequence: onmovestart (upon starting the drag), onmove (repeatedly during the drag), and onmoveend (upon release of the mouse button). The following example uses several events to demonstrate IE edit mode scripting (note that the native element dragging mechanism doesn't work well in IE 6 if the <!DOCTYPE> element points to a standards-compatible mode DTD):

<html> 
<head> 
<title>IE 5.5 (Windows) Edit Mode</title> 
<style type="text/css">
   body {font-family:Arial, sans-serif}
   #myDIV  {position:absolute; height:100px; width:300px;}
   .regular {border:5px black solid; padding:5px; background-color:lightgreen}
   .moving {border:5px maroon dashed; padding:5px; background-color:lightyellow}
   .chosen {border:5px maroon solid; padding:5px; background-color:lightyellow}
</style>
<script type="text/javascript">
// built-in dragging support
document.execCommand("2D-position",false,true);
// preserve content between modes
var oldHTML = "";

// engage static edit environment
function editOn( ) {
    var elem = event.srcElement;
    elem.className = "chosen";
}

// engage special edit-move environment
function moveOn( ) {
    var elem = event.srcElement;
    oldHTML = elem.innerHTML;
    elem.className = "moving";
}

// display coordinates during drag
function trackMove( ) {
    var elem = event.srcElement;
    elem.innerHTML = "Element is now at: " + elem.offsetLeft + ", " +
                      elem.offsetTop;
}

// turn off special edit-move environment
function moveOff( ) {
    var elem = event.srcElement;
    elem.innerHTML = oldHTML;
    elem.className = "chosen";
}

// restore original environment (wrapper gets onfocusout)
function editOff( ) {
    var elem = event.srcElement;
    if (elem.id == "wrapper") {
        elem.firstChild.className = "regular";
    }
}

// initialize event handlers
function init( ) {
    document.body.oncontrolselect = editOn;
    document.body.onmovestart = moveOn;
    document.body.onmove = trackMove;
    document.body.onmoveend = moveOff;
    document.body.onfocusout = editOff;
}
</script> 
</head> 
<body onload="init( );">
<div id="wrapper" contenteditable="true">
    <div id="myDIV" class="regular">
        This is a positioned element with some text in it.
    </div>
</div>
</body> 
</html>

Typical Targets

An XML LayoutRect object.

 
onpasteNN n/a IE 5(Win) DOM n/a

Bubbles: Yes; Cancelable: Yes
Fires after the user initiates the Paste command (via the Edit menu, a keyboard shortcut, or a context menu) to place a copy of the system clipboard into the selected content. An event handler function for this event can supplement the paste action by retrieving additional data from the clipboardData object (information placed there by one of the copy- or cut-related event handler functions).

To give users access to a Paste menu command for an otherwise uneditable element, set event.returnValue to false in the onbeforepaste event handler for the same object as the onpaste event handler. On the other hand, to prevent user pasting system clipboard content, set event.returnValue to false for the onpaste event handler.

Typical Targets

All rendered elements.

 
onpropertychangeNN n/a IE 5(Win) DOM n/a

Bubbles: No; Cancelable: No
Fires after the property of an element changes under script control. Property changes occur through direct property assignment and methods, such as setAttribute( ). Changes to an element's property (e.g., a property of an element's style object) also trigger this event. The event object's propertyName property contains the name of the property influenced by the event.

Typical Targets

All rendered elements, plus the document object.

 
onreadystatechangeNN n/a IE 4 DOM n/a

Bubbles: No; Cancelable: No
Fires if the readyState property changes for an element. See the shared readyState property in
Chapter 9 for details on what affects the property.

Typical Targets

Elements that load external content.

 
onresetNN 3 IE 4 DOM 2

Bubbles: No; Cancelable: Yes
Fires when a form element receives a request to reset the form from a reset-type input element or a scripted reset( ) method. By canceling the event, a script in the onreset event handler aborts the normal form reset.

Typical Targets

The form element.

 
onresizeNN 4 IE 4 DOM 2

Bubbles: Yes; Cancelable: No
Fires after an element or object is resized by the user or script control. Note that resizing a window may force other elements in the page to resize themselves. In IE, onresize events from those elements bubble to the body and window objects, where a lone onresize event handler may be bombarded by events.

Typical Targets

For IE, elements that have dimensions associated with them, plus the window and document objects; for Navigator, the window and document objects.

 
onresizeend, onresizestartNN n/a IE 5.5(Win) DOM n/a

Bubbles: Yes; Cancelable: No
Fire (in edit mode only) when a user resizes an element by dragging its resize handles. See onmove for a related example.

Typical Targets

All rendered elements.

 
onrowenter, onrowexit, onrowsdelete, onrowsinsertedNN n/a IE 4(Win) DOM n/a

Bubbles: Yes; Cancelable: No
Fire on the element hosting a data binding data source object (usually the object element) when a row in the remote database table is modified either through database or data source activity.

Typical Targets

The object and applet elements; the xml element in IE 5 and later.

 
onscrollNN n/a IE 4 DOM 2

Bubbles: No; Cancelable: No
Fires each time an element displaying scroll bars executes a scroll, either by user action or script control. If a user drags the scroll bar thumb, the event fires repeatedly during the dragging motion, but the frequency of event firings depends on system speeds.

Typical Targets

All rendered elements that can have scrollbars by default (such as textarea and window objects), plus any element that has its overflow style sheet attribute set to scroll.

 
onselectNN 2 IE 3 DOM 2

Bubbles: No (IE); Yes (NN 6); Cancelable: Yes
Fires when a user drags a selection in a text box (input or textarea elements). Broken in Navigator 4 for Windows. In IE 4 or later for Windows, the event also applies to body text selections.

Typical Targets

Text-type input and textarea elements for all browsers; body element for IE 4 or later for Windows.

 
onselectionchangeNN n/a IE 5.5(Win) DOM n/a

Bubbles: No; Cancelable: No
Fires when the selection type (in IE edit mode) changes.

Typical Targets

The document object.

 
onselectstartNN n/a IE 4 DOM n/a

Bubbles: Yes; Cancelable: Yes
Fires immediately after the user begins dragging a selection on a body element or form control text. If the selection extends across multiple elements, only one event fires, and its target remains the element where the selection began. Canceling this event in the <body> tag (onselectstart="return false") can prevent undesirable and inadvertent user selection and scrolling interaction.

Typical Targets

All rendered elements.

 
onstartNN n/a IE 4 DOM n/a

Bubbles: No; Cancelable: No
Fires when the scrolling text in a looping marquee element begins its motion after a page loads.

Typical Targets

The marquee element.

 
onstopNN n/a IE 5(Win) DOM n/a

Bubbles: No; Cancelable: No
Fires when the user clicks the browser's Stop button, even if the document and its content have successfully loaded.

Typical Targets

The document object.

 
onsubmitNN 2 IE 3 DOM 2

Bubbles: No (IE); Yes (NN 6); Cancelable: Yes
Fires when a form element receives a request to submit the form from a submit-type input element but not from a scripted submit( ) method. This is the event to trigger one final client-side form validation prior to sending a form to the server. By canceling the event, a script in the onsubmit event handler aborts the submission.

Typical Targets

The form element.

 
onunloadNN 2 IE 3 DOM 2

Bubbles: No; Cancelable: No
Fires just before the current document begins to unload due to impending navigation to a new page, form submission, or window closure. This event fires after the onbeforeunload event in browsers that support that event. In most browsers, the actual document unloading does not wait for the onunload event handler function to complete. Therefore, if the function performs too many actions, especially those that rely on script variables and elements in the current page, those references may become invalid while the function runs, creating script errors (of the "undefined" or "object not found" variety). Therefore, keep onunload processing to a minimum.

Typical Targets

The body and frameset elements, plus the window object.



Library Navigation Links

Copyright © 2003 O'Reilly & Associates. All rights reserved.