738 Part III ✦ Document Objects Reference Listing 29-11 (continued) with either mouse button (if you have more than one).</P> <P>Enter some text with uppercase and lowercase letters: <TEXTAREA COLS=40 ROWS=4 onKeyPress=”checkWhich(event)” WRAP=”virtual”> </TEXTAREA></P> </FORM> </BODY> </HTML> The codes displayed for the keyboard event are equivalent to the ASCII values of character keys. If you need the codes of other keys, the onKeyDown and onKeyUp event handlers provide Unicode values for any key that you press on the keyboard. See the keyCode property listings for event objects later in this chapter for more details. Event Types Although browsers prior to Version 4 did not have an accessible event object, this is a good time to summarize the evolution of what in today’s browsers is known as the type property. The type property reveals the kind of event that generates an event object (the event handler name minus the “on”). Object models in IE4+ and NN6+ provide event handlers for virtually every HTML element, so that it’s possi- ble, for example, to define an onClick event handler for not only a clickable button, but also a P or even an arbitrary SPAN element. We’ll come back to the current crop of browsers in a moment. But first, in case you must write scripts that work on older browsers, you need to know which elements in those browsers support which event handlers. This knowledge will help you determine a common denomi- nator of event handlers to implement in your pages, based on the browsers you anticipate will be accessing the pages. Older browsers Earlier browsers tended to limit the number of event handlers for any particular element to just those that made sense for the kind of element it was. Even so, many scripters wanted more event handlers on more objects. But until that became a reality in IE4+ and NN6+, authors had to know the limits of the object models. Table 29-3 shows the event handlers available for objects within three generations of early browsers. Each column represents the version in which the event type was introduced. For example, the window object started out with four event types and gained three more when NN4 was released. In contrast, the area object was exposed as an object for the first time in NN3, which is where the first event types for that object are listed. 739 Chapter 29 ✦ Event Objects Table 29-3 Event Types through the Early Ages Object NN2/IE3 NN3 NN4 window blur dragdrop focus move load resize unload layer blur focus load mouseout mouseover mouseup link click mouseout dblclick mouseover mousedown onmouseup area mouseout click mouseover image abort error load form submit reset text, textarea, password blur keydown change keypress focus keyup select all buttons click mousedown mouseup select blur change focus fileUpload blur focus select 740 Part III ✦ Document Objects Reference With the exception of the NN4 layer object, all objects shown in Table 29-3 have survived into the newer browsers, so that you can use these event handlers with confidence. Again, keep in mind that of the browsers listed in Table 29-3, only NN4 has an event object of any kind exposed to scripts. Event types in IE4+ and NN6 By now you should have at least scanned the list of event handlers defined for elements in common, as shown in Chapter 15. This list of event types is enormous. A sizable number of the event types are unique to IE4, IE5, and IE5.5, and in some cases, just the Windows version at that. If you compose pages for both IE4+ and NN6+, however, you need to know which event types these browser families and generations have in common. Event types for NN6 are based primarily on the W3C DOM Level 2 specification, although they also include keyboard events, which are not formally part of the Level 2 specifica- tion. Table 29-4 lists a common denominator of event types for modern browsers and the objects that support them. As you can see, many of these event types and corresponding objects go way back to the beginning. The biggest change is that mouse events are available for any visible element. While not as long as the IE event list, the event types in Table 29-4 are the basic set you should get to know for all browsers. Table 29-4 IE4+ and NN6+ Event Types in Common Event type Applicable Elements abort OBJECT blur window, BUTTON, text, password, LABEL, SELECT, TEXTAREA change text, password, TEXTAREA, SELECT click All elements error window, FRAMESET, OBJECT focus window, BUTTON, text, password, LABEL, SELECT, TEXTAREA keydown text, password, TEXTAREA keypress text, password, TEXTAREA keyup text, password, TEXTAREA load window, FRAMESET, OBJECT mousedown All elements mousemove All elements mouseout All elements mouseover All elements mouseup All elements reset FORM resize window 741 Chapter 29 ✦ Event Objects Event type Applicable Elements scroll window select text, password, TEXTAREA submit FORM unload window, FRAMESET NN4 event Object Properties Methods Event Handlers data layerX layerY modifiers pageX pageY screenX screenY target type which Syntax Accessing NN4 event object properties: eventObject.property NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ About this object Most of the details about this object were covered in the comparative event object discussions earlier in this chapter. As the NN4 browser dissipates from the user-installed base, this object and its details will become less important. (NN4) eventObject 742 Part III ✦ Document Objects Reference Properties data Value: Array of Strings Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ A DragDrop event contains information about the URL string being dragged to the browser window. Because dragging multiple items to a window is possible (for example, many icons representing URLs on some operating systems), the value of the property is an array of strings, with each string containing a single URL (includ- ing file:// URLs for computer files). URL information such as this is deemed to be private data, so it is exposed only to signed scripts after the user has granted permission to read browser data. If you want your signed script to capture this information without loading the URL into the window, the event handler must evaluate to return false. Example (with Listing 29-12) on the CD-ROM layerX layerY pageX pageY screenX screenY Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ For many (but not all) mouse-related events, the NN4 event object contains a lot of information about the coordinates of the pointer when the event occurred. In the most complex case, a click in a layer object has three distinct pairs of horizontal and vertical ( x and y) coordinate values relative to the layer, the page, and the entire screen. If no layers are specified for a document, the layer and page coordi- nate systems are identical. Note that these values are merely geographical in nature and do not, by themselves, contain any information about the object being clicked (information held by the eventObject.target property). On the CD-ROM (NN4) eventObject.layerX 743 Chapter 29 ✦ Event Objects These mouse coordinate properties are set only with specific events. In the case of a link object, the click and all four mouse events pack these values into the event object. For buttons, however, only the mouse events ( mouseDown and mouseUp) receive these coordinates. Each of the two window event types ( move and resize) uses one of these prop- erty pairs to convey the results of the user action involved. For example, when the user resizes a window, the resize event stuffs the eventObject.layerX and eventObject.layerY properties with the inner width and height (that is, the con- tent area) of the browser window (you can also use the optional eventObject.width and eventObject.height property names if you prefer). When the user moves the window, the eventObject.screenX and eventObject.screenY properties contain the screen coordinates of the top-left corner of the entire browser application window. Example (with Listing 29-13) on the CD-ROM Related Items: window and layer object move and resize methods. modifiers Value: Constant Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The modifiers property of the NN4 event object refers to the modifier keys that can be pressed while clicking or typing. Modifier keys are Alt (also the Option key on the Macintosh keyboard), Ctrl, Shift, and what is known as a meta key (for exam- ple, the Command key, Ô, on the Macintosh keyboard). You can use this property to find out if one or more modifier keys were pressed at the time the event occurred. Values for these keys are integer values designed in such a way that any combi- nation of keys generates a unique value. Fortunately, you don’t have to know any- thing about these values, because the event model supplies some plain-language constants (properties of a global Event object always available behind the scenes) that a script can apply to the property value passed with the object. The constant names consist of the key name (all uppercase), followed by an underscore and the uppercase word MASK. For example, if the Alt key is pressed by itself or in concert with other modifier keys, you can use the bitwise AND operator ( &) and the Event.ALT_MASK constant to test for the presence of the Alt key in the property value: function handleMyEvent(evt) { if (evt.modifiers & Event.ALT_MASK) { //statements for Alt key handling } } On the CD-ROM (NN4) eventObject.modifiers 744 Part III ✦ Document Objects Reference Modifiers are not available with every event. You can capture them with mouseDown and mouseUp events in buttons and links. The only click event offering modifiers is with button objects. Keyboard events in text objects also include these modifiers. But be aware that accelerated keyboard combinations (for example, Ctrl+Q/Ô-Q for Quit) are not trappable by JavaScript event mechanisms because they are reserved for the browser’s own menu shortcuts. Example See Listing 29-10 earlier in this chapter to see (in a cross-browser way) how the modifier keys are read for NN4. target Value: Object Reference Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ Every event has a property containing a reference to the object that was clicked, typed into, or otherwise acted upon. Most commonly, this property is examined when you set up a page to trap for events at the window, document, or layer level, as described earlier in this chapter. The target property lets you better identify the intended destination of the event while handling all processing for that type of event in one place. With a reference to the target object at hand in this property, your scripts can extract and/or set properties of the object directly. type Value: String Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ An event object’s type is the name of the event that generated the event object. An event name is the same as the event handler’s name, less the “on” prefix. Therefore, if a button’s onClick event handler is triggered by a user’s click, then the event type is click (all lowercase). If you create a multipurpose function for handling events, you can extract the eventObject.type property to help the func- tion decide how to handle the current event. This sounds like a good job for the switch control structure (see Chapter 39). (NN4) eventObject.type 745 Chapter 29 ✦ Event Objects which Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The value of the which property depends on the event type: a mouse button indicator for mouse events and a character key code for keyboard events. For a mouse-related event, the eventObject.which property contains either a 1 for the left (primary) mouse button or a 3 for the right (secondary) mouse button. Most Macintosh computers have only a one-button mouse, so exercise care in designing pages that rely on the second mouse button. Even on Windows and other platforms, you must program an object’s onMouseDown event handler to return false for the secondary button to be registered instead of a browser pop-up menu appearing on-screen. Keyboard events generate the ISO-Latin character code for the key that has been pressed. This value is an integer between 0 and 255. If your script needs to look at the actual character being typed, rather than the key code, use the String.fromCharCode() method (see Chapter 34) to make the conversion. If you have difficulty obtaining character codes from keyboard events, try using the onKeyDown and onKeyUp events rather than onKeyPress. In either case, the func- tion keys do not present character codes. Example See Listing 29-10 for an example of using the eventObject.which property. IE4+ event Object Properties Methods Event Handlers altKey altLeft behaviorCookie behaviorPart bookmarks boundElements button cancelBubble clientX Continued (IE) event 746 Part III ✦ Document Objects Reference Properties Methods Event Handlers clientY contentOverflow ctrlKey ctrlLeft dataFld dataTransfer fromElement keyCode nextPage offsetX offsetY propertyName qualifier reason recordset repeat returnValue saveType screenX screenY shiftKey shiftLeft srcElement srcFilter srcUrn toElement type x y (IE) event 747 Chapter 29 ✦ Event Objects Syntax Accessing IE4+ event object properties: [window.]event.property NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ About this object The IE4+ event object is a property of the window object. Its basic operation is covered earlier in this chapter. You can see a little of what the event object is about with the help of The Evaluator (see Chapter 13). If you type event into the bottom text box, you can examine the properties of the event object for the event that triggers the function that displays the event object properties. If you press the Enter key in the text box, you see properties of the keypress event that caused the internal script to run; click the List Properties button to see the properties of the click event fired at the button. Hold down some of the modifier keys while clicking to see how this affects some of the properties. As you review the properties for the event object, make special note of the com- patibility table for each property. The list of properties for this object has grown over the evolution of the IE4+ event object model. Also, most properties are listed here as being read-only, which they were in IE4. But for IE5+, these properties are also Read/Write if the event is created artificially via methods, such as IE5.5’s docu- ment.createEventObject() method. Event objects that are created by user or system action have very few properties that can be modified on the fly (to prevent your scripts from altering user actions). Properties altKey ctrlKey shiftKey Value: Boolean Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ When an event object is created in response to a user or system action, these three properties are set based on whether their corresponding keys were being held down at the time — a Shift-click, for example. If the key was held down, the property is assigned a value of true; otherwise the value is false. (IE) event.altKey . Methods Event Handlers altKey altLeft behaviorCookie behaviorPart bookmarks boundElements button cancelBubble clientX Continued (IE) event 746 Part III ✦ Document Objects Reference Properties Methods. the pages. Older browsers Earlier browsers tended to limit the number of event handlers for any particular element to just those that made sense for the kind of element it was. Even so, many scripters. keyup select all buttons click mousedown mouseup select blur change focus fileUpload blur focus select 740 Part III ✦ Document Objects Reference With the exception of the NN4 layer object, all objects shown