[Dynapi-Dev] Long Post: Events in DOM (just to help out developers)

[Raides J. <ra...@te...>]

	What I will say should be applicable to Mozilla, NS6 and IE5.5 (the DOM
compliant browsers):

	Object Event (properties):
	type -> string, the type of the event ("mouseover", etc.).
	target -> Object EventTarget, the object that originally got the event.
	currentTarget -> Object EventTarget, the object that actually is processing the
event (through bubbling or capturing).
	bubbles -> boolean, if true means that this event can bubble to the top of the
DOM tree.
	cancelable -> boolean, if true means that this event can be cancelled at any
moment and bubbling and capturing will stop inmediatly.
	timeStamp -> datetime, the time when the event took place.
	stopPropagation() -> inmediatly cancels the event, but doesn't disallow that
any other event listener in the same node of the DOM tree to catch the same
event.
	preventDefault() -> avoids the implementation's default action if it's a
cancelable event. This, on instance, means that in NS6 it's possible to cancel
the menu display on the right mouse click event.
	initEvent(type,canbubble,cancelable) -> creates an event with the type given,
that can or cann't bubble, and which is or not cancelable.

	NS6 gives this properties for a Mouse/Key Event:
	charCode -> char, code of the key
	keyCode -> integer, exploration code of the key
	altKey -> boolean, true if the Alt key is pressed
	ctrlKey -> boolean, true if the Control key is pressed
	shiftKey -> boolean, true if the Shift key is pressed
	metaKey -> boolean, true if the Meta key is pressed (Mac)
	screenX -> integer, the X coordinate of the mouse relative to screen
	screenY -> integer, the Y coordinate of the mouse relative to screen
	clientX -> integer, the X coordinate of the mouse relative to the current
client window
	clientY -> integer, the Y coordinate of the mouse relative to the current
client window
	button -> integer, the buttons pressed on the mouse
	relatedTarget -> Object EventTarget, secondary target of the event. In
mouseover indicates the target exited by the pointer (the last target with the
mouse over) and in mouseout indicates the target that the pointer entered (the
target that will catch the mouse over next).
	view -> Object Window, the current window object
	detail -> integer, *see below
	layerX -> integer, the X coordinate of the mouse relative to the actual layer
	layerY -> integer, the Y coordinate of the mouse relative to the actual layer
	pageX -> integer, the X coordinate of the mouse relative to the actual page
	pageY -> integer, the Y coordinate of the mouse relative to the actual page
	which -> integer, the kind of event (?)
	rangeParent -> Object Text, the text that is selected (if any)
	rangeOffset -> integer, the offset on the text parent object where the
selection starts
	cancelBubble -> boolean, if set to true cancellates the event bubbling
	isChar -> boolean, if true the key pressed is an ASCII key
	type -> string, the name of the event
	target, currentTarget -> same as for Event Object above
	originalTarget -> Object EventTarget, the first target that got this event
	eventPhase -> integer, any of CAPTURING_PHASE(1),AT_TARGET(2) and
BUBBLING_PHASE(3)
	bubbles, cancelable and timeStamp -> same as for Event Object above

	(*) About detail, quoting the DOM2-Events documentation:
"The MouseEvent interface provides specific contextual information associated
with Mouse events.
The detail attribute inherited from UIEvent [p.19] indicates the number of times
a mouse button
has been pressed and released over the same screen location during a user
action. The attribute value
is 1 when the user begins this action and increments by 1 for each full sequence
of pressing and
releasing. If the user moves the mouse between the mousedown and mouseup the
value will be set to
0, indicating that no click is occurring."
... which is a good way of knowing if a click is a double- or triple-click and
if a drag is on the way (a change from 1 to 0 will mean drag started-finished).

	And this is another quote from the DOM2-Events documentation at w3.org:
"It is expected that actions taken by EventListener [p.14] s may cause
additional events to fire.
Additional events should be handled in a synchronous manner and may cause
reentrancy into the event
model."
... which correlates with the mail from Doug Melvin titled "[Dynapi-Dev] To all;
Re drag events. (and other events)" and his use of a check variable to allow
event reentrancy.

	I hope this long post to be of help to the development of this API. I have both
the official documentation from the W3 and Netscape 6.0 to experiment, but no
time at the moment to study things further. I reccomend http://www.brainjar.com
(to which I'm in no way affiliated) as a source of knowledge on NS6 and IE5.5
DOM-compliant browsers and how to manipulate events and screen coordinates on
them.

	Raides J.

-- Paying attention to details since 1966 ;)