JavaScript Bible, Gold Edition part 91 potx

button NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 The buttonproperty reveals which button or buttons were pressed to activate a mouse event.. To prevent event bubbling for the current e

Most commonly, you use expressions consisting of this property as if construc-tion condiconstruc-tion 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 (event.shiftKey && event.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 three modifier keys:

if (event.shiftKey || event.ctrlKey || event.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 three properties are used to set the

checkedproperties of corresponding checkboxes for a variety of event types

Related Items:altLeft, ctrlLeft, shiftLeftproperties

altLeft

ctrlLeft

shiftLeft

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5

Some versions of Windows (notably Windows NT and Windows 2000) allow events to be modified by only the left-hand Alt, Ctrl, and Shift keys when using IE5.5+ For these modifiers to be recorded by the eventobject, focus must be on the document (body), and not in any form control If the left-key version is false

and the regular version is true, then your script knows that the right-hand key had been held down during the event

Related Items:altKey, ctrlKey, shiftKeyproperties

(IE) event.altLeft

behaviorPart

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5

These two properties are related to a Windows technology that Microsoft calls

rendering behaviors Unlike the behaviors discussed under the addBehavior()

method in Chapter 15, rendering behaviors are written in C++ and provide services

for custom drawing on your Web page For more details, consult the document

“Implementing Rendering Behaviors” at http://msdn.microsoft.com/

workshop/browser/editing/imprendbehav.asp

bookmarks

boundElements

dataFld

qualifier

reason

recordset

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5

This group of eventobject properties is tied to using Data Binding in Windows

versions of IE4+ Extensive details of Data Binding lie outside the scope of this book,

but Table 29-5 provides a summary of these eventobject properties within that

context (much of the terminology is used in Data Binding, but doesn’t affect other

scripting) For more details, search for ActiveX Data Objects (ADO) at

http://msdn.microsoft.com/workshop/

Table 29-5 ADO-Related event Object Properties

positions) for records within a recordset associated with the object that received the event.

Continued

(IE) event.bookmarks

Table 29-5 (continued)

boundElements Array IE5 Array of element references for all

elements bound to the same data set that was touched by the current event.

that is bound to a table cell that receives a cellchange event.

associated with a data source that receives a data-related event Available only if the data source object (DSO) allows multiple-named data members or a qualifier has been explicitly set via the DATASRC attribute of the bound element Read-write in IE5+.

onDataSetComplete event, provides the result code of the data set loading (0=successful; 1=transfer aborted; 2=other error).

recordset Object IE4 Reference to the current

recordset in a data source object.

button

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5

The buttonproperty reveals which button or buttons were pressed to activate a mouse event If no mouse button is pressed to generate an event, this property is zero But integers 1 through 7 reveal single and multiple button presses, including

(IE) event.button

three-button mice when they are recognized by the operating system Integer

val-ues correspond to buttons according to the following scheme:

3 Left and right buttons together

5 Left and middle buttons together

6 Right and middle buttons together

7 Left, middle, and right buttons together

Mouse buttons other than the primary one are easier to look for in mousedownor

mouseupevents, rather than onclickevents Be aware that as the user works

toward pressing multiple buttons, each press fires a mousedownevent Therefore, if

the user presses the left button first, the mousedownevent fires, with the

event.buttonproperty bearing the 1value; as soon as the right button is pressed,

the mousedownevent fires again, but this time with an event.buttonvalue of 3 If

your script intends to perform special action with both buttons pressed, it should

ignore and not perform any action for a single mouse button, because that

one-but-ton event will very likely fire in the process, disturbing the intended action

Exercise caution when scripting the event.buttonproperty for both IE4+ and

NN6+ The W3C DOM event model defines different button values for mouse

but-tons (0, 1, and 2for left, middle, and right) and no values for multiple buttons

Example

See Listing 29-11, where the event.buttonproperty is revealed in the statusbar

Try pressing individual mouse buttons on, for example, the screen button Then try

combinations, watching the results very closely in the statusbar

Related Items: None.

cancelBubble

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5

The cancelBubbleproperty (which sounds more as if it should be a method

name) determines whether the current eventobject 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

(IE) event.cancelBubble

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”

Cancelling event bubbling works only for the current event The very next event

to fire will have bubbling enabled (provided the event bubbles)

Example

See Listing 29-6 to see the cancelBubbleproperty in action 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:returnValueproperty

clientX

clientY

offsetX

offsetY

screenX

screenY

x

y

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5

An IE eventobject provides coordinates for an event in as many as four coordi-nate spaces: the element itself, the parent element of the event’s target, the view-able area of the browser window, and the entire video screen Unfortunately, misleading values can be returned by some of the properties that correspond to these coordinate spaces, as discussed in this section Note that no properties pro-vide the explicit position of an event relative to the entire page, in case the user has scrolled the window

Starting with the innermost space — that of the element that is the target of the event — the offsetXand offsetYproperties should provide pixel coordinates within the target element This is how, for example, you could determine the click point on an image, regardless of whether the image is embedded in the BODY or floating around in a positioned DIV Windows versions through (at least) IE5.5 pro-duce the correct values in most cases But for some elements that are child ele-ments of the BODY element, the vertical (y) value may be relative to the viewable

(IE) event.clientX

window, rather than just the element itself You can see an example of this when

you work with Listing 29-14 and click the H1 or P elements near the top of the page

This problem does not affect IE for the Mac, but there is another problem on Mac

versions: If the page is scrolled away from its normal original position, the scrolled

values are subtracted from the clientXand clientYvalues This is an

incompati-bility bug, and you must take this error into account if you need click coordinates

inside an element for a potentially scrolled page This error correction must be

done only for the Mac, because Windows works OK

Extending scope to the offset parent element of the event’s target, the xand y

properties in IE5+ for Windows should return the coordinates for the event relative

to the target’s offset parent element (the element that can be found via the

offsetParentproperty) For most non-positioned elements, these values are the

same as the clientXand clientYproperties because, as discussed in a moment,

the offset parent element has a zero offset with its parent, the BODY Observe an

important caution about the xand yproperties: In IE4/Windows and through

IE5/Macintosh, the properties do not take into account any offset parent locations

other than the BODY Even in IE5+ for Windows, this property can give false

read-ings in some circumstances By and large, these two properties should not be used

The next set of coordinates, clientXand clientY, are relative to the visible

doc-ument area of the browser window When the docdoc-ument is scrolled all the way to the

top (or the document doesn’t scroll at all), these coordinates are the same as the

coordinates on the entire page But because the page can scroll “underneath” the

viewable window, the coordinates on the page can change if the page scrolls Also, in

the Windows versions of IE, you can actually register mouse events that are up to

two pixels outside of the BODY element, which seems weird, but true Therefore, in

IE/Windows, if you click the background of the BODY, the event fires on the BODY

element, but the clientX/clientYvalues will be two pixels greater then

offsetX/offsetY(they’re equal in IE/Mac) Despite this slight discrepancy, you

should rely on the clientXand clientYproperties if you are trying to get the

coor-dinates of an event that may be in a positioned element, but have those coorcoor-dinates

relative to the entire viewable window, rather than just the positioning context

Taking the page’s scrolling into account for an event coordinate is often

impor-tant After all, unless you generate a fixed-size window for a user, you don’t know

how the browser window will be oriented If you’re looking for a click within a

spe-cific region of the page, you must take page scrolling into account The scrolling

fac-tor can be retrieved from the document.body.scrollLeftand

document.body.scrollTopproperties When reading the clientXand clientY

properties, be sure to add the corresponding scroll properties to get the position

on the page:

var coordX = event.clientX + document.body.scrollLeft

var coordY = event.clientY + document.body.scrollTop

Do this in your production work without fail

Finally, the screenXand screenYproperties return the pixel coordinates of the

event on the entire video screen These properties may be more useful if IE

pro-vided more window dimension properties In any case, because mouse events fire

only when the cursor is somewhere in the content region of the browser window,

don’t expect to get screen values of anywhere outside this region

(IE) event.clientX

If these descriptions seem confusing to you, you are not alone Throw in a few bugs, and it may seem like quite a mess But think how you may use event coordinates in scripts By and large, you want to know one of two types of mouse event coordinates: within the element itself and within the page Use the

offsetX/offsetYproperties for the former; use clientX/clientY(plus the scroll property values) for the latter

While the coordinate properties are used primarily for mouse events, there is a little quirk that may let you determine if the user has resized the window via the maximize icon in the title bar (on the Mac, this is called the zoom box) or the resize handle at the bottom-right corner of the screen Mouse event coordinates are recorded in the eventobject for a resizeevent In the case of the maximize icon, the clientYcoordinate is a negative value (above the client space) and the

clientXcoordinate is within about 45 pixels of the previous width of the window (document.body.clientWidth) This, of course, happens after the window has resized, so it is not a way to prevent window resizing

Example (with Listing 29-14) on the CD-ROM

Related Items:fromElement, toElementproperties

dataTransfer

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5

The dataTransferproperty is a reference to an IE/Windows-only object called the dataTransferobject Use this object in drag-and-drop operations (that is, with drag-and- drop-related events) to control not only the data that gets transferred from the source to the target but also to control the look of the cursor along the way

Table 29-6 lists the properties and methods of the dataTransferobject

On the

CD-ROM

(IE) event.dataTransfer

Table 29-6 dataTransfer object Properties and Methods

dropEffect String An element that is a potential recipient of a

drop action can use the onDragEnter, onDragOver , or onDrop event handler to set the cursor style to be displayed when the cursor is atop the element Before this can work, the source element’s onDragStart event handler must assign a value to the event.effectAllowed property Possible string values for both properties are copy, link , move, or none These properties correspond to the Windows system cursors for the operations users typically do with files and in other documents You must also cancel the default action (meaning set event.returnValue to false) for all of these drop element event handlers:

onDragEnter , onDragOver, and onDrop.

effectAllowed String Set in response to an onDragStart event

of the source element, this property determines which kind of drag-and-drop action will be taking place Possible string values are copy, link, move, or none This property value must match the dropEffect property value for the target element’s event object Also, cancel the default action (meaning, set event.returnValue to false ) in the onDragStart event handler.

clearData([format]) Nothing Removes data in the clipboard If no format

parameters are supplied, all data are cleared.

Data formats can be one or more of the following strings: Text, URL, File, HTML, Image

getData(format) String Retrieves data of the specified format from

the clipboard The format is one of the following strings: Text, URL, File, HTML, Image The clipboard is not emptied after you get the data, so that it can be retrieved

in several sequential operations.

Continued

(IE) event.dataTransfer

Table 29-6 (continued)

setData(format, data) Boolean Stores string data in the clipboard The

format is one of the following strings: Text, URL , File, HTML, Image For non-text data formats, the data must be a string that specifies the path or URL to the content Returns true if the transfer to the clipboard

is successful.

The dataTransferobject acts as a conduit and controller of data that your scripts need to transfer from one element to another in response to a user’s drag-and-drop action You need to adhere to a well-defined sequence of actions triggered

by a handful of event handlers This means that the object is invoked on different instances of the eventobject as different events fire in the process of dragging and dropping

The sequence begins at the source element, where an onDragStartevent han-dler typically assigns a value to the dropEffectproperty and uses the getData()

method to explicitly capture whatever data it is about the source object that gets transferred to the eventual target For example, if you drag an image, the informa-tion being transferred may simply be the URL of the image — data that is

extractable from the event.srcElement.srcproperty of that event (the src prop-erty of the image, that is)

At the target element(s), three event handlers must be defined: onDragEnter,

onDragOver, and onDrop Most commonly, the first two event handlers do nothing more than mark the element for a particular dropEffect(which must match the

effectAllowedset at the source during the drag’s start) and set

event.returnValueto false so that the cursor displays the desired cursor These actions are also carried out in the onDropevent handler, but that is also the han-dler that does the processing of the destination action at the target element This is when the dataTransferobject’s getData()method is invoked to pick up the data that has been “stored” away by getData()at the start of the drag If you also want

to make sure that the data is not picked up accidentally by another event, invoke the clearData()method to remove that data from memory

Note that the style of dragging being discussed here is not the kind in which you see the source element actually moving on the screen (although you could script it that way) The intention is to treat drag-and-drop operations just as Windows does

in, say, the Windows Explorer window or on the Desktop To the user, the draggable component becomes encapsulated in the cursor That’s why the properties of the

dataTransferobject control the appearance of the cursor at the drop point as a way of conveying to the user the type of action that will occur with the impending drop

(IE) event.dataTransfer

An extensive example of the dataTransferproperty in action can be found in

Listing 15-37 in the section for the onDragevent handler

Related Items:onDragEnd, onDragEnter, onDragLeave, onDragOver,

onDragStart, onDropevent handlers

fromElement

toElement

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5

The fromElementand toElementproperties allow an element to uncover where

the cursor rolled in from or has rolled out to These properties extend the power of

the onMouseOverand onMouseOutevent handlers by expanding their scope to

out-side the current element (usually to an adjacent element)

When the onMouseOverevent fires on an element, the cursor had to be over

some other element just beforehand The fromElementproperty holds a reference

to that element Conversely, when the onMouseOutevent fires, the cursor is already

over some other element The toElementproperty holds a reference to that

element

Example (with Listing 29-15) on the CD-ROM

Related Items:srcElementproperty

keyCode

Value: Integer Read-Only

NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5

For keyboard events, the keyCodeproperty returns an integer corresponding to

the Unicode value of the character (for onKeyPressevents) or the keyboard

char-acter key (for onKeyDownand onKeyUpevents) There is a significant distinction

between these numbering code systems

If you want the Unicode values (the same as ASCII values for the Latin character

set) for the key that a user pressed, get the keyCodeproperty from the onKeyPress

event handler For example, a lowercase “a” returns 97, while an uppercase “A”

returns 65 Non-character keys, such as arrows, page navigation, and function keys,

On the

CD-ROM

(IE) event.keyCode