JavaScript Bible, Gold Edition part 92 ppsx

758 Part III ✦ Document Objects Reference return a null value for the keyCode property during onKeyPress events. In other words, the keyCode property for onKeyPress events is more like a character code than a key code. To capture the exact keyboard key that the user presses, use either the onKeyDown or onKeyUp event handler. For these events, the event object captures a numeric code associated with a particular key on the keyboard. For the character keys, this varies with the language assigned as the system language. Importantly, 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 fired 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 key- board. 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-16) on the CD-ROM Related Items: onKeyDown, onKeyPress, onKeyUp event handlers. nextPage Value: String Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The nextPage property is applicable only if your IE5.5/Windows page uses a TemplatePrinter behavior. Values of this property are one of the following strings: left, right, or an empty string. For more information about the TemplatePrinter behavior for Windows-only versions of IE5.5+, see http://msdn.microsoft.com/workshop/browser/hosting/printpreview/reference/ behaviors/TemplatePrinter.asp propertyName Value: String Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ On the CD-ROM (IE) event.propertyName 759 Chapter 29 ✦ Event Objects The propertyName property is filled only after an onPropertyChange event fires. This property is not available through Version 5 of IE/Macintosh. If a script modifies a property, the onPropertyChange event handler fires, and the string name of the property is stuffed into the event.propertyName property. If the property happens to be a property of the style object associated with the element, the propertyName is the full property reference, as in style.backgroundColor. Example See Listing 15-46 in the section about the onPropertyChange event handler for an example of the values returned by this property. Related Items: onPropertyChange event handler (Chapter 15). repeat Value: Boolean Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The repeat property reveals for onKeyDown events only whether the key is in repeat mode (as determined by the Keyboard control panel settings in the system). With this information, you can prevent the automatic triggering of repeat mode from causing multiple characters from being recognized by the browser. This prop- erty can come in handy if users may be physically challenged and may occasionally and accidentally hold down a key too long. The following script fragment in an onKeyDown event handler for a text box or TEXTAREA prevents multiple characters from appearing even if the system goes into repeat mode: if (event.repeat) { event.returnValue = false } By disabling the default action while in repeat mode, no further characters reach the text box until repeat mode goes away (meaning, with the press of another key). This property is not available in IE/Mac through Version 5. Related Items: onKeyDown event handler. returnValue Value: Boolean Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ While IE4+ 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 (IE) event.returnValue 760 Part III ✦ Document Objects Reference return false), the IE4+ event model provides a property that lets the cancellation of default action take place entirely within a function invoked by an event handler. By default, the returnValue property of the event object is true, meaning that the element processes the event after the scripted handler completes its job, just as if the script weren’t there. Normal processing, for example, is displaying a typed character, navigating to a link’s HREF URL upon being clicked, or submitting a form after the Submit button is clicked. But you don’t always want the default action to occur. 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 char- acter is not a numeric character, then it should not reach the text box for display. The following validation function may be invoked from the onKeyPress event han- dler of just such a text box: function checkIt() { var charCode = event.keyCode if (charCode < 48 || charCode > 57) { alert(“Please make sure entries are numerals only.”) event.returnValue = false } } By using this event handler, the errant character won’t appear in the text box. Note that this property is not a substitute for the return statement of a func- tion. If you need a value to be returned to the invoking statement, you can use a return statement in addition to setting the event.returnValue property. Example on the CD-ROM Related Items: return statement (Chapter 41). saveType Value: String Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The saveType property is assigned a value only when an oncontentsave event is bound to an IE/Windows DHTML behavior (.htc). For more information about behaviors, see http://msdn.microsoft.com/workshop/author/behaviors/overview.asp Related Items: addBehavior() method. On the CD-ROM (IE) event.saveType 761 Chapter 29 ✦ Event Objects srcElement Value: Element Object Reference Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ The srcElement property is a reference to the HTML element object that is the original target of the event. Because an event may bubble up through the element containment hierarchy and be processed at any level along the way, having a prop- erty that points back to the element from which the event originated is comforting. After 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-17) on the CD-ROM Related Items: fromElement, toElement properties. srcFilter Value: String Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓ According to Microsoft, the srcFilter property should return a string of the name of the filter that was applied to trigger an onFilterChange event handler. While the property exists in the event object, its value is always null, at least through IE5.5. This property, because it is filter related, is a Windows-only property. Related Items: onFilterChange event handler; style.filter object. srcUrn Value: String Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ On the CD-ROM (IE) event.srcUrn 762 Part III ✦ Document Objects Reference If an event is fired in an IE/Windows behavior attached to an element, and the behavior has a URN identifier defined for it, the srcUrn property returns the string from the URN identifier. For more information about behaviors, see http://msdn.microsoft.com/workshop/author/behaviors/overview.asp Related Items: addBehavior() method. toElement See fromElement. 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 names in IE. This property can be helpful when you designate one event handler function to process different kinds of events. For example, both the onMouseDown and onClick event handlers for an object can invoke one function. Inside the func- tion, 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 for you to be aware of this power should your script constructions find the property helpful. This property and its values are fully compatible with the NN4 and NN6 event models. Example on the CD-ROM Related Items: All event handlers (Chapter 15). NN6+ event Object Properties Methods Event Handlers altKey preventDefault() bubbles stopPropagation() button On the CD-ROM (NN6) eventObject 763 Chapter 29 ✦ Event Objects Properties Methods Event Handlers cancelBubble cancelable charCode clientX clientY ctrlKey currentTarget detail eventPhase isChar keyCode layerX layerY metaKey pageX pageY relatedTarget screenX screenY shiftKey target timeStamp type view Syntax Accessing NN6+ event object properties and methods: eventObject.property | method([parameters]) NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ (NN6) eventObject 764 Part III ✦ Document Objects Reference About this object Although it is based largely on the event object as defined by the W3C DOM Level 2, the NN6+ event object also carries forward several characteristics from the NN4 event object. A few properties are continued primarily for backward compati- bility. But because development for NN6 will likely forego the peculiarities of the NN4 DOM and event models, you should ignore these items (as highlighted below). Wherever possible, look forward and embrace the W3C DOM aspects of the event model. While the NN6 event model provides a bubbling event propagation model just as IE4+, the incompatibility of referencing event objects between the event models is still there. In NN6 (as in NN4), an event object is explicitly passed as a parameter to event handler (or, rather, event listener) functions. But after you have a browser- specific event object assigned to a variable inside a function, a few important prop- erties have the same names between the IE4+ and NN6+ event models. If Microsoft adopts more of the W3C DOM event model in future versions of IE, the compatibil- ity situation should improve. The event object discussed in this section is the instance of an event that is cre- ated as the result of a user or system event action. The NN6 DOM includes an addi- tional static Event object. Many of the properties of the static Event object are inherited by the event instances, so the detailed coverage of those shared proper- ties is in this section because it is the event object you’ll be scripting for the most part. In many code fragments in the following detail sections, you will see references that begin with the evt reference. This assumes that the statement(s) resides inside a function that has assigned the incoming event object to the evt parameter variable: function myFunction(evt) { } As shown earlier in this chapter, you can equalize NN6 and IE4+ event object ref- erences when it is practical to do so because the scripts work on identical (or simi- lar) event object properties. Properties altKey ctrlKey metaKey shiftKey Value: Boolean Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ (NN6) eventObject.altKey 765 Chapter 29 ✦ Event Objects When an event object is created in response to a user or system action, these four 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. The metaKey property corresponds to the Command key on the Macintosh keyboard but does not register for the Windows key on Wintel computers. 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 (evt.shiftKey && evt.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 four modifier keys: if (evt.shiftKey || evt.ctrlKey || evt.metaKey || evt.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 properties are used to set the checked properties of corresponding checkboxes for a variety of event types. Related Items: None. bubbles Value: Boolean Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ Not every event bubbles. For example, an onsubmit event propagates no further than the form object with which the event is associated. Events that do not bubble have their event object’s bubbles property set to false; all others have the prop- erty set to true. You use this property in the rare circumstances of a single event handler function processing a wide variety of events. You may want to perform spe- cial operations only on events that can bubble and handle the others without spe- cial treatment. For this branch, you can use the property in an if condition statement: if (evt.bubbles) { // special processing for bubble-able events } (NN6) eventObject.bubbles 766 Part III ✦ Document Objects Reference You do not have to branch, however, just to cancel bubbling. A non-propagating event doesn’t mind if you tell it not to propagate. Related Items: cancelBubble property. button Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The button property reveals the button that was pressed to activate the mouse event. The left (primary) button returns a value of 1. If the mouse is a three-button mouse, the middle button returns 2. The right button (on any multi-button mouse) returns a value of 3. Note that these values differ from those stated in the W3C DOM ( 0, 1, and 2, respectively), but these values are backward-compatible with the NN4 which property. Mouse buttons other than the primary one are easier to look for in mousedown or mouseup events, rather than onclick events. In the case of a user pressing multiple buttons, only the most recent button is registered. Exercise caution when scripting the button property for both IE4+ and NN6+. The respective event models define different button values for mouse buttons. Example See Listing 29-11, where the button property is revealed in the statusbar. Try pressing individual mouse buttons on, say, the screen button. Related Items: None. cancelBubble Value: Boolean Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The cancelBubble property is a rare instance of an IE4+ event property being implemented in NN6 even though the property is not defined in the W3C DOM. The property operates the same as in IE4+ in that it 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. 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” (NN6) eventObject.cancelBubble 767 Chapter 29 ✦ Event Objects Cancelling event bubbling works only for the current event. The very next event to fire will have bubbling enabled (provided the event bubbles). If you are trying to migrate your code as much as possible to the W3C DOM, then use the stopPropagation() method instead of cancelBubble. For cross-browser compatibility, however, cancelBubble is a safe bet. Example See Listing 29-6 to see the cancelBubble property in action in an IE environ- ment. 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: stopPropagation() method. cancelable Value: Boolean Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ If an event is cancelable, then its default action can be prevented from occurring with the help of a script. While most events are cancelable, some are not. The can- celable property lets you inquire about a particular event object to see if its event type is cancelable. Values for the property are Booleans. You may want to perform special operations only on events that are cancelable, and handle the others with- out special treatment. For this branch, you can use the property in an if condition statement: if (evt.cancelable) { // special processing for cancelable events } You do not have to branch, however, just to prevent an event’s default action. A non-cancelable event doesn’t mind if you tell it to prevent the default action. Related Items: preventDefault() method. charCode keyCode Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The NN6 event object model clearly distinguishes between the Unicode charac- ter attached to the alphanumeric keys of the keyboard and the code attached to (NN6) eventObject.charCode . 758 Part III ✦ Document Objects Reference return a null value for the keyCode property during onKeyPress. onKeyUp event handler. For these events, the event object captures a numeric code associated with a particular key on the keyboard. For the character keys, this varies with the language assigned as. (that is, having the last statement of the event handler evaluate to (IE) event.returnValue 760 Part III ✦ Document Objects Reference return false), the IE4+ event model provides a property that