JavaScript Bible, Gold Edition part 36 doc

198 Part III ✦ Document Objects Reference property). It is not uncommon to wish to block the context menu from appearing so that users are somewhat inhibited from downloading copies of images or viewing the source code of a frame. Be aware, however, that if a user turns Active Scripting off in IE5+, the event handler cannot prevent the context menu from appearing. Another possibility for this event is to trigger the display of a custom context menu constructed with other DHTML facilities. In this case, you must also disable the intrinsic context menu so that both menus do not display at the same time. Example on the CD-ROM Related Items: releaseCapture(), setCapture() methods. onControlSelect NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The onControlSelect event should fire just before a user makes a selection on what Microsoft calls a control selection. Microsoft is less than clear in explaining what a control selection is, but it appears to have something to do with a user edit mode. I have not been able to have this event fire naturally in IE5.5. If I receive fur- ther details, they will appear at the JavaScript Bible Support Center ( http://www.dannyg.com). Related Items: onResizeEnd, onResizeStart event handlers. onCopy onCut NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The onCopy and onCut events (not implemented in IE5/Mac) fire immediately after the user or script initiates a copy or cut edit action on the current object. Each event is preceded by its associated “before” event, which fires before any Edit or context menu appears (or before the copy or cut action, if initiated by keyboard shortcut). Use these event handlers to provide edit functionality to elements that don’t nor- mally allow copying or cutting. In such circumstances, you need to enable the Copy or Cut menu items in the context or Edit menu by setting the event.returnValue for the onBeforeCopy or onBeforeCut event handlers to false. Then your onCopy or onCut event handlers must manually stuff a value into the clipboard by way of the setData() method of the clipboardData object. If you use the setData() On the CD-ROM elementObject.onCopy 199 Chapter 15 ✦ Generic HTML Element Objects method in your onCopy or onCut event handler, you must also set the event. returnValue property to false in the handler function to avoid the default copy or cut action from wiping out your clipboard contents. Because you are in charge of what data is stored in the clipboard, you are not limited to a direct copy of the data. For example, you might wish to store the value of the src property of an image object so that the user can paste it elsewhere on the page. In the case of the onCut event handler, your script is also responsible for cutting the element or selected content from the page. To eliminate all of the content of an element, you can set the element’s innerHTML or innerText property to an empty string. For a selection, use the selection.createRange() method to generate a TextRange object whose contents you can manipulate through the TextRange object’s methods. Example (with Listing 15-36) on the CD-ROM Related Items: onBeforeCopy, onBeforeCut, onBeforePaste, and onPaste event handlers. onDblClick NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓✓✓ The onDblClick event fires after the second click of a double-click sequence. The timing between clicks depends on the client’s mouse control panel settings. The onClick event also fires, but only after the first of the two clicks. NN4 implements the onDblClick event handler only for link objects (but not at all on the Macintosh version of NN4). IE4 introduced the event to virtually every HTML element. In general, it is rarely a good design to have an element perform one task when the mouse is single-clicked and a different task if double-clicked. With the event sequence employed in modern browsers, this isn’t practical anyway (the onClick event always fires, even when the user double-clicks). But it is not uncommon to have the mouse down action perform some helper action. You see this in most icon- based file systems: if you click a file icon, it is highlighted at mouse down to select the item; you can double-click the item to launch it. In either case, one event’s action does not impede the other nor confuse the user. Example on the CD-ROM Related Items: onClick, onMouseDown, onMouseUp event handlers. On the CD-ROM On the CD-ROM elementObject.onDblClick 200 Part III ✦ Document Objects Reference onDrag NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The onDrag event fires after the onDragStart event and continues firing repeatedly while the user drags a selection or object on the screen. Unlike the onMouseMove event, which fires only as the cursor moves on the screen, the onDrag event continues to fire even when the cursor is stationary. In the IE5+ environment, users can drag objects to other browser windows or other applica- tions. The event fires while the dragging extends beyond the browser window. Because the event fires regardless of what is underneath the dragged object, you can use it in a game or training environment in which the user has only a fixed amount of time to complete a dragging operation (for example, matching similar pairs of objects). If future versions of the browser accommodate downloadable cursors, the onDrag event could cycle the cursor through a series of cursor versions to resemble an animated cursor. Understanding the sequence of drag-related events during a user drag operation can be helpful if your scripts need to micromanage the actions (usually not neces- sary for basic drag-and-drop operations). Consider the drag-and-drop operation shown in Figure 15-2. Figure 15-2: A typical drag-and-drop operation blank1 TableA1 B1 B2 B3 elementObject.onDrag 201 Chapter 15 ✦ Generic HTML Element Objects It helps to imagine that the cells of the table with draggable content are named like spreadsheet cells: “truck” is cell A1; “round” is B1; “doll” is A2; and so on. During the drag operation, many objects are the targets of a variety of drag-related events. Table 15-10 lists the event sequence and the event targets. Table 15-10 Events and Their Targets During a Typical Drag-and-Drop Operation Event Target Discussion onDragStart cell A1 The very first event that fires during a drag-and-drop operation. onDrag cell A1 Fires continually on this target throughout the entire operation. Other events get interspersed, however. onDragEnter cell A1 Even though the cursor hasn’t moved from cell A1 yet, the onDragEnter event fires upon first movement within the source element. onDragOver cell A1 Fires continually on whatever element the cursor rests on at that instant. If the user simply holds the mouse button down and does not move the cursor during a drag, the onDrag and onDragOver events fire continually, alternating between the two. (repetition) cell A1 onDrag and onDragOver events fire alternately while the cursor remains atop cell A1. onDragEnter TABLE The TABLE element, represented by the border and/or cell padding, receives the onDragEnter event when the cursor touches its space. onDragLeave cell A1 Notice that the onDragLeave event fires after the onDragEnter event fires on another element. onDrag cell A1 Still firing away. onDragOver TABLE The source element for this event shifts to the TABLE because that’s what the cursor is “over” at this instant. If the cursor doesn’t move from this spot, the onDrag (cell A1) and onDragOver (TABLE) events continue to fire in turn. onDragEnter cell B1 The drag is progressing from the TABLE border space to cell B1. onDragLeave TABLE onDrag cell A1 The onDrag event continues to fire on the cell A1 object. onDragOver cell B1 The cursor is atop cell B1 now, so the onDragOver event fires for that object. Fires multiple times (depending on the speed of the computer and the user’s drag action), alternating with the previous onDrag event. Continued elementObject.onDrag 202 Part III ✦ Document Objects Reference Table 15-10 (continued) Event Target Discussion [More of the same as the cursor progresses from cell B1 through the TABLE border again to cell B2, the TABLE again, cell B3, and the outermost edge of the TABLE.] onDragEnter BODY Dragging is free of the TABLE and is floating free on the bare BODY element. onDragLeave TABLE Yes, you just left the TABLE. onDrag cell A1 Still alive and receiving this event. onDragOver BODY That’s where the cursor is now. Fires multiple times (depending on the speed of the computer and the user’s drag action), alternating with the previous onDrag event. onDragEnter blank1 The cursor reaches the SPAN element whose ID is blank1, where the empty underline is. onDragLeave BODY Just left the BODY for the blank. onDrag cell A1 Still kicking. onDragOver blank1 That’s where the cursor is now. Fires multiple times (depending on the speed of the computer and the user’s drag action), alternating with the previous onDrag event. onDrop blank1 The SPAN element gets the notification of a recent drop. onDragEnd cell A1 The original source element gets the final word that dragging is complete. This event fires even if the drag does not succeed because the drag does not end on a drop target. In practice, some of the events shown in Table 15-10 may not fire. Much has to do with how many event handlers you trap that need to execute scripts along the way. The other major factor is the physical speed at which the user performs the drag-and-drop operation (which interacts with the CPU processing speed). The kinds of events that are most likely to be skipped are the onDragEnter and onDragLeave events, and perhaps some onDragOver events if the user flies over an object before its onDragOver event has a chance to fire. Despite this uncertainty about drag-related event reliability, you can count on several important ones to fire all the time. The onDragStart, onDrop (if over a drop target), and onDragEnd events — as well some interstitial onDrag events — will definitely fire in the course of dragging on the screen. All but onDrop direct their events to the source element, while onDrop fires on the target. Example (with Listing 15-37) on the CD-ROM On the CD-ROM elementObject.onDrag 203 Chapter 15 ✦ Generic HTML Element Objects Related Items: event.dataTransfer object; onDragEnd, onDragEnter, onDragLeave, onDragOver, onDragStart, onDrop event handlers. onDragEnter onDragLeave NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ These events (not implemented in IE5/Mac) fire during a drag operation. When the cursor enters the rectangular space of an element on the page, the onDragEnter event fires on that element. Immediately thereafter, the onDragLeave event fires on the element from which the cursor came. While this may seem to occur out of sequence from the physical action, the events always fire in this order. Depending on the speed of the client computer’s CPU and the speed of the user’s dragging action, one or the other of these events may not fire —especially if the physical action out- strips the computer’s capability to fire the events in time. See the discussion of the onDrag event handler earlier in this chapter for more details on the sequence of drag-related events. Example (with Listing 15-38) on the CD-ROM Related Items: onDrag, onDragEnd, onDragOver, onDragStart, onDrop event handlers. onDragOver NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The onDragOver event (not implemented in IE5/Mac) fires continually while a dragged cursor is atop an element. In the course of dragging from one point on the page to another, the onDragOver event target changes with the element beneath the cursor. If no other drag-related events are firing (the mouse button is still down in the drag operation, but the cursor is not moving), the onDrag and onDragOver events fire continually, alternating between the two. You should have the onDragOver event handler of a drop target element set the event.returnValue property to false. See the discussion of the onDrag event handler earlier in this chapter for more details on the sequence of drag-related events. On the CD-ROM elementObject.onDragOver 204 Part III ✦ Document Objects Reference Example on the CD-ROM Related Items: event.dataTransfer object; onDrag, onDragEnd, onDragEnter, onDragLeave, onDragStart, onDrop event handlers. onDragStart NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ The onDragStart event handler is the first event to fire in the long sequence of events that occur in a typical drag-and-drop operation by the user. This event han- dler is associated with the element that is the source element of the drag operation. Typically, the onDragStart event handler sets the dataTransfer.effectAllowed property in IE5 for Windows, packages the data being passed along with the drag (via the dataTransfer.setData() method), and overrides default behavior by setting the event.returnValue property to false. See the discussion of the onDrag event handler earlier in this chapter for more details on the sequence of drag-related events. Example on the CD-ROM Related Items: event.dataTransfer object; onDrag, onDragEnd, onDragEnter, onDragLeave, onDragOver, onDrop event handlers. onDrop NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ The onDrop event (not implemented in IE5/Mac) fires on the drop target element as soon as the user releases the mouse button at the end of a drag-and-drop opera- tion. Microsoft recommends that you denote a drop target by applying the onDragEnter, onDragOver, and onDrop event handlers to the target element. In each of those event handlers, you should set the dataTransfer.dropEffect to the transfer effect you wish to portray in the drag-and-drop operation (signified by a different cursor for each type). These settings should match the dataTransfer. effectAllowed property that is usually set in the onDragStart event handler. Each of the three drop-related handlers should also override the default event behavior by setting the event.returnValue property to false. See the discussion of the onDrag event handler earlier in this chapter for more details on the sequence of drag-related events. On the CD-ROM On the CD-ROM elementObject.onDrop 205 Chapter 15 ✦ Generic HTML Element Objects Example on the CD-ROM Related Items: event.dataTransfer object; onDrag, onDragEnd, onDragEnter, onDragLeave, onDragOver, onDragStart event handlers. onFilterChange NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ The onFilterChange event (not implemented in IE5/Mac) fires whenever an object’s visual filter switches to a new state or a transition completes (a transition may be extended over time). Only objects that accommodate filters and transitions in IE (primarily block elements and form controls) receive the event. A common usage of the onFilterChange event is to trigger the next transition within a sequence of transition activities. This may include an infinite loop transi- tion, for which the object receiving the event toggles between two transition states. If you don’t want to get into a loop of that kind, place the different sets of content into their own positionable elements and use the onFilterChange event handler in one to trigger the transition in the other. Example (with Listing 15-39) on the CD-ROM Related Item: filter object. onFocus NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ ✓ ✓ ✓ ✓✓ ✓ The onFocus event fires when an element receives focus, usually following some other object losing focus. (The element losing focus receives the onBlur event before the current object receives the onFocus event.) For example, a text input element fires the onFocus event when a user tabs to that element while navigating through a form via the keyboard. Clicking an element also gives that element focus, as does making the browser the frontmost application on the client desktop. The availability of the onFocus event has expanded with succeeding generations of script-capable browsers. In earlier versions, blur and focus were largely confined to text-oriented input elements (including the SELECT element). The window object received the onFocus event handler starting with NN3 and IE4. IE4 also extended On the CD-ROM On the CD-ROM elementObject.onFocus 206 Part III ✦ Document Objects Reference the event handler to more form elements, predominantly on the Windows operating system because that OS has a user interface clue (the dotted rectangle) when items such as buttons and links receive focus (so that users may act upon them by press- ing the keyboard’s spacebar). For IE5, the onFocus event handler is available to vir- tually every HTML element. For most of those elements, however, you cannot use blur and focus unless you assign a value to the TABINDEX attribute of the element’s tag. For example, if you assign TABINDEX=1 inside a <P> tag, the user can bring focus to that paragraph (highlighted with the dotted rectangle in Windows) by clicking the paragraph or pressing the Tab key until that item receives focus in sequence. If you plan to use the onFocus event handler on window or text-oriented input elements, be aware that there might be some unexpected and undesirable conse- quences of scripting for the event. For example, in IE5 (but not IE4), some object almost always has focus. In most cases, the window has focus but loses it when the user clicks an element wired to receive focus. Clicking anywhere on an unwired element brings focus back to the window object. Similarly, the interaction between onBlur, onFocus, and the alert dialog box can be problematic with text input elements. IE5.5 adds the onActivate event handler, which fires immediately before the onFocus event handler. You can use one or the other, but there is little need to include both event handlers for the same object unless you temporarily wish to block an item from receiving focus. To prevent an object from receiving focus in IE5.5, include an event.returnValue=false statement in the onActivate event handler for the same object. In older browsers, you can usually get away with assigning onFocus=”this.blur()” as an event handler for elements such as form controls. However, this is not a foolproof way to prevent a user from changing a control’s setting. Unfortunately, there are few reliable alternatives. Example on the CD-ROM Related Items: onActivate, onBlur, onDeactivate event handlers. onHelp NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ The onHelp event handler fires in Windows whenever an element of the docu- ment has focus and the user presses the F1 function key on a Windows PC. As of IE5/Mac, the event fires only on the window (in other words, event handler speci- fied in the <BODY> tag) and does so via the dedicated Help key on a Mac keyboard. Browser Help menu choices do not activate this event. To prevent the browser’s Help window from appearing, the event handler must evaluate to return false (for IE4+) or set the event.returnValue property to false (IE5+). Because the On the CD-ROM elementObject.onHelp 207 Chapter 15 ✦ Generic HTML Element Objects event handler can be associated with individual elements of a document in the Windows version, you can create a context-sensitive help system. However, if the focus is in the Address field of the browser window, you cannot intercept the event. Instead, the browser’s Help window appears. Example (with Listing 15-40) on the CD-ROM Related Items: window.showHelp(), window.showModalDialog() methods. onKeyDown onKeyPress onKeyUp NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓✓✓ When someone presses and releases a keyboard key, a sequence of three events fires in quick succession. The onKeyDown event fires when the key makes its first contact. This is followed immediately by the onKeyPress event. When contact is broken by the key release, the onKeyUp event fires. If you hold a character key down until it begins auto-repeating, the onKeyDown and onKeyPress events fire with each repetition of the character. The sequence of events can be crucial in some keyboard event handling. Consider the scenario that wants the focus of a series of text fields to advance automatically after the user enters a fixed number of characters (for example, date, month, and two-digit year). By the time the onKeyUp event fires, the character associated with the key press action is already added to the field and you can accurately determine the length of text in the field, as shown in this simple example: <HTML> <HEAD> <SCRIPT Language=”JavaScript”> function jumpNext(fromFld, toFld) { if (fromFld.value.length == 2) { document.forms[0].elements[toFld].focus() document.forms[0].elements[toFld].select() } } </SCRIPT> </HEAD> <BODY> <FORM> Month: <INPUT Name=”month” Type=”text” Size=”3” VALUE=”” onKeyUp=”jumpNext(this, day)” maxLength=”2”> On the CD-ROM elementObject.onKeyDown . simple example: <HTML> <HEAD> <SCRIPT Language= JavaScript > function jumpNext(fromFld, toFld) { if (fromFld.value.length == 2) { document.forms[0].elements[toFld].focus() document.forms[0].elements[toFld].select() } } </SCRIPT> </HEAD> <BODY> <FORM> Month:. onMouseDown, onMouseUp event handlers. On the CD-ROM On the CD-ROM elementObject.onDblClick 200 Part III ✦ Document Objects Reference onDrag NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility. drag action), alternating with the previous onDrag event. Continued elementObject.onDrag 202 Part III ✦ Document Objects Reference Table 15-10 (continued) Event Target Discussion [More of the same