JavaScript Bible, Gold Edition part 93 pptx

768 Part III ✦ Document Objects Reference each of the keyboard (regardless of its character). To inspect the character of a key, use the onKeyPress event to create the event object, and then look at the event object’s charCode property. This is the property that returns 97 for “a” and 65 for “A” because it’s concerned with the character associated with the key action. This property’s value is zero for onKeyDown and onKeyUp events. In contrast, the keyCode property is filled with a non-zero value only from onKeyDown and onKeyUp events (onKeyPress sets the property to zero) when alphanumeric keys are pressed; for most other non-character keys, all three events fill the keyCode property. Through this property you can look for non-character keys, such as arrows, page navigation, and function keys. For the character keys, there is no distinction between uppercase or lowercase: The “A” key on the Latin keyboard returns a value of 65, regardless of the state of the Shift key. At the same time, however, the press of the Shift key fires its own onKeyDown and onKeyUp events, setting the keyCode value to 16. Other non-character keys — arrows, page navigation, function, and similar — have their own codes as well. This gets very detailed, including special key codes for the numeric keyboard keys that are differ- ent from their corresponding numbers along the top row of the alphanumeric keyboard. Be sure to see the extensive section on keyboard events in Chapter 15 for exam- ples of how to apply the keyCode property in applications. Example (with Listing 29-18) on the CD-ROM Related Items: onKeyDown, onKeyPress, onKeyUp event handlers. clientX clientY layerX layerY pageX pageY screenX screenY Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The NN6 event object borrows mouse coordinate properties from both the NN4 and IE4+ event models. If you have worked with event coordinates in these other browsers, then you have nothing new to learn for NN6. On the CD-ROM (NN6) eventObject.clientX 769 Chapter 29 ✦ Event Objects Like the IE4+ event object, the NN6 event object’s clientX and clientY proper- ties are the coordinates within the viewable content region of the window. These values are relative to the window space, not the document. But unlike IE4+, you don’t have to calculate the position of the coordinates within the document because another pair of properties, pageX and pageY, provide that information automatically. If the page has not scrolled, then the values of the client and page coordinates are the same. Because it is usually more important to know an event’s coordinates with respect to the document than the window, the pageX and pageY properties are used most often. Another property pair, layerX and layerY, borrow terminology from the now defunct layer schemes of NN4, but the properties can still be quite valuable nonetheless. These coordinates are measured relative to the positioning context of the element that received the event. For regular, unpositioned elements in the BODY part of a document, that positioning context is the BODY element. Thus, for those elements, the values of the page and layer coordinates will be the same. But if you create a positioned element, the coordinate space is measured from the top-left corner of that space. Thus, if you are using the coordinates to assist in scripted dragging of positioned elements, you can confine your scope to just the positioned element. One coordinate system missing from the NN6 repertoire is that of the target ele- ment itself (comparable to the offsetX and offsetY properties of IE4+). These val- ues, however, can be calculated by subtracting from the page coordinate properties the offsetLeft and offsetTop properties of both the target element and its posi- tioning context. For example, if you want to get the coordinates of a mouse event inside an image, the event handler can calculate those values as follows: var clickOffsetX = evt.pageX - evt.target.offsetLeft - document.body.offsetLeft var clickOffsetY = evt.pageY - evt.target.offsetTop - document.body.offsetTop The last set of coordinate properties, screenX and screenY, provide values rela- tive to the entire video display. Of all these properties, only the client and screen coordinates are defined in the W3C DOM Level 2 standard. Keep in mind that in NN6, event targets include text nodes inside elements. Because nodes do not have all the properties of elements (for example, they have no offset properties signifying their location in the document), you may sometimes have to go to the target node’s parent node to get an element object whose offset properties provide the necessary page geography. This matters, of course, only if your scripts need concern themselves with mouse events on text. Example (with Listing 29-19) on the CD-ROM Related Items: target property. On the CD-ROM (NN6) eventObject.clientX 770 Part III ✦ Document Objects Reference currentTarget Value: Element Object Reference Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ As an event courses its way through its propagation paths, an event listener may process that event along the way. While the event knows what the target is, it can also be helpful for the event listener function to know which element’s event lis- tener is now processing the event. The currentTarget property provides a refer- ence to the element object whose event listener is processing the event. This allows one listener function to potentially process the event from different levels, branch- ing the code to accommodate different element levels that process the event. A valuable companion piece of information about the event is the eventPhase property, which helps your event listener function determine if the event is in cap- ture mode, bubble mode, or is at the target. This property is demonstrated in the next section. Example (with Listing 29-20) on the CD-ROM Related Items: eventPhase property. detail Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The detail property is included in the W3C DOM specification as an extra prop- erty whose purpose can be determined by the browser maker. In theory, this inte- ger property value can convey additional information about the event. While the property is present in the NN6 event object (and returns values for some events), it contains no additional data about events, but may in the future. Related Items: None. On the CD-ROM (NN6) eventObject.detail 771 Chapter 29 ✦ Event Objects eventPhase Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ An event fires in one of three possible event phases: event capture, at the target, or bubbling. Because the same event listener function may be processing an event in multiple phases, it can inspect the value of the eventPhase property of the event object to see in which phase the event was when the function was invoked. Values for this property are integers 1 (capture), 2 (at target), or 3 (bubbling). Example on the CD-ROM Related Items: currentTarget property. isChar Value: Boolean Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ You can find out from each keyboard event whether the key being pressed is a character key by examining the isChar property. Most typically, however, you are already filtering for character or non-character keys by virtue of the event handlers used to capture keyboard actions: onKeyPress for character keys; onKeyDown or onKeyUp for non-character keys. Be aware that the isChar property returns incon- sistent values (even for the same key) in the first release of NN6. Related Items: charCode, keyCode properties. relatedTarget Value: Element Object Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The relatedTarget property allows an element to uncover where the cursor rolled in from or has rolled out to. This property extends the power of the On the CD-ROM (NN6) eventObject.relatedTarget 772 Part III ✦ Document Objects Reference onMouseOver and onMouseOut event handlers by expanding their scope to outside the current element (usually to an adjacent element). This one property in NN6 does the same duty as the fromElement and toElement properties of the IE4+ event object. When the onMouseOver event fires on an element, the cursor had to be over some other element just beforehand. The relatedTarget property holds a refer- ence to that element. Conversely, when the onMouseOut event fires, the cursor is already over some other element. The relatedTarget property holds a reference to that element. Example (with Listing 29-21) on the CD-ROM Related Items: target property. target Value: Element Object Reference Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The target property is a reference to the HTML element object that is the origi- nal target of the event. Because an event may trickle down and bubble up through the element containment hierarchy and be processed at any level along the way, having a property that points back to the element from which the event originated is comforting. As soon as you have a reference to that element, you can read or write any properties that belong to that element or invoke any of its methods. Example (with Listing 29-22) on the CD-ROM Related Items: relatedTarget property. timeStamp Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ Each event receives a time stamp in milliseconds, based on the same date epoch as the Date object (1 January 1970). Just as with the Date object, accuracy is wholly dependent on the accuracy of the system clock of the client computer. On the CD-ROM On the CD-ROM (NN6) eventObject.timeStamp 773 Chapter 29 ✦ Event Objects While the precise time of an event may be of value in only some situations, the time between events can be useful for applications, such as timed exercises or action games. You can preserve the time of the most recent event in a global vari- able, and compare the time of the current time stamp against the stored value to determine the elapsed time between events. Example (with Listing 29-23) on the CD-ROM Related Items: Date object. type Value: String Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ You can find out what kind of event fired to create the current event object by way of the type property. The value is a string version of the event name — just the name of the event without the “on” prefix that is normally associated with event lis- tener names in NN6. This property can be helpful when you designate one event handler function to process different kinds of events. For example, both the o nMouseDown and onClick event listeners for an object can invoke one function. Inside the function, a branch is written for whether the type comes in as mousedown or click, with different processing for each event type. That is not to endorse such event handler function sharing, but be aware of this power should your script con- structions find the property helpful. This property and its values are fully compatible with the NN4 and IE4+ event models. Related Items: All event handlers (Chapter 15). view Value: Window Object Reference Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The closest that the W3C DOM Level 2 specification comes to acknowledging the browser window is an abstract object called an abstract view (AbstractView class). The object’s only property is a reference to the document that it contains — the root document node that you’ve come to know and love. User events always occur within the confines of one of these views, and this is reflected in the event object’s On the CD-ROM (NN6) eventObject.view 774 Part III ✦ Document Objects Reference view property. NN6 returns a reference to the window object (which can be a frame) in which the event occurs. This reference allows an event object to be passed to scripts in other frames and those scripts can then gain access to the document object of the target element’s window. Related Items: window object. Methods preventDefault() Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ While NN6+ continues to honor the original way of preventing default action for an event handler (that is, having the last statement of the event handler evaluate to return false), the NN6+ event model provides a method that lets the cancellation of default action take place entirely within a function invoked by an event handler. For example, consider a text box that is supposed to allow only numbers be typed in it. The onKeyPress event handler can invoke a function that inspects each typed character. If the character is not a numeric character, then it does not reach the text box for display. The following validation function may be invoked from the onKeyPress event handler of just such a text box: function checkIt(evt) { var charCode = evt.charCode if (charCode < 48 || charCode > 57) { alert(“Please make sure entries are numbers only.”) evt.preventDefault() } } This way, the errant character won’t appear in the text box. Invoking the preventDefault() method in NN6 is the equivalent of assigning true to event.returnValue in IE5+. Related Items: cancelable property. stopPropagation() Returns: Nothing. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ (NN6) eventObject.stopPropagation() 775 Chapter 29 ✦ Event Objects Use the stopPropagation() method to stop events from trickling down or bub- bling up further through the element containment hierarchy. A statement in the event listener function that invokes evt.stopPropagation() is all that is needed. As an alternative, you can cancel bubbling directly in an ele- ment’s event handler attribute, as in the following: onClick=”doButtonClick(this); event.stopPropagation()” If you are writing cross-browser scripts, you also have the option of using the cancelBubble property, which is compatible with IE4+. Related Items: bubbles, cancelBubble properties. ✦✦✦ (NN6) eventObject.stopPropagation() . 768 Part III ✦ Document Objects Reference each of the keyboard (regardless of its character). To inspect. context of the element that received the event. For regular, unpositioned elements in the BODY part of a document, that positioning context is the BODY element. Thus, for those elements, the. 29-19) on the CD-ROM Related Items: target property. On the CD-ROM (NN6) eventObject.clientX 770 Part III ✦ Document Objects Reference currentTarget Value: Element Object Reference Read-Only NN2