748 Part III ✦ Document Objects Reference Most commonly, you use expressions consisting of this property as if construc- tion condition statements. Because these are Boolean values, you can combine mul- tiple properties in a single condition. For example, if you have a branch of a function that is to execute only if the event occurred with both the Shift and Control keys held down, the condition looks as the following: if (event.shiftKey && event.ctrlKey) { // statements to execute } Conversely, you can take a more user-friendly approach to provide special pro- cessing if the user holds down any one of the three modifier keys: if (event.shiftKey || event.ctrlKey || event.altKey) { // statements to execute } The rationale behind this approach is to offer perhaps some shortcut operation for users, but not force them to memorize a specific modifier key combination. Example See Listing 29-10, where the values of these three properties are used to set the checked properties of corresponding checkboxes for a variety of event types. Related Items: altLeft, ctrlLeft, shiftLeft properties. altLeft ctrlLeft shiftLeft Value: Boolean Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ Some versions of Windows (notably Windows NT and Windows 2000) allow events to be modified by only the left-hand Alt, Ctrl, and Shift keys when using IE5.5+. For these modifiers to be recorded by the event object, focus must be on the document (body), and not in any form control. If the left-key version is false and the regular version is true, then your script knows that the right-hand key had been held down during the event. Related Items: altKey, ctrlKey, shiftKey properties. (IE) event.altLeft 749 Chapter 29 ✦ Event Objects behaviorCookie behaviorPart Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ These two properties are related to a Windows technology that Microsoft calls rendering behaviors. Unlike the behaviors discussed under the addBehavior() method in Chapter 15, rendering behaviors are written in C++ and provide services for custom drawing on your Web page. For more details, consult the document “Implementing Rendering Behaviors” at http://msdn.microsoft.com/ workshop/browser/editing/imprendbehav.asp . bookmarks boundElements dataFld qualifier reason recordset Value: See Text Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ This group of event object properties is tied to using Data Binding in Windows versions of IE4+. Extensive details of Data Binding lie outside the scope of this book, but Table 29-5 provides a summary of these event object properties within that context (much of the terminology is used in Data Binding, but doesn’t affect other scripting). For more details, search for ActiveX Data Objects (ADO) at http://msdn.microsoft.com/workshop/. Table 29-5 ADO-Related event Object Properties Property Value First Implemented Description bookmarks Array IE4 Array of ADO bookmarks (saved positions) for records within a recordset associated with the object that received the event. Continued (IE) event.bookmarks 750 Part III ✦ Document Objects Reference Table 29-5 (continued) Property Value First Implemented Description boundElements Array IE5 Array of element references for all elements bound to the same data set that was touched by the current event. dataFld String IE5 Name of the data source column that is bound to a table cell that receives a cellchange event. qualifier String IE5 Name of the data member associated with a data source that receives a data-related event. Available only if the data source object (DSO) allows multiple- named data members or a qualifier has been explicitly set via the DATASRC attribute of the bound element. Read-write in IE5+. reason Integer IE4 Set only from onDataSetComplete event, provides the result code of the data set loading (0=successful; 1=transfer aborted; 2=other error). recordset Object IE4 Reference to the current recordset in a data source object. button Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The button property reveals which button or buttons were pressed to activate a mouse event. If no mouse button is pressed to generate an event, this property is zero. But integers 1 through 7 reveal single and multiple button presses, including (IE) event.button 751 Chapter 29 ✦ Event Objects three-button mice when they are recognized by the operating system. Integer val- ues correspond to buttons according to the following scheme: Value Description 0 No button 1 Left (primary) button 2 Right button 3 Left and right buttons together 4 Middle button 5 Left and middle buttons together 6 Right and middle buttons together 7 Left, middle, and right buttons together Mouse buttons other than the primary one are easier to look for in mousedown or mouseup events, rather than onclick events. Be aware that as the user works toward pressing multiple buttons, each press fires a mousedown event. Therefore, if the user presses the left button first, the mousedown event fires, with the event.button property bearing the 1 value; as soon as the right button is pressed, the mousedown event fires again, but this time with an event.button value of 3. If your script intends to perform special action with both buttons pressed, it should ignore and not perform any action for a single mouse button, because that one-but- ton event will very likely fire in the process, disturbing the intended action. Exercise caution when scripting the event.button property for both IE4+ and NN6+. The W3C DOM event model defines different button values for mouse but- tons ( 0, 1, and 2 for left, middle, and right) and no values for multiple buttons. Example See Listing 29-11, where the event.button property is revealed in the statusbar. Try pressing individual mouse buttons on, for example, the screen button. Then try combinations, watching the results very closely in the statusbar. Related Items: None. cancelBubble Value: Boolean Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The cancelBubble property (which sounds more as if it should be a method name) determines whether the current event object bubbles up any higher in the element containment hierarchy of the document. By default, this property is false, meaning that if the event is supposed to bubble, then it will do so automatically. (IE) event.cancelBubble 752 Part III ✦ Document Objects Reference To prevent event bubbling for the current event, set the property to true any- where within the event handler function. As an alternative, you can cancel bubbling directly in an element’s event handler attribute, as in the following: onClick=”doButtonClick(this); event.cancelBubble = true” Cancelling event bubbling works only for the current event. The very next event to fire will have bubbling enabled (provided the event bubbles). Example See Listing 29-6 to see the cancelBubble property in action. Even though that listing has some features that apply to IE5.5+, the bubble cancelling demonstration works all the way back to IE4. Related Items: returnValue property. clientX clientY offsetX offsetY screenX screenY x y Value: Integer Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ An IE event object provides coordinates for an event in as many as four coordi- nate spaces: the element itself, the parent element of the event’s target, the view- able area of the browser window, and the entire video screen. Unfortunately, misleading values can be returned by some of the properties that correspond to these coordinate spaces, as discussed in this section. Note that no properties pro- vide the explicit position of an event relative to the entire page, in case the user has scrolled the window. Starting with the innermost space — that of the element that is the target of the event — the offsetX and offsetY properties should provide pixel coordinates within the target element. This is how, for example, you could determine the click point on an image, regardless of whether the image is embedded in the BODY or floating around in a positioned DIV. Windows versions through (at least) IE5.5 pro- duce the correct values in most cases. But for some elements that are child ele- ments of the BODY element, the vertical ( y) value may be relative to the viewable (IE) event.clientX 753 Chapter 29 ✦ Event Objects window, rather than just the element itself. You can see an example of this when you work with Listing 29-14 and click the H1 or P elements near the top of the page. This problem does not affect IE for the Mac, but there is another problem on Mac versions: If the page is scrolled away from its normal original position, the scrolled values are subtracted from the clientX and clientY values. This is an incompati- bility bug, and you must take this error into account if you need click coordinates inside an element for a potentially scrolled page. This error correction must be done only for the Mac, because Windows works OK. Extending scope to the offset parent element of the event’s target, the x and y properties in IE5+ for Windows should return the coordinates for the event relative to the target’s offset parent element (the element that can be found via the offsetParent property). For most non-positioned elements, these values are the same as the clientX and clientY properties because, as discussed in a moment, the offset parent element has a zero offset with its parent, the BODY. Observe an important caution about the x and y properties: In IE4/Windows and through IE5/Macintosh, the properties do not take into account any offset parent locations other than the BODY. Even in IE5+ for Windows, this property can give false read- ings in some circumstances. By and large, these two properties should not be used. The next set of coordinates, clientX and clientY, are relative to the visible doc- ument area of the browser window. When the document is scrolled all the way to the top (or the document doesn’t scroll at all), these coordinates are the same as the coordinates on the entire page. But because the page can scroll “underneath” the viewable window, the coordinates on the page can change if the page scrolls. Also, in the Windows versions of IE, you can actually register mouse events that are up to two pixels outside of the BODY element, which seems weird, but true. Therefore, in IE/Windows, if you click the background of the BODY, the event fires on the BODY element, but the clientX/clientY values will be two pixels greater then offsetX/offsetY (they’re equal in IE/Mac). Despite this slight discrepancy, you should rely on the clientX and clientY properties if you are trying to get the coor- dinates of an event that may be in a positioned element, but have those coordinates relative to the entire viewable window, rather than just the positioning context. Taking the page’s scrolling into account for an event coordinate is often impor- tant. After all, unless you generate a fixed-size window for a user, you don’t know how the browser window will be oriented. If you’re looking for a click within a spe- cific region of the page, you must take page scrolling into account. The scrolling fac- tor can be retrieved from the document.body.scrollLeft and document.body.scrollTop properties. When reading the clientX and clientY properties, be sure to add the corresponding scroll properties to get the position on the page: var coordX = event.clientX + document.body.scrollLeft var coordY = event.clientY + document.body.scrollTop Do this in your production work without fail. Finally, the screenX and screenY properties return the pixel coordinates of the event on the entire video screen. These properties may be more useful if IE pro- vided more window dimension properties. In any case, because mouse events fire only when the cursor is somewhere in the content region of the browser window, don’t expect to get screen values of anywhere outside this region. (IE) event.clientX 754 Part III ✦ Document Objects Reference If these descriptions seem confusing to you, you are not alone. Throw in a few bugs, and it may seem like quite a mess. But think how you may use event coordinates in scripts. By and large, you want to know one of two types of mouse event coordinates: within the element itself and within the page. Use the offsetX/offsetY properties for the former; use clientX/clientY (plus the scroll property values) for the latter. While the coordinate properties are used primarily for mouse events, there is a little quirk that may let you determine if the user has resized the window via the maximize icon in the title bar (on the Mac, this is called the zoom box) or the resize handle at the bottom-right corner of the screen. Mouse event coordinates are recorded in the event object for a resize event. In the case of the maximize icon, the clientY coordinate is a negative value (above the client space) and the clientX coordinate is within about 45 pixels of the previous width of the window ( document.body.clientWidth). This, of course, happens after the window has resized, so it is not a way to prevent window resizing. Example (with Listing 29-14) on the CD-ROM Related Items: fromElement, toElement properties. dataTransfer Value: Object Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The dataTransfer property is a reference to an IE/Windows-only object called the dataTransfer object. Use this object in drag-and-drop operations (that is, with drag-and- drop-related events) to control not only the data that gets transferred from the source to the target but also to control the look of the cursor along the way. Table 29-6 lists the properties and methods of the dataTransfer object. On the CD-ROM (IE) event.dataTransfer 755 Chapter 29 ✦ Event Objects Table 29-6 dataTransfer object Properties and Methods Property/Method Returns Description dropEffect String An element that is a potential recipient of a drop action can use the onDragEnter, onDragOver, or onDrop event handler to set the cursor style to be displayed when the cursor is atop the element. Before this can work, the source element’s onDragStart event handler must assign a value to the event.effectAllowed property. Possible string values for both properties are copy, link, move, or none. These properties correspond to the Windows system cursors for the operations users typically do with files and in other documents. You must also cancel the default action (meaning set event.returnValue to false) for all of these drop element event handlers: onDragEnter, onDragOver, and onDrop. effectAllowed String Set in response to an onDragStart event of the source element, this property determines which kind of drag-and-drop action will be taking place. Possible string values are copy, link, move, or none. This property value must match the dropEffect property value for the target element’s event object. Also, cancel the default action (meaning, set event.returnValue to false) in the onDragStart event handler. clearData([format]) Nothing Removes data in the clipboard. If no format parameters are supplied, all data are cleared. Data formats can be one or more of the following strings: Text, URL, File, HTML, Image. getData(format) String Retrieves data of the specified format from the clipboard. The format is one of the following strings: Text, URL, File, HTML, Image. The clipboard is not emptied after you get the data, so that it can be retrieved in several sequential operations. Continued (IE) event.dataTransfer 756 Part III ✦ Document Objects Reference Table 29-6 (continued) Property/Method Returns Description setData(format, data) Boolean Stores string data in the clipboard. The format is one of the following strings: Text, URL, File, HTML, Image. For non-text data formats, the data must be a string that specifies the path or URL to the content. Returns true if the transfer to the clipboard is successful. The dataTransfer object acts as a conduit and controller of data that your scripts need to transfer from one element to another in response to a user’s drag- and-drop action. You need to adhere to a well-defined sequence of actions triggered by a handful of event handlers. This means that the object is invoked on different instances of the event object as different events fire in the process of dragging and dropping. The sequence begins at the source element, where an onDragStart event han- dler typically assigns a value to the dropEffect property and uses the getData() method to explicitly capture whatever data it is about the source object that gets transferred to the eventual target. For example, if you drag an image, the informa- tion being transferred may simply be the URL of the image — data that is extractable from the event.srcElement.src property of that event (the src prop- erty of the image, that is). At the target element(s), three event handlers must be defined: onDragEnter, onDragOver, and onDrop. Most commonly, the first two event handlers do nothing more than mark the element for a particular dropEffect (which must match the effectAllowed set at the source during the drag’s start) and set event.returnValue to false so that the cursor displays the desired cursor. These actions are also carried out in the onDrop event handler, but that is also the han- dler that does the processing of the destination action at the target element. This is when the dataTransfer object’s getData() method is invoked to pick up the data that has been “stored” away by getData() at the start of the drag. If you also want to make sure that the data is not picked up accidentally by another event, invoke the clearData() method to remove that data from memory. Note that the style of dragging being discussed here is not the kind in which you see the source element actually moving on the screen (although you could script it that way). The intention is to treat drag-and-drop operations just as Windows does in, say, the Windows Explorer window or on the Desktop. To the user, the draggable component becomes encapsulated in the cursor. That’s why the properties of the dataTransfer object control the appearance of the cursor at the drop point as a way of conveying to the user the type of action that will occur with the impending drop. (IE) event.dataTransfer 757 Chapter 29 ✦ Event Objects Example An extensive example of the dataTransfer property in action can be found in Listing 15-37 in the section for the onDrag event handler. Related Items: onDragEnd, onDragEnter, onDragLeave, onDragOver, onDragStart, onDrop event handlers. fromElement toElement Value: Element Object Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The fromElement and toElement properties allow an element to uncover where the cursor rolled in from or has rolled out to. These properties extend the power of the onMouseOver and onMouseOut event handlers by expanding their scope to out- side the current element (usually to an adjacent element). When the onMouseOver event fires on an element, the cursor had to be over some other element just beforehand. The fromElement property holds a reference to that element. Conversely, when the onMouseOut event fires, the cursor is already over some other element. The toElement property holds a reference to that element. Example (with Listing 29-15) on the CD-ROM Related Items: srcElement property. keyCode Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ For keyboard events, the keyCode property returns an integer corresponding to the Unicode value of the character (for onKeyPress events) or the keyboard char- acter key (for onKeyDown and onKeyUp events). There is a significant distinction between these numbering code systems. If you want the Unicode values (the same as ASCII values for the Latin character set) for the key that a user pressed, get the keyCode property from the onKeyPress event handler. For example, a lowercase “a” returns 97, while an uppercase “A” returns 65. Non-character keys, such as arrows, page navigation, and function keys, On the CD-ROM (IE) event.keyCode . 748 Part III ✦ Document Objects Reference Most commonly, you use expressions consisting of this property. ctrlKey, shiftKey properties. (IE) event.altLeft 749 Chapter 29 ✦ Event Objects behaviorCookie behaviorPart Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ These. a recordset associated with the object that received the event. Continued (IE) event.bookmarks 750 Part III ✦ Document Objects Reference Table 29-5 (continued) Property Value First Implemented Description boundElements