282Part IIIDocument Objects ReferenceListing 15-25(continued) } // invoke fireEvent() on object whose ID is passed as parameterfunction doDispatch(objID, evt) { // create empty mouse eventvar newEvt = document.createEvent( MouseEvents ); // initialize as click with button ID 3newEvt.initMouseEvent( click , true, true, window, 0, 0, 0, 0, 0, false, false, false, false, 3, null); // send event to element passed as paramdocument.getElementById(objID).dispatchEvent(newEvt); // don t let button clicks bubbleevt.stopPropagation(); }

fireEvent() Method

This is a paragraph (with a nested SPAN) that receives click events.

Control Panel

Related Item:fireEvent()method. fireEvent( eventType [, eventObjectRef]) Returns:Boolean. Compatibility:WinIE5.5+, MacIE-, NN-, Moz-, Safari- While some objects have methods that emulate physical events (for example, the click() and focus()methods), WinIE5.5+ generalizes the mechanism by letting a script direct anyvalid event to any object. The fireEvent()method is the vehicle. One required parameter is the event type, formatted as a string. IE event types are coded justlike the property names for event handlers (for example, onclick, onmouseover, and so on). A second, optional parameter is a reference to an existing eventobject. This object can be anevent that some user or system action triggers (meaning that the fireEvent()method is in afunction invoked by an event handler). The existing event can also be an object created by theIE5.5+ document.createEventObject()method. In either case, the purpose of providing anelementObject.dispatchEvent()

281Chapter 15Generic HTML Element Objectsinitializing a new mouse event, supported most reliably in Mozilla-based browsers. Thebehavior is identical to that of Listing 15-26, which demonstrates the IE5.5+ equivalent: fireEvent(). Listing 15-25: Using the dispatchEvent() Method

componentFromPoint() Method

Tracking the mouseDown event relative to the textarea object. Viewresults in status bar.

Related Item:eventobject. contains(elementObjectReference) Returns:Boolean. Compatibility:WinIE4+, MacIE4+, NN-, Moz-, Safari- The contains()method reports whether the current object contains another known objectwithin its HTML containment hierarchy. Note that this is not geographical collision detectionof overlapping elements, but rather the determination of whether one element is nestedsomewhere within another. The scope of the contains()method extends as deeply within the current object s hierarchyas is necessary to locate the object. In essence, the contains()method examines all of theelements that are part of an element s allarray. Therefore, you can use this method as ashortcut replacement for a forloop that examines each nested element of a container for theexistence of a specific element. The parameter to the contains()method is a reference to an object. If you have only the ele- ment s ID as a string to go by, you can use the document.getElementById()method to gen- erate a valid reference to the nested element. elementObject.contains()

278Part IIIDocument Objects ReferenceTable 15-8(continued) Returned StringElement Component at Coordinate PointscrollbarPageDownScrollbar page-down regionscrollbarPageLeftScrollbar page-left regionscrollbarPageRightScrollbar page-right regionscrollbarPageUpScrollbar page-up regionscrollbarRightScrollbar right arrowscrollbarUpScrollbar up arrowscrollbarVThumbScrollbar thumb on vertical barhandleBottomResize handle at bottomhandleBottomLeftResize handle at bottom lefthandleBottomRightResize handle at bottom righthandleLeftResize handle at lefthandleRightResize handle at righthandleTopResize handle at tophandleTopLeftResize handle at top lefthandleTopRightResize handle at top rightYou do not have to use this method for most collision or event detection, however. The eventobject s srcElementproperty returns a reference to whatever object receives the event. ExampleListing 15-24 demonstrates how the componentFromPoint()method can be used to determineexactly where a mouse event occurred. As presented, the method is associated with a textareaobject that is specifically sized to display both vertical and horizontal scrollbars. As you clickvarious areas of the textareaand the rest of the page, the status bar displays information aboutthe location of the event with the help of the componentFromPoint()method. The script utilizes a combination of the event.srcElementproperty and thecomponentFromPoint()method to help you distinguish how you can use each one for differ- ent types of event processing. The srcElementproperty is used initially as a filter to decidewhether the status bar will reveal further processing about the textareaelement s eventdetails. The onmousedownevent handler in the bodyelement triggers all event processing. IE eventsbubble up the hierarchy (and no events are cancelled in this page), so all mousedowneventseventually reach the bodyelement. Then, the whereInWorld()function can compare eachmousedownevent from any element against the text area s geography. Listing 15-24: Using the componentFromPoint() Method

Window focus() and blur() Methods

A key ingredient to the success of the makeNewWindow()function in Listing 15-23 is the firstconditional expression. Because newWindis initialized as a nullvalue when the page loads, that is its value the first time through the function. But after you open the subwindow the firsttime, newWindis assigned a value (the subwindow object) that remains intact even if the usercloses the window. Thus, the value doesn t revert to nullby itself. To catch the possibility thatelementObject.blur()

273Chapter 15Generic HTML Element Objectscompatible with other browsers) by initiating the focus and selection actions through asetTimeout()method. See Chapter 43 on the CD-ROM on data validation for an example. A common design requirement is to position the insertion pointer at the end of a text field ortextareaso that a user can begin appending text to existing content immediately. This ispossible in IE4+ with the help of the TextRangeobject. The following script fragment movesthe text insertion pointer to the end of a textareaelement whose ID is myTextarea: var range = document.getElementById( myTextarea ).createTextRange(); range.move( textedit ); range.select(); You should be very careful in combining blur()or focus()methods with onblurand onfocusevent handlers especially if the event handlers display alert boxes. Many combi- nations of these events and methods can cause an infinite loop in which it is impossible todismiss the alert dialog box completely. On the other hand, there is a useful combination forolder browsers that don t offer a disabledproperty for text boxes. The following text fieldevent handler can prevent users from entering text in a text field: onfocus = this.blur() ; Some operating systems and browsers enable you to give focus to elements such as buttons(including radio and checkbox buttons) and hypertext links (encompassing both aand areaelements). Typically, once such an element has focus, you can accomplish the equivalent of amouse click on the element by pressing the spacebar on the keyboard. This is helpful foraccessibility to those who have difficulty using a mouse. An unfortunate side effect of button focus in Win32 environments is that the focus highlight(a dotted rectangle) remains around the button after a user clicks it and until another objectgets focus. You can eliminate this artifact for browsers and objects that implement theonmouseupevent handler by including the following event handler in your buttons: onmouseup = this.blur() ; IE5.5+ recognizes the often undesirable effect of that dotted rectangle and lets scripts set thehideFocusproperty of an element to trueto keep that rectangle hidden while still giving theelement focus. It is a trade-off for the user, however, because there is no visual feedbackabout which element has focus. Other elementsFor other kinds of elements that support the focus()method, you can bring an element intoview in lieu of the scrollIntoView()method. Link (a) and areaelements in Windows ver- sions of IE display the dotted rectangle around them after a user brings focus to them. Toeliminate that artifact, use the sameonmouseup = this.blur() ; event handler (or IE5.5+ hideFocusproperty) as just described for form controls. ExampleListing 15-23 contains an example of using the focus()and blur()methods to tinker withchanging the focus of windows. This example creates a two-window environment; from eachwindow, you can bring the other window to the front. The main window uses the objectreturned by window.open()to assemble the reference to the new window. In the subwindow(whose content is created entirely on the fly by JavaScript), self.openeris summoned torefer to the original window, while self.blur()operates on the subwindow itself. Blurringone window and focusing on another window yields the same result of sending the window tothe back of the pile. elementObject.blur()